@layers/amba-web 4.0.8 → 4.0.10

package/dist-rn/index.d.ts

@@ -94,10 +94,9 @@ interface AuthResult {
 /**
  * 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`.
+ * `sessionToken` / `refreshToken` are live credentials from the SDK-managed
+ * durable browser session. Do not log them or duplicate them into app-owned
+ * storage. Callers that only need auth state should use `Amba.isAuthenticated`.
  */
 interface Session {
   sessionToken: string;
@@ -656,12 +655,17 @@ interface GroupCreate {
   name: string;
   description?: string;
   avatar_url?: string;
+  /** Set false for a private group that can own group-scoped collection rows. */
+  is_public?: boolean;
+  max_members?: number;
   metadata?: unknown;
 }
 interface GroupUpdate {
   name?: string;
   description?: string;
   avatar_url?: string;
+  is_public?: boolean;
+  max_members?: number;
   metadata?: unknown;
 }
 type ConversationType = "direct" | "group";
@@ -1396,6 +1400,69 @@ interface InvokeOptions {
    */
   onTraceId?: (traceId: string | null) => void;
 }
+/**
+ * Immutable browser collection scope for a server-verified group context.
+ * Each method carries its own `groupId` into the Rust request path; no mutable
+ * global header state is used, so parallel group A/group B calls cannot leak.
+ *
+ * Group-scoped writes deliberately bypass the global offline outbox. Replaying
+ * a queued group mutation without its membership context would be unsafe;
+ * callers receive the real network outcome and can retry in the same scope.
+ */
+declare class AmbaGroupScopedClient {
+  readonly groupId: string;
+  constructor(groupId: string);
+  asGroup(groupId: string): AmbaGroupScopedClient;
+  inGroup(groupId: string): AmbaGroupScopedClient;
+  collection<T = unknown>(name: string): CollectionSubscription<T>;
+  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;
+      };
+    }>;
+    upsert: <T = unknown>(name: string, row: Record<string, unknown>, options: UpsertOptions) => Promise<T>;
+    deleteWhere: (name: string, filter: Filter) => Promise<DeleteManyResult>;
+    restore: <T = unknown>(name: string, id: string) => Promise<T>;
+    transaction: (operations: TransactionOp[]) => Promise<TransactionOpResult[]>;
+    findNearest: <T = unknown>(name: string, options: NearestOptions) => Promise<NearestResponse<T>>;
+    count: (name: string, filter?: Filter) => Promise<number>;
+    optimisticInsert: <T = unknown, TApply = unknown>(name: string, row: Record<string, unknown>, view: {
+      apply: () => TApply;
+      rollback: (applied: TApply) => void;
+    }) => Promise<T>;
+    optimisticUpdate: <T = unknown, TApply = unknown>(name: string, id: string, set: Record<string, unknown>, view: {
+      apply: () => TApply;
+      rollback: (applied: TApply) => void;
+    }) => Promise<T>;
+    optimisticDelete: <TApply = unknown>(name: string, id: string, view: {
+      apply: () => TApply;
+      rollback: (applied: TApply) => void;
+    }) => Promise<{
+      data: {
+        deleted: boolean;
+      };
+    }>;
+    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;
+      isNull: (column: string) => Filter;
+      isNotNull: (column: string) => Filter;
+      and: (...filters: Filter[]) => Filter;
+      or: (...filters: Filter[]) => Filter;
+      not: (filter: Filter) => Filter;
+    };
+  };
+}
 /**
  * Top-level SDK namespace.
  *
@@ -1623,9 +1690,9 @@ declare const Amba: {
     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.
+     * Tokens are returned from the browser's durable session snapshot. Treat
+     * them as credentials: do not log them or copy them into app-managed
+     * storage.
      */
     getSession: () => Promise<Session | null>;
     /**
@@ -1680,6 +1747,15 @@ declare const Amba: {
      */
     revoke: (sessionId: string) => Promise<void>;
   };
+  /**
+   * Scope collection calls to a group the current session belongs to.
+   * Membership and role are verified by the API; an unknown/unauthorized
+   * group is rejected server-side. The returned caller is immutable and safe
+   * to use concurrently with callers scoped to other groups.
+   */
+  asGroup: (groupId: string) => AmbaGroupScopedClient;
+  /** Alias of {@link Amba.asGroup}. */
+  inGroup: (groupId: string) => AmbaGroupScopedClient;
   /**
    * Live collection subscriptions (SDK 4.0). Returns a builder — chain
    * `.where(column, value)` to narrow, then `.subscribe(cb)` to start
@@ -2063,6 +2139,10 @@ declare const Amba: {
    * hand-rolling `fetch` against a function URL, which leaves the call
    * unauthenticated (a footgun when the function holds secrets).
    *
+   * The function host is selected in order from `functionsBaseUrl`, a
+   * UUID-shaped configured project id, or a deduped diagnostics ping that
+   * supplies the authoritative server-side project id.
+   *
    * 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
@@ -2431,7 +2511,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.8";
+declare const SDK_VERSION = "4.0.10";
 //#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 };
+export { Achievement, AchievementProgress, AiContentBlock, AiImageInput, AiMessage, AiMessageRequest, AiMessageResponse, type AiStreamDelta, type AiStreamDone, type AiStreamEvent, type AiStreamOptions, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AmbaGroupScopedClient, AndFilter, AppSession, AuthResult, CatalogItem, Challenge, ChallengeProgress, CollectionSubscription, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationParticipant, ConversationSubscription, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DeleteManyResult, DiagnosticsEnvironment, EntitlementPeriodType, EntitlementStore, EventExplainResult, ExplainMatchedRule, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, type FlushResult, Friendship, FriendshipState, type GamificationChange, type GamificationKind, GamificationSubscription, Group, GroupCreate, GroupMember, GroupUpdate, IncludeClause, InventoryItem, InvokeOptions, type KvStore, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortMember, LeagueCohortView, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, LocalNotificationHandle, LocalNotificationTrigger, type LocalNotificationsNamespace, MarkReadResult, MediaAsset, MediaCatalog, MediaCatalogItem, MediaListResponse, Message, type MessageChange, MessageType, NearestOptions, NearestResponse, NotFilter, Offering, OfferingPackage, OfferingProduct, OfferingsResult, OnboardingStatus, OrFilter, OrderBy, type OutboxOp, type OutboxOpKind, PingResult, PresignData, PullChangesCursor, PullChangesResult, PurchaseOption, PurchaseRequest, PurchaseResult, PushChangesResult, PushPlatform, PushToken, type RealtimeChange, ReferralClaim, ReferralCode, Report, ReportRequest, RestoreResult, Review, ReviewCreate, ReviewUpdate, Role, type RowChangeOp, SDK_VERSION, ScheduleLocalNotificationInput, ScheduledLocalNotification, SendMessageRequest, Session, SocialProvider, Store, Streak, type SubscribeOptions, SyncChange, SyncConflict, TransactionOp, TransactionOpResult, type Unsubscribe, UpsertOptions, User, UserEntitlement, XpBalance, XpTransaction, getCoreWasm, withOptimistic };
 //# sourceMappingURL=index.d.ts.map

package/dist-rn/index.js

@@ -2,28 +2,46 @@
 /**
 * Browser localStorage adapter for SDK identity persistence.
 *
-* The SDK runtime currently re-seeds an `anonymous_id` on every page load.
-* This adapter is the documented home for storage-prefix handling so
-* customers can override the localStorage key prefix used by the
-* (eventual) identity cache.
+* Browsers can deny or throw on localStorage access (privacy mode, sandboxed
+* iframes, quota exhaustion). Persistence is best-effort: storage failures
+* must never turn a successful auth/network operation into an SDK failure.
 */
 var LocalStoragePersistence = class {
 	constructor(prefix) {
 		this.prefix = prefix;
 	}
-	/** Read everything we'd want to hydrate at init. No-op until wired through. */
-	hydrate() {}
+	get storage() {
+		try {
+			return globalThis.localStorage ?? null;
+		} catch {
+			return null;
+		}
+	}
+	get available() {
+		return this.storage !== null;
+	}
 	read(key) {
-		if (typeof localStorage === "undefined") return null;
-		return localStorage.getItem(`${this.prefix}:${key}`);
+		const storage = this.storage;
+		if (!storage) return null;
+		try {
+			return storage.getItem(`${this.prefix}:${key}`);
+		} catch {
+			return null;
+		}
 	}
 	write(key, value) {
-		if (typeof localStorage === "undefined") return;
-		localStorage.setItem(`${this.prefix}:${key}`, value);
+		const storage = this.storage;
+		if (!storage) return;
+		try {
+			storage.setItem(`${this.prefix}:${key}`, value);
+		} catch {}
 	}
 	delete(key) {
-		if (typeof localStorage === "undefined") return;
-		localStorage.removeItem(`${this.prefix}:${key}`);
+		const storage = this.storage;
+		if (!storage) return;
+		try {
+			storage.removeItem(`${this.prefix}:${key}`);
+		} catch {}
 	}
 };
 
@@ -1340,11 +1358,10 @@ 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.
+* `functionsBaseUrl` override is configured.
 */
 const DEFAULT_FUNCTIONS_HOST = "fn.amba.host";
+const PROJECT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
 * Internal state — one instance per page. Created lazily by `Amba.configure()`.
 */
@@ -1366,15 +1383,73 @@ let _configuredProjectId = null;
 let _configuredApiUrl = DEFAULT_API_URL;
 let _configuredClientKey = null;
 let _currentSessionToken = null;
+let _currentRefreshToken = null;
+let _currentSessionExpiresAt = null;
+let _currentUser = null;
+const BROWSER_IDENTITY_VERSION = 1;
+const DEFAULT_SESSION_TTL_MS = 3600 * 1e3;
+function identityStorageKey(projectId) {
+	return `identity:v${BROWSER_IDENTITY_VERSION}:project:${encodeURIComponent(projectId)}`;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function containsControlCharacter(value) {
+	return Array.from(value).some((char) => {
+		const code = char.charCodeAt(0);
+		return code <= 31 || code === 127;
+	});
+}
+/** Read + validate a project-bound identity snapshot. Corrupt or cross-project
+* data is removed instead of being handed to the core. */
+function readPersistedIdentity(persistence, projectId) {
+	const key = identityStorageKey(projectId);
+	const raw = persistence.read(key);
+	if (!raw) return null;
+	try {
+		const value = JSON.parse(raw);
+		const hasTokens = value.session_token != null || value.refresh_token != null;
+		if (value.version !== BROWSER_IDENTITY_VERSION || value.project_id !== projectId || !isNonEmptyString(value.anonymous_id) || hasTokens && !isNonEmptyString(value.app_user_id) || value.session_token != null && !isNonEmptyString(value.refresh_token) || value.session_token != null && !isNonEmptyString(value.session_token) || value.refresh_token != null && !isNonEmptyString(value.refresh_token) || value.expires_at != null && (!isNonEmptyString(value.expires_at) || !Number.isFinite(Date.parse(value.expires_at)))) throw new Error("invalid identity snapshot");
+		const expiresAt = isNonEmptyString(value.expires_at) ? Date.parse(value.expires_at) : NaN;
+		const sessionExpired = value.session_token != null && Number.isFinite(expiresAt) && expiresAt <= Date.now();
+		return {
+			version: BROWSER_IDENTITY_VERSION,
+			project_id: projectId,
+			anonymous_id: value.anonymous_id,
+			app_user_id: isNonEmptyString(value.app_user_id) ? value.app_user_id : null,
+			session_token: sessionExpired ? null : value.session_token ?? null,
+			refresh_token: value.refresh_token ?? null,
+			expires_at: sessionExpired ? null : value.expires_at ?? null,
+			user: value.user && typeof value.user === "object" && isNonEmptyString(value.user.id) ? value.user : null
+		};
+	} catch {
+		persistence.delete(key);
+		return null;
+	}
+}
+function writeIdentitySnapshot() {
+	if (!_persistence?.available || !_configuredProjectId || !coreInstance) return;
+	const snapshot = {
+		version: BROWSER_IDENTITY_VERSION,
+		project_id: _configuredProjectId,
+		anonymous_id: coreInstance.anonymousId(),
+		app_user_id: coreInstance.appUserId() ?? null,
+		session_token: _currentSessionToken,
+		refresh_token: _currentRefreshToken,
+		expires_at: _currentSessionExpiresAt,
+		user: _currentUser
+	};
+	_persistence.write(identityStorageKey(_configuredProjectId), JSON.stringify(snapshot));
+}
 /**
 * 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()`.
+* override from `Amba.configure({ functionsBaseUrl })`. The default-host path
+* caches its resolved project id and shares an in-flight diagnostics fallback
+* across concurrent invokes. All three reset on every `configure()`.
 */
 let _configuredFunctionsBaseUrl = null;
 let _resolvedFunctionsProjectId = null;
+let _functionsProjectIdInflight = null;
 /**
 * Offline-resilience state. `_persistence` is the localStorage-backed store
 * captured at configure-time; `_offlineQueue` is lazily built the first time
@@ -1442,7 +1517,7 @@ async function replayOutboxOp(op) {
 	switch (op.kind) {
 		case "collection.insert":
 			await coreCall((c) => c.collectionsInsert(op.collection, encodeJson({
-				...op.payload ?? {},
+				...op.payload,
 				idempotency_key: op.idempotencyKey
 			})));
 			return;
@@ -1563,12 +1638,12 @@ function toWireTransactionOp(op) {
 	return wire;
 }
 function snapshotSession(user) {
-	if (!user) return null;
+	if (!user || !_currentSessionToken) return null;
 	return {
-		sessionToken: "",
-		refreshToken: "",
+		sessionToken: _currentSessionToken,
+		refreshToken: _currentRefreshToken ?? "",
 		user,
-		expiresAt: ""
+		expiresAt: _currentSessionExpiresAt ?? ""
 	};
 }
 function notifyAuthSubscribers(session) {
@@ -1579,7 +1654,11 @@ function notifyAuthSubscribers(session) {
 	}
 }
 async function notifyFromAuthResult(result) {
-	if (result?.session_token) _currentSessionToken = result.session_token;
+	_currentSessionToken = result.session_token;
+	_currentRefreshToken = result.refresh_token;
+	_currentSessionExpiresAt = result.expires_at && Number.isFinite(Date.parse(result.expires_at)) ? result.expires_at : new Date(Date.now() + DEFAULT_SESSION_TTL_MS).toISOString();
+	_currentUser = result.user;
+	writeIdentitySnapshot();
 	notifyAuthSubscribers(snapshotSession(result.user));
 }
 /**
@@ -1626,22 +1705,156 @@ function buildAiStreamRequest(path, request) {
 /**
 * 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.
+* Resolution checks `functionsBaseUrl` first, then uses a UUID-shaped
+* configured project id directly, and finally falls back to a deduped
+* `diagnostics.ping` for the authoritative server-side project id. The
+* resolved default-host id is cached for subsequent invokes.
 */
 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://${await resolveFunctionsProjectId()}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
+}
+async function resolveFunctionsProjectId() {
+	if (_resolvedFunctionsProjectId) return _resolvedFunctionsProjectId;
+	if (_configuredProjectId && PROJECT_ID_PATTERN.test(_configuredProjectId)) {
+		_resolvedFunctionsProjectId = _configuredProjectId.toLowerCase();
+		return _resolvedFunctionsProjectId;
 	}
-	return `https://${_resolvedFunctionsProjectId}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
+	if (!_functionsProjectIdInflight) {
+		const configuredProjectId = _configuredProjectId;
+		const resolution = (async () => {
+			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);
+			if (_configuredProjectId === configuredProjectId && !_configuredFunctionsBaseUrl) _resolvedFunctionsProjectId = ping.server_project_id;
+			return ping.server_project_id;
+		})();
+		_functionsProjectIdInflight = resolution;
+		resolution.then(() => {
+			if (_functionsProjectIdInflight === resolution) _functionsProjectIdInflight = null;
+		}, () => {
+			if (_functionsProjectIdInflight === resolution) _functionsProjectIdInflight = null;
+		});
+	}
+	return _functionsProjectIdInflight;
 }
 /**
+* Immutable browser collection scope for a server-verified group context.
+* Each method carries its own `groupId` into the Rust request path; no mutable
+* global header state is used, so parallel group A/group B calls cannot leak.
+*
+* Group-scoped writes deliberately bypass the global offline outbox. Replaying
+* a queued group mutation without its membership context would be unsafe;
+* callers receive the real network outcome and can retry in the same scope.
+*/
+var AmbaGroupScopedClient = class AmbaGroupScopedClient {
+	groupId;
+	constructor(groupId) {
+		const normalized = groupId.trim();
+		if (!normalized || containsControlCharacter(normalized)) throw new AmbaApiError("VALIDATION_ERROR", "Amba.asGroup: groupId must be non-empty and contain no control characters");
+		this.groupId = normalized;
+	}
+	asGroup(groupId) {
+		return new AmbaGroupScopedClient(groupId);
+	}
+	inGroup(groupId) {
+		return this.asGroup(groupId);
+	}
+	collection(name) {
+		const groupId = this.groupId;
+		return new CollectionSubscription({
+			baseUrl: _configuredApiUrl,
+			authHeaders: () => {
+				const headers = realtimeAuthHeaders();
+				return headers ? {
+					...headers,
+					"X-Group-Context": groupId
+				} : null;
+			}
+		}, name);
+	}
+	collections = {
+		find: async (name, options = {}) => await coreCall((c) => c.collectionsFind(name, encodeJson(options), this.groupId)),
+		findOne: async (name, id) => await coreCall((c) => c.collectionsFindOne(name, id, this.groupId)),
+		insert: async (name, row) => await coreCall((c) => c.collectionsInsert(name, encodeJson(row), this.groupId)),
+		update: async (name, id, set) => await coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set), this.groupId)),
+		delete: async (name, id) => await coreCall((c) => c.collectionsDelete(name, id, this.groupId)),
+		upsert: async (name, row, options) => await coreCall((c) => c.collectionsUpsert(name, encodeJson(row), encodeJson({
+			on_conflict: options.onConflict,
+			conflict_target: options.conflictTarget
+		}), this.groupId)),
+		deleteWhere: async (name, filter) => await coreCall((c) => c.collectionsDeleteWhere(name, encodeJson(filter), this.groupId)),
+		restore: async (name, id) => await coreCall((c) => c.collectionsRestore(name, id, this.groupId)),
+		transaction: async (operations) => {
+			return (await coreCall((c) => c.collectionsTransaction(encodeJson(operations.map(toWireTransactionOp)), this.groupId))).data;
+		},
+		findNearest: async (name, options) => await coreCall((c) => c.collectionsFindNearest(name, encodeJson(options), this.groupId)),
+		count: async (name, filter) => await coreCall((c) => c.collectionsCount(name, filter ? encodeJson(filter) : void 0, this.groupId)),
+		optimisticInsert: async (name, row, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => coreCall((c) => c.collectionsInsert(name, encodeJson(row), this.groupId)),
+			rollback: view.rollback
+		}),
+		optimisticUpdate: async (name, id, set, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set), this.groupId)),
+			rollback: view.rollback
+		}),
+		optimisticDelete: async (name, id, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => coreCall((c) => c.collectionsDelete(name, id, this.groupId)),
+			rollback: view.rollback
+		}),
+		where: {
+			eq: (column, value) => ({
+				column,
+				op: "eq",
+				value
+			}),
+			ne: (column, value) => ({
+				column,
+				op: "ne",
+				value
+			}),
+			gt: (column, value) => ({
+				column,
+				op: "gt",
+				value
+			}),
+			gte: (column, value) => ({
+				column,
+				op: "gte",
+				value
+			}),
+			lt: (column, value) => ({
+				column,
+				op: "lt",
+				value
+			}),
+			lte: (column, value) => ({
+				column,
+				op: "lte",
+				value
+			}),
+			in: (column, values) => ({
+				column,
+				op: "in",
+				value: values
+			}),
+			isNull: (column) => ({
+				column,
+				op: "is_null"
+			}),
+			isNotNull: (column) => ({
+				column,
+				op: "is_not_null"
+			}),
+			and: (...filters) => ({ and: filters }),
+			or: (...filters) => ({ or: filters }),
+			not: (filter) => ({ not: filter })
+		}
+	};
+};
+/**
 * Top-level SDK namespace.
 *
 * Stateless from the JS side — all state lives in the SDK runtime. Calling
@@ -1659,7 +1872,7 @@ const Amba = {
 			else await initCore(); // Hermes-stripped Node-init block (DX-15) — see scripts/build-rn.mjs
 		}
 		const persistence = new LocalStoragePersistence(config.storagePrefix ?? "amba");
-		persistence.hydrate();
+		const restoredIdentity = readPersistedIdentity(persistence, config.projectId);
 		let nextCore;
 		try {
 			const { wasmClass } = await getCoreRuntime();
@@ -1672,6 +1885,13 @@ const Amba = {
 				consent_required: config.consentRequired,
 				debug: config.debug
 			}), globalThis.fetch.bind(globalThis));
+			if (restoredIdentity) nextCore.hydrateIdentity(encodeJson({
+				anonymous_id: restoredIdentity.anonymous_id,
+				app_user_id: restoredIdentity.app_user_id,
+				session_token: restoredIdentity.session_token,
+				refresh_token: restoredIdentity.refresh_token,
+				expires_at: restoredIdentity.expires_at
+			}));
 		} catch (err) {
 			throw toAmbaApiError(err);
 		}
@@ -1681,8 +1901,15 @@ const Amba = {
 		_configuredProjectId = config.projectId;
 		_configuredApiUrl = config.apiUrl ?? DEFAULT_API_URL;
 		_configuredClientKey = config.clientKey;
+		_currentSessionToken = nextCore.isAuthenticated() ? restoredIdentity?.session_token ?? null : null;
+		_currentRefreshToken = restoredIdentity?.refresh_token ?? null;
+		_currentSessionExpiresAt = nextCore.isAuthenticated() ? restoredIdentity?.expires_at ?? null : null;
+		_currentUser = nextCore.isAuthenticated() ? restoredIdentity?.user ?? null : null;
 		_configuredFunctionsBaseUrl = config.functionsBaseUrl ?? null;
 		_resolvedFunctionsProjectId = null;
+		_functionsProjectIdInflight = null;
+		if (!_configuredFunctionsBaseUrl && !PROJECT_ID_PATTERN.test(config.projectId)) resolveFunctionsProjectId().catch(() => {});
+		writeIdentitySnapshot();
 	},
 	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.");
@@ -1835,6 +2062,10 @@ const Amba = {
 		signOut: async (rotateAnonymousId = false) => {
 			await coreCall((c) => c.signOut(rotateAnonymousId));
 			_currentSessionToken = null;
+			_currentRefreshToken = null;
+			_currentSessionExpiresAt = null;
+			_currentUser = null;
+			writeIdentitySnapshot();
 			notifyAuthSubscribers(null);
 		},
 		refresh: async () => {
@@ -1843,11 +2074,17 @@ const Amba = {
 			return r;
 		},
 		me: async () => {
-			return await coreCall((c) => c.me());
+			const user = await coreCall((c) => c.me());
+			_currentUser = user;
+			writeIdentitySnapshot();
+			return user;
 		},
 		getSession: async () => {
 			if (!requireCore().isAuthenticated()) return null;
-			return snapshotSession(await coreCall((c) => c.me()));
+			const user = await coreCall((c) => c.me());
+			_currentUser = user;
+			writeIdentitySnapshot();
+			return snapshotSession(user);
 		},
 		getAnonymousId: async () => {
 			return requireCore().anonymousId();
@@ -1878,6 +2115,14 @@ const Amba = {
 			await coreCall((c) => c.sessionsRevoke(sessionId));
 		}
 	},
+	asGroup: (groupId) => {
+		requireCore();
+		return new AmbaGroupScopedClient(groupId);
+	},
+	inGroup: (groupId) => {
+		requireCore();
+		return new AmbaGroupScopedClient(groupId);
+	},
 	collection: (name) => new CollectionSubscription({
 		baseUrl: _configuredApiUrl,
 		authHeaders: realtimeAuthHeaders
@@ -2216,7 +2461,7 @@ const Amba = {
 		const method = options?.method ?? "POST";
 		const headers = {
 			"X-Api-Key": _configuredClientKey,
-			...options?.headers ?? {}
+			...options?.headers
 		};
 		if (_currentSessionToken) headers["Authorization"] = `Bearer ${_currentSessionToken}`;
 		let requestBody;
@@ -2427,8 +2672,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.8";
+const SDK_VERSION = "4.0.10";
 
 //#endregion
-export { Amba, AmbaApiError, CollectionSubscription, ConversationSubscription, GamificationSubscription, SDK_VERSION, getCoreWasm, withOptimistic };
+export { Amba, AmbaApiError, AmbaGroupScopedClient, CollectionSubscription, ConversationSubscription, GamificationSubscription, SDK_VERSION, getCoreWasm, withOptimistic };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba-web",
-  "version": "4.0.8",
+  "version": "4.0.10",
   "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.8"
+    "@layers/amba-core": "^4.0.10"
   },
   "devDependencies": {
     "@types/node": "^22.13.14",