@ateam-ai-mobile/core 0.1.0 → 0.1.1

package/src/acs/widgetsStore.ts

@@ -0,0 +1,229 @@
+/**
+ * Tracks the user's ACS widget tiles for the home carousel. Single source of
+ * truth for /api/acs/surface state. Optimistic ops with rollback on failure
+ * — backend contract treats 404 / already:true as success (per spec), so the
+ * store mirrors that policy: a delete that the server says was already done
+ * stays removed locally.
+ *
+ * Cross-device freshness: the WS subscription (./ws) forwards `acs.artifacts`
+ * events into the applyServer* methods; hosts should also refresh() on app
+ * foreground ("WS is best-effort; the GET is the source of truth").
+ */
+
+import { create } from 'zustand';
+import {
+  listSurface,
+  deleteArtifact,
+  patchArtifact,
+  setOrder,
+  recordEvent,
+  type AcsArtifact,
+  type AcsDeleteReason,
+} from './api';
+
+interface WidgetsState {
+  /** Tiles to render in the home carousel. Order matches what /surface
+   *  returned; sort by pinOrder when present. */
+  tiles: AcsArtifact[];
+  /** True after the first /surface fetch completes (success OR empty). */
+  hydrated: boolean;
+  /** True while a /surface request is in flight. */
+  loading: boolean;
+  /** Last error string from /surface; null on success or pre-fetch. */
+  error: string | null;
+
+  /** First load — idempotent; safe to call from multiple effects. */
+  hydrate: () => Promise<void>;
+  /** Force re-fetch; call on app foreground and after destructive ops. */
+  refresh: () => Promise<void>;
+  /** Reset to empty (sign-out, env switch). */
+  clear: () => void;
+
+  /**
+   * Optimistic remove. Returns { ok: false, error } only on real network /
+   * 5xx failures — 404 and already:true rollback to ok:true per the backend
+   * contract (no existence leak; the row is gone either way).
+   */
+  remove: (artifactId: string, reason?: AcsDeleteReason) => Promise<{ ok: boolean; error?: string }>;
+
+  /** Optimistic hide (visibility → 'hidden'). Tile disappears from carousel. */
+  hide: (artifactId: string) => Promise<{ ok: boolean; error?: string }>;
+
+  /** Optimistic unhide (visibility → 'pinned'). Tile reappears in carousel. */
+  unhide: (artifactId: string) => Promise<{ ok: boolean; error?: string }>;
+
+  /** Optimistic rename. Trims input and rejects empty / overlong names locally. */
+  rename: (artifactId: string, name: string) => Promise<{ ok: boolean; error?: string }>;
+
+  /**
+   * Persist a new pin order to the server. `pinnedIds` is the visible order
+   * of currently-pinned tiles. Optimistic — applies locally first, rolls
+   * back on server rejection.
+   */
+  reorder: (pinnedIds: string[]) => Promise<{ ok: boolean; error?: string }>;
+
+  // ─── Server-driven mutations (no API call) ─────────────────────────────
+  // The WS subscription (./ws) forwards `acs.artifacts` events into these
+  // methods. They ONLY mutate local state — they DO NOT call the API (the
+  // server is the source of the event, calling back would loop).
+
+  /** WS 'updated' event — replace the tile by id (hide/unhide/rename land here). */
+  applyServerUpdate: (artifact: AcsArtifact) => void;
+  /** WS 'retired' event — remove the tile by id. */
+  applyServerRetire: (artifactId: string) => void;
+  /** WS 'order' event — re-rank tiles to match the pinned ID array. */
+  applyServerOrder: (pinnedIds: string[]) => void;
+
+  /** Fire-and-forget usage event. Caller doesn't await. */
+  track: (artifactId: string, event: 'clicked' | 'dismissed' | 'acted' | 'ignored') => void;
+}
+
+export const useWidgetsStore = create<WidgetsState>((set, get) => ({
+  tiles: [],
+  hydrated: false,
+  loading: false,
+  error: null,
+
+  hydrate: async () => {
+    if (get().hydrated || get().loading) return;
+    await get().refresh();
+  },
+
+  refresh: async () => {
+    if (get().loading) return;
+    set({ loading: true, error: null });
+    try {
+      const tiles = await listSurface('home');
+      set({ tiles, loading: false, hydrated: true });
+    } catch (e: any) {
+      set({ loading: false, hydrated: true, error: e?.message || 'Failed to load widgets' });
+    }
+  },
+
+  clear: () => set({ tiles: [], hydrated: false, loading: false, error: null }),
+
+  remove: async (artifactId, reason = 'user_long_press_delete') => {
+    const before = get().tiles;
+    // Optimistic: snap removed immediately so the user sees the tile vanish.
+    set({ tiles: before.filter(t => t.id !== artifactId) });
+
+    const result = await deleteArtifact(artifactId, reason);
+    if (result.ok) {
+      // Includes 200, 200 already:true, and 404 — all "gone server-side too".
+      return { ok: true };
+    }
+
+    // Real failure — rollback.
+    set({ tiles: before });
+    return { ok: false, error: result.error || `HTTP ${result.status}` };
+  },
+
+  hide: async (artifactId) => {
+    const before = get().tiles;
+    set({
+      tiles: before.map(t =>
+        t.id === artifactId ? { ...t, visibility: 'hidden' as const } : t,
+      ),
+    });
+    const r = await patchArtifact(artifactId, { visibility: 'hidden' }, 'user_long_press_hide');
+    if (r.ok) {
+      // If the server returned the updated artifact, sync our copy to it
+      // (covers race conditions and server-side normalisation).
+      if (r.artifact) {
+        set({
+          tiles: get().tiles.map(t => (t.id === artifactId ? { ...t, ...r.artifact! } : t)),
+        });
+      }
+      return { ok: true };
+    }
+    set({ tiles: before });
+    return { ok: false, error: r.error || `HTTP ${r.status}` };
+  },
+
+  unhide: async (artifactId) => {
+    const before = get().tiles;
+    set({
+      tiles: before.map(t =>
+        t.id === artifactId ? { ...t, visibility: 'pinned' as const } : t,
+      ),
+    });
+    const r = await patchArtifact(artifactId, { visibility: 'pinned' }, 'user_long_press_unhide');
+    if (r.ok) {
+      if (r.artifact) {
+        set({
+          tiles: get().tiles.map(t => (t.id === artifactId ? { ...t, ...r.artifact! } : t)),
+        });
+      }
+      return { ok: true };
+    }
+    set({ tiles: before });
+    return { ok: false, error: r.error || `HTTP ${r.status}` };
+  },
+
+  rename: async (artifactId, name) => {
+    // Local validation mirrors backend's 60-char cap from the spec. Keep
+    // this strict so we don't hit the API with garbage that will 400 anyway.
+    const trimmed = name.trim();
+    if (!trimmed) return { ok: false, error: 'Name cannot be empty' };
+    if (trimmed.length > 60) return { ok: false, error: 'Name must be 60 characters or less' };
+
+    const before = get().tiles;
+    set({
+      tiles: before.map(t => (t.id === artifactId ? { ...t, name: trimmed } : t)),
+    });
+    const r = await patchArtifact(artifactId, { name: trimmed }, 'user_long_press_rename');
+    if (r.ok) {
+      if (r.artifact) {
+        set({
+          tiles: get().tiles.map(t => (t.id === artifactId ? { ...t, ...r.artifact! } : t)),
+        });
+      }
+      return { ok: true };
+    }
+    set({ tiles: before });
+    return { ok: false, error: r.error || `HTTP ${r.status}` };
+  },
+
+  reorder: async (pinnedIds) => {
+    const before = get().tiles;
+    // Optimistic: assign pinOrder by position in pinnedIds. Hidden tiles
+    // are not touched. If the server rejects, we roll back to `before`.
+    const idToOrder = new Map(pinnedIds.map((id, i) => [id, i] as const));
+    set({
+      tiles: before.map(t => {
+        const o = idToOrder.get(t.id);
+        return o == null ? t : { ...t, pinOrder: o };
+      }),
+    });
+    const r = await setOrder(pinnedIds);
+    if (r.ok) return { ok: true };
+    set({ tiles: before });
+    return { ok: false, error: r.error || `HTTP ${r.status}` };
+  },
+
+  applyServerUpdate: (artifact) => {
+    set({
+      tiles: get().tiles.map(t => (t.id === artifact.id ? { ...t, ...artifact } : t)),
+    });
+  },
+
+  applyServerRetire: (artifactId) => {
+    set({ tiles: get().tiles.filter(t => t.id !== artifactId) });
+  },
+
+  applyServerOrder: (pinnedIds) => {
+    const idToOrder = new Map(pinnedIds.map((id, i) => [id, i] as const));
+    set({
+      tiles: get().tiles.map(t => {
+        const o = idToOrder.get(t.id);
+        return o == null ? t : { ...t, pinOrder: o };
+      }),
+    });
+  },
+
+  track: (artifactId, event) => {
+    // Fire-and-forget. Surface tagged so backend analytics knows where the
+    // click happened (home carousel vs library, etc.).
+    recordEvent(artifactId, event, 'home');
+  },
+}));

package/src/acs/ws.ts

@@ -0,0 +1,198 @@
+/**
+ * Long-lived WebSocket subscription to the `acs.artifacts` and
+ * `acs.home-actions` topics. Protocol (backend websocket.js):
+ *
+ *   client → server : { type: "subscribe", topic: "acs.artifacts" }
+ *   server → client : { event: "subscribed", data: { topic: "acs.artifacts" } }
+ *   server → client : { topic: "acs.artifacts", event: "updated", artifact: {...} }
+ *   server → client : { topic: "acs.artifacts", event: "retired", artifactId: "..." }
+ *   server → client : { topic: "acs.artifacts", event: "order", pinned: [...] }
+ *
+ * Events flow into the stores' applyServer* methods so we don't loop (those
+ * methods mutate local state only — no API calls).
+ *
+ * Lifecycle:
+ *   connectAcsWs(token, tenant) starts a single connection + subscribe.
+ *   On disconnect, exponential-backoff reconnect (capped). Call
+ *   notifyAcsWsForeground() from the host's AppState listener to
+ *   force-reconnect when the socket dropped while backgrounded (this module
+ *   is host-agnostic — no react-native import — so the host owns AppState).
+ *   On signout, disconnectAcsWs() closes the socket and stops reconnects.
+ *
+ * Backend's spec note: "WS is best-effort; the GET is the source of truth"
+ * — so widgetsStore.refresh() on foreground stays the safety net even when
+ * the WS is healthy. This file is the realtime cherry on top.
+ */
+
+import { getCoreWsUrl } from '../config';
+import { useWidgetsStore } from './widgetsStore';
+import { useHomeActionsStore } from './homeActionsStore';
+
+let _ws: WebSocket | null = null;
+let _wantOpen = false;
+let _retryAttempt = 0;
+let _retryTimer: ReturnType<typeof setTimeout> | null = null;
+let _token: string | null = null;
+let _tenant: string | null = null;
+
+const TOPIC = 'acs.artifacts';
+const TOPIC_HOME = 'acs.home-actions';
+const MAX_BACKOFF_MS = 30_000;
+
+function backoffMs(attempt: number): number {
+  // 0.5s, 1s, 2s, 4s, ... capped at 30s. Tiny jitter to avoid thundering herd.
+  const base = Math.min(MAX_BACKOFF_MS, 500 * Math.pow(2, attempt));
+  const jitter = Math.random() * 250;
+  return base + jitter;
+}
+
+function send(obj: any) {
+  if (_ws && _ws.readyState === 1) {
+    try { _ws.send(JSON.stringify(obj)); } catch (e) { console.warn('[acsWs] send failed', e); }
+  }
+}
+
+function handleEvent(msg: any) {
+  // The subscribe confirmation comes as { event: "subscribed", data: {...} }
+  // (no `topic` field). Real events come as { topic, event, ...payload }.
+  if (msg?.event === 'subscribed') {
+    console.log('[acsWs] subscribed to', msg?.data?.topic);
+    return;
+  }
+
+  // Home-actions feed events route to its own store.
+  if (msg?.topic === TOPIC_HOME) {
+    const home = useHomeActionsStore.getState();
+    switch (msg.event) {
+      case 'updated':
+        if (msg.action && typeof msg.action.actionId === 'string') home.applyServerUpsert(msg.action);
+        break;
+      case 'removed':
+        if (typeof msg.actionId === 'string') home.applyServerRemove(msg.actionId);
+        break;
+      case 'order':
+        if (Array.isArray(msg.order)) home.applyServerOrder(msg.order.filter((id: any) => typeof id === 'string'));
+        break;
+      case 'refreshed':
+        home.refresh();
+        break;
+      default:
+        break;
+    }
+    return;
+  }
+
+  if (msg?.topic !== TOPIC) return;
+
+  const store = useWidgetsStore.getState();
+  switch (msg.event) {
+    case 'updated':
+      if (msg.artifact && typeof msg.artifact.id === 'string') {
+        store.applyServerUpdate(msg.artifact);
+      }
+      break;
+    case 'retired':
+      if (typeof msg.artifactId === 'string') {
+        store.applyServerRetire(msg.artifactId);
+      }
+      break;
+    case 'order':
+      if (Array.isArray(msg.pinned)) {
+        store.applyServerOrder(msg.pinned.filter((id: any) => typeof id === 'string'));
+      }
+      break;
+    case 'created':
+      // Backend spec lists `created` as TODO. Until it ships, host foreground
+      // refresh catches new widgets. When it lands the WS will also fire
+      // `updated` for the new tile, which is already handled. For now, treat
+      // any inbound created the same as updated.
+      if (msg.artifact && typeof msg.artifact.id === 'string') {
+        store.applyServerUpdate(msg.artifact);
+      }
+      break;
+    default:
+      // Unknown event — ignore so we stay forward-compatible with new types.
+      break;
+  }
+}
+
+function openSocket() {
+  if (_ws) return;
+  if (!_token || !_tenant) return;
+
+  const url = `${getCoreWsUrl()}/ws?token=${encodeURIComponent(_token)}&tenant=${encodeURIComponent(_tenant)}`;
+  console.log(`[acsWs] opening`);
+  const ws = new WebSocket(url);
+  _ws = ws;
+
+  ws.onopen = () => {
+    _retryAttempt = 0;
+    send({ type: 'subscribe', topic: TOPIC });
+    send({ type: 'subscribe', topic: TOPIC_HOME });
+  };
+  ws.onmessage = (e) => {
+    try {
+      const msg = JSON.parse(typeof e.data === 'string' ? e.data : '');
+      handleEvent(msg);
+    } catch (err) {
+      // Non-JSON or malformed frame — ignore, log for debugging.
+      console.warn('[acsWs] parse failed', err);
+    }
+  };
+  ws.onerror = (e: any) => {
+    console.warn('[acsWs] error', e?.message || e);
+  };
+  ws.onclose = () => {
+    _ws = null;
+    if (!_wantOpen) return;
+    const delay = backoffMs(_retryAttempt++);
+    console.log(`[acsWs] closed; reconnecting in ${Math.round(delay)}ms (attempt ${_retryAttempt})`);
+    if (_retryTimer) clearTimeout(_retryTimer);
+    _retryTimer = setTimeout(openSocket, delay);
+  };
+}
+
+/**
+ * Call from the host's AppState listener when the app returns to the
+ * foreground — if the socket dropped while backgrounded, reconnect
+ * immediately rather than waiting out the backoff timer.
+ */
+export function notifyAcsWsForeground() {
+  if (_wantOpen && !_ws) {
+    if (_retryTimer) { clearTimeout(_retryTimer); _retryTimer = null; }
+    _retryAttempt = 0;
+    openSocket();
+  }
+}
+
+/**
+ * Start the ACS WS subscription. Idempotent — calling twice with the same
+ * token/tenant is a no-op. Call once the host says the user is signed in
+ * (JWT available).
+ */
+export function connectAcsWs(token: string, tenant: string) {
+  if (_ws && _wantOpen && _token === token && _tenant === tenant) return;
+  // Token or tenant changed → tear down + reopen.
+  if (_ws) {
+    try { _ws.close(); } catch {}
+    _ws = null;
+  }
+  _token = token;
+  _tenant = tenant;
+  _wantOpen = true;
+  openSocket();
+}
+
+/**
+ * Stop the ACS WS subscription. Call on signout / env switch.
+ */
+export function disconnectAcsWs() {
+  _wantOpen = false;
+  _token = null;
+  _tenant = null;
+  if (_retryTimer) { clearTimeout(_retryTimer); _retryTimer = null; }
+  if (_ws) {
+    try { _ws.close(); } catch {}
+    _ws = null;
+  }
+}

package/src/api/tenants.ts

@@ -0,0 +1,22 @@
+import { apiFetch } from './client';
+
+export interface TenantMembership {
+  id: string;
+  name: string;
+  role: string | null;
+}
+
+/**
+ * List the tenants the CURRENT user belongs to (GET /api/tenants/list).
+ *
+ * For consumer JWTs the backend resolves memberships by login identity
+ * (google/apple oauth or embed id) across active tenants; builder JWTs get
+ * their user-doc memberships. Returns [] when signed out or unknown.
+ *
+ * Note: switching tenant still requires a NEW JWT for that tenant (the
+ * token is tenant-scoped) — the host owns that re-auth flow.
+ */
+export async function listMyTenants(): Promise<TenantMembership[]> {
+  const data = await apiFetch<{ ok: boolean; tenants?: TenantMembership[] }>('/api/tenants/list');
+  return data.ok && Array.isArray(data.tenants) ? data.tenants : [];
+}

package/src/config.ts

@@ -41,17 +41,28 @@ export interface AdasUser {
   actorId: string;
   name?: string;
   email?: string;
+  /** Roles from the host's identity (e.g. JWT claims) — forwarded to plugins
+   *  as PluginContext.user.roles. */
+  roles?: string[];
 }
 
+/** A URL that is either static or resolved on each read. Hosts with a
+ *  runtime env switcher (dev/prod) pass a getter so the SDK always sees the
+ *  currently-selected backend without re-calling initAdas(). */
+export type UrlSource = string | (() => string);
+
 export interface AdasConfig {
-  /** Core API base URL, e.g. https://app.ateam-ai.com */
-  coreUrl: string;
+  /** Core API base URL, e.g. https://app.ateam-ai.com. Pass a getter to
+   *  support a runtime env switch without re-initializing. */
+  coreUrl: UrlSource;
   /** Voice service base URL (optional — only voice features need it). */
-  voiceUrl?: string;
+  voiceUrl?: UrlSource;
   tokenProvider: TokenProvider;
-  /** Tenant slug — informational/telemetry only. The backend derives the
-   *  tenant from the JWT; the SDK never sends a tenant header. */
-  tenant?: string;
+  /** Tenant slug — used for plugin URL resolution and voice, never sent as a
+   *  header (the backend derives the tenant from the JWT). Pass a getter when
+   *  the host resolves the tenant after startup (storage hydration, runtime
+   *  tenant switch). */
+  tenant?: string | (() => string);
   /** Current end user as known to the host. actorId is used as the chat
    *  reply context; without it, replies route to 'unknown'. */
   getUser?: () => AdasUser | null;
@@ -81,8 +92,12 @@ export function getConfig(): AdasConfig {
   return _config;
 }
 
+function resolveUrl(src: UrlSource): string {
+  return (typeof src === 'function' ? src() : src).replace(/\/$/, '');
+}
+
 export function getCoreApiUrl(): string {
-  return getConfig().coreUrl.replace(/\/$/, '');
+  return resolveUrl(getConfig().coreUrl);
 }
 
 export function getCoreWsUrl(): string {
@@ -92,11 +107,12 @@ export function getCoreWsUrl(): string {
 export function getVoiceApiUrl(): string {
   const url = getConfig().voiceUrl;
   if (!url) throw new Error('[adas] voiceUrl not configured');
-  return url.replace(/\/$/, '');
+  return resolveUrl(url);
 }
 
 export function getTenant(): string {
-  return getConfig().tenant || '';
+  const t = getConfig().tenant;
+  return (typeof t === 'function' ? t() : t) || '';
 }
 
 export function getUser(): AdasUser | null {

package/src/index.ts

@@ -41,6 +41,10 @@ export {
   unwrapMcpResult,
 } from './api/mcp';
 
+// Tenant memberships
+export { listMyTenants } from './api/tenants';
+export type { TenantMembership } from './api/tenants';
+
 // Chat
 export {
   useChatStore,
@@ -70,3 +74,36 @@ export type { BufferedCommand } from './utils/emitter';
 
 // Theme tokens
 export { colors, ada, spacing, fontSize, borderRadius } from './theme/tokens';
+
+// ACS (home widgets + top-actions feed)
+export {
+  listSurface,
+  listMadeForYou,
+  deleteArtifact,
+  patchArtifact,
+  setOrder,
+  recordEvent,
+  listHomeActions,
+  patchHomeAction,
+  setHomeActionOrder,
+} from './acs/api';
+export type {
+  AcsArtifact,
+  AcsSurface,
+  AcsEvent,
+  AcsDeleteReason,
+  AcsPatchReason,
+  DeleteResult,
+  PatchResult,
+  HomeAction,
+  HomeActionLeaf,
+  HomeActionReason,
+} from './acs/api';
+export { useWidgetsStore } from './acs/widgetsStore';
+export { useHomeActionsStore } from './acs/homeActionsStore';
+export { connectAcsWs, disconnectAcsWs, notifyAcsWsForeground } from './acs/ws';
+export {
+  setAcsReachabilityReporter,
+  setAcsCacheStorage,
+} from './acs/providers';
+export type { AcsReachabilityReporter, AcsKvStorage } from './acs/providers';