@ateam-ai-mobile/core 0.1.6 → 0.1.8

package/src/gate.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+export type AdasPhase =
+  | 'loading'
+  | 'onboarding'
+  | 'handoff'
+  | 'invite'
+  | 'login'
+  | 'tenant'
+  | 'capabilities'
+  | 'app';
+
+export 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.
+ */
+export function resolveAdasPhase(f: AdasGateFlags): AdasPhase {
+  if (!f.configHydrated || f.authLoading || f.capabilitiesLoading || f.onboarded === undefined) {
+    return 'loading';
+  }
+  if (!f.onboarded) return 'onboarding';
+  if (!f.isAuthenticated) {
+    return f.handoffPending ? 'handoff' : f.invitePending ? 'invite' : 'login';
+  }
+  if (f.requireTenantPick && !f.tenantConfirmed) return 'tenant';
+  if (!f.hasCompletedSetup) return 'capabilities';
+  return 'app';
+}

package/src/index.ts

@@ -46,11 +46,77 @@ export {
 // Tenant memberships
 export { getSession, isDevHost } from './session';
 export type { Session, SessionEnv } from './session';
+
+// SDK-owned session state machine (R6) — JWT lifecycle, refresh table, restore,
+// logout orchestration. The host provides secure storage + a logout teardown hook.
+export { createAuthSession, userFromJwt } from './authSession';
+export type {
+  AuthSession,
+  AuthSessionState,
+  AuthSessionDeps,
+  SessionPersistence,
+  SessionUser,
+  SessionStatus,
+} from './authSession';
+
+// Push registration lifecycle + app-foreground coordinator (R7) — the host
+// supplies the native token acquisition + the backend calls; the SDK owns the
+// register/re-register/unregister lifecycle and the foreground reaction order.
+export { createPushRegistration } from './pushRegistration';
+export type { PushRegistration, PushBackend } from './pushRegistration';
+export { onAppForeground, notifyAppForeground } from './lifecycle';
+
+// App-gate cascade (R9) — the pure "which phase to render" decision the host's
+// root layout consumes; the host keeps the branded phase screens + the router.
+export { resolveAdasPhase } from './gate';
+export type { AdasPhase, AdasGateFlags } from './gate';
+
+// Consumer-auth flow (R9) — config fetch + provider/handoff/invite/open-join
+// exchanges + channel OTP. The host acquires the native id_token; this trades it
+// for a session JWT. Reads only the SDK config getters.
+export {
+  fetchConsumerConfig,
+  signInWithGoogle,
+  signInWithApple,
+  exchangeHandoff,
+  previewInvite,
+  joinWithGoogle,
+  joinWithApple,
+  openJoinWithGoogle,
+  openJoinWithApple,
+  linkChannelStart,
+  linkChannelVerify,
+} from './consumerAuth';
+export type {
+  ConsumerProviderConfig,
+  ConsumerCapabilityConfig,
+  ConsumerSignInResult,
+  OtpStartResult,
+  HandoffExchangeResult,
+  InvitePreview,
+} from './consumerAuth';
+
+// Deep-link code parsing (R9) — generic invite/handoff extraction; the URL
+// scheme stays host-side.
+export { parseDeepLinkParam, parseInviteCode, parseHandoffCode } from './deepLinks';
+
+// Workspace subscription state (server-resolved; GET /api/session)
+export {
+  useWorkspaceStore,
+  capabilityEnabled,
+  useCapability,
+} from './workspace';
+export type {
+  WorkspaceSnapshot,
+  WorkspaceState,
+  WorkspaceCapabilities,
+} from './workspace';
 export { listMyTenants, switchTenant } from './api/tenants';
 export type { TenantMembership } from './api/tenants';
 
 // Chat
 export {
+  setClientDeclarationProvider,
   useChatStore,
   closeChatStream,
   blocksToText,

package/src/lifecycle.ts

@@ -0,0 +1,43 @@
+/**
+ * SDK-owned app-lifecycle coordinator (R7).
+ *
+ * The OS foreground/background EVENT is a native concern — the host owns the one
+ * `AppState` listener (core cannot import react-native). But the REACTIONS to it
+ * were scattered across three separate app listeners (ACS WS reconnect, a
+ * battery refresh, an ACS GET safety-net), each firing independently on
+ * `active`. R7 consolidates the reactions here: the host pokes `notifyAppForeground()`
+ * from its single listener, and the SDK runs them in a deliberate order —
+ * reconnect the ACS socket FIRST (so a resumed session is live before the GET
+ * safety-net runs), then every registered host callback.
+ *
+ * No react-native import — the same seam works for any host.
+ */
+import { notifyAcsWsForeground } from './acs/ws';
+
+const foregroundCbs = new Set<() => void>();
+
+/**
+ * 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.
+ */
+export function onAppForeground(cb: () => void): () => void {
+  foregroundCbs.add(cb);
+  return () => { foregroundCbs.delete(cb); };
+}
+
+/**
+ * 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.
+ */
+export function notifyAppForeground(): void {
+  try { notifyAcsWsForeground(); } catch (e: any) {
+    console.warn('[adas/lifecycle] acs foreground reconnect failed:', e?.message || e);
+  }
+  for (const cb of foregroundCbs) {
+    try { cb(); } catch (e: any) {
+      console.warn('[adas/lifecycle] foreground callback failed:', e?.message || e);
+    }
+  }
+}

package/src/pushRegistration.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+export 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>;
+}
+
+export 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>;
+}
+
+export function createPushRegistration(backend: PushBackend): PushRegistration {
+  let token: string | null = null;
+
+  return {
+    getToken: () => token,
+
+    async setToken(next) {
+      if (!next) { token = null; return; }
+      if (next === token) return; // already registered this token
+      token = next;
+      try {
+        await backend.registerDevice(next);
+      } catch (e: any) {
+        console.warn('[adas/push] registerDevice failed:', e?.message || e);
+      }
+    },
+
+    async unregister() {
+      const t = token;
+      token = null; // forget locally immediately — a slow network must not block sign-out
+      if (t) {
+        backend.unregisterDevice(t).catch((e: any) =>
+          console.warn('[adas/push] unregisterDevice failed:', e?.message || e),
+        );
+      }
+    },
+  };
+}

package/src/workspace.ts

@@ -0,0 +1,127 @@
+// packages/core/src/workspace.ts
+//
+// Workspace subscription state — resolved ENTIRELY by the server and surfaced,
+// never interpreted by the client. The app holds NO subscription rules (no trial
+// dates, plan names, or close-code meaning); it renders what the server says.
+// That is the whole point of the design: a new plan needs no mobile release.
+//
+// Source: GET /api/session (authenticated, below attachActor). It answers even
+// when the realtime socket is refused (an expired tenant gets WS close 4003), so
+// it — not a WS frame — is the startup carrier for this state. A future ACS WS
+// delta push will update it in place; that path is not built yet, so no
+// push-apply API is exposed until the delta contract exists (avoids freezing an
+// unused contract early).
+
+import { create } from 'zustand';
+import { apiFetch } from './api/client';
+
+export 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. */
+export interface WorkspaceCapabilities {
+  chat?: boolean;
+  live_updates?: boolean;
+  ui_commands?: boolean;
+  [capability: string]: boolean | undefined;
+}
+
+export 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;
+}
+
+/** GET /api/session response envelope (only `workspace` is read here). */
+interface SessionResponse {
+  ok?: boolean;
+  actor?: unknown;
+  tenant?: string;
+  workspace?: Partial<WorkspaceSnapshot> | null;
+}
+
+function normalize(w: Partial<WorkspaceSnapshot> | null | undefined): WorkspaceSnapshot | null {
+  if (!w || typeof w !== 'object') return null;
+  const state: WorkspaceState =
+    w.state === 'active' || w.state === 'expired' || w.state === 'suspended' ? w.state : 'unknown';
+  return {
+    state,
+    reason: typeof w.reason === 'string' ? w.reason : null,
+    trialEndsAt: typeof w.trialEndsAt === 'string' ? w.trialEndsAt : null,
+    expiresInDays: typeof w.expiresInDays === 'number' ? w.expiresInDays : null,
+    capabilities:
+      w.capabilities && typeof w.capabilities === 'object' ? (w.capabilities as WorkspaceCapabilities) : {},
+    message: typeof w.message === 'string' && w.message.trim() ? w.message : null,
+  };
+}
+
+// Monotonic identity generation. Bumped whenever the workspace IDENTITY changes
+// — clear() on tenant switch / signout. A refresh() captures the generation at
+// dispatch and applies its result only if the generation has not moved on, so a
+// slow /api/session response scoped to tenant A can never land on (and mislabel)
+// tenant B after a switch. Without this, a late A response — success OR the
+// snapshot-preserving failure path — could leak A's banner/capabilities into B.
+let _gen = 0;
+
+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;
+}
+
+export const useWorkspaceStore = create<WorkspaceStore>((set) => ({
+  snapshot: null,
+  loaded: false,
+  refresh: async () => {
+    const gen = _gen; // this refresh belongs to the CURRENT identity
+    try {
+      const res = await apiFetch<SessionResponse>('/api/session');
+      if (gen !== _gen) return; // superseded by a tenant switch / signout — drop the stale response
+      set({ snapshot: normalize(res?.workspace), loaded: true });
+    } catch {
+      // Superseded → do not touch the new identity's state.
+      if (gen !== _gen) return;
+      // Same identity, transient failure (or pre-promotion 404): DO NOT grey
+      // anything out. Keep the last-known snapshot (null on first load), so the
+      // app stays fully capable and the banner only ever shows from a real
+      // snapshot, never from the absence of one.
+      set({ loaded: true });
+    }
+  },
+  clear: () => {
+    _gen++; // invalidate any in-flight refresh from the previous identity
+    set({ snapshot: null, loaded: false });
+  },
+}));
+
+/**
+ * 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.
+ */
+export function capabilityEnabled(name: string): boolean {
+  const { snapshot } = useWorkspaceStore.getState();
+  if (!snapshot) return true;
+  return snapshot.capabilities?.[name] === true;
+}
+
+/** Reactive form of capabilityEnabled for components (re-renders on change). */
+export function useCapability(name: string): boolean {
+  return useWorkspaceStore((s) => {
+    if (!s.snapshot) return true;
+    return s.snapshot.capabilities?.[name] === true;
+  });
+}