totalum-sdk 0.1.0-dev.10

package/dist/browser/index.js

@@ -0,0 +1,168 @@
+import { TotalumError } from '../errors.js';
+import { jsonClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** The frozen 67 (contracts `BROWSER_COMMANDS`, plan 11 §3.4) as a literal, so nothing is imported at runtime. */
+const BROWSER_COMMANDS = [
+    ...[
+        'goto',
+        'back',
+        'forward',
+        'reload',
+        'pageInfo',
+        'click',
+        'dblclick',
+        'type',
+        'press',
+        'hover',
+    ],
+    ...[
+        'scroll',
+        'dragAndDrop',
+        'select',
+        'upload',
+        'frames.list',
+        'frames.use',
+        'tabs.list',
+        'tabs.new',
+    ],
+    ...['tabs.use', 'tabs.close', 'waitFor', 'evaluate', 'content', 'screenshot', 'pdf', 'extract'],
+    ...[
+        'cookies.get',
+        'cookies.set',
+        'cookies.clear',
+        'storage.get',
+        'storage.set',
+        'storage.clear',
+    ],
+    ...[
+        'context.save',
+        'downloads.list',
+        'downloads.get',
+        'network.capture',
+        'network.log',
+        'network.har',
+    ],
+    ...[
+        'network.intercept',
+        'network.setHeaders',
+        'emulate.viewport',
+        'emulate.device',
+        'emulate.geolocation',
+    ],
+    ...[
+        'emulate.timezone',
+        'emulate.locale',
+        'emulate.userAgent',
+        'captcha.solve',
+        'captcha.events',
+    ],
+    ...[
+        'proxy.usage',
+        'stealth.get',
+        'session.status',
+        'session.liveView',
+        'session.recording',
+        'dialog.handle',
+    ],
+    ...[
+        'page.addInitScript',
+        'page.exposeFunction',
+        'emulate.media',
+        'emulate.network',
+        'emulate.cpu',
+    ],
+    ...[
+        'permissions.grant',
+        'clipboard.read',
+        'clipboard.write',
+        'act',
+        'observe',
+        'session.release',
+    ],
+    ...['network.subscribe', 'accessibility.snapshot'],
+];
+/** The leading positional arguments of a command method; the last argument is always the rest of its parameters. */
+const POSITIONAL = {
+    goto: ['url'],
+    click: ['target'],
+    dblclick: ['target'],
+    type: ['target', 'text'],
+    press: ['key'],
+    hover: ['target'],
+    select: ['target', 'value'],
+    upload: ['target', 'files'],
+    dragAndDrop: ['from', 'to'],
+    evaluate: ['expression'],
+    'cookies.set': ['cookies'],
+    act: ['instruction'],
+    observe: ['instruction'],
+};
+/**
+ * `totalum.browser` (plan 05 §6.3) over SDK-API `/v1/browser/*` (scope `browser`): Browserbase sessions driven entirely
+ * over HTTPS, so every command works from a Worker (A6.29). A command's refusal throws `TotalumError` with its frozen
+ * code (`ACTION_TIMEOUT`, `ACTION_FAILED`, …); `actions()` returns every result instead.
+ */
+export function totalumBrowser(options = {}) {
+    const call = jsonClient(options);
+    const path = (id) => `/v1/browser/sessions/${encodeURIComponent(id)}`;
+    function handle(created) {
+        const run = async (command) => {
+            const { results } = await call('POST', `${path(created.id)}/actions`, {
+                action: command,
+            });
+            const r = results[0];
+            if (!r?.ok)
+                throw new TotalumError(r?.error?.code ?? 'ACTION_FAILED', r?.error?.message ?? 'Browser command failed', 400);
+            return r.data;
+        };
+        const methods = {};
+        for (const type of BROWSER_COMMANDS) {
+            const names = POSITIONAL[type] ?? [];
+            const method = (...args) => {
+                const params = Object.fromEntries(names.map((n, i) => [n, args[i]]));
+                return run({ ...args[names.length], ...params, type });
+            };
+            const [group, name] = type.split('.');
+            if (name && group)
+                (methods[group] ??= {})[name] = method;
+            else
+                methods[type] = method;
+        }
+        return Object.assign(methods, {
+            id: created.id,
+            liveViewUrl: created.liveViewUrl ?? '',
+            expiresAt: created.expiresAt ?? '',
+            actions: async (batch, opts = {}) => (await call('POST', `${path(created.id)}/actions`, { actions: batch, ...opts }))
+                .results,
+            program: (program) => call('POST', `${path(created.id)}/program`, program),
+            status: () => call('GET', path(created.id)),
+            close: () => call('DELETE', path(created.id)),
+        });
+    }
+    return {
+        /** Opens a session with the vendor options and the Totalum-synthesised ones. */
+        session: async (opts = {}) => handle(await call('POST', '/v1/browser/sessions', opts)),
+        sessions: {
+            /** The project's sessions, filtered by `status` or `metadata`. */
+            list: (q = {}) => call('GET', `/v1/browser/sessions?${Object.entries(q)
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+                .join('&')}`),
+            /** A handle on an existing session (no call is made). */
+            get: (id) => handle({ id }),
+        },
+        programs: {
+            /** A program's status and, once finished, its results. */
+            get: (programId) => call('GET', `/v1/browser/programs/${encodeURIComponent(programId)}`),
+            /** Polls until the program leaves `pending`/`running` (the `browser.program.completed` webhook is the push twin). */
+            wait: async (programId, opts = {}) => {
+                const until = Date.now() + (opts.timeoutMs ?? 960_000);
+                for (;;) {
+                    const s = await call('GET', `/v1/browser/programs/${encodeURIComponent(programId)}`);
+                    if ((s.status !== 'pending' && s.status !== 'running') || Date.now() > until)
+                        return s;
+                    await new Promise((r) => setTimeout(r, opts.intervalMs ?? 2000));
+                }
+            },
+        },
+    };
+}

package/dist/cron/index.d.ts

@@ -0,0 +1,180 @@
+import { c as CronJobInput, b as CronJob, d as CronJobPatch } from '../_types/integrations.d-BNGV70e3.js';
+export { e as CronRun, f as CronRunsPage } from '../_types/integrations.d-BNGV70e3.js';
+import { T as TotalumClientOptions } from '../_types/errors.d-Cu3q_E_r.js';
+export { a as TotalumError, i as isTotalumError } from '../_types/errors.d-Cu3q_E_r.js';
+import '../_types/coerce.d-C0KIW76L.js';
+
+/**
+ * `totalum.cron` (plan 05 §6.9) over SDK-API `/v1/cron/*` (scope `cron`): HTTP jobs against the project's own host,
+ * fired by Totalum's Scheduler; limits per plan (`429 CRON_LIMIT_REACHED {limit, plan}`, `400 INVALID_SCHEDULE
+ * {minIntervalSeconds}`). Executions cost nothing.
+ */
+declare function totalumCron(options?: TotalumClientOptions): {
+    /**
+     * A job that calls a URL of the project's own host on a cron `schedule` (or `{ everyMinutes }`).
+     *
+     * @example
+     * await cron.create({
+     *   name: 'daily-report',
+     *   schedule: '0 8 * * *',
+     *   request: { method: 'POST', url: 'https://my-app.totalum-project.com/api/cron/report' },
+     * });
+     */
+    create: (input: CronJobInput) => Promise<{
+        id: string;
+        name: string;
+        schedule: string | {
+            everyMinutes: number;
+        };
+        request: {
+            method: "GET" | "POST";
+            url: string;
+            headers?: Record<string, string> | undefined;
+            body?: string | undefined;
+            timeoutMs?: number | undefined;
+        };
+        enabled: boolean;
+        status: "active" | "paused" | "paused_failures";
+        nextRunAt: string | null;
+        createdAt: string;
+        env: "dev" | "live";
+        lastRun?: {
+            at: string;
+            status: number | "error" | "timeout" | "skipped";
+            latencyMs: number;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    /** Every job of the project. */
+    list: () => Promise<{
+        id: string;
+        name: string;
+        schedule: string | {
+            everyMinutes: number;
+        };
+        request: {
+            method: "GET" | "POST";
+            url: string;
+            headers?: Record<string, string> | undefined;
+            body?: string | undefined;
+            timeoutMs?: number | undefined;
+        };
+        enabled: boolean;
+        status: "active" | "paused" | "paused_failures";
+        nextRunAt: string | null;
+        createdAt: string;
+        env: "dev" | "live";
+        lastRun?: {
+            at: string;
+            status: number | "error" | "timeout" | "skipped";
+            latencyMs: number;
+        } | undefined;
+        description?: string | undefined;
+    }[]>;
+    /** `null` when the job is not this project's. */
+    get: (id: string) => Promise<CronJob | null>;
+    /** Changes any field of a job (`schedule`, `request`, `enabled`, …). */
+    update: (id: string, patch: CronJobPatch) => Promise<{
+        id: string;
+        name: string;
+        schedule: string | {
+            everyMinutes: number;
+        };
+        request: {
+            method: "GET" | "POST";
+            url: string;
+            headers?: Record<string, string> | undefined;
+            body?: string | undefined;
+            timeoutMs?: number | undefined;
+        };
+        enabled: boolean;
+        status: "active" | "paused" | "paused_failures";
+        nextRunAt: string | null;
+        createdAt: string;
+        env: "dev" | "live";
+        lastRun?: {
+            at: string;
+            status: number | "error" | "timeout" | "skipped";
+            latencyMs: number;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    /** Deletes a job. */
+    delete: (id: string) => Promise<void>;
+    /** Stops a job from firing until `resume`. */
+    pause: (id: string) => Promise<{
+        id: string;
+        name: string;
+        schedule: string | {
+            everyMinutes: number;
+        };
+        request: {
+            method: "GET" | "POST";
+            url: string;
+            headers?: Record<string, string> | undefined;
+            body?: string | undefined;
+            timeoutMs?: number | undefined;
+        };
+        enabled: boolean;
+        status: "active" | "paused" | "paused_failures";
+        nextRunAt: string | null;
+        createdAt: string;
+        env: "dev" | "live";
+        lastRun?: {
+            at: string;
+            status: number | "error" | "timeout" | "skipped";
+            latencyMs: number;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    /** Lets a paused job fire again. */
+    resume: (id: string) => Promise<{
+        id: string;
+        name: string;
+        schedule: string | {
+            everyMinutes: number;
+        };
+        request: {
+            method: "GET" | "POST";
+            url: string;
+            headers?: Record<string, string> | undefined;
+            body?: string | undefined;
+            timeoutMs?: number | undefined;
+        };
+        enabled: boolean;
+        status: "active" | "paused" | "paused_failures";
+        nextRunAt: string | null;
+        createdAt: string;
+        env: "dev" | "live";
+        lastRun?: {
+            at: string;
+            status: number | "error" | "timeout" | "skipped";
+            latencyMs: number;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    /** A job's executions, newest first (30 days). */
+    runs: (id: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<{
+        items: {
+            id: string;
+            scheduledFor: string;
+            startedAt: string | null;
+            status: number | "error" | "timeout" | "skipped";
+            latencyMs: number | null;
+            error?: string | undefined;
+            responseSnippet?: string | undefined;
+        }[];
+        nextCursor: string | null;
+    }>;
+    /** Fires a job now, outside its schedule. */
+    trigger: (id: string) => Promise<{
+        runId: string;
+    }>;
+};
+type TotalumCron = ReturnType<typeof totalumCron>;
+
+export { CronJob, CronJobInput, CronJobPatch, TotalumClientOptions, totalumCron };
+export type { TotalumCron };

package/dist/cron/index.js

@@ -0,0 +1,61 @@
+import { isTotalumError } from '../errors.js';
+import { jsonClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/**
+ * `totalum.cron` (plan 05 §6.9) over SDK-API `/v1/cron/*` (scope `cron`): HTTP jobs against the project's own host,
+ * fired by Totalum's Scheduler; limits per plan (`429 CRON_LIMIT_REACHED {limit, plan}`, `400 INVALID_SCHEDULE
+ * {minIntervalSeconds}`). Executions cost nothing.
+ */
+export function totalumCron(options = {}) {
+    const call = jsonClient(options);
+    const job = (id) => `/v1/cron/jobs/${encodeURIComponent(id)}`;
+    const update = (id, patch) => call('PATCH', job(id), patch);
+    return {
+        /**
+         * A job that calls a URL of the project's own host on a cron `schedule` (or `{ everyMinutes }`).
+         *
+         * @example
+         * await cron.create({
+         *   name: 'daily-report',
+         *   schedule: '0 8 * * *',
+         *   request: { method: 'POST', url: 'https://my-app.totalum-project.com/api/cron/report' },
+         * });
+         */
+        create: (input) => call('POST', '/v1/cron/jobs', input),
+        /** Every job of the project. */
+        list: async () => (await call('GET', '/v1/cron/jobs')).items,
+        /** `null` when the job is not this project's. */
+        get: async (id) => {
+            try {
+                return await call('GET', job(id));
+            }
+            catch (e) {
+                if (isTotalumError(e) && e.errorCode === 'CRON_JOB_NOT_FOUND')
+                    return null;
+                throw e;
+            }
+        },
+        /** Changes any field of a job (`schedule`, `request`, `enabled`, …). */
+        update,
+        /** Deletes a job. */
+        delete: async (id) => {
+            await call('DELETE', job(id));
+        },
+        /** Stops a job from firing until `resume`. */
+        pause: (id) => update(id, { enabled: false }),
+        /** Lets a paused job fire again. */
+        resume: (id) => update(id, { enabled: true }),
+        /** A job's executions, newest first (30 days). */
+        runs: (id, opts = {}) => {
+            const q = new URLSearchParams();
+            if (opts.limit !== undefined)
+                q.set('limit', String(opts.limit));
+            if (opts.cursor !== undefined)
+                q.set('cursor', opts.cursor);
+            const qs = q.toString();
+            return call('GET', `${job(id)}/runs${qs ? `?${qs}` : ''}`);
+        },
+        /** Fires a job now, outside its schedule. */
+        trigger: (id) => call('POST', `${job(id)}/trigger`),
+    };
+}

package/dist/d1/errors.js

@@ -0,0 +1,31 @@
+import { TotalumError } from '../errors.js';
+/**
+ * The database `TotalumError` (plan 05 §3.5): `message` is `D1_ERROR: …`-shaped so it reads like a native failure —
+ * byte-identical to the binding's message when the failure is SQLite's.
+ */
+export class TotalumD1Error extends TotalumError {
+    name = 'TotalumD1Error';
+    constructor(errorCode, message, options = {}) {
+        super(errorCode, message, options.status ?? 500, options.details, options.requestId);
+    }
+    /** A client-side refusal (`D1_ERROR: <code>: <message>`). */
+    static client(errorCode, message) {
+        return new TotalumD1Error(errorCode, `D1_ERROR: ${errorCode}: ${message}`);
+    }
+    /** The SDK-API error envelope → typed error; `SQL_ERROR` rebuilds the native message from `sqliteMessage`. */
+    static fromWire(errors, status, requestId) {
+        const details = isRecord(errors.errorDetails) ? errors.errorDetails : undefined;
+        const sqlite = details?.['sqliteMessage'];
+        const message = errors.errorCode === 'SQL_ERROR' && typeof sqlite === 'string'
+            ? `D1_ERROR: ${sqlite}`
+            : `D1_ERROR: ${errors.errorCode}: ${errors.errorMessage}`;
+        const init = { status, ...(details && { details }), ...(requestId !== undefined && { requestId }) };
+        return new TotalumD1Error(errors.errorCode, message, init);
+    }
+}
+export function isTotalumD1Error(e) {
+    return e instanceof TotalumD1Error;
+}
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/d1/https.js

@@ -0,0 +1,103 @@
+import { TotalumD1Error } from './errors.js';
+import { assertBindable, pickFirst } from './sql.js';
+/**
+ * The wire headers the driver sends, as literals so the published package has no runtime dependency (plan 05
+ * §1); `satisfies` over contracts' `as const` object fails the build if either side ever drifts.
+ */
+const HEADERS = {
+    env: 'x-totalum-env',
+    migrate: 'x-totalum-migrate',
+    migrateDestructive: 'x-totalum-migrate-destructive',
+};
+/** The `D1Database` half that speaks `POST /v1/db/query|batch` (plan 04 §3.2; contracts `db.ts`). */
+export function httpsExecutor(config) {
+    const headers = {
+        authorization: `Bearer ${config.key}`,
+        'content-type': 'application/json',
+        [HEADERS.env]: config.env,
+    };
+    if (config.migrate)
+        headers[HEADERS.migrate] = '1';
+    if (config.migrate && config.destructive)
+        headers[HEADERS.migrateDestructive] = '1';
+    async function call(path, body) {
+        let response;
+        try {
+            response = await fetch(config.apiUrl + path, { method: 'POST', headers, body: JSON.stringify(body) });
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            throw new TotalumD1Error('NETWORK_ERROR', `D1_ERROR: NETWORK_ERROR: ${reason}`, { status: 0 });
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            throw new TotalumD1Error('RESPONSE_PARSE_ERROR', `D1_ERROR: RESPONSE_PARSE_ERROR: HTTP ${String(response.status)} without a JSON envelope`, {
+                status: response.status,
+            });
+        }
+        const envelope = payload;
+        if (envelope.errors !== null) {
+            throw TotalumD1Error.fromWire(envelope.errors, response.status, envelope.metadata?.requestId);
+        }
+        return envelope.data;
+    }
+    class HttpsStatement {
+        sql;
+        params;
+        constructor(sql, params = []) {
+            this.sql = sql;
+            this.params = params;
+        }
+        bind(...values) {
+            assertBindable(values);
+            return new HttpsStatement(this.sql, values.map(encodeParam));
+        }
+        query(mode, columnNames) {
+            const statement = { sql: this.sql, params: this.params, mode };
+            if (columnNames)
+                statement.columnNames = true;
+            return call('/v1/db/query', statement);
+        }
+        async first(colName) {
+            return pickFirst((await this.query('first')).results, colName);
+        }
+        run() {
+            return this.query('run');
+        }
+        all() {
+            return this.query('all');
+        }
+        async raw(options) {
+            return (await this.query('raw', options?.columnNames === true ? true : undefined)).results;
+        }
+    }
+    return {
+        prepare: (sql) => new HttpsStatement(sql),
+        async batch(statements) {
+            const body = {
+                statements: statements.map((s) => ({
+                    sql: s.sql,
+                    params: s.params,
+                })),
+            };
+            return (await call('/v1/db/batch', body)).results;
+        },
+    };
+}
+/** Bytes travel as `{ $bytes: base64 }` (plan 04 §3.2); every other bindable value is JSON already. */
+function encodeParam(value) {
+    if (value instanceof ArrayBuffer)
+        return { $bytes: toBase64(new Uint8Array(value)) };
+    if (ArrayBuffer.isView(value))
+        return { $bytes: toBase64(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)) };
+    return value;
+}
+function toBase64(bytes) {
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}

package/dist/d1/index.d.ts

@@ -0,0 +1,107 @@
+import { S as SdkClientErrorCode, a as TotalumError, b as TotalumErrorCode, E as ErrorBody } from '../_types/errors.d-Cu3q_E_r.js';
+import { TotalumClientOptions } from '../ai/index.js';
+export { i as isTotalumError } from '../_types/errors.d-Cu3q_E_r.js';
+
+/**
+ * Cloudflare's `D1Database` surface, re-declared structurally so an app needs no Cloudflare types to compile
+ * and `drizzle-orm/d1` accepts the object (plan 05 §1, §3.1). `D1Meta` is Cloudflare's own interface
+ * (`size_after` required); the contracts wire shape is looser and every value here satisfies it (type-tested).
+ */
+type D1Meta = {
+    duration: number;
+    size_after: number;
+    rows_read: number;
+    rows_written: number;
+    last_row_id: number;
+    changed_db: boolean;
+    changes: number;
+    served_by_region?: string;
+    served_by_primary?: boolean;
+};
+interface D1Result<T = Record<string, unknown>> {
+    results: T[];
+    success: true;
+    meta: D1Meta;
+}
+interface D1ExecResult {
+    count: number;
+    duration: number;
+}
+interface D1PreparedStatement {
+    bind(...values: unknown[]): D1PreparedStatement;
+    first<T = Record<string, unknown>>(colName?: string): Promise<T | null>;
+    run<T = Record<string, unknown>>(): Promise<D1Result<T>>;
+    all<T = Record<string, unknown>>(): Promise<D1Result<T>>;
+    raw<T = unknown[]>(options: {
+        columnNames: true;
+    }): Promise<[string[], ...T[]]>;
+    raw<T = unknown[]>(options?: {
+        columnNames?: false;
+    }): Promise<T[]>;
+}
+interface D1DatabaseSession {
+    prepare(sql: string): D1PreparedStatement;
+    batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+    getBookmark(): string | null;
+}
+interface D1Database {
+    prepare(sql: string): D1PreparedStatement;
+    batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+    exec(sql: string): Promise<D1ExecResult>;
+    dump(): Promise<ArrayBuffer>;
+    withSession(constraintOrBookmark?: string): D1DatabaseSession;
+}
+/** `key`, `apiUrl` and `env` (HTTPS path only) resolve exactly as in every other namespace. */
+interface TotalumD1Options extends TotalumClientOptions {
+    /** `'migrate'` (scripts/migrate.ts only) sends `x-totalum-migrate: 1` and enables `exec()`; default `'query'`. */
+    mode?: 'query' | 'migrate';
+    /** Migrate mode only: sends `x-totalum-migrate-destructive: 1` (A10.4). */
+    destructive?: boolean;
+    /** An explicit binding wins over detection (plain Workers: `env.TOTALUM_DB`; tests: a Miniflare D1). */
+    binding?: D1Database;
+    /** `'https'` forces the HTTPS path even inside a Worker (the conformance corpus); default `'auto'`. */
+    transport?: 'auto' | 'https';
+}
+
+/** The client-side codes the driver throws (plan 05 §7.2), from contracts' `SDK_CLIENT_ERROR_CODES`. */
+type TotalumD1ClientCode = Extract<SdkClientErrorCode, 'SDK_NOT_CONFIGURED' | 'NOT_SUPPORTED' | 'BATCH_FOREIGN_STATEMENT' | 'NETWORK_ERROR' | 'RESPONSE_PARSE_ERROR'>;
+type TotalumD1ErrorCode = TotalumErrorCode;
+/**
+ * The database `TotalumError` (plan 05 §3.5): `message` is `D1_ERROR: …`-shaped so it reads like a native failure —
+ * byte-identical to the binding's message when the failure is SQLite's.
+ */
+declare class TotalumD1Error extends TotalumError {
+    name: string;
+    constructor(errorCode: TotalumD1ErrorCode, message: string, options?: {
+        status?: number;
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+    /** A client-side refusal (`D1_ERROR: <code>: <message>`). */
+    static client(errorCode: TotalumD1ClientCode | 'EXEC_REQUIRES_MIGRATE_MODE', message: string): TotalumD1Error;
+    /** The SDK-API error envelope → typed error; `SQL_ERROR` rebuilds the native message from `sqliteMessage`. */
+    static fromWire(errors: ErrorBody, status: number, requestId: string | undefined): TotalumD1Error;
+}
+declare function isTotalumD1Error(e: unknown): e is TotalumD1Error;
+
+/** Set on every mutating response; while the browser holds it, its reads go to the primary (read-your-writes). */
+declare const READ_YOUR_WRITES_COOKIE = "__tlm_d1_w";
+/**
+ * Runs one request of a Worker with a replicated D1 (A3.23, research 46 §6.3): a `GET`/`HEAD` reads through a
+ * `first-unconstrained` session — the nearest replica — unless the browser wrote in the last 10 s; any other method
+ * uses the plain binding (writes go to the primary; measured faster than any session) and its response sets the short
+ * cookie that sends that browser's next reads to the primary. `run` receives the env to hand to the app, whose
+ * `totalumD1()` reads `TOTALUM_DB` from it on every statement. No D1 binding (Turso, a laptop): `run(env)` unchanged.
+ */
+declare function withTotalumSession<E extends object>(request: Request, env: E, run: (env: E) => Promise<Response>): Promise<Response>;
+
+/**
+ * A `D1Database` for the project's own database wherever the code runs (A3.4, plan 05 §3): the bound
+ * `TOTALUM_DB` inside a Worker, the libsql adapter when the environment moved to Turso, the local D1 that
+ * `initOpenNextCloudflareForDev()` binds under `next dev`, and an HTTPS client to SDK-API everywhere else.
+ * Detection happens on the first statement, never at call time (§3.1).
+ */
+declare function totalumD1(options?: TotalumD1Options): D1Database;
+
+export { READ_YOUR_WRITES_COOKIE, TotalumD1Error, TotalumError, TotalumErrorCode, isTotalumD1Error, totalumD1, withTotalumSession };
+export type { D1Database, D1DatabaseSession, D1ExecResult, D1PreparedStatement, D1Result, TotalumD1ClientCode, TotalumD1ErrorCode, TotalumD1Options };