@sovaria/sdk 0.0.0-stage → 0.5.0

package/dist/index.js

@@ -0,0 +1,3018 @@
+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 { credentialToJSON, creationOptionsFromJSON, passkeysSupported, requestOptionsFromJSON } from './passkeys.js';
+export { base64urlToBuffer, bufferToBase64url, credentialToJSON, creationOptionsFromJSON, passkeysSupported, requestOptionsFromJSON } from './passkeys.js';
+import { DocumentReference, Query, WriteBatch, runTransaction as runDocumentTransaction, } from './collections.js';
+export { DocumentReference, FieldValue, LiveQuery, Query, Transaction, VectorQuery, WriteBatch, newDocumentId, splitTransforms, and, average, count, filter, or, sum, } from './collections.js';
+import { createOfflineTransport } from './offline.js';
+import { CrashReporter } from './crashes.js';
+export { CrashReporter, distinctId, parseStack } from './crashes.js';
+import { PerfMonitor } from './perf.js';
+export { PerfMonitor } from './perf.js';
+import { WebPushClient } from './webpush.js';
+import { InAppMessages } from './inapp.js';
+export { InAppMessages } from './inapp.js';
+export { WebPushClient, serviceWorkerSource, urlBase64ToUint8Array } from './webpush.js';
+import { Analytics } from './analytics.js';
+import { RemoteConfig } from './remote-config.js';
+export { Analytics } from './analytics.js';
+export { RemoteConfig } from './remote-config.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';
+/** Arguments as query-string values: objects and arrays as JSON, null left out. */
+function rpcQueryArgs(args) {
+    const out = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (value === null || value === undefined)
+            continue;
+        out[key] = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    }
+    return out;
+}
+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);
+    }
+    /**
+     * Every collection with this id at any depth (`comments`, `posts/p1/comments`, …), like Firestore's
+     * `collectionGroup`. Guard rules and row policies apply per matched collection; `onSnapshot` is a live listener on the whole group.
+     *
+     * ```ts
+     * const top = await sov.collectionGroup('comments').where('flagged', '==', true).orderBy('at', 'desc').get()
+     * ```
+     */
+    collectionGroup(collectionId) {
+        return new Query(this.documentsTransport(), collectionId, {}, true);
+    }
+    /** 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 }), (sessions) => this.request('POST', '/crashes/v1/sessions', { body: { sessions }, requiresScope: false }));
+    /**
+     * Client performance monitoring: `sov.perf.install({ release })` measures web vitals (LCP, INP, CLS, FCP, TTFB)
+     * and every Sovaria request (joined to the server trace by its `traceparent`); `sov.perf.trace(name, fn)` times
+     * your own steps. Results are in the console under Observability › Performance.
+     */
+    perf = new PerfMonitor((events) => this.request('POST', '/perf/v1/events', { body: { events }, requiresScope: false }), () => this.crashes.sessionId);
+    /** Web push for browsers with the project's own VAPID keys: `await sov.push.register()` after sign-in. */
+    push = new WebPushClient((method, path, options) => this.request(method, path, options));
+    /** In-app messages (fetch what to show, report impressions / clicks / dismissals) and push open tracking. */
+    inApp = new InAppMessages((method, path, options) => this.request(method, path, options));
+    /**
+     * Product analytics: `sov.analytics.track(name, props)`, `screen(name)`, `identify(userProps)`,
+     * `setEnabled(false)` for an opt-out. Batched, offline-safe; reports in the console under Analytics.
+     */
+    analytics = new Analytics((body) => this.request('POST', '/analytics/v1/events', { body, requiresScope: false,
+        headers: { 'X-Sovaria-Device-ID': this.analytics.anonId } }), (granted, anonId, erase) => this.request('PUT', '/analytics/v1/consent', { body: { granted, anon_id: anonId, erase },
+        requiresScope: false }));
+    /**
+     * Remote config and feature flags: `setDefaults`, `fetchAndActivate()`, `getBool/getString/getNumber/getJson`,
+     * `onUpdate(cb)` (live after a publish). Values are evaluated on the server for this user.
+     */
+    config = new RemoteConfig(async (query, etag) => {
+        try {
+            const body = await this.request('GET', '/config/v1/fetch', { query, requiresScope: false,
+                headers: { 'X-Sovaria-Device-ID': this.analytics.anonId, ...(etag ? { 'If-None-Match': `"${etag}"` } : {}) } });
+            return { status: 200, body };
+        }
+        catch (error) {
+            if (error instanceof SovariaError && error.statusCode === 304)
+                return { status: 304 };
+            throw error;
+        }
+    }, this.analytics, (channel, onMessage) => openRealtimeChannel(this, channel, { onMessage: () => onMessage() }));
+    async request(method, path, options = {}) {
+        if (path.startsWith('/crashes/v1') || path.startsWith('/perf/v1') || path.startsWith('/analytics/v1') || path.startsWith('/config/v1')) {
+            return this.requestImpl(method, path, options);
+        }
+        let status = 0;
+        const timed = this.perf.timesNetwork;
+        let traceId;
+        const started = timed ? (globalThis.performance?.now?.() ?? Date.now()) : 0;
+        if (timed && !Object.keys(options.headers ?? {}).some((k) => k.toLowerCase() === 'traceparent')) {
+            // The span and the request share one W3C trace id, so the console can open the server trace for it.
+            traceId = newTraceId();
+            options = { ...options, headers: { ...(options.headers ?? {}), traceparent: traceparentFor(traceId) } };
+        }
+        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'}` });
+            if (timed) {
+                this.perf.network(method, path, status, (globalThis.performance?.now?.() ?? Date.now()) - started, traceId);
+            }
+        }
+    }
+    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;
+        // FormData and raw bytes (Blob, ArrayBuffer, typed arrays) go as they are; anything else is JSON.
+        const rawBody = hasBody && (options.body instanceof FormData || (typeof Blob !== 'undefined' && options.body instanceof Blob)
+            || options.body instanceof ArrayBuffer || ArrayBuffer.isView(options.body));
+        if (hasBody && !rawBody && !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
+                        ? rawBody
+                            ? 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' || type === 'link') {
+                // `link` is a linkIdentity return; it completes through the same PKCE code exchange as `sso`, which
+                // binds the completion to this browser's verifier (the one that started the link).
+                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 };
+        },
+        /**
+         * Enterprise SAML single sign-on for your app's users (connections in Authentication › SAML SSO, Team plan).
+         * Pass the user's work `email` (or its `domain`) to find their company's identity provider, or a
+         * `connectionId`. The browser goes to the IdP and comes back like `signInWithProvider()`:
+         * `?code=…&type=sso`, which `exchangeCodeForSession()` turns into a session.
+         */
+        signInWithSSO: async (opts) => {
+            const projectId = opts.projectId ?? (await this.resolveScope())?.projectId;
+            if (!projectId)
+                throw SovariaError.config('signInWithSSO() needs a project id (use the project URL or setScope first).');
+            let connectionId = opts.connectionId;
+            if (!connectionId) {
+                const address = opts.email ?? (opts.domain ? `user@${opts.domain}` : '');
+                if (!address)
+                    throw SovariaError.config('signInWithSSO() needs an email, a domain or a connectionId.');
+                const q = new URLSearchParams({ project_id: projectId, email: address });
+                const found = await this.request('GET', `/api/v1/auth/sso/saml/lookup?${q}`, { requiresAuth: false });
+                connectionId = String(found.connection_id ?? '');
+            }
+            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 with the in-memory verifier */
+            }
+            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/saml/${encodeURIComponent(connectionId)}/authorize?${params}`, { requiresAuth: false });
+            const url = String(res.authorization_url ?? '');
+            if (typeof window !== 'undefined' && url)
+                window.location.assign(url);
+            return { url, connectionId };
+        },
+        /** 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);
+        },
+        /**
+         * Link another sign-in method (Google/GitHub/SAML…) to the SIGNED-IN user (Supabase `linkIdentity`).
+         * Sends the browser to the provider; it returns to `redirectTo` (or your Site URL) with `?code=…&type=link`,
+         * which `handleEmailLink()` / `exchangeCodeForSession()` complete. The completion is bound to THIS browser by
+         * a PKCE verifier kept in sessionStorage, so a forwarded link can't attach someone else's identity to your
+         * account. An anonymous user who links a verified provider becomes permanent.
+         */
+        linkIdentity: async (providerId, opts = {}) => {
+            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 with the in-memory verifier */
+            }
+            const params = new URLSearchParams({
+                provider: providerId,
+                code_challenge: challenge,
+                code_challenge_method: 'S256',
+                skip_http_redirect: 'true',
+            });
+            if (opts.redirectTo)
+                params.set('redirect_to', opts.redirectTo);
+            const res = await this.request('GET', `/api/v1/auth/me/identities/authorize?${params}`);
+            const url = String(res.url ?? '');
+            if (typeof window !== 'undefined' && url)
+                window.location.assign(url);
+            return { url };
+        },
+        /** The sign-in methods linked to the signed-in user (email, google, saml:…, passkey). */
+        getUserIdentities: async () => this.request('GET', '/api/v1/auth/me/identities'),
+        /** Remove a linked sign-in method (never the last one). Pass a recent-auth `nonce` if the project requires it. */
+        unlinkIdentity: async (identityId, opts = {}) => {
+            const q = opts.nonce ? `?nonce=${encodeURIComponent(opts.nonce)}` : '';
+            return this.request('DELETE', `/api/v1/auth/me/identities/${encodeURIComponent(identityId)}${q}`);
+        },
+        /** 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 }),
+        },
+        /**
+         * Blocking hooks (before-create, before-sign-in): a webhook or one of the project's functions that can
+         * refuse a sign-up / sign-in or add custom claims. Project owners and admins; plan key `auth.blocking_hooks`.
+         * `set` returns the signing secret once (`secret`) when it is created or `rotateSecret` is true.
+         */
+        blockingHooks: {
+            get: () => this.request('GET', '/api/v1/auth/blocking-hooks', { requiresScope: false }),
+            set: (event, hook) => this.request('PUT', `/api/v1/auth/blocking-hooks/${event.replace(/_/g, '-')}`, {
+                body: {
+                    target: hook.target ?? (hook.function ? 'function' : 'webhook'),
+                    url: hook.url ?? null,
+                    function: hook.function ?? null,
+                    ...(hook.timeoutMs !== undefined ? { timeout_ms: hook.timeoutMs } : {}),
+                    fail: hook.fail ?? 'closed',
+                    enabled: hook.enabled ?? true,
+                    rotate_secret: hook.rotateSecret ?? false,
+                },
+                requiresScope: false,
+            }),
+            delete: (event) => this.request('DELETE', `/api/v1/auth/blocking-hooks/${event.replace(/_/g, '-')}`, { requiresScope: false }),
+            /** Send a sample event and get the hook's decision (`allowed`, `claims`, `message`, `failed`, `error`, `latency_ms`). */
+            test: (event, sample = {}) => this.request('POST', `/api/v1/auth/blocking-hooks/${event.replace(/_/g, '-')}/test`, {
+                body: sample,
+                requiresScope: false,
+            }),
+        },
+        /**
+         * SCIM 2.0 provisioning of the project's app users and groups (Okta, Entra ID …). `createToken` turns it on or
+         * rotates the token (the old one stops at once) and returns it once with the `base_url` for the identity
+         * provider. Plan key `auth.scim`.
+         */
+        scim: {
+            status: () => this.request('GET', '/api/v1/auth/scim', { requiresScope: false }),
+            createToken: () => this.request('POST', '/api/v1/auth/scim/token', { body: {}, requiresScope: false }),
+            revokeToken: () => this.request('DELETE', '/api/v1/auth/scim/token', { 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 }),
+        },
+        /**
+         * Passkeys (WebAuthn): add one for the signed-in user, sign in with one, list and remove them.
+         * The project must have passkeys set up (Users › Passkeys). `register()` and `signIn()` run the
+         * browser ceremony; on other platforms use the `start…` / `finish…` calls with your own WebAuthn API.
+         *
+         * ```ts
+         * await sov.auth.passkeys.register('MacBook')          // signed in: Touch ID creates a passkey
+         * const session = await sov.auth.passkeys.signIn()     // later: sign in with it, no email needed
+         * ```
+         */
+        passkeys: {
+            /** True when this browser can create and use passkeys. */
+            isSupported: () => passkeysSupported(),
+            /** Registration options for the signed-in user (their existing passkeys are excluded). */
+            startRegistration: (name = 'Passkey') => this.request('POST', '/api/v1/auth/passkeys/register/start', { body: { name } }),
+            /** Save the credential the authenticator created (`credential` is WebAuthn JSON). */
+            finishRegistration: (credential, name = 'Passkey') => this.request('POST', '/api/v1/auth/passkeys/register/finish', { body: { credential, name } }),
+            /** Create a passkey for the signed-in user with the browser's WebAuthn API and save it. */
+            register: async (name = 'Passkey') => {
+                if (!passkeysSupported())
+                    throw SovariaError.config('Passkeys need a browser with WebAuthn (navigator.credentials).');
+                const start = await this.auth.passkeys.startRegistration(name);
+                const created = await globalThis.navigator.credentials.create({ publicKey: creationOptionsFromJSON((start.options ?? start)) });
+                if (!created)
+                    throw SovariaError.config('No passkey was created.');
+                return this.auth.passkeys.finishRegistration(credentialToJSON(created), name);
+            },
+            /** Sign-in options: `{ challenge_id, options }`. Pass `userId` to offer only that user's passkeys. */
+            startSignIn: async (opts = {}) => {
+                await this.resolveScope();
+                return this.request('POST', '/api/v1/auth/passkeys/authenticate/start', {
+                    requiresAuth: false,
+                    body: opts.userId ? { user_id: opts.userId } : {},
+                });
+            },
+            /** Verify the signed challenge and sign the user in (the session is kept and refreshed like any sign-in). */
+            finishSignIn: async (challengeId, credential) => {
+                const tokens = await this.request('POST', '/api/v1/auth/passkeys/authenticate/finish', {
+                    requiresAuth: false,
+                    body: { challenge_id: challengeId, credential },
+                });
+                return this.applyAuthResponse(tokens);
+            },
+            /** Sign in with a passkey using the browser's WebAuthn API. Resolves to the session tokens (`aal` says if it was two-factor). */
+            signIn: async (opts = {}) => {
+                if (!passkeysSupported())
+                    throw SovariaError.config('Passkeys need a browser with WebAuthn (navigator.credentials).');
+                const start = await this.auth.passkeys.startSignIn(opts);
+                const asserted = await globalThis.navigator.credentials.get({ publicKey: requestOptionsFromJSON(start.options) });
+                if (!asserted)
+                    throw SovariaError.config('No passkey was chosen.');
+                return this.auth.passkeys.finishSignIn(String(start.challenge_id), credentialToJSON(asserted));
+            },
+            /** The signed-in user's passkeys: id, name, created_at, last_used_at. */
+            list: () => this.request('GET', '/api/v1/auth/passkeys'),
+            /** Remove one of the signed-in user's passkeys. */
+            remove: (passkeyId) => this.request('DELETE', `/api/v1/auth/passkeys/${safePathSegment(passkeyId)}`),
+        },
+        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 = {
+        /**
+         * Create an org, project or environment node. For a PROJECT, `options.databasePassword` sets the
+         * project's database password (12–72 characters, letters, numbers and symbols; no spaces, quotes,
+         * backslashes or backticks). Without it the database gets a random password you can change later.
+         */
+        createNode: (nodeType, name, metadata = {}, options = {}) => this.request('POST', '/api/v1/org', {
+            body: {
+                type: nodeType,
+                name,
+                metadata,
+                ...(options.databasePassword ? { database_password: options.databasePassword } : {}),
+            },
+        }),
+        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).
+         *
+         * `{ readOnly: true }` runs it in a read-only transaction (the server refuses writes, including
+         * through functions). The answer has `truncated: true` when it was cut at your plan's `sql.max_rows`.
+         */
+        sql: (sql, params, txid = 0, opts) => {
+            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 } : {}),
+                    ...(opts?.readOnly ? { read_only: true } : {}),
+                },
+            });
+        },
+        /**
+         * Call one of your Postgres functions: `POST /rest/v1/rpc/{name}` with the arguments by name.
+         * A function that returns one value resolves to that value; one that returns rows resolves to
+         * an array of objects. App users need an access policy that allows `fn:<name>`. When the function
+         * raises an error, the SovariaError's `detail` holds the database's `code` and `message` (and
+         * `technicalMessage` repeats it for logs); `message` stays one you can show users.
+         *
+         *     const n = await sovaria.data.rpc<number>('post_count', { u: userId })
+         *     const top = await sovaria.data.rpc('top_posts', { days: 7 }, { get: true, query: { limit: 10 } })
+         */
+        rpc: (name, args = {}, options = {}) => {
+            if (!name?.trim())
+                throw SovariaError.config('rpc() needs a function name');
+            return this.request(options.get ? 'GET' : 'POST', `/rest/v1/rpc/${safePathSegment(name.trim())}`, {
+                body: options.get ? undefined : args,
+                query: options.get ? { ...rpcQueryArgs(args), ...(options.query ?? {}) } : options.query,
+                requiresScope: false,
+            });
+        },
+        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. Pass `{ manifest_id }` from `discover()` to skip discovery (manifest content is never
+         * accepted). Narrow with `{ filter: { resource, action, role } }` (role: `__guest__`,
+         * `__app_user__`, `app:<role>` or a team role): up to 25 request types is a single-request check
+         * that doesn't use the allowance; a wider filter is charged as a full run. One full run at a time
+         * per organization (409 `SIMULATION_RUN_IN_PROGRESS`).
+         */
+        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 }),
+        /** Real runs used and allowed today (UTC) and this month: `{ day: {used, limit, resets_at}, month: {…} }`. */
+        quota: () => this.request('GET', '/api/v1/sim/quota', { requiresScope: true }),
+        /** Outcomes the team marked as intended (shown green on every run, left out of findings). */
+        listIntended: () => this.request('GET', '/api/v1/sim/intended', { requiresScope: true }),
+        /** Mark an outcome as intended, e.g. `{ role: '__guest__', action: 'sql:select', resource: 'public.products',
+         *  outcome: 'ALLOW', note: 'The catalogue is public' }`. Needs policies.write. */
+        markIntended: (mark) => this.request('POST', '/api/v1/sim/intended', { body: mark, requiresScope: true }),
+        /** Remove a mark; matching cases show as measured again. */
+        unmarkIntended: (markId) => this.request('DELETE', `/api/v1/sim/intended/${safePathSegment(markId)}`, { requiresScope: true }),
+        /** Callers, gateway checks, sign-in, resources and connectors (platform defences as "Platform protection"). */
+        topology: () => this.request('GET', '/api/v1/sim/topology', { requiresScope: true }),
+        /** Everything the project has, read from every engine (every schema it created, collections, buckets, secret names,
+         *  functions with schedules, queues, workflows and triggers, sign-in, webhooks, channels, edge limits, backups,
+         *  environments, domains, policies, plan headroom). */
+        inventory: (params = {}) => this.request('GET', '/api/v1/sim/inventory', {
+            query: { include: params.include, fresh: params.fresh ? 'true' : undefined }, requiresScope: true
+        }),
+        /** What is wrong or at risk, worst first, each with a fix. `severity` keeps that level and worse. */
+        checks: (params = {}) => this.request('GET', '/api/v1/sim/checks', {
+            query: { severity: params.severity, area: params.area, fresh: params.fresh ? 'true' : undefined }, requiresScope: true
+        }),
+        /** The architecture map: nodes by layer with their status, and the edges between them. */
+        graph: (params = {}) => this.request('GET', '/api/v1/sim/graph', { query: { fresh: params.fresh ? 'true' : undefined }, requiresScope: true }),
+        /** Every limit the project lives under, with its value and how it is counted. */
+        limits: () => this.request('GET', '/api/v1/sim/limits', { requiresScope: true }),
+        /** One integration flow under a programmed outcome. `modelled` is free and sends nothing; `sealed` runs the
+         *  real code path to the send point and returns the recording (one single-request check). */
+        integrationRun: (body) => this.request('POST', '/api/v1/sim/integrations/run', { body, requiresScope: true }),
+        /** The 14 security drills judged from the project's configuration, with an optional what-if draft (never saved). */
+        drillsRun: (body = {}) => this.request('POST', '/api/v1/sim/drills/run', { body, requiresScope: true }),
+        /** What a run's sealed send points would have sent. */
+        runArtifacts: (runId) => this.request('GET', `/api/v1/sim/runs/${safePathSegment(runId)}/artifacts`, { 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` on a branch changes, file by file, with who would gain or lose access. Writes nothing.
+         * The branch decides the environment acted on (main = production); `envId` is the one you have checked out
+         * ('' = production) and a mismatch is refused (ENV_MISMATCH).
+         */
+        restorePlan: (at, timeline = 'main', options = {}) => this.request('POST', '/api/v1/chrono/restore-plan', {
+            body: { at, timeline, ...(options.envId !== undefined ? { env_id: options.envId } : {}) },
+            requiresScope: true,
+        }),
+        /**
+         * Go back to `at` on a branch: applies the plan's automated changes with the caller's own permissions, in that
+         * branch's own environment. `includeSchema` also rolls back the migrations applied since then; `includeDatabase`
+         * also restores the database as of then (production: the closest backup; an environment: point-in-time).
+         * The answer has `new_head`, or `recording: true` while the new commits are still arriving.
+         */
+        restore: (at, timeline = 'main', options = {}) => this.request('POST', '/api/v1/chrono/restore', {
+            body: {
+                at, timeline, confirm: true,
+                ...(options.includeDatabase ? { include_database: true } : {}),
+                ...(options.includeSchema ? { include_schema: true } : {}),
+                ...(options.envId !== undefined ? { env_id: options.envId } : {}),
+            },
+            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 }),
+        /**
+         * Call an HTTP function like `fetch`: any method, a sub-path, headers, a raw body (string, bytes, FormData…),
+         * and the function's own Response back (status, headers, binary body). Sends the signed-in user's token
+         * when there is one (none for public functions).
+         *
+         *     const res = await sovaria.functions.fetch('api', 'users/42', { method: 'PUT', body: JSON.stringify(user) })
+         *     if (res.status === 201) console.log(await res.json())
+         */
+        fetch: async (functionName, path = '', init = {}) => {
+            const sub = path.replace(/^\/+/, '');
+            if (sub.split('/').includes('..'))
+                throw SovariaError.config('Function paths cannot contain ..', 400);
+            const query = init.query ? `?${new URLSearchParams(init.query).toString()}` : '';
+            const url = `${this.baseUrl}/functions/v1/${safePathSegment(functionName)}${sub ? `/${sub}` : ''}${query}`;
+            if (this.accessToken)
+                await this.ensureAccessTokenFresh();
+            const headers = {
+                ...(await this.clientHeaders()),
+                ...(init.headers ?? {}),
+                ...(this.accessToken ? { Authorization: `Bearer ${this.accessToken}` } : {}),
+            };
+            return this.fetchImpl(url, { method: (init.method ?? 'GET').toUpperCase(), headers, body: init.body ?? undefined });
+        },
+        /** Make a function an HTTP function (Request in, Response out) or a JSON one again. */
+        setHttp: (functionName, http) => this.request('PUT', `/api/v1/fn/functions/${safePathSegment(functionName)}/http`, { body: { http } }),
+        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 }),
+    };
+    /**
+     * Web hosting (Sites): static builds served on `<site>.sovaria.app` and your own domains. Deploys are
+     * immutable and content-addressed (only new files are uploaded); a release switches the whole site at once.
+     *
+     *     await sovaria.hosting.createSite('my-app')
+     *     const { release } = await sovaria.hosting.deployFiles('my-app', { '/index.html': '<h1>Hi</h1>' }, { config: { spa: true } })
+     *     console.log(release.url)   // https://my-app.sovaria.app
+     */
+    hosting = {
+        config: () => this.request('GET', '/api/v1/fn/hosting/config'),
+        sites: () => this.request('GET', '/api/v1/fn/hosting/sites'),
+        createSite: (name) => this.request('POST', '/api/v1/fn/hosting/sites', { body: { name } }),
+        site: (site) => this.request('GET', `/api/v1/fn/hosting/sites/${safePathSegment(site)}`),
+        deleteSite: (site) => this.request('DELETE', `/api/v1/fn/hosting/sites/${safePathSegment(site)}`),
+        deploys: (site) => this.request('GET', `/api/v1/fn/hosting/sites/${safePathSegment(site)}/deploys`),
+        releases: (site, channel) => this.request('GET', `/api/v1/fn/hosting/sites/${safePathSegment(site)}/releases`, {
+            query: channel ? { channel } : undefined,
+        }),
+        rollback: (site, options = {}) => this.request('POST', `/api/v1/fn/hosting/sites/${safePathSegment(site)}/rollback`, {
+            body: { channel: options.channel ?? 'live', ...(options.deployId ? { deploy_id: options.deployId } : {}) },
+        }),
+        channels: (site) => this.request('GET', `/api/v1/fn/hosting/sites/${safePathSegment(site)}/channels`),
+        releaseToChannel: (site, channel, deployId, expiresDays) => this.request('POST', `/api/v1/fn/hosting/sites/${safePathSegment(site)}/channels/${safePathSegment(channel)}`, {
+            body: { deploy_id: deployId, ...(expiresDays ? { expires_days: expiresDays } : {}) },
+        }),
+        deleteChannel: (site, channel) => this.request('DELETE', `/api/v1/fn/hosting/sites/${safePathSegment(site)}/channels/${safePathSegment(channel)}`),
+        /**
+         * Deploy files (path → contents) and release them: hashes each file, uploads only the ones the project
+         * doesn't have, then switches the channel (`live` by default) to the new deploy in one step.
+         */
+        deployFiles: async (site, files, options = {}) => {
+            const bytes = {};
+            for (const [path, value] of Object.entries(files)) {
+                bytes[path.startsWith('/') ? path : `/${path}`] =
+                    typeof value === 'string' ? new TextEncoder().encode(value)
+                        : value instanceof Uint8Array ? value
+                            : value instanceof ArrayBuffer ? new Uint8Array(value)
+                                : new Uint8Array(await value.arrayBuffer());
+            }
+            const listing = {};
+            const byHash = {};
+            for (const [path, data] of Object.entries(bytes)) {
+                const digest = await globalThis.crypto.subtle.digest('SHA-256', data);
+                const sha = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, '0')).join('');
+                listing[path] = { sha256: sha, size: data.byteLength };
+                byHash[sha] = data;
+            }
+            const base = `/api/v1/fn/hosting/sites/${safePathSegment(site)}/deploys`;
+            const created = await this.request('POST', base, {
+                body: { files: listing, config: options.config ?? {}, message: options.message ?? '' },
+            });
+            for (const sha of created.missing ?? []) {
+                await this.request('PUT', `${base}/${created.deploy_id}/files/${sha}`, {
+                    body: byHash[sha],
+                    headers: { 'Content-Type': 'application/octet-stream' },
+                });
+            }
+            return this.request('POST', `${base}/${created.deploy_id}/finalize`, {
+                body: {
+                    release: options.release ?? true,
+                    channel: options.channel ?? 'live',
+                    ...(options.expiresDays ? { expires_days: options.expiresDays } : {}),
+                },
+            });
+        },
+    };
+    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,
+        }),
+    };
+    /**
+     * Compliance center (organization owners and admins): the evidence pack for your own audits. It is evidence of
+     * how Sovaria is configured for your organization, not a certification.
+     */
+    compliance = {
+        /** Audit-log check, encryption and own-key status, data regions, per-project backups/PITR/Security Advisor, access. */
+        overview: (orgId, options = {}) => this.request('GET', `/api/v1/org/${safePathSegment(this.complianceOrg(orgId))}/compliance`, {
+            query: options.projectId ? { project_id: options.projectId } : undefined,
+        }),
+        /** The evidence pack as a ZIP Blob (MANIFEST.json holds every file's SHA-256). Counted per day; audited. */
+        downloadEvidence: (orgId, options = {}) => this.request('GET', `/api/v1/org/${safePathSegment(this.complianceOrg(orgId))}/compliance/evidence`, {
+            query: options.projectId ? { project_id: options.projectId } : undefined,
+            responseType: 'blob',
+        }),
+    };
+    complianceOrg(orgId) {
+        const org = String(orgId ?? this.scope?.orgId ?? '').trim();
+        if (!org)
+            throw SovariaError.config('Pass an organization id or call setScope({ orgId, projectId }) first.');
+        return org;
+    }
+    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: {},
+        }),
+        /** Add-ons on the billing account (price, paid units, what renews, paid-through) and the autopay mandate. */
+        listAddons: (accountId) => this.request('GET', `/api/v1/accounts/${safePathSegment(accountId)}/addons`),
+        /**
+         * Start paying for `quantity` more units of an add-on (`extra_project`, `custom_domains`,
+         * `extra_environment`), prorated to the period end. Returns a Razorpay order to open in Checkout;
+         * the units count once the payment is verified (`razorpayVerifyPayment`). Uses the scoped org.
+         */
+        addonCheckout: (accountId, addonId, quantity = 1, projectId) => this.request('POST', `/api/v1/accounts/${safePathSegment(accountId)}/addons/${safePathSegment(addonId)}/checkout`, { body: projectId ? { quantity, project_id: projectId } : { quantity } }),
+        /** How many units renew at the period end (0 cancels). Units already paid for keep working until then. */
+        setAddonRenewal: (accountId, addonId, renewQuantity) => this.request('PUT', `/api/v1/accounts/${safePathSegment(accountId)}/addons/${safePathSegment(addonId)}/renewal`, { body: { renew_quantity: renewQuantity } }),
+        /** ₹1 (refunded) authorisation that saves a card or UPI mandate; open it in Checkout with `recurring: '1'`. */
+        autopaySetup: (accountId, body = {}) => this.request('POST', `/api/v1/accounts/${safePathSegment(accountId)}/autopay/setup`, { body }),
+        /** Remove the saved mandate; renewals become invoices to pay by hand. */
+        removeAutopayMandate: (accountId) => this.request('DELETE', `/api/v1/accounts/${safePathSegment(accountId)}/autopay/mandate`),
+    };
+    /** 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). `embed` works anywhere (in functions too, with the service key).
+     *
+     * **Collections are the legacy vector store** (capped at `ai.collection_max_records` per collection). For
+     * large or row-secured data use SQL vectors (`sov.api.vector.sqlSearch`, `sqlCreateIndex`, automatic
+     * embeddings) or knowledge bases (`sov.knowledge`).
+     *
+     * 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)}`),
+    };
+    /**
+     * Knowledge bases (RAG) on the project's own Postgres: add documents (text, files, web pages), then search
+     * them with citations. Searches only return passages the signed-in user may read.
+     *
+     * ```ts
+     * await sov.knowledge.addFile('support_docs', file)            // a File / Blob in the browser
+     * const { results, citations } = await sov.knowledge.search('support_docs', 'refund window')
+     * ```
+     */
+    knowledge = {
+        list: () => this.request('GET', KNOWLEDGE_PATH),
+        create: (name, options = {}) => this.request('POST', KNOWLEDGE_PATH, {
+            body: {
+                name,
+                ...(options.description !== undefined ? { description: options.description } : {}),
+                ...(options.access ? { access: options.access } : {}),
+                ...(options.userUploads !== undefined ? { user_uploads: options.userUploads } : {}),
+                ...(options.chunkTokens ? { chunk_tokens: options.chunkTokens } : {}),
+            },
+        }),
+        addText: (name, text, options = {}) => this.request('POST', `${KNOWLEDGE_PATH}/${safePathSegment(name)}/documents`, {
+            body: { text, format: options.format ?? 'markdown', ...knowledgeDocumentBody(options) },
+        }),
+        /** A web page. `refreshHours` (team, paid plans) fetches it again on a schedule; only changed parts are re-embedded. */
+        addUrl: (name, url, options = {}) => this.request('POST', `${KNOWLEDGE_PATH}/${safePathSegment(name)}/documents`, {
+            body: { url, ...knowledgeDocumentBody(options), ...(options.refreshHours ? { refresh_hours: options.refreshHours } : {}) },
+        }),
+        /** URL documents fetched again on a schedule (team). */
+        sources: (name) => this.request('GET', `${KNOWLEDGE_PATH}/${safePathSegment(name)}/sources`),
+        /** A PDF, DOCX, HTML, Markdown, TXT, CSV or JSON file (up to 7 MB): a `File`/`Blob`, or bytes with `filename`. */
+        addFile: async (name, file, options = {}) => {
+            const named = file.name;
+            const filename = options.filename ?? (typeof named === 'string' ? named : '');
+            if (!filename)
+                throw SovariaError.config('Give the file name (options.filename) so its format is known');
+            const bytes = file instanceof Uint8Array ? file
+                : file instanceof ArrayBuffer ? new Uint8Array(file)
+                    : new Uint8Array(await file.arrayBuffer());
+            return this.request('POST', `${KNOWLEDGE_PATH}/${safePathSegment(name)}/documents`, {
+                body: {
+                    content_base64: bytesToBase64(bytes), filename,
+                    ...(file.type ? { content_type: file.type } : {}),
+                    ...knowledgeDocumentBody(options),
+                },
+            });
+        },
+        documents: (name, options = {}) => this.request('GET', `${KNOWLEDGE_PATH}/${safePathSegment(name)}/documents`, {
+            query: { limit: options.limit, offset: options.offset },
+        }),
+        deleteDocument: (name, documentId) => this.request('DELETE', `${KNOWLEDGE_PATH}/${safePathSegment(name)}/documents/${safePathSegment(documentId)}`),
+        /**
+         * Passages for a question. `documentIds` (up to 50) scopes the search; `rerank` reorders the passages with
+         * the managed reranker (counts on `ai.rerank_month`; `reranked: false` when none is configured).
+         */
+        search: (name, query, options = {}) => this.request('POST', `${KNOWLEDGE_PATH}/${safePathSegment(name)}/search`, {
+            body: {
+                query,
+                ...(options.k ? { k: options.k } : {}),
+                ...(options.mode ? { mode: options.mode } : {}),
+                ...(options.metadataFilter ? { metadata_filter: options.metadataFilter } : {}),
+                ...(options.documentIds?.length ? { document_ids: options.documentIds } : {}),
+                ...(options.rerank ? { rerank: true } : {}),
+            },
+        }),
+    };
+    /**
+     * Your project's agents, from your app. The agent acts with the signed-in user's own permissions (and an
+     * agent with knowledge bases only retrieves passages that user may read).
+     *
+     * ```ts
+     * const reply = await sov.agents.run(agentId, { message: 'Where is my order?', onEvent: (e) => render(e) })
+     * await sov.agents.run(agentId, { message: 'And the invoice?', threadId: reply.threadId })
+     * ```
+     */
+    agents = {
+        /** Send a message (a new thread, or `threadId` to continue one) and wait for the answer; `onEvent` streams it. */
+        run: async (agentId, input) => {
+            const events = [];
+            for await (const event of this.agents.stream(agentId, input)) {
+                events.push(event);
+                input.onEvent?.(event);
+            }
+            return agentResult(events);
+        },
+        /** The same as `run`, as an async iterator of events (`conversation`, `text_delta`, `text`, `tool_call`, …, `done`). */
+        stream: (agentId, input) => this.streamEvents(`/api/v1/sovariq/agents/${safePathSegment(agentId)}/runs`, { message: input.message, ...(input.threadId ? { thread_id: input.threadId } : {}) }, input.signal),
+        /** The signed-in user's threads with this agent, newest first. */
+        threads: (agentId) => this.request('GET', `/api/v1/sovariq/agents/${safePathSegment(agentId)}/runs`)
+            .then((out) => out.runs ?? []),
+        /** One thread with its events (messages, tool calls, answers). */
+        thread: (threadId) => this.request('GET', `/api/v1/sovariq/conversations/${safePathSegment(threadId)}`),
+        /** Stop the agent's current run in this thread. */
+        cancel: (threadId) => this.request('POST', `/api/v1/sovariq/conversations/${safePathSegment(threadId)}/cancel`, { body: {} }),
+    };
+    /** POST a JSON body and read the server-sent events it streams back (one JSON object per `data:` line). */
+    async *streamEvents(path, body, signal) {
+        if (!this.accessToken) {
+            throw new SovariaError(401, 'Missing access token; sign the user in first');
+        }
+        await this.ensureAccessTokenFresh();
+        if (!this.scope)
+            await this.resolveScope();
+        this.assertScopePresent();
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            ...this.getScopeHeaders(),
+            ...(await this.clientHeaders()),
+            'Content-Type': 'application/json',
+            Accept: 'text/event-stream',
+            traceparent: traceparentFor(newTraceId()),
+        };
+        let response;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            headers.Authorization = `Bearer ${this.accessToken}`;
+            response = await this.fetchImpl(url, { method: 'POST', headers, body: JSON.stringify(body), signal });
+            if (response.status === 401 && this.refreshToken && attempt === 0) {
+                await this.ensureAccessTokenFresh(true);
+                continue;
+            }
+            break;
+        }
+        if (!response || !response.ok) {
+            const payload = response ? await response.json().catch(() => ({})) : {};
+            throw new SovariaError(response?.status ?? 0, payload);
+        }
+        yield* parseEventStream(response);
+    }
+}
+const KNOWLEDGE_PATH = '/api/v1/data/rel/vector/knowledge';
+function knowledgeDocumentBody(options) {
+    return {
+        ...(options.documentId ? { document_id: options.documentId } : {}),
+        ...(options.title ? { title: options.title } : {}),
+        ...(options.metadata ? { metadata: options.metadata } : {}),
+    };
+}
+function bytesToBase64(bytes) {
+    const g = globalThis;
+    if (g.Buffer)
+        return g.Buffer.from(bytes).toString('base64');
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return g.btoa(binary);
+}
+/** Server-sent events → JSON objects. Streams when the runtime gives a readable body, else reads it whole. */
+export async function* parseEventStream(response) {
+    const parse = (block) => {
+        const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trimStart()).join('\n');
+        if (!data)
+            return null;
+        try {
+            const value = JSON.parse(data);
+            return value && typeof value === 'object' ? value : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const reader = response.body?.getReader?.();
+    if (!reader) {
+        for (const block of (await response.text()).split(/\r?\n\r?\n/)) {
+            const event = parse(block);
+            if (event)
+                yield event;
+        }
+        return;
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let cut = buffer.search(/\r?\n\r?\n/);
+        while (cut >= 0) {
+            const block = buffer.slice(0, cut);
+            buffer = buffer.slice(buffer.slice(cut).match(/^\r?\n\r?\n/)[0].length + cut);
+            const event = parse(block);
+            if (event)
+                yield event;
+            cut = buffer.search(/\r?\n\r?\n/);
+        }
+    }
+    const last = parse(buffer + decoder.decode());
+    if (last)
+        yield last;
+}
+function agentResult(events) {
+    const conversation = events.find((e) => e.type === 'conversation');
+    const done = [...events].reverse().find((e) => e.type === 'done');
+    const finals = events.filter((e) => e.type === 'text' && typeof e.text === 'string').map((e) => e.text);
+    const deltas = events.filter((e) => e.type === 'text_delta' && typeof e.text === 'string').map((e) => e.text);
+    return {
+        threadId: String(conversation?.id ?? ''),
+        text: (finals.length ? finals.join('\n\n') : deltas.join('')).trim(),
+        status: String(done?.status ?? (events.some((e) => e.type === 'error') ? 'error' : 'unknown')),
+        usage: done?.usage ?? undefined,
+        events,
+    };
+}
+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);
+    };
+    // Catch-up after a reconnect: the last stream_seq delivered, and live frames held back while the
+    // missed ones are fetched (so the app sees every message once, in order).
+    let lastSeq = null;
+    let held = null;
+    let generation = 0;
+    const deliver = (frame) => {
+        const seq = typeof frame.stream_seq === 'number' ? frame.stream_seq : null;
+        if (seq !== null) {
+            if (lastSeq !== null && seq <= lastSeq)
+                return; // already delivered (live and replayed overlap)
+            lastSeq = seq;
+        }
+        const payload = (frame.payload ?? frame.data ?? frame);
+        try {
+            handlers.onMessage?.(payload, frame);
+        }
+        catch (error) {
+            console.error('SovariaSDK: realtime onMessage handler failed', error);
+        }
+    };
+    const catchUp = async (fromSeq, gen) => {
+        const pageSize = 500;
+        try {
+            for (let page = 0; page < 20; page += 1) {
+                const res = await sdk.realtime.replay(name, lastSeq ?? fromSeq, pageSize);
+                if (closed || gen !== generation)
+                    return;
+                const events = Array.isArray(res.events) ? res.events : [];
+                for (const event of events) {
+                    if (event.type === 'gap') {
+                        const toSeq = Number(event.to_seq);
+                        handlers.onGap?.({ fromSeq: Number(event.from_seq), toSeq, reason: 'not_retained' });
+                        if (lastSeq === null || toSeq > lastSeq)
+                            lastSeq = toSeq;
+                        continue;
+                    }
+                    deliver(event);
+                }
+                if (events.length < pageSize)
+                    break;
+            }
+        }
+        catch (error) {
+            handlers.onError?.(error);
+            if (!closed && gen === generation)
+                handlers.onGap?.({ fromSeq: fromSeq + 1, reason: 'replay_failed' });
+        }
+        finally {
+            if (gen === generation) {
+                const pending = held ?? [];
+                held = null;
+                for (const frame of pending)
+                    deliver(frame);
+            }
+        }
+    };
+    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;
+            const gen = ++generation;
+            held = null;
+            ws.onopen = () => {
+                attempt = 0;
+                setStatus('live');
+                // A reconnect (we had seen messages before): fetch what was published while we were away.
+                if (lastSeq !== null && handlers.catchUp !== false) {
+                    held = [];
+                    void catchUp(lastSeq, gen);
+                }
+            };
+            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;
+                if (held && gen === generation) {
+                    held.push(frame); // delivered after the missed messages
+                    return;
+                }
+                deliver(frame);
+            };
+            ws.onclose = () => {
+                if (socket === ws)
+                    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(/=+$/, '');
+}