@layers/amba-web 4.0.1 → 4.0.3

package/dist-rn/index.d.ts

@@ -505,6 +505,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;
@@ -716,6 +728,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
@@ -983,6 +1093,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>>;
@@ -1315,12 +1442,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 +1559,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.1";
+declare const SDK_VERSION = "4.0.3";
 //#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, 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,165 @@ 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";
 /**
 * Internal state — one instance per page. Created lazily by `Amba.configure()`.
 */
@@ -111,6 +268,17 @@ 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;
 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 +316,22 @@ 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}`
+	};
+}
+/**
 * Top-level SDK namespace.
 *
 * Stateless from the JS side — all state lives in the SDK runtime. Calling
@@ -176,6 +357,8 @@ const Amba = {
 			throw toAmbaApiError(err);
 		}
 		_configuredProjectId = config.projectId;
+		_configuredApiUrl = config.apiUrl ?? DEFAULT_API_URL;
+		_configuredClientKey = config.clientKey;
 	},
 	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.");
@@ -274,6 +457,7 @@ const Amba = {
 		},
 		signOut: async (rotateAnonymousId = false) => {
 			await coreCall((c) => c.signOut(rotateAnonymousId));
+			_currentSessionToken = null;
 			notifyAuthSubscribers(null);
 		},
 		refresh: async () => {
@@ -317,6 +501,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)));
@@ -580,7 +768,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 +831,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.1";
+const SDK_VERSION = "4.0.3";
 
 //#endregion
-export { Amba, AmbaApiError, SDK_VERSION, getCoreWasm };
+export { Amba, AmbaApiError, CollectionSubscription, ConversationSubscription, SDK_VERSION, getCoreWasm };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba-web",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "amba SDK for browser apps — full SDK 4.0 surface (34 modules: auth + magic link, users, sessions, sync, collections + vector search, storage + list/delete/download, push, entitlements, flags, config, deep links, onboarding, content, messaging, friends, groups, feeds, reviews, moderation, roles, referrals, achievements, xp, streaks, challenges, leaderboards, leagues, currencies, inventory, stores, catalog, ai, diagnostics).",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@layers/amba-core": "^4.0.1"
+    "@layers/amba-core": "^4.0.3"
   },
   "devDependencies": {
     "@types/node": "^22.13.14",