@sovaria/sdk 0.0.0-stage → 0.4.0

package/dist/index.js

@@ -0,0 +1,2287 @@
+import { SovariaError, newTraceId, traceparentFor } from './errors.js';
+export { SovariaError, userMessageFor } from './errors.js';
+import { createAdminApi, createGovernanceApi, createKeysApi } from './complete-api.js';
+import { createGeneratedApi } from './generated.js';
+import { DocumentReference, Query, WriteBatch, runTransaction as runDocumentTransaction, } from './collections.js';
+export { DocumentReference, FieldValue, LiveQuery, Query, Transaction, WriteBatch, newDocumentId, splitTransforms, } from './collections.js';
+import { createOfflineTransport } from './offline.js';
+import { CrashReporter } from './crashes.js';
+export { CrashReporter, parseStack } from './crashes.js';
+export { evaluateQuery, indexedDbStorage, keyValueStorage, memoryStorage, } from './offline.js';
+import { decryptDocument, decryptDocumentWithKek, deriveKek, encryptDocument, encryptDocumentWithKek, hexToBytes, bytesToHex, zeroBytes, } from './crypto.js';
+export { ARGON2_HASH_LEN, ARGON2_MEMORY_COST, ARGON2_PARALLELISM, ARGON2_SALT_LEN, ARGON2_TIME_COST, computePayloadHash, decryptDocument, decryptDocumentWithKek, deriveKek, DEK_SIZE_BYTES, encryptDocument, encryptDocumentWithKek, generateSalt, hexToBytes, bytesToHex, NONCE_SIZE_BYTES, zeroBytes, } from './crypto.js';
+function storageObjectPath(bucket, objectPath) {
+    return [bucket, ...objectPath.split('/')].map((p) => safePathSegment(p)).join('/');
+}
+function resolveFetchImpl(fetchImpl) {
+    const candidate = fetchImpl ?? globalThis.fetch;
+    if (typeof candidate !== 'function') {
+        throw SovariaError.config('No fetch implementation available. Provide fetchImpl or run in an environment with global fetch.', 500);
+    }
+    // Browser fetch requires the Window context in some runtimes.
+    if (candidate === globalThis.fetch) {
+        return candidate.bind(globalThis);
+    }
+    return candidate;
+}
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+const SCOPE_REQUIRED_PREFIXES = ['/api/v1/sql/', '/api/v1/data/rel/', '/api/v1/rt/'];
+const SAFE_RETRY_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const REFRESH_MARGIN_MS = 60_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getHeaderCaseInsensitive(headers, headerName) {
+    const wanted = headerName.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === wanted) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function generateIdempotencyKey() {
+    const cryptoObj = globalThis.crypto;
+    if (typeof cryptoObj?.randomUUID === 'function') {
+        return cryptoObj.randomUUID();
+    }
+    if (typeof cryptoObj?.getRandomValues === 'function') {
+        const bytes = new Uint8Array(16);
+        cryptoObj.getRandomValues(bytes);
+        return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    }
+    throw SovariaError.config('No CSPRNG available for idempotency key generation', 500);
+}
+function existingIdempotencyKey(headers) {
+    const existing = getHeaderCaseInsensitive(headers, 'Idempotency-Key') ??
+        getHeaderCaseInsensitive(headers, 'X-Idempotency-Key');
+    return existing?.trim() || undefined;
+}
+/** Sets Idempotency-Key, dropping a differently-cased copy so the header is sent once. */
+function setIdempotencyKeyHeader(headers, key) {
+    for (const name of Object.keys(headers)) {
+        if (name.toLowerCase() === 'idempotency-key')
+            delete headers[name];
+    }
+    headers['Idempotency-Key'] = key;
+}
+function redactRefreshToken(tokens) {
+    const redacted = { ...tokens };
+    delete redacted.refresh_token;
+    return redacted;
+}
+function looksLikeJwt(token) {
+    const parts = token.split('.');
+    return parts.length === 3 && parts.every(Boolean) && token.startsWith('eyJ');
+}
+function parseRetryAfterMs(retryAfterHeader) {
+    if (!retryAfterHeader) {
+        return null;
+    }
+    const seconds = Number.parseFloat(retryAfterHeader);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.floor(seconds * 1000);
+    }
+    const retryAtMs = Date.parse(retryAfterHeader);
+    if (Number.isNaN(retryAtMs)) {
+        return null;
+    }
+    return Math.max(0, retryAtMs - Date.now());
+}
+function computeRetryDelayMs(attempt, retryBaseDelayMs, retryAfterMs = null) {
+    const jitterBackoffMs = Math.min(10_000, retryBaseDelayMs * 2 ** attempt * Math.random());
+    if (retryAfterMs === null) {
+        return jitterBackoffMs;
+    }
+    return Math.max(jitterBackoffMs, Math.min(60_000, retryAfterMs));
+}
+function safePathSegment(value) {
+    return encodeURIComponent(value);
+}
+function docCollectionPath(collection, documentId) {
+    const collectionPath = collection
+        .split('/')
+        .map((segment) => safePathSegment(segment))
+        .join('/');
+    return `/api/v1/data/doc/${collectionPath}/${safePathSegment(documentId)}`;
+}
+function normalizeSubpath(path) {
+    return path.replace(/^\/+/, '');
+}
+function mergeQuery(query) {
+    const params = new URLSearchParams();
+    if (!query) {
+        return params;
+    }
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        params.set(key, String(value));
+    }
+    return params;
+}
+/**
+ * Inside an Edge Function invoked in simulation mode (Forge sets SOVARIA_SIMULATION=1): every
+ * Sovaria call is checked as usual and its writes are rolled back or refused, so nothing changes.
+ */
+function simulationRun() {
+    const env = globalThis.process?.env;
+    const deno = globalThis.Deno;
+    let value;
+    try {
+        value = env?.SOVARIA_SIMULATION ?? deno?.env?.get('SOVARIA_SIMULATION');
+    }
+    catch {
+        value = undefined; // Deno without --allow-env
+    }
+    return (value ?? '').trim() === '1';
+}
+export class SovariaSDK {
+    baseUrl;
+    fetchImpl;
+    retryCount;
+    retryBaseDelayMs;
+    accessToken;
+    /** Project anon/publishable key: the token used when no user is signed in. */
+    publishableKey = '';
+    /** PKCE verifier for an in-flight provider sign-in (fallback when sessionStorage is unavailable). */
+    ssoVerifier;
+    /** PKCE verifier for an email link that opens an app (magic link / password reset). */
+    linkVerifier;
+    device;
+    attestationToken;
+    refreshToken;
+    expiresAtMs;
+    refreshInFlight;
+    scope;
+    /** In-flight lookup of the project/org behind a project URL (see resolveScope). */
+    scopeLookup;
+    onTokenRefresh;
+    onTokenRefreshSensitive;
+    sessionStore;
+    authListeners = new Set();
+    /** Session-cached Argon2id salt (hex from login/register). */
+    argon2Salt;
+    /** Session-cached KEK derived at login — reused for E2EE document ops. */
+    cachedKek;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.fetchImpl = resolveFetchImpl(options.fetchImpl);
+        this.retryCount = options.retryCount ?? 4;
+        this.retryBaseDelayMs = options.retryBaseDelayMs ?? 100;
+        this.accessToken = options.accessToken ?? '';
+        this.refreshToken = options.refreshToken ?? '';
+        const ttlMs = Math.max((options.expiresIn ?? 3600) * 1000, REFRESH_MARGIN_MS + 1);
+        this.expiresAtMs = this.accessToken ? Date.now() + ttlMs : 0;
+        this.refreshInFlight = null;
+        this.onTokenRefresh = options.onTokenRefresh;
+        this.onTokenRefreshSensitive = options.onTokenRefreshSensitive;
+        this.device = options.device;
+        this.attestationToken = options.attestationToken;
+        this.configureSessionStore(options.persistSession);
+    }
+    /** Device + attestation headers (mobile apps); empty for a plain web or server client. */
+    async clientHeaders() {
+        const out = {};
+        if (this.device?.id) {
+            out['X-Sovaria-Device-ID'] = this.device.id;
+            if (this.device.name)
+                out['X-Sovaria-Device-Name'] = this.device.name;
+            if (this.device.platform)
+                out['X-Sovaria-Device-Platform'] = this.device.platform;
+            if (this.device.appVersion)
+                out['X-Sovaria-App-Version'] = this.device.appVersion;
+        }
+        if (this.attestationToken) {
+            const token = await this.attestationToken();
+            if (token)
+                out['X-Sovaria-Attestation'] = token;
+        }
+        return out;
+    }
+    /** Start a PKCE pair for an email link; the verifier is kept (session storage too) until the link is opened. */
+    async startLinkPkce() {
+        const verifier = randomVerifier();
+        this.linkVerifier = verifier;
+        try {
+            ;
+            (this.sessionStore?.storage ?? globalThis.sessionStorage)?.setItem('sovaria.link.verifier', verifier);
+        }
+        catch {
+            /* kept in memory only */
+        }
+        return s256(verifier);
+    }
+    takeLinkVerifier(explicit) {
+        if (explicit)
+            return explicit;
+        let stored;
+        try {
+            const storage = this.sessionStore?.storage ?? globalThis.sessionStorage;
+            stored = storage?.getItem('sovaria.link.verifier') ?? undefined;
+            storage?.removeItem('sovaria.link.verifier');
+        }
+        catch {
+            stored = undefined;
+        }
+        const verifier = stored ?? this.linkVerifier;
+        this.linkVerifier = undefined;
+        return verifier;
+    }
+    configureSessionStore(option) {
+        if (!option)
+            return;
+        const custom = typeof option === 'object' ? option : {};
+        let storage = custom.storage;
+        if (!storage) {
+            try {
+                storage = globalThis.localStorage;
+            }
+            catch {
+                storage = undefined; // blocked storage (privacy mode): the session lasts for this page only
+            }
+        }
+        if (!storage)
+            return;
+        let host = 'default';
+        try {
+            host = new URL(this.baseUrl).host;
+        }
+        catch {
+            /* relative base URL */
+        }
+        this.sessionStore = { storage, key: custom.key ?? `sovaria.session.${host}` };
+    }
+    /** Load a stored session (called once the publishable key is known, so sign-out falls back to it). */
+    restoreSession() {
+        const store = this.sessionStore;
+        if (!store)
+            return;
+        let saved = null;
+        try {
+            const raw = store.storage.getItem(store.key);
+            saved = raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            saved = null;
+        }
+        if (!saved?.access_token)
+            return;
+        if (!saved.refresh_token && saved.expires_at <= Date.now()) {
+            this.writeSession(null);
+            return;
+        }
+        this.accessToken = saved.access_token;
+        this.refreshToken = saved.refresh_token ?? '';
+        this.expiresAtMs = saved.expires_at;
+    }
+    writeSession(session) {
+        const store = this.sessionStore;
+        if (!store)
+            return;
+        try {
+            if (session)
+                store.storage.setItem(store.key, JSON.stringify(session));
+            else
+                store.storage.removeItem(store.key);
+        }
+        catch {
+            /* storage full or blocked: keep working in memory */
+        }
+    }
+    currentSession() {
+        if (!this.accessToken || this.accessToken === this.publishableKey)
+            return null;
+        return {
+            access_token: this.accessToken,
+            ...(this.refreshToken ? { refresh_token: this.refreshToken } : {}),
+            expires_at: this.expiresAtMs,
+        };
+    }
+    emitAuth(event) {
+        const session = this.currentSession();
+        if (event !== 'INITIAL_SESSION')
+            this.writeSession(session);
+        for (const listener of [...this.authListeners]) {
+            try {
+                listener(event, session);
+            }
+            catch (error) {
+                console.error('SovariaSDK: onAuthStateChange listener failed', error);
+            }
+        }
+    }
+    static fromPortalConfig(config) {
+        const baseUrl = String(config.url ?? config.baseUrl ?? '').trim();
+        if (!baseUrl) {
+            throw SovariaError.config('Missing portal URL. Provide config.url or config.baseUrl.');
+        }
+        const accessToken = String(config.accessToken ??
+            config.access_token ??
+            config.publishableKey ??
+            config.publishable_key ??
+            config.anonKey ??
+            config.anon_key ??
+            '').trim();
+        const expiresInRaw = config.expiresIn ?? config.expires_in;
+        const sdk = new SovariaSDK({
+            baseUrl,
+            accessToken: accessToken || undefined,
+            expiresIn: typeof expiresInRaw === 'number' ? expiresInRaw : undefined,
+            onTokenRefresh: config.onTokenRefresh,
+            onTokenRefreshSensitive: config.onTokenRefreshSensitive,
+        });
+        const hasAppKey = Boolean(String(config.publishableKey ?? config.publishable_key ?? config.anonKey ?? config.anon_key ?? '').trim());
+        const persist = config.persistSession ?? (hasAppKey && typeof globalThis.window !== 'undefined');
+        sdk.configureSessionStore(persist);
+        const publishable = String(config.publishableKey ?? config.publishable_key ?? '').trim();
+        const fallbackKey = publishable || String(config.anonKey ?? config.anon_key ?? '').trim();
+        if (fallbackKey && !looksLikeJwt(fallbackKey)) {
+            sdk.publishableKey = fallbackKey;
+        }
+        if (publishable && looksLikeJwt(publishable)) {
+            console.warn('SovariaSDK: publishableKey looks like a user JWT. Use a portal publishable/anon key for frontend bootstrap; session JWTs belong in accessToken with expiresIn.');
+        }
+        const orgId = String(config.orgId ?? config.org_id ?? '').trim();
+        const projectId = String(config.projectId ?? config.project_id ?? '').trim();
+        const envId = String(config.envId ?? config.env_id ?? '').trim();
+        if (orgId && projectId) {
+            sdk.setScope({
+                orgId,
+                projectId,
+                envId: envId || undefined,
+            });
+        }
+        sdk.restoreSession();
+        return sdk;
+    }
+    static fromEnv(env = {}) {
+        const baseUrl = String(env.SOVARIA_URL ?? env.NEXT_PUBLIC_SOVARIA_URL ?? env.VITE_SOVARIA_URL ?? '').trim();
+        if (!baseUrl) {
+            throw SovariaError.config('Missing SOVARIA_URL (or NEXT_PUBLIC_SOVARIA_URL / VITE_SOVARIA_URL).');
+        }
+        return SovariaSDK.fromPortalConfig({
+            baseUrl,
+            orgId: env.SOVARIA_ORG_ID,
+            projectId: env.SOVARIA_PROJECT_ID,
+            envId: env.SOVARIA_ENV_ID,
+            accessToken: env.SOVARIA_ACCESS_TOKEN,
+            publishableKey: env.SOVARIA_PUBLISHABLE_KEY,
+            anonKey: env.SOVARIA_ANON_KEY,
+            expiresIn: env.SOVARIA_EXPIRES_IN ? Number(env.SOVARIA_EXPIRES_IN) : undefined,
+        });
+    }
+    setAccessToken(token, options = {}) {
+        this.accessToken = token.trim();
+        if (this.accessToken) {
+            const ttlMs = Math.max((options.expiresIn ?? 3600) * 1000, REFRESH_MARGIN_MS + 1);
+            this.expiresAtMs = Date.now() + ttlMs;
+        }
+        else {
+            this.expiresAtMs = 0;
+        }
+        return this;
+    }
+    setRefreshToken(token) {
+        this.refreshToken = token.trim();
+        return this;
+    }
+    clearAccessToken() {
+        const hadSession = this.currentSession() !== null;
+        this.accessToken = this.publishableKey;
+        this.refreshToken = '';
+        this.expiresAtMs = 0;
+        this.refreshInFlight = null;
+        this.clearKekCache();
+        if (hadSession)
+            this.emitAuth('SIGNED_OUT');
+        else
+            this.writeSession(null);
+        return this;
+    }
+    clearKekCache() {
+        if (this.cachedKek) {
+            zeroBytes(this.cachedKek);
+        }
+        this.cachedKek = undefined;
+        this.argon2Salt = undefined;
+    }
+    cacheArgon2SaltFromResponse(tokens) {
+        const saltHex = String(tokens.argon2_salt ?? '').trim();
+        if (!saltHex || Boolean(tokens.mfa_required)) {
+            return;
+        }
+        try {
+            this.argon2Salt = hexToBytes(saltHex);
+        }
+        catch {
+            // Non-fatal: E2EE calls will fall back to explicit password.
+        }
+    }
+    async tryDeriveKekFromPassword(password, tokens) {
+        if (!this.argon2Salt || Boolean(tokens.mfa_required)) {
+            return;
+        }
+        try {
+            const kek = await deriveKek(password, this.argon2Salt);
+            if (this.cachedKek) {
+                zeroBytes(this.cachedKek);
+            }
+            this.cachedKek = kek;
+        }
+        catch {
+            // Non-fatal: session remains valid; E2EE requires explicit password.
+        }
+    }
+    applyAuthResponse(tokens, event = 'SIGNED_IN') {
+        const accessToken = String(tokens.access_token ?? '');
+        const refreshToken = String(tokens.refresh_token ?? '');
+        const mfaRequired = Boolean(tokens.mfa_required);
+        if (accessToken) {
+            this.setAccessToken(accessToken, {
+                expiresIn: Number(tokens.expires_in ?? (mfaRequired ? 300 : 3600)),
+            });
+        }
+        if (refreshToken) {
+            this.setRefreshToken(refreshToken);
+        }
+        else if (mfaRequired) {
+            this.refreshToken = '';
+        }
+        this.cacheArgon2SaltFromResponse(tokens);
+        this.onTokenRefreshSensitive?.(tokens);
+        this.onTokenRefresh?.(redactRefreshToken(tokens));
+        if (accessToken && !mfaRequired)
+            this.emitAuth(event);
+        return tokens;
+    }
+    tokenNeedsRefresh() {
+        if (!this.accessToken || !this.refreshToken) {
+            return false;
+        }
+        return Date.now() >= this.expiresAtMs - REFRESH_MARGIN_MS;
+    }
+    /** Refresh when the token is near expiry, or always with `force` (the server said 401). */
+    async ensureAccessTokenFresh(force = false) {
+        if (!force && !this.tokenNeedsRefresh()) {
+            return;
+        }
+        if (this.refreshInFlight) {
+            await this.refreshInFlight;
+            return;
+        }
+        this.refreshInFlight = (async () => {
+            let refreshed;
+            try {
+                refreshed = await this.auth.refresh(this.refreshToken);
+            }
+            catch (error) {
+                // The refresh token was revoked or expired: the user is signed out, not "broken".
+                if (error instanceof SovariaError && [400, 401, 403].includes(error.statusCode)) {
+                    this.clearAccessToken();
+                    throw new SovariaError(401, error.detail, 'UNAUTHENTICATED');
+                }
+                throw error;
+            }
+            this.applyAuthResponse(refreshed, 'TOKEN_REFRESHED');
+        })();
+        try {
+            await this.refreshInFlight;
+        }
+        finally {
+            this.refreshInFlight = null;
+        }
+    }
+    setScope(scope) {
+        this.scope = {
+            orgId: scope.orgId.trim(),
+            projectId: scope.projectId.trim(),
+            envId: scope.envId?.trim(),
+        };
+        return this;
+    }
+    clearScope() {
+        this.scope = undefined;
+        this.scopeLookup = undefined;
+        return this;
+    }
+    /**
+     * The org/project this client talks to. Set explicitly with setScope(), or discovered once from
+     * the project URL (https://<ref>.sovarias.in) — so `createClient(projectUrl, anonKey)` is enough.
+     */
+    async resolveScope() {
+        if (this.scope?.orgId && this.scope?.projectId)
+            return this.scope;
+        this.scopeLookup ??= this.request('GET', '/api/v1/auth/public-config', {
+            requiresAuth: false,
+            requiresScope: false,
+        })
+            .then((cfg) => {
+            const project = (cfg?.project ?? {});
+            if (project.id && project.orgId) {
+                this.setScope({ orgId: String(project.orgId), projectId: String(project.id) });
+            }
+            return this.scope;
+        })
+            .catch(() => {
+            this.scopeLookup = undefined;
+            return undefined;
+        });
+        return this.scopeLookup;
+    }
+    getScopeHeaders() {
+        if (!this.scope) {
+            return {};
+        }
+        const headers = {
+            'X-Sovaria-Org-ID': this.scope.orgId,
+            'X-Sovaria-Project-ID': this.scope.projectId,
+        };
+        if (this.scope.envId) {
+            headers['X-Sovaria-Env-ID'] = this.scope.envId;
+        }
+        return headers;
+    }
+    getRealtimeWebSocketUrl(channel, ticket) {
+        const protocolSwapped = this.baseUrl
+            .replace(/^https:\/\//, 'wss://')
+            .replace(/^http:\/\//, 'ws://');
+        const params = new URLSearchParams();
+        const resolvedTicket = (ticket ?? '').trim();
+        if (resolvedTicket) {
+            params.set('ticket', resolvedTicket);
+        }
+        if (this.scope?.orgId) {
+            params.set('org_id', this.scope.orgId);
+        }
+        if (this.scope?.projectId) {
+            params.set('project_id', this.scope.projectId);
+        }
+        if (this.scope?.envId) {
+            params.set('env_id', this.scope.envId);
+        }
+        const suffix = params.toString();
+        const base = `${protocolSwapped}/api/v1/rt/ws/${safePathSegment(channel)}`;
+        return suffix ? `${base}?${suffix}` : base;
+    }
+    async issueRealtimeWebSocketTicket(channel) {
+        await this.resolveScope();
+        this.assertScopePresent();
+        const response = await this.request('POST', '/api/v1/auth/ws-ticket', {
+            body: {
+                channel,
+                org_id: this.scope?.orgId,
+                project_id: this.scope?.projectId,
+                env_id: this.scope?.envId,
+            },
+            requiresScope: true,
+        });
+        const ticket = String(response.ticket ?? '').trim();
+        if (!ticket) {
+            throw new SovariaError(502, 'Gateway did not return a websocket ticket');
+        }
+        return ticket;
+    }
+    async getRealtimeWebSocketUrlWithTicket(channel) {
+        const ticket = await this.issueRealtimeWebSocketTicket(channel);
+        return this.getRealtimeWebSocketUrl(channel, ticket);
+    }
+    offlineTransport;
+    /**
+     * Offline-first documents: reads fall back to a local cache, offline writes are applied locally at
+     * once and queued, and everything syncs in order when the connection is back. Call once, before
+     * reading or writing documents.
+     *
+     * ```ts
+     * const offline = sov.enableOffline({ storage: indexedDbStorage(), onSyncError: (e, writes) => console.warn(e, writes) })
+     * ```
+     */
+    enableOffline(options = {}) {
+        if (!this.offlineTransport) {
+            this.offlineTransport = createOfflineTransport(this.onlineDocumentsTransport(), {
+                namespace: this.scope?.projectId || 'default', ...options,
+            });
+        }
+        return this.offlineTransport.controller;
+    }
+    documentsTransport() {
+        return this.offlineTransport ?? this.onlineDocumentsTransport();
+    }
+    onlineDocumentsTransport() {
+        return {
+            request: (method, path, options) => this.request(method, path, options),
+            openChannel: (name, handlers) => this.realtime.channel(name, {
+                onMessage: (payload) => handlers.onMessage?.(payload),
+                onStatus: (status) => handlers.onStatus?.(status),
+                onError: handlers.onError,
+            }),
+        };
+    }
+    /**
+     * A document collection (or `users/alice/posts` subcollection): field queries, cursors,
+     * live listeners and `add`.
+     *
+     * ```ts
+     * const snap = await sov.collection('posts').where('tags', 'array-contains', 'news').orderBy('at', 'desc').limit(20).get()
+     * ```
+     */
+    collection(path) {
+        return new Query(this.documentsTransport(), path);
+    }
+    /** A document reference: `get`, `set` (merge), `create`, `update` with FieldValue transforms, `delete`, `onSnapshot`. */
+    doc(path) {
+        return new DocumentReference(this.documentsTransport(), path);
+    }
+    /** Writes committed together: every one or none. */
+    batch() {
+        return new WriteBatch(this.documentsTransport());
+    }
+    /** Read then write atomically; retried (up to `maxAttempts`) when a document it read changes meanwhile. */
+    runTransaction(fn, maxAttempts = 5) {
+        return runDocumentTransaction(this.documentsTransport(), fn, maxAttempts);
+    }
+    /**
+     * App crash reporting: `sov.crashes.install({ release })` reports uncaught errors (browser and React
+     * Native); `sov.crashes.capture(error)` reports one you caught. Issues appear in the console under
+     * Observability › Crashes.
+     */
+    crashes = new CrashReporter((events) => this.request('POST', '/crashes/v1/events', { body: { events }, requiresScope: false }));
+    async request(method, path, options = {}) {
+        if (path.startsWith('/crashes/v1'))
+            return this.requestImpl(method, path, options);
+        let status = 0;
+        try {
+            const out = await this.requestImpl(method, path, options);
+            status = 200;
+            return out;
+        }
+        catch (error) {
+            status = error instanceof SovariaError ? error.statusCode : 0;
+            throw error;
+        }
+        finally {
+            // Breadcrumb for crash reports: which Sovaria calls led up to an error (no bodies or tokens).
+            this.crashes.addBreadcrumb({ category: 'sovaria', message: `${method.toUpperCase()} ${path.split('?')[0]} ${status || 'network error'}` });
+        }
+    }
+    async requestImpl(method, path, options = {}) {
+        const normalizedMethod = method.toUpperCase();
+        const requiresAuth = options.requiresAuth ?? true;
+        const requiresScope = options.requiresScope ?? this.pathRequiresScope(path);
+        if (requiresAuth && !this.accessToken) {
+            throw new SovariaError(401, 'Missing access token; call auth.consoleLogin() / auth.projectLogin() or setAccessToken() first');
+        }
+        if (requiresAuth) {
+            await this.ensureAccessTokenFresh();
+        }
+        if (requiresAuth && requiresScope) {
+            if (!this.scope)
+                await this.resolveScope();
+            this.assertScopePresent();
+        }
+        const queryParams = mergeQuery(options.query);
+        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+        const url = `${this.baseUrl}${normalizedPath}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        const headers = {
+            ...this.getScopeHeaders(),
+            ...(await this.clientHeaders()),
+            ...(simulationRun() ? { 'X-Echo-Mode': '1' } : {}),
+            ...(options.headers ?? {}),
+        };
+        if (requiresAuth) {
+            headers.Authorization = `Bearer ${this.accessToken}`;
+        }
+        const hasBody = options.body !== undefined;
+        if (hasBody && !(options.body instanceof FormData) && !headers['Content-Type']) {
+            headers['Content-Type'] = 'application/json';
+        }
+        // One Idempotency-Key for every attempt of a write (the caller's, or a fresh one): if the first
+        // try was applied but its response was lost, the retry gets the stored answer instead of
+        // running the change twice.
+        const idempotencyKey = options.idempotencyKey?.trim() ||
+            existingIdempotencyKey(headers) ||
+            (MUTATING_METHODS.has(normalizedMethod) ? generateIdempotencyKey() : undefined);
+        if (idempotencyKey) {
+            setIdempotencyKeyHeader(headers, idempotencyKey);
+        }
+        const canRetry = SAFE_RETRY_METHODS.has(normalizedMethod) || MUTATING_METHODS.has(normalizedMethod);
+        // One trace per call (every retry shares it), so a refused request can be explained later.
+        const callerTrace = Object.keys(headers).find((k) => k.toLowerCase() === 'traceparent');
+        const traceId = callerTrace ? headers[callerTrace].split('-')[1] ?? newTraceId() : newTraceId();
+        for (let attempt = 0; attempt < this.retryCount; attempt += 1) {
+            if (!callerTrace)
+                headers.traceparent = traceparentFor(traceId);
+            try {
+                const fetchImpl = this.fetchImpl;
+                const response = await fetchImpl(url, {
+                    method: normalizedMethod,
+                    headers,
+                    body: hasBody
+                        ? options.body instanceof FormData
+                            ? options.body
+                            : JSON.stringify(options.body)
+                        : undefined,
+                });
+                if (response.ok && options.responseType === 'blob') {
+                    return (await response.blob());
+                }
+                const contentType = response.headers.get('content-type') ?? '';
+                const isJson = contentType.includes('application/json');
+                const payload = isJson
+                    ? await response.json().catch(() => ({}))
+                    : await response.text().catch(() => '');
+                if (response.ok) {
+                    options.onResponseHeaders?.(response.headers);
+                    if (response.status === 204) {
+                        return {};
+                    }
+                    return payload;
+                }
+                if (response.status === 401 &&
+                    requiresAuth &&
+                    this.refreshToken &&
+                    attempt === 0) {
+                    await this.ensureAccessTokenFresh(true);
+                    headers.Authorization = `Bearer ${this.accessToken}`;
+                    continue;
+                }
+                // "The same Idempotency-Key is still being processed": wait, then the retry gets the first
+                // try's stored answer instead of running the change twice.
+                const inProgress = response.status === 409 && payload?.code === 'IDEMPOTENCY_IN_PROGRESS';
+                if (canRetry && (RETRYABLE_STATUSES.has(response.status) || inProgress) && attempt < this.retryCount - 1) {
+                    const retryAfterMs = response.status === 429 || inProgress ? parseRetryAfterMs(response.headers.get('Retry-After')) : null;
+                    const delay = computeRetryDelayMs(attempt, this.retryBaseDelayMs, retryAfterMs);
+                    await sleep(delay);
+                    continue;
+                }
+                throw new SovariaError(response.status, payload).withTraceId(response.headers.get('X-Request-ID') ?? traceId);
+            }
+            catch (error) {
+                if (error instanceof SovariaError) {
+                    throw error;
+                }
+                if (attempt >= this.retryCount - 1 || !canRetry) {
+                    throw new SovariaError(0, String(error));
+                }
+                const delay = computeRetryDelayMs(attempt, this.retryBaseDelayMs);
+                await sleep(delay);
+            }
+        }
+        throw new SovariaError(0, 'Max retries exceeded');
+    }
+    pathRequiresScope(path) {
+        return SCOPE_REQUIRED_PREFIXES.some((prefix) => path.startsWith(prefix));
+    }
+    assertScopePresent() {
+        if (this.scope?.orgId && this.scope?.projectId) {
+            return;
+        }
+        throw SovariaError.config('This endpoint requires org/project scope. Call setScope({ orgId, projectId, envId? }).');
+    }
+    async productAuthRequest(method, suffix, options = {}) {
+        await this.resolveScope();
+        return this.request(method, this.productAuthPath(suffix), options);
+    }
+    productAuthPath(suffix) {
+        this.assertScopePresent();
+        return `/api/v1/projects/${safePathSegment(this.scope.projectId)}/auth${suffix}`;
+    }
+    auth = {
+        /**
+         * Listen for sign-in, token refresh and sign-out. Fires once right away with the current
+         * session (`INITIAL_SESSION`). Returns a function that stops listening.
+         */
+        onAuthStateChange: (callback) => {
+            this.authListeners.add(callback);
+            queueMicrotask(() => {
+                if (!this.authListeners.has(callback))
+                    return;
+                try {
+                    callback('INITIAL_SESSION', this.currentSession());
+                }
+                catch (error) {
+                    console.error('SovariaSDK: onAuthStateChange listener failed', error);
+                }
+            });
+            return () => {
+                this.authListeners.delete(callback);
+            };
+        },
+        /** The signed-in app user's session, or null. */
+        getSession: () => this.currentSession(),
+        /** Sign the app user out (revokes the refresh token) and fall back to the anon key. */
+        signOut: async () => {
+            await this.auth.logout();
+        },
+        /**
+         * Create an app user and sign them in. When the project requires email confirmation, the
+         * result has `email_verification_required: true` and no session until the user confirms.
+         */
+        signUp: async (email, password, name = '') => {
+            const created = await this.auth.register(email, password, name);
+            if (created.access_token || created.email_verification_required)
+                return created;
+            const session = await this.auth.projectLogin(email, password);
+            return { ...created, ...session };
+        },
+        /** Sign an app user in with email and password (same as projectLogin). */
+        signIn: async (email, password) => this.auth.projectLogin(email, password),
+        /** Create an app user (no session). Most apps want signUp(), which also signs them in. */
+        register: async (email, password, name) => {
+            await this.resolveScope();
+            const scopePayload = this.scope
+                ? {
+                    org_id: this.scope.orgId,
+                    project_id: this.scope.projectId,
+                    ...(this.scope.envId ? { env_id: this.scope.envId } : {}),
+                }
+                : {};
+            const tokens = await this.request('POST', '/api/v1/auth/register', {
+                requiresAuth: false,
+                body: { email, password, name, ...scopePayload },
+            });
+            if (tokens.access_token) {
+                this.applyAuthResponse(tokens);
+                await this.tryDeriveKekFromPassword(password, tokens);
+            }
+            return tokens;
+        },
+        /**
+         * @deprecated Use {@link consoleLogin} for operators or {@link projectLogin}
+         * for product users. Unscoped calls post to `/api/v1/auth/console/login`.
+         */
+        login: async (email, password) => {
+            console.warn('auth.login() is deprecated; use auth.consoleLogin() for operators or auth.projectLogin() for product users. Unscoped login() posts to /api/v1/auth/console/login (not legacy /api/v1/auth/login).');
+            await this.resolveScope();
+            const scopePayload = this.scope
+                ? {
+                    org_id: this.scope.orgId,
+                    project_id: this.scope.projectId,
+                    ...(this.scope.envId ? { env_id: this.scope.envId } : {}),
+                }
+                : {};
+            const path = this.scope?.orgId && this.scope?.projectId
+                ? '/api/v1/auth/project/login'
+                : '/api/v1/auth/console/login';
+            const tokens = await this.request('POST', path, {
+                requiresAuth: false,
+                body: { email, password, ...scopePayload },
+            });
+            this.applyAuthResponse(tokens);
+            await this.tryDeriveKekFromPassword(password, tokens);
+            return tokens;
+        },
+        /** Strict console login — rejects every project-scoped credential. */
+        consoleLogin: async (email, password) => {
+            const tokens = await this.request('POST', '/api/v1/auth/console/login', {
+                requiresAuth: false,
+                body: { email, password },
+            });
+            this.applyAuthResponse(tokens);
+            await this.tryDeriveKekFromPassword(password, tokens);
+            return tokens;
+        },
+        /** Alias for consoleLogin() matching lane terminology in docs. */
+        loginConsole: async (email, password) => this.auth.consoleLogin(email, password),
+        /** Strict project login — requires X-Sovaria-Org-ID + X-Sovaria-Project-ID. */
+        projectLogin: async (email, password) => {
+            await this.resolveScope();
+            if (!this.scope?.orgId || !this.scope?.projectId) {
+                throw SovariaError.config('projectLogin() needs the project: create the client with your project URL, or call setScope({ orgId, projectId }).');
+            }
+            const tokens = await this.request('POST', '/api/v1/auth/project/login', {
+                requiresAuth: false,
+                body: {
+                    email,
+                    password,
+                    org_id: this.scope.orgId,
+                    project_id: this.scope.projectId,
+                    ...(this.scope.envId ? { env_id: this.scope.envId } : {}),
+                },
+            });
+            this.applyAuthResponse(tokens);
+            await this.tryDeriveKekFromPassword(password, tokens);
+            return tokens;
+        },
+        /** Alias for projectLogin() matching lane terminology in docs. */
+        loginProduct: async (email, password) => this.auth.projectLogin(email, password),
+        refresh: async (refreshToken) => this.request('POST', '/api/v1/auth/refresh', {
+            requiresAuth: false,
+            body: { refresh_token: refreshToken },
+        }),
+        logout: async (refreshToken) => {
+            const token = (refreshToken ?? this.refreshToken).trim();
+            try {
+                if (this.accessToken && token) {
+                    return await this.request('POST', '/api/v1/auth/logout', {
+                        body: { refresh_token: token },
+                    });
+                }
+                return {};
+            }
+            finally {
+                this.clearAccessToken();
+            }
+        },
+        me: async () => {
+            const me = await this.request('GET', '/api/v1/auth/me');
+            const orgId = String(me.org_id ?? '');
+            const projectId = String(me.project_id ?? '');
+            const envId = String(me.env_id ?? '');
+            if (orgId && projectId && !this.scope) {
+                this.setScope({ orgId, projectId, envId: envId || undefined });
+            }
+            return me;
+        },
+        verifyMfa: async (code, method = 'totp') => {
+            const tokens = await this.request('POST', '/api/v1/auth/mfa/verify', {
+                body: { code, method },
+            });
+            return this.applyAuthResponse(tokens);
+        },
+        /** Send a one-time login link by email. Returns 200 even for unknown emails. */
+        /**
+         * Email a sign-in link (plus a 6-digit code). A link that opens a mobile app (`myapp://…` or a
+         * registered app link) is bound to this app with PKCE automatically; pass `pkce: true` to force it.
+         */
+        sendMagicLink: async (email, opts = {}) => {
+            const orgId = opts.orgId ?? this.scope?.orgId;
+            const projectId = opts.projectId ?? this.scope?.projectId;
+            const challenge = opts.pkce || isAppRedirect(opts.redirectTo) ? await this.startLinkPkce() : undefined;
+            return this.request('POST', '/api/v1/auth/magic-link/send', {
+                requiresAuth: false,
+                body: {
+                    email,
+                    ...(orgId ? { org_id: orgId } : {}),
+                    ...(projectId ? { project_id: projectId } : {}),
+                    // Must be your Site URL or in the project's redirect allow-list; otherwise the Site URL is used.
+                    ...(opts.redirectTo ? { redirect_to: opts.redirectTo } : {}),
+                    ...(challenge ? { code_challenge: challenge } : {}),
+                },
+            });
+        },
+        /** Email a password-reset link. Returns 200 even for unknown emails. */
+        resetPasswordForEmail: async (email, opts = {}) => {
+            const orgId = opts.orgId ?? this.scope?.orgId;
+            const projectId = opts.projectId ?? this.scope?.projectId;
+            const challenge = opts.pkce || isAppRedirect(opts.redirectTo) ? await this.startLinkPkce() : undefined;
+            return this.request('POST', '/api/v1/auth/password-reset/send', {
+                requiresAuth: false,
+                body: {
+                    email,
+                    ...(orgId ? { org_id: orgId } : {}),
+                    ...(projectId ? { project_id: projectId } : {}),
+                    ...(opts.redirectTo ? { redirect_to: opts.redirectTo } : {}),
+                    ...(challenge ? { code_challenge: challenge } : {}),
+                },
+            });
+        },
+        /** Set a new password with the token from a reset link (`type=recovery`). */
+        confirmPasswordReset: (token, newPassword, codeVerifier) => {
+            const verifier = this.takeLinkVerifier(codeVerifier);
+            return this.request('POST', '/api/v1/auth/password-reset/confirm', {
+                requiresAuth: false,
+                body: { token, new_password: newPassword, ...(verifier ? { code_verifier: verifier } : {}) },
+            });
+        },
+        /**
+         * Handle the link an auth email opened (`?token=…&type=…` on your Site URL).
+         * Magic links sign the user in; email confirmations are confirmed; for `recovery`
+         * the token is returned so you can show a "new password" form and call
+         * `confirmPasswordReset`. Returns null when the URL isn't an auth link.
+         */
+        handleEmailLink: async (url) => {
+            const href = url ?? (typeof window !== 'undefined' ? window.location.href : '');
+            if (!href)
+                return null;
+            const params = new URL(href).searchParams;
+            const type = params.get('type');
+            if (type === 'sso') {
+                const error = params.get('error');
+                if (error)
+                    return { type, error, description: params.get('error_description') ?? undefined };
+                const code = params.get('code');
+                return code ? { type, session: await this.auth.exchangeCodeForSession(code) } : null;
+            }
+            const token = params.get('token');
+            if (!token || !type)
+                return null;
+            if (type === 'magiclink')
+                return { type, session: await this.auth.verifyMagicLink(token) };
+            if (type === 'signup')
+                return { type, result: await this.auth.confirmVerificationEmail(token) };
+            if (type === 'email_change_current')
+                return { type, result: await this.request('POST', '/api/v1/auth/email-change/confirm', { requiresAuth: false, body: { token } }) };
+            if (type === 'email_change_new')
+                return { type, result: await this.request('POST', '/api/v1/auth/email-change/finalize', { requiresAuth: false, body: { token } }) };
+            return { type, token };
+        },
+        /**
+         * "Sign in with Google / GitHub / …" (providers connected in Authentication › Sign in / Providers).
+         * Sends the browser to the provider; it comes back to `redirectTo` (or your Site URL) with
+         * `?code=…&type=sso`, which `handleEmailLink()` / `exchangeCodeForSession()` turn into a session.
+         * A PKCE verifier is kept in sessionStorage so only this browser can redeem the code.
+         */
+        signInWithProvider: async (providerId, opts = {}) => {
+            const projectId = opts.projectId ?? (await this.resolveScope())?.projectId;
+            if (!projectId)
+                throw SovariaError.config('signInWithProvider() needs a project id (use the project URL or setScope first).');
+            const verifier = randomVerifier();
+            const challenge = await s256(verifier);
+            this.ssoVerifier = verifier;
+            try {
+                globalThis.sessionStorage?.setItem('sovaria.sso.verifier', verifier);
+            }
+            catch {
+                /* storage unavailable: the code can still be exchanged without PKCE */
+            }
+            const params = new URLSearchParams({ project_id: projectId, code_challenge: challenge, code_challenge_method: 'S256', mode: 'json' });
+            if (opts.redirectTo)
+                params.set('redirect_to', opts.redirectTo);
+            const res = await this.request('GET', `/api/v1/auth/sso/${encodeURIComponent(providerId)}/authorize?${params}`, { requiresAuth: false });
+            const url = String(res.authorization_url ?? '');
+            if (typeof window !== 'undefined' && url)
+                window.location.assign(url);
+            return { url };
+        },
+        /** Exchange the one-time `code` from a provider sign-in redirect for a session. */
+        exchangeCodeForSession: async (code, codeVerifier) => {
+            let verifier = codeVerifier;
+            if (!verifier) {
+                try {
+                    verifier = globalThis.sessionStorage?.getItem('sovaria.sso.verifier') ?? undefined;
+                    globalThis.sessionStorage?.removeItem('sovaria.sso.verifier');
+                }
+                catch {
+                    verifier = undefined;
+                }
+                verifier = verifier ?? this.ssoVerifier;
+            }
+            this.ssoVerifier = undefined;
+            const tokens = await this.request('POST', '/api/v1/auth/sso/exchange', {
+                requiresAuth: false,
+                body: { code, ...(verifier ? { code_verifier: verifier } : {}) },
+            });
+            return this.applyAuthResponse(tokens);
+        },
+        /** Enabled social / enterprise providers for your sign-in screen. */
+        listProviders: async (projectId) => {
+            const pid = projectId ?? (await this.resolveScope())?.projectId;
+            if (!pid)
+                throw SovariaError.config('listProviders() needs a project id (use the project URL or setScope first).');
+            return this.request('GET', `/api/v1/auth/sso/providers?project_id=${encodeURIComponent(pid)}`, { requiresAuth: false });
+        },
+        /** Public sign-in config for a project: enabled providers, password rules, MFA factors, passkeys. */
+        getPublicConfig: (projectId) => {
+            const pid = projectId ?? this.scope?.projectId;
+            // Without an id the project host (https://<ref>.sovarias.in) identifies the project.
+            const query = pid ? `?project_id=${encodeURIComponent(pid)}` : '';
+            return this.request('GET', `/api/v1/auth/public-config${query}`, {
+                requiresAuth: false,
+                requiresScope: false,
+            });
+        },
+        /** Exchange a magic-link token for an access + refresh token pair. */
+        verifyMagicLink: async (token, codeVerifier) => {
+            const verifier = this.takeLinkVerifier(codeVerifier);
+            const tokens = await this.request('POST', '/api/v1/auth/magic-link/verify', {
+                requiresAuth: false,
+                body: { token, ...(verifier ? { code_verifier: verifier } : {}) },
+            });
+            return this.applyAuthResponse(tokens);
+        },
+        /**
+         * Sign in with the 6-digit code from the sign-in email (the same email carries the magic link).
+         * Uses the client scope's org/project unless given.
+         */
+        verifyEmailCode: async (email, code, opts = {}) => {
+            const orgId = opts.orgId ?? this.scope?.orgId;
+            const projectId = opts.projectId ?? this.scope?.projectId;
+            const tokens = await this.request('POST', '/api/v1/auth/magic-link/verify-code', {
+                requiresAuth: false,
+                body: { email, code: code.replace(/\s+/g, ''), ...(orgId ? { org_id: orgId } : {}), ...(projectId ? { project_id: projectId } : {}) },
+            });
+            return this.applyAuthResponse(tokens);
+        },
+        /** Send an SMS OTP code for phone-based login. */
+        sendOtp: (phone, opts = {}) => {
+            const body = { phone };
+            const orgId = opts.orgId ?? this.scope?.orgId;
+            const projectId = opts.projectId ?? this.scope?.projectId;
+            const envId = opts.envId ?? this.scope?.envId;
+            if (orgId) {
+                body.org_id = orgId;
+            }
+            if (projectId) {
+                body.project_id = projectId;
+            }
+            if (envId) {
+                body.env_id = envId;
+            }
+            return this.request('POST', '/api/v1/auth/otp/send', {
+                requiresAuth: false,
+                body,
+            });
+        },
+        /** Verify an SMS OTP code and establish a session.
+         * Passwordless by default — pass `password` when argon2_salt is present to
+         * populate the session KEK without a follow-up password login.
+         */
+        verifyOtp: async (phone, code, opts = {}) => {
+            const body = { phone, code };
+            const orgId = opts.orgId ?? this.scope?.orgId;
+            const projectId = opts.projectId ?? this.scope?.projectId;
+            const envId = opts.envId ?? this.scope?.envId;
+            if (orgId) {
+                body.org_id = orgId;
+            }
+            if (projectId) {
+                body.project_id = projectId;
+            }
+            if (envId) {
+                body.env_id = envId;
+            }
+            const tokens = await this.request('POST', '/api/v1/auth/otp/verify', {
+                requiresAuth: false,
+                body,
+            });
+            this.applyAuthResponse(tokens);
+            if (opts.password) {
+                await this.tryDeriveKekFromPassword(opts.password, tokens);
+            }
+            return tokens;
+        },
+        /** Exchange an OAuth handoff token for a session (console OAuth callback).
+         * Passwordless: session KEK is not derived unless `password` is supplied.
+         */
+        oauthHandoff: async (token, password) => {
+            const tokens = await this.request('POST', '/api/v1/auth/oauth/handoff', {
+                requiresAuth: false,
+                body: { token },
+            });
+            this.applyAuthResponse(tokens);
+            if (password) {
+                await this.tryDeriveKekFromPassword(password, tokens);
+            }
+            return tokens;
+        },
+        /** Console-operator listing of product users across accessible projects. Path: GET /api/v1/auth/product-users (console lane). */
+        listConsoleProductUsers: () => this.request('GET', '/api/v1/auth/product-users'),
+        /** Trigger a verification email for the authenticated user. */
+        sendVerificationEmail: () => this.request('POST', '/api/v1/auth/verify-email/send', {
+            body: {},
+        }),
+        /** Confirm an email-verification token. */
+        confirmVerificationEmail: (token) => this.request('POST', '/api/v1/auth/verify-email/confirm', {
+            requiresAuth: false,
+            body: { token },
+        }),
+        /**
+         * Auth event hooks (per-project HTTP webhooks). The project is the client's scope
+         * (`X-Sovaria-Project-ID`); the caller must be an owner or admin of it.
+         */
+        eventHooks: {
+            list: () => this.request('GET', '/api/v1/auth/event-hooks', {
+                requiresScope: false,
+            }),
+            create: (payload) => this.request('POST', '/api/v1/auth/event-hooks', {
+                body: {
+                    name: payload.name,
+                    url: payload.url,
+                    events: payload.events,
+                    secret: payload.secret ?? '',
+                    enabled: payload.enabled ?? true,
+                },
+                // A project other than the client's scope is named by the header, never the body.
+                ...(payload.projectId ? { headers: { 'X-Sovaria-Project-ID': payload.projectId } } : {}),
+                requiresScope: false,
+            }),
+            delete: (hookId) => this.request('DELETE', `/api/v1/auth/event-hooks/${safePathSegment(hookId)}`, { requiresScope: false }),
+        },
+        /**
+         * @deprecated Legacy GET `/api/v1/auth/users`. Use `productUsers.list()` for
+         * project-scoped product users or `listConsoleProductUsers()` for the console
+         * product-user admin path. Use `consoleMembers.list()` for org console members.
+         */
+        listUsers: () => {
+            console.warn('auth.listUsers() is deprecated (legacy GET /api/v1/auth/users). ' +
+                'For product users use auth.productUsers.list() ' +
+                '(GET /api/v1/projects/{id}/auth/users) or auth.listConsoleProductUsers() ' +
+                '(GET /api/v1/auth/product-users). For org console members use auth.consoleMembers.list() ' +
+                '(GET /api/v1/org/{orgId}/members).');
+            if (this.scope?.orgId && this.scope?.projectId) {
+                return this.auth.productUsers.list();
+            }
+            return this.auth.listConsoleProductUsers();
+        },
+        /**
+         * @deprecated Legacy DELETE `/api/v1/auth/users/{id}`. Use `productUsers.delete()`
+         * or `consoleMembers.delete()`.
+         */
+        deleteUser: (userId) => {
+            console.warn('auth.deleteUser() is deprecated (legacy DELETE /api/v1/auth/users/{id}). ' +
+                'Use auth.productUsers.delete() for product users or auth.consoleMembers.delete() for console members.');
+            if (this.scope?.orgId && this.scope?.projectId) {
+                return this.auth.productUsers.delete(userId);
+            }
+            return this.request('DELETE', `/api/v1/auth/product-users/${safePathSegment(userId)}`);
+        },
+        /**
+         * @deprecated Legacy POST `/api/v1/auth/users/{id}/ban`. Use `productUsers.ban()`.
+         */
+        banUser: (userId) => {
+            console.warn('auth.banUser() is deprecated (legacy POST /api/v1/auth/users/{id}/ban). ' +
+                'Use auth.productUsers.ban() for product users.');
+            if (this.scope?.orgId && this.scope?.projectId) {
+                return this.auth.productUsers.ban(userId);
+            }
+            return this.request('POST', `/api/v1/auth/product-users/${safePathSegment(userId)}/ban`);
+        },
+        /** Org console-member management. Canonical path: GET /api/v1/org/{orgId}/members. Not product users. */
+        consoleMembers: {
+            list: () => {
+                const orgId = this.scope?.orgId;
+                if (!orgId) {
+                    throw SovariaError.config('consoleMembers.list() requires setScope({ orgId, projectId }). Canonical path: GET /api/v1/org/{orgId}/members. For product users use auth.productUsers.list() or auth.listConsoleProductUsers().');
+                }
+                return this.request('GET', `/api/v1/org/${safePathSegment(orgId)}/members`);
+            },
+            delete: (userId) => {
+                const orgId = this.scope?.orgId;
+                if (!orgId) {
+                    throw SovariaError.config('consoleMembers.delete() requires setScope({ orgId, projectId }). Canonical path: DELETE /api/v1/org/{orgId}/member/{userId}.');
+                }
+                return this.request('DELETE', `/api/v1/org/${safePathSegment(orgId)}/member/${safePathSegment(userId)}`);
+            },
+            ban: (userId) => {
+                console.warn('auth.consoleMembers.ban() is not a console-member route. Use auth.productUsers.ban() for product users. Legacy POST /api/v1/auth/users/{id}/ban is deprecated.');
+                if (this.scope?.orgId && this.scope?.projectId) {
+                    return this.auth.productUsers.ban(userId);
+                }
+                return this.request('POST', `/api/v1/auth/product-users/${safePathSegment(userId)}/ban`);
+            },
+        },
+        /** Product auth admin (project-scoped identities). Path: GET /api/v1/projects/{id}/auth/users. Requires setScope. */
+        productUsers: {
+            /** Every product user: follows all pages. Use `listPage()` for big projects. */
+            list: async () => {
+                const all = [];
+                let cursor = null;
+                do {
+                    const page = await this.auth.productUsers.listPage({ limit: 500, cursor });
+                    all.push(...page.users);
+                    cursor = page.nextCursor;
+                } while (cursor);
+                return all;
+            },
+            /** One page of product users, newest first. `search` matches part of an email or an exact id. */
+            listPage: async (params = {}) => {
+                let headers = null;
+                const limit = Math.max(1, Math.min(Math.trunc(params.limit ?? 50), 500));
+                const body = await this.productAuthRequest('GET', '/users', {
+                    requiresScope: true,
+                    query: { limit, cursor: params.cursor || undefined, q: params.search || undefined, status: params.status },
+                    onResponseHeaders: (h) => {
+                        headers = h;
+                    },
+                });
+                const h = headers;
+                const total = h?.get('x-total-count') ?? '';
+                return {
+                    users: Array.isArray(body) ? body : [],
+                    nextCursor: h?.get('x-next-cursor') || null,
+                    total: /^\d+$/.test(total) ? Number(total) : null,
+                };
+            },
+            delete: (userId) => this.productAuthRequest('DELETE', `/users/${safePathSegment(userId)}`, {
+                requiresScope: true,
+            }),
+            ban: (userId) => this.productAuthRequest('POST', `/users/${safePathSegment(userId)}/ban`, {
+                requiresScope: true,
+            }),
+            roles: (userId) => this.productAuthRequest('GET', `/users/${safePathSegment(userId)}/roles`, {
+                requiresScope: true,
+            }),
+            setRoles: (userId, roles) => this.productAuthRequest('PUT', `/users/${safePathSegment(userId)}/roles`, {
+                requiresScope: true,
+                body: { roles },
+            }),
+            create: (payload) => this.productAuthRequest('POST', '/users', {
+                requiresScope: true,
+                body: payload,
+            }),
+            /**
+             * Bulk-import app users (up to 1,000 per call) with their ids and password hashes: `bcrypt`
+             * (Supabase) as is, `firebase_scrypt` (Firebase) checked with `hashConfig` and upgraded to bcrypt
+             * at first sign-in. No emails, hooks or triggers fire; existing emails are skipped. Org owners/admins.
+             */
+            import: (users, hashConfig) => this.productAuthRequest('POST', '/users/import', {
+                requiresScope: true,
+                body: hashConfig ? { users, hash_config: hashConfig } : { users },
+            }),
+        },
+        sessions: {
+            list: () => this.request('GET', '/api/v1/auth/sessions'),
+            revoke: (sessionId) => this.request('DELETE', `/api/v1/auth/sessions/${safePathSegment(sessionId)}`),
+            revokeOthers: () => this.request('POST', '/api/v1/auth/sessions/revoke-others', { body: {} }),
+            getConfig: () => this.request('GET', '/api/v1/auth/sessions/config'),
+            setConfig: (body) => this.request('PUT', '/api/v1/auth/sessions/config', { body }),
+        },
+        providersConfig: {
+            get: () => this.request('GET', '/api/v1/auth/providers/config'),
+            set: (body) => this.request('PUT', '/api/v1/auth/providers/config', { body }),
+        },
+        mfa: {
+            status: () => this.request('GET', '/api/v1/auth/mfa/status'),
+            enroll: () => this.request('POST', '/api/v1/auth/mfa/enroll', { body: {} }),
+            disable: (totpCode) => this.request('DELETE', '/api/v1/auth/mfa', { body: { totp_code: totpCode } }),
+        },
+        github: {
+            connectionState: () => this.request('GET', '/api/v1/auth/github/connection-state'),
+            disconnect: () => this.request('DELETE', '/api/v1/auth/github/connection-state'),
+        },
+    };
+    graph = {
+        createNode: (nodeType, name, metadata = {}) => this.request('POST', '/api/v1/org', {
+            body: { type: nodeType, name, metadata },
+        }),
+        createEdge: (sourceId, targetId, relationType, role) => this.request('POST', '/api/v1/edge', {
+            body: { source_id: sourceId, target_id: targetId, relation_type: relationType, role },
+        }),
+        addMember: (orgId, userId, role = 'MEMBER') => this.request('POST', `/api/v1/org/${safePathSegment(orgId)}/member`, {
+            body: { user_id: userId, role },
+        }),
+        getContext: (userId, resourceId) => this.request('GET', `/api/v1/context/${safePathSegment(userId)}/${safePathSegment(resourceId)}`),
+        listNodes: (nodeType) => this.request('GET', '/api/v1/org', {
+            query: nodeType ? { type: nodeType } : undefined,
+        }),
+        getNode: (nodeId) => this.request('GET', `/api/v1/org/${safePathSegment(nodeId)}`),
+        getChildren: (parentId, relation = 'OWNS') => this.request('GET', `/api/v1/org/${safePathSegment(parentId)}/children`, {
+            query: { relation },
+        }),
+        updateOrg: (orgId, body) => this.request('PUT', `/api/v1/org/${safePathSegment(orgId)}`, { body }),
+        deleteOrg: (orgId) => this.request('DELETE', `/api/v1/org/${safePathSegment(orgId)}`),
+        setOrgPlan: (orgId, body) => this.request('PUT', `/api/v1/org/${safePathSegment(orgId)}/plan`, { body }),
+        listMembers: (orgId) => this.request('GET', `/api/v1/org/${safePathSegment(orgId)}/members`),
+        removeMember: (orgId, userId) => this.request('DELETE', `/api/v1/org/${safePathSegment(orgId)}/member/${safePathSegment(userId)}`),
+        updateMember: (orgId, userId, body) => this.request('PUT', `/api/v1/org/${safePathSegment(orgId)}/member/${safePathSegment(userId)}`, { body }),
+        createInvite: (orgId, body) => this.request('POST', `/api/v1/org/${safePathSegment(orgId)}/invites`, { body }),
+        acceptInvite: (body) => this.request('POST', '/api/v1/org/invites/accept', { body }),
+        getRoleMatrix: () => this.request('GET', '/api/v1/roles/matrix'),
+        setRoleMatrix: (body) => this.request('PUT', '/api/v1/roles/matrix', { body }),
+        getRoleCatalog: () => this.request('GET', '/api/v1/roles/catalog'),
+        getProjectRef: (projectId) => this.request('GET', `/api/v1/org/${safePathSegment(projectId)}/ref`),
+        getProjectSettings: () => this.request('GET', '/api/v1/project-settings', { requiresScope: true }),
+        setProjectSettings: (body) => this.request('PUT', '/api/v1/project-settings', { body, requiresScope: true }),
+    };
+    data = {
+        docPut: (collection, documentId, data) => this.request('POST', `/api/v1/data/doc/${collection
+            .split('/')
+            .map((segment) => safePathSegment(segment))
+            .join('/')}/${safePathSegment(documentId)}`, { body: { data } }),
+        docGet: (collection, documentId, atTxid) => this.request('GET', `/api/v1/data/doc/${collection
+            .split('/')
+            .map((segment) => safePathSegment(segment))
+            .join('/')}/${safePathSegment(documentId)}`, { query: atTxid ? { at_txid: atTxid } : undefined }),
+        docDelete: (collection, documentId) => this.request('DELETE', docCollectionPath(collection, documentId)),
+        /** Encrypt client-side and write a Zero-Knowledge document envelope to Atlas-Doc. */
+        putDocumentE2ee: async (collection, documentId, plaintext, password) => {
+            const plainBytes = typeof plaintext === 'string' ? new TextEncoder().encode(plaintext) : plaintext;
+            let envelope;
+            if (this.cachedKek && this.argon2Salt) {
+                envelope = await encryptDocumentWithKek(plainBytes, this.cachedKek);
+                envelope = { ...envelope, salt: bytesToHex(this.argon2Salt) };
+            }
+            else if (password) {
+                if (!this.argon2Salt) {
+                    throw SovariaError.config('No server Argon2 salt is available for this session. Password-only E2EE writes will not generate an ephemeral salt. Log in/register against a Phase 2 server that returns argon2_salt.');
+                }
+                envelope = await encryptDocument(plainBytes, password, this.argon2Salt);
+                envelope = { ...envelope, salt: bytesToHex(this.argon2Salt) };
+            }
+            else {
+                throw SovariaError.config('No cached KEK found. Either log in with a Phase 2–enabled server or supply the password argument explicitly.');
+            }
+            return this.request('POST', docCollectionPath(collection, documentId), {
+                body: {
+                    document: {
+                        collection_id: collection,
+                        document_id: documentId,
+                        ...envelope,
+                    },
+                },
+                headers: { 'X-Payload-Hash': envelope.payload_hash },
+            });
+        },
+        /** Retrieve and decrypt a Zero-Knowledge document from Atlas-Doc. */
+        getDocumentE2ee: async (collection, documentId, password, atTxid) => {
+            const resp = await this.request('GET', docCollectionPath(collection, documentId), { query: atTxid ? { at_txid: atTxid } : undefined });
+            if (!resp.found) {
+                throw new SovariaError(404, `Document ${documentId} not found`);
+            }
+            const doc = resp.document;
+            const envelope = {
+                ciphertext: String(doc.ciphertext ?? ''),
+                nonce: String(doc.nonce ?? ''),
+                auth_tag: String(doc.auth_tag ?? ''),
+                encrypted_dek: String(doc.encrypted_dek ?? ''),
+                dek_nonce: String(doc.dek_nonce ?? ''),
+                payload_hash: String(doc.payload_hash ?? ''),
+            };
+            let plaintext;
+            if (this.cachedKek && this.argon2Salt) {
+                plaintext = await decryptDocumentWithKek(envelope, this.cachedKek);
+            }
+            else if (password) {
+                const saltHex = String(doc.salt ?? '');
+                const salt = this.argon2Salt ?? (saltHex ? hexToBytes(saltHex) : undefined);
+                if (!salt) {
+                    throw SovariaError.config('No Argon2 salt available to decrypt. The document envelope must embed salt, or the session must have a cached server salt.');
+                }
+                plaintext = await decryptDocument(envelope, password, salt);
+            }
+            else {
+                throw SovariaError.config('No cached KEK. Supply the password argument to decrypt.');
+            }
+            return { ...resp, plaintext };
+        },
+        /**
+         * List the documents in one collection (newest writes last): `[{ id, data, txid }]`.
+         * Subcollections are not included — list `collection/<docId>/<sub>` for those.
+         */
+        docList: async (collection, options = {}) => {
+            const prefix = `${collection.replace(/^\/+|\/+$/g, '')}:`;
+            const res = await this.request('POST', '/api/v1/data/query/scan', {
+                body: { prefix, limit: options.limit ?? 500 },
+            });
+            const docs = res.documents ?? [];
+            return docs
+                .map((d) => ({ id: String(d.key ?? '').slice(prefix.length), data: (d.data ?? {}), txid: Number(d.txid ?? 0) }))
+                .filter((d) => d.id && !d.id.includes('/'));
+        },
+        /** Field query (`where`, `order_by`, `limit`, cursors) — see also `sov.collection(...)`. */
+        docQuery: (collection, query = {}) => this.request('POST', `/api/v1/data/doc/_query/${collection.split('/').map(safePathSegment).join('/')}`, { body: query }),
+        docCount: (collection, query = {}) => this.request('POST', `/api/v1/data/doc/_count/${collection.split('/').map(safePathSegment).join('/')}`, { body: query }),
+        /** Atomic commit: `{ op, path, data, merge, transforms, precondition }` writes; `reads` make it a transaction. */
+        docCommit: (writes, reads = []) => this.request('POST', '/api/v1/data/doc/_commit', { body: { writes, reads } }),
+        docIndexes: (collection) => this.request('GET', '/api/v1/data/doc/_indexes', { query: { collection } }),
+        createDocIndex: (collection, fields) => this.request('POST', '/api/v1/data/doc/_indexes', { body: { collection, fields } }),
+        dropDocIndex: (name) => this.request('DELETE', `/api/v1/data/doc/_indexes/${safePathSegment(name)}`),
+        collectionRules: (collection) => this.request('GET', `/api/v1/data/doc/_rules/${collection.split('/').map(safePathSegment).join('/')}`),
+        docScan: (args) => this.request('POST', '/api/v1/data/query/scan', { body: args }),
+        /**
+         * Run one SQL statement. Pass values for `$1, $2, …` as `params` — they are bound by the
+         * database, so user input never becomes SQL: `sql('SELECT * FROM books WHERE id = $1', [id])`.
+         * A number as the second argument is still read as `txid` (older signature).
+         */
+        sql: (sql, params, txid = 0) => {
+            const bound = Array.isArray(params) ? params : undefined;
+            const snapshot = typeof params === 'number' ? params : txid;
+            return this.request('POST', '/api/v1/sql/query', {
+                body: { sql, ...(bound && bound.length ? { params: bound } : {}), ...(snapshot > 0 ? { txid: snapshot } : {}) },
+            });
+        },
+        tableCreate: (payload) => this.request('POST', '/api/v1/data/rel/create', { body: payload }),
+        tableDrop: (tableName) => this.request('POST', '/api/v1/data/rel/drop', {
+            body: { table_name: tableName },
+        }),
+        tableAddColumn: (payload) => this.request('POST', '/api/v1/data/rel/column/add', { body: payload }),
+        tableDropColumn: (tableName, columnName) => this.request('POST', '/api/v1/data/rel/column/drop', {
+            body: { table_name: tableName, column_name: columnName },
+        }),
+        tableAddForeignKey: (payload) => this.request('POST', '/api/v1/data/rel/foreign-key/add', { body: payload }),
+        tableDropForeignKey: (payload) => this.request('POST', '/api/v1/data/rel/foreign-key/drop', { body: payload }),
+        tableMigrations: (query) => this.request('GET', '/api/v1/data/rel/migrations', { query }),
+        /** The schema as one short line per table: types, keys, →references, allowed values, indexes, owner-only rows. */
+        schemaDigest: (options = {}) => this.request('GET', '/api/v1/data/rel/schema/digest', {
+            query: { tables: options.tables?.join(',') || undefined, max_chars: options.maxChars, since: options.since },
+            requiresScope: true,
+        }),
+        /**
+         * Create or extend tables from one declarative plan: checked first (a 422 lists every problem and nothing
+         * changes), then applied as one reversible migration and verified. `dryRun` returns the SQL instead.
+         */
+        applySchemaPlan: (plan) => this.request('POST', '/api/v1/data/rel/schema/plan', {
+            body: { tables: plan.tables, dry_run: plan.dryRun, name: plan.name },
+            requiresScope: true,
+        }),
+        /** Apply a migration atomically and record it in the project's history. `downSql` makes it reversible. */
+        applyMigration: (migration) => this.request('POST', '/api/v1/data/rel/migrations/apply', {
+            body: { name: migration.name, up_sql: migration.upSql, down_sql: migration.downSql, version: migration.version },
+            requiresScope: true,
+        }),
+        /** Run a migration inside a transaction and roll it back: reports whether it would apply. */
+        dryRunMigration: (migration) => this.request('POST', '/api/v1/data/rel/migrations/dry-run', {
+            body: { name: migration.name, up_sql: migration.upSql, down_sql: migration.downSql },
+            requiresScope: true,
+        }),
+        /**
+         * Check several migrations the way they will be applied (what `sov db migrations push --dry-run` does):
+         * all run in order inside one transaction that is rolled back, so later ones see what earlier ones
+         * create. Up to 500 and 5 MB of SQL; `failed.index` is the first that fails. Nothing is kept.
+         */
+        dryRunMigrations: (migrations) => this.request('POST', '/api/v1/data/rel/migrations/dry-run-sequence', {
+            body: { migrations: migrations.map((m) => ({ name: m.name, up_sql: m.upSql })) },
+            requiresScope: true,
+        }),
+        /** Undo the latest migration (or `version` with `force`) using its down SQL. */
+        rollbackMigration: (opts = {}) => this.request('POST', '/api/v1/data/rel/migrations/rollback', {
+            query: { ...(opts.version ? { version: opts.version } : {}), ...(opts.force ? { force: 'true' } : {}) },
+            requiresScope: true,
+        }),
+        beginTransaction: () => this.request('POST', '/api/v1/data/rel/transaction/begin', { requiresScope: true }),
+        commitTransaction: (txid) => this.request('POST', '/api/v1/data/rel/transaction/commit', {
+            body: { txid },
+            requiresScope: true,
+        }),
+        rollbackTransaction: (txid) => this.request('POST', '/api/v1/data/rel/transaction/rollback', {
+            body: { txid },
+            requiresScope: true,
+        }),
+    };
+    realtime = {
+        subscribe: (channel, clientId) => this.request('POST', '/api/v1/rt/stream/subscribe', {
+            body: { channel, client_id: clientId },
+        }),
+        unsubscribe: (channel, clientId) => this.request('POST', '/api/v1/rt/stream/unsubscribe', {
+            body: { channel, client_id: clientId },
+        }),
+        presence: (channel) => this.request('GET', `/api/v1/rt/stream/presence/${safePathSegment(channel)}`),
+        channels: () => this.request('GET', '/api/v1/rt/stream/channels'),
+        replay: (channel, after = 0, limit = 200) => this.request('GET', `/api/v1/rt/stream/replay/${safePathSegment(channel)}`, {
+            query: { after, limit },
+        }),
+        publish: (channel, payload, clock, clockDelta) => this.request('POST', `/api/v1/rt/stream/publish/${safePathSegment(channel)}`, {
+            body: {
+                payload,
+                clock,
+                clock_delta: clockDelta,
+            },
+        }),
+        e2eeBootstrap: (channel, ttlSeconds = 86400, forceNew = false) => this.request('POST', '/api/v1/rt/e2ee/keys/bootstrap', {
+            body: { channel, ttl_seconds: ttlSeconds, force_new: forceNew },
+        }),
+        e2eeRotate: (channel, ttlSeconds = 86400) => this.request('POST', '/api/v1/rt/e2ee/keys/rotate', {
+            body: { channel, ttl_seconds: ttlSeconds },
+        }),
+        e2eeRevoke: (channel, keyId, reason) => this.request('POST', '/api/v1/rt/e2ee/keys/revoke', {
+            body: { channel, key_id: keyId, reason },
+        }),
+        /** Pass your RSA-OAEP (SHA-256) public key — PEM or base64 SPKI — to get the key wrapped for you. */
+        e2eeActiveKey: (channel, clientPublicKey) => this.request('GET', `/api/v1/rt/e2ee/keys/active/${safePathSegment(channel)}`, {
+            query: { client_public_key_pem: clientPublicKey },
+        }),
+        e2eeGetKey: (channel, keyId, clientPublicKey) => this.request('GET', `/api/v1/rt/e2ee/keys/${safePathSegment(channel)}/${safePathSegment(keyId)}`, { query: { client_public_key_pem: clientPublicKey } }),
+        e2eeListKeys: (channel) => this.request('GET', `/api/v1/rt/e2ee/keys/${safePathSegment(channel)}`),
+        wsTicket: (channel) => this.issueRealtimeWebSocketTicket(channel),
+        wsUrl: (channel, ticket) => this.getRealtimeWebSocketUrl(channel, ticket),
+        wsUrlWithTicket: (channel) => this.getRealtimeWebSocketUrlWithTicket(channel),
+        /**
+         * Listen on a channel over WebSocket. Reconnects with backoff (a fresh ticket each time) and
+         * hands you each message's payload. Call `close()` when done.
+         *
+         * ```ts
+         * const ch = sov.realtime.channel('book:42', { onMessage: (m) => console.log(m), onStatus: setStatus })
+         * await ch.send({ type: 'typing' })
+         * ch.close()
+         * ```
+         */
+        channel: (name, handlers = {}) => openRealtimeChannel(this, name, handlers),
+    };
+    policy = {
+        templates: () => this.request('GET', '/api/v1/policies/templates'),
+        list: () => this.request('GET', '/api/v1/policies/'),
+        get: (policyId) => this.request('GET', `/api/v1/policies/${safePathSegment(policyId)}`),
+        create: (payload) => this.request('POST', '/api/v1/policies/', {
+            body: payload,
+            requiresScope: false,
+        }),
+        update: (policyId, payload) => this.request('PUT', `/api/v1/policies/${safePathSegment(policyId)}`, {
+            body: payload,
+            requiresScope: false,
+        }),
+        delete: (policyId) => this.request('DELETE', `/api/v1/policies/${safePathSegment(policyId)}`, {
+            requiresScope: false,
+        }),
+        evaluate: (policyId, context) => this.request('POST', `/api/v1/policies/${safePathSegment(policyId)}/evaluate`, {
+            body: { context },
+            requiresScope: false,
+        }),
+        check: (payload) => this.request('POST', '/api/v1/policies/check', {
+            body: {
+                org_id: payload.orgId,
+                project_id: payload.projectId,
+                action: payload.action,
+                resource: payload.resource,
+                context: payload.context ?? {},
+            },
+            requiresScope: false,
+        }),
+        preflight: async (action, resource, context = {}) => {
+            await this.resolveScope();
+            this.assertScopePresent();
+            return this.policy.check({
+                orgId: this.scope.orgId,
+                projectId: this.scope.projectId,
+                action,
+                resource,
+                context,
+            });
+        },
+        history: (policyId) => this.request('GET', `/api/v1/policies/${safePathSegment(policyId)}/history`, {
+            requiresScope: false,
+        }),
+        rollback: (policyId, version) => this.request('POST', `/api/v1/policies/${safePathSegment(policyId)}/rollback`, {
+            body: { version },
+            requiresScope: false,
+        }),
+        simulate: (splSource, context = {}) => this.request('POST', '/api/v1/policies/simulate', {
+            body: { spl_source: splSource, context },
+            requiresScope: true,
+        }),
+    };
+    audit = {
+        append: (payload) => this.request('POST', '/api/v1/audit/', {
+            body: payload,
+        }),
+        list: (query) => this.request('GET', '/api/v1/audit/', { query }),
+        verify: () => this.request('GET', '/api/v1/audit/verify'),
+        count: () => this.request('GET', '/api/v1/audit/count'),
+    };
+    simulate = {
+        /**
+         * Who can do what in the live project, as visitors, the app's users and the team; nothing is
+         * written. Narrow with `{ filter: { resource, action, role } }` (role: `__guest__`,
+         * `__app_user__`, `app:<role>` or a team role).
+         */
+        run: async (payload = {}) => {
+            const filter = payload.filter;
+            if (filter && Object.keys(filter).length > 0) {
+                return this.request('POST', '/api/v1/sim/run', { body: payload, requiresScope: true });
+            }
+            // A full run takes longer than one request should wait: start it in the background, poll it.
+            let run = await this.request('POST', '/api/v1/sim/run', {
+                body: { ...payload, background: true }, requiresScope: true,
+            });
+            const deadline = Date.now() + 10 * 60_000;
+            while (run.status === 'running') {
+                if (Date.now() > deadline)
+                    throw new Error(`Simulation ${String(run.run_id)} is still running after 10 minutes`);
+                await sleep(2_000);
+                run = await this.request('GET', `/api/v1/sim/runs/${encodeURIComponent(String(run.run_id))}`, {
+                    requiresScope: true,
+                });
+            }
+            if (run.status === 'failed')
+                throw new Error(String(run.error ?? 'Simulation failed'));
+            return run;
+        },
+        /**
+         * Try a change before making it; nothing is written. `{ kind: 'policy', policy: { spl_source,
+         * name?, replaces? }, disable_policy_ids? }` lists who gains and loses access; `{ kind: 'sql',
+         * sql }` runs the script with every check, rolls it back and lists what it changed.
+         */
+        change: (payload) => this.request('POST', '/api/v1/sim/change', { body: payload, requiresScope: true }),
+        plan: (payload) => this.request('POST', '/api/v1/sim/plan', { body: payload }),
+        discover: () => this.request('POST', '/api/v1/sim/discover', { body: {}, requiresScope: true }),
+        listRuns: (query) => this.request('GET', '/api/v1/sim/runs', { query, requiresScope: true }),
+        getRun: (runId) => this.request('GET', `/api/v1/sim/runs/${safePathSegment(runId)}`, {
+            requiresScope: true,
+        }),
+        compareRuns: (targetRunId, baselineRunId) => this.request('GET', `/api/v1/sim/runs/${safePathSegment(targetRunId)}/compare/${safePathSegment(baselineRunId)}`, { requiresScope: true }),
+    };
+    chrono = {
+        /** The project's configuration (policies, schema, functions, settings, buckets, keys) at a commit or ISO time. */
+        state: (query = {}) => this.request('GET', '/api/v1/chrono/state', { query: { timeline: 'main', ...query }, requiresScope: true }),
+        /** What going back to `at` changes, file by file, with who would gain or lose access. Writes nothing. */
+        restorePlan: (at, timeline = 'main') => this.request('POST', '/api/v1/chrono/restore-plan', { body: { at, timeline }, requiresScope: true }),
+        /**
+         * Go back to `at`: applies the plan's automated changes with the caller's own permissions.
+         * `includeDatabase` also restores the database from the closest backup before `at` (replaces all
+         * data after a safety backup; undo within 7 days).
+         */
+        restore: (at, timeline = 'main', options = {}) => this.request('POST', '/api/v1/chrono/restore', {
+            body: { at, timeline, confirm: true, ...(options.includeDatabase ? { include_database: true } : {}) },
+            requiresScope: true,
+        }),
+        commit: (payload) => this.request('POST', '/api/v1/chrono/commit', { body: payload }),
+        timelineSpawn: (payload) => this.request('POST', '/api/v1/chrono/timelines/spawn', { body: payload }),
+        timelineList: () => this.request('GET', '/api/v1/chrono/timelines'),
+        timelineDelete: (name) => this.request('DELETE', `/api/v1/chrono/timelines/${safePathSegment(name)}`),
+        timelineJump: (name, targetHex) => this.request('POST', `/api/v1/chrono/timelines/${safePathSegment(name)}/jump`, {
+            body: { target_hex: targetHex },
+        }),
+        timelineHistory: (name, limit = 50, offset = 0) => this.request('GET', `/api/v1/chrono/timelines/${safePathSegment(name)}/history`, {
+            query: { limit, offset },
+        }),
+        topology: (timeline = 'main', limit = 50) => this.request('GET', '/api/v1/chrono/timelines/topology', {
+            query: { timeline, limit },
+        }),
+        converge: (payload) => this.request('POST', '/api/v1/chrono/timelines/converge', {
+            body: payload,
+        }),
+        variance: (payload) => this.request('POST', '/api/v1/chrono/variance', {
+            body: payload,
+        }),
+        snapshotCreate: (payload) => this.request('POST', '/api/v1/chrono/snapshots/create', {
+            body: payload,
+        }),
+        snapshotList: () => this.request('GET', '/api/v1/chrono/snapshots'),
+        snapshotRestore: (snapshotId) => this.request('POST', `/api/v1/chrono/snapshots/${snapshotId}/restore`),
+    };
+    functions = {
+        list: (options) => this.request('GET', '/api/v1/fn/functions', {
+            query: {
+                project_id: options.projectId,
+                limit: options.limit,
+                offset: options.offset,
+            },
+            requiresScope: false,
+        }),
+        /** Validate a bundle and get a signed plan bound to its exact bytes. */
+        plan: (bundle, name, projectId) => {
+            const form = new FormData();
+            form.append('bundle', bundle, 'bundle.zip');
+            form.append('name', name);
+            if (projectId) {
+                form.append('project_id', projectId);
+            }
+            return this.request('POST', '/api/v1/fn/plan', {
+                body: form,
+                requiresScope: false,
+            });
+        },
+        /** Plans, then applies exactly the planned bundle (Forge refuses anything else). */
+        deploy: async (bundle, name, projectId) => {
+            const plan = await this.functions.plan(bundle, name, projectId);
+            const token = typeof plan.token === 'string' ? plan.token : '';
+            const form = new FormData();
+            form.append('bundle', bundle, 'bundle.zip');
+            form.append('name', name);
+            if (projectId) {
+                form.append('project_id', projectId);
+            }
+            return this.request('POST', '/api/v1/fn/deploy', {
+                body: form,
+                headers: token ? { 'X-Sovaria-Deploy-Plan': token } : undefined,
+                requiresScope: false,
+            });
+        },
+        status: (deployId, projectId) => this.request('GET', `/api/v1/fn/${safePathSegment(deployId)}/status`, {
+            query: projectId ? { project_id: projectId } : undefined,
+            requiresScope: false,
+        }),
+        invoke: (functionName, payload, options) => this.request('POST', `/api/v1/fn/${safePathSegment(functionName)}/invoke`, {
+            body: payload,
+            query: options?.projectId || options?.deployId || options?.executionProfile
+                ? {
+                    project_id: options?.projectId,
+                    deploy_id: options?.deployId,
+                    execution_profile: options?.executionProfile,
+                }
+                : undefined,
+            requiresScope: false,
+        }),
+        /**
+         * Call a function the way an app does: POST {projectUrl}/functions/v1/{name} with the signed-in
+         * user's token (or no token for functions marked public). Returns the function's result.
+         */
+        call: (functionName, payload = {}) => this.request('POST', `/functions/v1/${safePathSegment(functionName)}`, { body: payload, requiresScope: false }),
+        simulate: (functionName, payload, options) => this.request('POST', `/api/v1/fn/${safePathSegment(functionName)}/simulate`, {
+            body: payload,
+            query: options?.projectId || options?.deployId || options?.executionProfile
+                ? {
+                    project_id: options?.projectId,
+                    deploy_id: options?.deployId,
+                    execution_profile: options?.executionProfile,
+                }
+                : undefined,
+            requiresScope: false,
+        }),
+        invokeAsync: (functionName, payload, options) => this.request('POST', `/api/v1/fn/${safePathSegment(functionName)}/invoke/async`, {
+            body: payload,
+            query: options?.projectId ||
+                options?.deployId ||
+                options?.executionProfile ||
+                options?.simulation !== undefined
+                ? {
+                    project_id: options?.projectId,
+                    deploy_id: options?.deployId,
+                    execution_profile: options?.executionProfile,
+                    simulation: options?.simulation,
+                }
+                : undefined,
+            requiresScope: false,
+        }),
+        invocationStatus: (invocationId, projectId) => this.request('GET', `/api/v1/fn/invocations/${safePathSegment(invocationId)}`, {
+            query: { project_id: projectId },
+            requiresScope: false,
+        }),
+        jobs: (functionName, options) => this.request('GET', `/api/v1/fn/${safePathSegment(functionName)}/jobs`, {
+            query: {
+                project_id: options.projectId,
+                status: options.status,
+                limit: options.limit,
+                offset: options.offset,
+            },
+            requiresScope: false,
+        }),
+        versions: (functionName, options) => this.request('GET', `/api/v1/fn/${safePathSegment(functionName)}/versions`, {
+            query: {
+                project_id: options.projectId,
+                limit: options.limit,
+                offset: options.offset,
+            },
+            requiresScope: false,
+        }),
+        history: (functionName, options) => this.request('GET', `/api/v1/fn/${safePathSegment(functionName)}/history/invocations`, {
+            query: {
+                project_id: options.projectId,
+                mode: options.mode,
+                limit: options.limit,
+                offset: options.offset,
+            },
+            requiresScope: false,
+        }),
+        simulationDiff: (functionName, options) => this.request('GET', `/api/v1/fn/${safePathSegment(functionName)}/history/simulation-diff`, {
+            query: {
+                project_id: options.projectId,
+                left_invocation_id: options.leftInvocationId,
+                right_invocation_id: options.rightInvocationId,
+            },
+            requiresScope: false,
+        }),
+        promote: (functionName, options) => {
+            if (options.version === undefined && !options.deployId) {
+                throw SovariaError.config('Provide either version or deployId for promote.');
+            }
+            return this.request('POST', `/api/v1/fn/${safePathSegment(functionName)}/promote`, {
+                query: {
+                    project_id: options.projectId,
+                },
+                body: {
+                    version: options.version,
+                    deploy_id: options.deployId,
+                    reason: options.reason ?? '',
+                },
+                requiresScope: false,
+            });
+        },
+        rollback: (functionName, options) => this.request('POST', `/api/v1/fn/${safePathSegment(functionName)}/rollback`, {
+            query: {
+                project_id: options.projectId,
+            },
+            body: {
+                version: options.version,
+                reason: options.reason ?? '',
+            },
+            requiresScope: false,
+        }),
+        request: (method, path, options = {}) => this.request(method, `/api/v1/fn/${normalizeSubpath(path)}`, {
+            ...options,
+            requiresScope: options.requiresScope ?? false,
+        }),
+        get: (name) => this.request('GET', `/api/v1/fn/functions/${safePathSegment(name)}`, {
+            requiresScope: true,
+        }),
+        getSource: (name) => this.request('GET', `/api/v1/fn/functions/${safePathSegment(name)}/source`, {
+            requiresScope: true,
+        }),
+        update: (name, body) => this.request('PATCH', `/api/v1/fn/functions/${safePathSegment(name)}`, {
+            body,
+            requiresScope: true,
+        }),
+        delete: (name) => this.request('DELETE', `/api/v1/fn/functions/${safePathSegment(name)}`, {
+            requiresScope: true,
+        }),
+        logs: (name, query) => this.request('GET', `/api/v1/fn/functions/${safePathSegment(name)}/logs`, {
+            query,
+            requiresScope: true,
+        }),
+        getPolicy: (name) => this.request('GET', `/api/v1/fn/functions/${safePathSegment(name)}/policy`, {
+            requiresScope: true,
+        }),
+        setPolicy: (name, body) => this.request('PUT', `/api/v1/fn/functions/${safePathSegment(name)}/policy`, {
+            body,
+            requiresScope: true,
+        }),
+        getBindings: (name) => this.request('GET', `/api/v1/fn/functions/${safePathSegment(name)}/bindings`, {
+            requiresScope: true,
+        }),
+        setBindings: (name, body) => this.request('PUT', `/api/v1/fn/functions/${safePathSegment(name)}/bindings`, {
+            body,
+            requiresScope: true,
+        }),
+        githubRepositories: (body) => this.request('POST', '/api/v1/fn/github/repositories', { body, requiresScope: true }),
+        githubImport: (body) => this.request('POST', '/api/v1/fn/github/import', { body, requiresScope: true }),
+        githubCommit: (body) => this.request('POST', '/api/v1/fn/github/commit', { body, requiresScope: true }),
+    };
+    storage = {
+        request: (method, path, options = {}) => this.request(method, `/api/v1/store/${normalizeSubpath(path)}`, {
+            ...options,
+            requiresScope: options.requiresScope ?? false,
+        }),
+        putJson: (path, payload) => this.request('POST', `/api/v1/store/${normalizeSubpath(path)}`, {
+            body: payload,
+            requiresScope: false,
+        }),
+        get: (path, query) => this.request('GET', `/api/v1/store/${normalizeSubpath(path)}`, {
+            query,
+            requiresScope: false,
+        }),
+        delete: (path) => this.request('DELETE', `/api/v1/store/${normalizeSubpath(path)}`, {
+            requiresScope: false,
+        }),
+        /** Public URL of an object in a public bucket (no token needed; safe to put in <img src>). */
+        publicUrl: (bucket, objectPath, projectId) => {
+            const pid = projectId ?? this.scope?.projectId;
+            if (!pid)
+                throw SovariaError.config('publicUrl() needs a projectId or setScope() first');
+            const path = objectPath.split('/').map((p) => encodeURIComponent(p)).join('/');
+            return `${this.baseUrl}/api/v1/store/public/${encodeURIComponent(pid)}/${encodeURIComponent(bucket)}/${path}`;
+        },
+        listBuckets: () => this.request('GET', '/api/v1/store/buckets', { requiresScope: true }),
+        createBucket: (body) => this.request('POST', '/api/v1/store/buckets', { body, requiresScope: true }),
+        getBucket: (name) => this.request('GET', `/api/v1/store/buckets/${safePathSegment(name)}`, {
+            requiresScope: true,
+        }),
+        updateBucket: (name, body) => this.request('PATCH', `/api/v1/store/buckets/${safePathSegment(name)}`, {
+            body,
+            requiresScope: true,
+        }),
+        deleteBucket: (name) => this.request('DELETE', `/api/v1/store/buckets/${safePathSegment(name)}`, {
+            requiresScope: true,
+        }),
+        listObjects: (bucket, query) => this.request('GET', `/api/v1/store/objects/${safePathSegment(bucket)}`, {
+            query,
+            requiresScope: true,
+        }),
+        signDownload: (bucket, objectPath, expiresIn = 3600) => this.request('POST', `/api/v1/store/objects/${safePathSegment(bucket)}/${objectPath
+            .split('/')
+            .map((p) => safePathSegment(p))
+            .join('/')}/sign-download`, { body: { expires_in: expiresIn }, requiresScope: true }),
+        /**
+         * Signed upload URL. Pass `sizeBytes` (the file's exact size) to get a direct-to-storage URL bound
+         * to that size; without it the URL uploads through Sovaria, which checks the size limits as the
+         * bytes arrive.
+         */
+        signUpload: (bucket, objectPath, expiresIn = 3600, options = {}) => this.request('POST', `/api/v1/store/objects/${safePathSegment(bucket)}/${objectPath
+            .split('/')
+            .map((p) => safePathSegment(p))
+            .join('/')}/sign-upload`, {
+            body: {
+                expires_in: expiresIn,
+                ...(options.sizeBytes !== undefined ? { size_bytes: options.sizeBytes } : {}),
+                ...(options.contentType ? { content_type: options.contentType } : {}),
+            },
+            requiresScope: true,
+        }),
+        moveObject: (body) => this.request('POST', '/api/v1/store/objects/move', { body, requiresScope: true }),
+        /**
+         * Upload a file. Bucket rules decide who may write where — e.g. with the "Own folder" rule a
+         * user writes to `${userId}/…`. Pass `upsert: true` to replace an existing object.
+         */
+        upload: (bucket, objectPath, file, options = {}) => {
+            const form = new FormData();
+            const name = objectPath.split('/').pop() || 'file';
+            // Without a type the server would store application/octet-stream; guess from the extension.
+            const type = options.contentType || file.type || guessContentType(name);
+            const blob = type && type !== file.type ? new Blob([file], { type }) : file;
+            form.append('file', blob, name);
+            return this.request('POST', `/api/v1/store/objects/${storageObjectPath(bucket, objectPath)}`, {
+                body: form,
+                query: options.upsert ? { upsert: true } : undefined,
+                requiresScope: true,
+            });
+        },
+        /** Download an object the caller may read, as a Blob. */
+        download: (bucket, objectPath) => this.request('GET', `/api/v1/store/objects/${storageObjectPath(bucket, objectPath)}`, {
+            requiresScope: true,
+            responseType: 'blob',
+        }),
+        /** Delete an object. */
+        remove: (bucket, objectPath) => this.request('DELETE', `/api/v1/store/objects/${storageObjectPath(bucket, objectPath)}`, {
+            requiresScope: true,
+        }),
+    };
+    system = {
+        enginesHealth: () => this.request('GET', '/api/v1/system/engines/health', {
+            requiresAuth: false,
+        }),
+    };
+    /**
+     * Billing + plan management (Ledger engine).
+     *
+     * The plan catalog is public; subscription and usage routes require a
+     * valid auth token. Subscription writes require the caller to be an
+     * org admin.
+     */
+    billing = {
+        listPlans: () => this.request('GET', '/api/v1/plans', { requiresAuth: false }),
+        getPlan: (name) => this.request('GET', `/api/v1/plans/${safePathSegment(name)}`, {
+            requiresAuth: false,
+        }),
+        getSubscription: (orgId) => this.request('GET', `/api/v1/subscriptions/${safePathSegment(orgId)}`, { requiresScope: false }),
+        setSubscription: (orgId, payload) => this.request('PUT', `/api/v1/subscriptions/${safePathSegment(orgId)}`, {
+            body: {
+                plan: payload.plan,
+                billing_cycle: payload.billingCycle ?? 'monthly',
+                ...(payload.stripeCustomerId
+                    ? { stripe_customer_id: payload.stripeCustomerId }
+                    : {}),
+                metadata: payload.metadata ?? {},
+            },
+            requiresScope: false,
+        }),
+        cancelSubscription: (orgId, options = {}) => this.request('DELETE', `/api/v1/subscriptions/${safePathSegment(orgId)}`, {
+            query: options.immediate ? { immediate: true } : undefined,
+            requiresScope: false,
+        }),
+        listSubscriptions: () => this.request('GET', '/api/v1/subscriptions', { requiresScope: false }),
+        getUsage: (orgId, period) => this.request('GET', `/api/v1/usage/${safePathSegment(orgId)}`, {
+            query: period ? { period } : undefined,
+            requiresScope: false,
+        }),
+        getUsageHistory: (orgId, months = 6) => this.request('GET', `/api/v1/usage/${safePathSegment(orgId)}/history`, {
+            query: { months },
+            requiresScope: false,
+        }),
+        listInvoices: (orgId) => this.request('GET', `/api/v1/invoices/${safePathSegment(orgId)}`),
+        buildInvoice: (orgId, period) => this.request('POST', `/api/v1/invoices/${safePathSegment(orgId)}/build`, {
+            query: period ? { period } : undefined,
+        }),
+        getCompute: (orgId, period) => this.request('GET', `/api/v1/compute/${safePathSegment(orgId)}`, {
+            query: period ? { period } : undefined,
+        }),
+        checkout: (body) => this.request('POST', '/api/v1/billing/checkout', { body }),
+        getProvider: () => this.request('GET', '/api/v1/billing/provider'),
+        getFx: () => this.request('GET', '/api/v1/billing/fx'),
+        getOverage: (orgId) => this.request('GET', `/api/v1/billing/overage/${safePathSegment(orgId)}`),
+        getOpenInvoice: () => this.request('GET', '/api/v1/billing/invoices/open'),
+        payInvoice: (orgId, period, body = {}) => this.request('POST', `/api/v1/billing/invoices/${safePathSegment(orgId)}/${safePathSegment(period)}/pay`, { body }),
+        razorpayCreateOrder: (body) => this.request('POST', '/api/v1/billing/razorpay/create-order', { body }),
+        razorpayVerifyPayment: (body) => this.request('POST', '/api/v1/billing/razorpay/verify-payment', { body }),
+        getAccount: (accountId) => this.request('GET', `/api/v1/accounts/${safePathSegment(accountId)}`),
+        cancelAccount: (accountId) => this.request('POST', `/api/v1/accounts/${safePathSegment(accountId)}/cancel`, {
+            body: {},
+        }),
+        resumeAccount: (accountId) => this.request('POST', `/api/v1/accounts/${safePathSegment(accountId)}/resume`, {
+            body: {},
+        }),
+    };
+    /** The complete API, generated from spec/sovaria-api.json (same surface in every SDK language). */
+    api = createGeneratedApi((method, path, options) => this.request(method, path, options), () => this.scope);
+    keys = createKeysApi(this.request.bind(this));
+    governance = createGovernanceApi(this.request.bind(this));
+    admin = createAdminApi(this.request.bind(this));
+    /**
+     * Vector / embeddings (Nexus engine).
+     *
+     * All routes are project-scoped via the standard `X-Sovaria-Project-ID`
+     * header so call `setScope({ orgId, projectId })` first.
+     */
+    vector = {
+        embed: (texts) => this.request('POST', '/api/v1/embed', { body: { texts } }),
+        upsert: (collection, docs) => this.request('POST', '/api/v1/vectors/upsert', {
+            body: { collection, docs },
+        }),
+        /**
+         * Search a collection. `mode`: `vector` (meaning), `keyword` (the words, BM25) or `hybrid` (both,
+         * fused); the default is vector with a real embedding model and hybrid with the local hash model.
+         * Apps (anon key, signed-in users) may only search collections opened with `setCollection(name, { appSearch: true })`.
+         */
+        search: (collection, query, options = {}) => this.request('POST', '/api/v1/vectors/search', {
+            body: {
+                collection,
+                query,
+                top_k: options.topK ?? 5,
+                metadata_filter: options.metadataFilter ?? {},
+                ...(options.mode ? { mode: options.mode } : {}),
+            },
+        }),
+        /** Collection settings (team / service key): `appSearch` lets the project's apps search it. */
+        setCollection: (collection, settings) => this.request('PATCH', `/api/v1/collections/${safePathSegment(collection)}`, {
+            body: { ...(settings.appSearch !== undefined ? { app_search: settings.appSearch } : {}) },
+        }),
+        listCollections: () => this.request('GET', '/api/v1/collections'),
+        listRecords: (collection, options = {}) => this.request('GET', `/api/v1/collections/${safePathSegment(collection)}/records`, {
+            query: {
+                limit: options.limit,
+                offset: options.offset,
+            },
+        }),
+        deleteRecord: (collection, recordId) => this.request('DELETE', `/api/v1/collections/${safePathSegment(collection)}/records/${safePathSegment(recordId)}`),
+        deleteCollection: (collection) => this.request('DELETE', `/api/v1/collections/${safePathSegment(collection)}`),
+    };
+}
+const CONTENT_TYPES = {
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', avif: 'image/avif',
+    svg: 'image/svg+xml', ico: 'image/x-icon', pdf: 'application/pdf', json: 'application/json', txt: 'text/plain',
+    csv: 'text/csv', md: 'text/markdown', html: 'text/html', css: 'text/css', js: 'text/javascript',
+    mp4: 'video/mp4', webm: 'video/webm', mp3: 'audio/mpeg', wav: 'audio/wav', zip: 'application/zip',
+};
+function guessContentType(name) {
+    const ext = name.includes('.') ? name.split('.').pop().toLowerCase() : '';
+    return CONTENT_TYPES[ext] ?? '';
+}
+function openRealtimeChannel(sdk, name, handlers) {
+    const WS = globalThis.WebSocket;
+    let status = 'connecting';
+    let socket = null;
+    let closed = false;
+    let attempt = 0;
+    let timer;
+    const setStatus = (next) => {
+        if (status === next)
+            return;
+        status = next;
+        handlers.onStatus?.(next);
+    };
+    const schedule = () => {
+        if (closed)
+            return;
+        setStatus('reconnecting');
+        const cap = handlers.maxBackoffMs ?? 15_000;
+        const delay = Math.min(cap, 500 * 2 ** Math.min(attempt, 6)) * (0.75 + Math.random() * 0.5);
+        attempt += 1;
+        timer = setTimeout(() => void connect(), delay);
+    };
+    const connect = async () => {
+        if (closed)
+            return;
+        if (!WS) {
+            handlers.onError?.(SovariaError.config('No WebSocket implementation available in this runtime.'));
+            setStatus('closed');
+            return;
+        }
+        try {
+            const url = await sdk.realtime.wsUrlWithTicket(name);
+            if (closed)
+                return;
+            const ws = new WS(url);
+            socket = ws;
+            ws.onopen = () => {
+                attempt = 0;
+                setStatus('live');
+            };
+            ws.onmessage = (event) => {
+                let frame;
+                try {
+                    frame = JSON.parse(String(event.data));
+                }
+                catch {
+                    return; // pings and other non-JSON frames
+                }
+                if (frame.type === 'ping' || frame.type === 'pong')
+                    return;
+                const payload = (frame.payload ?? frame.data ?? frame);
+                try {
+                    handlers.onMessage?.(payload, frame);
+                }
+                catch (error) {
+                    console.error('SovariaSDK: realtime onMessage handler failed', error);
+                }
+            };
+            ws.onclose = () => {
+                socket = null;
+                schedule();
+            };
+            ws.onerror = (error) => handlers.onError?.(error);
+        }
+        catch (error) {
+            handlers.onError?.(error);
+            // Signed out (session can't be refreshed) or no permission: retrying will not help, and
+            // every retry is a refused ticket request. A new sign-in opens channels again.
+            if (error instanceof SovariaError && (error.code === 'PERMISSION_DENIED' || error.code === 'CONFIG_ERROR' || error.code === 'UNAUTHENTICATED')) {
+                setStatus('closed');
+                return;
+            }
+            schedule();
+        }
+    };
+    handlers.onStatus?.('connecting');
+    void connect();
+    return {
+        name,
+        get status() {
+            return status;
+        },
+        send: (payload) => sdk.realtime.publish(name, payload),
+        close: () => {
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            const ws = socket;
+            socket = null;
+            ws?.close();
+            setStatus('closed');
+        },
+    };
+}
+/** Map sovaria.config.json content (written by `sov init` / `sov link`) to SDK bootstrap config. */
+export function portalConfigFromProjectFile(raw, options = {}) {
+    const ref = String(raw.project?.ref ?? '').trim();
+    const gatewayUrl = String(raw.gateway?.url ?? '').trim() || (ref ? `https://${ref}.sovarias.in` : '');
+    if (!gatewayUrl) {
+        throw SovariaError.config('Missing gateway.url in sovaria.config.json — run `sov link` in your app folder.');
+    }
+    const scope = raw.scope ?? {};
+    const env = globalThis.process?.env;
+    const accessToken = options.accessToken ??
+        options.access_token ??
+        env?.SOVARIA_ACCESS_TOKEN;
+    const publishableKey = options.publishableKey ??
+        options.publishable_key ??
+        options.anonKey ??
+        options.anon_key ??
+        env?.SOVARIA_PUBLISHABLE_KEY ??
+        env?.SOVARIA_ANON_KEY;
+    return {
+        ...options,
+        url: gatewayUrl,
+        orgId: String(options.orgId ?? scope.org_id ?? scope.orgId ?? '').trim(),
+        projectId: String(options.projectId ?? scope.project_id ?? scope.projectId ?? '').trim(),
+        envId: String(options.envId ?? scope.env_id ?? scope.envId ?? '').trim(),
+        accessToken: accessToken ? String(accessToken).trim() : undefined,
+        publishableKey: publishableKey ? String(publishableKey).trim() : undefined,
+    };
+}
+/**
+ * Create a client from sovaria.config.json. In a bundler, import the file and pass the anon key:
+ * `createClientFromProjectConfig(config, { publishableKey: import.meta.env.VITE_SOVARIA_ANON_KEY })`.
+ */
+export function createClientFromProjectConfig(raw, options = {}) {
+    return SovariaSDK.fromPortalConfig(portalConfigFromProjectFile(raw, options));
+}
+/**
+ * Create a client. Either pass the two values from the console's **Connect** panel —
+ * `createClient('https://<ref>.sovarias.in', '<anon-key>')` — or a config object.
+ */
+export function createClient(urlOrConfig, key, options = {}) {
+    if (typeof urlOrConfig === 'string') {
+        return SovariaSDK.fromPortalConfig({ ...options, url: urlOrConfig, ...(key ? { publishableKey: key } : {}) });
+    }
+    return SovariaSDK.fromPortalConfig(urlOrConfig);
+}
+/** A redirect into an app (custom scheme), which the server only accepts with PKCE. */
+function isAppRedirect(url) {
+    const match = /^([a-z][a-z0-9+.-]*):/i.exec((url ?? '').trim());
+    return !!match && !['http', 'https'].includes(match[1].toLowerCase());
+}
+function randomVerifier() {
+    const bytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(bytes);
+    return base64Url(bytes);
+}
+async function s256(verifier) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return base64Url(new Uint8Array(digest));
+}
+function base64Url(bytes) {
+    let bin = '';
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}