@ateam-ai-mobile/core 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -66,16 +66,30 @@ 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(). */
+type UrlSource = string | (() => string);
 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;
+    /** Consumer-auth base URL, e.g. https://consumer-auth.ateam-ai.com. Only
+     *  needed for `switchTenant()` (re-scoping the session to another tenant
+     *  the user belongs to). */
+    consumerAuthUrl?: 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;
@@ -83,6 +97,24 @@ interface AdasConfig {
      *  survive app restarts. No-op when omitted (previews live in memory for
      *  the session only). @ateam-ai-mobile/ui ships an Expo/RN implementation. */
     attachmentCache?: AttachmentCache;
+    /** Called by `switchTenant()` with the freshly-minted session for the
+     *  target tenant. The host MUST persist it here (store the new JWT so
+     *  tokenProvider.getToken() returns it, and update the active tenant) —
+     *  the SDK never stores credentials. Awaited before the chat reconnects. */
+    onSession?: (session: AdasSession) => void | Promise<void>;
+}
+/** A tenant-scoped session minted by the platform (e.g. via switchTenant). */
+interface AdasSession {
+    jwt: string;
+    tenant: {
+        id: string;
+        name: string;
+    };
+    actor: {
+        id: string;
+        email: string | null;
+        roles: string[];
+    };
 }
 /** Register the SDK configuration. Call once at app start, before any other
  *  SDK API. Calling again replaces the config (e.g. env switch) — combine
@@ -93,6 +125,7 @@ declare function getConfig(): AdasConfig;
 declare function getCoreApiUrl(): string;
 declare function getCoreWsUrl(): string;
 declare function getVoiceApiUrl(): string;
+declare function getConsumerAuthApiUrl(): string;
 declare function getTenant(): string;
 declare function getUser(): AdasUser | null;
 declare function getToken(): string | null;
@@ -142,6 +175,35 @@ declare function postCommandResult(correlationId: string, result: any, error?: s
  */
 declare function unwrapMcpResult(result: any): any;
 
+interface TenantMembership {
+    id: string;
+    name: string;
+    role: string | null;
+}
+/**
+ * List the tenants the CURRENT user belongs to (GET /api/tenants/list).
+ *
+ * The list is membership-scoped: for consumer JWTs the backend returns ONLY
+ * tenants where the user's login identity (google/apple oauth or embed id)
+ * has an active actor; builder JWTs get their user-doc memberships. It never
+ * leaks the full tenant list. Returns [] when signed out or unknown.
+ */
+declare function listMyTenants(): Promise<TenantMembership[]>;
+/**
+ * Re-scope the whole session to another tenant the user already belongs to.
+ *
+ * The backend treats the JWT tenant claim as the sole source of truth, so
+ * switching = minting a fresh JWT for the target tenant's actor. The SDK
+ * owns the call (POST consumer-auth /platform/consumer/switch-tenant, authed
+ * by the current token); the HOST persists the new session via
+ * `config.onSession` (the SDK never stores credentials). The chat stream is
+ * then torn down and cleared so it reconnects against the new tenant.
+ *
+ * Requires `consumerAuthUrl` and `onSession` in the initAdas() config.
+ * Throws on any non-OK response (e.g. not a member of the target tenant).
+ */
+declare function switchTenant(targetTenantId: string): Promise<AdasSession>;
+
 interface ToolCall {
     name: string;
     args: Record<string, unknown>;
@@ -386,4 +448,310 @@ declare const borderRadius: {
     readonly full: 9999;
 };
 
-export { type AdasConfig, type AdasUser, type AttachmentCache, type AttachmentPreview, type BufferedCommand, type JobProgress, type Message, type MessageAttachment, type OutgoingAttachment, PluginCommandEmitter, type RefreshOutcome, TABLE_BLOCK_CLOSE, TABLE_BLOCK_OPEN, type TokenProvider, type ToolCall, type UIAction, ada, apiFetch, apiFetchRaw, blocksToText, borderRadius, closeChatStream, colors, connectorCall, fontSize, getConfig, getCoreApiUrl, getCoreWsUrl, getTenant, getToken, getUser, getVoiceApiUrl, initAdas, isAdasInitialized, mcpFetch, mcpToolCall, pluginCommandEmitter, postCommandResult, spacing, unwrapMcpResult, useChatStore };
+/**
+ * Client for Core's /api/acs/* proxy → ACS service. Powers the "widgets"
+ * surface on home: AI-generated artifacts that render as carousel tiles and
+ * full-screen interactive panels via the bundleUrl — plus the home
+ * "top actions" feed.
+ *
+ * Endpoints:
+ *   POST   /api/acs/surface           — list active artifacts for a surface
+ *   POST   /api/acs/event             — usage tracking (clicked/dismissed/etc.)
+ *   GET    /api/acs/made-for-you      — full library, all lifecycle stages
+ *   DELETE /api/acs/artifacts/{id}    — user-initiated retire (idempotent)
+ *   PATCH  /api/acs/artifacts/{id}    — visibility + rename
+ *   PUT    /api/acs/order             — drag-reorder
+ *   GET    /api/acs/home-actions      — top-actions feed (+ PATCH/PUT order)
+ *   WS topics acs.artifacts / acs.home-actions — cross-device sync (see ./ws)
+ */
+interface AcsArtifact {
+    id: string;
+    name: string;
+    description?: string;
+    iconHint?: string;
+    manifest?: Record<string, any>;
+    bundleUrl: string;
+    version: number;
+    provenance?: Record<string, any>;
+    kind?: 'user' | 'featured';
+    visibility?: 'pinned' | 'hidden';
+    pinOrder?: number;
+    canDelete?: boolean;
+    canRename?: boolean;
+    canHide?: boolean;
+    previewMode?: 'live' | 'snapshot' | 'none';
+    previewUrl?: string;
+}
+type AcsSurface = 'home' | 'library' | (string & {});
+type AcsEvent = 'clicked' | 'dismissed' | 'acted' | 'ignored';
+type AcsDeleteReason = 'user_long_press_delete' | 'user_swipe_delete' | 'user_bulk_delete' | (string & {});
+type AcsPatchReason = 'user_long_press_hide' | 'user_long_press_unhide' | 'user_long_press_rename' | (string & {});
+/**
+ * List artifacts surfaced for the given surface name. Returns [] on error
+ * (network, auth, or empty result) — callers shouldn't have to distinguish.
+ * Use surface="home" for the carousel.
+ */
+declare function listSurface(surface: AcsSurface, context?: Record<string, any>): Promise<AcsArtifact[]>;
+/**
+ * Full library — every artifact across all lifecycle stages. Used by a
+ * Library screen's Yours + Hidden sections.
+ */
+declare function listMadeForYou(): Promise<AcsArtifact[]>;
+interface DeleteResult {
+    ok: boolean;
+    /** True when the server already had this artifact retired. Treat as success. */
+    already?: boolean;
+    /** True for HTTP 404 — artifact gone or never owned by caller. Treat as success
+     *  (remove from local state) per the backend's contract: no existence leak. */
+    notFound?: boolean;
+    /** HTTP status returned by the server. */
+    status: number;
+    error?: string;
+}
+/**
+ * Retire a user widget. Per backend contract:
+ *   200 ok                → success
+ *   200 ok + already:true → idempotent, treat as success
+ *   404                   → already gone or not owned, treat as success
+ *   5xx / network         → real failure, caller should rollback optimistic remove
+ */
+declare function deleteArtifact(artifactId: string, reason?: AcsDeleteReason): Promise<DeleteResult>;
+interface PatchResult {
+    ok: boolean;
+    /** Updated tile when the server returns the new state. */
+    artifact?: AcsArtifact;
+    already?: boolean;
+    notFound?: boolean;
+    status: number;
+    error?: string;
+}
+/**
+ * Update an artifact's visibility (hide/unhide) and/or name (rename). One
+ * call covers both because backend offers a single PATCH endpoint with
+ * optional fields. At least one of visibility/name must be provided.
+ *
+ * Per backend contract (mirrors DELETE semantics):
+ *   200 ok                → success
+ *   200 ok + already:true → idempotent no-op, treat as success
+ *   404                   → not found / not owned, treat as success
+ *   400 / 403             → real failure, surface to user
+ *   5xx / network         → real failure, caller should rollback
+ */
+declare function patchArtifact(artifactId: string, body: {
+    visibility?: 'pinned' | 'hidden';
+    name?: string;
+}, reason: AcsPatchReason): Promise<PatchResult>;
+/**
+ * Persist a new pin order. Body lists currently-pinned artifact IDs in the
+ * new visual order; server validates ownership + pinned state of each ID.
+ *
+ * Returns { ok: false, error } on failure. 400 means the array contained
+ * an id that's not owned or not pinned — caller should refetch /surface
+ * and re-render rather than fight the server.
+ */
+declare function setOrder(pinned: string[]): Promise<{
+    ok: boolean;
+    status: number;
+    error?: string;
+}>;
+/**
+ * Record a usage event. Fire-and-forget — never throws, never blocks the UI.
+ * Use surface to tell the backend which surface the event came from
+ * (e.g. 'home' for the carousel).
+ */
+declare function recordEvent(artifactId: string, event: AcsEvent, surface?: AcsSurface): Promise<void>;
+type HomeActionLeaf = {
+    type: 'send_message';
+    prompt: string;
+    skillSlug?: string;
+} | {
+    type: 'open_widget';
+    artifactId: string;
+} | {
+    type: string;
+    [k: string]: any;
+};
+interface HomeAction {
+    actionId: string;
+    pinOrder?: number;
+    title: string;
+    subtitle?: string;
+    icon?: string;
+    action: HomeActionLeaf;
+    source?: 'curated' | 'pinned_by_user' | 'skill_authored' | (string & {});
+    canDismiss?: boolean;
+    canPin?: boolean;
+    pinned?: boolean;
+}
+/** List the home top-actions feed. Returns [] on any error. */
+declare function listHomeActions(): Promise<HomeAction[]>;
+type HomeActionReason = 'user_pin' | 'user_unpin' | 'user_dismiss' | 'user_drag_reorder' | (string & {});
+/** Pin/unpin or dismiss a card. 200 already / 404 both count as success. */
+declare function patchHomeAction(actionId: string, body: {
+    pinned?: boolean;
+    dismissed?: boolean;
+}, reason: HomeActionReason): Promise<{
+    ok: boolean;
+    action?: HomeAction;
+    status: number;
+    error?: string;
+}>;
+/** Persist a new card order. Optimistic; caller rolls back on failure. */
+declare function setHomeActionOrder(order: string[]): Promise<{
+    ok: boolean;
+    status: number;
+    error?: string;
+}>;
+
+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;
+    }>;
+    /** 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;
+}
+declare const useWidgetsStore: zustand.UseBoundStore<zustand.StoreApi<WidgetsState>>;
+
+interface HomeActionsState {
+    actions: HomeAction[];
+    hydrated: boolean;
+    loading: boolean;
+    hydrate: () => Promise<void>;
+    refresh: () => Promise<void>;
+    clear: () => void;
+    /** Optimistic dismiss — removes locally, rolls back on real failure. */
+    dismiss: (actionId: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Optimistic pin/unpin. */
+    setPinned: (actionId: string, pinned: boolean) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Optimistic reorder — `orderedIds` is the new visual order. */
+    reorder: (orderedIds: string[]) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    applyServerUpsert: (action: HomeAction) => void;
+    applyServerRemove: (actionId: string) => void;
+    applyServerOrder: (orderedIds: string[]) => void;
+}
+declare const useHomeActionsStore: zustand.UseBoundStore<zustand.StoreApi<HomeActionsState>>;
+
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+declare function notifyAcsWsForeground(): void;
+/**
+ * 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).
+ */
+declare function connectAcsWs(token: string, tenant: string): void;
+/**
+ * Stop the ACS WS subscription. Call on signout / env switch.
+ */
+declare function disconnectAcsWs(): void;
+
+/**
+ * ACS host DI seams. Both optional — the ACS layer works without them:
+ * no reachability reporting, and the home-actions cache lives in memory only.
+ */
+/** Host hook fired on every ACS fetch outcome — a response (any status)
+ *  proves the server is reachable; a thrown fetch means it isn't. The
+ *  reference app wires this to its connectivity banner store. */
+interface AcsReachabilityReporter {
+    up: () => void;
+    down: () => void;
+}
+declare function setAcsReachabilityReporter(r: AcsReachabilityReporter | null): void;
+/** Minimal async KV used to persist the home-actions feed across cold starts
+ *  (AsyncStorage-shaped). @ateam-ai-mobile/expo wires AsyncStorage in
+ *  setupExpoProviders(); without a provider the cache is a no-op. */
+interface AcsKvStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+declare function setAcsCacheStorage(kv: AcsKvStorage | null): void;
+
+export { type AcsArtifact, type AcsDeleteReason, type AcsEvent, type AcsKvStorage, type AcsPatchReason, type AcsReachabilityReporter, type AcsSurface, type AdasConfig, type AdasSession, type AdasUser, type AttachmentCache, type AttachmentPreview, type BufferedCommand, type DeleteResult, type HomeAction, type HomeActionLeaf, type HomeActionReason, type JobProgress, type Message, type MessageAttachment, type OutgoingAttachment, type PatchResult, PluginCommandEmitter, type RefreshOutcome, TABLE_BLOCK_CLOSE, TABLE_BLOCK_OPEN, type TenantMembership, type TokenProvider, type ToolCall, type UIAction, ada, apiFetch, apiFetchRaw, blocksToText, borderRadius, closeChatStream, colors, connectAcsWs, connectorCall, deleteArtifact, disconnectAcsWs, fontSize, getConfig, getConsumerAuthApiUrl, getCoreApiUrl, getCoreWsUrl, getTenant, getToken, getUser, getVoiceApiUrl, initAdas, isAdasInitialized, listHomeActions, listMadeForYou, listMyTenants, listSurface, mcpFetch, mcpToolCall, notifyAcsWsForeground, patchArtifact, patchHomeAction, pluginCommandEmitter, postCommandResult, recordEvent, setAcsCacheStorage, setAcsReachabilityReporter, setHomeActionOrder, setOrder, spacing, switchTenant, unwrapMcpResult, useChatStore, useHomeActionsStore, useWidgetsStore };