@layers/amba-web 4.0.4 → 4.0.5

package/dist-rn/index.js

@@ -39,11 +39,89 @@ function encodeJson(value) {
 	return JSON.stringify(value);
 }
 
+//#endregion
+//#region src/ai-images.ts
+/**
+* Normalize an image input into a content block, applying the SAME validity
+* rule the backend's gateway + the MCP tool use: trim `url`/`data`, treat a
+* blank/whitespace-only value as absent, and return `null` when NEITHER a real
+* url nor real data survives. A `null` block is dropped by the caller so we
+* never emit an empty image — keeping the SDK, MCP, and gateway in agreement.
+*/
+function normalizeImageBlock(img) {
+	const url = typeof img.url === "string" && img.url.trim().length > 0 ? img.url.trim() : void 0;
+	const data = typeof img.data === "string" && img.data.trim().length > 0 ? img.data.trim() : void 0;
+	if (!url && !data) return null;
+	const block = { type: "image" };
+	if (url !== void 0) block.url = url;
+	if (data !== void 0) block.data = data;
+	if (img.mime !== void 0) block.mime = img.mime;
+	return block;
+}
+/**
+* Expand a request's convenience `images` into content blocks on `messages`.
+* Returns the SAME object reference when there's nothing to expand, or a new
+* request (with `images` removed) when images were attached.
+*/
+function expandAiImages(request) {
+	const images = request.images;
+	if (!images || images.length === 0) return request;
+	const imageBlocks = images.map(normalizeImageBlock).filter((b) => b !== null);
+	const { images: _images,...rest } = request;
+	if (imageBlocks.length === 0) return rest;
+	const messages = (rest.messages ?? []).map((m) => ({ ...m }));
+	let lastUserIdx = -1;
+	for (let i = messages.length - 1; i >= 0; i--) if (messages[i].role === "user") {
+		lastUserIdx = i;
+		break;
+	}
+	if (lastUserIdx === -1) {
+		const variableBlocks = rest.variables && Object.keys(rest.variables).length > 0 ? [{
+			type: "text",
+			text: JSON.stringify(rest.variables)
+		}] : [];
+		messages.push({
+			role: "user",
+			content: [...variableBlocks, ...imageBlocks]
+		});
+	} else {
+		const existing = messages[lastUserIdx].content;
+		let leadingBlocks;
+		if (typeof existing === "string") leadingBlocks = [{
+			type: "text",
+			text: existing
+		}];
+		else if (Array.isArray(existing)) leadingBlocks = existing;
+		else if (existing === null || existing === void 0) leadingBlocks = [];
+		else leadingBlocks = [{
+			type: "text",
+			text: JSON.stringify(existing)
+		}];
+		messages[lastUserIdx] = {
+			...messages[lastUserIdx],
+			content: [...leadingBlocks, ...imageBlocks]
+		};
+	}
+	return {
+		...rest,
+		messages
+	};
+}
+
 //#endregion
 //#region src/error.ts
 var AmbaApiError = class extends Error {
 	code;
 	details;
+	/**
+	* Server-side request / trace id (the `X-Amba-Request-Id` response
+	* header, falling back to the `request_id` field in the standard error
+	* envelope). Present on errors thrown by `Amba.functions.invoke()` so a
+	* failed run can be correlated with server logs
+	* (`functions logs --request-id <traceId>`). `undefined` when the failure
+	* happened before a response was received (e.g. a transport error).
+	*/
+	traceId;
 	constructor(code, message, details) {
 		super(message);
 		this.name = "AmbaApiError";
@@ -254,6 +332,978 @@ var ConversationSubscription = class {
 		});
 	}
 };
+/**
+* Builder returned by `Amba.gamification`. Call `.subscribe(cb)` to receive the
+* signed-in user's xp / level / achievement / streak changes live instead of
+* polling.
+*
+*   const unsub = Amba.gamification.subscribe((change) => {
+*     // change.kind: "xp" | "level" | "achievement" | "streak"
+*     // change.data: the new state
+*   });
+*   unsub(); // stop listening
+*
+* 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*/verify* first.");
+		return openGamificationStream({
+			url: `${this.ctx.baseUrl}/v1/client/realtime/gamification`,
+			authHeaders: this.ctx.authHeaders,
+			onChange: cb,
+			options
+		});
+	}
+};
+/**
+* Open a streamed GET to the gamification realtime endpoint. Identical
+* transport + backoff/reconnect to {@link openStream}; only the frame payload
+* shape differs (gamification carries `kind`, not `op`/`row`), so it gets its
+* own thin consumer rather than overloading the row-change parser.
+*/
+function openGamificationStream(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 consumeGamification(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 consumeGamification(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();
+			}
+			dispatchGamificationFrame(frame, args.onChange);
+		}
+	}
+}
+function dispatchGamificationFrame(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({
+			kind: payload.kind,
+			data: payload.data,
+			truncated: payload.truncated
+		});
+	} catch {}
+}
+
+//#endregion
+//#region src/ai-stream.ts
+function newUsageAccumulator() {
+	return {
+		input_tokens: 0,
+		output_tokens: 0,
+		cache_creation_input_tokens: 0,
+		cache_read_input_tokens: 0
+	};
+}
+function toAiUsage(acc) {
+	return {
+		input_tokens: acc.input_tokens,
+		output_tokens: acc.output_tokens,
+		cache_creation_input_tokens: acc.cache_creation_input_tokens,
+		cache_read_input_tokens: acc.cache_read_input_tokens
+	};
+}
+/** Read a numeric field defensively (vendors occasionally send null). */
+function num(v) {
+	return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+/**
+* Merge a vendor `usage`-shaped object into the accumulator. Handles both
+* Anthropic (`input_tokens` / `output_tokens` / `cache_*`) and OpenAI
+* (`prompt_tokens` / `completion_tokens`) field names, taking the max so a
+* later frame that re-reports a counter doesn't shrink it.
+*/
+function mergeUsage(acc, usage) {
+	const input = usage["input_tokens"] ?? usage["prompt_tokens"];
+	const output = usage["output_tokens"] ?? usage["completion_tokens"];
+	if (input !== void 0) acc.input_tokens = Math.max(acc.input_tokens, num(input));
+	if (output !== void 0) acc.output_tokens = Math.max(acc.output_tokens, num(output));
+	if (usage["cache_creation_input_tokens"] !== void 0) acc.cache_creation_input_tokens = Math.max(acc.cache_creation_input_tokens, num(usage["cache_creation_input_tokens"]));
+	if (usage["cache_read_input_tokens"] !== void 0) acc.cache_read_input_tokens = Math.max(acc.cache_read_input_tokens, num(usage["cache_read_input_tokens"]));
+}
+/**
+* Parse one SSE frame (everything between blank lines) and return the text
+* delta it carries, if any. Side-effect: folds any usage / model / stop
+* metadata into `acc`. Returns `null` for keepalive comments, the `[DONE]`
+* sentinel, and frames with no text (e.g. Anthropic's `message_start`).
+*
+* Tolerant by design — a malformed `data:` payload is skipped rather than
+* tearing down the stream.
+*/
+function parseAiSseFrame(frame, acc) {
+	const dataLines = [];
+	for (const line of frame.split(/\r\n|\r|\n/)) {
+		if (line.startsWith(":")) continue;
+		if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+	}
+	if (dataLines.length === 0) return null;
+	const data = dataLines.join("\n").trim();
+	if (data === "" || data === "[DONE]") return null;
+	let payload;
+	try {
+		payload = JSON.parse(data);
+	} catch {
+		return null;
+	}
+	const type = typeof payload["type"] === "string" ? payload["type"] : "";
+	if (type === "content_block_delta") {
+		const text = payload["delta"]?.["text"];
+		return typeof text === "string" ? text : null;
+	}
+	if (type === "message_start") {
+		const message = payload["message"];
+		const usage = message?.["usage"];
+		if (usage && typeof usage === "object") mergeUsage(acc, usage);
+		if (typeof message?.["model"] === "string") acc.model = message["model"];
+		return null;
+	}
+	if (type === "message_delta") {
+		const usage = payload["usage"];
+		if (usage && typeof usage === "object") mergeUsage(acc, usage);
+		const delta = payload["delta"];
+		if (typeof delta?.["stop_reason"] === "string") acc.stopReason = delta["stop_reason"];
+		return null;
+	}
+	if (type === "message_stop") return null;
+	if (Array.isArray(payload["choices"])) {
+		const choices = payload["choices"];
+		if (typeof payload["model"] === "string") acc.model = payload["model"];
+		const usage = payload["usage"];
+		if (usage && typeof usage === "object") mergeUsage(acc, usage);
+		const first = choices[0];
+		if (first) {
+			const finish = first["finish_reason"];
+			if (typeof finish === "string") acc.stopReason = finish;
+			const content = first["delta"]?.["content"];
+			if (typeof content === "string" && content.length > 0) return content;
+		}
+		return null;
+	}
+	return null;
+}
+/**
+* SSE event-frame delimiter: a blank line. The spec permits any line ending
+* (`\r\n`, `\n`, `\r`), so a blank line is two consecutive line breaks in any
+* combination — `\r\n\r\n`, `\n\n`, or `\r\r`. Some servers / proxies emit
+* CRLF, so splitting on `\n\n` alone would never frame those streams.
+*/
+const SSE_FRAME_DELIMITER = /\r\n\r\n|\n\n|\r\r/;
+/**
+* Pull the next complete SSE frame off the front of `buffer`, returning the
+* frame text (without the trailing blank-line delimiter) and the remaining
+* buffer, or `null` when no complete frame is present yet.
+*
+* Only *complete* delimiters match: a buffer ending mid-delimiter (e.g.
+* `…\r\n\r`, awaiting the final `\n`) leaves the partial bytes buffered for the
+* next read rather than framing prematurely.
+*/
+function splitNextSseFrame(buffer) {
+	const m = SSE_FRAME_DELIMITER.exec(buffer);
+	if (!m) return null;
+	return {
+		frame: buffer.slice(0, m.index),
+		rest: buffer.slice(m.index + m[0].length)
+	};
+}
+/**
+* Open the streaming route and yield vendor-neutral events. Throws an
+* `AmbaApiError` on a transport failure or a non-2xx response (the error body
+* is read and surfaced just like the buffered path).
+*
+* The generator yields zero or more `{type:'delta'}` events followed by
+* exactly one terminal `{type:'done'}` when the stream completes cleanly.
+*/
+async function* invokeAiStream(args) {
+	let resp;
+	try {
+		resp = await fetch(args.url, {
+			method: "POST",
+			headers: args.headers,
+			body: args.body
+		});
+	} catch (err) {
+		throw new AmbaApiError("NETWORK_ERROR", `AI stream network error: ${String(err)}`);
+	}
+	if (!resp.ok) {
+		const text = await resp.text().catch(() => "");
+		let parsed = void 0;
+		if (text.length > 0) try {
+			parsed = JSON.parse(text);
+		} catch {
+			parsed = text;
+		}
+		const envelope = parsed && typeof parsed === "object" ? parsed : void 0;
+		throw new AmbaApiError(typeof envelope?.error?.code === "string" ? envelope.error.code : `HTTP_${resp.status}`, typeof envelope?.error?.message === "string" ? envelope.error.message : typeof parsed === "string" && parsed.length > 0 ? parsed : `AI stream failed with status ${resp.status}`, parsed);
+	}
+	if (!resp.body) throw new AmbaApiError("NETWORK_ERROR", "AI stream response had no readable body (the environment does not expose a streaming fetch body).");
+	const reader = resp.body.getReader();
+	const decoder = new TextDecoder();
+	const acc = newUsageAccumulator();
+	let buffer = "";
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (value) buffer += decoder.decode(value, { stream: true });
+			if (done) buffer += decoder.decode();
+			let split;
+			while ((split = splitNextSseFrame(buffer)) !== null) {
+				buffer = split.rest;
+				const text = parseAiSseFrame(split.frame, acc);
+				if (text !== null && text.length > 0) {
+					args.onChunk?.(text);
+					yield {
+						type: "delta",
+						text
+					};
+				}
+			}
+			if (done) {
+				const tail = buffer.trim();
+				if (tail.length > 0) {
+					const text = parseAiSseFrame(tail, acc);
+					if (text !== null && text.length > 0) {
+						args.onChunk?.(text);
+						yield {
+							type: "delta",
+							text
+						};
+					}
+				}
+				break;
+			}
+		}
+	} finally {
+		try {
+			reader.releaseLock();
+		} catch {}
+	}
+	yield {
+		type: "done",
+		usage: toAiUsage(acc),
+		model: acc.model,
+		stopReason: acc.stopReason ?? null
+	};
+}
+
+//#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
+/**
+* Subscribe to browser push-subscription rotation. On a
+* `pushsubscriptionchange`, the new subscription endpoint is forwarded to
+* `reRegister` (which the SDK points at its idempotent token-upsert).
+*
+* Returns an unsubscribe function. No-ops (returning a no-op detacher) when
+* the runtime has no service-worker / push support — e.g. SSR or a browser
+* without Web Push — so callers can invoke it unconditionally.
+*/
+/**
+* Are we executing inside a ServiceWorkerGlobalScope? `pushsubscriptionchange`
+* ONLY fires there — on a normal page `self === window`, where the event never
+* fires, so attaching a listener silently does nothing. We detect the scope by
+* the `ServiceWorkerGlobalScope` constructor when present, falling back to the
+* SW-only `self.registration.pushManager` shape (a window has no `registration`
+* on its global).
+*/
+function inServiceWorkerScope(g) {
+	if (typeof g !== "object" || g === null) return false;
+	const swCtor = globalThis.ServiceWorkerGlobalScope;
+	if (typeof swCtor === "function" && g instanceof swCtor) return true;
+	const reg = g.registration;
+	return !!reg && typeof reg.pushManager === "object" && reg.pushManager !== null;
+}
+let pageScopeWarned = false;
+function enableWebPushAutoRotation(reRegister) {
+	const g = typeof self !== "undefined" ? self : void 0;
+	if (!g || !inServiceWorkerScope(g)) {
+		if (!pageScopeWarned && typeof console !== "undefined") {
+			pageScopeWarned = true;
+			console.warn("[amba] push.enableAutoRotation() must run inside your service worker — `pushsubscriptionchange` doesn't fire on a page/window. Call it from your amba service worker. No-op here.");
+		}
+		return () => {};
+	}
+	const sw = g;
+	if (typeof sw.addEventListener !== "function") return () => {};
+	const onChange = (event) => {
+		(async () => {
+			try {
+				const ev = event;
+				let endpoint = ev?.newSubscription?.endpoint;
+				if (!endpoint && sw.registration?.pushManager?.getSubscription) endpoint = (await sw.registration.pushManager.getSubscription())?.endpoint ?? void 0;
+				if (!endpoint) return;
+				const work = reRegister(endpoint, "web");
+				if (typeof ev?.waitUntil === "function") ev.waitUntil(work);
+				await work;
+			} catch (err) {
+				if (typeof console !== "undefined") console.error("[amba] push auto-rotation re-register failed", err);
+			}
+		})();
+	};
+	sw.addEventListener("pushsubscriptionchange", onChange);
+	return () => {
+		sw.removeEventListener?.("pushsubscriptionchange", onChange);
+	};
+}
+
+//#endregion
+//#region src/local-notifications.ts
+/**
+* Browsers store a `setTimeout` delay in a signed 32-bit int. A delay
+* larger than `2^31 - 1` ms (~24.8 days) overflows and is clamped — most
+* browsers fire (often immediately) rather than wait. So a far-future
+* local notification scheduled via the in-page timer fallback would fire
+* at the wrong time. We chunk long delays: arm a timer for at most
+* `MAX_TIMEOUT_MS`, and on wake re-arm for the remainder until due.
+*/
+const MAX_TIMEOUT_MS = 2147483647;
+const pendingTimers = /* @__PURE__ */ new Map();
+function hasNotificationApi() {
+	return typeof globalThis !== "undefined" && typeof globalThis.Notification === "function";
+}
+function timestampTriggerCtor() {
+	const ctor = globalThis.TimestampTrigger;
+	return typeof ctor === "function" ? ctor : void 0;
+}
+function genId() {
+	const c = globalThis.crypto;
+	if (c?.randomUUID) return c.randomUUID();
+	return `amba_local_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+/**
+* Per-INSTANCE token. The stable `__ambaLocalId` survives a reschedule of the
+* same id; this token does not — every individual `scheduleLocal` call mints a
+* fresh one. It lets `listScheduledLocal` distinguish a NEW pending schedule
+* for an id from an OLD already-fired-but-still-visible notification of the
+* SAME id (which the Service Worker reports under `getNotifications()`),
+* instead of conflating the two by id and hiding the pending one. (Round-5.)
+*/
+function genInstanceToken() {
+	return `${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. We reject blank at schedule time so every
+* returned handle id round-trips through `cancelLocal`. Shared by both
+* SDK platforms (web + react-native) for identical validation.
+*/
+function normalizeScheduleId(rawId) {
+	if (rawId === void 0) return genId();
+	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;
+}
+function parseTrigger(input) {
+	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 }");
+	if ("at" in trigger) {
+		const ms = (trigger.at instanceof Date ? trigger.at : new Date(trigger.at)).getTime();
+		if (Number.isNaN(ms)) throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: trigger.at must be a valid Date");
+		return {
+			kind: "absolute",
+			at: ms
+		};
+	}
+	if ("inSeconds" in trigger) {
+		if (!Number.isFinite(trigger.inSeconds) || trigger.inSeconds < 0) throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: trigger.inSeconds must be a non-negative number");
+		return {
+			kind: "relative",
+			seconds: trigger.inSeconds
+		};
+	}
+	throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.scheduleLocal: trigger must be { at: Date } or { inSeconds: number }");
+}
+/**
+* Resolve a parsed trigger to an absolute fire time (ms epoch). For a
+* relative trigger this is `now + seconds` — call it ONLY after permission
+* has resolved so `inSeconds` counts from when scheduling actually completes.
+*/
+function computeFireAt(parsed) {
+	return parsed.kind === "absolute" ? parsed.at : Date.now() + parsed.seconds * 1e3;
+}
+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");
+}
+async function ensurePermission() {
+	const N = globalThis.Notification;
+	let permission = N.permission;
+	if (permission === "default") permission = await N.requestPermission();
+	if (permission !== "granted") throw new AmbaApiError("LOCAL_NOTIFICATIONS_PERMISSION_DENIED", "user denied notification permission — local notifications cannot be shown");
+}
+/**
+* How long we'll wait for an existing-but-not-yet-active registration to
+* become `ready` before falling through to the in-page timer path. A real
+* activation is near-instant; this cap only guards against a wedged
+* activation hanging the call.
+*/
+const SW_READY_TIMEOUT_MS = 1e3;
+/**
+* Resolve the Service Worker registration to use for OS-trigger
+* notifications — WITHOUT ever hanging.
+*
+* The footgun this avoids: `navigator.serviceWorker.ready` NEVER resolves
+* when no service worker is registered (the common case for a page that has
+* the Notifications API but no SW). Awaiting it unconditionally would hang
+* `scheduleLocal` / `cancelLocal` / `listScheduledLocal` forever instead of
+* falling back to the documented in-page timer path. (Round-6 HIGH.)
+*
+* Instead we first call `getRegistration()`, which resolves to `undefined`
+* when nothing is registered (no hang). Only if a registration exists do we
+* wait — briefly, raced against a timeout — for `.ready`, so an active SW is
+* used while a wedged activation can't stall the caller.
+*/
+async function getServiceWorkerRegistration() {
+	const nav = globalThis.navigator;
+	if (!nav || !("serviceWorker" in nav)) return void 0;
+	const swc = nav.serviceWorker;
+	let existing;
+	try {
+		existing = await swc.getRegistration();
+	} catch {
+		return;
+	}
+	if (!existing) return void 0;
+	try {
+		return await Promise.race([swc.ready, new Promise((resolve) => setTimeout(() => resolve(void 0), SW_READY_TIMEOUT_MS))]) ?? existing;
+	} catch {
+		return existing;
+	}
+}
+/**
+* Cancel (close) any Service Worker OS-trigger notification scheduled by us
+* under `tag === id`. Passes `includeTriggered: true` so that
+* scheduled-but-not-yet-fired trigger notifications are returned by
+* `getNotifications` — without it, pending OS-trigger notifications are
+* invisible and therefore impossible to cancel. No-op when there's no
+* registration (degraded / timer-only environments).
+*/
+async function cancelOsTriggerNotification(registration, id) {
+	if (!registration) return;
+	try {
+		const matches = await registration.getNotifications({
+			tag: id,
+			includeTriggered: true
+		});
+		for (const n of matches) {
+			if ((n.data ?? {}).__ambaLocalId !== id) continue;
+			n.close();
+		}
+	} catch {}
+}
+/**
+* Show the in-page `Notification` for a fired timer. Tolerant of permission
+* being revoked between scheduling and firing (construction can throw).
+*/
+function fireInPageNotification(record, id) {
+	try {
+		const N = globalThis.Notification;
+		new N(record.title, {
+			body: record.body,
+			data: {
+				...record.data,
+				__ambaLocalId: id
+			},
+			tag: id
+		});
+	} catch {}
+}
+/**
+* Arm the next chunk of an in-page timer for the registry entry under `id`.
+* If the remaining delay until `entry.fireAt` exceeds `MAX_TIMEOUT_MS`, arm
+* for `MAX_TIMEOUT_MS` and re-arm on wake; otherwise arm for the exact
+* remainder, then fire and remove the entry.
+*
+* `entry.handle` is reassigned to each chunk's timeout id, so a concurrent
+* `clearTimeout(entry.handle)` (cancel / reschedule) always targets the live
+* chunk and stops the chain.
+*/
+function armTimerChunk(id, entry) {
+	const remaining = entry.fireAt - Date.now();
+	if (remaining > MAX_TIMEOUT_MS) {
+		entry.handle = setTimeout(() => {
+			if (pendingTimers.get(id) === entry) armTimerChunk(id, entry);
+		}, MAX_TIMEOUT_MS);
+		return;
+	}
+	entry.handle = setTimeout(() => {
+		if (pendingTimers.get(id) !== entry) return;
+		pendingTimers.delete(id);
+		fireInPageNotification(entry.record, id);
+	}, Math.max(0, remaining));
+}
+/**
+* The web `notifications` namespace. Web capability is partial — see the
+* module-level doc. The returned handle includes `scheduledVia` so apps
+* can detect whether the notification was handed to the OS
+* (`"os-trigger"`) or relies on an in-page timer (`"timer"`).
+*/
+const notifications = {
+	async scheduleLocal(input) {
+		validateContent(input);
+		if (!hasNotificationApi()) throw new AmbaApiError("LOCAL_NOTIFICATIONS_UNAVAILABLE", "the Notifications API is not available in this environment (server-side rendering, or a browser with notifications disabled). Local notifications require a browser context.");
+		const parsedTrigger = parseTrigger(input);
+		const id = normalizeScheduleId(input.id);
+		await ensurePermission();
+		const fireAt = computeFireAt(parsedTrigger);
+		const instanceToken = genInstanceToken();
+		const TriggerCtor = timestampTriggerCtor();
+		const registration = await getServiceWorkerRegistration();
+		if (TriggerCtor && registration) {
+			await registration.showNotification(input.title, {
+				body: input.body,
+				data: {
+					...input.data,
+					__ambaLocalId: id,
+					__ambaInstance: instanceToken
+				},
+				tag: id,
+				showTrigger: new TriggerCtor(fireAt)
+			});
+			const priorTimer$1 = pendingTimers.get(id);
+			if (priorTimer$1) {
+				clearTimeout(priorTimer$1.handle);
+				pendingTimers.delete(id);
+			}
+			return {
+				id,
+				scheduledVia: "os-trigger"
+			};
+		}
+		const priorTimer = pendingTimers.get(id);
+		if (priorTimer) {
+			clearTimeout(priorTimer.handle);
+			pendingTimers.delete(id);
+		}
+		await cancelOsTriggerNotification(registration, id);
+		const entry = {
+			handle: void 0,
+			fireAt,
+			record: {
+				id,
+				title: input.title,
+				body: input.body,
+				data: input.data
+			}
+		};
+		pendingTimers.set(id, entry);
+		armTimerChunk(id, entry);
+		return {
+			id,
+			scheduledVia: "timer"
+		};
+	},
+	async cancelLocal(id) {
+		if (typeof id !== "string" || id.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.notifications.cancelLocal: id is required");
+		const timer = pendingTimers.get(id);
+		if (timer) {
+			clearTimeout(timer.handle);
+			pendingTimers.delete(id);
+		}
+		await cancelOsTriggerNotification(await getServiceWorkerRegistration(), id);
+	},
+	async listScheduledLocal() {
+		const out = [];
+		for (const { record } of pendingTimers.values()) out.push({ ...record });
+		const registration = await getServiceWorkerRegistration();
+		if (registration) try {
+			const [withTriggered, shownOnly] = await Promise.all([registration.getNotifications({ includeTriggered: true }), registration.getNotifications()]);
+			const shownInstances = /* @__PURE__ */ new Set();
+			for (const n of shownOnly) {
+				const token = (n.data ?? {}).__ambaInstance;
+				if (token) shownInstances.add(token);
+			}
+			for (const n of withTriggered) {
+				const data = n.data ?? {};
+				const id = data.__ambaLocalId;
+				if (!id) continue;
+				const token = data.__ambaInstance;
+				if (token && shownInstances.has(token)) continue;
+				if (out.some((existing) => existing.id === id)) continue;
+				out.push({
+					id,
+					title: n.title,
+					body: n.body ?? "",
+					data
+				});
+			}
+		} catch {}
+		return out;
+	}
+};
 
 //#endregion
 //#region src/index.ts
@@ -296,6 +1346,153 @@ let _currentSessionToken = null;
 */
 let _configuredFunctionsBaseUrl = null;
 let _resolvedFunctionsProjectId = null;
+/**
+* Offline-resilience state. `_persistence` is the localStorage-backed store
+* captured at configure-time; `_offlineQueue` is lazily built the first time
+* `Amba.offline.enable()` runs. `_offlineEnabled` gates whether failed writes
+* are diverted to the durable outbox (opt-in — default behavior is unchanged,
+* a failed write throws). All three reset on every `configure()`.
+*/
+let _persistence = null;
+let _offlineQueue = null;
+let _offlineEnabled = false;
+/**
+* Detacher for the active queue's `online` auto-flush listener, if installed.
+* Held so a `configure()` (or a fresh `enable()`) can tear it down — otherwise
+* the previous queue's listener leaks and fires against a dead queue.
+*/
+let _offlineDetach = null;
+/**
+* Monotonic token identifying the CURRENT offline activation. Bumped on every
+* `enable()` AND every teardown/`configure()`, and 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) becomes
+* a no-op instead of wrongly turning the now-active outbox off.
+*/
+let _offlineEnableToken = 0;
+/**
+* Tear down any active offline wiring: detach the `online` listener, DISPOSE
+* the active queue (awaiting any in-flight flush so it can never write the
+* shared outbox again), and drop the references. Bumps the generation so stale
+* `enable()` disable callbacks no-op. Called before re-initializing on
+* `configure()`. Async so the in-flight flush is awaited before a replacement
+* queue is installed — preventing an orphaned flush from racing the new queue.
+*/
+async function teardownOffline() {
+	if (_offlineDetach) {
+		_offlineDetach();
+		_offlineDetach = null;
+	}
+	const old = _offlineQueue;
+	_offlineQueue = null;
+	_offlineEnabled = false;
+	_offlineEnableToken += 1;
+	if (old) await old.dispose();
+}
+/**
+* Bridge the localStorage persistence adapter to the {@link KvStore} contract
+* the offline outbox persists through. Namespaced under the configured
+* storage prefix so multiple projects in one origin don't collide.
+*/
+function offlineStore() {
+	const p = _persistence;
+	if (!p) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) before using Amba.offline.");
+	return {
+		get: (key) => p.read(key),
+		set: (key, value) => p.write(key, value),
+		delete: (key) => p.delete(key)
+	};
+}
+/**
+* Replay a single queued mutation against the live API, forwarding the op's
+* idempotency key on collection writes so a write that landed before the
+* connection dropped is never double-applied. Used as the {@link OfflineQueue}
+* executor.
+*/
+async function replayOutboxOp(op) {
+	switch (op.kind) {
+		case "collection.insert":
+			await coreCall((c) => c.collectionsInsert(op.collection, encodeJson({
+				...op.payload ?? {},
+				idempotency_key: op.idempotencyKey
+			})));
+			return;
+		case "collection.update":
+			await coreCall((c) => c.collectionsUpdate(op.collection, op.id, encodeJson(op.payload ?? {})));
+			return;
+		case "collection.delete":
+			await coreCall((c) => c.collectionsDelete(op.collection, op.id));
+			return;
+		case "track":
+			if (op.occurredAt !== void 0) await replayTrackDirect(op);
+			else await coreCall((c) => c.track(op.event, op.properties ? encodeJson(op.properties) : void 0, op.telemetry));
+			return;
+	}
+}
+/**
+* Replay a buffered `track` op via a direct POST to `/v1/client/events`,
+* preserving the original `timestamp` captured at enqueue (the events route
+* honors body `timestamp` → `occurred_at`, but attributes the event to the
+* current session user — it has no body-`anonymous_id` attribution). Throws on
+* a transport failure or non-2xx so the queue retains the op.
+*
+* A `401`/`403` (no / expired session at replay) is surfaced as a coded
+* `NETWORK_ERROR` so the outbox RETAINS the event for a later attempt — an
+* unauthenticated replay must NOT be dropped as a deterministic rejection
+* (the session may refresh and the event then lands).
+*/
+async function replayTrackDirect(op) {
+	const headers = { "content-type": "application/json" };
+	if (_configuredClientKey) headers["X-Api-Key"] = _configuredClientKey;
+	if (_currentSessionToken) headers["Authorization"] = `Bearer ${_currentSessionToken}`;
+	const body = {
+		event: op.event,
+		properties: op.properties ?? void 0,
+		timestamp: op.occurredAt,
+		...op.telemetry ? { telemetry: true } : {}
+	};
+	const eventsUrl = `${_configuredApiUrl.replace(/\/$/, "")}/v1/client/events`;
+	let resp;
+	try {
+		resp = await fetch(eventsUrl, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body)
+		});
+	} catch (err) {
+		throw new AmbaApiError("NETWORK_ERROR", `track replay network error: ${String(err)}`);
+	}
+	if (!resp.ok) {
+		if (resp.status === 401 || resp.status === 403) throw new AmbaApiError("NETWORK_ERROR", `track replay deferred: no valid session (status ${resp.status})`);
+		const text = await resp.text().catch(() => "");
+		let code = `HTTP_${resp.status}`;
+		try {
+			const parsed = JSON.parse(text);
+			if (typeof parsed?.error?.code === "string") code = parsed.error.code;
+		} catch {}
+		throw new AmbaApiError(code, `track replay failed with status ${resp.status}`, text);
+	}
+}
+function getOfflineQueue() {
+	if (!_offlineQueue) _offlineQueue = new OfflineQueue({
+		store: offlineStore(),
+		storageKey: `offline_outbox:${_configuredProjectId ?? "default"}`,
+		executor: replayOutboxOp,
+		onDropped: (op, err) => {
+			if (typeof console !== "undefined") console.warn(`[amba] dropped un-replayable offline ${op.kind} (${op.collection ?? op.event ?? "?"}):`, err);
+		}
+	});
+	return _offlineQueue;
+}
+async function insertDirect(name, row) {
+	return await coreCall((c) => c.collectionsInsert(name, encodeJson(row)));
+}
+async function updateDirect(name, id, set) {
+	return await coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set)));
+}
+async function deleteDirect(name, id) {
+	return await coreCall((c) => c.collectionsDelete(name, id));
+}
 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;
@@ -316,6 +1513,26 @@ async function coreCall(fn) {
 	}
 }
 const authSubscribers = /* @__PURE__ */ new Set();
+/**
+* Translate a public `TransactionOp` (camelCase `onConflict` /
+* `conflictTarget`) into the server's wire op (snake_case `on_conflict` /
+* `conflict_target`). Unset optionals are dropped so the server applies its
+* defaults.
+*/
+function toWireTransactionOp(op) {
+	const wire = {
+		collection: op.collection,
+		op: op.op
+	};
+	if (op.id !== void 0) wire["id"] = op.id;
+	if (op.row !== void 0) wire["row"] = op.row;
+	if (op.set !== void 0) wire["set"] = op.set;
+	if (op.where !== void 0) wire["where"] = op.where;
+	if (op.expected !== void 0) wire["expected"] = op.expected;
+	if (op.onConflict !== void 0) wire["on_conflict"] = op.onConflict;
+	if (op.conflictTarget !== void 0) wire["conflict_target"] = op.conflictTarget;
+	return wire;
+}
 function snapshotSession(user) {
 	if (!user) return null;
 	return {
@@ -348,6 +1565,35 @@ function realtimeAuthHeaders() {
 		Authorization: `Bearer ${_currentSessionToken}`
 	};
 }
+/** SDK-facing AI streaming routes (vendor split is a stable wire shape). */
+const AI_ANTHROPIC_PATH = "/v1/client/ai/anthropic/messages";
+const AI_OPENAI_PATH = "/v1/client/ai/openai/chat/completions";
+/**
+* Build the request (url + headers + body) for a streamed AI invocation.
+* Forces `stream: true` onto the request, injects the client key + live
+* session token, and targets the configured API base. Shared by the
+* Anthropic + OpenAI streaming methods so the auth/path wiring can't drift.
+*/
+function buildAiStreamRequest(path, request) {
+	requireCore();
+	if (!_configuredClientKey) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) before streaming AI.");
+	if (!request.prompt_slug || request.prompt_slug.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "prompt_slug is required");
+	const headers = {
+		"X-Api-Key": _configuredClientKey,
+		"content-type": "application/json",
+		accept: "text/event-stream"
+	};
+	if (_currentSessionToken) headers["Authorization"] = `Bearer ${_currentSessionToken}`;
+	const expanded = expandAiImages(request);
+	return {
+		url: `${_configuredApiUrl.replace(/\/$/, "")}${path}`,
+		headers,
+		body: JSON.stringify({
+			...expanded,
+			stream: true
+		})
+	};
+}
 /**
 * Resolve the full invocation URL for a deployed function.
 *
@@ -377,9 +1623,11 @@ const Amba = {
 		if (!config.projectId || config.projectId.trim() === "") throw new Error("Amba.configure: projectId is required");
 		if (!config.clientKey || config.clientKey.trim() === "") throw new Error("Amba.configure: clientKey is required");
 		await init(); // Hermes-stripped Node-init block (DX-15) — see scripts/build-rn.mjs
-		new LocalStoragePersistence(config.storagePrefix ?? "amba").hydrate();
+		const persistence = new LocalStoragePersistence(config.storagePrefix ?? "amba");
+		persistence.hydrate();
+		let nextCore;
 		try {
-			coreInstance = AmbaCoreWasm.init(encodeJson({
+			nextCore = AmbaCoreWasm.init(encodeJson({
 				api_key: config.clientKey,
 				base_url: config.apiUrl,
 				project_id: config.projectId,
@@ -391,6 +1639,9 @@ const Amba = {
 		} catch (err) {
 			throw toAmbaApiError(err);
 		}
+		await teardownOffline();
+		_persistence = persistence;
+		coreInstance = nextCore;
 		_configuredProjectId = config.projectId;
 		_configuredApiUrl = config.apiUrl ?? DEFAULT_API_URL;
 		_configuredClientKey = config.clientKey;
@@ -413,9 +1664,59 @@ const Amba = {
 	setDebug: (enabled) => {
 		requireCore().setDebug(enabled);
 	},
-	events: { track: async (event, properties, options) => {
-		await coreCall((c) => c.track(event, properties ? encodeJson(properties) : void 0, options?.telemetry));
-	} },
+	events: {
+		track: async (event, properties, options) => {
+			try {
+				await coreCall((c) => c.track(event, properties ? encodeJson(properties) : void 0, options?.telemetry));
+			} catch (err) {
+				if (_offlineEnabled && isOfflineError(err)) {
+					await getOfflineQueue().enqueue({
+						kind: "track",
+						event,
+						properties,
+						telemetry: options?.telemetry,
+						occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+					});
+					return;
+				}
+				throw err;
+			}
+		},
+		explain: async (event, properties, options) => {
+			if (!_configuredClientKey) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) before Amba.events.explain().");
+			if (!event || event.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.events.explain: an event name is required.");
+			const candidate = { name: event };
+			if (properties !== void 0) candidate["properties"] = properties;
+			if (options && "userId" in options) candidate["user_id"] = options.userId ?? null;
+			const headers = {
+				"Content-Type": "application/json",
+				"X-Api-Key": _configuredClientKey
+			};
+			if (_currentSessionToken) headers["Authorization"] = `Bearer ${_currentSessionToken}`;
+			let resp;
+			try {
+				resp = await fetch(`${_configuredApiUrl.replace(/\/$/, "")}/v1/client/events/explain`, {
+					method: "POST",
+					headers,
+					body: JSON.stringify({ event: candidate })
+				});
+			} catch (err) {
+				throw new AmbaApiError("NETWORK_ERROR", `Amba.events.explain("${event}") network error: ${String(err)}`);
+			}
+			const text = await resp.text();
+			let parsed = void 0;
+			if (text.length > 0) try {
+				parsed = JSON.parse(text);
+			} catch {
+				parsed = void 0;
+			}
+			if (!resp.ok) {
+				const envelope = parsed && typeof parsed === "object" ? parsed : void 0;
+				throw new AmbaApiError(typeof envelope?.error?.code === "string" ? envelope.error.code : `HTTP_${resp.status}`, typeof envelope?.error?.message === "string" ? envelope.error.message : `Amba.events.explain("${event}") failed with status ${resp.status}`, parsed);
+			}
+			return parsed.data;
+		}
+	},
 	auth: {
 		signInAnonymously: async () => {
 			const r = await coreCall((c) => c.signInAnonymously());
@@ -553,20 +1854,106 @@ const Amba = {
 			return await coreCall((c) => c.collectionsFindOne(name, id));
 		},
 		insert: async (name, row) => {
+			if (_offlineEnabled) {
+				const idempotencyKey = (typeof row["idempotency_key"] === "string" ? row["idempotency_key"] : void 0) ?? newIdempotencyKey();
+				const wireRow = {
+					...row,
+					idempotency_key: idempotencyKey
+				};
+				try {
+					return await coreCall((c) => c.collectionsInsert(name, encodeJson(wireRow)));
+				} catch (err) {
+					if (isOfflineError(err)) {
+						await getOfflineQueue().enqueue({
+							kind: "collection.insert",
+							collection: name,
+							payload: row,
+							idempotencyKey
+						});
+						return {
+							...row,
+							_amba_pending: true
+						};
+					}
+					throw err;
+				}
+			}
 			return await coreCall((c) => c.collectionsInsert(name, encodeJson(row)));
 		},
 		update: async (name, id, set) => {
+			if (_offlineEnabled) try {
+				return await coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set)));
+			} catch (err) {
+				if (isOfflineError(err)) {
+					await getOfflineQueue().enqueue({
+						kind: "collection.update",
+						collection: name,
+						id,
+						payload: set
+					});
+					return {
+						id,
+						...set,
+						_amba_pending: true
+					};
+				}
+				throw err;
+			}
 			return await coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set)));
 		},
 		delete: async (name, id) => {
+			if (_offlineEnabled) try {
+				return await coreCall((c) => c.collectionsDelete(name, id));
+			} catch (err) {
+				if (isOfflineError(err)) {
+					await getOfflineQueue().enqueue({
+						kind: "collection.delete",
+						collection: name,
+						id
+					});
+					return { data: { deleted: true } };
+				}
+				throw err;
+			}
 			return await coreCall((c) => c.collectionsDelete(name, id));
 		},
+		upsert: async (name, row, options) => {
+			const wire = {
+				on_conflict: options.onConflict,
+				conflict_target: options.conflictTarget
+			};
+			return await coreCall((c) => c.collectionsUpsert(name, encodeJson(row), encodeJson(wire)));
+		},
+		deleteWhere: async (name, filter) => {
+			return await coreCall((c) => c.collectionsDeleteWhere(name, encodeJson(filter)));
+		},
+		restore: async (name, id) => {
+			return await coreCall((c) => c.collectionsRestore(name, id));
+		},
+		transaction: async (operations) => {
+			return (await coreCall((c) => c.collectionsTransaction(encodeJson(operations.map(toWireTransactionOp))))).data;
+		},
 		findNearest: async (name, options) => {
 			return await coreCall((c) => c.collectionsFindNearest(name, encodeJson(options)));
 		},
 		count: async (name, filter) => {
 			return await coreCall((c) => c.collectionsCount(name, filter ? encodeJson(filter) : void 0));
 		},
+		optimisticInsert: async (name, row, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => insertDirect(name, row),
+			rollback: view.rollback
+		}),
+		optimisticUpdate: async (name, id, set, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => updateDirect(name, id, set),
+			rollback: view.rollback
+		}),
+		optimisticDelete: async (name, id, view) => withOptimistic({
+			apply: view.apply,
+			mutate: () => deleteDirect(name, id),
+			rollback: view.rollback
+		}),
 		where: {
 			eq: (column, value) => ({
 				column,
@@ -652,7 +2039,7 @@ const Amba = {
 				headers: uploadHeaders,
 				body: params.file
 			});
-			if (!putResp.ok) throw new Error(`upload to R2 failed: status ${putResp.status}`);
+			if (!putResp.ok) throw new Error(`upload to storage failed: status ${putResp.status}`);
 			return await coreCall((c) => c.storageCommit(presign.upload_id, presign.asset_id));
 		},
 		list: async (prefix) => {
@@ -666,6 +2053,32 @@ const Amba = {
 			return new Blob([bytes]);
 		}
 	},
+	media: { catalog: async (slug) => {
+		if (!_configuredClientKey) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) before reading a media catalog.");
+		if (!slug || slug.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.media.catalog: a catalog slug is required.");
+		const url = `${_configuredApiUrl.replace(/\/$/, "")}/v1/client/media/catalogs/${encodeURIComponent(slug)}`;
+		let resp;
+		try {
+			resp = await fetch(url, {
+				method: "GET",
+				headers: { "X-Api-Key": _configuredClientKey }
+			});
+		} catch (err) {
+			throw new AmbaApiError("NETWORK_ERROR", `Amba.media.catalog("${slug}") network error: ${String(err)}`);
+		}
+		const text = await resp.text();
+		let parsed = void 0;
+		if (text.length > 0) try {
+			parsed = JSON.parse(text);
+		} catch {
+			parsed = void 0;
+		}
+		if (!resp.ok) {
+			const envelope = parsed && typeof parsed === "object" ? parsed : void 0;
+			throw new AmbaApiError(typeof envelope?.error?.code === "string" ? envelope.error.code : `HTTP_${resp.status}`, typeof envelope?.error?.message === "string" ? envelope.error.message : `Amba.media.catalog("${slug}") failed with status ${resp.status}`, parsed);
+		}
+		return parsed.data;
+	} },
 	sync: {
 		pushChanges: async (changes) => {
 			return await coreCall((c) => c.syncPushChanges(encodeJson(changes)));
@@ -674,6 +2087,33 @@ const Amba = {
 			return await coreCall((c) => c.syncPullChanges(encodeJson(since)));
 		}
 	},
+	offline: {
+		enable: () => {
+			if (_offlineDetach) {
+				_offlineDetach();
+				_offlineDetach = null;
+			}
+			_offlineEnabled = true;
+			_offlineEnableToken += 1;
+			const token = _offlineEnableToken;
+			const q = getOfflineQueue();
+			_offlineDetach = q.startAutoFlush();
+			q.flush();
+			return () => {
+				if (_offlineEnableToken !== token) return;
+				_offlineEnabled = false;
+				if (_offlineDetach) {
+					_offlineDetach();
+					_offlineDetach = null;
+				}
+			};
+		},
+		isEnabled: () => _offlineEnabled,
+		pendingCount: async () => getOfflineQueue().pendingCount(),
+		pending: async () => getOfflineQueue().pending(),
+		flush: async () => getOfflineQueue().flush(),
+		clear: async () => getOfflineQueue().clear()
+	},
 	push: {
 		register: async (token, platform, bundleId) => {
 			return await coreCall((c) => c.pushRegister(token, platform, bundleId ?? void 0));
@@ -689,19 +2129,49 @@ const Amba = {
 		},
 		unsubscribe: async (topic) => {
 			await coreCall((c) => c.pushUnsubscribe(topic));
-		}
+		},
+		enableAutoRotation: () => enableWebPushAutoRotation((token) => Amba.push.register(token, "web"))
 	},
+	notifications,
 	entitlements: {
 		list: async () => {
 			return await coreCall((c) => c.entitlementsList());
 		},
 		has: async (name) => {
 			return await coreCall((c) => c.entitlementsHas(name));
+		},
+		restore: async () => {
+			return await coreCall((c) => c.entitlementsRestore());
 		}
 	},
-	ai: { anthropic: { messages: { create: async (request) => {
-		return await coreCall((c) => c.aiAnthropicMessages(encodeJson(request)));
-	} } } },
+	offerings: async (offeringId) => {
+		return await coreCall((c) => offeringId ? c.offeringsGet(offeringId) : c.offeringsList());
+	},
+	ai: {
+		anthropic: { messages: {
+			create: async (request) => {
+				return await coreCall((c) => c.aiAnthropicMessages(encodeJson(expandAiImages(request))));
+			},
+			stream: (request, options) => {
+				const { url, headers, body } = buildAiStreamRequest(AI_ANTHROPIC_PATH, request);
+				return invokeAiStream({
+					url,
+					headers,
+					body,
+					onChunk: options?.onChunk
+				});
+			}
+		} },
+		openai: { chat: { completions: { stream: (request, options) => {
+			const { url, headers, body } = buildAiStreamRequest(AI_OPENAI_PATH, request);
+			return invokeAiStream({
+				url,
+				headers,
+				body,
+				onChunk: options?.onChunk
+			});
+		} } } }
+	},
 	functions: { invoke: async (name, body, options) => {
 		requireCore();
 		if (!_configuredClientKey) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) before Amba.functions.invoke().");
@@ -735,9 +2205,14 @@ const Amba = {
 		} catch {
 			parsed = text;
 		}
+		const envelopeRequestId = parsed && typeof parsed === "object" ? parsed.error?.request_id ?? parsed.request_id : void 0;
+		const traceId = resp.headers.get("X-Amba-Request-Id") ?? (typeof envelopeRequestId === "string" ? envelopeRequestId : null);
+		options?.onTraceId?.(traceId);
 		if (!resp.ok) {
 			const envelope = parsed && typeof parsed === "object" ? parsed : void 0;
-			throw new AmbaApiError(typeof envelope?.error?.code === "string" ? envelope.error.code : `HTTP_${resp.status}`, typeof envelope?.error?.message === "string" ? envelope.error.message : typeof parsed === "string" && parsed.length > 0 ? parsed : `Amba.functions.invoke("${name}") failed with status ${resp.status}`, parsed);
+			const error = new AmbaApiError(typeof envelope?.error?.code === "string" ? envelope.error.code : `HTTP_${resp.status}`, typeof envelope?.error?.message === "string" ? envelope.error.message : typeof parsed === "string" && parsed.length > 0 ? parsed : `Amba.functions.invoke("${name}") failed with status ${resp.status}`, parsed);
+			if (traceId !== null) error.traceId = traceId;
+			throw error;
 		}
 		return parsed;
 	} },
@@ -802,6 +2277,12 @@ const Amba = {
 		getAll: async () => await coreCall((c) => c.streaksGetAll()),
 		qualify: async (streakKey) => await coreCall((c) => c.streaksQualify(streakKey))
 	},
+	get gamification() {
+		return new GamificationSubscription({
+			baseUrl: _configuredApiUrl,
+			authHeaders: realtimeAuthHeaders
+		});
+	},
 	feeds: { getActivity: async (feed, cursor) => await coreCall((c) => c.feedsGetActivity(feed ?? void 0, cursor ?? void 0)) },
 	friends: {
 		getList: async () => await coreCall((c) => c.friendsGetList()),
@@ -910,8 +2391,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.4";
+const SDK_VERSION = "4.0.5";
 
 //#endregion
-export { Amba, AmbaApiError, CollectionSubscription, ConversationSubscription, SDK_VERSION, getCoreWasm };
+export { Amba, AmbaApiError, CollectionSubscription, ConversationSubscription, GamificationSubscription, SDK_VERSION, getCoreWasm, withOptimistic };
 //# sourceMappingURL=index.js.map