expo-openclaw-chat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bruno Barbieri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# 🦞 expo-openclaw-chat 🦞
+
+Minimal chat SDK for Expo apps to connect to OpenClaw gateway.
+
+<p align="center">
+  <img src="screenshot.png" width="300" alt="Demo Chat Screenshot" />
+  <br/>
+  <em>A picture is worth a thousand words.</em>
+</p>
+
+## Installation
+
+```bash
+npm install expo-openclaw-chat
+```
+
+## Quick Start
+
+```tsx
+import { createChat } from "expo-openclaw-chat";
+
+// Create chat instance
+const chat = createChat({
+  gatewayUrl: "wss://your-gateway.example.com",
+  token: "your-auth-token", // or use password/deviceToken
+});
+
+// Wrap your app with ChatProvider
+function App() {
+  return (
+    <chat.ChatProvider>
+      <YourApp />
+    </chat.ChatProvider>
+  );
+}
+
+// Open chat modal from anywhere
+chat.open();
+
+// Close chat modal
+chat.close();
+```
+
+## Configuration Options
+
+```tsx
+createChat({
+  // Required
+  gatewayUrl: string;           // WebSocket URL (wss:// or ws://)
+
+  // Authentication (pick one)
+  token?: string;               // Simple auth token
+  password?: string;            // Password auth
+  deviceToken?: string;         // Device token from pairing
+
+  // Optional
+  sessionKey?: string;          // Chat session key (auto-generated if not provided)
+  title?: string;               // Modal title (default: "Chat")
+  placeholder?: string;         // Input placeholder text
+  showImagePicker?: boolean;    // Show image picker button (requires expo-image-picker)
+  clientId?: string;            // Client ID for gateway registration
+
+  // Callbacks
+  onOpen?: () => void;          // Called when modal opens
+  onClose?: () => void;         // Called when modal closes
+
+  // Storage
+  storage?: Storage;            // Custom storage for device identity
+});
+```
+
+## Optional Dependencies
+
+Install these for additional features:
+
+```bash
+# Image attachments
+npm install expo-image-picker
+
+# Markdown rendering
+npm install react-native-marked
+
+# Persistent device identity (recommended)
+npm install react-native-mmkv
+```
+
+## Custom Storage
+
+By default, device identity is stored in memory (regenerates on app restart). For persistent identity:
+
+```tsx
+import { setStorage } from "expo-openclaw-chat/lib";
+import { MMKV } from "react-native-mmkv";
+
+const storage = new MMKV({ id: "my-app" });
+setStorage(storage);
+```
+
+## Advanced Usage
+
+### Using Individual Components
+
+```tsx
+import {
+  GatewayClient,
+  ChatEngine,
+  ChatModal,
+  ChatList,
+  ChatBubble,
+  ChatInput
+} from "expo-openclaw-chat";
+
+// Create client manually
+const client = new GatewayClient("wss://gateway.example.com", {
+  token: "your-token",
+});
+
+// Connect
+await client.connect();
+
+// Create chat engine
+const engine = new ChatEngine(client, "session-key");
+
+// Listen for updates
+engine.on("update", () => {
+  console.log("Messages:", engine.messages);
+});
+
+// Send a message
+await engine.send("Hello!");
+```
+
+### Direct Core Access
+
+```tsx
+import {
+  GatewayClient,
+  generateIdempotencyKey,
+  loadOrCreateIdentity,
+} from "expo-openclaw-chat/lib";
+```
+
+## Demo App
+
+See the [demo](./demo) folder for a complete example.
+
+
+https://github.com/user-attachments/assets/69316dca-5bbf-42b7-93b9-fa9bc3bbc5f5
+
+
+## License
+
+MIT

package/lib/index.ts

@@ -0,0 +1,2 @@
+// Subpath export for Metro compatibility
+export * from "../src/core";

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "expo-openclaw-chat",
+  "version": "0.1.0",
+  "description": "Minimal chat SDK for Expo apps to connect to OpenClaw gateway",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./lib": "./lib/index.ts"
+  },
+  "files": [
+    "src",
+    "lib"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^3.0.0",
+    "@noble/hashes": "^2.0.0"
+  },
+  "peerDependencies": {
+    "expo": ">=50.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-keyboard-controller": ">=1.0.0",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-safe-area-context": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-image-picker": {
+      "optional": true
+    },
+    "react-native-marked": {
+      "optional": true
+    },
+    "react-native-mmkv": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@types/jest": "^29.5.0",
+    "@types/react": "^19.2.10",
+    "@types/react-native": "^0.72.8",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "react-native-keyboard-controller": "^1.20.7",
+    "react-native-reanimated": "^4.2.1",
+    "react-native-safe-area-context": "^5.6.2",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/__tests__/**/*.test.ts"
+    ],
+    "moduleFileExtensions": [
+      "ts",
+      "js"
+    ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!(@noble)/)"
+    ],
+    "transform": {
+      "^.+\\.ts$": "ts-jest",
+      "^.+\\.js$": "babel-jest"
+    }
+  },
+  "keywords": [
+    "expo",
+    "react-native",
+    "chat",
+    "openclaw",
+    "ai"
+  ],
+  "author": "Bruno Barbieri",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/expo-openclaw-chat"
+  }
+}

package/src/chat/__tests__/engine.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Tests for ChatEngine
+ */
+
+import { ChatEngine, type PendingAttachment } from "../engine";
+import type { GatewayClient } from "../../core/client";
+import type { ChatEventPayload } from "../../core/protocol";
+
+// Mock client type with test helpers
+type MockGatewayClient = GatewayClient & {
+  _emitConnectionState: (state: string) => void;
+  _emitChatEvent: (payload: ChatEventPayload) => void;
+};
+
+// Mock GatewayClient
+function createMockClient(overrides: Partial<GatewayClient> = {}): MockGatewayClient {
+  const connectionStateListeners = new Set<(state: string) => void>();
+  const chatEventListeners = new Set<(payload: ChatEventPayload) => void>();
+
+  return {
+    isConnected: true,
+    connectionState: "connected",
+    serverInfo: null,
+
+    onConnectionStateChange: jest.fn((cb) => {
+      connectionStateListeners.add(cb);
+      return () => connectionStateListeners.delete(cb);
+    }),
+
+    onChatEvent: jest.fn((cb) => {
+      chatEventListeners.add(cb);
+      return () => chatEventListeners.delete(cb);
+    }),
+
+    chatSubscribe: jest.fn(),
+    chatSend: jest.fn().mockResolvedValue({ runId: "test-run-id" }),
+    chatAbort: jest.fn().mockResolvedValue(undefined),
+
+    // Test helpers
+    _emitConnectionState: (state: string) => {
+      connectionStateListeners.forEach((cb) => cb(state));
+    },
+    _emitChatEvent: (payload: ChatEventPayload) => {
+      chatEventListeners.forEach((cb) => cb(payload));
+    },
+
+    ...overrides,
+  } as unknown as MockGatewayClient;
+}
+
+describe("ChatEngine", () => {
+  let mockClient: MockGatewayClient;
+  let engine: ChatEngine;
+
+  beforeEach(() => {
+    mockClient = createMockClient();
+    engine = new ChatEngine(mockClient as unknown as GatewayClient, "test-session");
+  });
+
+  afterEach(() => {
+    engine.destroy();
+  });
+
+  describe("constructor", () => {
+    it("initializes with empty messages", () => {
+      expect(engine.messages).toEqual([]);
+      expect(engine.isStreaming).toBe(false);
+      expect(engine.error).toBeNull();
+    });
+
+    it("subscribes to chat events for the session", () => {
+      expect(mockClient.chatSubscribe).toHaveBeenCalledWith("test-session");
+    });
+  });
+
+  describe("send", () => {
+    it("adds a user message to the list", async () => {
+      await engine.send("Hello, world!");
+
+      expect(engine.messages.length).toBe(2); // user + assistant placeholder
+      const userMessage = engine.messages[0];
+      expect(userMessage).toBeDefined();
+      expect(userMessage!.role).toBe("user");
+      expect(userMessage!.content).toEqual([{ type: "text", text: "Hello, world!" }]);
+    });
+
+    it("calls chatSend on the client", async () => {
+      await engine.send("Test message");
+
+      expect(mockClient.chatSend).toHaveBeenCalledWith(
+        "test-session",
+        "Test message",
+        expect.objectContaining({
+          idempotencyKey: expect.any(String),
+        }),
+      );
+    });
+
+    it("does not send empty messages", async () => {
+      await engine.send("");
+      await engine.send("   ");
+
+      expect(mockClient.chatSend).not.toHaveBeenCalled();
+      expect(engine.messages).toEqual([]);
+    });
+
+    it("handles attachments", async () => {
+      const attachments: PendingAttachment[] = [
+        {
+          id: "img-1",
+          fileName: "test.jpg",
+          mimeType: "image/jpeg",
+          content: "base64data",
+          type: "image",
+        },
+      ];
+
+      await engine.send("With image", attachments);
+
+      const message = engine.messages[0];
+      expect(message).toBeDefined();
+      expect(message!.content.length).toBe(2); // image + text
+      expect(message!.content[0]!.type).toBe("image");
+    });
+
+    it("sets error when not connected", async () => {
+      const disconnectedClient = createMockClient({ isConnected: false });
+      const disconnectedEngine = new ChatEngine(
+        disconnectedClient as unknown as GatewayClient,
+        "test-session",
+      );
+
+      await disconnectedEngine.send("Test");
+
+      expect(disconnectedEngine.error).not.toBeNull();
+      expect(disconnectedEngine.error?.message).toBe("Not connected");
+
+      disconnectedEngine.destroy();
+    });
+  });
+
+  describe("abort", () => {
+    it("calls chatAbort on the client", async () => {
+      await engine.send("Test");
+      await engine.abort();
+
+      expect(mockClient.chatAbort).toHaveBeenCalled();
+    });
+
+    it("does nothing when not streaming", async () => {
+      await engine.abort();
+
+      expect(mockClient.chatAbort).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("clear", () => {
+    it("removes all messages", async () => {
+      await engine.send("Message 1");
+      engine.clear();
+
+      expect(engine.messages).toEqual([]);
+      expect(engine.isStreaming).toBe(false);
+    });
+  });
+
+  describe("event handling", () => {
+    it("handles delta events", async () => {
+      await engine.send("Test");
+
+      // Simulate streaming delta
+      mockClient._emitChatEvent({
+        runId: "test-run-id",
+        sessionKey: "test-session",
+        state: "delta",
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "Partial response" }],
+        },
+      } as ChatEventPayload);
+
+      // Wait for flush timer
+      await new Promise((resolve) => setTimeout(resolve, 300));
+
+      const assistantMsg = engine.messages.find((m) => m.role === "assistant");
+      expect(assistantMsg).toBeDefined();
+      expect(assistantMsg?.isStreaming).toBe(true);
+    });
+
+    it("handles complete events", async () => {
+      await engine.send("Test");
+
+      // Simulate complete
+      mockClient._emitChatEvent({
+        runId: "test-run-id",
+        sessionKey: "test-session",
+        state: "complete",
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "Final response" }],
+        },
+      } as ChatEventPayload);
+
+      const assistantMsg = engine.messages.find((m) => m.role === "assistant");
+      expect(assistantMsg?.isStreaming).toBe(false);
+      expect(engine.isStreaming).toBe(false);
+    });
+
+    it("handles error events", async () => {
+      await engine.send("Test");
+
+      mockClient._emitChatEvent({
+        runId: "test-run-id",
+        sessionKey: "test-session",
+        state: "error",
+        errorMessage: "Something went wrong",
+      } as ChatEventPayload);
+
+      expect(engine.error?.message).toBe("Something went wrong");
+      expect(engine.isStreaming).toBe(false);
+    });
+
+    it("ignores events for other sessions", async () => {
+      await engine.send("Test");
+
+      mockClient._emitChatEvent({
+        runId: "other-run-id",
+        sessionKey: "other-session",
+        state: "delta",
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "Wrong session" }],
+        },
+      } as ChatEventPayload);
+
+      // Should only have user message + placeholder
+      expect(engine.messages.length).toBe(2);
+    });
+  });
+
+  describe("event subscriptions", () => {
+    it("notifies update listeners", async () => {
+      const updates: number[] = [];
+      engine.on("update", () => updates.push(engine.messages.length));
+
+      await engine.send("Test");
+
+      expect(updates.length).toBeGreaterThan(0);
+    });
+
+    it("notifies error listeners", async () => {
+      const errors: Error[] = [];
+      engine.on("error", (err) => errors.push(err));
+
+      // Trigger an error
+      mockClient._emitChatEvent({
+        runId: "test-run-id",
+        sessionKey: "test-session",
+        state: "error",
+        errorMessage: "Test error",
+      } as ChatEventPayload);
+
+      expect(errors.length).toBe(1);
+      expect(errors[0]!.message).toBe("Test error");
+    });
+
+    it("allows unsubscribing", () => {
+      const updates: number[] = [];
+      const unsub = engine.on("update", () => updates.push(1));
+
+      unsub();
+      engine.clear();
+
+      expect(updates).toEqual([]);
+    });
+  });
+
+  describe("destroy", () => {
+    it("cleans up subscriptions", () => {
+      const updates: number[] = [];
+      engine.on("update", () => updates.push(1));
+
+      engine.destroy();
+      engine.clear(); // This would normally trigger update
+
+      expect(updates).toEqual([]);
+    });
+  });
+});