openclaw-voice 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyaukyuai
+
+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,237 @@
+# OpenClaw Voice (Expo React Native)
+
+![OpenClawVoice logo](assets/logo-badge.png)
+
+[![Expo SDK 54](https://img.shields.io/badge/Expo-SDK%2054-000020?logo=expo&logoColor=white)](https://expo.dev/)
+[![React Native 0.81](https://img.shields.io/badge/React%20Native-0.81-61DAFB?logo=react&logoColor=1f2937)](https://reactnative.dev/)
+[![TypeScript 5.x](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+A simple voice-first iOS client for OpenClaw Gateway.
+
+Speak -> edit transcript -> send -> stream response.
+
+## npm Package Usage
+
+Install:
+
+```bash
+npm install openclaw-voice
+```
+
+Example:
+
+```ts
+import { GatewayClient } from 'openclaw-voice';
+
+const client = new GatewayClient('wss://your-openclaw-gateway.example.com', {
+  token: 'your-token',
+  clientId: 'openclaw-ios',
+  displayName: 'OpenClawVoice',
+});
+```
+
+## Quick Start (5 Minutes)
+
+Prerequisites:
+
+- Node.js 18+
+- Xcode + iOS runtime
+- CocoaPods
+- A running OpenClaw Gateway endpoint (`wss://...`)
+
+Run one command:
+
+```bash
+bash scripts/bootstrap.sh
+```
+
+What this does:
+
+- Installs dependencies with `npm install`
+- Generates iOS native project (if missing)
+- Installs CocoaPods
+- Launches the app on a physical device (`npm run ios -- --device`)
+
+Or install dependencies manually:
+
+```bash
+npm install
+```
+
+If you prefer simulator:
+
+```bash
+npm run ios
+```
+
+## Screenshot
+
+![OpenClaw Voice UI states](docs/screenshots/openclaw-voice-v4.html.png)
+
+## Features
+
+- Speech-to-text input using `expo-speech-recognition`
+- Editable transcript before sending
+- OpenClaw Gateway connection with URL + token/password
+- Streaming chat response rendering
+- Conversation history with per-turn status (`WAIT`, `OK`, `ERR`)
+- Auto-reconnect capable gateway client
+- Persistent settings for gateway URL, token/password, and theme (`dark` / `light`)
+- Device identity persistence for gateway auth (Ed25519 key pair)
+- Compact UI with header connection status and bottom round action button
+
+## Tech Stack
+
+- Expo SDK 54
+- React Native 0.81
+- TypeScript
+- `expo-speech-recognition`
+- `expo-secure-store`
+- `expo-crypto`
+- `@noble/ed25519` + `@noble/hashes`
+
+## Environment Configuration
+
+Copy `.env.example` to `.env` and set values for your local environment:
+
+```bash
+cp .env.example .env
+```
+
+Available variables:
+
+- `EXPO_PUBLIC_DEFAULT_GATEWAY_URL`
+- `EXPO_PUBLIC_DEFAULT_THEME` (`light` or `dark`)
+- `EXPO_PUBLIC_GATEWAY_CLIENT_ID` (default: `openclaw-ios`)
+- `EXPO_PUBLIC_GATEWAY_DISPLAY_NAME` (default: `OpenClawVoice`)
+
+Notes:
+
+- `.env` files are ignored by git.
+- Do not commit gateway tokens or secrets.
+
+## Project Structure
+
+| Path | Purpose |
+| --- | --- |
+| `App.tsx` | Main UI, voice capture flow, transcript editing, gateway connect/send flow, history rendering |
+| `src/openclaw/client.ts` | OpenClaw Gateway WebSocket protocol client (handshake, events, requests, reconnect, keepalive) |
+| `src/openclaw/protocol.ts` | Protocol v3 types and event/method constants |
+| `src/openclaw/device-identity.ts` | Device identity generation/signing for gateway authentication |
+| `src/openclaw/storage.ts` | Storage abstraction used by identity module |
+| `crypto-polyfill.ts` | `crypto.getRandomValues`, `atob`, `btoa` polyfills for React Native runtime compatibility |
+| `scripts/bootstrap.sh` | One-command setup + run for iOS |
+| `.env.example` | Sample environment configuration |
+| `CONTRIBUTING.md` | Contribution workflow and local checks |
+| `docs/TROUBLESHOOTING.md` | Common issues and fixes |
+| `app.json` | Expo configuration and microphone/speech permission strings |
+
+## How to Use
+
+1. Launch the app.
+2. If not connected, the gateway panel opens automatically.
+3. Enter your `Gateway URL` (example: `wss://your-openclaw-gateway.example.com`) and optional `Token / Password`.
+4. Tap `Connect`.
+5. Hold the round mic button to speak.
+6. Release to stop recognition.
+7. Edit transcript if needed.
+8. Tap the send button (same round button state) to submit.
+9. View streamed response in History.
+
+## Scripts
+
+- `npm run start` - Start Expo dev server
+- `npm run ios` - Build and run iOS app
+- `npm run android` - Build and run Android app
+- `npm run web` - Run web target
+- `npm run typecheck` - Run TypeScript checks
+- `npm run build:package` - Build npm package files to `dist/`
+
+## Connection and Auth Notes
+
+The client currently connects with these defaults:
+
+- `clientId: openclaw-ios`
+- `displayName: OpenClawVoice`
+- `role: operator`
+- `scopes: operator.read, operator.write`
+- `caps: talk`
+- Device identity is generated locally and reused via secure persistence when available.
+- If identity is reset, the gateway may request pairing again.
+
+## Speech Recognition Behavior
+
+- Language is selectable from the Gateway panel (`日本語 / English`).
+- Interim results are shown while speaking.
+- Final recognition text is stored in editable transcript.
+- Some `aborted/cancelled` recognition errors are intentionally ignored when caused by expected stop flow.
+
+## Configuration Persistence
+
+These values are persisted locally:
+
+- Gateway URL
+- Token/password
+- Theme mode
+- Device identity record
+
+`expo-secure-store` is used when available. If native module loading fails, the app falls back to in-memory storage for runtime continuity.
+
+## Troubleshooting
+
+See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for known issues and fixes.
+
+## UI / UX Design Direction
+
+The current UI is intentionally minimal:
+
+- Small header with live connection chip
+- Gateway settings panel shown only when disconnected
+- Card-based transcript/history surfaces with subtle border + shadow
+- Bottom round icon-only primary action (mic/send state switch)
+- Dark/light theme toggle in header
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for branch/PR workflow and local checks.
+
+## CI
+
+GitHub Actions runs on push/PR:
+
+- Type check (`npm run typecheck`)
+- Lint (`npm run lint --if-present`)
+- Tests (`npm test --if-present`)
+
+Issue and PR templates are available in `.github/`.
+
+## Publish to npm
+
+```bash
+npm run build:package
+npm publish --access public
+```
+
+## Security Notes
+
+- Do not commit private gateway tokens.
+- Use secure `wss://` endpoints.
+- Pair only trusted devices in OpenClaw.
+- Prefer private network exposure first. Recommended order:
+  1. Tailscale/WireGuard private network
+  2. Cloudflare Tunnel with access control
+  3. Hardened VPS reverse proxy
+- Do not expose the Gateway port directly to the public internet.
+- If using Cloudflare Tunnel or VPS, require authentication at both layers:
+  - Edge access control (IdP login / service token / mTLS as applicable)
+  - Gateway token/password validation
+- Restrict source access (ACL / allowlist), rotate tokens regularly, and revoke leaked credentials immediately.
+- Keep TLS certificates and server packages updated, and enable request/rate logging for incident response.
+
+## Acknowledgements
+
+- [`expo-openclaw-chat`](https://github.com/brunobar79/expo-openclaw-chat) for protocol/client reference and implementation ideas.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

package/dist/openclaw/client.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Gateway WebSocket Client — full protocol v3 implementation
+ *
+ * Handles connect handshake, request/response, event subscriptions,
+ * auto-reconnect with exponential backoff, keepalive, and chat methods.
+ */
+import { type HelloOk, type ChatHistoryPayload, type ChatSendResponse, type ChatEventPayload, type AgentEventPayload, type HealthPayload, type SessionsListResponse, type ChatAttachmentPayload, type ErrorShape } from "./protocol";
+export type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting";
+export interface GatewayClientOptions {
+    /** Auth token (simple shared secret) */
+    token?: string;
+    /** Auth password (alternative) */
+    password?: string;
+    /** Device token from previous pairing */
+    deviceToken?: string;
+    /** Device identity */
+    deviceId?: string;
+    /** Auto-reconnect on disconnect (default true) */
+    autoReconnect?: boolean;
+    /** Default request timeout in ms (default 15000) */
+    defaultTimeoutMs?: number;
+    /** Client display name */
+    displayName?: string;
+    /** App version string */
+    appVersion?: string;
+    /** Platform string (e.g. 'ios', 'android') */
+    platform?: string;
+    /** Client ID for gateway registration (default: openclaw-ios) */
+    clientId?: string;
+    /** Role used at connect handshake (default: operator) */
+    role?: "operator" | "node";
+    /** Scopes used at connect handshake */
+    scopes?: string[];
+    /** Capabilities used at connect handshake */
+    caps?: string[];
+}
+type EventCallback = (payload: unknown) => void;
+type ConnectionStateCallback = (state: ConnectionState) => void;
+type ChatEventCallback = (payload: ChatEventPayload) => void;
+type AgentEventCallback = (payload: AgentEventPayload) => void;
+type HealthEventCallback = (payload: HealthPayload) => void;
+export interface ModelEntry {
+    key: string;
+    name: string;
+    input?: string;
+    contextWindow?: number;
+    local?: boolean;
+    available: boolean;
+    tags?: string[];
+    missing?: boolean;
+}
+export interface ModelsListResponse {
+    count: number;
+    models: ModelEntry[];
+}
+export declare class GatewayError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    readonly retryable?: boolean;
+    readonly retryAfterMs?: number;
+    constructor(error: ErrorShape);
+}
+export declare class GatewayClient {
+    private url;
+    private options;
+    private ws;
+    private _connectionState;
+    private requestIdCounter;
+    private pendingRequests;
+    private eventListeners;
+    private connectionStateListeners;
+    private chatEventListeners;
+    private agentEventListeners;
+    private healthEventListeners;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private intentionalClose;
+    private tickTimer;
+    private tickIntervalMs;
+    private lastTickReceived;
+    private missedTickThreshold;
+    private lastSeq;
+    private connectPromiseResolve;
+    private connectPromiseReject;
+    private challengeNonce;
+    private helloOk;
+    private deviceIdentity;
+    private awaitingPairing;
+    constructor(url: string, options?: GatewayClientOptions);
+    get connectionState(): ConnectionState;
+    get isConnected(): boolean;
+    get serverInfo(): HelloOk | null;
+    /**
+     * Ensure device identity is loaded (lazy init).
+     */
+    private ensureIdentity;
+    /**
+     * Connect to the gateway. Resolves with HelloOk on successful handshake.
+     */
+    connect(): Promise<HelloOk>;
+    /**
+     * Cleanly disconnect from the gateway.
+     */
+    disconnect(): void;
+    /**
+     * Send a request frame and wait for the matching response.
+     */
+    request<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /**
+     * Send a fire-and-forget event frame.
+     */
+    sendEvent(event: string, payload?: unknown): void;
+    /**
+     * Subscribe to a specific event name.
+     */
+    on(eventName: string, callback: EventCallback): void;
+    /**
+     * Unsubscribe from a specific event name.
+     */
+    off(eventName: string, callback: EventCallback): void;
+    /**
+     * Subscribe to connection state changes.
+     */
+    onConnectionStateChange(callback: ConnectionStateCallback): () => void;
+    /**
+     * Subscribe to chat streaming events.
+     */
+    onChatEvent(callback: ChatEventCallback): () => void;
+    /**
+     * Subscribe to agent run progress events.
+     */
+    onAgentEvent(callback: AgentEventCallback): () => void;
+    /**
+     * Subscribe to health events.
+     */
+    onHealthEvent(callback: HealthEventCallback): () => void;
+    /**
+     * Fetch chat history for a session.
+     */
+    chatHistory(sessionKey: string, options?: {
+        limit?: number;
+    }): Promise<ChatHistoryPayload>;
+    /**
+     * Send a chat message. Returns runId for tracking streaming events.
+     */
+    chatSend(sessionKey: string, message: string, options?: {
+        thinking?: string;
+        attachments?: ChatAttachmentPayload[];
+        idempotencyKey?: string;
+        timeoutMs?: number;
+    }): Promise<ChatSendResponse>;
+    /**
+     * Abort a running chat agent.
+     */
+    chatAbort(sessionKey: string, runId: string): Promise<void>;
+    /**
+     * Subscribe to chat events for a session.
+     * Note: Server may auto-subscribe on chatSend, this is a no-op for now.
+     */
+    chatSubscribe(_sessionKey: string): void;
+    /**
+     * List available sessions.
+     */
+    sessionsList(options?: {
+        limit?: number;
+        includeGlobal?: boolean;
+    }): Promise<SessionsListResponse>;
+    /**
+     * Health check — returns true if gateway responds.
+     */
+    health(timeoutMs?: number): Promise<boolean>;
+    /**
+     * List available models from the gateway.
+     */
+    modelsList(options?: {
+        timeoutMs?: number;
+    }): Promise<ModelsListResponse>;
+    private openWebSocket;
+    private handleMessage;
+    private handleResponse;
+    private handleEvent;
+    private handlePairResolved;
+    private handleChallenge;
+    private handleHelloOk;
+    private sendConnectFrame;
+    private sendConnectFrameAsync;
+    private handleConnectFailure;
+    private handleClose;
+    private scheduleReconnect;
+    private attemptReconnect;
+    private clearReconnectTimer;
+    private handleTick;
+    private startTickMonitor;
+    private clearTickTimer;
+    private sendFrame;
+    private nextRequestId;
+    private setConnectionState;
+    private emitEvent;
+}
+/**
+ * Generate a unique idempotency key for side-effecting requests.
+ */
+export declare function generateIdempotencyKey(): string;
+export {};