@layers/amba-web 4.0.4 → 4.0.5

package/dist/index.d.ts

@@ -114,6 +114,38 @@ interface OrderBy {
   column: string;
   direction: "asc" | "desc";
 }
+/**
+ * Eager-load related rows from another collection in the same `find` call,
+ * avoiding an N+1 round-trip per base row. Single-level (MVP).
+ *
+ * belongs-to — each base row's `localKey` column points at the related row:
+ *   { collection: "novels", localKey: "novel_id", as: "novel", single: true }
+ *   → row.novel = the matching novels row (or null)
+ *
+ * has-many — the related collection's `foreignKey` column points back at the
+ * base row's id:
+ *   { collection: "chapters", foreignKey: "novel_id", as: "chapters" }
+ *   → row.chapters = the matching chapters rows (array)
+ *
+ * The included collection's own read policy + soft-delete are honored.
+ */
+interface IncludeClause {
+  /** Target collection to eager-load from. */
+  collection: string;
+  /** belongs-to: FK column on the base row pointing at the target. */
+  localKey?: string;
+  /**
+   * Join column on the target. belongs-to: defaults to `id`. has-many:
+   * required — the FK column on the target pointing back at the base id.
+   */
+  foreignKey?: string;
+  /** Result key the nested data lands under on each base row. */
+  as: string;
+  /** belongs-to only: nest a single object instead of an array. */
+  single?: boolean;
+  /** has-many only: cap related rows per base row (default 100, max 1000). */
+  limit?: number;
+}
 interface FindOptions {
   filter?: Filter;
   order?: OrderBy[];
@@ -121,12 +153,61 @@ interface FindOptions {
   cursor?: string;
   select?: string[];
   include_deleted?: boolean;
+  /** Eager-load related rows from other collections (kills N+1). */
+  include?: IncludeClause[];
 }
 interface FindResponse<T> {
   data: T[];
   next_cursor?: string | null;
   has_more: boolean;
 }
+/**
+ * Options for {@link Amba.collections.upsert}.
+ *
+ * `conflictTarget` is the set of columns covered by the unique index the
+ * upsert arbitrates on (e.g. `["user_id", "kind"]`). Every column must be
+ * present in the inserted row. `onConflict: "ignore"` keeps the existing
+ * row and returns it; `"update"` merges the supplied columns into it.
+ */
+interface UpsertOptions {
+  onConflict: "ignore" | "update";
+  conflictTarget: string[];
+}
+/** Result of {@link Amba.collections.deleteWhere} — the soft-deleted row count. */
+interface DeleteManyResult {
+  data: {
+    deleted: number;
+  };
+}
+/**
+ * One operation in an atomic multi-collection transaction
+ * ({@link Amba.collections.transaction}). Mirrors the single-row methods:
+ * `insert` carries `row` (+ optional upsert controls); `update` carries `id` +
+ * `set` (+ optional `expected` compare-and-set); `delete` carries `id` (+
+ * optional `expected`). `where` is an extra guard predicate AND'd onto the
+ * owner scope.
+ */
+interface TransactionOp {
+  collection: string;
+  op: "insert" | "update" | "delete";
+  id?: string;
+  row?: Record<string, unknown>;
+  set?: Record<string, unknown>;
+  where?: Record<string, unknown>;
+  expected?: Record<string, unknown>;
+  onConflict?: "ignore" | "update";
+  conflictTarget?: string[];
+}
+/** One per-op result returned by a committed transaction. */
+interface TransactionOpResult {
+  index: number;
+  op: "insert" | "update" | "delete";
+  collection: string;
+  id: string | null;
+  created?: boolean;
+  deleted?: boolean;
+  row?: Record<string, unknown>;
+}
 interface MediaAsset {
   id: string;
   bucket: string;
@@ -152,27 +233,120 @@ 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;
+  /** ISO-8601 duration display hint (e.g. "P1M", "P1Y"). */
+  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;
+  /** Whether this is the default offering to show. */
+  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;
   content: unknown;
 }
+/**
+ * A single vendor-neutral image for vision (multimodal) prompts. Provide a
+ * remote `url` OR base64 `data` (+ optional `mime`). Amba maps it to the
+ * model's native image format — you never touch provider-specific shapes.
+ */
+interface AiImageInput {
+  /** Remote image URL. Use this OR `data`, not both. */
+  url?: string;
+  /** Base64-encoded image bytes (no `data:` prefix). */
+  data?: string;
+  /** MIME type for a base64 image (e.g. `"image/png"`). Defaults to image/png. */
+  mime?: string;
+}
+/** A vendor-neutral content block inside a message's `content` array. */
+type AiContentBlock = {
+  type: "text";
+  text: string;
+} | {
+  type: "image";
+  url?: string;
+  data?: string;
+  mime?: string;
+};
 interface AiMessageRequest {
   prompt_slug: string;
   variables?: Record<string, unknown>;
   messages?: AiMessage[];
+  /**
+   * Image(s) to send to a vision-capable prompt. They attach to the last user
+   * message as vendor-neutral content blocks; the backend maps them to the
+   * model's native image format. The prompt's model must be vision-capable, or
+   * the call returns `ai_model_not_multimodal`. Omit for text-only prompts.
+   */
+  images?: AiImageInput[];
   max_tokens?: number;
   temperature?: number;
   enable_prompt_cache?: boolean;
+  /**
+   * Opt into a streamed (SSE) response from the backend. NOTE: the buffered
+   * `ai.anthropic.messages.create()` decodes a single JSON envelope, so it
+   * ignores this flag — to consume streamed tokens use the dedicated
+   * `ai.anthropic.messages.stream()` / `ai.openai.chat.completions.stream()`
+   * methods, which set `stream: true` for you and yield text deltas as they
+   * arrive plus a final usage event. The field exists so the request type
+   * matches the backend contract.
+   */
+  stream?: boolean;
 }
 interface AiUsage {
   input_tokens: number;
@@ -185,6 +359,13 @@ interface AiMessageResponse {
   usage: AiUsage;
   stop_reason?: string | null;
   model: string;
+  /**
+   * Computed USD cost of this call (input + output + cache token rates,
+   * summed server-side). `null` when the model isn't in the cost table — the
+   * call still succeeds; the cost is just unattributed. Read it to surface
+   * per-call spend without a separate analytics round-trip.
+   */
+  cost_usd?: number | null;
 }
 /**
  * Resolved remote config returned by `config.fetch()`.
@@ -723,6 +904,60 @@ interface MediaListResponse {
   data: MediaAsset[];
   next_cursor?: string | null;
 }
+/** A single asset within a media catalog, resolved to a public URL. */
+interface MediaCatalogItem {
+  media_id: string;
+  position: number;
+  caption?: string | null;
+  metadata: Record<string, unknown>;
+  filename: string;
+  mime_type: string;
+  /** Stable, long-cacheable public URL for the asset. */
+  url: string;
+  thumbnail_url?: string | null;
+  alt_text?: string | null;
+  blurhash?: string | null;
+}
+/**
+ * A curated, slug-addressable bundle of media assets fetched in one call.
+ * Items are returned in their configured order.
+ */
+interface MediaCatalog {
+  slug: string;
+  name: string;
+  description?: string | null;
+  metadata: Record<string, unknown>;
+  updated_at: string;
+  items: MediaCatalogItem[];
+}
+/**
+ * One rule a candidate event would trigger, as returned by
+ * `Amba.events.explain`. `would` describes the effect that WOULD be produced
+ * if the event were tracked for real; `note` (when present) flags a per-user
+ * gate (daily limit, cooldown, balance cap) that would suppress or reduce it.
+ */
+interface ExplainMatchedRule {
+  rule_type: "xp" | "currency_grant" | "feed" | "streak" | "webhook";
+  rule_id: string;
+  name: string;
+  would: Record<string, unknown>;
+  note?: string;
+}
+/**
+ * Result of a read-only event rule dry-run (`Amba.events.explain`). Producing
+ * this commits no side effect — it is a preview of what tracking the event
+ * would do across XP, currency grants, feed items, streaks, and webhooks.
+ */
+interface EventExplainResult {
+  event: {
+    name: string;
+    properties: Record<string, unknown>;
+    user_id: string | null;
+  };
+  matched: ExplainMatchedRule[];
+  evaluated_surfaces: string[];
+  unmatched_reason_samples?: string[];
+}
 /**
  * Options for `Amba.collections.findNearest`.
  *
@@ -745,6 +980,46 @@ interface NearestOptions {
 interface NearestResponse<T> {
   data: T[];
 }
+/**
+ * When a local notification should fire. Exactly one shape:
+ *
+ *   - `{ at: Date }`            — fire once at an absolute time.
+ *   - `{ inSeconds, repeats? }` — fire after a relative delay.
+ *
+ * Local notifications are scheduled and fired by the device itself, with
+ * no server involvement — distinct from remote push (`Amba.push.*`).
+ * Browser scheduling is partial; see `notifications.scheduleLocal`.
+ */
+type LocalNotificationTrigger = {
+  at: Date | string;
+} | {
+  inSeconds: number;
+  repeats?: boolean;
+};
+/** Input to `Amba.notifications.scheduleLocal`. */
+interface ScheduleLocalNotificationInput {
+  /** Optional stable id; omit to let the platform mint one. */
+  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/realtime.d.ts
 /**
@@ -843,6 +1118,184 @@ declare class ConversationSubscription<T = unknown> {
   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.
+ *
+ *   const unsub = Amba.gamification.subscribe((change) => {
+ *     // change.kind: "xp" | "level" | "achievement" | "streak"
+ *     // change.data: the new state
+ *   });
+ *   unsub(); // stop listening
+ *
+ * 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/ai-stream.d.ts
+/** A streamed token delta — append `text` to your running output buffer. */
+interface AiStreamDelta {
+  type: "delta";
+  /** The incremental text the model just produced. */
+  text: string;
+}
+/**
+ * Terminal event. Emitted once when the stream completes cleanly. `usage`
+ * carries the token accounting accumulated across the stream (zeroed fields
+ * when the vendor didn't report a given counter); `model` / `stopReason` are
+ * populated when the vendor surfaced them.
+ */
+interface AiStreamDone {
+  type: "done";
+  usage: AiUsage;
+  model?: string;
+  stopReason?: string | null;
+}
+/** Vendor-neutral event yielded by the streaming AI methods. */
+type AiStreamEvent = AiStreamDelta | AiStreamDone;
+/** Options accepted by the streaming AI methods. */
+interface AiStreamOptions {
+  /**
+   * Optional callback invoked for every text delta as it arrives — a
+   * convenience over iterating, useful when you only care about appending
+   * tokens to the UI. Fires in addition to the yielded `delta` events.
+   */
+  onChunk?: (text: string) => void;
+}
+//#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/error.d.ts
 /**
@@ -862,13 +1315,38 @@ declare class ConversationSubscription<T = unknown> {
  * `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;
+  /**
+   * Server-side request / trace id (the `X-Amba-Request-Id` response
+   * header, falling back to the `request_id` field in the standard error
+   * envelope). Present on errors thrown by `Amba.functions.invoke()` so a
+   * failed run can be correlated with server logs
+   * (`functions logs --request-id <traceId>`). `undefined` when the failure
+   * happened before a response was received (e.g. a transport error).
+   */
+  traceId?: string;
   constructor(code: AmbaApiErrorCode, message: string, details?: unknown);
 }
 //#endregion
+//#region src/local-notifications.d.ts
+/**
+ * The web `notifications` namespace. Web capability is partial — see the
+ * module-level doc. The returned handle includes `scheduledVia` so apps
+ * can detect whether the notification was handed to the OS
+ * (`"os-trigger"`) or relies on an in-page timer (`"timer"`).
+ */
+declare const notifications: {
+  scheduleLocal(input: ScheduleLocalNotificationInput): Promise<LocalNotificationHandle & {
+    scheduledVia: "os-trigger" | "timer";
+  }>;
+  cancelLocal(id: string): Promise<void>;
+  listScheduledLocal(): Promise<ScheduledLocalNotification[]>;
+};
+type LocalNotificationsNamespace = typeof notifications;
+//#endregion
 //#region src/index.d.ts
 /** Options for `Amba.functions.invoke`. */
 interface InvokeOptions {
@@ -876,6 +1354,18 @@ interface InvokeOptions {
   method?: "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
   /** Extra headers merged on top of the injected auth headers. */
   headers?: Record<string, string>;
+  /**
+   * Called with the server-side request / trace id (the
+   * `X-Amba-Request-Id` response header) as soon as a response is
+   * received — on both success and failure. Use it to correlate a run with
+   * server logs (`functions logs --request-id <traceId>`). `null` when the
+   * server returned no trace id (e.g. a pre-auth rejection that doesn't
+   * stamp the header).
+   *
+   * The same id is also attached to any thrown `AmbaApiError` as
+   * `error.traceId`, so error-path correlation works without a callback.
+   */
+  onTraceId?: (traceId: string | null) => void;
 }
 /**
  * Top-level SDK namespace.
@@ -925,6 +1415,23 @@ declare const Amba: {
     track: (event: string, properties?: Record<string, unknown>, options?: {
       telemetry?: boolean;
     }) => Promise<void>;
+    /**
+     * Dry-run an event against the rule engine WITHOUT firing it. Returns
+     * which rules would match and what each WOULD produce — XP awards,
+     * currency grants, feed items, streak qualification, and webhook
+     * deliveries — so you can predict the consequences of a `track` call
+     * before committing any side effect. Nothing is written.
+     *
+     * Pass `{ userId }` to also preview per-user gating (daily limits,
+     * cooldowns, balance caps); omit it for the user-independent base match.
+     *
+     * @example
+     * const plan = await Amba.events.explain('lesson_completed', { score: 90 });
+     * // plan.matched → [{ rule_type: 'xp', would: { xp_delta: 25 }, ... }, ...]
+     */
+    explain: (event: string, properties?: Record<string, unknown>, options?: {
+      userId?: string | null;
+    }) => Promise<EventExplainResult>;
   };
   /** Authentication flows. */
   auth: {
@@ -1172,6 +1679,54 @@ declare const Amba: {
         deleted: boolean;
       };
     }>;
+    /**
+     * Insert a row, resolving a unique-index conflict instead of failing.
+     *
+     * With `options.onConflict: "ignore"` a conflicting row is left
+     * untouched and returned; with `"update"` the supplied columns are
+     * merged into the existing row. `options.conflictTarget` names the
+     * unique-index columns to arbitrate on (e.g. `["user_id", "kind"]`) and
+     * every one must be present in `row`. Auto-RLS still applies — the
+     * ignore-fallback / merge is scoped to the caller's own rows.
+     *
+     * @example
+     * await Amba.collections.upsert("prefs",
+     *   { kind: "theme", value: "dark" },
+     *   { onConflict: "update", conflictTarget: ["kind"] });
+     */
+    upsert: <T = unknown>(name: string, row: Record<string, unknown>, options: UpsertOptions) => Promise<T>;
+    /**
+     * Bulk soft-delete every row matching `filter`. Returns the count of
+     * rows deleted. Auto-RLS scopes the delete to the caller's own rows;
+     * soft-deleted rows can be brought back with {@link restore}.
+     *
+     * @example
+     * const { data } = await Amba.collections.deleteWhere(
+     *   "todos", Amba.collections.where.eq("status", "done"));
+     * console.log(`${data.deleted} removed`);
+     */
+    deleteWhere: (name: string, filter: Filter) => Promise<DeleteManyResult>;
+    /**
+     * Restore a previously soft-deleted row by id (clears `deleted_at`).
+     * Returns the restored row. Only rows currently soft-deleted and owned
+     * by the caller can be restored; anything else resolves as not-found.
+     */
+    restore: <T = unknown>(name: string, id: string) => Promise<T>;
+    /**
+     * Run an ordered list of writes (insert / update / delete, across any
+     * collections) as ONE atomic transaction. The whole batch commits, or — if
+     * any op fails — rolls back entirely; a partial multi-write can never
+     * persist. Resolves to the per-op results; throws naming the failing op
+     * index (`details.opIndex`) on rollback. Each op honors the same auto-RLS /
+     * owner-scoping / compare-and-set rules as the single-row methods.
+     *
+     * @example
+     * await Amba.collections.transaction([
+     *   { collection: "carts", op: "insert", row: { sku: "widget", qty: 2 } },
+     *   { collection: "inventory", op: "update", id: invId, set: { reserved: 2 } },
+     * ]);
+     */
+    transaction: (operations: TransactionOp[]) => Promise<TransactionOpResult[]>;
     /**
      * Vector-search the collection (SDK 4.0). Returns the `k` nearest
      * neighbors of `options.query_vector` against the column named
@@ -1191,6 +1746,45 @@ declare const Amba: {
      * a bare number on the JS side.
      */
     count: (name: string, filter?: Filter) => Promise<number>;
+    /**
+     * Optimistic insert — update a local view immediately, fire the real
+     * insert, and roll the local view back if it fails. The reconcile is your
+     * own (replace the temporary local row with the server's authoritative
+     * row in your `apply`/`rollback` handlers). Thin convenience over the
+     * exported {@link withOptimistic} so the common single-write case reads
+     * clean; for multi-step flows use `withOptimistic` 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 server 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.
+     *
+     * @example
+     * await Amba.collections.optimisticInsert("todos", draft, {
+     *   apply: () => { const prev = todos; setTodos([...todos, draft]); return prev; },
+     *   rollback: (prev) => setTodos(prev),
+     * });
+     */
+    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;
+      };
+    }>;
     /** Filter DSL helpers — pass into `find({ filter: f })`. */
     where: {
       eq: (column: string, value: FilterValue) => Filter;
@@ -1220,7 +1814,7 @@ declare const Amba: {
       retentionDays?: number;
     }) => Promise<PresignData>;
     /**
-     * Complete-flow upload: presign → PUT to R2 → commit.
+     * Complete-flow upload: presign → PUT to object storage → commit.
      * Returns the finalized MediaAsset.
      */
     upload: (params: {
@@ -1238,7 +1832,7 @@ declare const Amba: {
     list: (prefix?: string) => Promise<MediaListResponse>;
     /**
      * Soft-delete the asset (SDK 4.0). Accepts the asset id returned
-     * by `presign` / `commit` / `list`. The corresponding R2 object
+     * by `presign` / `commit` / `list`. The corresponding storage object
      * is removed asynchronously on the server.
      */
     delete: (assetId: string) => Promise<void>;
@@ -1247,11 +1841,23 @@ declare const Amba: {
      * the Uint8Array returned by the engine, so consumers can
      * call `.text()` / `.arrayBuffer()` / `.stream()` directly or
      * pipe to a `URL.createObjectURL()` for preview. The two-step
-     * fetch (asset metadata → CDN GET) is handled server-side on
-     * the WASM side; this method is single-call from the consumer.
+     * fetch (asset metadata → CDN GET) is handled inside the SDK
+     * core; this method is single-call from the consumer.
      */
     download: (assetId: string) => Promise<Blob>;
   };
+  /** Curated public-asset catalogs. */
+  media: {
+    /**
+     * Fetch a public media catalog by slug
+     * (`GET /v1/client/media/catalogs/:slug`). A catalog is a named,
+     * curated bundle of assets your app loads in one call — each item
+     * resolves to a stable, long-cacheable public URL, returned in the
+     * order configured for the catalog. Only catalogs published as public
+     * are readable; the call needs the client key but no signed-in user.
+     */
+    catalog: (slug: string) => Promise<MediaCatalog>;
+  };
   /** Offline change replay (SDK 4.0). */
   sync: {
     /**
@@ -1272,6 +1878,53 @@ declare const Amba: {
      */
     pullChanges: (since: PullChangesCursor) => Promise<PullChangesResult>;
   };
+  /**
+   * 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
+   * local outbox instead of throwing — then replayed in order the moment
+   * connectivity returns. Replays reuse a per-op idempotency key so a write
+   * that actually 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
+   * Amba.offline.enable();          // call once after configure()
+   * await Amba.collections.insert("todos", { title: "Buy milk" }); // queues if offline
+   * // ...reconnect...
+   * console.log(await Amba.offline.pendingCount()); // drains automatically
+   */
+  offline: {
+    /**
+     * Turn the outbox on and start auto-flushing on reconnect. Idempotent —
+     * a repeat call detaches the prior `online` listener before re-attaching,
+     * so it never stacks listeners. Immediately attempts a flush in case ops
+     * were persisted in a prior session. Returns a disable function that
+     * detaches the reconnect listener (queued ops are NOT dropped — call
+     * `clear()` for that).
+     *
+     * The disabler is tied to THIS activation: once a later `enable()` (or a
+     * `configure()`) supersedes it, calling it is a no-op — so a stale disabler
+     * can never turn a freshly re-enabled outbox off.
+     */
+    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 (also runs automatically on reconnect).
+     * Resolves with `{ flushed, dropped, remaining }` (dropped = ops the server rejected deterministically on replay, removed so they cannot wedge the queue).
+     */
+    flush: () => Promise<FlushResult>;
+    /** Drop every queued write without replaying. */
+    clear: () => Promise<void>;
+  };
   /** Push notifications. */
   push: {
     register: (token: string, platform: PushPlatform, bundleId?: string) => Promise<PushToken>;
@@ -1279,17 +1932,97 @@ declare const Amba: {
     getTokens: () => Promise<PushToken[]>;
     subscribe: (topic: string) => Promise<void>;
     unsubscribe: (topic: string) => Promise<void>;
+    /**
+     * Auto re-register the device's Web Push subscription when the browser
+     * rotates it.
+     *
+     * The browser can silently roll a push subscription (key rollover,
+     * permission re-grant); when it does, the service worker fires
+     * `pushsubscriptionchange` and the old endpoint stops delivering. Call
+     * this from your service worker (where that event fires) and the SDK
+     * re-registers the fresh endpoint through the idempotent
+     * {@link register} path automatically.
+     *
+     * No-op (returns a no-op detacher) in runtimes without service-worker /
+     * push support, so it's safe to call unconditionally. Returns an
+     * unsubscribe function.
+     *
+     * @example
+     * // in your service worker
+     * Amba.push.enableAutoRotation();
+     */
+    enableAutoRotation: () => (() => void);
+  };
+  /**
+   * On-device local notifications — `scheduleLocal` / `cancelLocal` /
+   * `listScheduledLocal`. Fire from the device without a server
+   * round-trip (reminders, streak nudges), distinct from remote push
+   * (`Amba.push.*`). Browser scheduling is partial: the OS-backed path
+   * needs the experimental Notification Triggers API + an active Service
+   * Worker (Chromium today); without it the SDK falls back to an in-page
+   * timer and reports `scheduledVia: "timer"` so the degradation is
+   * visible — never a silent no-op. See `./local-notifications.ts`.
+   */
+  notifications: {
+    scheduleLocal(input: ScheduleLocalNotificationInput): Promise<LocalNotificationHandle & {
+      scheduledVia: "os-trigger" | "timer";
+    }>;
+    cancelLocal(id: string): Promise<void>;
+    listScheduledLocal(): Promise<ScheduledLocalNotification[]>;
   };
-  /** RevenueCat/App Store/Stripe entitlements. */
+  /** Subscription entitlements — feature gates resolved server-side. */
   entitlements: {
     list: () => Promise<UserEntitlement[]>;
     has: (name: 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. Rejects (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` to fetch one offering; omit it for all.
+   */
+  offerings: (offeringId?: string) => Promise<OfferingsResult>;
   /** LLM proxy. */
   ai: {
     anthropic: {
       messages: {
         create: (request: AiMessageRequest) => Promise<AiMessageResponse>;
+        /**
+         * Stream the response token-by-token instead of waiting for the full
+         * buffered reply. Returns an async iterable of vendor-neutral events:
+         * zero or more `{type:'delta', text}` as tokens arrive, then exactly
+         * one `{type:'done', usage, model, stopReason}` when the stream ends.
+         *
+         * ```ts
+         * let answer = "";
+         * for await (const ev of Amba.ai.anthropic.messages.stream({ prompt_slug: "chat" })) {
+         *   if (ev.type === "delta") answer += ev.text;
+         *   else console.log("tokens:", ev.usage.output_tokens);
+         * }
+         * ```
+         *
+         * Pass `{ onChunk }` to also receive each delta via callback. Throws
+         * an `AmbaApiError` on a transport failure or a non-2xx response.
+         */
+        stream: (request: AiMessageRequest, options?: AiStreamOptions) => AsyncGenerator<AiStreamEvent, void, unknown>;
+      };
+    };
+    openai: {
+      chat: {
+        completions: {
+          /**
+           * Stream an OpenAI-routed prompt token-by-token. Same event shape
+           * as `Amba.ai.anthropic.messages.stream` — the vendor split is just
+           * a stable wire path; the server resolves the real provider from the
+           * prompt's registered configuration.
+           */
+          stream: (request: AiMessageRequest, options?: AiStreamOptions) => AsyncGenerator<AiStreamEvent, void, unknown>;
+        };
       };
     };
   };
@@ -1301,19 +2034,37 @@ declare const Amba: {
    * hand-rolling `fetch` against a function URL, which leaves the call
    * unauthenticated (a footgun when the function holds secrets).
    *
+   * The return value is unchanged (the parsed body, typed `T`). To
+   * correlate a run with server logs, read the trace id additively:
+   * pass `options.onTraceId` to receive the `X-Amba-Request-Id` on every
+   * response, and on failure read `error.traceId` off the thrown
+   * `AmbaApiError`. Then `functions logs --request-id <traceId>` pulls the
+   * matching server log.
+   *
    * @example
    * const result = await Amba.functions.invoke<{ ok: boolean }>(
    *   'send_welcome_email',
    *   { to: 'user@example.com' },
+   *   { onTraceId: (id) => console.log('trace', id) },
    * );
    *
+   * @example
+   * try {
+   *   await Amba.functions.invoke('charge', { amount: 100 });
+   * } catch (err) {
+   *   if (err instanceof AmbaApiError) {
+   *     console.error(`failed (trace ${err.traceId}): ${err.message}`);
+   *   }
+   * }
+   *
    * @param name  The deployed function name.
    * @param body  JSON-serializable request body (omitted for GET).
-   * @param options  Method + extra headers.
+   * @param options  Method, extra headers, and an `onTraceId` callback.
    * @returns The parsed JSON response (or the raw text if not JSON).
    * @throws AmbaApiError on a network failure or a non-2xx response. When
    *   the function / router returns the standard `{ error: { code, message } }`
-   *   envelope, those surface as the thrown error's `code` + `message`.
+   *   envelope, those surface as the thrown error's `code` + `message`; the
+   *   server trace id (when present) is attached as `error.traceId`.
    */
   functions: {
     invoke: <T = unknown>(name: string, body?: unknown, options?: InvokeOptions) => Promise<T>;
@@ -1416,6 +2167,22 @@ declare const Amba: {
     getAll: () => Promise<Streak[]>;
     qualify: (streakKey: string) => Promise<Streak>;
   };
+  /**
+   * Live gamification updates for the signed-in user. Call `.subscribe(cb)` to
+   * receive xp / level / achievement / streak changes the instant they happen,
+   * instead of polling `xp.getBalance()` / `streaks.getAll()` on a timer.
+   *
+   * @example
+   * const unsub = Amba.gamification.subscribe((change) => {
+   *   // change.kind: "xp" | "level" | "achievement" | "streak"
+   *   if (change.kind === "level") showLevelUp(change.data.level);
+   * });
+   * // later: unsub();
+   *
+   * You only ever receive your own gamification changes — never another user's.
+   * Requires an authenticated session.
+   */
+  readonly gamification: GamificationSubscription;
   /** Activity feeds. */
   feeds: {
     getActivity: (feed?: string, cursor?: string) => Promise<FeedResponse>;
@@ -1635,7 +2402,7 @@ declare function getCoreWasm(): AmbaCoreWasm;
  * `verify-sdk-version-coherence` GH action gates every publish on the
  * pair agreeing (and matching the `web-v<X.Y.Z>` tag when tag-triggered).
  */
-declare const SDK_VERSION = "4.0.4";
+declare const SDK_VERSION = "4.0.5";
 //#endregion
-export { Achievement, AchievementProgress, AiMessage, AiMessageRequest, AiMessageResponse, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AppSession, AuthResult, CatalogItem, Challenge, ChallengeProgress, CollectionSubscription, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationParticipant, ConversationSubscription, 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, LeagueCohortMember, LeagueCohortView, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, MarkReadResult, MediaAsset, MediaListResponse, Message, type MessageChange, MessageType, NearestOptions, NearestResponse, NotFilter, OnboardingStatus, OrFilter, OrderBy, PingResult, PresignData, PullChangesCursor, PullChangesResult, PurchaseOption, PurchaseRequest, PurchaseResult, PushChangesResult, PushPlatform, PushToken, type RealtimeChange, ReferralClaim, ReferralCode, Report, ReportRequest, Review, ReviewCreate, ReviewUpdate, Role, type RowChangeOp, SDK_VERSION, SendMessageRequest, Session, SocialProvider, Store, Streak, type SubscribeOptions, SyncChange, SyncConflict, type Unsubscribe, User, UserEntitlement, XpBalance, XpTransaction, getCoreWasm };
+export { Achievement, AchievementProgress, AiContentBlock, AiImageInput, AiMessage, AiMessageRequest, AiMessageResponse, type AiStreamDelta, type AiStreamDone, type AiStreamEvent, type AiStreamOptions, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AppSession, AuthResult, CatalogItem, Challenge, ChallengeProgress, CollectionSubscription, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationParticipant, ConversationSubscription, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DeleteManyResult, DiagnosticsEnvironment, EntitlementPeriodType, EntitlementStore, EventExplainResult, ExplainMatchedRule, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, type FlushResult, Friendship, FriendshipState, type GamificationChange, type GamificationKind, GamificationSubscription, Group, GroupCreate, GroupMember, GroupUpdate, IncludeClause, InventoryItem, InvokeOptions, type KvStore, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortMember, LeagueCohortView, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, LocalNotificationHandle, LocalNotificationTrigger, type LocalNotificationsNamespace, MarkReadResult, MediaAsset, MediaCatalog, MediaCatalogItem, MediaListResponse, Message, type MessageChange, MessageType, NearestOptions, NearestResponse, NotFilter, Offering, OfferingPackage, OfferingProduct, OfferingsResult, OnboardingStatus, OrFilter, OrderBy, type OutboxOp, type OutboxOpKind, PingResult, PresignData, PullChangesCursor, PullChangesResult, PurchaseOption, PurchaseRequest, PurchaseResult, PushChangesResult, PushPlatform, PushToken, type RealtimeChange, ReferralClaim, ReferralCode, Report, ReportRequest, RestoreResult, Review, ReviewCreate, ReviewUpdate, Role, type RowChangeOp, SDK_VERSION, ScheduleLocalNotificationInput, ScheduledLocalNotification, SendMessageRequest, Session, SocialProvider, Store, Streak, type SubscribeOptions, SyncChange, SyncConflict, TransactionOp, TransactionOpResult, type Unsubscribe, UpsertOptions, User, UserEntitlement, XpBalance, XpTransaction, getCoreWasm, withOptimistic };
 //# sourceMappingURL=index.d.ts.map