@layers/amba-web 4.0.2 → 4.0.4

package/dist-rn/index.d.ts

@@ -19,6 +19,16 @@ interface AmbaConfig {
    * 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.
@@ -267,17 +277,23 @@ interface ChallengeProgress {
   claimed_at?: string | null;
 }
 interface CurrencyBalance {
-  currency_id: string;
-  key: string;
+  currency_code: string;
+  name: string;
+  is_premium: boolean;
   balance: number;
-  updated_at: string;
+  lifetime_earned: number;
+  lifetime_spent: number;
 }
 interface CurrencyTransaction {
   id: string;
-  currency_id: string;
-  delta: number;
+  app_user_id?: string;
+  currency_code: string;
+  amount: number;
   balance_after: number;
-  reason?: string | null;
+  transaction_type?: string;
+  source?: string;
+  reference_id?: string | null;
+  idempotency_key?: string | null;
   created_at: string;
 }
 interface InventoryItem {
@@ -505,6 +521,18 @@ interface MarkReadResult {
   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;
@@ -676,6 +704,8 @@ 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;
@@ -716,6 +746,104 @@ interface NearestResponse<T> {
   data: T[];
 }
 //#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;
+}
+//#endregion
 //#region src/error.d.ts
 /**
  * Typed error class for the amba SDK + helper that converts arbitrary
@@ -742,6 +870,13 @@ declare class AmbaApiError extends Error {
 }
 //#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>;
+}
 /**
  * Top-level SDK namespace.
  *
@@ -899,6 +1034,32 @@ declare const Amba: {
      * 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
@@ -983,6 +1144,23 @@ declare const Amba: {
      */
     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>>;
@@ -1115,6 +1293,31 @@ declare const Amba: {
       };
     };
   };
+  /**
+   * 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).
+   *
+   * @example
+   * const result = await Amba.functions.invoke<{ ok: boolean }>(
+   *   'send_welcome_email',
+   *   { to: 'user@example.com' },
+   * );
+   *
+   * @param name  The deployed function name.
+   * @param body  JSON-serializable request body (omitted for GET).
+   * @param options  Method + extra headers.
+   * @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`.
+   */
+  functions: {
+    invoke: <T = unknown>(name: string, body?: unknown, options?: InvokeOptions) => Promise<T>;
+  };
   /** Remote config bundle. */
   config: {
     fetch: () => Promise<ConfigBundle>;
@@ -1315,12 +1518,44 @@ declare const Amba: {
      * 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: {
@@ -1400,7 +1635,7 @@ declare function getCoreWasm(): AmbaCoreWasm;
  * `verify-sdk-version-coherence` GH action gates every publish on the
  * pair agreeing (and matching the `web-v<X.Y.Z>` tag when tag-triggered).
  */
-declare const SDK_VERSION = "4.0.2";
+declare const SDK_VERSION = "4.0.4";
 //#endregion
-export { Achievement, AchievementProgress, AiMessage, AiMessageRequest, AiMessageResponse, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AppSession, 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, LeagueCohortMember, LeagueCohortView, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, MarkReadResult, MediaAsset, MediaListResponse, Message, MessageType, NearestOptions, NearestResponse, NotFilter, OnboardingStatus, OrFilter, OrderBy, PingResult, PresignData, PullChangesCursor, PullChangesResult, PurchaseOption, PurchaseRequest, PurchaseResult, PushChangesResult, PushPlatform, PushToken, ReferralClaim, ReferralCode, Report, ReportRequest, Review, ReviewCreate, ReviewUpdate, Role, SDK_VERSION, SendMessageRequest, Session, SocialProvider, Store, Streak, SyncChange, SyncConflict, User, UserEntitlement, XpBalance, XpTransaction, getCoreWasm };
+export { Achievement, AchievementProgress, AiMessage, AiMessageRequest, AiMessageResponse, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AndFilter, AppSession, AuthResult, CatalogItem, Challenge, ChallengeProgress, CollectionSubscription, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationParticipant, ConversationSubscription, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DiagnosticsEnvironment, EntitlementSource, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, Friendship, FriendshipState, Group, GroupCreate, GroupMember, GroupUpdate, InventoryItem, InvokeOptions, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortMember, LeagueCohortView, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, MarkReadResult, MediaAsset, MediaListResponse, Message, type MessageChange, MessageType, NearestOptions, NearestResponse, NotFilter, OnboardingStatus, OrFilter, OrderBy, PingResult, PresignData, PullChangesCursor, PullChangesResult, PurchaseOption, PurchaseRequest, PurchaseResult, PushChangesResult, PushPlatform, PushToken, type RealtimeChange, ReferralClaim, ReferralCode, Report, ReportRequest, Review, ReviewCreate, ReviewUpdate, Role, type RowChangeOp, SDK_VERSION, SendMessageRequest, Session, SocialProvider, Store, Streak, type SubscribeOptions, SyncChange, SyncConflict, type Unsubscribe, User, UserEntitlement, XpBalance, XpTransaction, getCoreWasm };
 //# sourceMappingURL=index.d.ts.map

package/dist-rn/index.js

@@ -99,8 +99,173 @@ function toAmbaApiError(err) {
 	return new AmbaApiError("UNKNOWN_ERROR", String(err));
 }
 
+//#endregion
+//#region src/realtime.ts
+const INITIAL_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 15e3;
+/**
+* Builder returned by `Amba.collection(name)`. Chain `.where(...)` to
+* narrow, then `.subscribe(cb)` to start streaming.
+*/
+var CollectionSubscription = class {
+	filters = {};
+	constructor(ctx, name) {
+		this.ctx = ctx;
+		this.name = name;
+	}
+	/** Add an equality filter. Chainable. All filters must match (AND). */
+	where(column, value) {
+		this.filters[column] = value;
+		return this;
+	}
+	/**
+	* Start listening. `cb` fires once per matching row change. Returns an
+	* unsubscribe handle — call it to close the connection.
+	*/
+	subscribe(cb, options = {}) {
+		if (!this.ctx.authHeaders()) throw new Error("Amba.collection().subscribe() requires an authenticated session — call Amba.auth.signIn*/verify* first.");
+		const qs = Object.keys(this.filters).length > 0 ? `?where=${encodeURIComponent(JSON.stringify(this.filters))}` : "";
+		return openStream({
+			url: `${this.ctx.baseUrl}/v1/client/realtime/collections/${encodeURIComponent(this.name)}${qs}`,
+			authHeaders: this.ctx.authHeaders,
+			onChange: cb,
+			options
+		});
+	}
+};
+/**
+* Open a streamed GET to a realtime endpoint and dispatch row-change events
+* to `onChange`. Reconnects with exponential backoff until the returned
+* unsubscribe handle is invoked. Shared by both collection and conversation
+* subscriptions — the only thing that differs between them is the URL.
+*
+* Uses `fetch` + a streamed response body (rather than the browser's
+* native `EventSource`) because `EventSource` cannot set request headers —
+* which would force the session token into the URL query string, where it
+* would leak into access logs. Streaming `fetch` keeps auth in headers.
+*/
+function openStream(args) {
+	let stopped = false;
+	let controller = null;
+	let backoff = INITIAL_BACKOFF_MS;
+	const run = async () => {
+		while (!stopped) {
+			controller = new AbortController();
+			try {
+				const headers = args.authHeaders();
+				if (!headers) throw new Error("no active session");
+				const resp = await fetch(args.url, {
+					method: "GET",
+					headers: {
+						...headers,
+						Accept: "text/event-stream"
+					},
+					signal: controller.signal
+				});
+				if (!resp.ok || !resp.body) throw new Error(`realtime connect failed: HTTP ${resp.status}`);
+				await consume(resp.body, args, () => {
+					backoff = INITIAL_BACKOFF_MS;
+					args.options.onOpen?.();
+				});
+			} catch (err) {
+				if (stopped) break;
+				args.options.onError?.(err);
+			}
+			if (stopped) break;
+			await delay(backoff);
+			backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+		}
+	};
+	run();
+	return () => {
+		stopped = true;
+		controller?.abort();
+	};
+}
+async function consume(body, args, onFirstFrame) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let sawFrame = false;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) return;
+		buffer += decoder.decode(value, { stream: true });
+		let idx;
+		while ((idx = buffer.indexOf("\n\n")) !== -1) {
+			const frame = buffer.slice(0, idx);
+			buffer = buffer.slice(idx + 2);
+			if (!sawFrame) {
+				sawFrame = true;
+				onFirstFrame();
+			}
+			dispatchFrame(frame, args.onChange);
+		}
+	}
+}
+function dispatchFrame(frame, onChange) {
+	let event = "";
+	const dataLines = [];
+	for (const line of frame.split("\n")) {
+		if (line.startsWith(":")) continue;
+		if (line.startsWith("event:")) event = line.slice(6).trim();
+		else if (line.startsWith("data:")) dataLines.push(line.slice(5).trim());
+	}
+	if (event !== "change") return;
+	try {
+		const payload = JSON.parse(dataLines.join("\n"));
+		onChange({
+			op: payload.op,
+			row: payload.row,
+			truncated: payload.truncated
+		});
+	} catch {}
+}
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* 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.
+*/
+var ConversationSubscription = class {
+	constructor(ctx, conversationId) {
+		this.ctx = ctx;
+		this.conversationId = conversationId;
+	}
+	subscribe(cb, options = {}) {
+		if (!this.ctx.authHeaders()) throw new Error("Amba.messaging.conversation().subscribe() requires an authenticated session — call Amba.auth.signIn*/verify* first.");
+		return openStream({
+			url: `${this.ctx.baseUrl}/v1/client/realtime/conversations/${encodeURIComponent(this.conversationId)}`,
+			authHeaders: this.ctx.authHeaders,
+			onChange: cb,
+			options
+		});
+	}
+};
+
 //#endregion
 //#region src/index.ts
+const DEFAULT_API_URL = "https://api.amba.dev";
+/**
+* Default host that serves deployed functions. `Amba.functions.invoke(name)`
+* targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
+* `functionsBaseUrl` override is configured. The `<projectId>` label is the
+* server-resolved id (from `diagnostics.ping`), which the function router
+* accepts directly.
+*/
+const DEFAULT_FUNCTIONS_HOST = "fn.amba.host";
 /**
 * Internal state — one instance per page. Created lazily by `Amba.configure()`.
 */
@@ -111,6 +276,26 @@ let coreInstance = null;
 * core finishes initializing.
 */
 let _configuredProjectId = null;
+/**
+* Realtime (`Amba.collection(name).subscribe`) needs the API base URL,
+* client key, and current session token in the TS layer to open the
+* streamed connection — the engine doesn't expose them back. We capture
+* the base URL + client key at configure-time and the session token from
+* every auth result (the engine rotates it internally on refresh; the
+* subscribe connection picks up the latest at connect time).
+*/
+let _configuredApiUrl = DEFAULT_API_URL;
+let _configuredClientKey = null;
+let _currentSessionToken = null;
+/**
+* Functions invocation state. `_configuredFunctionsBaseUrl` is the optional
+* override from `Amba.configure({ functionsBaseUrl })`. When it's null, the
+* default-host path resolves the project id once via `diagnostics.ping` and
+* caches it in `_resolvedFunctionsProjectId` so subsequent invokes skip the
+* round-trip. Both reset on every `configure()`.
+*/
+let _configuredFunctionsBaseUrl = null;
+let _resolvedFunctionsProjectId = null;
 function requireCore() {
 	if (!coreInstance) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) at app start before any other API.");
 	return coreInstance;
@@ -148,9 +333,40 @@ function notifyAuthSubscribers(session) {
 	}
 }
 async function notifyFromAuthResult(result) {
+	if (result?.session_token) _currentSessionToken = result.session_token;
 	notifyAuthSubscribers(snapshotSession(result.user));
 }
 /**
+* Build the auth headers for a realtime subscribe connection, or `null`
+* when there's no live session. Read lazily at connect-time so reconnects
+* pick up a rotated session token.
+*/
+function realtimeAuthHeaders() {
+	if (!_configuredClientKey || !_currentSessionToken) return null;
+	return {
+		"X-Api-Key": _configuredClientKey,
+		Authorization: `Bearer ${_currentSessionToken}`
+	};
+}
+/**
+* Resolve the full invocation URL for a deployed function.
+*
+* With `functionsBaseUrl` configured we POST to `<base>/<name>` verbatim
+* (custom domains / non-prod). Otherwise we resolve the server-side project
+* id once (via `diagnostics.ping`, cached) and target
+* `https://<projectId>.fn.amba.host/<name>` — the function router accepts the
+* project id as the host label directly.
+*/
+async function resolveFunctionUrl(name) {
+	if (_configuredFunctionsBaseUrl) return `${_configuredFunctionsBaseUrl.replace(/\/$/, "")}/${encodeURIComponent(name)}`;
+	if (!_resolvedFunctionsProjectId) {
+		const ping = await Amba.diagnostics.ping();
+		if (!ping.ok || !ping.server_project_id) throw new AmbaApiError("FUNCTIONS_HOST_UNRESOLVED", "Could not resolve the functions host for this project. Pass `functionsBaseUrl` to Amba.configure() to invoke functions explicitly.", ping);
+		_resolvedFunctionsProjectId = ping.server_project_id;
+	}
+	return `https://${_resolvedFunctionsProjectId}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
+}
+/**
 * Top-level SDK namespace.
 *
 * Stateless from the JS side — all state lives in the SDK runtime. Calling
@@ -176,6 +392,10 @@ const Amba = {
 			throw toAmbaApiError(err);
 		}
 		_configuredProjectId = config.projectId;
+		_configuredApiUrl = config.apiUrl ?? DEFAULT_API_URL;
+		_configuredClientKey = config.clientKey;
+		_configuredFunctionsBaseUrl = config.functionsBaseUrl ?? null;
+		_resolvedFunctionsProjectId = null;
 	},
 	get projectId() {
 		if (!_configuredProjectId) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) at app start before any other API.");
@@ -257,6 +477,9 @@ const Amba = {
 		linkEmailOtp: async (email, code) => {
 			return await coreCall((c) => c.linkEmailOtp(email, code));
 		},
+		linkEmailPassword: async (email, password) => {
+			return await coreCall((c) => c.linkEmailPassword(email, password));
+		},
 		unlinkSmsOtp: async () => {
 			return await coreCall((c) => c.unlinkSmsOtp());
 		},
@@ -274,6 +497,7 @@ const Amba = {
 		},
 		signOut: async (rotateAnonymousId = false) => {
 			await coreCall((c) => c.signOut(rotateAnonymousId));
+			_currentSessionToken = null;
 			notifyAuthSubscribers(null);
 		},
 		refresh: async () => {
@@ -317,6 +541,10 @@ const Amba = {
 			await coreCall((c) => c.sessionsRevoke(sessionId));
 		}
 	},
+	collection: (name) => new CollectionSubscription({
+		baseUrl: _configuredApiUrl,
+		authHeaders: realtimeAuthHeaders
+	}, name),
 	collections: {
 		find: async (name, options = {}) => {
 			return await coreCall((c) => c.collectionsFind(name, encodeJson(options)));
@@ -474,6 +702,45 @@ const Amba = {
 	ai: { anthropic: { messages: { create: async (request) => {
 		return await coreCall((c) => c.aiAnthropicMessages(encodeJson(request)));
 	} } } },
+	functions: { invoke: async (name, body, options) => {
+		requireCore();
+		if (!_configuredClientKey) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) before Amba.functions.invoke().");
+		if (!name || name.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.functions.invoke: a function name is required.");
+		const url = await resolveFunctionUrl(name);
+		const method = options?.method ?? "POST";
+		const headers = {
+			"X-Api-Key": _configuredClientKey,
+			...options?.headers ?? {}
+		};
+		if (_currentSessionToken) headers["Authorization"] = `Bearer ${_currentSessionToken}`;
+		let requestBody;
+		if (body !== void 0 && method !== "GET") {
+			headers["content-type"] = "application/json";
+			requestBody = JSON.stringify(body);
+		}
+		let resp;
+		try {
+			resp = await fetch(url, {
+				method,
+				headers,
+				body: requestBody
+			});
+		} catch (err) {
+			throw new AmbaApiError("NETWORK_ERROR", `Amba.functions.invoke("${name}") network error: ${String(err)}`);
+		}
+		const text = await resp.text();
+		let parsed = void 0;
+		if (text.length > 0) try {
+			parsed = JSON.parse(text);
+		} catch {
+			parsed = text;
+		}
+		if (!resp.ok) {
+			const envelope = parsed && typeof parsed === "object" ? parsed : void 0;
+			throw new AmbaApiError(typeof envelope?.error?.code === "string" ? envelope.error.code : `HTTP_${resp.status}`, typeof envelope?.error?.message === "string" ? envelope.error.message : typeof parsed === "string" && parsed.length > 0 ? parsed : `Amba.functions.invoke("${name}") failed with status ${resp.status}`, parsed);
+		}
+		return parsed;
+	} },
 	config: { fetch: async () => {
 		return await coreCall((c) => c.configFetch());
 	} },
@@ -580,7 +847,12 @@ const Amba = {
 		getMessage: async (conversationId, messageId) => {
 			return await coreCall((c) => c.messagingGetMessage(conversationId, messageId));
 		},
-		markRead: async (conversationId) => await coreCall((c) => c.messagingMarkRead(conversationId))
+		addParticipant: async (conversationId, userId) => await coreCall((c) => c.messagingAddParticipant(conversationId, userId)),
+		markRead: async (conversationId) => await coreCall((c) => c.messagingMarkRead(conversationId)),
+		conversation: (conversationId) => new ConversationSubscription({
+			baseUrl: _configuredApiUrl,
+			authHeaders: realtimeAuthHeaders
+		}, conversationId)
 	},
 	moderation: {
 		reportUser: async (request) => await coreCall((c) => c.moderationReportUser(encodeJson(request))),
@@ -638,8 +910,8 @@ function getCoreWasm() {
 * `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).
 */
-const SDK_VERSION = "4.0.2";
+const SDK_VERSION = "4.0.4";
 
 //#endregion
-export { Amba, AmbaApiError, SDK_VERSION, getCoreWasm };
+export { Amba, AmbaApiError, CollectionSubscription, ConversationSubscription, SDK_VERSION, getCoreWasm };
 //# sourceMappingURL=index.js.map