@layers/amba-react-native 4.0.3 → 4.0.5

package/dist/index.d.ts

@@ -138,15 +138,66 @@ interface PushToken {
   bundle_id?: string | null;
   created_at: string;
 }
-type EntitlementSource = "revenue_cat" | "app_store" | "play_store" | "stripe" | "promo_code" | "manual";
+/**
+ * Store an entitlement's purchase resolved from. `"web"` is the neutral bucket
+ * for any non-native checkout (it replaced the former `"stripe"` value).
+ */
+type EntitlementStore = "app_store" | "play_store" | "web";
+/** Lifecycle phase of the subscription period backing the entitlement. */
+type EntitlementPeriodType = "trial" | "intro" | "normal";
+/**
+ * A server-evaluated entitlement grant, mirroring the
+ * `GET /v1/client/entitlements` response field-for-field. `store` and
+ * `period_type` are nullable, CHECK-constrained text columns, typed
+ * loosely (`… | (string & {}) | null`) so an unexpected value from a newer
+ * server never breaks decoding while still autocompleting the known set.
+ */
 interface UserEntitlement {
-  id: string;
-  name: string;
+  /** Project-defined entitlement key (e.g. `"pro"`) — what `has()` checks. */
+  entitlement_id: string;
   is_active: boolean;
-  source: EntitlementSource;
-  expires_at?: string | null;
-  granted_at?: string | null;
+  product_id?: string | null;
+  store?: EntitlementStore | (string & {}) | null;
+  purchase_date?: string | null;
+  expiration_date?: string | null;
+  period_type?: EntitlementPeriodType | (string & {}) | null;
+}
+/** Result of `entitlements.restore()` — the active set after a server re-sync. */
+interface RestoreResult {
+  restored_count: number;
+  entitlements: UserEntitlement[];
+}
+/** A product behind an offering package (provider-neutral). */
+interface OfferingProduct {
+  product_id: string;
+  display_name?: string | null;
+  description?: string | null;
+  product_type?: string | null;
+  /** Map of neutral store id → that store's product identifier. */
+  store_product_refs: Record<string, string>;
+  grants_entitlement_id?: string | null;
+  trial_period_days?: number | null;
+  duration?: string | null;
+}
+/** A package — one product at a position within an offering. */
+interface OfferingPackage {
+  package_id: string;
+  position: number;
   metadata: Record<string, unknown>;
+  product: OfferingProduct | null;
+}
+interface Offering {
+  offering_id: string;
+  display_name?: string | null;
+  description?: string | null;
+  current: boolean;
+  metadata: Record<string, unknown>;
+  packages: OfferingPackage[];
+}
+/** The shape `offerings()` returns. */
+interface OfferingsResult {
+  offerings: Offering[];
+  current_offering_id: string | null;
 }
 interface AiMessage {
   role: string;
@@ -588,8 +639,8 @@ interface UserPatch {
 /**
  * One row from `Amba.sessions.list` — a server-tracked customer-defined
  * app session row. Mirrors the `toSdkSession` projection in
- * `apps/api/src/routes/client/sessions.ts` and the Rust core's
- * `AppSession` struct (`sdks/core/src/sessions.rs`).
+ * `apps/api/src/routes/client/sessions.ts` and the SDK core's
+ * `AppSession` type.
  *
  * NOTE: this is NOT a device/auth session record — `/v1/client/sessions`
  * surfaces analytics-style `app_sessions` rows (open/background events).
@@ -611,7 +662,7 @@ interface SessionRecord {
 /**
  * One offline-replay change submitted to `Amba.sync.pushChanges`.
  * Mirrors `SyncPushInput.changes[]` in `apps/api/src/routes/client/sync.ts`
- * and the Rust core's `SyncChange` struct (`sdks/core/src/sync.rs`).
+ * and the SDK core's `SyncChange` type.
  * Server resolves conflicts server-wins.
  */
 interface SyncChange {
@@ -704,6 +755,315 @@ interface LeagueCohort {
     is_me?: boolean;
   }>;
 }
+/**
+ * When a local notification should fire. Exactly one shape:
+ *
+ *   - `{ at: Date }`            — fire once at an absolute time.
+ *   - `{ inSeconds, repeats? }` — fire after a relative delay; set
+ *     `repeats: true` to re-fire on that interval (the OS enforces a
+ *     minimum interval — typically ~60s on iOS for repeating triggers).
+ *
+ * Local notifications are scheduled and fired by the device itself, with
+ * no server involvement — distinct from remote push (`Amba.push.*`).
+ */
+type LocalNotificationTrigger = {
+  at: Date | string;
+} | {
+  inSeconds: number;
+  repeats?: boolean;
+};
+/** Input to `Amba.notifications.scheduleLocal`. */
+interface ScheduleLocalNotificationInput {
+  /**
+   * Optional stable id. Supply your own to make scheduling idempotent
+   * and to control the value `cancelLocal` expects; omit to let the
+   * platform mint one (returned in the handle).
+   */
+  id?: string;
+  /** Notification title (required, non-empty). */
+  title: string;
+  /** Notification body text. */
+  body: string;
+  /** Arbitrary payload delivered to the app when the notification is tapped. */
+  data?: Record<string, unknown>;
+  /** When to fire it. */
+  trigger: LocalNotificationTrigger;
+}
+/** Handle returned by `scheduleLocal`; `id` is accepted by `cancelLocal`. */
+interface LocalNotificationHandle {
+  id: string;
+}
+/** A pending local notification, as reported by `listScheduledLocal`. */
+interface ScheduledLocalNotification {
+  id: string;
+  title: string;
+  body: string;
+  data?: Record<string, unknown>;
+}
+//#endregion
+//#region src/resilience.d.ts
+/**
+ * Offline mutation queue + optimistic-update helpers — framework-agnostic
+ * orchestration that sits ABOVE the collection / event write methods.
+ *
+ * Nothing here touches the SDK runtime directly: the queue is handed a
+ * small `KvStore` (durable key/value persistence) and a `WriteExecutor`
+ * (the function that actually performs a queued mutation against the API).
+ * That keeps the same code identical across every JS SDK target — only the
+ * adapters that supply storage + the executor differ per platform.
+ *
+ * Design:
+ *   - A write that fails because the device is offline (a transport-level
+ *     network error, or `navigator.onLine === false`) is appended to a
+ *     durable outbox instead of throwing all the way up.
+ *   - Each queued op carries a stable idempotency key. On replay the key is
+ *     forwarded to the API's collection-write idempotency support so a
+ *     mutation that actually reached the server before the connection
+ *     dropped is never applied twice.
+ *   - On reconnect (`online` event) the outbox is flushed in FIFO order;
+ *     each op is removed only after it succeeds, so a mid-flush failure
+ *     leaves the remainder intact for the next attempt.
+ */
+/**
+ * Minimal durable key/value contract the outbox persists through. Both the
+ * browser `localStorage` adapter and the React Native AsyncStorage adapter
+ * satisfy this — the queue never assumes anything else.
+ */
+interface KvStore {
+  get(key: string): Promise<string | null> | string | null;
+  set(key: string, value: string): Promise<void> | void;
+  delete(key: string): Promise<void> | void;
+}
+/** The kinds of mutation the outbox can durably replay. */
+type OutboxOpKind = "collection.insert" | "collection.update" | "collection.delete" | "track";
+/**
+ * A single durably-queued mutation. `idempotencyKey` is reused verbatim on
+ * every replay attempt so the server dedupes a COLLECTION write that landed
+ * before the connection dropped (the events `track` API has no idempotency
+ * channel, so `track` replays are at-least-once — a rare reconnect duplicate
+ * is acceptable for fire-and-forget analytics). `enqueuedAt` is an ISO
+ * timestamp for inspection.
+ */
+interface OutboxOp {
+  /** Stable per-op id (the idempotency key for collection writes). */
+  idempotencyKey: string;
+  kind: OutboxOpKind;
+  /** Target collection name (absent for `track`). */
+  collection?: string;
+  /** Row id for update / delete. */
+  id?: string;
+  /** Insert row / update set payload. */
+  payload?: Record<string, unknown>;
+  /** Event name for `track`. */
+  event?: string;
+  /** Event properties for `track`. */
+  properties?: Record<string, unknown>;
+  /** Whether the tracked event was telemetry-tier. */
+  telemetry?: boolean;
+  /**
+   * ISO timestamp the `track` originally OCCURRED, captured at enqueue. Replayed
+   * as the events body `timestamp` (→ `occurred_at`) so a buffered event keeps
+   * its real time instead of being re-stamped at flush. (Attribution is by the
+   * session user at replay time — the events route has no body-id channel.)
+   */
+  occurredAt?: string;
+  enqueuedAt: string;
+}
+/** Result of a {@link OfflineQueue.flush}. */
+interface FlushResult {
+  /** Ops successfully replayed and removed from the outbox. */
+  flushed: number;
+  /**
+   * Ops dropped because their replay failed deterministically (a coded server
+   * rejection like `VALIDATION_ERROR` / `NOT_FOUND` that would fail identically
+   * forever). Dropping them prevents one poisoned op from wedging the queue;
+   * the drain continues past it.
+   */
+  dropped: number;
+  /** Ops still pending after the flush (a replay failed and stopped it). */
+  remaining: number;
+}
+/**
+ * Apply a local change immediately, fire the real mutation, and roll the
+ * local change back if the mutation fails. Framework-agnostic: `apply` and
+ * `rollback` operate on whatever local view you hand them (a React state
+ * setter, a store, an in-memory cache).
+ *
+ * Resolves with the mutation's result on success. On failure it invokes
+ * `rollback` (with the value `apply` returned, so you can restore a captured
+ * snapshot) and rethrows the original error.
+ *
+ * @example
+ * await withOptimistic({
+ *   apply: () => { const prev = todos; setTodos([...todos, draft]); return prev; },
+ *   mutate: () => Amba.collections.insert("todos", draft),
+ *   rollback: (prev) => setTodos(prev),
+ * });
+ */
+declare function withOptimistic<TApply, TResult>(spec: {
+  /** Mutate the local view now. Return a snapshot for `rollback` to restore. */
+  apply: () => TApply;
+  /** The real async mutation against the API. */
+  mutate: () => Promise<TResult>;
+  /** Undo the local change. Receives whatever `apply` returned. */
+  rollback: (applied: TApply) => void;
+}): Promise<TResult>;
+//#endregion
+//#region src/push-rotation.d.ts
+/**
+ * A platform token-refresh subscription primitive. Given a handler that
+ * receives the new token string, it must invoke that handler on every rotation
+ * and return an unsubscribe function. `Notifications.addPushTokenListener`
+ * (Expo) adapts to this directly.
+ */
+type TokenRefreshSubscribe = (handler: (token: string) => void) => () => void;
+//#endregion
+//#region src/realtime.d.ts
+/**
+ * Live collection / messaging / gamification subscriptions for
+ * `@layers/amba-react-native`.
+ *
+ * Public surface is byte-for-byte identical to `@layers/amba-web` and
+ * `@layers/amba-node` so the docs are uniform across every JS SDK:
+ *
+ *   const unsub = Amba.collection("messages")
+ *     .where("circle_id", circleId)
+ *     .subscribe((change) => {
+ *       // change.op: "INSERT" | "UPDATE" | "DELETE"; change.row: the row
+ *     });
+ *   unsub(); // stop listening
+ *
+ *   const unsub2 = Amba.messaging
+ *     .conversation(conversationId)
+ *     .subscribe((change) => { ... });
+ *
+ *   const unsub3 = Amba.gamification.subscribe((change) => { ... });
+ *
+ * ── Why a different transport from web/node ─────────────────────────────
+ * The web/node SDKs read the streamed HTTP response body via
+ * `response.body.getReader()`. React Native's `fetch` (Hermes / RN's
+ * networking layer) resolves the Response only AFTER the body is fully
+ * received and does NOT expose a readable `body` stream — so the web
+ * transport silently never delivers a frame on a long-lived connection.
+ *
+ * Instead we drive the SAME server endpoint (an event stream) through
+ * `XMLHttpRequest`, which RN implements with INCREMENTAL `responseText`:
+ * `onreadystatechange` fires at `readyState === 3` (LOADING) as bytes
+ * arrive, so we parse the newly-appended slice frame-by-frame. This is the
+ * mechanism `react-native-sse` uses under the hood; we inline it to avoid a
+ * peer dependency (and to set the auth header in `Authorization`, keeping
+ * the session token out of the URL/query string where it would leak into
+ * access logs — `EventSource` can't set headers).
+ *
+ * If XHR is somehow unavailable in the host runtime, we fall back to the
+ * web-style `fetch` + streamed-body reader (works on RN-for-web / any
+ * runtime that does expose `response.body`). Both transports speak the
+ * exact same wire frames, so the public behaviour is identical.
+ *
+ * Reconnect/backoff and frame parsing match web/node exactly.
+ */
+type RowChangeOp = "INSERT" | "UPDATE" | "DELETE";
+interface RealtimeChange<T = unknown> {
+  /** Which kind of write happened. */
+  op: RowChangeOp;
+  /**
+   * The affected row. For deletes this is a partial row (at minimum `id`).
+   * If the row was too large to deliver inline, `truncated` is `true` and
+   * `row` carries just `id` — re-fetch with `Amba.collections.find()` /
+   * `findOne()` when you need the full body.
+   */
+  row: T;
+  truncated?: boolean;
+}
+interface SubscribeOptions {
+  /** Called once when the live connection is (re)established. */
+  onOpen?: () => void;
+  /** Called on a connection error before the SDK retries. */
+  onError?: (err: unknown) => void;
+}
+/** Unsubscribe handle returned by `.subscribe(...)`. Call it to stop. */
+type Unsubscribe = () => void;
+/**
+ * Auth + endpoint context for a subscription. `authHeaders` is read lazily
+ * at connect time so reconnects pick up a rotated session token. Returns
+ * `null` when there's no live session (subscribe throws).
+ */
+interface RealtimeContext {
+  baseUrl: string;
+  authHeaders: () => Record<string, string> | null;
+}
+/**
+ * Builder returned by `Amba.collection(name)`. Chain `.where(...)` to
+ * narrow, then `.subscribe(cb)` to start streaming.
+ */
+declare class CollectionSubscription<T = unknown> {
+  private readonly ctx;
+  private readonly name;
+  private readonly filters;
+  constructor(ctx: RealtimeContext, name: string);
+  /** Add an equality filter. Chainable. All filters must match (AND). */
+  where(column: string, value: unknown): this;
+  /**
+   * Start listening. `cb` fires once per matching row change. Returns an
+   * unsubscribe handle — call it to close the connection.
+   */
+  subscribe(cb: (change: RealtimeChange<T>) => void, options?: SubscribeOptions): Unsubscribe;
+}
+/**
+ * A live message change in a conversation. `op` is "INSERT" for a new
+ * message; moderation removals arrive as "DELETE". For a delete (or when a
+ * message was too large to deliver inline) `row` may be partial — re-fetch
+ * with `Amba.messaging.listMessages(conversationId)` when you need the full
+ * body.
+ */
+type MessageChange<T = unknown> = RealtimeChange<T>;
+/**
+ * Builder returned by `Amba.messaging.conversation(id)`. Call `.subscribe(cb)`
+ * to receive new messages live instead of polling.
+ *
+ * Delivery is scoped to conversation participants — you receive messages for
+ * a conversation only if your session is a member of it. Reconnects with the
+ * same exponential backoff as collection subscriptions.
+ */
+declare class ConversationSubscription<T = unknown> {
+  private readonly ctx;
+  private readonly conversationId;
+  constructor(ctx: RealtimeContext, conversationId: string);
+  subscribe(cb: (change: MessageChange<T>) => void, options?: SubscribeOptions): Unsubscribe;
+}
+/** Which slice of the signed-in user's gamification state changed. */
+type GamificationKind = "xp" | "level" | "achievement" | "streak";
+/**
+ * A live change to the signed-in user's gamification state. `kind` says which
+ * slice moved; `data` carries the new state inline so you can update without a
+ * re-fetch:
+ *   - `xp`          — `{ total_xp, level, delta }`
+ *   - `level`       — `{ level, total_xp }`
+ *   - `achievement` — `{ achievement_id, unlocked }`
+ *   - `streak`      — `{ streak_id, count, status, ... }`
+ *
+ * If a payload was too large to deliver inline, `truncated` is `true` and `data`
+ * is empty — re-fetch with `Amba.xp.getBalance()` / `Amba.streaks.getAll()` etc.
+ */
+interface GamificationChange<T = Record<string, unknown>> {
+  kind: GamificationKind;
+  data: T;
+  truncated?: boolean;
+}
+/**
+ * Builder returned by `Amba.gamification`. Call `.subscribe(cb)` to receive the
+ * signed-in user's xp / level / achievement / streak changes live instead of
+ * polling.
+ *
+ * Delivery is scoped to the signed-in user — you only ever receive your own
+ * gamification changes, never another user's. Reconnects with the same
+ * exponential backoff as collection subscriptions.
+ */
+declare class GamificationSubscription {
+  private readonly ctx;
+  constructor(ctx: RealtimeContext);
+  subscribe(cb: (change: GamificationChange) => void, options?: SubscribeOptions): Unsubscribe;
+}
 //#endregion
 //#region src/error.d.ts
 /**
@@ -723,16 +1083,63 @@ interface LeagueCohort {
  * `new AmbaApiError("MY_CODE", "...")` without coordinating with this
  * package's TypeScript types.
  */
-type AmbaApiErrorCode = "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMITED" | "VALIDATION_ERROR" | "NETWORK_ERROR" | "HTTP_ERROR" | "CIRCUIT_OPEN" | "CONSENT_NOT_GRANTED" | "NOT_INITIALIZED" | "INVALID_CONFIG" | "INVALID_ARGUMENT" | "PUSH_PERMISSION_DENIED" | "PUSH_REGISTRATION_FAILED" | "NOT_SANDBOX_TIER" | "UNKNOWN_ERROR" | (string & {});
+type AmbaApiErrorCode = "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMITED" | "VALIDATION_ERROR" | "NETWORK_ERROR" | "HTTP_ERROR" | "CIRCUIT_OPEN" | "CONSENT_NOT_GRANTED" | "NOT_INITIALIZED" | "INVALID_CONFIG" | "INVALID_ARGUMENT" | "PUSH_PERMISSION_DENIED" | "PUSH_REGISTRATION_FAILED" | "LOCAL_NOTIFICATIONS_UNAVAILABLE" | "LOCAL_NOTIFICATIONS_PERMISSION_DENIED" | "NOT_SANDBOX_TIER" | "UNKNOWN_ERROR" | (string & {});
 declare class AmbaApiError extends Error {
   readonly code: AmbaApiErrorCode;
   readonly details?: unknown;
   constructor(code: AmbaApiErrorCode, message: string, details?: unknown);
 }
 //#endregion
+//#region src/local-notifications.d.ts
+/**
+ * The `notifications` namespace. Shared by `@layers/amba-react-native`
+ * and (via re-export) `@layers/amba-expo`.
+ */
+declare const notifications: {
+  /**
+   * Schedule a notification the device will fire locally — no server
+   * round-trip. Requests the OS notification permission on first use.
+   *
+   * @returns a handle whose `id` can be passed to `cancelLocal`.
+   * @throws `AmbaApiError`:
+   *   - `LOCAL_NOTIFICATIONS_UNAVAILABLE` — `expo-notifications` not installed.
+   *   - `LOCAL_NOTIFICATIONS_PERMISSION_DENIED` — user declined the prompt.
+   *   - `INVALID_ARGUMENT` — bad title / body / trigger.
+   *
+   * @example
+   * const { id } = await Amba.notifications.scheduleLocal({
+   *   title: 'Keep your streak alive',
+   *   body: 'You have a lesson waiting.',
+   *   trigger: { inSeconds: 60 * 60 * 12 },
+   * });
+   */
+  scheduleLocal(input: ScheduleLocalNotificationInput): Promise<LocalNotificationHandle>;
+  /**
+   * Cancel a previously scheduled local notification by id. No-throw if
+   * the id is unknown (the device framework treats it as already-gone),
+   * but still throws `LOCAL_NOTIFICATIONS_UNAVAILABLE` if the peer dep is
+   * absent so callers learn about the missing integration.
+   */
+  cancelLocal(id: string): Promise<void>;
+  /**
+   * List the notifications Amba has scheduled to fire on this device.
+   * Returns an empty array when none are pending.
+   *
+   * `getAllScheduledNotificationsAsync` returns EVERY pending
+   * `expo-notifications` schedule in the app — including ones the host app
+   * created directly. We filter to only entries carrying the Amba marker
+   * (`data.__ambaLocalId`) so foreign schedules never leak into the Amba
+   * list. (Mirrors the web SDK's marker filter.) These are pending by
+   * definition — `getAllScheduledNotificationsAsync` does not return
+   * already-delivered notifications.
+   */
+  listScheduledLocal(): Promise<ScheduledLocalNotification[]>;
+};
+type LocalNotificationsNamespace = typeof notifications;
+//#endregion
 //#region src/index.d.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-declare const SDK_VERSION = "4.0.3";
+declare const SDK_VERSION = "4.0.5";
 /** Options for `Amba.functions.invoke`. */
 interface InvokeOptions {
   /** HTTP method. Defaults to `"POST"`. */
@@ -757,6 +1164,37 @@ declare const Amba: {
   readonly isAuthenticated: boolean;
   readonly projectId: string;
   setDebug: (enabled: boolean) => void;
+  /**
+   * Live collection subscriptions. Returns a builder — chain `.where(...)`
+   * to narrow, then `.subscribe(cb)` to start streaming row changes:
+   *
+   *   const unsub = Amba.collection("messages")
+   *     .where("circle_id", circleId)
+   *     .subscribe((change) => {
+   *       // change.op: "INSERT" | "UPDATE" | "DELETE"; change.row: the row
+   *     });
+   *   unsub(); // stop listening
+   *
+   * Delivery mirrors `Amba.collections.find()` — you receive only rows your
+   * session owns (plus shared/public rows), optionally narrowed by
+   * `.where(...)`. Reconnects automatically with backoff if the connection
+   * drops. Requires an authenticated session.
+   */
+  collection: <T = unknown>(name: string) => CollectionSubscription<T>;
+  /**
+   * Live gamification updates for the signed-in user. Call `.subscribe(cb)`
+   * to receive xp / level / achievement / streak changes live:
+   *
+   *   const unsub = Amba.gamification.subscribe((change) => {
+   *     // change.kind: "xp" | "level" | "achievement" | "streak"
+   *     // change.data: the new state
+   *   });
+   *   unsub(); // stop listening
+   *
+   * You only ever receive your own gamification changes — never another
+   * user's. A getter so `baseUrl` is read at access time. Requires a session.
+   */
+  readonly gamification: GamificationSubscription;
   events: {
     /**
      * Track an event.
@@ -933,8 +1371,8 @@ declare const Amba: {
   };
   /**
    * Offline change replay. NEW in 4.0. Wraps `/v1/client/sync` per
-   * `apps/api/src/routes/client/sync.ts` and the engine's
-   * `SyncModule` (`sdks/core/src/sync.rs`).
+   * `apps/api/src/routes/client/sync.ts` and the SDK core's
+   * `SyncModule`.
    *
    * - `pushChanges(changes)` → `POST /v1/client/sync` with `{ changes }`.
    *   Server returns `{ applied, conflicts, checkpoint_token }`.
@@ -957,6 +1395,44 @@ declare const Amba: {
       checkpoint_token?: string;
     }) => Promise<SyncPullResult>;
   };
+  /**
+   * Automatic offline mutation queue (opt-in).
+   *
+   * Once enabled, a collection write (`insert` / `update` / `delete`) or a
+   * `track` that fails because the device is offline is buffered to a durable
+   * on-device outbox (AsyncStorage) instead of throwing — then replayed in
+   * order on the next {@link flush} (e.g. when your NetInfo listener detects
+   * reconnect). Replays reuse a per-op idempotency key so a write that reached
+   * the server before the connection dropped is never applied twice.
+   *
+   * This is distinct from `Amba.sync` (manual change replay): `offline` is the
+   * automatic, fire-and-forget safety net for ordinary writes.
+   *
+   * @example
+   * import NetInfo from "@react-native-community/netinfo";
+   * Amba.offline.enable();
+   * NetInfo.addEventListener((s) => { if (s.isConnected) Amba.offline.flush(); });
+   * await Amba.collections.insert("todos", { title: "Buy milk" }); // queues if offline
+   */
+  offline: {
+    /**
+     * Turn the outbox on. Idempotent. Returns a disable function (queued ops
+     * are NOT dropped — call `clear()` for that). Drive `flush()` from your own
+     * connectivity listener (e.g. NetInfo) since React Native has no global
+     * `online` event.
+     */
+    enable: () => (() => void);
+    /** Whether the outbox is currently enabled. */
+    isEnabled: () => boolean;
+    /** Count of writes awaiting replay. */
+    pendingCount: () => Promise<number>;
+    /** Snapshot the pending ops (a copy — safe to inspect). */
+    pending: () => Promise<OutboxOp[]>;
+    /** Force a replay attempt now. Resolves with `{ flushed, dropped, remaining }` (dropped = poisoned ops the server rejects on replay, removed so they cannot wedge the queue). */
+    flush: () => Promise<FlushResult>;
+    /** Drop every queued write without replaying. */
+    clear: () => Promise<void>;
+  };
   collections: {
     find: <T = unknown>(name: string, options?: FindOptions) => Promise<FindResponse<T>>;
     findOne: <T = unknown>(name: string, id: string) => Promise<T>;
@@ -982,8 +1458,7 @@ declare const Amba: {
      *
      * The server's `/count` route only honors `where` + `includeDeleted`
      * — passing other knobs (`limit`, `cursor`, etc.) returns
-     * `INVALID_QUERY_PARAM`. Mirrors the engine's `CollectionsModule::count`
-     * (`sdks/core/src/collections.rs`).
+     * `INVALID_QUERY_PARAM`. Mirrors the SDK core's `CollectionsModule::count`.
      */
     count: (name: string, where?: Filter) => Promise<number>;
     insert: <T = unknown>(name: string, row: Record<string, unknown>) => Promise<T>;
@@ -993,6 +1468,36 @@ declare const Amba: {
         deleted: boolean;
       };
     }>;
+    /**
+     * Optimistic insert — update a local view immediately, fire the real
+     * insert, and roll the view back if it fails. Thin convenience over the
+     * exported {@link withOptimistic}; for multi-step flows use that directly.
+     *
+     * Optimistic writes always hit the network directly — they are NOT diverted
+     * to the offline outbox even when `Amba.offline` is enabled. Optimistic UI
+     * needs an unambiguous outcome: this resolves only on a confirmed write and
+     * rejects (running your `rollback`) on any failure including being offline.
+     * To buffer-and-replay instead, use the plain `insert`/`update`/`delete`
+     * with the outbox on.
+     */
+    optimisticInsert: <T = unknown, TApply = unknown>(name: string, row: Record<string, unknown>, view: {
+      apply: () => TApply;
+      rollback: (applied: TApply) => void;
+    }) => Promise<T>;
+    /** Optimistic update — see {@link optimisticInsert}. */
+    optimisticUpdate: <T = unknown, TApply = unknown>(name: string, id: string, set: Record<string, unknown>, view: {
+      apply: () => TApply;
+      rollback: (applied: TApply) => void;
+    }) => Promise<T>;
+    /** Optimistic delete — see {@link optimisticInsert}. */
+    optimisticDelete: <TApply = unknown>(name: string, id: string, view: {
+      apply: () => TApply;
+      rollback: (applied: TApply) => void;
+    }) => Promise<{
+      data: {
+        deleted: boolean;
+      };
+    }>;
     where: {
       eq: (column: string, value: FilterValue) => Filter;
       ne: (column: string, value: FilterValue) => Filter;
@@ -1053,9 +1558,8 @@ declare const Amba: {
      * Returns a `Blob` — RN's fetch surfaces blobs natively
      * (`response.blob()`). NEW in 4.0.
      *
-     * Mirrors the engine's `StorageModule::download` in
-     * `sdks/core/src/storage.rs:247` — there is no
-     * `/v1/client/media/download` route on the server; the CDN URL
+     * Mirrors the SDK core's `StorageModule::download` — there is no
+     * `/v1/client/media/download` route on the server; the asset URL
      * on the asset row is the canonical fetch target.
      */
     download: (assetId: string) => Promise<Blob>;
@@ -1066,11 +1570,63 @@ declare const Amba: {
     getTokens: () => Promise<PushToken[]>;
     subscribe: (topic: string) => Promise<void>;
     unsubscribe: (topic: string) => Promise<void>;
+    /**
+     * Auto re-register the device push token when the OS rotates it.
+     *
+     * The OS can roll a device's push token (reinstall, restore, key roll);
+     * the new token must be re-registered or notifications stop arriving. Pass
+     * your notification library's token-refresh subscription primitive — e.g.
+     * `(h) => Notifications.addPushTokenListener((t) => h(t.data)).remove` on
+     * Expo, or the bare-FCM `onTokenRefresh` callback — and the SDK forwards
+     * each rotated token through the idempotent {@link register} path.
+     *
+     * Pass the token `platform` for your build — `"apns"` on iOS, `"fcm"` on
+     * Android (defaults to `"fcm"` when omitted). The bare RN SDK never reads
+     * `Platform.OS` itself (it's a pure-JS client that also loads under Node),
+     * so the caller supplies it; the Expo wrapper's
+     * `Amba.enablePushAutoRotation()` resolves it for you. Returns an
+     * unsubscribe function.
+     *
+     * @example
+     * import { Platform } from "react-native";
+     * import * as Notifications from "expo-notifications";
+     * const detach = Amba.push.enableAutoRotation(
+     *   (h) => Notifications.addPushTokenListener((t) => h(t.data)).remove,
+     *   Platform.OS === "ios" ? "apns" : "fcm",
+     * );
+     */
+    enableAutoRotation: (subscribe: TokenRefreshSubscribe, platform?: "apns" | "fcm") => (() => void);
+  };
+  /**
+   * On-device local notifications — `scheduleLocal` / `cancelLocal` /
+   * `listScheduledLocal`. These schedule notifications the device fires
+   * itself (reminders, streak nudges) with no server round-trip, distinct
+   * from remote push (`Amba.push.*`). Backed by `expo-notifications`
+   * (an optional peer dep that works in both Expo and bare RN apps),
+   * loaded lazily; methods throw a clear `LOCAL_NOTIFICATIONS_UNAVAILABLE`
+   * error if it isn't installed. See `./local-notifications.ts`.
+   */
+  notifications: {
+    scheduleLocal(input: ScheduleLocalNotificationInput): Promise<LocalNotificationHandle>;
+    cancelLocal(id: string): Promise<void>;
+    listScheduledLocal(): Promise<ScheduledLocalNotification[]>;
   };
   entitlements: {
     list: () => Promise<UserEntitlement[]>;
-    has: (name: string) => Promise<boolean>;
+    has: (entitlementId: string) => Promise<boolean>;
+    /**
+     * Restore purchases — re-sync the user's owned entitlements from the
+     * server and return the active set. Required for App Store review (3.1.1);
+     * wire it to a "Restore Purchases" button. Throws (access unchanged) if the
+     * server can't reach the validation engine — show a retry message.
+     */
+    restore: () => Promise<RestoreResult>;
   };
+  /**
+   * Subscription offerings — the packages your paywall renders, provider-
+   * neutral. Pass an `offeringId` for one offering; omit it for all.
+   */
+  offerings: (offeringId?: string) => Promise<OfferingsResult>;
   ai: {
     anthropic: {
       messages: {
@@ -1228,6 +1784,22 @@ declare const Amba: {
    * The real route is `/v1/client/messaging/conversations/:id/messages`.
    */
   messaging: {
+    /**
+     * Live conversation subscription. Returns a builder — call
+     * `.subscribe(cb)` to receive new messages live instead of polling:
+     *
+     *   const unsub = Amba.messaging
+     *     .conversation(conversationId)
+     *     .subscribe((change) => {
+     *       // change.op === "INSERT"; change.row is the new message
+     *     });
+     *   unsub(); // stop listening
+     *
+     * Delivery is scoped to conversation participants — you receive messages
+     * only if your session is a member of the conversation. Reconnects
+     * automatically with backoff. Requires an authenticated session.
+     */
+    conversation: <T = Message>(conversationId: string) => ConversationSubscription<T>;
     /**
      * `POST /v1/client/messaging/conversations` — create (or fetch
      * the existing direct) conversation. Idempotent for direct
@@ -1251,8 +1823,7 @@ declare const Amba: {
      * query filter (see `apps/api/src/routes/client/messaging.ts:358`,
      * which returns the full paginated page). We paginate forward
      * (newest-first, server page size 100) and find the matching id
-     * client-side, mirroring the engine's strategy in
-     * `sdks/core/src/messaging.rs:223`. Walks up to `MAX_PAGES`
+     * client-side, mirroring the SDK core's strategy. Walks up to `MAX_PAGES`
      * (5,000 messages total) before giving up to avoid an unbounded
      * loop against a giant conversation; callers with longer histories
      * should keep a local index instead of relying on this helper as a
@@ -1337,5 +1908,5 @@ declare const Amba: {
   };
 };
 //#endregion
-export { Achievement, AchievementProgress, AiMessage, AiMessageRequest, AiMessageResponse, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AuthResult, CatalogItem, Challenge, ChallengeProgress, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DiagnosticsEnvironment, EntitlementSource, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, Friendship, FriendshipState, Group, GroupCreate, GroupMember, GroupUpdate, InventoryItem, InvokeOptions, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortRef, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, MarkReadResult, MediaAsset, Message, MessageType, NotFilter, OnboardingStatus, OrFilter, OrderBy, PingResult, PresignData, PurchaseOption, PurchaseRequest, PurchaseResult, PushPlatform, PushToken, ReferralClaim, ReferralCode, Report, ReportRequest, Review, ReviewCreate, ReviewUpdate, Role, SDK_VERSION, SendMessageRequest, Session, SessionRecord, SocialProvider, Store, Streak, SyncChange, SyncConflict, SyncPullResult, SyncPullSince, SyncPushResult, User, UserEntitlement, UserPatch, XpBalance, XpTransaction };
+export { Achievement, AchievementProgress, AiMessage, AiMessageRequest, AiMessageResponse, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AuthResult, CatalogItem, Challenge, ChallengeProgress, CollectionSubscription, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationSubscription, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DiagnosticsEnvironment, EntitlementPeriodType, EntitlementStore, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, type FlushResult, Friendship, FriendshipState, type GamificationChange, type GamificationKind, GamificationSubscription, Group, GroupCreate, GroupMember, GroupUpdate, InventoryItem, InvokeOptions, type KvStore, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortRef, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, LocalNotificationHandle, LocalNotificationTrigger, type LocalNotificationsNamespace, MarkReadResult, MediaAsset, Message, type MessageChange, MessageType, NotFilter, Offering, OfferingPackage, OfferingProduct, OfferingsResult, OnboardingStatus, OrFilter, OrderBy, type OutboxOp, type OutboxOpKind, PingResult, PresignData, PurchaseOption, PurchaseRequest, PurchaseResult, PushPlatform, PushToken, type RealtimeChange, ReferralClaim, ReferralCode, Report, ReportRequest, RestoreResult, Review, ReviewCreate, ReviewUpdate, Role, type RowChangeOp, SDK_VERSION, ScheduleLocalNotificationInput, ScheduledLocalNotification, SendMessageRequest, Session, SessionRecord, SocialProvider, Store, Streak, type SubscribeOptions, SyncChange, SyncConflict, SyncPullResult, SyncPullSince, SyncPushResult, type TokenRefreshSubscribe, type Unsubscribe, User, UserEntitlement, UserPatch, XpBalance, XpTransaction, withOptimistic };
 //# sourceMappingURL=index.d.ts.map