# @ray-js/robot-custom-log Custom Log Utility Library

## Overview

`@ray-js/robot-custom-log` is a custom utility library designed for robot vacuum business scenarios. It enables developers to easily record and export raw data such as maps and paths reported by devices, facilitating troubleshooting. It also provides a companion online parsing tool platform that significantly improves problem identification efficiency.

## Features

- **Multi-type Log Recording:** Supports independent recording of map data, path data, and custom logs

- **Secure Storage:** Log content is encrypted before being written to the local file system

- **Real-time Monitoring:** Provides log file change callbacks, supporting dynamic log list updates

- **Easy Sharing:** Built-in log file sharing functionality for convenient data export

- **Online Parsing:** Supports uploading log files to Tuya's official platform for visual parsing and dynamic rendering

## Installation

```bash
yarn add @ray-js/robot-custom-log
```

## Quick Start

1. Record Logs

```typescript
import { logMapData, logPathData, logCustomData } from '@ray-js/robot-custom-log';

// Record map data
logMapData(devId, mapData);

// Record path data
logPathData(devId, pathData);

// Record custom log
logCustomData(devId, customLog);
```

2. Monitor and Display Log Files

```typescript
import React, { useState } from 'react';
import {
  registerLogFileChangeCallBack,
  shareLogFile,
  cleanAllLogFiles,
  authorizeFileWrite,
} from '@ray-js/robot-custom-log';
import type { LogFileInfo } from '@ray-js/robot-custom-log';

const LogManagement = ({ devId }) => {
  const [allLogList, setAllLogList] = useState<LogFileInfo[]>([]);

  // Register log file change listener
  React.useEffect(() => {
    registerLogFileChangeCallBack(devId, (fileList) => {
      setAllLogList([...fileList]);
    });
  }, [devId]);

  // Share a single log file
  const handleShareLog = (fileId: string) => {
    shareLogFile(fileId);
  };

  return (
    <div>
      {allLogList.map((item) => (
        <div key={item.id} className="log-item">
          <div className="log-header">
            <span>File Index: {item.fileIndex}</span>
            <span>
              Last Modified: {new Date(item.lastModifiedTime).toLocaleString()}
            </span>
          </div>
          <div className="log-footer">
            <span>Size: {formatFileSize(item.fileSize)}</span>
            <button onClick={() => handleShareLog(item.id)}>
              Share Log
            </button>
          </div>
        </div>
      ))}
    </div>
  );
};
```

3. File Management

```typescript
// Request file write permission (call before first use)
authorizeFileWrite();

// Clean all log files
cleanAllLogFiles();
```

## Log Parsing Platform

Exported log files can be uploaded to Tuya's official parsing platform for visual analysis:

- Platform URL: https://developer.tuya.com/tools/vacuum/

- Supported Features:

  - Log content parsing and display

  - Map data visualization rendering

  - Path data dynamic drawing

  - Multi-type data correlation analysis

## Notes

1. Call `authorizeFileWrite()` to obtain file write permission before first use
2. Log file size and quantity are limited by local storage; regular cleanup is recommended
3. It is recommended to disable this feature by default in production environments; control should be managed by the business side, as the SDK does not handle this

## API Reference

| Method | Description | Parameters |
|--------|-------------|------------|
| `logMapData` | Record map data | `devId: string, data: any` |
| `logPathData` | Record path data | `devId: string, data: any` |
| `logCustomData` | Record custom log | `devId: string, data: any` |
| `registerLogFileChangeCallBack` | Register file change callback | `devId: string, callback: (files: LogFileInfo[]) => void` |
| `shareLogFile` | Share log file | `fileId: string` |
| `cleanAllLogFiles` | Clean all log files | - |
| `authorizeFileWrite` | Request file write permission | - |

## Type Definitions

```typescript
interface LogFileInfo {
  id: string;
  fileIndex: number;
  lastModifiedTime: number;
  fileSize: number;
}
```

---

With this utility library, developers can quickly integrate data recording and debugging capabilities for robot vacuum businesses, effectively improving troubleshooting efficiency. For questions or suggestions, please refer to the official documentation or contact technical support.