react-native-kookit 0.2.3 → 0.2.6

package/ANDROID_FTP_UPDATE.md

@@ -0,0 +1,161 @@
+# Android FTP Client Implementation Update
+
+This document summarizes the updates made to the Android implementation to support the new object-oriented FTP client API.
+
+## Overview
+
+The Android implementation has been updated to support multiple FTP client instances, matching the iOS implementation and providing a consistent cross-platform API.
+
+## Key Changes
+
+### 1. ReactNativeKookitModule.kt Updates
+
+#### New Client Management
+
+- Added `ftpClients` HashMap to manage multiple FTP client instances
+- Each client is identified by a unique `clientId` string
+- Clients can be created, used, and disposed independently
+
+#### New Native Methods
+
+**Client Lifecycle:**
+
+- `createFtpClient(clientId: String)` - Create a new FTP client instance
+- `disposeFtpClient(clientId: String)` - Dispose client and clean up resources
+- `getFtpClientStatus(clientId: String)` - Get client status (exists, connected)
+- `listFtpClients()` - List all active clients with their status
+
+**Connection Management:**
+
+- `ftpClientConnect(clientId: String, config: Map<String, Any>)` - Connect specific client
+- `ftpClientDisconnect(clientId: String)` - Disconnect specific client
+
+**File Operations (all require clientId):**
+
+- `ftpClientList(clientId: String, path: String?)` - List files/directories
+- `ftpClientDownload(clientId: String, remotePath: String, localPath: String)` - Download file
+- `ftpClientUpload(clientId: String, localPath: String, remotePath: String)` - Upload file
+- `ftpClientDelete(clientId: String, remotePath: String, isDirectory: Boolean?)` - Delete file/directory
+- `ftpClientCreateDirectory(clientId: String, remotePath: String)` - Create directory
+- `ftpClientChangeDirectory(clientId: String, remotePath: String)` - Change directory
+- `ftpClientGetCurrentDirectory(clientId: String)` - Get current directory
+
+#### Event System Updates
+
+All FTP events now include `clientId` to identify which client triggered the event:
+
+- `onFtpProgress` - Includes `clientId`, `transferred`, `total`, `percentage`
+- `onFtpComplete` - Includes `clientId`
+- `onFtpError` - Includes `clientId`, `error`
+
+### 2. FtpClient.kt Updates
+
+#### New Methods
+
+- `isConnected(): Boolean` - Public method to check connection status
+- Enhanced connection state management
+
+#### Existing Features Maintained
+
+- UTF-8 encoding support for Chinese characters
+- Passive mode FTP connections
+- Progress callbacks for upload/download operations
+- Comprehensive error handling
+- Multi-line FTP response parsing
+
+## Architecture Benefits
+
+### Resource Management
+
+- Each client manages its own connection independently
+- Proper cleanup when clients are disposed
+- No interference between multiple concurrent connections
+
+### Scalability
+
+- Support for multiple FTP servers simultaneously
+- Each client can connect to different servers
+- Independent authentication and configuration per client
+
+### Error Isolation
+
+- Errors in one client don't affect others
+- Per-client event handling
+- Individual client status tracking
+
+## Usage Pattern
+
+### Android Native Layer
+
+```kotlin
+// Create client
+createFtpClient("client1")
+
+// Connect
+ftpClientConnect("client1", config)
+
+// Use client
+ftpClientList("client1", "/")
+ftpClientDownload("client1", "/remote/file.txt", "/local/file.txt")
+
+// Clean up
+disposeFtpClient("client1")
+```
+
+### Event Handling
+
+```kotlin
+// Events now include clientId for identification
+sendEvent("onFtpProgress", mapOf(
+  "clientId" to clientId,
+  "transferred" to transferred,
+  "total" to total,
+  "percentage" to percentage
+))
+```
+
+## Backward Compatibility
+
+The old global FTP methods (`ftpConnect`, `ftpDisconnect`, etc.) are maintained for backward compatibility, but the new client-based API is recommended for new development.
+
+## Error Handling
+
+All new methods include comprehensive error handling:
+
+- Client not found errors when invalid `clientId` is provided
+- Connection state validation before operations
+- Proper exception propagation to JavaScript layer
+- Resource cleanup on errors
+
+## Testing
+
+The implementation has been tested with:
+
+- ✅ TypeScript compilation (0 errors)
+- ✅ Multiple concurrent clients
+- ✅ Client lifecycle management
+- ✅ Event system with client identification
+- ✅ Error handling and resource cleanup
+
+## Migration from Old API
+
+### Old Android Pattern:
+
+```kotlin
+ftpConnect(config)
+ftpList(path)
+ftpDownload(remotePath, localPath)
+ftpDisconnect()
+```
+
+### New Android Pattern:
+
+```kotlin
+createFtpClient(clientId)
+ftpClientConnect(clientId, config)
+ftpClientList(clientId, path)
+ftpClientDownload(clientId, remotePath, localPath)
+disposeFtpClient(clientId)
+```
+
+The new API provides better resource management, supports multiple concurrent connections, and maintains consistency with the iOS implementation.

package/API_UNIFICATION.md

@@ -0,0 +1,180 @@
+# iOS与Android API接口统一更新
+
+本文档记录了为统一iOS和Android FTP客户端API接口命名所做的更改。
+
+## 问题描述
+
+之前iOS和Android的FTP API方法命名不一致：
+
+### 修改前的命名差异
+
+| 功能           | iOS方法名                   | Android方法名                  |
+| -------------- | --------------------------- | ------------------------------ |
+| 连接           | `ftpConnect`                | `ftpClientConnect`             |
+| 断开连接       | `ftpDisconnect`             | `ftpClientDisconnect`          |
+| 文件列表       | `ftpList`                   | `ftpClientList`                |
+| 下载文件       | `ftpDownload`               | `ftpClientDownload`            |
+| 上传文件       | `ftpUpload`                 | `ftpClientUpload`              |
+| 删除文件       | `ftpDelete`                 | `ftpClientDelete`              |
+| 创建目录       | `ftpCreateDirectory`        | `ftpClientCreateDirectory`     |
+| 切换目录       | `ftpChangeDirectory`        | `ftpClientChangeDirectory`     |
+| 获取当前目录   | `ftpGetCurrentDirectory`    | `ftpClientGetCurrentDirectory` |
+| 获取客户端状态 | `getFtpClientStatus` (同步) | `getFtpClientStatus` (异步)    |
+| 列出所有客户端 | `listFtpClients` (同步)     | `listFtpClients` (异步)        |
+
+## 解决方案
+
+统一使用`ftpClient*`命名模式，并确保所有方法都是异步的。
+
+### 修改后的统一命名
+
+| 功能           | 统一方法名                     | 参数                                                            |
+| -------------- | ------------------------------ | --------------------------------------------------------------- |
+| 创建客户端     | `createFtpClient`              | `(clientId: String)`                                            |
+| 释放客户端     | `disposeFtpClient`             | `(clientId: String)`                                            |
+| 连接           | `ftpClientConnect`             | `(clientId: String, config: Object)`                            |
+| 断开连接       | `ftpClientDisconnect`          | `(clientId: String)`                                            |
+| 文件列表       | `ftpClientList`                | `(clientId: String, path?: String)`                             |
+| 下载文件       | `ftpClientDownload`            | `(clientId: String, remotePath: String, localPath: String)`     |
+| 上传文件       | `ftpClientUpload`              | `(clientId: String, localPath: String, remotePath: String)`     |
+| 删除文件       | `ftpClientDelete`              | `(clientId: String, remotePath: String, isDirectory?: Boolean)` |
+| 创建目录       | `ftpClientCreateDirectory`     | `(clientId: String, remotePath: String)`                        |
+| 切换目录       | `ftpClientChangeDirectory`     | `(clientId: String, remotePath: String)`                        |
+| 获取当前目录   | `ftpClientGetCurrentDirectory` | `(clientId: String)`                                            |
+| 获取客户端状态 | `getFtpClientStatus`           | `(clientId: String)`                                            |
+| 列出所有客户端 | `listFtpClients`               | `()`                                                            |
+
+## iOS代码更改详情
+
+### 主要FTP操作方法
+
+```swift
+// 连接
+AsyncFunction("ftpClientConnect") { (clientId: String, config: [String: Any], promise: Promise) in
+
+// 断开连接
+AsyncFunction("ftpClientDisconnect") { (clientId: String, promise: Promise) in
+
+// 文件列表
+AsyncFunction("ftpClientList") { (clientId: String, path: String?, promise: Promise) in
+
+// 下载文件
+AsyncFunction("ftpClientDownload") { (clientId: String, remotePath: String, localPath: String, promise: Promise) in
+
+// 上传文件
+AsyncFunction("ftpClientUpload") { (clientId: String, localPath: String, remotePath: String, promise: Promise) in
+
+// 删除文件
+AsyncFunction("ftpClientDelete") { (clientId: String, remotePath: String, isDirectory: Bool?, promise: Promise) in
+
+// 创建目录
+AsyncFunction("ftpClientCreateDirectory") { (clientId: String, remotePath: String, promise: Promise) in
+
+// 切换目录
+AsyncFunction("ftpClientChangeDirectory") { (clientId: String, remotePath: String, promise: Promise) in
+
+// 获取当前目录
+AsyncFunction("ftpClientGetCurrentDirectory") { (clientId: String, promise: Promise) in
+```
+
+### 客户端管理方法
+
+```swift
+// 获取客户端状态 - 改为异步
+AsyncFunction("getFtpClientStatus") { (clientId: String, promise: Promise) in
+  guard let ftpClient = self.ftpClients[clientId] else {
+    promise.resolve([
+      "exists": false,
+      "connected": false
+    ])
+    return
+  }
+
+  promise.resolve([
+    "exists": true,
+    "connected": ftpClient.isConnected
+  ])
+}
+
+// 列出所有客户端 - 改为异步
+AsyncFunction("listFtpClients") { (promise: Promise) in
+  let clientsInfo = self.ftpClients.mapValues { client in
+    [
+      "connected": client.isConnected
+    ]
+  }
+
+  promise.resolve([
+    "clients": clientsInfo,
+    "count": self.ftpClients.count
+  ])
+}
+```
+
+## 兼容性说明
+
+### 完全统一
+
+现在iOS和Android的API接口完全统一：
+
+- ✅ 方法名称一致
+- ✅ 参数顺序一致
+- ✅ 返回值格式一致
+- ✅ 所有方法都是异步的
+- ✅ 错误处理方式一致
+
+### TypeScript类型定义
+
+TypeScript模块定义(`ReactNativeKookitModule.ts`)已经使用了统一的命名，无需修改。
+
+### FtpClient包装类
+
+`FtpClient.ts`中的方法调用已经更新为使用统一的方法名。
+
+## 影响范围
+
+### 不影响的部分
+
+- TypeScript客户端API保持不变
+- 示例应用代码无需修改
+- 用户使用的高级API (`FtpClient` 类) 保持不变
+
+### 改进的部分
+
+- 跨平台开发时API行为完全一致
+- 调试时方法名称在两个平台上相同
+- 内部native方法调用逻辑统一
+
+## 验证结果
+
+### 构建测试
+
+- ✅ TypeScript编译：0错误
+- ✅ iOS Swift编译：通过
+- ✅ Android Kotlin编译：通过
+
+### API一致性验证
+
+```typescript
+// 现在这些调用在iOS和Android上完全一致
+await ReactNativeKookitModule.createFtpClient(clientId);
+await ReactNativeKookitModule.ftpClientConnect(clientId, config);
+await ReactNativeKookitModule.ftpClientList(clientId, path);
+await ReactNativeKookitModule.ftpClientDownload(
+  clientId,
+  remotePath,
+  localPath
+);
+// ... 所有其他方法
+```
+
+## 总结
+
+通过这次统一更新：
+
+1. **解决了命名不一致问题**：iOS方法名更新为与Android一致
+2. **统一了异步模式**：所有方法都使用AsyncFunction模式
+3. **简化了维护工作**：两个平台使用相同的API接口
+4. **提高了开发体验**：跨平台开发时无需记忆不同的方法名
+
+现在iOS和Android的FTP客户端API完全统一，为开发者提供了一致的跨平台体验。

package/FTP_CLIENT_API.md

@@ -0,0 +1,301 @@
+# FTP Client API
+
+This document describes the new FTP Client API that provides an object-oriented approach to FTP operations.
+
+## Overview
+
+The new FTP API allows you to create multiple FTP client instances, each maintaining its own connection and state. This is more flexible than the previous global FTP functions.
+
+## Basic Usage
+
+### Creating an FTP Client
+
+```typescript
+import { FtpClient } from "react-native-kookit";
+
+// Method 1: Using static create method (recommended)
+const ftpClient = await FtpClient.create("my-client-id");
+
+// Method 2: Manual initialization
+const ftpClient = new FtpClient("my-client-id");
+await ftpClient.initialize();
+```
+
+### Setting up Event Handlers
+
+```typescript
+ftpClient.setEventHandlers({
+  onProgress: (progress) => {
+    console.log(`Progress: ${progress.percentage}%`);
+    console.log(`Transferred: ${progress.transferred}/${progress.total} bytes`);
+  },
+  onComplete: () => {
+    console.log("Operation completed successfully!");
+  },
+  onError: (error) => {
+    console.error("FTP Error:", error.message);
+  },
+});
+```
+
+### Connecting to FTP Server
+
+```typescript
+await ftpClient.connect({
+  host: "192.168.1.100",
+  port: 21, // optional, defaults to 21
+  username: "your-username",
+  password: "your-password",
+  passive: true, // optional, defaults to true
+  timeout: 30, // optional, defaults to 30 seconds
+});
+```
+
+## FTP Operations
+
+### Directory Operations
+
+```typescript
+// Get current directory
+const currentDir = await ftpClient.getCurrentDirectory();
+console.log("Current directory:", currentDir);
+
+// Change directory
+await ftpClient.changeDirectory("/path/to/directory");
+
+// Create directory
+await ftpClient.createDirectory("/path/to/new-directory");
+
+// List files and directories
+const files = await ftpClient.list(); // List current directory
+const filesInPath = await ftpClient.list("/specific/path"); // List specific path
+
+files.forEach((file) => {
+  console.log(
+    `${file.name} - ${file.isDirectory ? "DIR" : "FILE"} - ${file.size} bytes`
+  );
+});
+```
+
+### File Operations
+
+```typescript
+// Download file
+await ftpClient.download("/remote/path/file.txt", "/local/path/file.txt");
+
+// Upload file
+await ftpClient.upload("/local/path/file.txt", "/remote/path/file.txt");
+
+// Delete file
+await ftpClient.delete("/remote/path/file.txt");
+
+// Delete directory
+await ftpClient.delete("/remote/path/directory", true); // true for directory
+```
+
+### Client Management
+
+```typescript
+// Check client status
+const status = ftpClient.getStatus();
+console.log("Client exists:", status.exists);
+console.log("Client connected:", status.connected);
+
+// Check if connected (convenience method)
+if (ftpClient.isConnected()) {
+  console.log("Client is ready for operations");
+}
+
+// Get client ID
+const clientId = ftpClient.getClientId();
+console.log("Client ID:", clientId);
+
+// Disconnect from server
+await ftpClient.disconnect();
+
+// Dispose client and clean up resources
+await ftpClient.dispose();
+```
+
+## Advanced Usage
+
+### Multiple FTP Clients
+
+```typescript
+import { FtpClient } from "react-native-kookit";
+
+// Create multiple clients for different servers
+const client1 = await FtpClient.create("server1");
+const client2 = await FtpClient.create("server2");
+
+// Connect to different servers
+await client1.connect({
+  host: "ftp1.example.com",
+  username: "user1",
+  password: "pass1",
+});
+
+await client2.connect({
+  host: "ftp2.example.com",
+  username: "user2",
+  password: "pass2",
+});
+
+// Perform operations on different servers simultaneously
+const [files1, files2] = await Promise.all([client1.list(), client2.list()]);
+
+// Clean up
+await Promise.all([client1.dispose(), client2.dispose()]);
+```
+
+### Managing All Clients
+
+```typescript
+// List all active FTP clients
+const clientsInfo = FtpClient.listClients();
+console.log("Active clients:", clientsInfo.count);
+console.log("Clients details:", clientsInfo.clients);
+
+// Example output:
+// {
+//   clients: {
+//     'client-1': { connected: true },
+//     'client-2': { connected: false }
+//   },
+//   count: 2
+// }
+```
+
+### Error Handling
+
+```typescript
+try {
+  const ftpClient = await FtpClient.create();
+
+  await ftpClient.connect({
+    host: "ftp.example.com",
+    username: "user",
+    password: "pass",
+  });
+
+  await ftpClient.download("/remote/file.txt", "/local/file.txt");
+} catch (error) {
+  console.error("FTP operation failed:", error.message);
+} finally {
+  // Always dispose to clean up resources
+  if (ftpClient) {
+    await ftpClient.dispose();
+  }
+}
+```
+
+## API Reference
+
+### FtpClient Class
+
+#### Constructor
+
+- `new FtpClient(clientId?: string)` - Create a new FTP client instance
+
+#### Static Methods
+
+- `FtpClient.create(clientId?: string): Promise<FtpClient>` - Create and initialize a new FTP client
+- `FtpClient.listClients()` - Get information about all active FTP clients
+
+#### Instance Methods
+
+**Lifecycle:**
+
+- `initialize(): Promise<void>` - Initialize the client (called automatically by `create()`)
+- `dispose(): Promise<void>` - Dispose client and clean up resources
+
+**Connection:**
+
+- `connect(config: FtpConnectionConfig): Promise<void>` - Connect to FTP server
+- `disconnect(): Promise<void>` - Disconnect from FTP server
+- `isConnected(): boolean` - Check if client is connected
+
+**Directory Operations:**
+
+- `list(path?: string): Promise<FtpFileInfo[]>` - List files and directories
+- `getCurrentDirectory(): Promise<string>` - Get current working directory
+- `changeDirectory(path: string): Promise<void>` - Change working directory
+- `createDirectory(path: string): Promise<void>` - Create a directory
+
+**File Operations:**
+
+- `download(remotePath: string, localPath: string): Promise<void>` - Download a file
+- `upload(localPath: string, remotePath: string): Promise<void>` - Upload a file
+- `delete(remotePath: string, isDirectory?: boolean): Promise<void>` - Delete a file or directory
+
+**Utility:**
+
+- `getStatus()` - Get client status information
+- `getClientId(): string` - Get the client ID
+- `setEventHandlers(handlers: FtpClientEventHandlers): void` - Set event handlers
+
+### Types
+
+```typescript
+interface FtpConnectionConfig {
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  passive?: boolean;
+  timeout?: number;
+}
+
+interface FtpFileInfo {
+  name: string;
+  isDirectory: boolean;
+  size: number;
+  lastModified: string;
+  permissions?: string;
+}
+
+interface FtpClientEventHandlers {
+  onProgress?: (progress: {
+    transferred: number;
+    total: number;
+    percentage: number;
+  }) => void;
+  onComplete?: () => void;
+  onError?: (error: Error) => void;
+}
+```
+
+## Migration from Old API
+
+If you're migrating from the old global FTP functions, here's how to update your code:
+
+### Old API:
+
+```typescript
+import ReactNativeKookitModule from "react-native-kookit";
+
+await ReactNativeKookitModule.ftpConnect(config);
+const files = await ReactNativeKookitModule.ftpList();
+await ReactNativeKookitModule.ftpDownload(remotePath, localPath);
+await ReactNativeKookitModule.ftpDisconnect();
+```
+
+### New API:
+
+```typescript
+import { FtpClient } from "react-native-kookit";
+
+const ftpClient = await FtpClient.create();
+await ftpClient.connect(config);
+const files = await ftpClient.list();
+await ftpClient.download(remotePath, localPath);
+await ftpClient.dispose(); // This disconnects and cleans up
+```
+
+## Best Practices
+
+1. **Always dispose clients**: Call `dispose()` when you're done to clean up resources
+2. **Use try-finally blocks**: Ensure disposal happens even if operations fail
+3. **Handle events**: Set up progress, completion, and error handlers for better UX
+4. **Use meaningful client IDs**: This helps with debugging and client management
+5. **Check connection status**: Use `isConnected()` before performing operations