botschat 0.1.12 → 0.1.14

package/README.md

@@ -117,24 +117,17 @@ Clone, install, and run the server on your machine. Wrangler uses [Miniflare](ht
 git clone https://github.com/botschat-app/botsChat.git
 cd botsChat
 npm install
-# One-command startup: build web → migrate D1 → start on 0.0.0.0:8787
 ./scripts/dev.sh
 ```
 
-Or step by step:
-
-```bash
-npm run build -w packages/web                          # Build the React frontend
-npm run db:migrate                                     # Apply D1 migrations (local)
-npx wrangler dev --config wrangler.toml --ip 0.0.0.0   # Start on port 8787
-```
-
-Open `http://localhost:8787` in your browser.
+One command does everything: build frontend → migrate database → start server → launch Mock AI → open browser with auto-login. No environment variables to set, no separate terminals to manage.
 
 Other dev commands:
 
 ```bash
-./scripts/dev.sh reset     # Nuke local DB → re-migrate → start
+./scripts/dev.sh reset     # Nuke local DB → re-migrate → start full dev env
+./scripts/dev.sh server    # Server only (no mock AI, no browser)
+./scripts/dev.sh mock      # Start mock OpenClaw standalone (foreground)
 ./scripts/dev.sh migrate   # Only run D1 migrations
 ./scripts/dev.sh build     # Only build web frontend
 ./scripts/dev.sh sync      # Sync plugin to remote OpenClaw host + restart gateway
@@ -282,16 +275,19 @@ openclaw plugins remove botschat
 
 ## Development
 
-### Build the plugin
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full development guide — local setup, Mock OpenClaw for testing, architecture principles, WebSocket protocol, database migrations, and more.
+
+### Quick Start
 
 ```bash
-npm run build:plugin
+./scripts/dev.sh         # Build + migrate + start server + mock AI + open browser
 ```
 
-### Type-check everything
+### Build
 
 ```bash
-npm run typecheck
+npm run build -w packages/web      # Build frontend
+npm run build -w packages/plugin   # Build plugin
 ```
 
 

package/migrations/0012_push_tokens.sql

@@ -0,0 +1,11 @@
+-- Push notification device tokens (FCM registration tokens)
+CREATE TABLE IF NOT EXISTS push_tokens (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token TEXT NOT NULL,
+  platform TEXT NOT NULL CHECK (platform IN ('web', 'ios', 'android')),
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE(user_id, token)
+);
+CREATE INDEX IF NOT EXISTS idx_push_tokens_user ON push_tokens(user_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botschat",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "A self-hosted chat interface for OpenClaw AI agents",
   "workspaces": [
     "packages/*"
@@ -20,6 +20,10 @@
     "ios:open": "npx cap open ios",
     "ios:run": "npx cap run ios",
     "ios:sync": "npx cap sync ios",
+    "android:build": "npm run build -w packages/web && npx cap sync android",
+    "android:open": "npx cap open android",
+    "android:run": "npx cap run android",
+    "android:sync": "npx cap sync android",
     "test:e2e": "npx tsx scripts/verify-e2e.ts && npx tsx packages/e2e-crypto/e2e-crypto.test.ts",
     "test:e2e-db": "npx tsx scripts/verify-e2e-db.ts"
   },
@@ -58,11 +62,13 @@
     "wrangler": "^3.100.0"
   },
   "dependencies": {
+    "@capacitor/android": "^8.1.0",
     "@capacitor/app": "^8.0.1",
     "@capacitor/core": "^8.1.0",
     "@capacitor/haptics": "^8.0.0",
     "@capacitor/ios": "^8.1.0",
     "@capacitor/keyboard": "^8.0.0",
+    "@capacitor/push-notifications": "^8.0.1",
     "@capacitor/splash-screen": "^8.0.1",
     "@capacitor/status-bar": "^8.0.1",
     "@capgo/capacitor-social-login": "^8.3.1",

package/packages/api/src/do/connection-do.ts

@@ -1,5 +1,7 @@
 import type { Env } from "../env.js";
 import { verifyToken, getJwtSecret, signMediaUrl } from "../utils/auth.js";
+import { getFcmAccessToken, sendPushNotification } from "../utils/fcm.js";
+import { sendApnsNotification, type ApnsConfig } from "../utils/apns.js";
 import { generateId as generateIdUtil } from "../utils/id.js";
 import { randomUUID } from "../utils/uuid.js";
 
@@ -27,6 +29,9 @@ export class ConnectionDO implements DurableObject {
   /** Pending resolve for a real-time task.scan.request → task.scan.result round-trip. */
   private pendingScanResolve: ((tasks: Array<Record<string, unknown>>) => void) | null = null;
 
+  /** Browser sessions that report themselves in foreground (push notifications are suppressed). */
+  private foregroundSessions = new Set<string>();
+
   constructor(state: DurableObjectState, env: Env) {
     this.state = state;
     this.env = env;
@@ -115,7 +120,10 @@ export class ConnectionDO implements DurableObject {
         JSON.stringify({ type: "openclaw.disconnected" }),
       );
     }
-    // No explicit cleanup needed — the runtime manages the socket list
+    // Clean up foreground tracking for browser sessions
+    if (tag?.startsWith("browser:")) {
+      this.foregroundSessions.delete(tag);
+    }
   }
 
   /** Called when a WebSocket encounters an error. */
@@ -210,6 +218,9 @@ export class ConnectionDO implements DurableObject {
         // After auth, request task scan + models list from the plugin
         ws.send(JSON.stringify({ type: "task.scan.request" }));
         ws.send(JSON.stringify({ type: "models.request" }));
+        // Send notification preview preference to plugin
+        const notifyPreview = await this.getNotifyPreviewSetting(userId);
+        ws.send(JSON.stringify({ type: "settings.notifyPreview", enabled: notifyPreview }));
         // Notify all browser clients that OpenClaw is now connected
         this.broadcastToBrowsers(
           JSON.stringify({ type: "connection.status", openclawConnected: true, defaultModel: this.defaultModel, models: this.cachedModels }),
@@ -308,11 +319,24 @@ export class ConnectionDO implements DurableObject {
       await this.handleJobUpdate(msg);
     }
 
-    // Forward all messages to browser clients
+    // Forward all messages to browser clients (strip notifyPreview — plaintext
+    // must not be relayed to browser WebSockets; browsers decrypt locally)
     if (msg.type === "agent.text") {
       console.log(`[DO] Forwarding agent.text to browsers: encrypted=${msg.encrypted}, messageId=${msg.messageId}, textLen=${typeof msg.text === "string" ? msg.text.length : "?"}`);
     }
-    this.broadcastToBrowsers(JSON.stringify(msg));
+    const { notifyPreview: _stripped, ...msgForBrowser } = msg;
+    this.broadcastToBrowsers(JSON.stringify(msgForBrowser));
+
+    // Send push notification if no browser session is in foreground
+    if (
+      (msg.type === "agent.text" || msg.type === "agent.media" || msg.type === "agent.a2ui") &&
+      this.foregroundSessions.size === 0 &&
+      (this.env.FCM_SERVICE_ACCOUNT_JSON || this.env.APNS_AUTH_KEY)
+    ) {
+      this.sendPushNotifications(msg).catch((err) => {
+        console.error("[DO] Push notification failed:", err);
+      });
+    }
   }
 
   private async handleBrowserMessage(
@@ -370,6 +394,18 @@ export class ConnectionDO implements DurableObject {
       return;
     }
 
+    // Handle foreground/background state tracking for push notifications
+    if (msg.type === "foreground.enter") {
+      const tag = attachment.tag;
+      if (tag) this.foregroundSessions.add(tag);
+      return;
+    }
+    if (msg.type === "foreground.leave") {
+      const tag = attachment.tag;
+      if (tag) this.foregroundSessions.delete(tag);
+      return;
+    }
+
     // Persist user messages to D1
     if (msg.type === "user.message") {
       console.log("[DO] User inbound:", JSON.stringify({
@@ -516,6 +552,24 @@ export class ConnectionDO implements DurableObject {
 
   // ---- Helpers ----
 
+  /** Read the user's notifyPreview preference from D1 settings_json. */
+  private async getNotifyPreviewSetting(userId?: string | null): Promise<boolean> {
+    const uid = userId ?? await this.state.storage.get<string>("userId");
+    if (!uid) return false;
+    try {
+      const row = await this.env.DB.prepare(
+        "SELECT settings_json FROM users WHERE id = ?",
+      ).bind(uid).first<{ settings_json: string }>();
+      if (row?.settings_json) {
+        const settings = JSON.parse(row.settings_json);
+        return settings.notifyPreview === true;
+      }
+    } catch (err) {
+      console.error("[DO] Failed to read notifyPreview setting:", err);
+    }
+    return false;
+  }
+
   /** Restore cachedModels and defaultModel from durable storage if in-memory cache is empty. */
   private async ensureCachedModels(): Promise<void> {
     if (this.cachedModels.length > 0) return;
@@ -564,6 +618,125 @@ export class ConnectionDO implements DurableObject {
     }
   }
 
+  // ---- Push notifications ----
+
+  /**
+   * Send push notifications to all of the user's registered devices.
+   * Called when an agent message arrives and no browser session is in foreground.
+   *
+   * iOS tokens go directly to APNs (Capacitor returns raw APNs device tokens).
+   * Web/Android tokens go through FCM HTTP v1 API.
+   */
+  private async sendPushNotifications(msg: Record<string, unknown>): Promise<void> {
+    const userId = await this.state.storage.get<string>("userId");
+    if (!userId) return;
+
+    const { results } = await this.env.DB.prepare(
+      "SELECT id, token, platform FROM push_tokens WHERE user_id = ?",
+    )
+      .bind(userId)
+      .all<{ id: string; token: string; platform: string }>();
+
+    if (!results || results.length === 0) return;
+    console.log(`[DO] Push: ${results.length} token(s) for ${userId} (ios: ${results.filter((r) => r.platform === "ios").length})`);
+
+    const data: Record<string, string> = {
+      type: msg.type as string,
+      sessionKey: (msg.sessionKey as string) ?? "",
+      messageId: (msg.messageId as string) ?? "",
+      encrypted: msg.encrypted ? "1" : "0",
+    };
+
+    let notifBody = "New message";
+    if (msg.type === "agent.text") {
+      data.text = (msg.text as string) ?? "";
+      if (msg.encrypted && typeof msg.notifyPreview === "string" && msg.notifyPreview) {
+        const preview = msg.notifyPreview as string;
+        notifBody = preview.length > 100 ? preview.slice(0, 100) + "…" : preview;
+      } else if (!msg.encrypted && data.text) {
+        notifBody = data.text.length > 100 ? data.text.slice(0, 100) + "…" : data.text;
+      } else if (msg.encrypted) {
+        notifBody = "New encrypted message";
+      }
+    } else if (msg.type === "agent.media") {
+      data.text = (msg.caption as string) || "";
+      data.mediaUrl = (msg.mediaUrl as string) ?? "";
+      notifBody = data.text || "Sent a media file";
+    } else if (msg.type === "agent.a2ui") {
+      data.text = "New interactive message";
+      notifBody = "New interactive message";
+    }
+
+    const iosTokens = results.filter((r) => r.platform === "ios");
+    const androidTokens = results.filter((r) => r.platform === "android");
+    const webTokens = results.filter((r) => r.platform === "web");
+    const invalidTokenIds: string[] = [];
+    const notification = { title: "BotsChat", body: notifBody };
+
+    // iOS: send via APNs directly (Capacitor registers raw APNs device tokens)
+    if (iosTokens.length > 0 && this.env.APNS_AUTH_KEY) {
+      const apnsConfig: ApnsConfig = {
+        authKey: this.env.APNS_AUTH_KEY,
+        keyId: this.env.APNS_KEY_ID ?? "",
+        teamId: this.env.APNS_TEAM_ID ?? "",
+        bundleId: "app.botschat.console",
+      };
+      await Promise.allSettled(
+        iosTokens.map(async (row) => {
+          const ok = await sendApnsNotification({
+            config: apnsConfig,
+            deviceToken: row.token,
+            title: "BotsChat",
+            body: notifBody,
+            data,
+          });
+          if (!ok) invalidTokenIds.push(row.id);
+        }),
+      );
+    }
+
+    // Android: FCM with notification payload (data-only is silent in background)
+    if (androidTokens.length > 0 && this.env.FCM_SERVICE_ACCOUNT_JSON) {
+      const accessToken = await getFcmAccessToken(this.env.FCM_SERVICE_ACCOUNT_JSON);
+      const projectId = this.env.FIREBASE_PROJECT_ID ?? "botschat-130ff";
+      await Promise.allSettled(
+        androidTokens.map(async (row) => {
+          const ok = await sendPushNotification({
+            accessToken,
+            projectId,
+            fcmToken: row.token,
+            data,
+            notification,
+          });
+          if (!ok) invalidTokenIds.push(row.id);
+        }),
+      );
+    }
+
+    // Web: FCM data-only (Service Worker decrypts + shows notification)
+    if (webTokens.length > 0 && this.env.FCM_SERVICE_ACCOUNT_JSON) {
+      const accessToken = await getFcmAccessToken(this.env.FCM_SERVICE_ACCOUNT_JSON);
+      const projectId = this.env.FIREBASE_PROJECT_ID ?? "botschat-130ff";
+      await Promise.allSettled(
+        webTokens.map(async (row) => {
+          const ok = await sendPushNotification({
+            accessToken,
+            projectId,
+            fcmToken: row.token,
+            data,
+          });
+          if (!ok) invalidTokenIds.push(row.id);
+        }),
+      );
+    }
+
+    // Clean up invalid/expired tokens
+    for (const id of invalidTokenIds) {
+      await this.env.DB.prepare("DELETE FROM push_tokens WHERE id = ?").bind(id).run();
+      console.log(`[DO] Removed invalid push token: ${id}`);
+    }
+  }
+
   // ---- Media caching ----
 
   // ---- SSRF protection ----

package/packages/api/src/env.ts

@@ -12,4 +12,12 @@ export type Env = {
   PUBLIC_URL?: string;
   /** Secret for dev-token auth bypass (automated testing). Endpoint is 404 when unset. */
   DEV_AUTH_SECRET?: string;
+  /** FCM Service Account JSON for push notifications (stored as secret via `wrangler secret put`). */
+  FCM_SERVICE_ACCOUNT_JSON?: string;
+  /** APNs Auth Key (.p8 content) for direct iOS push via APNs HTTP/2 API. */
+  APNS_AUTH_KEY?: string;
+  /** APNs Key ID (from Apple Developer portal, e.g. "3Q4V693LW4"). */
+  APNS_KEY_ID?: string;
+  /** Apple Developer Team ID (e.g. "C5N5PPC329"). */
+  APNS_TEAM_ID?: string;
 };

package/packages/api/src/index.ts

@@ -11,6 +11,7 @@ import { models } from "./routes/models.js";
 import { pairing } from "./routes/pairing.js";
 import { sessions } from "./routes/sessions.js";
 import { upload } from "./routes/upload.js";
+import { push } from "./routes/push.js";
 import { setup } from "./routes/setup.js";
 import { devAuth } from "./routes/dev-auth.js";
 
@@ -25,7 +26,8 @@ const PRODUCTION_ORIGINS = [
   "https://botschat.app",
   "https://botschat-api.auxtenwpc.workers.dev",
   "capacitor://localhost",  // iOS Capacitor app
-  "http://localhost",       // Android Capacitor app
+  "http://localhost",       // Android Capacitor app (http scheme)
+  "https://localhost",      // Android Capacitor app (https scheme)
 ];
 
 // CORS and security headers — skip for WebSocket upgrade requests
@@ -122,7 +124,7 @@ protectedApp.get("/me", async (c) => {
 
 protectedApp.patch("/me", async (c) => {
   const userId = c.get("userId");
-  const body = await c.req.json<{ defaultModel?: string }>();
+  const body = await c.req.json<{ defaultModel?: string; notifyPreview?: boolean }>();
 
   // defaultModel is not stored in D1 — get/set only via plugin (connection.status / push).
   const existing = await c.env.DB.prepare(
@@ -133,7 +135,11 @@ protectedApp.patch("/me", async (c) => {
 
   const settings = JSON.parse(existing?.settings_json || "{}");
   delete settings.defaultModel;
-  // Persist other settings (if any) to D1; defaultModel is never written.
+
+  if (body.notifyPreview !== undefined) {
+    settings.notifyPreview = body.notifyPreview;
+  }
+
   await c.env.DB.prepare(
     "UPDATE users SET settings_json = ? WHERE id = ?",
   )
@@ -159,6 +165,25 @@ protectedApp.patch("/me", async (c) => {
     }
   }
 
+  if (body.notifyPreview !== undefined) {
+    try {
+      const doId = c.env.CONNECTION_DO.idFromName(userId);
+      const stub = c.env.CONNECTION_DO.get(doId);
+      await stub.fetch(
+        new Request("https://internal/send", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            type: "settings.notifyPreview",
+            enabled: body.notifyPreview,
+          }),
+        }),
+      );
+    } catch (err) {
+      console.error("Failed to push notifyPreview to OpenClaw:", err);
+    }
+  }
+
   const outSettings = { ...settings };
   delete outSettings.defaultModel;
   return c.json({ ok: true, settings: outSettings });
@@ -275,6 +300,7 @@ protectedApp.route("/channels/:channelId/tasks/:taskId/jobs", jobs);
 // Nested session routes under /api/channels/:channelId/sessions
 protectedApp.route("/channels/:channelId/sessions", sessions);
 protectedApp.route("/pairing-tokens", pairing);
+protectedApp.route("/push-tokens", push);
 protectedApp.route("/upload", upload);
 
 // ---- Media serving route (signed URL or Bearer auth) ----

package/packages/api/src/routes/auth.ts

@@ -155,11 +155,6 @@ async function handleFirebaseAuth(c: {
     return c.json({ error: msg }, 401);
   }
 
-  const email = firebaseUser.email?.toLowerCase();
-  if (!email) {
-    return c.json({ error: "Account has no email address" }, 400);
-  }
-
   const firebaseUid = firebaseUser.sub;
   // Determine provider from Firebase token (google.com, github.com, etc.)
   const signInProvider = firebaseUser.firebase?.sign_in_provider ?? "unknown";
@@ -167,7 +162,21 @@ async function handleFirebaseAuth(c: {
     ? "google"
     : signInProvider.includes("github")
       ? "github"
-      : signInProvider;
+      : signInProvider.includes("apple")
+        ? "apple"
+        : signInProvider;
+
+  // Apple Sign-In may hide the user's real email; generate a short placeholder
+  let email = firebaseUser.email?.toLowerCase() || null;
+  if (!email && authProvider === "apple") {
+    const hash = Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(firebaseUid))))
+      .slice(0, 6).map(b => b.toString(16).padStart(2, "0")).join("");
+    email = `apple_${hash}@privaterelay.appleid.com`;
+  }
+  if (!email) {
+    return c.json({ error: "Account has no email address" }, 400);
+  }
+
   const displayName = firebaseUser.name ?? email.split("@")[0];
 
   // 2. Look up existing user by firebase_uid first, then by email
@@ -241,6 +250,7 @@ async function handleFirebaseAuth(c: {
 auth.post("/firebase", (c) => handleFirebaseAuth(c));
 auth.post("/google", (c) => handleFirebaseAuth(c));
 auth.post("/github", (c) => handleFirebaseAuth(c));
+auth.post("/apple", (c) => handleFirebaseAuth(c));
 
 /**
  * POST /api/auth/dev-login — development-only passwordless login by email.
@@ -307,6 +317,7 @@ auth.get("/config", (c) => {
     emailEnabled: isDev,
     googleEnabled: !!c.env.FIREBASE_PROJECT_ID,
     githubEnabled: !!c.env.FIREBASE_PROJECT_ID,
+    appleEnabled: !!c.env.FIREBASE_PROJECT_ID,
   });
 });
 
@@ -342,4 +353,26 @@ auth.get("/me", async (c) => {
   });
 });
 
+/** DELETE /api/auth/account — permanently delete the authenticated user's account and all data */
+auth.delete("/account", async (c) => {
+  const userId = c.get("userId" as never) as string;
+  if (!userId) return c.json({ error: "Unauthorized" }, 401);
+
+  // Delete all user media from R2
+  const prefix = `${userId}/`;
+  let cursor: string | undefined;
+  do {
+    const listed = await c.env.MEDIA.list({ prefix, cursor });
+    if (listed.objects.length > 0) {
+      await Promise.all(listed.objects.map(obj => c.env.MEDIA.delete(obj.key)));
+    }
+    cursor = listed.truncated ? listed.cursor : undefined;
+  } while (cursor);
+
+  // Delete user record — all related tables use ON DELETE CASCADE
+  await c.env.DB.prepare("DELETE FROM users WHERE id = ?").bind(userId).run();
+
+  return c.json({ ok: true });
+});
+
 export { auth };

package/packages/api/src/routes/push.ts

@@ -0,0 +1,52 @@
+import { Hono } from "hono";
+import type { Env } from "../env.js";
+import { generateId } from "../utils/id.js";
+
+const push = new Hono<{ Bindings: Env; Variables: { userId: string } }>();
+
+/** POST /api/push-tokens — register or update a device push token */
+push.post("/", async (c) => {
+  const userId = c.get("userId");
+  const { token, platform } = await c.req.json<{ token: string; platform: string }>();
+
+  if (!token || !platform) {
+    return c.json({ error: "Missing token or platform" }, 400);
+  }
+  if (!["web", "ios", "android"].includes(platform)) {
+    return c.json({ error: "Invalid platform (web | ios | android)" }, 400);
+  }
+
+  const id = generateId("pt_");
+  const now = Math.floor(Date.now() / 1000);
+
+  // Upsert: if the same user+token already exists, update the timestamp
+  await c.env.DB.prepare(
+    `INSERT INTO push_tokens (id, user_id, token, platform, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(user_id, token) DO UPDATE SET platform = excluded.platform, updated_at = excluded.updated_at`,
+  )
+    .bind(id, userId, token, platform, now, now)
+    .run();
+
+  return c.json({ ok: true, id }, 201);
+});
+
+/** DELETE /api/push-tokens — unregister a device push token */
+push.delete("/", async (c) => {
+  const userId = c.get("userId");
+  const { token } = await c.req.json<{ token: string }>().catch(() => ({ token: "" }));
+
+  if (!token) {
+    return c.json({ error: "Missing token" }, 400);
+  }
+
+  await c.env.DB.prepare(
+    "DELETE FROM push_tokens WHERE user_id = ? AND token = ?",
+  )
+    .bind(userId, token)
+    .run();
+
+  return c.json({ ok: true });
+});
+
+export { push };