@ateam-ai-mobile/core 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -197,18 +197,367 @@ declare function isDevHost(u: string | undefined | null): boolean;
  *  wraps this for reactivity; imperative code can call it directly. */
 declare function getSession(): Session;
 
+/**
+ * SDK-owned session state machine (R6).
+ *
+ * Until R6 the JWT lifecycle lived in the app (apps/mobile/src/stores/
+ * authStore.ts): token storage, the decode/user projection, the startup
+ * restore + silent refresh, and the refresh decision table. A second host
+ * (host-demo, a third-party app) had to re-implement all of it. R6 moves the
+ * MECHANISM here; the host keeps only what is genuinely its own — secure
+ * storage and the side effects of signing out.
+ *
+ * Two seams keep this free of any app/Expo import and free of an auth<->bridge
+ * cycle (the plan's explicit constraint):
+ *   - `persistence`  the host's secure JWT storage (get/save/clear). The SDK
+ *                    never imports expo-secure-store.
+ *   - `onLogout`     the host's teardown, run in ONE place so the order is
+ *                    owned here: stop the device/relay bridge, unregister push
+ *                    (while the token still exists), clear plugin storage +
+ *                    bundle cache + device-tool registry, close chat. The SDK
+ *                    calls it; it never imports the stores that do the work.
+ *
+ * The refresh decision table and JWT projection are moved VERBATIM from the app
+ * so behaviour is identical (the R0.5 authRefresh baseline is the oracle).
+ */
+
+interface SessionUser {
+    actorId: string;
+    email?: string;
+    displayName?: string;
+    tenantRole?: string | null;
+    serviceRole?: string | null;
+    platformRoles?: string[];
+    roles: string[];
+}
+type SessionStatus = 'loading' | 'authenticated' | 'signed_out';
+interface AuthSessionState {
+    token: string | null;
+    user: SessionUser | null;
+    status: SessionStatus;
+}
+/**
+ * The host's secure JWT storage. Only the token lives here — tenant selection
+ * and env are resolved through the config getters, not stored by the session
+ * (derive-never-store).
+ */
+interface SessionPersistence {
+    loadToken(): Promise<string | null>;
+    saveToken(token: string): Promise<void>;
+    clearToken(): Promise<void>;
+}
+interface AuthSessionDeps {
+    persistence: SessionPersistence;
+    /**
+     * Host teardown for sign-out, run by `logout()` WHILE THE TOKEN STILL EXISTS
+     * (push unregister needs the JWT) and BEFORE the SDK clears it. The host does
+     * the app-specific work — stop the bridge, unregister push, clear the tenant
+     * keys, evict plugin storage / bundle cache / device-tool registry, close
+     * chat — in this one hook, so there is no auth->bridge import cycle.
+     */
+    onLogout?: () => void | Promise<void>;
+    /**
+     * Called when a token is adopted (login, or a successful refresh) with the
+     * projected user, so the host can persist side data (e.g. its TENANT key)
+     * without the session reaching into app storage.
+     */
+    onToken?: (token: string, user: SessionUser | null) => void | Promise<void>;
+}
+declare function userFromJwt(token: string): SessionUser | null;
+interface AuthSession {
+    /** Current token (synchronous, in-memory) — the TokenProvider read path. */
+    getToken(): string | null;
+    getUser(): SessionUser | null;
+    getState(): AuthSessionState;
+    subscribe(cb: (s: AuthSessionState) => void): () => void;
+    /** Startup: load the persisted token, project the user, and silently refresh
+     *  an expired JWT (ok → adopt, auth_failed → sign out, transient → keep). */
+    restore(): Promise<void>;
+    /** Adopt a freshly-minted token (host authenticated the user). */
+    login(token: string): Promise<void>;
+    /** Sign out: host teardown (with token still present) → clear token → state. */
+    logout(): Promise<void>;
+    /** The 401 refresh path. Adopts a new token on success; returns the API
+     *  client's outcome shape ('ok' → retry, 'auth_failed' → sign out). */
+    refresh(): Promise<RefreshOutcome>;
+}
+declare function createAuthSession(deps: AuthSessionDeps): AuthSession;
+
+/**
+ * SDK-owned push registration lifecycle (R7).
+ *
+ * R6 left the sign-out push unregister as a temporary APP hook (authStore's
+ * teardown dynamically imported getCurrentPushToken + unregisterDevice). R7
+ * finishes it with an SDK-owned service: the token→backend LIFECYCLE lives here
+ * (register when a token is acquired, re-register when it refreshes, unregister
+ * on sign-out, remember the current token), and the host supplies only the two
+ * genuinely native/host pieces via an injected backend:
+ *   - registerDevice / unregisterDevice   (the Core notif-api calls)
+ * The host's native layer (FCM/APNs acquisition, permission prompts, token
+ * refresh listeners) feeds tokens in via setToken(); it does not own the
+ * backend lifecycle any more.
+ *
+ * No Expo/RN import here — the same seam works for any host.
+ */
+interface PushBackend {
+    /** Register a device push token with the backend (needs a live JWT). */
+    registerDevice(token: string): Promise<void>;
+    /** Unregister a device push token from the backend. */
+    unregisterDevice(token: string): Promise<void>;
+}
+interface PushRegistration {
+    /**
+     * Adopt a freshly-acquired native push token and register it with the backend.
+     * Idempotent — re-registering the SAME token is a no-op; a NEW token (refresh)
+     * registers the new one. Pass null to forget without a backend call.
+     * Best-effort: a backend failure is logged, never thrown (push is not
+     * allowed to break sign-in).
+     */
+    setToken(token: string | null): Promise<void>;
+    /** The current registered token, or null. */
+    getToken(): string | null;
+    /**
+     * Sign-out: unregister the current token from the backend and forget it.
+     * Fire-and-forget on the network call so a flaky connection can't BLOCK
+     * sign-out (the ordering contract: this runs while the JWT still exists, then
+     * the session clears the JWT). Returns once the token is forgotten locally.
+     */
+    unregister(): Promise<void>;
+}
+declare function createPushRegistration(backend: PushBackend): PushRegistration;
+
+/**
+ * Register a reaction to run when the app returns to the foreground (e.g. the
+ * host's battery refresh, or an ACS GET safety-net). Returns an unsubscribe.
+ */
+declare function onAppForeground(cb: () => void): () => void;
+/**
+ * The host calls this from its single AppState listener when the app becomes
+ * `active`. Order is owned here: force the ACS WS to reconnect first, then run
+ * the registered host reactions. Each step is guarded so one failure can't stop
+ * the rest.
+ */
+declare function notifyAppForeground(): void;
+
+/**
+ * SDK-owned app-gate cascade (R9).
+ *
+ * The host's root layout used to inline the "which screen do we show right now"
+ * decision — a linear cascade (loading → onboarding → auth → tenant →
+ * capabilities → app) with a pre-auth PRIORITY (a web→app handoff beats an
+ * invite, which beats the default login). That decision is generic navigation
+ * orchestration: every host makes the same one. R9 moves the DECISION here as a
+ * pure function; the host keeps the presentation (its branded phase screens) and
+ * the Expo Router `<Stack>` that owns route registration.
+ *
+ * No react-native import — a pure function of the flags the host already tracks
+ * (auth comes from the SDK session; onboarding/capabilities/invite/handoff are
+ * host state), so it is trivially unit-testable and host-agnostic.
+ */
+type AdasPhase = 'loading' | 'onboarding' | 'handoff' | 'invite' | 'login' | 'tenant' | 'capabilities' | 'app';
+interface AdasGateFlags {
+    /** Host config/service-URL hydration finished. */
+    configHydrated: boolean;
+    /** The SDK session is still restoring (status === 'loading'). */
+    authLoading: boolean;
+    /** First-launch onboarding: true = done, false = show it, undefined = still checking. */
+    onboarded: boolean | undefined;
+    /** The SDK session is authenticated. */
+    isAuthenticated: boolean;
+    /** Host capability init still running. */
+    capabilitiesLoading: boolean;
+    /** A pending web→app handoff (one-time code → session) — the strongest pre-auth signal. */
+    handoffPending: boolean;
+    /** A pending invite (tenant join → OAuth). */
+    invitePending: boolean;
+    /** Whether the host requires an explicit tenant pick before entering the app
+     *  (multi-tenant). A single-tenant host passes false and skips the phase. */
+    requireTenantPick: boolean;
+    /** The user has confirmed/selected a tenant (auto-true in single-tenant). */
+    tenantConfirmed: boolean;
+    /** Capability onboarding done. */
+    hasCompletedSetup: boolean;
+}
+/**
+ * Resolve the single screen phase to render, in the exact order the host used:
+ * a still-hydrating app shows `loading`; then first-launch `onboarding`; then,
+ * if signed out, the pre-auth priority handoff > invite > login; then (only when
+ * the host requires it) the tenant pick; then capability setup; then the app.
+ */
+declare function resolveAdasPhase(f: AdasGateFlags): AdasPhase;
+
+interface ConsumerProviderConfig {
+    google?: {
+        web_client_id?: string;
+        ios_client_id?: string;
+        android_client_id?: string;
+        client_id?: string;
+    };
+    apple?: {
+        service_id: string;
+    };
+}
+interface ConsumerCapabilityConfig {
+    ok: boolean;
+    tenant: string;
+    providers: ConsumerProviderConfig;
+    linked_channels: string[];
+}
+interface ConsumerSignInResult {
+    ok: boolean;
+    jwt: string;
+    actor: {
+        id: string;
+        email: string;
+        role: string;
+    };
+}
+interface OtpStartResult {
+    ok: boolean;
+    challenge_id: string;
+    sent_to: string;
+    provider: string;
+    debug_code?: string;
+}
+/**
+ * Fetch the public consumer config for the active tenant. Returns the public
+ * OAuth client IDs needed to render Google/Apple sign-in buttons.
+ */
+declare function fetchConsumerConfig(): Promise<ConsumerCapabilityConfig>;
+/**
+ * Exchange a Google id_token for a tenant-scoped consumer JWT. The id_token
+ * comes from the host's native Google sign-in flow.
+ */
+declare function signInWithGoogle(idToken: string): Promise<ConsumerSignInResult>;
+/** Exchange an Apple id_token for a tenant-scoped consumer JWT. */
+declare function signInWithApple(idToken: string): Promise<ConsumerSignInResult>;
+interface HandoffExchangeResult extends ConsumerSignInResult {
+    tenant?: string;
+}
+declare function exchangeHandoff(code: string): Promise<HandoffExchangeResult>;
+interface InvitePreview {
+    ok: boolean;
+    org: string;
+    role: string | null;
+}
+/**
+ * Preview an invite (no auth) to render the "Join <Org> as <role>?" screen.
+ * Throws with a friendly message on 404 (invalid/expired).
+ */
+declare function previewInvite(code: string): Promise<InvitePreview>;
+/**
+ * Exchange an invite + Google id_token for a tenant-scoped consumer JWT.
+ * NOTE: no `tenant` field — the invite carries the tenant. Sending `tenant`
+ * instead would be the open-signup path (403 on invite-only tenants).
+ */
+declare function joinWithGoogle(invite: string, idToken: string): Promise<ConsumerSignInResult>;
+/** Exchange an invite + Apple id_token for a tenant-scoped consumer JWT. */
+declare function joinWithApple(invite: string, idToken: string): Promise<ConsumerSignInResult>;
+declare function openJoinWithGoogle(tenant: string, idToken: string): Promise<ConsumerSignInResult>;
+declare function openJoinWithApple(tenant: string, idToken: string): Promise<ConsumerSignInResult>;
+/**
+ * Start a channel-link OTP challenge. The consumer must be authenticated
+ * (their JWT is passed via the Authorization header).
+ */
+declare function linkChannelStart(jwt: string, channel: string, handle: string): Promise<OtpStartResult>;
+/** Verify the OTP and complete the channel link. */
+declare function linkChannelVerify(jwt: string, challengeId: string, code: string): Promise<{
+    ok: boolean;
+    channel: string;
+    handle: string;
+    actorId: string;
+    transferred: boolean;
+}>;
+
+/**
+ * Deep-link parsing (R9) — the generic navigation-orchestration half of the
+ * host's invite/handoff capture. Extracting a code from a link's query string
+ * is the same for any host; only the URL SCHEME (adas://, universal-link
+ * domains) is host-specific and stays in the host's Expo Router config.
+ */
+/**
+ * Pull a query param's value out of a deep link, URL-decoded. Returns null when
+ * the link is empty, the param is absent, or the value is empty. Tolerant of a
+ * malformed encoding (falls back to the raw match) so a valid code is never
+ * dropped on a stray `%`.
+ */
+declare function parseDeepLinkParam(url: string | null | undefined, param: string): string | null;
+/** A tenant-invite code from `?invite=<code>`. */
+declare function parseInviteCode(url: string | null | undefined): string | null;
+/**
+ * A web→app handoff code from `?handoff=<code>`. Deliberately keyed on `handoff=`
+ * and NOT `code=`, so it never collides with an OAuth `?code=` redirect.
+ */
+declare function parseHandoffCode(url: string | null | undefined): string | null;
+
+type WorkspaceState = 'active' | 'expired' | 'suspended' | 'unknown';
+/** Server-granted capabilities. Open-ended on purpose: a plan can introduce a
+ *  new capability name and old app versions simply won't grant it. */
+interface WorkspaceCapabilities {
+    chat?: boolean;
+    live_updates?: boolean;
+    ui_commands?: boolean;
+    [capability: string]: boolean | undefined;
+}
+interface WorkspaceSnapshot {
+    state: WorkspaceState;
+    reason: string | null;
+    trialEndsAt: string | null;
+    expiresInDays: number | null;
+    capabilities: WorkspaceCapabilities;
+    /** Server-authored copy. Rendered VERBATIM — the client never composes it. */
+    message: string | null;
+}
+interface WorkspaceStore {
+    /** null = not loaded / endpoint absent — treat the app as fully capable. */
+    snapshot: WorkspaceSnapshot | null;
+    loaded: boolean;
+    /** Fetch GET /api/session and store the workspace snapshot (identity-guarded). */
+    refresh: () => Promise<void>;
+    /** Reset AND invalidate any in-flight refresh. Call on signout / tenant switch
+     *  (the host must clear before refreshing a new identity). */
+    clear: () => void;
+}
+declare const useWorkspaceStore: zustand.UseBoundStore<zustand.StoreApi<WorkspaceStore>>;
+/**
+ * Is a capability granted? The SERVER decides; the client never infers it from
+ * a local rule. Two deliberate, asymmetric defaults:
+ *  - No snapshot loaded (endpoint absent, or not fetched yet) → GRANTED, so the
+ *    app behaves exactly as it did before this layer existed.
+ *  - Snapshot loaded but this capability missing/unknown → NOT granted, so a new
+ *    plan can restrict an old app version and an unrecognised name never leaks
+ *    access.
+ */
+declare function capabilityEnabled(name: string): boolean;
+/** Reactive form of capabilityEnabled for components (re-renders on change). */
+declare function useCapability(name: string): boolean;
+
 interface TenantMembership {
     id: string;
     name: string;
     role: string | null;
 }
 /**
- * List the tenants the CURRENT user belongs to (GET /api/tenants/list).
+ * List the tenants the CURRENT user belongs to.
  *
  * 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.
+ *
+ * IT CALLS CONSUMER-AUTH, NOT CORE. This used to be
+ * `apiFetch('/api/tenants/list')` against the Core API, which is the wrong
+ * service: the membership a consumer JWT proves is held by consumer-auth, so
+ * Core could not answer it for the case that matters — a signed-in consumer
+ * asking which teams they are in. Hence the explicit fetch with the bearer
+ * token rather than the shared `apiFetch` helper, which is Core-scoped.
+ *
+ * EVERY FAILURE PATH RETURNS [] deliberately: no token, non-OK response,
+ * unparseable body, or a thrown fetch. "I could not find out" and "you belong
+ * to nothing" are genuinely different, but this signature has no room to say
+ * so — the caller renders a team list, and an empty one is the safe render.
+ * If that distinction ever matters, widen the return type rather than
+ * inventing a tenant.
  */
 declare function listMyTenants(): Promise<TenantMembership[]>;
 /**
@@ -346,6 +695,20 @@ declare function blocksToText(blocks?: Array<{
     content: any;
 }>): string;
 declare const useChatStore: zustand.UseBoundStore<zustand.StoreApi<ChatState>>;
+/** What this client can execute, supplied by the host (see setClientDeclarationProvider). */
+type ClientDeclaration = {
+    device_host: boolean;
+    tools: Array<{
+        name: string;
+    }>;
+};
+/**
+ * Host DI: what to tell the server about this client on connect.
+ *
+ * Kept as a provider rather than a value because the answer changes — plugins
+ * load after boot, so the tool list is not known when the socket first opens.
+ */
+declare function setClientDeclarationProvider(fn: (() => ClientDeclaration | null) | null): void;
 /** Tear down the live connection (env/auth switch, SDK unmount). */
 declare function closeChatStream(): void;
 
@@ -782,4 +1145,4 @@ interface AcsKvStorage {
 }
 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, type Session, type SessionEnv, 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, getSession, getTenant, getToken, getUser, getVoiceApiUrl, initAdas, isAdasInitialized, isDevHost, listHomeActions, listMadeForYou, listMyTenants, listSurface, mcpFetch, mcpToolCall, notifyAcsWsForeground, patchArtifact, patchHomeAction, pluginCommandEmitter, postCommandResult, recordEvent, refreshToken, setAcsCacheStorage, setAcsReachabilityReporter, setHomeActionOrder, setOrder, spacing, switchTenant, unwrapMcpResult, useChatStore, useHomeActionsStore, useWidgetsStore };
+export { type AcsArtifact, type AcsDeleteReason, type AcsEvent, type AcsKvStorage, type AcsPatchReason, type AcsReachabilityReporter, type AcsSurface, type AdasConfig, type AdasGateFlags, type AdasPhase, type AdasSession, type AdasUser, type AttachmentCache, type AttachmentPreview, type AuthSession, type AuthSessionDeps, type AuthSessionState, type BufferedCommand, type ConsumerCapabilityConfig, type ConsumerProviderConfig, type ConsumerSignInResult, type DeleteResult, type HandoffExchangeResult, type HomeAction, type HomeActionLeaf, type HomeActionReason, type InvitePreview, type JobProgress, type Message, type MessageAttachment, type OtpStartResult, type OutgoingAttachment, type PatchResult, PluginCommandEmitter, type PushBackend, type PushRegistration, type RefreshOutcome, type Session, type SessionEnv, type SessionPersistence, type SessionStatus, type SessionUser, TABLE_BLOCK_CLOSE, TABLE_BLOCK_OPEN, type TenantMembership, type TokenProvider, type ToolCall, type UIAction, type WorkspaceCapabilities, type WorkspaceSnapshot, type WorkspaceState, ada, apiFetch, apiFetchRaw, blocksToText, borderRadius, capabilityEnabled, closeChatStream, colors, connectAcsWs, connectorCall, createAuthSession, createPushRegistration, deleteArtifact, disconnectAcsWs, exchangeHandoff, fetchConsumerConfig, fontSize, getConfig, getConsumerAuthApiUrl, getCoreApiUrl, getCoreWsUrl, getSession, getTenant, getToken, getUser, getVoiceApiUrl, initAdas, isAdasInitialized, isDevHost, joinWithApple, joinWithGoogle, linkChannelStart, linkChannelVerify, listHomeActions, listMadeForYou, listMyTenants, listSurface, mcpFetch, mcpToolCall, notifyAcsWsForeground, notifyAppForeground, onAppForeground, openJoinWithApple, openJoinWithGoogle, parseDeepLinkParam, parseHandoffCode, parseInviteCode, patchArtifact, patchHomeAction, pluginCommandEmitter, postCommandResult, previewInvite, recordEvent, refreshToken, resolveAdasPhase, setAcsCacheStorage, setAcsReachabilityReporter, setClientDeclarationProvider, setHomeActionOrder, setOrder, signInWithApple, signInWithGoogle, spacing, switchTenant, unwrapMcpResult, useCapability, useChatStore, useHomeActionsStore, useWidgetsStore, useWorkspaceStore, userFromJwt };