react-native-kookit 0.2.1 → 0.2.2

package/FTP_README.md

@@ -0,0 +1,322 @@
+# React Native Kookit - FTP Client
+
+A React Native Expo module that provides volume key interception and FTP client functionality for iOS and Android.
+
+## Features
+
+### Volume Key Interception
+
+- Intercept volume up/down button presses
+- Works on both iOS and Android
+- Prevent default volume behavior (optional)
+
+### FTP Client
+
+- Connect to FTP servers
+- List files and directories
+- Download files from FTP server
+- Upload files to FTP server
+- Delete files and directories
+- Create directories
+- Navigate directories
+- Progress monitoring for uploads/downloads
+
+## Installation
+
+```bash
+npm install react-native-kookit
+```
+
+### iOS Setup
+
+For iOS, no additional setup is required. The module works out of the box.
+
+### Android Setup
+
+For Android, your MainActivity must implement the `VolumeKeyInterceptActivity` interface:
+
+```kotlin
+import expo.modules.kookit.VolumeKeyInterceptActivity
+
+class MainActivity : ReactActivity(), VolumeKeyInterceptActivity {
+    // ... existing code ...
+}
+```
+
+## Usage
+
+### Basic Import
+
+```typescript
+import ReactNativeKookitModule, {
+  FtpConnectionConfig,
+  FtpFileInfo,
+  FtpProgressInfo,
+} from "react-native-kookit";
+```
+
+### Volume Key Interception
+
+```typescript
+import { useEffect } from "react";
+
+useEffect(() => {
+  // Set up volume key listener
+  const subscription = ReactNativeKookitModule.addListener(
+    "onVolumeButtonPressed",
+    (event) => {
+      console.log("Volume button pressed:", event.key); // 'up' or 'down'
+    }
+  );
+
+  // Enable volume key interception
+  ReactNativeKookitModule.enableVolumeKeyInterception();
+
+  return () => {
+    // Clean up
+    ReactNativeKookitModule.disableVolumeKeyInterception();
+    subscription.remove();
+  };
+}, []);
+```
+
+### FTP Client Usage
+
+#### 1. Connect to FTP Server
+
+```typescript
+const config: FtpConnectionConfig = {
+  host: "ftp.example.com",
+  port: 21, // optional, defaults to 21
+  username: "your-username",
+  password: "your-password",
+  passive: true, // optional, defaults to true
+  timeout: 30000, // optional, defaults to 30000ms
+};
+
+try {
+  await ReactNativeKookitModule.ftpConnect(config);
+  console.log("Connected to FTP server");
+} catch (error) {
+  console.error("Failed to connect:", error);
+}
+```
+
+#### 2. List Files and Directories
+
+```typescript
+try {
+  const files: FtpFileInfo[] = await ReactNativeKookitModule.ftpList();
+  files.forEach((file) => {
+    console.log(
+      `${file.isDirectory ? "DIR" : "FILE"}: ${file.name} (${file.size} bytes)`
+    );
+  });
+} catch (error) {
+  console.error("Failed to list files:", error);
+}
+```
+
+#### 3. Download Files
+
+```typescript
+try {
+  const remotePath = "remote-file.txt";
+  const localPath = "/path/to/local/file.txt";
+
+  await ReactNativeKookitModule.ftpDownload(remotePath, localPath);
+  console.log("File downloaded successfully");
+} catch (error) {
+  console.error("Download failed:", error);
+}
+```
+
+#### 4. Upload Files
+
+```typescript
+try {
+  const localPath = "/path/to/local/file.txt";
+  const remotePath = "remote-file.txt";
+
+  await ReactNativeKookitModule.ftpUpload(localPath, remotePath);
+  console.log("File uploaded successfully");
+} catch (error) {
+  console.error("Upload failed:", error);
+}
+```
+
+#### 5. Progress Monitoring
+
+```typescript
+useEffect(() => {
+  const progressListener = ReactNativeKookitModule.addListener(
+    "onFtpProgress",
+    (progress: FtpProgressInfo) => {
+      console.log(
+        `Progress: ${progress.percentage}% (${progress.transferred}/${progress.total} bytes)`
+      );
+    }
+  );
+
+  const completeListener = ReactNativeKookitModule.addListener(
+    "onFtpComplete",
+    () => {
+      console.log("Operation completed");
+    }
+  );
+
+  const errorListener = ReactNativeKookitModule.addListener(
+    "onFtpError",
+    (error) => {
+      console.error("FTP Error:", error.error);
+    }
+  );
+
+  return () => {
+    progressListener.remove();
+    completeListener.remove();
+    errorListener.remove();
+  };
+}, []);
+```
+
+#### 6. Directory Operations
+
+```typescript
+// Create directory
+await ReactNativeKookitModule.ftpCreateDirectory("new-directory");
+
+// Change directory
+await ReactNativeKookitModule.ftpChangeDirectory("some-directory");
+
+// Get current directory
+const currentDir = await ReactNativeKookitModule.ftpGetCurrentDirectory();
+console.log("Current directory:", currentDir);
+
+// Delete file or directory
+await ReactNativeKookitModule.ftpDelete("file.txt", false); // false for file
+await ReactNativeKookitModule.ftpDelete("directory", true); // true for directory
+```
+
+#### 7. Disconnect
+
+```typescript
+try {
+  await ReactNativeKookitModule.ftpDisconnect();
+  console.log("Disconnected from FTP server");
+} catch (error) {
+  console.error("Failed to disconnect:", error);
+}
+```
+
+## API Reference
+
+### 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 FtpProgressInfo {
+  transferred: number;
+  total: number;
+  percentage: number;
+}
+```
+
+### Methods
+
+#### Volume Key Methods
+
+- `enableVolumeKeyInterception()`: Enable volume key interception
+- `disableVolumeKeyInterception()`: Disable volume key interception
+
+#### FTP Methods
+
+- `ftpConnect(config: FtpConnectionConfig): Promise<void>`
+- `ftpDisconnect(): Promise<void>`
+- `ftpList(path?: string): Promise<FtpFileInfo[]>`
+- `ftpDownload(remotePath: string, localPath: string): Promise<void>`
+- `ftpUpload(localPath: string, remotePath: string): Promise<void>`
+- `ftpDelete(remotePath: string, isDirectory?: boolean): Promise<void>`
+- `ftpCreateDirectory(remotePath: string): Promise<void>`
+- `ftpChangeDirectory(remotePath: string): Promise<void>`
+- `ftpGetCurrentDirectory(): Promise<string>`
+
+### Events
+
+#### Volume Key Events
+
+- `onVolumeButtonPressed`: Fired when volume button is pressed
+  ```typescript
+  {
+    key: "up" | "down";
+  }
+  ```
+
+#### FTP Events
+
+- `onFtpProgress`: Fired during file transfer operations
+
+  ```typescript
+  { transferred: number, total: number, percentage: number }
+  ```
+
+- `onFtpComplete`: Fired when an operation completes successfully
+
+- `onFtpError`: Fired when an error occurs
+  ```typescript
+  {
+    error: string;
+  }
+  ```
+
+## Platform Support
+
+- ✅ iOS 15.1+
+- ✅ Android API 21+
+- ❌ Web (FTP operations are not supported due to browser security restrictions)
+
+## Example
+
+See the [FtpExample.tsx](./example/FtpExample.tsx) file for a complete working example.
+
+## Security Considerations
+
+- FTP credentials are transmitted in plain text. Use FTPS or SFTP for secure file transfers when possible.
+- Ensure proper file path validation to prevent directory traversal attacks.
+- Consider implementing connection pooling and timeout handling for production use.
+
+## Troubleshooting
+
+### Android
+
+- Make sure your MainActivity implements `VolumeKeyInterceptActivity`
+- Check that you have INTERNET permission in your AndroidManifest.xml
+
+### iOS
+
+- Ensure your app has network permissions
+- For file operations, make sure your app has appropriate file system permissions
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+MIT

package/android/src/main/java/expo/modules/kookit/FtpClient.kt

@@ -0,0 +1,399 @@
+package expo.modules.kookit
+
+import kotlinx.coroutines.*
+import java.io.*
+import java.net.*
+import java.nio.charset.StandardCharsets
+import java.text.SimpleDateFormat
+import java.util.*
+import java.util.regex.Pattern
+
+data class FtpConnectionConfig(
+    val host: String,
+    val port: Int = 21,
+    val username: String,
+    val password: String,
+    val passive: Boolean = true,
+    val timeout: Int = 30000
+)
+
+data class FtpFileInfo(
+    val name: String,
+    val isDirectory: Boolean,
+    val size: Long,
+    val lastModified: String,
+    val permissions: String? = null
+)
+
+interface FtpProgressListener {
+    fun onProgress(transferred: Long, total: Long)
+    fun onComplete()
+    fun onError(error: String)
+}
+
+class FtpClient {
+    private var controlSocket: Socket? = null
+    private var controlInput: BufferedReader? = null
+    private var controlOutput: PrintWriter? = null
+    private var isConnected = false
+    private var config: FtpConnectionConfig? = null
+    private var useUtf8 = false
+    
+    @Throws(Exception::class)
+    suspend fun connect(config: FtpConnectionConfig) = withContext(Dispatchers.IO) {
+        this@FtpClient.config = config
+        
+        try {
+            // Create control connection
+            controlSocket = Socket().apply {
+                soTimeout = config.timeout
+                connect(InetSocketAddress(config.host, config.port), config.timeout)
+            }
+            
+            // Use default charset for initial communication
+            controlInput = BufferedReader(InputStreamReader(controlSocket!!.getInputStream(), StandardCharsets.ISO_8859_1))
+            controlOutput = PrintWriter(OutputStreamWriter(controlSocket!!.getOutputStream(), StandardCharsets.ISO_8859_1), true)
+            
+            // Read welcome message
+            val welcomeResponse = readResponse()
+            if (!welcomeResponse.startsWith("220")) {
+                throw Exception("FTP server not ready: $welcomeResponse")
+            }
+
+            // Try to switch to UTF-8
+            sendCommand("OPTS UTF8 ON")
+            val utf8Response = readResponse()
+            if (utf8Response.startsWith("200")) {
+                useUtf8 = true
+                // Re-initialize streams with UTF-8
+                controlInput = BufferedReader(InputStreamReader(controlSocket!!.getInputStream(), StandardCharsets.UTF_8))
+                controlOutput = PrintWriter(OutputStreamWriter(controlSocket!!.getOutputStream(), StandardCharsets.UTF_8), true)
+            }
+            
+            // Send username
+            sendCommand("USER ${config.username}")
+            val userResponse = readResponse()
+            if (!userResponse.startsWith("331") && !userResponse.startsWith("230")) {
+                throw Exception("Username rejected: $userResponse")
+            }
+            
+            // Send password if needed
+            if (userResponse.startsWith("331")) {
+                sendCommand("PASS ${config.password}")
+                val passResponse = readResponse()
+                if (!passResponse.startsWith("230")) {
+                    throw Exception("Authentication failed: $passResponse")
+                }
+            }
+            
+            // Set binary mode
+            sendCommand("TYPE I")
+            val typeResponse = readResponse()
+            if (!typeResponse.startsWith("200")) {
+                throw Exception("Failed to set binary mode: $typeResponse")
+            }
+            
+            isConnected = true
+        } catch (e: Exception) {
+            disconnect()
+            throw e
+        }
+    }
+    
+    suspend fun disconnect() = withContext(Dispatchers.IO) {
+        try {
+            if (isConnected) {
+                sendCommand("QUIT")
+                readResponse()
+            }
+        } catch (e: Exception) {
+            // Ignore errors during disconnect
+        } finally {
+            try {
+                controlInput?.close()
+                controlOutput?.close()
+                controlSocket?.close()
+            } catch (e: Exception) {
+                // Ignore
+            }
+            controlInput = null
+            controlOutput = null
+            controlSocket = null
+            isConnected = false
+            useUtf8 = false
+        }
+    }
+    
+    @Throws(Exception::class)
+    suspend fun listFiles(path: String? = null): List<FtpFileInfo> = withContext(Dispatchers.IO) {
+        if (!isConnected) throw Exception("Not connected to FTP server")
+        
+        val dataSocket = enterPassiveMode()
+        
+        try {
+            val command = if (path != null) "LIST $path" else "LIST"
+            sendCommand(command)
+            val response = readResponse()
+            if (!response.startsWith("150") && !response.startsWith("125")) {
+                throw Exception("Failed to list files: $response")
+            }
+            
+            val files = mutableListOf<FtpFileInfo>()
+            val charset = if (useUtf8) StandardCharsets.UTF_8 else Charsets.ISO_8859_1
+            val reader = BufferedReader(InputStreamReader(dataSocket.getInputStream(), charset))
+            
+            reader.useLines { lines ->
+                lines.forEach { line ->
+                    parseListing(line)?.let { fileInfo ->
+                        files.add(fileInfo)
+                    }
+                }
+            }
+            
+            dataSocket.close()
+            
+            val finalResponse = readResponse()
+            if (!finalResponse.startsWith("226")) {
+                // Some servers send 250, so we'll accept that too.
+                if (!finalResponse.startsWith("250")) {
+                    throw Exception("Failed to complete file listing: $finalResponse")
+                }
+            }
+            
+            files
+        } catch (e: Exception) {
+            dataSocket.close()
+            throw e
+        }
+    }
+    
+    @Throws(Exception::class)
+    suspend fun downloadFile(remotePath: String, localPath: String, listener: FtpProgressListener? = null) = withContext(Dispatchers.IO) {
+        if (!isConnected) throw Exception("Not connected to FTP server")
+        
+        val dataSocket = enterPassiveMode()
+        val localFile = File(localPath)
+        
+        // Create parent directories if they don't exist
+        localFile.parentFile?.mkdirs()
+        
+        try {
+            sendCommand("RETR $remotePath")
+            val response = readResponse()
+            if (!response.startsWith("150") && !response.startsWith("125")) {
+                throw Exception("Failed to start download: $response")
+            }
+            
+            val inputStream = dataSocket.getInputStream()
+            val outputStream = FileOutputStream(localFile)
+            
+            val buffer = ByteArray(8192)
+            var totalBytes = 0L
+            var bytesRead: Int
+            
+            try {
+                while (inputStream.read(buffer).also { bytesRead = it } != -1) {
+                    outputStream.write(buffer, 0, bytesRead)
+                    totalBytes += bytesRead
+                    listener?.onProgress(totalBytes, -1) // Size unknown during download
+                }
+                
+                outputStream.flush()
+                listener?.onComplete()
+            } finally {
+                outputStream.close()
+                inputStream.close()
+            }
+            
+            dataSocket.close()
+            
+            val finalResponse = readResponse()
+            if (!finalResponse.startsWith("226")) {
+                throw Exception("Download failed: $finalResponse")
+            }
+        } catch (e: Exception) {
+            dataSocket.close()
+            localFile.delete() // Clean up incomplete file
+            listener?.onError(e.message ?: "Download failed")
+            throw e
+        }
+    }
+    
+    @Throws(Exception::class)
+    suspend fun uploadFile(localPath: String, remotePath: String, listener: FtpProgressListener? = null) = withContext(Dispatchers.IO) {
+        if (!isConnected) throw Exception("Not connected to FTP server")
+        
+        val localFile = File(localPath)
+        if (!localFile.exists()) {
+            throw Exception("Local file does not exist: $localPath")
+        }
+        
+        val dataSocket = enterPassiveMode()
+        val fileSize = localFile.length()
+        
+        try {
+            sendCommand("STOR $remotePath")
+            val response = readResponse()
+            if (!response.startsWith("150") && !response.startsWith("125")) {
+                throw Exception("Failed to start upload: $response")
+            }
+            
+            val inputStream = FileInputStream(localFile)
+            val outputStream = dataSocket.getOutputStream()
+            
+            val buffer = ByteArray(8192)
+            var totalBytes = 0L
+            var bytesRead: Int
+            
+            try {
+                while (inputStream.read(buffer).also { bytesRead = it } != -1) {
+                    outputStream.write(buffer, 0, bytesRead)
+                    totalBytes += bytesRead
+                    listener?.onProgress(totalBytes, fileSize)
+                }
+                
+                outputStream.flush()
+                listener?.onComplete()
+            } finally {
+                inputStream.close()
+                outputStream.close()
+            }
+            
+            dataSocket.close()
+            
+            val finalResponse = readResponse()
+            if (!finalResponse.startsWith("226")) {
+                throw Exception("Upload failed: $finalResponse")
+            }
+        } catch (e: Exception) {
+            dataSocket.close()
+            listener?.onError(e.message ?: "Upload failed")
+            throw e
+        }
+    }
+    
+    @Throws(Exception::class)
+    suspend fun deleteFile(remotePath: String, isDirectory: Boolean = false) = withContext(Dispatchers.IO) {
+        if (!isConnected) throw Exception("Not connected to FTP server")
+        
+        val command = if (isDirectory) "RMD $remotePath" else "DELE $remotePath"
+        sendCommand(command)
+        val response = readResponse()
+        if (!response.startsWith("250")) {
+            throw Exception("Failed to delete: $response")
+        }
+    }
+    
+    @Throws(Exception::class)
+    suspend fun createDirectory(remotePath: String) = withContext(Dispatchers.IO) {
+        if (!isConnected) throw Exception("Not connected to FTP server")
+        
+        sendCommand("MKD $remotePath")
+        val response = readResponse()
+        if (!response.startsWith("257")) {
+            throw Exception("Failed to create directory: $response")
+        }
+    }
+    
+    @Throws(Exception::class)
+    suspend fun changeDirectory(remotePath: String) = withContext(Dispatchers.IO) {
+        if (!isConnected) throw Exception("Not connected to FTP server")
+        
+        sendCommand("CWD $remotePath")
+        val response = readResponse()
+        if (!response.startsWith("250")) {
+            throw Exception("Failed to change directory: $response")
+        }
+    }
+    
+    @Throws(Exception::class)
+    suspend fun getCurrentDirectory(): String = withContext(Dispatchers.IO) {
+        if (!isConnected) throw Exception("Not connected to FTP server")
+        
+        sendCommand("PWD")
+        val response = readResponse()
+        if (!response.startsWith("257")) {
+            throw Exception("Failed to get current directory: $response")
+        }
+        
+        // Extract directory from response like: 257 "/home/user" is current directory
+        val start = response.indexOf('"')
+        val end = response.indexOf('"', start + 1)
+        if (start != -1 && end != -1) {
+            response.substring(start + 1, end)
+        } else {
+            throw Exception("Failed to parse current directory response: $response")
+        }
+    }
+    
+    private fun sendCommand(command: String) {
+        controlOutput?.println(command)
+    }
+    
+    private fun readResponse(): String {
+        val response = StringBuilder()
+        var line: String?
+        
+        do {
+            line = controlInput?.readLine()
+            if (line != null) {
+                response.append(line).append("\n")
+            }
+        } while (line != null && (line.length < 4 || line[3] == '-'))
+        
+        return response.toString().trim()
+    }
+    
+    @Throws(Exception::class)
+    private fun enterPassiveMode(): Socket {
+        sendCommand("PASV")
+        val response = readResponse()
+        if (!response.startsWith("227")) {
+            throw Exception("Failed to enter passive mode: $response")
+        }
+        
+        // Parse passive mode response: 227 Entering Passive Mode (h1,h2,h3,h4,p1,p2)
+        val pattern = Pattern.compile("\\((\\d+),(\\d+),(\\d+),(\\d+),(\\d+),(\\d+)\\)")
+        val matcher = pattern.matcher(response)
+        if (!matcher.find()) {
+            throw Exception("Failed to parse passive mode response: $response")
+        }
+        
+        val host = "${matcher.group(1)}.${matcher.group(2)}.${matcher.group(3)}.${matcher.group(4)}"
+        val port = matcher.group(5)!!.toInt() * 256 + matcher.group(6)!!.toInt()
+        
+        return Socket().apply {
+            soTimeout = config?.timeout ?: 30000
+            connect(InetSocketAddress(host, port), config?.timeout ?: 30000)
+        }
+    }
+    
+    private fun parseListing(line: String): FtpFileInfo? {
+        if (line.trim().isEmpty()) return null
+        
+        // Parse Unix-style listing: drwxr-xr-x 3 user group 4096 Mar 15 10:30 dirname
+        val parts = line.trim().split("\\s+".toRegex())
+        if (parts.size < 9) return null
+        
+        val permissions = parts[0]
+        val isDirectory = permissions.startsWith("d")
+        val size = if (isDirectory) 0L else parts[4].toLongOrNull() ?: 0L
+        
+        // Reconstruct filename (can contain spaces)
+        val name = parts.drop(8).joinToString(" ")
+        
+        // Parse date
+        val month = parts[5]
+        val day = parts[6]
+        val yearOrTime = parts[7]
+        val lastModified = "$month $day $yearOrTime"
+        
+        return FtpFileInfo(
+            name = name,
+            isDirectory = isDirectory,
+            size = size,
+            lastModified = lastModified,
+            permissions = permissions
+        )
+    }
+}