@layers/amba-react-native 3.0.3 → 4.0.1

package/dist/index.d.ts

@@ -18,6 +18,12 @@ 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/link completed for this email. */
+  email_verified?: boolean;
+  /** `true` once SMS-OTP verify/link completed for this phone. */
+  phone_verified?: boolean;
   display_name?: string | null;
   avatar_url?: string | null;
   external_id?: string | null;
@@ -29,6 +35,17 @@ interface User {
   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, `a***@domain` for email); raw values stay server-side.
+ * Social providers (`apple`, `google`) have `null` masked value.
+ */
+interface LinkedIdentifier {
+  provider: "sms_otp" | "email_otp" | "apple" | "google";
+  verified: boolean;
+  identifier_masked: string | null;
+}
 interface AuthResult {
   session_token: string;
   refresh_token: string;
@@ -156,6 +173,15 @@ interface FlagAssignment {
   variant?: string | null;
   payload?: unknown;
 }
+type DiagnosticsEnvironment = "production" | "staging" | "sandbox";
+interface PingResult {
+  ok: boolean;
+  server_project_id: string | null;
+  environment: DiagnosticsEnvironment | null;
+  key_fingerprint: string;
+  latency_ms: number;
+  error: string | null;
+}
 interface Achievement {
   id: string;
   key: string;
@@ -522,6 +548,138 @@ interface OnboardingStatus {
   completed: boolean;
   completed_at?: string | null;
 }
+/**
+ * Patch shape for `Amba.users.update`. Mirrors the server's writable
+ * user fields — see `apps/api/src/routes/client/users.ts` (the route
+ * allows `display_name`, `avatar_url`, `properties`, `timezone` only;
+ * `email` is silently ignored and intentionally not part of this type).
+ *
+ * `timezone` must be a valid IANA name (e.g. `America/New_York`) when
+ * set; the server rejects invalid values with `VALIDATION_ERROR`.
+ */
+interface UserPatch {
+  display_name?: string | null;
+  avatar_url?: string | null;
+  properties?: Record<string, unknown>;
+  timezone?: string | null;
+}
+/**
+ * One row from `Amba.sessions.list` — a server-tracked customer-defined
+ * app session row. Mirrors the `toSdkSession` projection in
+ * `apps/api/src/routes/client/sessions.ts` and the Rust core's
+ * `AppSession` struct (`sdks/core/src/sessions.rs`).
+ *
+ * NOTE: this is NOT a device/auth session record — `/v1/client/sessions`
+ * surfaces analytics-style `app_sessions` rows (open/background events).
+ * There is no `user_agent` / `ip_address` / `current` field — the server
+ * doesn't populate them.
+ */
+interface SessionRecord {
+  id: string;
+  user_id: string;
+  session_id?: string | null;
+  started_at: string;
+  ended_at?: string | null;
+  duration_secs?: number | null;
+  platform?: string | null;
+  app_version?: string | null;
+  device_model?: string | null;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * One offline-replay change submitted to `Amba.sync.pushChanges`.
+ * Mirrors `SyncPushInput.changes[]` in `apps/api/src/routes/client/sync.ts`
+ * and the Rust core's `SyncChange` struct (`sdks/core/src/sync.rs`).
+ * Server resolves conflicts server-wins.
+ */
+interface SyncChange {
+  /** Collection / table name the change targets. */
+  entity_type: string;
+  /** Server-side primary key of the row being modified. */
+  entity_id: string;
+  /** One of `"insert"`, `"update"`, `"delete"`. */
+  action: "insert" | "update" | "delete";
+  /**
+   * Mutation payload — depends on `action`. For inserts/updates this is
+   * the row body; for deletes the server tolerates empty.
+   */
+  data?: Record<string, unknown>;
+  /**
+   * Client-side ISO-8601 timestamp at which the mutation was captured.
+   * Used for the conflict-resolution comparison (server wins when its
+   * `last_synced_at` is newer).
+   */
+  client_timestamp: string;
+}
+/**
+ * Per-row conflict surfaced by the server in `pushChanges` responses.
+ * `resolution` is `"server_wins"` today.
+ */
+interface SyncConflict {
+  entity_type: string;
+  entity_id: string;
+  resolution: "server_wins";
+  server_data?: Record<string, unknown>;
+}
+interface SyncPushResult {
+  applied: number;
+  conflicts: SyncConflict[];
+  /** Opaque server-issued cursor to supply to the next `pullChanges`. */
+  checkpoint_token: string;
+}
+interface SyncPullResult {
+  changes: SyncChange[];
+  /** Cursor to supply on the next pull to continue from this point. */
+  checkpoint_token: string;
+  has_more?: boolean;
+}
+/**
+ * Cursor input to `Amba.sync.pullChanges`. The server requires
+ * `entity_type`; `checkpoint_token` is optional on the first pull.
+ */
+interface SyncPullSince {
+  entity_type: string;
+  checkpoint_token?: string;
+}
+/** League tier metadata. */
+interface LeagueTier {
+  id: string;
+  name: string;
+  tier_order: number;
+}
+/** Cohort the requester currently belongs to. */
+interface LeagueCohortRef {
+  id: string;
+  league_id: string;
+  /** ISO-8601 date (YYYY-MM-DD) — the Monday that opens the cohort. */
+  week_start: string;
+  status: string;
+}
+/**
+ * Reply from `GET /v1/client/leagues/me`. Mirrors
+ * `apps/api/src/routes/client/leagues.ts:GET /me`.
+ */
+interface LeagueMembership {
+  cohort: LeagueCohortRef | null;
+  league: LeagueTier | null;
+  rank: number | null;
+  score: number;
+  member_count: number;
+}
+/**
+ * Reply from `GET /v1/client/leagues/me/cohort`. The cohort with every
+ * member's anonymised standing — `members[]` carries `display_name` /
+ * `score` / `rank` only (no `user_id` leak).
+ */
+interface LeagueCohort {
+  cohort: LeagueCohortRef | null;
+  league: LeagueTier | null;
+  members: Array<{
+    display_name?: string | null;
+    score: number;
+    rank: number;
+  }>;
+}
 //#endregion
 //#region src/error.d.ts
 /**
@@ -550,7 +708,7 @@ declare class AmbaApiError extends Error {
 //#endregion
 //#region src/index.d.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-declare const SDK_VERSION = "3.0.0";
+declare const SDK_VERSION = "4.0.1";
 /**
  * Top-level SDK namespace for React Native.
  */
@@ -569,13 +727,118 @@ declare const Amba: {
   readonly projectId: string;
   setDebug: (enabled: boolean) => void;
   events: {
-    track: (event: string, properties?: Record<string, unknown>) => Promise<void>;
+    /**
+     * Track an event.
+     *
+     * Default routes to the engagement meter (fan-out to segments,
+     * workflows, 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.
+     *
+     * @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>;
   };
   auth: {
     signInAnonymously: () => Promise<AuthResult>;
     signInWithEmail: (email: string, password: string) => Promise<AuthResult>;
     signUpWithEmail: (email: string, password: string) => Promise<AuthResult>;
-    signInWithSocial: (provider: SocialProvider, idToken: string) => Promise<AuthResult>;
+    /**
+     * Sign in with an Apple ID identity token (from
+     * `ASAuthorization.identityToken` on iOS / `expo-apple-authentication`).
+     * Replaces the 3.x `signInWithSocial('apple', token)` polymorphic form.
+     */
+    signInWithApple: (identityToken: string) => Promise<AuthResult>;
+    /**
+     * Sign in with a Google ID token (from Google Sign-In SDK / Expo
+     * `expo-auth-session/providers/google`). Replaces the 3.x
+     * `signInWithSocial('google', token)` polymorphic form.
+     */
+    signInWithGoogle: (idToken: string) => Promise<AuthResult>;
+    /**
+     * Request a one-time passcode for `email`. Server emails a 6-digit
+     * code; the user types it in, then call
+     * `verifyEmailOtp(email, code)` to exchange for a session.
+     */
+    requestEmailOtp: (email: string) => Promise<void>;
+    /**
+     * Exchange `(email, code)` for a session. Returns the same shape
+     * as `signInWithEmail`.
+     */
+    verifyEmailOtp: (email: string, code: string) => Promise<AuthResult>;
+    /**
+     * Request a one-time passcode by SMS. `phone` must be E.164
+     * (starts with +, 8–15 digits). Server sends a 6-digit code;
+     * user types it, then call `verifySmsOtp(phone, code)` to
+     * exchange for a session.
+     */
+    requestSmsOtp: (phone: string) => Promise<void>;
+    /**
+     * Exchange `(phone, code)` for a session. Same shape as
+     * `signInWithEmail`.
+     */
+    verifySmsOtp: (phone: string, code: string) => Promise<AuthResult>;
+    /**
+     * Request a one-time magic link for `email`. The server emails a
+     * deep-link URL containing a single-use token; the app's deep-link
+     * handler extracts the token and calls `verifyMagicLink(token)` to
+     * exchange for a session. NEW in 4.0.
+     */
+    requestMagicLink: (email: string) => Promise<void>;
+    /**
+     * Exchange a magic-link `token` for a session. Same shape as
+     * `signInWithEmail`. NEW in 4.0.
+     */
+    verifyMagicLink: (token: string) => Promise<AuthResult>;
+    /**
+     * Link a social identity provider to the current (anonymous or
+     * identified) user. Upgrades an anonymous session to an identified
+     * one without minting a new app_user. NEW in 4.0.
+     *
+     * Mirrors `AmbaCore::link_account` in the engine — the SDK reads
+     * the active session token from local identity state and posts
+     * `{ provider, token, session_token }` to `/v1/client/auth/link`,
+     * which is the wire shape the server expects. Callers must already
+     * have a session (any flow) before linking; an `UNAUTHORIZED` error
+     * is thrown if none is present.
+     *
+     * Email linking via this endpoint is rejected server-side — use
+     * `signInWithEmail` / `signUpWithEmail` instead.
+     *
+     * @param provider — `"apple" | "google"`
+     * @param credential — provider identity token (Apple `identityToken`,
+     *   Google `id_token`).
+     */
+    linkAccount: (provider: string, credential: string) => Promise<AuthResult>;
+    /**
+     * Attach a verified phone to the current session's user without
+     * minting new tokens. Same `user_id`, same session token. Server
+     * returns `PHONE_ALREADY_LINKED` (409) with
+     * `details.conflicting_user_id` if the phone is owned by another
+     * user — the SDK rethrows as `AmbaApiError`.
+     */
+    linkSmsOtp: (phone: string, code: string) => Promise<User>;
+    /** Symmetric counterpart to `linkSmsOtp` for email. */
+    linkEmailOtp: (email: string, code: string) => Promise<User>;
+    /**
+     * Detach the SMS-OTP identifier from the current session's user.
+     * Refused with `LAST_IDENTIFIER` if it would orphan the account.
+     */
+    unlinkSmsOtp: () => Promise<User>;
+    unlinkEmailOtp: () => Promise<User>;
+    unlinkApple: () => Promise<User>;
+    unlinkGoogle: () => Promise<User>;
+    /**
+     * Snapshot of identifier providers attached to the current user.
+     * Values come back **masked** (phone last-4, `a***@domain`).
+     */
+    getCurrentIdentifiers: () => Promise<LinkedIdentifier[]>;
     signOut: (rotateAnonymousId?: boolean) => Promise<void>;
     refresh: () => Promise<AuthResult>;
     me: () => Promise<User>;
@@ -583,9 +846,105 @@ declare const Amba: {
     getAnonymousId: () => Promise<string>;
     onAuthStateChange: (cb: (session: Session | null) => void) => (() => void);
   };
+  /**
+   * Profile read/update for the current user. NEW in 4.0.
+   *
+   * `get()` — fetches the current user's full record. Short-circuits to
+   * `/auth/me` so the server doesn't have to look up the caller twice.
+   *
+   * Both `users.get(userId)` and `users.update(userId, patch)` are
+   * SDK 4.0 surfaces — `userId` omitted = current user, `userId` set
+   * = the other user (server route `/v1/client/users/{id}`). The
+   * server returns a public-safe profile shape for non-self reads;
+   * cross-user writes require the caller to hold `users:write` in
+   * their role permissions (403 otherwise).
+   */
+  users: {
+    get: (userId?: string) => Promise<User>;
+    /**
+     * Update a profile. Two overloads:
+     *   - `update(patch)` — update the current user (PATCH /users/me).
+     *   - `update(userId, patch)` — admin-style cross-user update
+     *     (PATCH /users/{id}); requires `users:write` role permission
+     *     server-side, else 403.
+     */
+    update: {
+      (patch: UserPatch): Promise<User>;
+      (userId: string, patch: UserPatch): Promise<User>;
+    };
+  };
+  /**
+   * Server-tracked customer-defined app sessions for the current user.
+   * NEW in 4.0. These are the analytics `app_sessions` rows
+   * (open/background events), not auth device sessions.
+   *
+   * - `list()` → `GET /v1/client/sessions` returns `AppSession[]` newest
+   *   first (capped at 100 by the server).
+   * - `revoke(sessionId)` → `POST /v1/client/sessions/:id/end` ends the
+   *   given session row (idempotent — a second `revoke` on an already-
+   *   ended session is a no-op). `sessionId` is the row id (UUID)
+   *   returned by `list()` (the `id` field, not `session_id`). Server
+   *   has no DELETE on `/sessions/:id` — `end` is the canonical revoke.
+   */
+  sessions: {
+    list: () => Promise<SessionRecord[]>;
+    revoke: (sessionId: string) => Promise<void>;
+  };
+  /**
+   * Offline change replay. NEW in 4.0. Wraps `/v1/client/sync` per
+   * `apps/api/src/routes/client/sync.ts` and the engine's
+   * `SyncModule` (`sdks/core/src/sync.rs`).
+   *
+   * - `pushChanges(changes)` → `POST /v1/client/sync` with `{ changes }`.
+   *   Server returns `{ applied, conflicts, checkpoint_token }`.
+   *   Conflicts are server-wins; callers should re-apply
+   *   `server_data` from each `SyncConflict` to their local cache
+   *   before issuing follow-up writes.
+   * - `pullChanges({ entity_type, checkpoint_token? })` →
+   *   `GET /v1/client/sync?entity_type=…&checkpoint_token=…`. Server
+   *   requires `entity_type`; `checkpoint_token` is optional on the
+   *   first pull. Returns `{ changes, checkpoint_token, has_more }`.
+   *
+   * NOTE: The wire is a single `/sync` endpoint with method = action.
+   * Earlier 4.0 drafts referenced `/sync/push` and `/sync/pull` — those
+   * routes do not exist on the server.
+   */
+  sync: {
+    pushChanges: (changes: SyncChange[]) => Promise<SyncPushResult>;
+    pullChanges: (since: {
+      entity_type: string;
+      checkpoint_token?: string;
+    }) => Promise<SyncPullResult>;
+  };
   collections: {
     find: <T = unknown>(name: string, options?: FindOptions) => Promise<FindResponse<T>>;
     findOne: <T = unknown>(name: string, id: string) => Promise<T>;
+    /**
+     * Vector similarity search. Returns the top `k` rows closest to the
+     * supplied `vector` by cosine distance (default), optionally
+     * further filtered by `where`. NEW in 4.0 — wires to the
+     * pgvector-backed `POST /v1/client/collections/:name/find-nearest`
+     * route.
+     *
+     * Wire body matches `NearestRequestBody` in
+     * `apps/api/src/routes/client/collections.ts`: `to_vector` (or
+     * `to_text` for server-side embedding) + optional `k`, `column`,
+     * `distance`, `where`, `includeDeleted`.
+     */
+    findNearest: <T = unknown>(name: string, vector: number[], k: number, where?: Filter) => Promise<T[]>;
+    /**
+     * Count rows in a collection, optionally filtered. NEW in 4.0 —
+     * wires to `GET /v1/client/collections/:name/count` with an
+     * optional `?query={"where":...}` body channel (GET requests
+     * can't carry a JSON body, so the server reads the JSON from the
+     * `query` param).
+     *
+     * The server's `/count` route only honors `where` + `includeDeleted`
+     * — passing other knobs (`limit`, `cursor`, etc.) returns
+     * `INVALID_QUERY_PARAM`. Mirrors the engine's `CollectionsModule::count`
+     * (`sdks/core/src/collections.rs`).
+     */
+    count: (name: string, where?: Filter) => Promise<number>;
     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<{
@@ -620,6 +979,45 @@ declare const Amba: {
       retentionDays?: number;
     }) => Promise<PresignData>;
     commit: (uploadId: string, assetId: string) => Promise<MediaAsset>;
+    /**
+     * List media assets, optionally filtered by a key prefix. NEW in 4.0.
+     *
+     * Returns the full `{ data, next_cursor }` envelope so paginated
+     * listings expose the cursor — aligns with the web SDK shape
+     * (`MediaListResponse`) and the engine `ListResponse`.
+     */
+    list: (prefix?: string) => Promise<{
+      data: MediaAsset[];
+      next_cursor?: string | null;
+    }>;
+    /**
+     * Soft-delete a media asset by its asset id (the UUID returned
+     * from `upload()` / `list()` / `get()`). NEW in 4.0.
+     *
+     * Wires to `DELETE /v1/client/media/:assetId` per
+     * `apps/api/src/routes/client/media.ts:374`. The server scopes
+     * deletes by `uploaded_by = current user`. Returns 404 if the
+     * asset doesn't exist or isn't owned by the caller.
+     *
+     * NOTE: takes the asset id (UUID), not the storage key — the
+     * server has no `?key=` query channel. Use `Amba.storage.list()`
+     * to get the id from a `MediaAsset` row.
+     */
+    delete: (assetId: string) => Promise<void>;
+    /**
+     * Download a media asset's bytes by its asset id. Two-step:
+     * resolve the `MediaAsset` metadata (which carries the CDN URL),
+     * then fetch the CDN URL directly with no API headers.
+     *
+     * Returns a `Blob` — RN's fetch surfaces blobs natively
+     * (`response.blob()`). NEW in 4.0.
+     *
+     * Mirrors the engine's `StorageModule::download` in
+     * `sdks/core/src/storage.rs:247` — there is no
+     * `/v1/client/media/download` route on the server; the CDN URL
+     * on the asset row is the canonical fetch target.
+     */
+    download: (assetId: string) => Promise<Blob>;
   };
   push: {
     register: (token: string, platform: PushPlatform, bundleId?: string) => Promise<PushToken>;
@@ -644,6 +1042,29 @@ declare const Amba: {
   };
   flags: {
     fetch: () => Promise<FlagAssignment[]>;
+    /**
+     * Get a single flag assignment by name. NEW in 4.0. Wraps
+     * `GET /v1/client/flags/{key}` — returns `null` when the flag is
+     * unknown or disabled for this user (the server treats both as
+     * 404 by design; the SDK normalizes to `null`). Other errors
+     * (auth, rate-limit, network) still throw.
+     */
+    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 in
+   * the right environment. See `@layers/amba-web::Amba.diagnostics.ping`
+   * for the canonical usage example — the response shape is identical
+   * across every Amba SDK.
+   *
+   * The ping response is NOT wrapped in the usual `{data: ...}`
+   * envelope — the route returns the `PingResult` shape directly so
+   * an operator running `curl … | jq` sees the structured fields
+   * without an extra unwrap.
+   */
+  diagnostics: {
+    ping: () => Promise<PingResult>;
   };
   achievements: {
     getAll: () => Promise<Achievement[]>;
@@ -670,6 +1091,17 @@ declare const Amba: {
     getEntries: (key: string, limit?: number) => Promise<LeaderboardEntry[]>;
     getMyRank: (key: string) => Promise<LeaderboardEntry>;
   };
+  /**
+   * Tiered weekly cohorts (Duolingo-style leagues). NEW in 4.0.
+   *
+   * `me()` returns the caller's current cohort/tier/score snapshot.
+   * `cohort()` returns the full peer list competing in the same tier
+   * this week — for rendering a league-board UI.
+   */
+  leagues: {
+    me: () => Promise<LeagueMembership>;
+    cohort: () => Promise<LeagueCohort>;
+  };
   stores: {
     list: () => Promise<Store[]>;
     getPurchaseOptions: (storeKey: string) => Promise<PurchaseOption[]>;
@@ -690,9 +1122,35 @@ declare const Amba: {
   friends: {
     getList: () => Promise<Friendship[]>;
     getFriends: () => Promise<Friendship[]>;
+    /**
+     * Send a friend request to `userId`. NEW in 4.0 — the existing
+     * SDK shipped block/unblock but had no request/accept/decline
+     * surface, so customers couldn't actually build a friends graph
+     * without dropping to raw HTTP.
+     */
+    sendRequest: (userId: string) => Promise<Friendship>;
+    /**
+     * Accept an inbound friend request. NEW in 4.0.
+     */
+    acceptRequest: (friendshipId: string) => Promise<Friendship>;
+    /**
+     * Decline an inbound friend request. NEW in 4.0. Server endpoint
+     * is `/:friendshipId/reject` (not `/decline`) — SDK keeps the
+     * `declineRequest` name (intent is clear) but hits the server's
+     * spelling. apps/api/src/routes/client/friends.ts:152.
+     */
+    declineRequest: (friendshipId: string) => Promise<void>;
     blockUser: (userId: string) => Promise<Friendship>;
     unblockUser: (userId: string) => Promise<void>;
     removeBlock: (friendshipId: string) => Promise<void>;
+    /**
+     * `friends.removeFriend(userId)` — unfriend by the other user's id
+     * without needing the friendship row id. NEW in 4.0. Wraps
+     * `DELETE /v1/client/friends/by-user/{userId}`. Server preserves
+     * blocked rows (use `unblockUser` to clear those); 404 → throws
+     * AmbaApiError with code NOT_FOUND.
+     */
+    removeFriend: (userId: string) => Promise<void>;
   };
   groups: {
     create: (params: GroupCreate) => Promise<Group>;
@@ -717,12 +1175,34 @@ declare const Amba: {
      * conversations between two users.
      */
     createConversation: (request: CreateConversationRequest) => Promise<Conversation>;
-    getConversations: () => Promise<Conversation[]>;
-    /** Alias matching the `listX` naming convention used elsewhere. */
-    listConversations: () => Promise<Conversation[]>;
+    /**
+     * `GET /v1/client/messaging/conversations` — list the caller's
+     * conversations. Canonical 4.0 name; the legacy `getConversations`
+     * is removed in 4.0 per the spec.
+     */
+    conversations: () => Promise<Conversation[]>;
     sendMessage: (conversationId: string, request: SendMessageRequest) => Promise<Message>;
     listMessages: (conversationId: string, opts?: ListMessagesOptions) => Promise<Message[]>;
     markRead: (conversationId: string) => Promise<MarkReadResult>;
+    /**
+     * Fetch a single message by id within a conversation. NEW in 4.0.
+     *
+     * The server has no dedicated `GET /messages/:id` route — the
+     * `/messages` list endpoint also doesn't honour a `?message_id=`
+     * query filter (see `apps/api/src/routes/client/messaging.ts:358`,
+     * which returns the full paginated page). We paginate forward
+     * (newest-first, server page size 100) and find the matching id
+     * client-side, mirroring the engine's strategy in
+     * `sdks/core/src/messaging.rs:223`. Walks up to `MAX_PAGES`
+     * (5,000 messages total) before giving up to avoid an unbounded
+     * loop against a giant conversation; callers with longer histories
+     * should keep a local index instead of relying on this helper as a
+     * search primitive.
+     *
+     * Returns `null` when the message id isn't found within the cap
+     * (or the conversation), matching the canonical contract.
+     */
+    getMessage: (conversationId: string, messageId: string) => Promise<Message | null>;
   };
   moderation: {
     reportUser: (request: ReportRequest) => Promise<Report>;
@@ -746,14 +1226,24 @@ declare const Amba: {
   };
   catalog: {
     list: () => Promise<CatalogItem[]>;
+    /**
+     * Get a single catalog item by id. NEW in 4.0 — wires to
+     * `GET /v1/client/catalog/:id`.
+     */
+    get: (id: string) => Promise<CatalogItem>;
   };
   content: {
-    getToday: (channel?: string) => Promise<ContentItem | null>;
-    getLibrary: (channel?: string, options?: {
+    /**
+     * Canonical 4.0 names — `today` / `library` / `item`. The legacy
+     * `getToday` / `getLibrary` / `getItem` are removed in 4.0 per
+     * the spec (CANONICAL_API.md, content section).
+     */
+    today: (channel?: string) => Promise<ContentItem | null>;
+    library: (channel?: string, options?: {
       limit?: number;
       cursor?: string;
     }) => Promise<ContentItem[]>;
-    getItem: (id: string) => Promise<ContentItem>;
+    item: (id: string) => Promise<ContentItem>;
     updateItem: (id: string, state_: unknown) => Promise<ContentItem>;
     createItem: (channel: string, item: unknown) => Promise<ContentItem>;
   };
@@ -788,5 +1278,5 @@ declare const Amba: {
   };
 };
 //#endregion
-export { Achievement, AchievementProgress, AiMessage, AiMessageRequest, AiMessageResponse, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AuthResult, CatalogItem, Challenge, ChallengeProgress, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, EntitlementSource, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, Friendship, FriendshipState, Group, GroupCreate, GroupMember, GroupUpdate, InventoryItem, Leaderboard, LeaderboardEntry, ListMessagesOptions, MarkReadResult, MediaAsset, Message, MessageType, NotFilter, OnboardingStatus, OrFilter, OrderBy, PresignData, PurchaseOption, PurchaseRequest, PurchaseResult, PushPlatform, PushToken, ReferralClaim, ReferralCode, Report, ReportRequest, Review, ReviewCreate, ReviewUpdate, Role, SDK_VERSION, SendMessageRequest, Session, SocialProvider, Store, Streak, User, UserEntitlement, XpBalance, XpTransaction };
+export { Achievement, AchievementProgress, AiMessage, AiMessageRequest, AiMessageResponse, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AuthResult, CatalogItem, Challenge, ChallengeProgress, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DiagnosticsEnvironment, EntitlementSource, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, Friendship, FriendshipState, Group, GroupCreate, GroupMember, GroupUpdate, InventoryItem, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortRef, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, MarkReadResult, MediaAsset, Message, MessageType, NotFilter, OnboardingStatus, OrFilter, OrderBy, PingResult, PresignData, PurchaseOption, PurchaseRequest, PurchaseResult, PushPlatform, PushToken, ReferralClaim, ReferralCode, Report, ReportRequest, Review, ReviewCreate, ReviewUpdate, Role, SDK_VERSION, SendMessageRequest, Session, SessionRecord, SocialProvider, Store, Streak, SyncChange, SyncConflict, SyncPullResult, SyncPullSince, SyncPushResult, User, UserEntitlement, UserPatch, XpBalance, XpTransaction };
 //# sourceMappingURL=index.d.ts.map