@layers/amba-web 4.0.6 → 4.0.7

package/dist/index.browser.d.ts

@@ -0,0 +1,2437 @@
+import { AmbaCoreWasm } from "@layers/amba-core";
+
+//#region src/types.d.ts
+
+/**
+ * Public type surface for `@layers/amba-web`.
+ *
+ * Mirrors the amba API wire format. Field names match the wire format
+ * (snake_case) where it would cause confusion to translate; idiomatic
+ * camelCase is reserved for the SDK's own option objects.
+ */
+interface AmbaConfig {
+  /** Project id from the developer console or CLI (`proj_…`). */
+  projectId: string;
+  /** Client key from the developer console or CLI (`amba_ck_…`). */
+  clientKey: string;
+  /**
+   * Override the API base URL for non-prod environments.
+   * Defaults to `"https://api.amba.dev"`.
+   */
+  apiUrl?: string;
+  /**
+   * Base URL for `Amba.functions.invoke()`. Set this to call your deployed
+   * functions through a custom domain or a non-prod environment, e.g.
+   * `"https://api.example.com"` or `"https://<id>.staging.fn.amba.host"`.
+   * `invoke(name, body)` POSTs to `"<functionsBaseUrl>/<name>"`.
+   *
+   * When omitted, the SDK resolves the default host automatically on first
+   * use (one cached round-trip) — no configuration needed for production.
+   */
+  functionsBaseUrl?: string;
+  /**
+   * If `true`, blocks all telemetry until `setConsent(granted)` is called.
+   * Required for SOC2 / GDPR strict modes.
+   */
+  consentRequired?: boolean;
+  /** Verbose SDK logging. */
+  debug?: boolean;
+  /** Override the localStorage key prefix. Defaults to `"amba"`. */
+  storagePrefix?: string;
+  /**
+   * Advanced: explicit URL or RequestInfo for the @layers/amba-core WASM file.
+   * Browser bundlers should not need this; the browser entry supplies a
+   * bundler-safe core runtime automatically.
+   */
+  wasmUrl?: RequestInfo | URL;
+  /**
+   * Advanced: explicit compiled module, response, or bytes for the WASM core.
+   * Mutually exclusive with `wasmUrl`.
+   */
+  wasmModule?: Response | BufferSource | WebAssembly.Module;
+}
+type SocialProvider = "apple" | "google";
+type PushPlatform = "apns" | "fcm" | "web";
+interface User {
+  id: string;
+  email?: string | null;
+  /** E.164-normalized phone number set by SMS-OTP verify/link flows. */
+  phone?: string | null;
+  /** `true` once email-OTP verify or email-OTP link completed for this email. */
+  email_verified?: boolean;
+  /** `true` once SMS-OTP verify or SMS-OTP link completed for this phone. */
+  phone_verified?: boolean;
+  display_name?: string | null;
+  avatar_url?: string | null;
+  external_id?: string | null;
+  anonymous_id?: string | null;
+  auth_providers: string[];
+  properties: Record<string, unknown>;
+  first_seen_at?: string;
+  last_seen_at?: string;
+  created_at?: string;
+  updated_at?: string;
+}
+/**
+ * A single identifier attached to the current user — returned by
+ * `Amba.auth.getCurrentIdentifiers()`. `identifier_masked` is server-masked
+ * (phone last-4 with country-code prefix, `a***@domain` for email); the raw
+ * value stays server-side. Social providers (`apple`, `google`) have no
+ * value to surface — `identifier_masked` is `null` in that case.
+ */
+interface LinkedIdentifier {
+  provider: "sms_otp" | "email_otp" | "apple" | "google";
+  verified: boolean;
+  identifier_masked: string | null;
+}
+interface AuthResult {
+  session_token: string;
+  refresh_token: string;
+  user: User;
+  anonymous_id?: string | null;
+  expires_at?: string | null;
+}
+/**
+ * Snapshot of the current session as visible to the SDK consumer.
+ *
+ * `sessionToken` / `refreshToken` / `expiresAt` are SDK-managed and held
+ * internally for the auto-refresh dance, so they're empty strings on the
+ * consumer side — present for shape-compatibility. Callers who need to
+ * introspect should branch on `user` / `Amba.isAuthenticated`.
+ */
+interface Session {
+  sessionToken: string;
+  refreshToken: string;
+  user: User;
+  expiresAt: string;
+}
+type FilterValue = string | number | boolean | null | unknown[];
+interface ConditionFilter {
+  column: string;
+  op: string;
+  value?: FilterValue;
+}
+interface AndFilter {
+  and: Filter[];
+}
+interface OrFilter {
+  or: Filter[];
+}
+interface NotFilter {
+  not: Filter;
+}
+type Filter = ConditionFilter | AndFilter | OrFilter | NotFilter;
+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.
+ *
+ * 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;
+  /**
+   * Filtered include — an extra predicate on the related rows, in the
+   * server's where-DSL shape (`{ status: "published" }`,
+   * `{ score: { gte: 10 } }`). The target collection's own read policy +
+   * soft-delete still apply.
+   */
+  where?: Record<string, unknown>;
+  /**
+   * Projection on the included rows — only these columns are returned
+   * (join keys are handled internally).
+   */
+  select?: string[];
+  /**
+   * Nested include — eager-load relations OF the included rows
+   * (e.g. novels → chapters → comments). Max depth 3; max 10 clauses
+   * total per find.
+   */
+  include?: IncludeClause[];
+}
+interface FindOptions {
+  filter?: Filter;
+  order?: OrderBy[];
+  limit?: number;
+  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;
+  key: string;
+  url: string;
+  mime_type: string;
+  size_bytes: number;
+  width?: number | null;
+  height?: number | null;
+  retention_days?: number | null;
+  created_at: string;
+}
+interface PresignData {
+  upload_id: string;
+  upload_url: string;
+  upload_headers: Array<[string, string]>;
+  asset_id: string;
+}
+interface PushToken {
+  id: string;
+  token: string;
+  platform: PushPlatform;
+  bundle_id?: string | null;
+  created_at: string;
+}
+/**
+ * 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 {
+  /** Project-defined entitlement key (e.g. `"pro"`) — what `has()` checks. */
+  entitlement_id: string;
+  is_active: boolean;
+  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;
+  output_tokens: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+interface AiMessageResponse {
+  content: unknown[];
+  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()`.
+ *
+ * Server: `GET /v1/client/config` returns body `{ "data": { key → value, ... } }`
+ * plus an `ETag` response header carrying the version stamp. The SDK
+ * lifts the `data` map into `values` and parses the ETag prefix into
+ * `version`.
+ *
+ * `version` is `null` when the server didn't send an ETag (e.g. local
+ * dev with an empty config-versions row).
+ */
+interface ConfigBundle {
+  version: string | null;
+  values: Record<string, unknown>;
+}
+interface FlagAssignment {
+  name: string;
+  enabled: boolean;
+  variant?: string | null;
+  payload?: unknown;
+}
+/** Customer-facing environment label, derived server-side. */
+type DiagnosticsEnvironment = "production" | "staging" | "sandbox";
+interface PingResult {
+  /**
+   * `true` on a successful round-trip. `false` only when the server
+   * reached the route handler but couldn't resolve the lookup; in
+   * that case `error` carries a stable code string. Transport
+   * failures throw `AmbaApiError` and never produce a `PingResult`.
+   */
+  ok: boolean;
+  /**
+   * Project id the server resolved from the API key. Compare to the
+   * value you passed to `Amba.configure({ projectId })` — they should
+   * match.
+   */
+  server_project_id: string | null;
+  /** `production` / `staging` / `sandbox`, server-derived. */
+  environment: DiagnosticsEnvironment | null;
+  /**
+   * Last 4 hex chars of the sha256 of the API key the server saw.
+   * Pastes alongside the same suffix in the developer console UI.
+   */
+  key_fingerprint: string;
+  /**
+   * Server-measured handler latency, in milliseconds. Excludes
+   * client-side network time.
+   */
+  latency_ms: number;
+  /**
+   * `null` on success. On server-side failure, a stable code (e.g.
+   * `"DIAGNOSTICS_INTERNAL_ERROR"`).
+   */
+  error: string | null;
+}
+interface Achievement {
+  id: string;
+  key: string;
+  name: string;
+  description?: string | null;
+  icon_url?: string | null;
+  /** XP granted to the user on unlock. Mirrors the wire field `xp_reward`. */
+  xp_reward: number;
+  criteria: unknown;
+}
+interface AchievementProgress {
+  achievement_id: string;
+  key: string;
+  progress: number;
+  unlocked: boolean;
+  unlocked_at?: string | null;
+}
+interface Challenge {
+  id: string;
+  key: string;
+  name: string;
+  description?: string | null;
+  starts_at: string;
+  ends_at: string;
+  criteria: unknown;
+  reward: unknown;
+}
+interface ChallengeProgress {
+  challenge_id: string;
+  progress: number;
+  completed: boolean;
+  claimed: boolean;
+  completed_at?: string | null;
+  claimed_at?: string | null;
+}
+interface CurrencyBalance {
+  currency_code: string;
+  name: string;
+  is_premium: boolean;
+  balance: number;
+  lifetime_earned: number;
+  lifetime_spent: number;
+}
+interface CurrencyTransaction {
+  id: string;
+  app_user_id?: string;
+  currency_code: string;
+  amount: number;
+  balance_after: number;
+  transaction_type?: string;
+  source?: string;
+  reference_id?: string | null;
+  idempotency_key?: string | null;
+  created_at: string;
+}
+interface InventoryItem {
+  id: string;
+  catalog_item_id: string;
+  sku: string;
+  quantity: number;
+  acquired_at: string;
+  metadata: unknown;
+}
+interface PurchaseRequest {
+  sku: string;
+  quantity?: number;
+  currency_key?: string;
+}
+interface ConsumeRequest {
+  item_id: string;
+  quantity: number;
+}
+interface Leaderboard {
+  id: string;
+  key: string;
+  name: string;
+  period: string;
+  direction: string;
+  starts_at?: string | null;
+  ends_at?: string | null;
+}
+interface LeaderboardEntry {
+  rank: number;
+  user_id: string;
+  display_name?: string | null;
+  avatar_url?: string | null;
+  score: number;
+}
+interface Store {
+  id: string;
+  key: string;
+  name: string;
+}
+interface PurchaseOption {
+  id: string;
+  store_id: string;
+  sku: string;
+  name: string;
+  price_cents: number;
+  currency: string;
+  period?: string | null;
+  metadata: unknown;
+}
+interface PurchaseResult {
+  id: string;
+  user_id: string;
+  purchase_option_id: string;
+  status: string;
+  purchased_at: string;
+  receipt: unknown;
+}
+interface XpBalance {
+  user_id: string;
+  total_xp: number;
+  current_level: number;
+  xp_into_level: number;
+  xp_to_next_level: number;
+  updated_at: string;
+  /**
+   * XP earned in the current rolling window. The window is server-defined
+   * via the project's XP rules. Older servers that don't populate this
+   * field decode as `0`.
+   */
+  xp_this_period: number;
+}
+interface XpTransaction {
+  id: string;
+  delta: number;
+  reason?: string | null;
+  source?: string | null;
+  created_at: string;
+}
+interface Streak {
+  id: string;
+  /**
+   * Stable human-readable key, e.g. `"daily_play"`. Use this to qualify:
+   * `Amba.streaks.qualify('daily_play')`.
+   */
+  key: string;
+  /** Display name of the streak the user is on. */
+  name: string;
+  /** Current consecutive qualifying-event count. Resets to 0 on break. */
+  current_count: number;
+  /** All-time best `current_count` for this user + streak. */
+  longest_count: number;
+  /** ISO timestamp of the last successful qualify. */
+  last_qualified_at?: string | null;
+  updated_at: string;
+  /**
+   * Lifecycle state.
+   * - `"active"` — streak is alive
+   * - `"broken"` — user missed a period; `current_count` reset to 0
+   * - `"frozen"` — a shield protected the streak from a miss
+   */
+  status: 'active' | 'broken' | 'frozen';
+  /**
+   * Unused streak-shield count. Auto-granted per the streak's configured
+   * cadence, capped at the streak's `max_freezes`.
+   */
+  freezes_remaining: number;
+}
+interface FeedItem {
+  id: string;
+  actor_id: string;
+  verb: string;
+  object_type: string;
+  object_id: string;
+  target_type?: string | null;
+  target_id?: string | null;
+  data: unknown;
+  created_at: string;
+}
+interface FeedResponse {
+  data: FeedItem[];
+  next_cursor?: string | null;
+}
+type FriendshipState = "pending" | "accepted" | "blocked" | "declined";
+interface Friendship {
+  id: string;
+  user_id: string;
+  friend_id: string;
+  state: FriendshipState;
+  created_at: string;
+}
+interface Group {
+  id: string;
+  name: string;
+  description?: string | null;
+  avatar_url?: string | null;
+  created_by: string;
+  member_count: number;
+  created_at: string;
+  updated_at: string;
+  metadata: unknown;
+}
+interface GroupMember {
+  group_id: string;
+  user_id: string;
+  role: string;
+  joined_at: string;
+}
+interface GroupCreate {
+  name: string;
+  description?: string;
+  avatar_url?: string;
+  metadata?: unknown;
+}
+interface GroupUpdate {
+  name?: string;
+  description?: string;
+  avatar_url?: string;
+  metadata?: unknown;
+}
+type ConversationType = "direct" | "group";
+type MessageType = "text" | "image" | "system";
+interface Message {
+  id: string;
+  conversation_id: string;
+  sender_id: string;
+  body: string;
+  /** Server-tagged message kind. Defaults to `"text"` when omitted. */
+  message_type?: MessageType | null;
+  metadata: unknown;
+  created_at: string;
+}
+interface Conversation {
+  id: string;
+  /** `"direct"` or `"group"` — present on rows returned by the API. */
+  type?: ConversationType | null;
+  /** Group conversation name. `null` for direct conversations. */
+  name?: string | null;
+  /**
+   * Participant ids on the row. Optional because the API's POST
+   * `/conversations` response doesn't include them — only the
+   * list-endpoint does. SDK consumers should fall back to the
+   * server's richer `conversation_participants` shape if they need
+   * display names.
+   */
+  participants?: string[];
+  last_message?: Message | null;
+  metadata?: unknown;
+  created_at: string;
+  updated_at: string;
+}
+/**
+ * Request body for `Amba.messaging.createConversation`. Mirrors the
+ * server's `CreateConversationInput`. The caller is implicitly added
+ * to `participant_ids` — clients don't have to include their own
+ * `user_id`.
+ */
+interface CreateConversationRequest {
+  participant_ids: string[];
+  type?: ConversationType;
+  /** Optional name — only meaningful for `type === "group"`. */
+  name?: string;
+}
+/**
+ * Request body for `Amba.messaging.sendMessage`. The conversation id
+ * is a path parameter and is passed separately to the SDK method;
+ * this object is the JSON body the server reads.
+ */
+interface SendMessageRequest {
+  body: string;
+  message_type?: MessageType;
+  metadata?: Record<string, unknown>;
+}
+/** Pagination options for `Amba.messaging.listMessages`. */
+interface ListMessagesOptions {
+  limit?: number;
+  offset?: number;
+}
+/**
+ * Response shape from `Amba.messaging.markRead`. Mirrors the updated
+ * `conversation_participants` row the server returns.
+ */
+interface MarkReadResult {
+  conversation_id?: string | null;
+  app_user_id?: string | null;
+  last_read_at?: string | null;
+}
+/**
+ * A `conversation_participants` row — returned by
+ * `Amba.messaging.addParticipant`. All fields are optional so older
+ * servers that trim columns still decode.
+ */
+interface ConversationParticipant {
+  id?: string | null;
+  conversation_id?: string | null;
+  app_user_id?: string | null;
+  joined_at?: string | null;
+  last_read_at?: string | null;
+}
+interface Report {
+  id: string;
+  reporter_id: string;
+  target_type: string;
+  target_id: string;
+  reason: string;
+  status: string;
+  notes?: string | null;
+  created_at: string;
+  resolved_at?: string | null;
+}
+interface ReportRequest {
+  target_id: string;
+  reason: string;
+  notes?: string;
+}
+interface ReferralCode {
+  id: string;
+  code: string;
+  owner_id: string;
+  uses_count: number;
+  max_uses?: number | null;
+  expires_at?: string | null;
+  created_at: string;
+}
+interface ReferralClaim {
+  id: string;
+  code_id: string;
+  referrer_id: string;
+  referee_id: string;
+  reward: unknown;
+  claimed_at: string;
+}
+interface Review {
+  id: string;
+  author_id: string;
+  target_type: string;
+  target_id: string;
+  rating: number;
+  title?: string | null;
+  body?: string | null;
+  created_at: string;
+  updated_at: string;
+}
+interface ReviewCreate {
+  target_type: string;
+  target_id: string;
+  rating: number;
+  title?: string;
+  body?: string;
+}
+interface ReviewUpdate {
+  rating?: number;
+  title?: string;
+  body?: string;
+}
+interface Role {
+  id: string;
+  key: string;
+  name: string;
+  permissions: string[];
+}
+interface CatalogItem {
+  id: string;
+  sku: string;
+  name: string;
+  description?: string | null;
+  price_cents?: number | null;
+  currency?: string | null;
+  metadata: unknown;
+}
+interface ContentItem {
+  id: string;
+  channel: string;
+  title?: string | null;
+  body?: string | null;
+  data: unknown;
+  published_at: string;
+  user_state: unknown;
+}
+interface DeepLink {
+  id: string;
+  url: string;
+  short_code: string;
+  target_path?: string | null;
+  metadata: unknown;
+  created_at: string;
+}
+interface DeepLinkCreate {
+  target_path: string;
+  metadata?: unknown;
+  short_code?: string;
+}
+interface OnboardingStatus {
+  current_step: string | null;
+  completed_steps: string[];
+  remaining_steps: string[];
+  completed: boolean;
+  completed_at?: string | null;
+}
+/**
+ * Active customer-defined app session row. Returned by
+ * `Amba.sessions.list()`. Distinct from the auth-session token held by
+ * the SDK itself — these track app-foreground sessions the customer
+ * opted to record via `sessions.start` / `sessions.end` on the server.
+ */
+interface AppSession {
+  id: string;
+  user_id: string;
+  started_at: string;
+  ended_at?: string | null;
+  duration_secs?: number | null;
+  metadata?: unknown;
+}
+/**
+ * A single buffered mutation queued for replay. The client constructs
+ * these while offline and replays the batch via
+ * `Amba.sync.pushChanges(changes)` on reconnect.
+ */
+interface SyncChange {
+  entity_type: string;
+  entity_id: string;
+  /** `"insert" | "update" | "delete"`. */
+  action: string;
+  data?: unknown;
+  /** Client-side ISO-8601 timestamp the mutation was captured. */
+  client_timestamp: string;
+}
+interface SyncConflict {
+  entity_type: string;
+  entity_id: string;
+  /** Always `"server_wins"` in 4.0; reserved for future strategies. */
+  resolution: string;
+  server_data?: unknown;
+}
+interface PushChangesResult {
+  applied: number;
+  conflicts: SyncConflict[];
+  checkpoint_token: string;
+}
+interface PullChangesResult {
+  changes: SyncChange[];
+  checkpoint_token: string;
+  has_more?: boolean;
+}
+/**
+ * Cursor input to `Amba.sync.pullChanges`. `entity_type` scopes the
+ * pull to a single collection; `checkpoint_token` is the opaque cursor
+ * returned by the previous `pushChanges` / `pullChanges` reply.
+ */
+interface PullChangesCursor {
+  entity_type: string;
+  checkpoint_token?: string;
+}
+interface LeagueCohort {
+  id: string;
+  league_id: string;
+  /** ISO-8601 date (YYYY-MM-DD) that opens the cohort's 7-day window. */
+  week_start: string;
+  /** `"active" | "settling" | "closed"`. */
+  status: string;
+}
+interface LeagueTier {
+  id: string;
+  name: string;
+  tier_order: number;
+}
+interface LeagueCohortMember {
+  display_name?: string | null;
+  score: number;
+  rank: number;
+  /** `true` for the requesting user's own row (server-derived; no id leak). */
+  is_me?: boolean;
+}
+interface LeagueMembership {
+  cohort: LeagueCohort | null;
+  league: LeagueTier | null;
+  rank: number | null;
+  score: number;
+  member_count: number;
+}
+interface LeagueCohortView {
+  cohort: LeagueCohort | null;
+  league: LeagueTier | null;
+  members: LeagueCohortMember[];
+}
+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`.
+ *
+ * Spec note: the canonical 4.0 signature is `findNearest(name, vector, k, filter?)`,
+ * but the underlying server route requires a `vector_field` column name
+ * to scan against — the SDK widens the contract to a single options
+ * object so `vector_field` is unambiguous in TS. (Documented in the
+ * 4.0 migration guide.)
+ */
+interface NearestOptions {
+  /** Name of the column carrying the vector to compare against. */
+  vector_field: string;
+  /** Query vector. Length must match the column's configured dimensions. */
+  query_vector: number[];
+  /** Number of nearest neighbors to return. Must be > 0. */
+  k: number;
+  /** Optional WHERE filter applied before nearest-neighbor ranking. */
+  filter?: Filter;
+}
+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
+/**
+ * Live collection subscriptions for `@layers/amba-web` (PROTOTYPE — T13).
+ *
+ * Public surface is intentionally tiny and provider-agnostic:
+ *
+ *   const unsub = Amba.collection("messages")
+ *     .where("circle_id", circleId)
+ *     .subscribe((change) => {
+ *       // change.op is "INSERT" | "UPDATE" | "DELETE"
+ *       // change.row is the affected row
+ *     });
+ *   unsub(); // stop listening
+ *
+ * The transport (a streamed HTTP response) and the server-side fan-out
+ * mechanism are deliberately NOT named here — customers only ever see
+ * `.subscribe()`. Internally this opens a long-lived streamed GET to the
+ * realtime endpoint and reconnects with backoff if the connection drops.
+ *
+ * Delivery mirrors `Amba.collection.find()` exactly: you receive only rows
+ * your session owns, optionally narrowed by `.where(...)` equality filters.
+ */
+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.collection.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;
+/**
+ * Resolved at call time so the latest session token is used. Returns the
+ * auth headers, or `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.
+ *
+ *   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 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.
+ *
+ *   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
+/**
+ * Typed error class for the amba SDK + helper that converts arbitrary
+ * thrown values (native Error, plain objects, runtime-emitted errors)
+ * into a stable `AmbaApiError` instance.
+ *
+ * Callers can `instanceof`-narrow safely, branch on `.code`, and pull
+ * extra payload from `.details` (raw HTTP body, validation field paths,
+ * etc.). The wrapper methods on `Amba` wrap every async call in
+ * `toAmbaApiError`, so consumers see one error shape regardless of
+ * which layer (network, runtime, validation) failed.
+ */
+/**
+ * Stable error codes surfaced by the SDK. Strings rather than an enum
+ * so customers can extend with custom codes by simply throwing
+ * `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" | "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 {
+  /** HTTP method. Defaults to `"POST"`. */
+  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.
+ *
+ * Stateless from the JS side — all state lives in the SDK runtime. Calling
+ * `Amba.configure()` multiple times replaces the previous instance.
+ */
+declare const Amba: {
+  /**
+   * Initialize the SDK. Must be called once at app start.
+   *
+   * Seeds an `anonymous_id` from localStorage (if present) or generates a
+   * fresh one.
+   */
+  configure: (config: AmbaConfig) => Promise<void>;
+  /** Project id this SDK instance is scoped to. */
+  readonly projectId: string;
+  /** Anonymous id — stable per browser. */
+  readonly anonymousId: string;
+  /** Authenticated user id, if a session is live. */
+  readonly appUserId: string | undefined;
+  /** Whether a session token is currently held. */
+  readonly isAuthenticated: boolean;
+  /** Toggle verbose logging at runtime. */
+  setDebug: (enabled: boolean) => void;
+  /** Track engagement events. */
+  events: {
+    /**
+     * Track an event.
+     *
+     * The default route writes to the engagement meter — events that
+     * fan out to segments, workflows, and push. Pass
+     * `{ telemetry: true }` for high-volume, fire-and-forget events
+     * that DON'T need fan-out: UI button clicks, scroll-depth markers,
+     * game-loop telemetry. Telemetry events are billed at $0.10 per 1M
+     * overage vs $0.50 per 10K for engagement events — a ~500×
+     * difference that mirrors the underlying compute cost.
+     *
+     * Telemetry events are persisted and queryable via analytics, but
+     * skip segment recompute, streak qualification, currency grant
+     * rules, and `last_seen_at` updates.
+     *
+     * @example
+     * await Amba.events.track('purchase_completed', { amount: 9.99 });
+     * await Amba.events.track('scroll_depth', { px: 1024 }, { telemetry: true });
+     */
+    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: {
+    signInAnonymously: () => Promise<AuthResult>;
+    signInWithEmail: (email: string, password: string) => Promise<AuthResult>;
+    signUpWithEmail: (email: string, password: string) => Promise<AuthResult>;
+    /**
+     * Sign in with an Apple identity token (the JWT returned by Sign
+     * in with Apple). Replaces the SDK 3.x polymorphic
+     * `signInWithSocial('apple', token)` form — that surface is
+     * removed in 4.0.
+     */
+    signInWithApple: (identityToken: string) => Promise<AuthResult>;
+    /**
+     * Sign in with a Google ID token (the JWT returned by Google
+     * Sign-In). Replaces the SDK 3.x polymorphic
+     * `signInWithSocial('google', token)` form — that surface is
+     * removed in 4.0.
+     */
+    signInWithGoogle: (idToken: string) => Promise<AuthResult>;
+    /**
+     * Request a one-time passcode for `email`. The server emails a
+     * 6-digit code; the user types it into the app, then call
+     * `verifyEmailOtp(email, code)` to exchange for a session. Always
+     * resolves successfully regardless of email registration — the
+     * server uses uniform responses to prevent account enumeration.
+     */
+    requestEmailOtp: (email: string) => Promise<void>;
+    /**
+     * Exchange `(email, code)` for a session. Returns the same
+     * `AuthResult` shape as `signInWithEmail` and persists tokens for
+     * subsequent calls. Rejects with a single error code for every
+     * failure mode (wrong/expired/exhausted) — the server intentionally
+     * does not distinguish them to prevent enumeration.
+     */
+    verifyEmailOtp: (email: string, code: string) => Promise<AuthResult>;
+    /**
+     * Request a one-time passcode by SMS. `phone` MUST be E.164
+     * (starts with `+`, 8–15 total digits). The SDK rejects
+     * anything else with a `VALIDATION_ERROR` before the network
+     * call. Server sends a 6-digit code; user types it into the
+     * app, then call `verifySmsOtp(phone, code)` to exchange for
+     * a session. Always resolves successfully regardless of phone
+     * registration — uniform responses prevent enumeration.
+     */
+    requestSmsOtp: (phone: string) => Promise<void>;
+    /**
+     * Exchange `(phone, code)` for a session. Same shape +
+     * failure semantics as `verifyEmailOtp`. Persists tokens for
+     * subsequent calls.
+     */
+    verifySmsOtp: (phone: string, code: string) => Promise<AuthResult>;
+    /**
+     * Request a magic-link email for `email`. The server emails the
+     * link; the user clicks it, which delivers a one-time token back
+     * to the app. Exchange that token for a session with
+     * `verifyMagicLink(token)`. Always resolves successfully
+     * regardless of email registration (uniform responses prevent
+     * account enumeration).
+     */
+    requestMagicLink: (email: string) => Promise<void>;
+    /**
+     * Exchange a magic-link `token` for a session. Returns the same
+     * `AuthResult` shape as `signInWithEmail` and persists tokens for
+     * subsequent calls.
+     */
+    verifyMagicLink: (token: string) => Promise<AuthResult>;
+    /**
+     * Link an additional auth provider to the current session — used to
+     * upgrade an anonymous session to an identified one without losing
+     * the user's data. `provider` is one of the supported identity
+     * strings (e.g. `"apple"`, `"google"`); `credential` is the
+     * provider-issued token (identity-token / id-token / OTP code).
+     */
+    linkAccount: (provider: string, credential: string) => Promise<AuthResult>;
+    /**
+     * Attach a verified phone number to the **current session's user** —
+     * without minting new tokens and without changing `user_id`.
+     *
+     * Flow: call `requestSmsOtp(phone)` first to mail the 6-digit code,
+     * then call THIS instead of `verifySmsOtp` when the desired outcome
+     * is "decorate the current (often anonymous) user with this phone"
+     * rather than "switch to the user who owns this phone".
+     *
+     * Guarantees (symmetric to `linkEmailOtp`):
+     *
+     * - **Same `user_id`** before and after — collections, holds, XP,
+     *   `anonymous_id` all carry over.
+     * - **Session token unchanged.** The existing token stays valid;
+     *   `onAuthStateChange` does NOT fire (no rotation).
+     * - **Idempotent.** Re-linking the same phone to the same user
+     *   succeeds — no-op apart from `last_seen_at`.
+     * - **Collision.** If the phone is already verified to a different
+     *   user, throws an error with `code = "PHONE_ALREADY_LINKED"` and
+     *   `details.conflicting_user_id` populated. The caller decides
+     *   whether to abort or switch identities via `verifySmsOtp`.
+     *
+     * Requires an active session — throws `UNAUTHORIZED` otherwise.
+     *
+     * @returns the updated user record (with `phone` set and
+     *   `phone_verified = true`).
+     */
+    linkSmsOtp: (phone: string, code: string) => Promise<User>;
+    /**
+     * Attach a verified email to the current session's user. Symmetric
+     * to `linkSmsOtp` — see that for the full guarantee list. Collision
+     * code is `EMAIL_ALREADY_LINKED`.
+     */
+    linkEmailOtp: (email: string, code: string) => Promise<User>;
+    /**
+     * Upgrade an anonymous (or any current) session by attaching an
+     * email + password credential — converting the current user in place
+     * to an email-identified account so its data (streak, library,
+     * progress, `anonymous_id`) is preserved rather than minting a new
+     * user.
+     *
+     * Guarantees (symmetric to `linkEmailOtp`):
+     *
+     * - **Same `user_id`** before and after.
+     * - **Session token unchanged.** No rotation; `onAuthStateChange`
+     *   does NOT fire.
+     * - **Idempotent.** Re-linking the same email to the same user
+     *   succeeds.
+     * - **Collision.** If the email is already owned by a different user,
+     *   throws an error with `code = "EMAIL_ALREADY_LINKED"` and
+     *   `details.conflicting_user_id` populated.
+     *
+     * After linking, the user can sign in with `signInWithEmail(email,
+     * password)`. Requires an active session — throws `UNAUTHORIZED`
+     * otherwise.
+     *
+     * @returns the updated user record (with `email` set and
+     *   `email_verified = true`).
+     */
+    linkEmailPassword: (email: string, password: string) => Promise<User>;
+    /**
+     * Detach the SMS-OTP identifier from the current session's user.
+     * Refused with `LAST_IDENTIFIER` if this would leave the account
+     * with no recoverable identifier (link another first, then unlink).
+     * No token rotation.
+     */
+    unlinkSmsOtp: () => Promise<User>;
+    /** Detach the email-OTP identifier. Same guarantees as `unlinkSmsOtp`. */
+    unlinkEmailOtp: () => Promise<User>;
+    /** Detach the Apple social identity from the current session's user. */
+    unlinkApple: () => Promise<User>;
+    /** Detach the Google social identity from the current session's user. */
+    unlinkGoogle: () => Promise<User>;
+    /**
+     * Snapshot the identifier providers attached to the current
+     * session's user. Lets a host app gate "should I show the verify-
+     * email prompt" without a profile round-trip.
+     *
+     * Identifier values come back **masked** — raw values stay
+     * server-side.
+     */
+    getCurrentIdentifiers: () => Promise<LinkedIdentifier[]>;
+    signOut: (rotateAnonymousId?: boolean) => Promise<void>;
+    refresh: () => Promise<AuthResult>;
+    me: () => Promise<User>;
+    /**
+     * Snapshot the current session, or `null` if no session is live.
+     * sessionToken/refreshToken/expiresAt come back as empty strings —
+     * they're SDK-managed and not read-back-able from the core. Use
+     * `Amba.isAuthenticated` if you only need the boolean.
+     */
+    getSession: () => Promise<Session | null>;
+    /**
+     * Stable anonymous identifier (kept in memory by the SDK runtime).
+     * Sync today, async for parity with the RN/native shape where the
+     * platform may need to await a persistence read.
+     */
+    getAnonymousId: () => Promise<string>;
+    /**
+     * Subscribe to session changes. Fires after every `signIn*`,
+     * `signUp*`, `refresh`, and `signOut` call. Returns an
+     * unsubscribe function — call it to remove the callback.
+     *
+     * Does NOT fire an initial snapshot when subscribed; call
+     * `getSession()` once after subscribing if you need the
+     * current state up front.
+     */
+    onAuthStateChange: (cb: (session: Session | null) => void) => (() => void);
+  };
+  /** Profile read/update (SDK 4.0). */
+  users: {
+    /**
+     * Get a user profile. `userId` omitted → current user
+     * (`GET /v1/client/users/me`); `userId` set → public-safe profile
+     * of the other user (`GET /v1/client/users/{id}`).
+     */
+    get: (userId?: string) => Promise<User>;
+    /**
+     * Update a profile. Two shapes:
+     *   - `update(patch)` — current user (`PATCH /users/me`).
+     *   - `update(userId, patch)` — admin-style cross-user update
+     *     (`PATCH /users/{id}`); the server requires the caller to
+     *     hold `users:write` and 403s otherwise.
+     *
+     * Allowed keys (both shapes): `display_name`, `avatar_url`,
+     * `properties`, `timezone`.
+     */
+    update: {
+      (patch: Partial<User>): Promise<User>;
+      (userId: string, patch: Partial<User>): Promise<User>;
+    };
+  };
+  /** List + revoke customer-recorded app sessions (SDK 4.0). */
+  sessions: {
+    /** `GET /v1/client/sessions` — list the caller's app sessions. */
+    list: () => Promise<AppSession[]>;
+    /**
+     * `POST /v1/client/sessions/:id/end` — end the session with the
+     * given id. The 4.0 `revoke` contract returns unit; customers who
+     * need the ended row should use the lower-level `sessions.end`
+     * helper on the core (not exposed on the public SDK).
+     */
+    revoke: (sessionId: string) => Promise<void>;
+  };
+  /**
+   * Live collection subscriptions (SDK 4.0). Returns a builder — chain
+   * `.where(column, value)` to narrow, then `.subscribe(cb)` to start
+   * receiving row changes. `subscribe` returns an unsubscribe handle.
+   *
+   * @example
+   * const unsub = Amba.collection("messages")
+   *   .where("circle_id", circleId)
+   *   .subscribe((change) => {
+   *     // change.op: "INSERT" | "UPDATE" | "DELETE"; change.row: the row
+   *   });
+   * // later: unsub();
+   *
+   * Delivery mirrors `Amba.collections.find()` — you only receive rows your
+   * session owns. Requires an authenticated session.
+   */
+  collection: <T = unknown>(name: string) => CollectionSubscription<T>;
+  /** Typed collection CRUD with auto-RLS. */
+  collections: {
+    find: <T = unknown>(name: string, options?: FindOptions) => Promise<FindResponse<T>>;
+    findOne: <T = unknown>(name: string, id: string) => Promise<T>;
+    insert: <T = unknown>(name: string, row: Record<string, unknown>) => Promise<T>;
+    update: <T = unknown>(name: string, id: string, set: Record<string, unknown>) => Promise<T>;
+    delete: (name: string, id: string) => Promise<{
+      data: {
+        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
+     * `options.vector_field`. Distance metric and index strategy are
+     * server-side; pass `options.filter` to narrow the candidate set
+     * before ranking.
+     *
+     * Spec note: the canonical `findNearest(name, vector, k, filter?)`
+     * shape omits the column name; the SDK widens the contract to a
+     * single typed options object so `vector_field` is required and
+     * unambiguous in TS.
+     */
+    findNearest: <T = unknown>(name: string, options: NearestOptions) => Promise<NearestResponse<T>>;
+    /**
+     * Count rows in the collection (SDK 4.0). Pass an optional filter
+     * to scope; omit it for the total. The server's response unwraps to
+     * 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;
+      ne: (column: string, value: FilterValue) => Filter;
+      gt: (column: string, value: FilterValue) => Filter;
+      gte: (column: string, value: FilterValue) => Filter;
+      lt: (column: string, value: FilterValue) => Filter;
+      lte: (column: string, value: FilterValue) => Filter;
+      in: (column: string, values: FilterValue[]) => Filter;
+      notIn: (column: string, values: FilterValue[]) => Filter;
+      like: (column: string, pattern: string) => Filter;
+      ilike: (column: string, pattern: string) => Filter;
+      isNull: (column: string) => Filter;
+      isNotNull: (column: string) => Filter;
+      and: (...filters: Filter[]) => Filter;
+      or: (...filters: Filter[]) => Filter;
+      not: (filter: Filter) => Filter;
+    };
+  };
+  /** Media uploads + CDN URL helpers. */
+  storage: {
+    presign: (params: {
+      bucket: string;
+      filename: string;
+      mimeType: string;
+      sizeBytes: number;
+      retentionDays?: number;
+    }) => Promise<PresignData>;
+    /**
+     * Complete-flow upload: presign → PUT to object storage → commit.
+     * Returns the finalized MediaAsset.
+     */
+    upload: (params: {
+      bucket: string;
+      file: File | Blob;
+      filename?: string;
+      retentionDays?: number;
+    }) => Promise<MediaAsset>;
+    /**
+     * List media assets (SDK 4.0). Pass `prefix` to scope to a key
+     * prefix (filename / path-like). Without it, returns the caller's
+     * full list. Server enforces RLS — only the calling user's assets
+     * are returned.
+     */
+    list: (prefix?: string) => Promise<MediaListResponse>;
+    /**
+     * Soft-delete the asset (SDK 4.0). Accepts the asset id returned
+     * by `presign` / `commit` / `list`. The corresponding storage object
+     * is removed asynchronously on the server.
+     */
+    delete: (assetId: string) => Promise<void>;
+    /**
+     * Download an asset's bytes (SDK 4.0). Returns a `Blob` wrapping
+     * 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 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: {
+    /**
+     * Replay a batch of buffered mutations
+     * (`POST /v1/client/sync`). The server applies them in order and
+     * returns the count of successfully-applied changes plus any
+     * per-row conflicts. Conflict resolution in 4.0 is always
+     * server-wins; the `SyncConflict.resolution` field is reserved
+     * for future strategies.
+     */
+    pushChanges: (changes: SyncChange[]) => Promise<PushChangesResult>;
+    /**
+     * Pull remote-origin changes since the supplied cursor
+     * (`GET /v1/client/sync`). Pass the `checkpoint_token` from the
+     * previous `pushChanges` / `pullChanges` reply, and the
+     * `entity_type` to scope to a single collection. On the first
+     * call, omit `checkpoint_token` to receive the full backfill.
+     */
+    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>;
+    unregister: (token: string) => Promise<void>;
+    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[]>;
+  };
+  /** 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>;
+        };
+      };
+    };
+  };
+  /**
+   * Invoke a deployed function by name, with the project's client key (and
+   * the live session token, if any) injected automatically.
+   *
+   * This is the authenticated way to call your functions — prefer it over
+   * 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, 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`; the
+   *   server trace id (when present) is attached as `error.traceId`.
+   */
+  functions: {
+    invoke: <T = unknown>(name: string, body?: unknown, options?: InvokeOptions) => Promise<T>;
+  };
+  /** Remote config bundle. */
+  config: {
+    fetch: () => Promise<ConfigBundle>;
+  };
+  /** Server-evaluated feature flags. */
+  flags: {
+    fetch: () => Promise<FlagAssignment[]>;
+    /**
+     * Single-flag lookup (SDK 4.0). Wraps `GET /v1/client/flags/{key}`.
+     * Returns `null` for unknown / disabled keys; other errors
+     * (auth, rate-limit, network) propagate.
+     */
+    get: (key: string) => Promise<FlagAssignment | null>;
+  };
+  /**
+   * Wire-verify primitive. Call once after `configure()` to confirm
+   * the SDK is talking to the right project with the right key.
+   *
+   * The response is entirely server-decided — none of the fields are
+   * derived from request parameters — so it's trustworthy as a setup
+   * check. Common usage:
+   *
+   * ```ts
+   * const ping = await Amba.diagnostics.ping();
+   * if (!ping.ok || ping.server_project_id !== expectedProjectId) {
+   *   throw new Error(`amba misconfigured: ${JSON.stringify(ping)}`);
+   * }
+   * ```
+   */
+  diagnostics: {
+    ping: () => Promise<PingResult>;
+  };
+  /** Achievement definitions + per-user progress. */
+  achievements: {
+    getAll: () => Promise<Achievement[]>;
+    getProgress: () => Promise<AchievementProgress[]>;
+  };
+  /** Time-bounded challenges with rewards. */
+  challenges: {
+    getActive: () => Promise<Challenge[]>;
+    get: (id: string) => Promise<Challenge>;
+    getProgress: (id: string) => Promise<ChallengeProgress>;
+    claim: (id: string) => Promise<ChallengeProgress>;
+  };
+  /** Virtual currency balances + ledger. */
+  currencies: {
+    getBalance: () => Promise<CurrencyBalance[]>;
+    getTransactions: (currencyKey: string) => Promise<CurrencyTransaction[]>;
+  };
+  /** User inventory items + purchase/consume. */
+  inventory: {
+    getItems: () => Promise<InventoryItem[]>;
+    getItem: (id: string) => Promise<InventoryItem>;
+    purchase: (request: PurchaseRequest) => Promise<InventoryItem>;
+    consume: (request: ConsumeRequest) => Promise<InventoryItem>;
+  };
+  /** Score rankings. */
+  leaderboards: {
+    get: (key: string) => Promise<Leaderboard>;
+    getEntries: (key: string, limit?: number) => Promise<LeaderboardEntry[]>;
+    getMyRank: (key: string) => Promise<LeaderboardEntry>;
+  };
+  /**
+   * Tiered weekly leaderboard cohorts (SDK 4.0). Each user is bucketed
+   * into a small cohort (~25 members) within their league tier; the
+   * top scorers each week promote and the bottom scorers demote.
+   */
+  leagues: {
+    /**
+     * `GET /v1/client/leagues/me` — the caller's active-cohort
+     * standing plus live rank/score and member count.
+     */
+    me: () => Promise<LeagueMembership>;
+    /**
+     * `GET /v1/client/leagues/me/cohort` — the caller's cohort with
+     * every member's anonymised standing (display name, score, rank).
+     * Notably no user ids — the server strips them so a leaderboard
+     * UI can render the cohort without exposing identities.
+     */
+    cohort: () => Promise<LeagueCohortView>;
+  };
+  /** Purchase storefronts. */
+  stores: {
+    list: () => Promise<Store[]>;
+    getPurchaseOptions: (storeKey: string) => Promise<PurchaseOption[]>;
+    purchase: (storeKey: string, purchaseOptionId: string, receipt: unknown) => Promise<PurchaseResult>;
+  };
+  /** Experience points + level system. */
+  xp: {
+    getBalance: () => Promise<XpBalance>;
+    getHistory: (limit?: number) => Promise<XpTransaction[]>;
+    claim: (grantKey: string) => Promise<XpTransaction>;
+  };
+  /** Daily-engagement streaks. */
+  streaks: {
+    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>;
+  };
+  /** Friend graph + block list. */
+  friends: {
+    getList: () => Promise<Friendship[]>;
+    getFriends: () => Promise<Friendship[]>;
+    /**
+     * Send a friend request to `userId` (SDK 4.0). Returns the
+     * resulting `Friendship` row in `pending` state.
+     */
+    sendRequest: (userId: string) => Promise<Friendship>;
+    /**
+     * Accept a pending incoming friend request (SDK 4.0). Pass the
+     * friendship id from `getList()`.
+     */
+    acceptRequest: (friendshipId: string) => Promise<Friendship>;
+    /**
+     * Decline a pending incoming friend request (SDK 4.0). Removes
+     * the pending row; idempotent.
+     */
+    declineRequest: (friendshipId: string) => Promise<void>;
+    blockUser: (userId: string) => Promise<Friendship>;
+    unblockUser: (userId: string) => Promise<void>;
+    removeBlock: (friendshipId: string) => Promise<void>;
+    /**
+     * Unfriend by the other user's id (SDK 4.0). Wraps
+     * `DELETE /v1/client/friends/by-user/{userId}`. Server preserves
+     * blocked rows; use `unblockUser` to clear those. 404 propagates
+     * as `AmbaApiError`.
+     */
+    removeFriend: (userId: string) => Promise<void>;
+  };
+  /** Multi-user groups. */
+  groups: {
+    create: (params: GroupCreate) => Promise<Group>;
+    get: (id: string) => Promise<Group>;
+    update: (id: string, patch: GroupUpdate) => Promise<Group>;
+    delete: (id: string) => Promise<void>;
+    getMembers: (id: string) => Promise<GroupMember[]>;
+    join: (id: string) => Promise<GroupMember>;
+    leave: (id: string) => Promise<void>;
+    invite: (id: string, userId: string) => Promise<GroupMember>;
+  };
+  /**
+   * User-to-user direct messaging.
+   *
+   * Paths mirror the API exactly — see `apps/api/src/routes/client/messaging.ts`:
+   *
+   * | SDK method            | API route                                                |
+   * | --------------------- | -------------------------------------------------------- |
+   * | `createConversation`  | POST `/v1/client/messaging/conversations`                |
+   * | `getConversations`    | GET  `/v1/client/messaging/conversations`                |
+   * | `listConversations`   | (alias for `getConversations`)                           |
+   * | `sendMessage`         | POST `/v1/client/messaging/conversations/:id/messages`   |
+   * | `listMessages`        | GET  `/v1/client/messaging/conversations/:id/messages`   |
+   * | `markRead`            | POST `/v1/client/messaging/conversations/:id/read`       |
+   *
+   * Task #62 corrected `sendMessage`'s path (it previously POSTed to
+   * `/messaging/messages`, a route that doesn't exist on the API), and
+   * added the four missing helpers. The previous `getMessage(id)` helper
+   * has been removed — there is no GET-by-id route on the server; the
+   * shape consumers actually want is `listMessages(conversationId, opts)`.
+   */
+  messaging: {
+    /**
+     * `POST /v1/client/messaging/conversations` — create (or fetch the
+     * existing direct) conversation. For `type: "direct"` with exactly
+     * one other participant, the server returns the existing row if
+     * one already exists between these two users — calls are
+     * idempotent.
+     */
+    createConversation: (request: CreateConversationRequest) => Promise<Conversation>;
+    /**
+     * `GET /v1/client/messaging/conversations` — list the caller's
+     * conversations. Canonical 4.0 name; the legacy `getConversations`
+     * / `listConversations` are removed in 4.0 per the spec.
+     */
+    conversations: () => Promise<Conversation[]>;
+    /**
+     * `POST /v1/client/messaging/conversations/:conversationId/messages`
+     * — send a message into an existing conversation. The
+     * `conversation_id` argument is a path parameter (not a body
+     * field) — the previous SDK shape mistakenly placed it in the
+     * body, which the API ignored because the route was wrong anyway.
+     */
+    sendMessage: (conversationId: string, request: SendMessageRequest) => Promise<Message>;
+    /**
+     * `GET /v1/client/messaging/conversations/:conversationId/messages`
+     * — list messages in a conversation. Pagination uses `?limit=&offset=`
+     * (the server's `parsePagination` clamps both; defaults to 50 / 0).
+     */
+    listMessages: (conversationId: string, opts?: ListMessagesOptions) => Promise<Message[]>;
+    /**
+     * `GET /v1/client/messaging/conversations/:conversationId/messages/:messageId`
+     * — fetch a single message by id. Returns `null` when the message
+     * doesn't exist or the caller can't see it. (SDK 4.0: Phase A
+     * shipped the missing `amba_messaging_get_message` core symbol the
+     * native SDKs were already trying to call.)
+     */
+    getMessage: (conversationId: string, messageId: string) => Promise<Message | null>;
+    /**
+     * `POST /v1/client/messaging/conversations/:conversationId/participants`
+     * — add a participant to an existing conversation. The caller must
+     * already be a participant (the server returns `403
+     * NOT_A_PARTICIPANT` otherwise) — this is the peer-invite path.
+     * Idempotent: re-adding an existing member returns the existing
+     * participant row, not an error. Enables dynamic membership growth
+     * (e.g. a circle whose members qualify over time). Server-side
+     * membership management (admin/matchmaker) uses the admin
+     * add-participant endpoint instead.
+     */
+    addParticipant: (conversationId: string, userId: string) => Promise<ConversationParticipant>;
+    /**
+     * `POST /v1/client/messaging/conversations/:conversationId/read`
+     * — bump the caller's `last_read_at` for the conversation. Returns
+     * the updated participant row.
+     */
+    markRead: (conversationId: string) => Promise<MarkReadResult>;
+    /**
+     * Live message subscriptions (SDK 4.0). Returns a builder — call
+     * `.subscribe(cb)` to receive new messages in a conversation live
+     * instead of polling `listMessages`. `subscribe` returns an
+     * unsubscribe handle.
+     *
+     * @example
+     * const unsub = Amba.messaging
+     *   .conversation(conversationId)
+     *   .subscribe((change) => {
+     *     // change.op === "INSERT"; change.row is the new message
+     *     appendMessageToThread(change.row);
+     *   });
+     * // later: unsub();
+     *
+     * Delivery is scoped to conversation participants — you receive a
+     * conversation's messages only if your session is a member of it.
+     * Requires an authenticated session.
+     */
+    conversation: <T = Message>(conversationId: string) => ConversationSubscription<T>;
+  };
+  /** Report users / content for moderation. */
+  moderation: {
+    reportUser: (request: ReportRequest) => Promise<Report>;
+    reportContent: (request: ReportRequest) => Promise<Report>;
+    getReportStatus: (id: string) => Promise<Report>;
+  };
+  /** User reviews of catalog items or other users. */
+  reviews: {
+    list: (targetType: string, targetId: string) => Promise<Review[]>;
+    create: (params: ReviewCreate) => Promise<Review>;
+    update: (id: string, patch: ReviewUpdate) => Promise<Review>;
+    delete: (id: string) => Promise<void>;
+  };
+  /** RBAC roles + permission checks. */
+  roles: {
+    getMyRoles: () => Promise<Role[]>;
+    hasPermission: (permission: string) => Promise<boolean>;
+  };
+  /** Referral codes + claim flow. */
+  referrals: {
+    getReferralCode: () => Promise<ReferralCode>;
+    claimReferral: (code: string) => Promise<ReferralClaim>;
+    create: (code?: string, maxUses?: number) => Promise<ReferralCode>;
+  };
+  /** Read-only product catalog. */
+  catalog: {
+    list: () => Promise<CatalogItem[]>;
+    /**
+     * Fetch a single catalog item by id (SDK 4.0).
+     * `GET /v1/client/catalog/:id`.
+     */
+    get: (id: string) => Promise<CatalogItem>;
+  };
+  /** Developer-defined content items (daily quotes, lessons, etc.). */
+  content: {
+    /**
+     * Get today's published item for `channel`. Defaults to `"default"`
+     * so single-channel apps can call `Amba.content.today()` bare.
+     * (Canonical 4.0 name; legacy `getToday` is removed.)
+     */
+    today: (channel?: string) => Promise<ContentItem | null>;
+    /**
+     * Paginated library list for `channel`. `options.limit` caps page size
+     * (server default applies when omitted); `options.cursor` is the
+     * opaque token returned by a prior response's `next_cursor`.
+     * (Canonical 4.0 name; legacy `getLibrary` is removed.)
+     */
+    library: (channel?: string, options?: {
+      limit?: number;
+      cursor?: string;
+    }) => Promise<ContentItem[]>;
+    item: (id: string) => Promise<ContentItem>;
+    updateItem: (id: string, state: unknown) => Promise<ContentItem>;
+    createItem: (channel: string, item: unknown) => Promise<ContentItem>;
+  };
+  /** Server-managed deep link records. */
+  deepLinks: {
+    get: (shortCode: string) => Promise<DeepLink>;
+    create: (params: DeepLinkCreate) => Promise<DeepLink>;
+  };
+  /** Step-by-step user onboarding flow. */
+  onboarding: {
+    getStatus: () => Promise<OnboardingStatus>;
+    nextStep: (payload: unknown) => Promise<OnboardingStatus>;
+    skipStep: () => Promise<OnboardingStatus>;
+    complete: () => Promise<OnboardingStatus>;
+  };
+};
+/** Escape hatch — the raw SDK runtime handle, for namespaces not yet wrapped. */
+declare function getCoreWasm(): AmbaCoreWasm;
+/**
+ * Package version stamped at build time. Sent in the
+ * `sdk_wrapper_version` header on every customer request.
+ *
+ * **Must match `package.json#version` exactly** — the
+ * `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.7";
+//#endregion
+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.browser.d.ts.map