@layers/amba-react-native 4.0.3 → 4.0.5

package/dist/index.js

@@ -350,10 +350,806 @@ function freshSeed() {
 	};
 }
 
+//#endregion
+//#region src/resilience.ts
+/**
+* Best-effort online probe. In a browser/RN runtime `navigator.onLine`
+* exists; under Node / SSR it doesn't, so we treat "unknown" as online
+* (the executor's own error handling then decides).
+*/
+function isOnline() {
+	const nav = typeof navigator !== "undefined" ? navigator : void 0;
+	if (nav && typeof nav.onLine === "boolean") return nav.onLine;
+	return true;
+}
+/**
+* Error codes the server raised deterministically — replaying them would fail
+* identically, so they're NEVER queued even when the device reports offline.
+* (A request can fail validation/auth/etc. while `navigator.onLine` is briefly
+* false; we must not buffer-and-retry those forever.)
+*/
+const DETERMINISTIC_ERROR_CODES = new Set([
+	"VALIDATION_ERROR",
+	"INVALID_ARGUMENT",
+	"INVALID_INPUT",
+	"UNAUTHORIZED",
+	"FORBIDDEN",
+	"NOT_FOUND",
+	"CONFLICT",
+	"CONSENT_NOT_GRANTED",
+	"NOT_INITIALIZED"
+]);
+/**
+* Is this a deterministic server rejection — a coded error the server would
+* raise identically on every replay (bad input, auth, not-found, conflict)? A
+* queued op that fails this way is poison: retrying it forever would wedge the
+* queue, so the flush DROPS it. Everything else (transport failures, 5xx
+* `HTTP_ERROR`, `RATE_LIMITED`, `CIRCUIT_OPEN`, anything uncoded) is treated as
+* transient and RETAINED for a later attempt — favoring retain over data loss.
+*/
+function isDeterministicError(err) {
+	const code = err?.code;
+	return typeof code === "string" && DETERMINISTIC_ERROR_CODES.has(code);
+}
+/**
+* Heuristic: does a thrown value look like a transient offline / transport
+* failure (vs a deterministic 4xx the server would reject again)? Used at
+* ENQUEUE time to decide whether a failed write is worth buffering — a
+* `VALIDATION_ERROR` will fail identically on replay, so it throws instead.
+*
+* A deterministic server error is excluded even when the device reports
+* offline: the request clearly reached the server (it got a coded response),
+* so retrying it on reconnect is pointless and would wedge the queue.
+*
+* NOTE: this is intentionally stricter than {@link isDeterministicError}'s
+* inverse — at enqueue time we only buffer GENUINE connectivity failures (a
+* non-offline 5xx/429 surfaces to the caller immediately rather than silently
+* queueing). The flush drop-decision uses {@link isDeterministicError} so a
+* transient 5xx/429 encountered DURING replay is retained, not dropped.
+*/
+function isOfflineError(err) {
+	const code = err?.code;
+	if (typeof code === "string" && DETERMINISTIC_ERROR_CODES.has(code)) return false;
+	if (code === "NETWORK_ERROR") return true;
+	const msg = err?.message;
+	if (typeof msg === "string" && /network (error|request failed)|failed to fetch|fetch failed|load failed/i.test(msg)) return true;
+	return !isOnline();
+}
+/** Generate a stable idempotency key for a queued op. */
+function newIdempotencyKey() {
+	const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
+	if (c && typeof c.randomUUID === "function") return `amba_obx_${c.randomUUID()}`;
+	return `amba_obx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+}
+/**
+* Durable, ordered, idempotent offline outbox. Opt-in via `Amba.offline`.
+* Single in-flight flush is enforced so concurrent reconnect signals don't
+* double-replay.
+*/
+var OfflineQueue = class {
+	store;
+	executor;
+	storageKey;
+	/**
+	* Notified when a queued op is dropped because its replay failed
+	* deterministically (a poisoned op the server will always reject). Lets the
+	* SDK surface the loss (debug log) instead of silently discarding.
+	*/
+	onDropped;
+	flushing = null;
+	/**
+	* Serializes every read-modify-write of the persisted outbox. Each mutation
+	* chains onto the previous one's promise, so concurrent `enqueue`s — and an
+	* `enqueue` racing the per-op removal inside `flush` — can never read a stale
+	* snapshot and clobber each other's writes (the lost-update bug). All
+	* storage mutations funnel through `mutate()`; only `pendingCount`/`pending`
+	* read without taking the lock (a stale-by-one read is harmless).
+	*/
+	tail = Promise.resolve();
+	/** Detach function for the auto-flush `online` listener, if installed. */
+	detachOnline = null;
+	/**
+	* Set once `dispose()` is called (on teardown / reconfigure). A disposed
+	* queue refuses to mutate the persisted outbox, so an orphaned in-flight
+	* flush — or any late call against the old instance — can never race the new
+	* queue by reading/writing the same storage after it's been replaced.
+	*/
+	disposed = false;
+	constructor(opts) {
+		this.store = opts.store;
+		this.executor = opts.executor;
+		this.storageKey = opts.storageKey ?? "offline_outbox";
+		this.onDropped = opts.onDropped;
+	}
+	/**
+	* Run `fn` exclusively against the persisted outbox: it chains after every
+	* prior mutation and the next one waits for it. `fn` receives the current
+	* ops and returns the next ops to persist plus its own result.
+	*/
+	mutate(fn, opts) {
+		const run = this.tail.then(async () => {
+			if (this.disposed && opts?.rejectIfDisposed) throw new Error("amba offline queue was disposed (SDK reconfigured)");
+			const { next, result } = await fn(await this.load());
+			await this.save(next);
+			return result;
+		});
+		this.tail = run.catch(() => void 0);
+		return run;
+	}
+	async load() {
+		const raw = await this.store.get(this.storageKey);
+		if (!raw) return [];
+		try {
+			const parsed = JSON.parse(raw);
+			return Array.isArray(parsed) ? parsed : [];
+		} catch {
+			return [];
+		}
+	}
+	async save(ops) {
+		if (this.disposed) return;
+		if (ops.length === 0) {
+			await this.store.delete(this.storageKey);
+			return;
+		}
+		await this.store.set(this.storageKey, JSON.stringify(ops));
+	}
+	/**
+	* Permanently retire this queue. Detaches the auto-flush listener and marks
+	* it disposed so it can no longer mutate the persisted outbox. Returns once
+	* any in-flight flush + pending mutation chain has settled, so a caller (e.g.
+	* `configure()` teardown) can safely create a replacement queue knowing the
+	* old one will never touch storage again. Idempotent.
+	*/
+	async dispose() {
+		this.disposed = true;
+		if (this.detachOnline) {
+			this.detachOnline();
+			this.detachOnline = null;
+		}
+		try {
+			await this.flushing;
+		} catch {}
+		await this.tail.catch(() => void 0);
+	}
+	/** Whether this queue has been disposed. */
+	get isDisposed() {
+		return this.disposed;
+	}
+	/** Append an op to the durable outbox. Returns the persisted op. */
+	async enqueue(op) {
+		if (this.disposed) throw new Error("amba offline queue was disposed (SDK reconfigured)");
+		const full = {
+			...op,
+			idempotencyKey: op.idempotencyKey ?? newIdempotencyKey(),
+			enqueuedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		return this.mutate((ops) => ({
+			next: [...ops, full],
+			result: full
+		}), { rejectIfDisposed: true });
+	}
+	/** Number of ops awaiting replay. */
+	async pendingCount() {
+		return (await this.load()).length;
+	}
+	/** Snapshot the pending ops (a copy — mutating it does not affect the queue). */
+	async pending() {
+		return [...await this.load()];
+	}
+	/** Drop every queued op without replaying. */
+	async clear() {
+		await this.mutate(() => ({
+			next: [],
+			result: void 0
+		}));
+	}
+	/**
+	* Replay the outbox in FIFO order. Each op is removed only after it
+	* succeeds; the first failure stops the flush and retains the remainder
+	* (so order is preserved and nothing is dropped mid-batch). Concurrent
+	* calls share one in-flight flush.
+	*/
+	async flush() {
+		if (this.disposed) return {
+			flushed: 0,
+			dropped: 0,
+			remaining: 0
+		};
+		if (this.flushing) return this.flushing;
+		this.flushing = this.runFlush().finally(() => {
+			this.flushing = null;
+		});
+		return this.flushing;
+	}
+	async runFlush() {
+		let flushed = 0;
+		let dropped = 0;
+		for (;;) {
+			if (this.disposed) break;
+			const head = (await this.load())[0];
+			if (!head) break;
+			let replayError = void 0;
+			let ok = false;
+			try {
+				await this.executor(head);
+				ok = true;
+			} catch (err) {
+				replayError = err;
+			}
+			if (!ok && !isDeterministicError(replayError)) {
+				await this.mutate((ops) => {
+					return {
+						next: ops.some((o) => o.idempotencyKey === head.idempotencyKey) ? ops : [head, ...ops],
+						result: void 0
+					};
+				});
+				break;
+			}
+			if (!await this.mutate((ops) => {
+				const idx = ops.findIndex((o) => o.idempotencyKey === head.idempotencyKey);
+				if (idx === -1) return {
+					next: ops,
+					result: false
+				};
+				return {
+					next: ops.slice(0, idx).concat(ops.slice(idx + 1)),
+					result: true
+				};
+			})) break;
+			if (ok) flushed += 1;
+			else {
+				dropped += 1;
+				try {
+					this.onDropped?.(head, replayError);
+				} catch {}
+			}
+		}
+		const remaining = (await this.load()).length;
+		return {
+			flushed,
+			dropped,
+			remaining
+		};
+	}
+	/**
+	* Install an auto-flush listener on the runtime's `online` event so the
+	* queue drains the moment connectivity returns. Idempotent — a second
+	* call is a no-op. Returns a detach function.
+	*/
+	startAutoFlush() {
+		if (this.detachOnline) return this.detachOnline;
+		const target = typeof globalThis !== "undefined" && typeof globalThis.addEventListener === "function" ? globalThis : null;
+		if (!target) {
+			this.detachOnline = () => {};
+			return this.detachOnline;
+		}
+		const handler = () => {
+			this.flush();
+		};
+		target.addEventListener("online", handler);
+		this.detachOnline = () => {
+			target.removeEventListener("online", handler);
+			this.detachOnline = null;
+		};
+		return this.detachOnline;
+	}
+};
+/**
+* Apply a local change immediately, fire the real mutation, and roll the
+* local change back if the mutation fails. Framework-agnostic: `apply` and
+* `rollback` operate on whatever local view you hand them (a React state
+* setter, a store, an in-memory cache).
+*
+* Resolves with the mutation's result on success. On failure it invokes
+* `rollback` (with the value `apply` returned, so you can restore a captured
+* snapshot) and rethrows the original error.
+*
+* @example
+* await withOptimistic({
+*   apply: () => { const prev = todos; setTodos([...todos, draft]); return prev; },
+*   mutate: () => Amba.collections.insert("todos", draft),
+*   rollback: (prev) => setTodos(prev),
+* });
+*/
+async function withOptimistic(spec) {
+	const applied = spec.apply();
+	try {
+		return await spec.mutate();
+	} catch (err) {
+		try {
+			spec.rollback(applied);
+		} catch {}
+		throw err;
+	}
+}
+
+//#endregion
+//#region src/push-rotation.ts
+/**
+* Wire a platform token-refresh subscription to the SDK's idempotent
+* re-register path. On every rotation the fresh token is forwarded to
+* `reRegister(token, platform)` — the same upsert the first `push.register`
+* call used, so re-registering the same device is a no-op server-side.
+*
+* `platform` defaults to the conventional pick (`"apns"` on iOS, `"fcm"`
+* elsewhere) supplied by the caller. Returns an unsubscribe function.
+*
+* @example
+* // Expo:
+* import * as Notifications from "expo-notifications";
+* const detach = enableNativePushAutoRotation(
+*   (h) => Notifications.addPushTokenListener((t) => h(t.data)).remove,
+*   reRegister,
+*   "apns",
+* );
+*/
+function enableNativePushAutoRotation(subscribe, reRegister, platform) {
+	const unsubscribe = subscribe((token) => {
+		if (!token) return;
+		(async () => {
+			try {
+				await reRegister(token, platform);
+			} catch (err) {
+				if (typeof console !== "undefined") console.error("[amba] push auto-rotation re-register failed", err);
+			}
+		})();
+	});
+	return typeof unsubscribe === "function" ? unsubscribe : () => {};
+}
+
+//#endregion
+//#region src/local-notifications.ts
+/**
+* Marker key stamped into every Amba-scheduled notification's `data`. Lets
+* `listScheduledLocal` distinguish OUR notifications from any other
+* `expo-notifications` schedules the host app created — so foreign
+* schedules never leak into the Amba list. Mirrors the web SDK's
+* `__ambaLocalId` marker.
+*/
+const AMBA_LOCAL_ID_KEY = "__ambaLocalId";
+/**
+* Generate a stable local-notification id when the caller omits one.
+*/
+function genLocalId() {
+	const c = globalThis.crypto;
+	if (c?.randomUUID) return c.randomUUID();
+	return `amba_local_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+/**
+* Resolve the id a schedule will be filed under. A caller may omit `id`
+* (we mint one) but must not pass a BLANK/whitespace id: `cancelLocal`
+* rejects blank ids, so returning one in the handle would make the
+* notification uncancellable. Reject blank at schedule time so every
+* returned handle id round-trips through `cancelLocal`. Mirrors the web SDK.
+*/
+function normalizeScheduleId(rawId) {
+	if (rawId === void 0) return genLocalId();
+	if (typeof rawId !== "string" || rawId.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: id, when provided, must be a non-empty string");
+	return rawId;
+}
+async function loadExpoNotifications() {
+	try {
+		const mod = await import("expo-notifications");
+		return mod.default ?? mod;
+	} catch (err) {
+		throw new AmbaApiError("LOCAL_NOTIFICATIONS_UNAVAILABLE", "Amba.notifications requires the `expo-notifications` peer dependency. Install it with `npx expo install expo-notifications` (works in both Expo and bare React Native apps).", err);
+	}
+}
+/**
+* Translate Amba's platform-neutral trigger into the shape
+* `expo-notifications` expects. We build object triggers keyed by the
+* library's `SchedulableTriggerInputTypes` when present (SDK 0.27+),
+* falling back to the legacy `{ date }` / `{ seconds }` shorthand the
+* older API accepts — both forms remain supported by current releases.
+*/
+function buildExpoTrigger(input, Notifications) {
+	const types = Notifications.SchedulableTriggerInputTypes;
+	const trigger = input.trigger;
+	if (!trigger || typeof trigger !== "object") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: trigger must be { at: Date } or { inSeconds: number, repeats?: boolean }");
+	if ("at" in trigger) {
+		const at = trigger.at instanceof Date ? trigger.at : new Date(trigger.at);
+		if (Number.isNaN(at.getTime())) throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: trigger.at must be a valid Date");
+		return types ? {
+			type: types.DATE,
+			date: at
+		} : { date: at };
+	}
+	if ("inSeconds" in trigger) {
+		const seconds = trigger.inSeconds;
+		if (!Number.isFinite(seconds) || seconds < 0) throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: trigger.inSeconds must be a non-negative number");
+		const repeats = "repeats" in trigger ? Boolean(trigger.repeats) : false;
+		return types ? {
+			type: types.TIME_INTERVAL,
+			seconds,
+			repeats
+		} : {
+			seconds,
+			repeats
+		};
+	}
+	throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: trigger must be { at: Date } or { inSeconds: number, repeats?: boolean }");
+}
+function validateContent(input) {
+	if (!input || typeof input.title !== "string" || input.title.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: title is required");
+	if (typeof input.body !== "string") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: body must be a string");
+}
+/**
+* The `notifications` namespace. Shared by `@layers/amba-react-native`
+* and (via re-export) `@layers/amba-expo`.
+*/
+const notifications = {
+	async scheduleLocal(input) {
+		validateContent(input);
+		const id = normalizeScheduleId(input.id);
+		const Notifications = await loadExpoNotifications();
+		const trigger = buildExpoTrigger(input, Notifications);
+		const existing = await Notifications.getPermissionsAsync();
+		let granted = existing.granted ?? existing.status === "granted";
+		if (!granted) {
+			const requested = await Notifications.requestPermissionsAsync();
+			granted = requested.granted ?? requested.status === "granted";
+		}
+		if (!granted) throw new AmbaApiError("LOCAL_NOTIFICATIONS_PERMISSION_DENIED", "user denied notification permission — local notifications cannot be scheduled");
+		return { id: await Notifications.scheduleNotificationAsync({
+			identifier: id,
+			content: {
+				title: input.title,
+				body: input.body,
+				data: {
+					...input.data,
+					[AMBA_LOCAL_ID_KEY]: id
+				}
+			},
+			trigger
+		}) || id };
+	},
+	async cancelLocal(id) {
+		if (typeof id !== "string" || id.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.cancelLocal: id is required");
+		await (await loadExpoNotifications()).cancelScheduledNotificationAsync(id);
+	},
+	async listScheduledLocal() {
+		const scheduled = await (await loadExpoNotifications()).getAllScheduledNotificationsAsync();
+		const out = [];
+		for (const n of scheduled) {
+			const data = n.content?.data ?? {};
+			const markerId = data[AMBA_LOCAL_ID_KEY];
+			if (!markerId) continue;
+			out.push({
+				id: markerId,
+				title: n.content?.title ?? "",
+				body: n.content?.body ?? "",
+				data
+			});
+		}
+		return out;
+	}
+};
+
+//#endregion
+//#region src/realtime.ts
+const INITIAL_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 15e3;
+const DEFAULT_API_URL = "https://api.amba.dev";
+const DEFAULT_REALTIME_URL = "https://realtime.amba.host";
+/**
+* Resolve the base URL for live-update connections. Long-lived streams are
+* served from a dedicated realtime host (no request-duration ceiling), so
+* when the SDK points at the default production API the stream connects
+* there instead. Any custom `apiUrl` (dev, staging, self-hosted, proxy)
+* keeps live updates on that same origin — override semantics unchanged.
+*/
+function resolveRealtimeBaseUrl(baseUrl) {
+	return baseUrl.replace(/\/+$/, "") === DEFAULT_API_URL ? DEFAULT_REALTIME_URL : baseUrl;
+}
+/**
+* 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* first.");
+		const qs = Object.keys(this.filters).length > 0 ? `?where=${encodeURIComponent(JSON.stringify(this.filters))}` : "";
+		return openStream({
+			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/collections/${encodeURIComponent(this.name)}${qs}`,
+			authHeaders: this.ctx.authHeaders,
+			onChange: cb,
+			options,
+			parse: parseRowChangeFrame
+		});
+	}
+};
+/**
+* Builder returned by `Amba.messaging.conversation(id)`. Call `.subscribe(cb)`
+* to receive new messages live instead of polling.
+*
+* 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* first.");
+		return openStream({
+			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/conversations/${encodeURIComponent(this.conversationId)}`,
+			authHeaders: this.ctx.authHeaders,
+			onChange: cb,
+			options,
+			parse: parseRowChangeFrame
+		});
+	}
+};
+/**
+* Builder returned by `Amba.gamification`. Call `.subscribe(cb)` to receive the
+* signed-in user's xp / level / achievement / streak changes live instead of
+* polling.
+*
+* Delivery is scoped to the signed-in user — you only ever receive your own
+* gamification changes, never another user's. Reconnects with the same
+* exponential backoff as collection subscriptions.
+*/
+var GamificationSubscription = class {
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	subscribe(cb, options = {}) {
+		if (!this.ctx.authHeaders()) throw new Error("Amba.gamification.subscribe() requires an authenticated session — call Amba.auth.signIn* first.");
+		return openStream({
+			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/gamification`,
+			authHeaders: this.ctx.authHeaders,
+			onChange: cb,
+			options,
+			parse: parseGamificationFrame
+		});
+	}
+};
+/**
+* Open a long-lived event stream and dispatch parsed events to `onChange`.
+* Reconnects with exponential backoff until the returned unsubscribe handle
+* is invoked. Chooses the XHR incremental-text transport (RN-native) when
+* available, else the streamed-`fetch`-body transport (RN-for-web / Node).
+*/
+function openStream(args) {
+	let stopped = false;
+	let backoff = INITIAL_BACKOFF_MS;
+	let closeActive = null;
+	let settleActive = null;
+	const run = async () => {
+		while (!stopped) {
+			const headers = args.authHeaders();
+			if (!headers) {
+				args.options.onError?.(/* @__PURE__ */ new Error("no active session"));
+				break;
+			}
+			try {
+				await new Promise((resolve, reject) => {
+					settleActive = resolve;
+					const onFirstFrame = () => {
+						backoff = INITIAL_BACKOFF_MS;
+						args.options.onOpen?.();
+					};
+					closeActive = connectOnce({
+						url: args.url,
+						headers,
+						onFrame: (frame) => {
+							const ev = args.parse(frame);
+							if (ev !== null) args.onChange(ev);
+						},
+						onFirstFrame,
+						onDone: resolve,
+						onError: reject
+					});
+				});
+			} catch (err) {
+				if (stopped) break;
+				args.options.onError?.(err);
+			} finally {
+				closeActive?.();
+				closeActive = null;
+				settleActive = null;
+			}
+			if (stopped) break;
+			await delay(backoff);
+			backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+		}
+	};
+	run();
+	return () => {
+		stopped = true;
+		closeActive?.();
+		settleActive?.();
+	};
+}
+/**
+* Establish a single connection using the best available transport. Returns
+* an abort function. The XHR transport is preferred on React Native; the
+* fetch-stream transport covers RN-for-web and any runtime exposing a
+* readable `response.body`.
+*/
+function connectOnce(args) {
+	if (typeof XMLHttpRequest !== "undefined") return connectXhr(args, XMLHttpRequest);
+	return connectFetchStream(args);
+}
+/**
+* Incremental-`responseText` transport via XMLHttpRequest — the RN-native
+* path. `onreadystatechange` fires at readyState 3 (LOADING) as bytes
+* stream in; we track how much of `responseText` we've already parsed and
+* extract any newly-completed `\n\n`-delimited frames.
+*/
+function connectXhr(args, XHR) {
+	const xhr = new XHR();
+	let consumed = 0;
+	let buffer = "";
+	let sawFrame = false;
+	let aborted = false;
+	const drain = () => {
+		const text = xhr.responseText;
+		if (text.length <= consumed) return;
+		buffer += text.slice(consumed);
+		consumed = text.length;
+		let idx;
+		while ((idx = buffer.indexOf("\n\n")) !== -1) {
+			const frame = buffer.slice(0, idx);
+			buffer = buffer.slice(idx + 2);
+			if (!sawFrame) {
+				sawFrame = true;
+				args.onFirstFrame();
+			}
+			args.onFrame(frame);
+		}
+	};
+	xhr.open("GET", args.url, true);
+	for (const [k, v] of Object.entries(args.headers)) xhr.setRequestHeader(k, v);
+	xhr.setRequestHeader("Accept", "text/event-stream");
+	xhr.onreadystatechange = () => {
+		if (aborted) return;
+		if (xhr.readyState === 3) {
+			if (xhr.status >= 400) return;
+			drain();
+		}
+	};
+	xhr.onload = () => {
+		if (aborted) return;
+		if (xhr.status >= 200 && xhr.status < 300) {
+			drain();
+			args.onDone();
+		} else args.onError(/* @__PURE__ */ new Error(`realtime connect failed: HTTP ${xhr.status}`));
+	};
+	xhr.onerror = () => {
+		if (aborted) return;
+		args.onError(/* @__PURE__ */ new Error("realtime transport error"));
+	};
+	xhr.ontimeout = () => {
+		if (aborted) return;
+		args.onError(/* @__PURE__ */ new Error("realtime connection timed out"));
+	};
+	try {
+		xhr.send();
+	} catch (err) {
+		args.onError(err);
+	}
+	return () => {
+		aborted = true;
+		try {
+			xhr.abort();
+		} catch {}
+	};
+}
+/**
+* Streamed-`fetch`-body transport — used when XHR isn't present (RN-for-web,
+* Node). Identical wire handling to web/node's `consume`.
+*/
+function connectFetchStream(args) {
+	const controller = new AbortController();
+	let aborted = false;
+	(async () => {
+		try {
+			const resp = await fetch(args.url, {
+				method: "GET",
+				headers: {
+					...args.headers,
+					Accept: "text/event-stream"
+				},
+				signal: controller.signal
+			});
+			if (!resp.ok || !resp.body) throw new Error(`realtime connect failed: HTTP ${resp.status}`);
+			const reader = resp.body.getReader();
+			const decoder = new TextDecoder();
+			let buffer = "";
+			let sawFrame = false;
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				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;
+						args.onFirstFrame();
+					}
+					args.onFrame(frame);
+				}
+			}
+			if (!aborted) args.onDone();
+		} catch (err) {
+			if (!aborted) args.onError(err);
+		}
+	})();
+	return () => {
+		aborted = true;
+		controller.abort();
+	};
+}
+/** Pull the `event:` name + joined `data:` lines out of one raw frame. */
+function readFrame(frame) {
+	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());
+	}
+	return {
+		event,
+		data: dataLines.join("\n")
+	};
+}
+function parseRowChangeFrame(frame) {
+	const { event, data } = readFrame(frame);
+	if (event !== "change") return null;
+	try {
+		const payload = JSON.parse(data);
+		return {
+			op: payload.op,
+			row: payload.row,
+			truncated: payload.truncated
+		};
+	} catch {
+		return null;
+	}
+}
+function parseGamificationFrame(frame) {
+	const { event, data } = readFrame(frame);
+	if (event !== "change") return null;
+	try {
+		const payload = JSON.parse(data);
+		return {
+			kind: payload.kind,
+			data: payload.data,
+			truncated: payload.truncated
+		};
+	} catch {
+		return null;
+	}
+}
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.0.3";
+const SDK_VERSION = "4.0.5";
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
@@ -361,10 +1157,33 @@ const SDK_VERSION = "4.0.3";
 */
 const DEFAULT_FUNCTIONS_HOST = "fn.amba.host";
 let state = null;
+/**
+* Monotonic token identifying the current offline activation. Bumped on every
+* `offline.enable()` AND every `configure()`, captured by each `enable()` into
+* its disable callback. A disabler only acts while the token still matches — so
+* a stale disabler (held across a re-`enable()` or a reconfigure) no-ops
+* instead of disabling the now-active outbox.
+*/
+let _offlineEnableToken = 0;
 function getState() {
 	if (!state) throw new AmbaApiError("NOT_INITIALIZED", "@layers/amba-react-native: SDK not configured. Call Amba.configure({ projectId, clientKey }) at app start.");
 	return state;
 }
+/**
+* Build the auth headers for a realtime subscribe connection, or `null`
+* when the SDK isn't configured or there's no live session. Read lazily at
+* connect time so reconnects pick up a rotated session token (the identity
+* store holds the canonical, auto-refreshed copy).
+*/
+function realtimeAuthHeaders() {
+	if (!state) return null;
+	const token = state.identity.getSessionToken();
+	if (!token) return null;
+	return {
+		"X-Api-Key": state.clientKey,
+		Authorization: `Bearer ${token}`
+	};
+}
 const authSubscribers = /* @__PURE__ */ new Set();
 function snapshotSession(user) {
 	if (!user) return null;
@@ -490,6 +1309,8 @@ const P = {
 	pushSubscribe: "/v1/client/push/subscribe",
 	pushUnsubscribe: "/v1/client/push/unsubscribe",
 	entitlements: "/v1/client/entitlements",
+	entitlementsRestore: "/v1/client/entitlements/restore",
+	offerings: "/v1/client/offerings",
 	aiAnthropic: "/v1/client/ai/anthropic/messages",
 	config: "/v1/client/config",
 	flags: "/v1/client/flags",
@@ -535,6 +1356,74 @@ async function resolveFunctionUrl(s, name) {
 	return `https://${s.resolvedFunctionsProjectId}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
 }
 /**
+* Bridge the AsyncStorage-backed persistence to the {@link KvStore} the
+* outbox persists through. Namespaced under the configured storage prefix so
+* multiple projects in one app don't collide.
+*/
+function offlineStore(s) {
+	return {
+		get: (key) => s.persistence.read(key),
+		set: (key, value) => s.persistence.write(key, value),
+		delete: (key) => s.persistence.delete(key)
+	};
+}
+/**
+* Replay one queued mutation against the live API, forwarding the op's
+* idempotency key on collection inserts so a write that landed before the
+* connection dropped is never double-applied (API migration 056).
+*/
+async function replayOutboxOp(s, op) {
+	switch (op.kind) {
+		case "collection.insert":
+			await s.http.post(`${P.collections}/${encodePathSegment(op.collection)}`, {
+				...op.payload ?? {},
+				idempotency_key: op.idempotencyKey
+			});
+			return;
+		case "collection.update":
+			await s.http.patch(`${P.collections}/${encodePathSegment(op.collection)}/${encodePathSegment(op.id)}`, { set: op.payload ?? {} });
+			return;
+		case "collection.delete":
+			await s.http.delete(`${P.collections}/${encodePathSegment(op.collection)}/${encodePathSegment(op.id)}`);
+			return;
+		case "track":
+			try {
+				await s.http.post(P.events, {
+					event: op.event,
+					properties: op.properties ?? void 0,
+					anonymous_id: s.identity.getAnonymousId(),
+					timestamp: op.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+					...op.telemetry ? { telemetry: true } : {}
+				});
+			} catch (err) {
+				const code = err?.code;
+				if (code === "UNAUTHORIZED" || code === "FORBIDDEN") throw new AmbaApiError("NETWORK_ERROR", "track replay deferred: no valid session");
+				throw err;
+			}
+			return;
+	}
+}
+function getOfflineQueue(s) {
+	if (!s.offlineQueue) s.offlineQueue = new OfflineQueue({
+		store: offlineStore(s),
+		storageKey: `offline_outbox:${s.projectId}`,
+		executor: (op) => replayOutboxOp(s, op),
+		onDropped: (op, err) => {
+			if (typeof console !== "undefined") console.warn(`[amba] dropped un-replayable offline ${op.kind} (${op.collection ?? op.event ?? "?"}):`, err);
+		}
+	});
+	return s.offlineQueue;
+}
+async function insertDirect(s, name, row) {
+	return (await s.http.post(`${P.collections}/${encodePathSegment(name)}`, row)).data;
+}
+async function updateDirect(s, name, id, set) {
+	return (await s.http.patch(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`, { set })).data;
+}
+async function deleteDirect(s, name, id) {
+	return await s.http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
+}
+/**
 * Top-level SDK namespace for React Native.
 */
 const Amba = {
@@ -546,23 +1435,32 @@ const Amba = {
 		const identity = await IdentityStore.create(persistence);
 		const baseUrl = (config.apiUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 		const sdkVersionHeader = `amba-sdk/${SDK_VERSION} ${`amba-react-native/${SDK_VERSION}`}`;
+		const http = new AmbaHttpClient({
+			apiKey: config.clientKey,
+			baseUrl,
+			sdkPlatform: "react-native",
+			sdkVersionHeader,
+			identity,
+			ensureSession: config.autoAnonymousSession === false ? void 0 : async (path) => {
+				if (pathSkipsLazySession(path)) return;
+				await ensureAnonymousSession(getState());
+			}
+		});
+		const prior = state;
+		_offlineEnableToken += 1;
+		if (prior?.offlineQueue) await prior.offlineQueue.dispose();
 		state = {
-			http: new AmbaHttpClient({
-				apiKey: config.clientKey,
-				baseUrl,
-				sdkPlatform: "react-native",
-				sdkVersionHeader,
-				identity,
-				ensureSession: config.autoAnonymousSession === false ? void 0 : async (path) => {
-					if (pathSkipsLazySession(path)) return;
-					await ensureAnonymousSession(getState());
-				}
-			}),
+			http,
 			identity,
 			debug: config.debug ?? false,
 			projectId: config.projectId,
+			clientKey: config.clientKey,
+			baseUrl,
 			functionsBaseUrl: config.functionsBaseUrl ?? null,
-			resolvedFunctionsProjectId: null
+			resolvedFunctionsProjectId: null,
+			persistence,
+			offlineEnabled: false,
+			offlineQueue: null
 		};
 	},
 	_reset: () => {
@@ -584,16 +1482,41 @@ const Amba = {
 	setDebug: (enabled) => {
 		getState().debug = enabled;
 	},
+	collection: (name) => new CollectionSubscription({
+		baseUrl: getState().baseUrl,
+		authHeaders: realtimeAuthHeaders
+	}, name),
+	get gamification() {
+		return new GamificationSubscription({
+			baseUrl: getState().baseUrl,
+			authHeaders: realtimeAuthHeaders
+		});
+	},
 	events: { track: async (event, properties, options) => {
 		const s = getState();
+		const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
 		const body = {
 			event,
 			properties: properties ?? void 0,
 			anonymous_id: s.identity.getAnonymousId(),
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			timestamp: occurredAt
 		};
 		if (options?.telemetry) body["telemetry"] = true;
-		await s.http.post(P.events, body);
+		try {
+			await s.http.post(P.events, body);
+		} catch (err) {
+			if (s.offlineEnabled && isOfflineError(err)) {
+				await getOfflineQueue(s).enqueue({
+					kind: "track",
+					event,
+					properties,
+					telemetry: options?.telemetry,
+					occurredAt
+				});
+				return;
+			}
+			throw err;
+		}
 	} },
 	auth: {
 		signInAnonymously: async () => {
@@ -794,6 +1717,23 @@ const Amba = {
 			return (await getState().http.get(P.sync, query)).data;
 		}
 	},
+	offline: {
+		enable: () => {
+			const s = getState();
+			s.offlineEnabled = true;
+			_offlineEnableToken += 1;
+			const token = _offlineEnableToken;
+			return () => {
+				if (_offlineEnableToken !== token || state !== s) return;
+				s.offlineEnabled = false;
+			};
+		},
+		isEnabled: () => getState().offlineEnabled,
+		pendingCount: async () => getOfflineQueue(getState()).pendingCount(),
+		pending: async () => getOfflineQueue(getState()).pending(),
+		flush: async () => getOfflineQueue(getState()).flush(),
+		clear: async () => getOfflineQueue(getState()).clear()
+	},
 	collections: {
 		find: async (name, options = {}) => {
 			return getState().http.post(`${P.collections}/${encodePathSegment(name)}/find`, options);
@@ -816,14 +1756,86 @@ const Amba = {
 			return (await s.http.get(`${P.collections}/${encodePathSegment(name)}/count`, query)).data.count;
 		},
 		insert: async (name, row) => {
-			return (await getState().http.post(`${P.collections}/${encodePathSegment(name)}`, row)).data;
+			const s = getState();
+			if (s.offlineEnabled) {
+				const idempotencyKey = (typeof row["idempotency_key"] === "string" ? row["idempotency_key"] : void 0) ?? newIdempotencyKey();
+				try {
+					return (await s.http.post(`${P.collections}/${encodePathSegment(name)}`, {
+						...row,
+						idempotency_key: idempotencyKey
+					})).data;
+				} catch (err) {
+					if (isOfflineError(err)) {
+						await getOfflineQueue(s).enqueue({
+							kind: "collection.insert",
+							collection: name,
+							payload: row,
+							idempotencyKey
+						});
+						return {
+							...row,
+							_amba_pending: true
+						};
+					}
+					throw err;
+				}
+			}
+			return (await s.http.post(`${P.collections}/${encodePathSegment(name)}`, row)).data;
 		},
 		update: async (name, id, set) => {
-			return (await getState().http.patch(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`, { set })).data;
+			const s = getState();
+			if (s.offlineEnabled) try {
+				return (await s.http.patch(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`, { set })).data;
+			} catch (err) {
+				if (isOfflineError(err)) {
+					await getOfflineQueue(s).enqueue({
+						kind: "collection.update",
+						collection: name,
+						id,
+						payload: set
+					});
+					return {
+						id,
+						...set,
+						_amba_pending: true
+					};
+				}
+				throw err;
+			}
+			return (await s.http.patch(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`, { set })).data;
 		},
 		delete: async (name, id) => {
-			return await getState().http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
-		},
+			const s = getState();
+			if (s.offlineEnabled) try {
+				return await s.http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
+			} catch (err) {
+				if (isOfflineError(err)) {
+					await getOfflineQueue(s).enqueue({
+						kind: "collection.delete",
+						collection: name,
+						id
+					});
+					return { data: { deleted: true } };
+				}
+				throw err;
+			}
+			return await s.http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
+		},
+		optimisticInsert: async (name, row, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => insertDirect(getState(), name, row),
+			rollback: view.rollback
+		}),
+		optimisticUpdate: async (name, id, set, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => updateDirect(getState(), name, id, set),
+			rollback: view.rollback
+		}),
+		optimisticDelete: async (name, id, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => deleteDirect(getState(), name, id),
+			rollback: view.rollback
+		}),
 		where: {
 			eq: (column, value) => ({
 				column,
@@ -951,16 +1963,24 @@ const Amba = {
 		},
 		unsubscribe: async (topic) => {
 			await getState().http.post(P.pushUnsubscribe, { topic });
-		}
+		},
+		enableAutoRotation: (subscribe, platform = "fcm") => enableNativePushAutoRotation(subscribe, (token, p) => Amba.push.register(token, p), platform)
 	},
+	notifications,
 	entitlements: {
 		list: async () => {
 			return (await getState().http.get(P.entitlements)).data;
 		},
-		has: async (name) => {
-			return (await getState().http.get(P.entitlements, { active_only: "true" })).data.some((e) => e.name === name && e.is_active);
+		has: async (entitlementId) => {
+			return (await getState().http.get(P.entitlements, { active_only: "true" })).data.some((e) => e.entitlement_id === entitlementId && e.is_active);
+		},
+		restore: async () => {
+			return (await getState().http.post(P.entitlementsRestore, {})).data;
 		}
 	},
+	offerings: async (offeringId) => {
+		return (await getState().http.get(P.offerings, offeringId ? { offering_id: offeringId } : void 0)).data;
+	},
 	ai: { anthropic: { messages: { create: async (request) => {
 		const env = await getState().http.post(P.aiAnthropic, request);
 		if (!env || typeof env !== "object" || env.data === void 0) throw new AmbaApiError("MALFORMED_RESPONSE", "AI response was not wrapped in the expected { data } envelope", env);
@@ -1206,6 +2226,10 @@ const Amba = {
 		}
 	},
 	messaging: {
+		conversation: (conversationId) => new ConversationSubscription({
+			baseUrl: getState().baseUrl,
+			authHeaders: realtimeAuthHeaders
+		}, conversationId),
 		createConversation: async (request) => {
 			return (await getState().http.post(`${P.messaging}/conversations`, request)).data;
 		},
@@ -1349,5 +2373,5 @@ const Amba = {
 };
 
 //#endregion
-export { Amba, AmbaApiError, SDK_VERSION };
+export { Amba, AmbaApiError, CollectionSubscription, ConversationSubscription, GamificationSubscription, SDK_VERSION, withOptimistic };
 //# sourceMappingURL=index.js.map