totalum-sdk 0.1.0-dev.2

package/README.md

@@ -0,0 +1,14 @@
+# totalum-sdk
+
+The SDK Totalum v2 apps import. Wave 1 ships `totalum-sdk/d1`: a `D1Database` for the project's own database wherever the code runs — the bound `TOTALUM_DB` inside a Cloudflare Worker, HTTPS to SDK-API from a sandbox or a laptop (`TOTALUM_PROJECT_KEY`, optional `TOTALUM_SDK_API_URL`, `TOTALUM_ENV=dev|live`), and the Turso adapter when `TOTALUM_DB_PROVIDER=turso`.
+
+```ts
+import { drizzle } from 'drizzle-orm/d1';
+import { totalumD1 } from 'totalum-sdk/d1';
+
+export const db = drizzle(totalumD1()); // no I/O until the first statement
+```
+
+`totalumD1({ mode: 'migrate' })` is for `scripts/migrate.ts` only: it enables DDL (`x-totalum-migrate: 1`) and `exec()`. Failures are `TotalumD1Error` (`errorCode`, `status`, `details`, `requestId`); SQLite failures keep the binding's `D1_ERROR: …` message byte for byte.
+
+Pre-release (`0.1.0-dev.N`, dist-tag `dev`): the API may change until 0.1.0.

package/dist/d1/errors.d.ts

@@ -0,0 +1,27 @@
+import type { ErrorBody, ErrorCode } from '@speed-paradigm/totalum-contracts';
+/** Client-side codes of plan 05 §7.2 that never travel on the wire, so they are not in the contracts enum. */
+export type TotalumD1ClientCode = 'SDK_NOT_CONFIGURED' | 'NOT_SUPPORTED' | 'BATCH_FOREIGN_STATEMENT' | 'NETWORK_ERROR' | 'RESPONSE_PARSE_ERROR';
+export type TotalumD1ErrorCode = ErrorCode | TotalumD1ClientCode;
+/**
+ * The database twin of `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 declare class TotalumD1Error extends Error {
+    readonly name = "TotalumD1Error";
+    readonly errorCode: TotalumD1ErrorCode;
+    /** HTTP status; 0 for network errors, 500 for client-side refusals. */
+    readonly status: number;
+    readonly details: Record<string, unknown> | undefined;
+    readonly requestId: string | undefined;
+    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;
+}
+export declare function isTotalumD1Error(e: unknown): e is TotalumD1Error;
+export declare function isRecord(v: unknown): v is Record<string, unknown>;

package/dist/d1/errors.js

@@ -0,0 +1,39 @@
+/**
+ * The database twin of `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 Error {
+    name = 'TotalumD1Error';
+    errorCode;
+    /** HTTP status; 0 for network errors, 500 for client-side refusals. */
+    status;
+    details;
+    requestId;
+    constructor(errorCode, message, options = {}) {
+        super(message);
+        this.errorCode = errorCode;
+        this.status = options.status ?? 500;
+        this.details = options.details;
+        this.requestId = 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.d.ts

@@ -0,0 +1,10 @@
+import type { Executor } from './types.js';
+export interface HttpsConfig {
+    apiUrl: string;
+    key: string;
+    env: 'dev' | 'live';
+    migrate: boolean;
+    destructive: boolean;
+}
+/** The `D1Database` half that speaks `POST /v1/db/query|batch` (plan 04 §3.2; contracts `db.ts`). */
+export declare function httpsExecutor(config: HttpsConfig): Executor;

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,10 @@
+import type { D1Database, TotalumD1Options } from './types.js';
+export { TotalumD1Error, isTotalumD1Error } from './errors.js';
+export type { TotalumD1ClientCode, TotalumD1ErrorCode } from './errors.js';
+export type { D1Database, D1DatabaseSession, D1ExecResult, D1PreparedStatement, D1Result, TotalumD1Options, } from './types.js';
+/**
+ * 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, and an HTTPS client to
+ * SDK-API everywhere else. Detection happens on the first statement, never at call time (§3.1).
+ */
+export declare function totalumD1(options?: TotalumD1Options): D1Database;

package/dist/d1/index.js

@@ -0,0 +1,61 @@
+import { TotalumD1Error } from './errors.js';
+import { httpsExecutor } from './https.js';
+import { lazyD1 } from './lazy.js';
+import { libsqlExecutor } from './libsql.js';
+export { TotalumD1Error, isTotalumD1Error } from './errors.js';
+const DEFAULT_API_URL = 'https://sdk-api.totalum.app';
+/**
+ * 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, and an HTTPS client to
+ * SDK-API everywhere else. Detection happens on the first statement, never at call time (§3.1).
+ */
+export function totalumD1(options = {}) {
+    return lazyD1(() => resolveTarget(options), options.mode === 'migrate');
+}
+async function resolveTarget(options) {
+    if (options.binding)
+        return options.binding;
+    const inWorker = typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers';
+    if (inWorker && options.transport !== 'https') {
+        if (readEnv('TOTALUM_DB_PROVIDER') === 'turso')
+            return await tursoTarget();
+        const binding = await openNextBinding();
+        if (binding)
+            return binding;
+    }
+    const key = options.key ?? readEnv('TOTALUM_PROJECT_KEY');
+    if (key === undefined) {
+        throw TotalumD1Error.client('SDK_NOT_CONFIGURED', 'Set TOTALUM_PROJECT_KEY (server-side) or pass { binding } to totalumD1().');
+    }
+    return httpsExecutor({
+        apiUrl: options.apiUrl ?? readEnv('TOTALUM_SDK_API_URL') ?? DEFAULT_API_URL,
+        key,
+        env: options.env ?? readEnv('TOTALUM_ENV') ?? 'live',
+        migrate: options.mode === 'migrate',
+        destructive: options.destructive === true,
+    });
+}
+/** Env is `process.env` (Node; workerd with `nodejs_compat`, where OpenNext and Miniflare populate it from bindings). */
+function readEnv(name) {
+    const value = typeof process === 'undefined' ? undefined : process.env[name];
+    return value === '' ? undefined : value;
+}
+/** OpenNext exposes the request's bindings; absent (a laptop) or outside a request, there is no binding. */
+async function openNextBinding() {
+    try {
+        const openNext = (await import('@opennextjs/cloudflare'));
+        return openNext.getCloudflareContext().env['TOTALUM_DB'];
+    }
+    catch {
+        return undefined;
+    }
+}
+async function tursoTarget() {
+    const url = readEnv('TURSO_DATABASE_URL');
+    const authToken = readEnv('TURSO_AUTH_TOKEN');
+    if (url === undefined || authToken === undefined) {
+        throw TotalumD1Error.client('SDK_NOT_CONFIGURED', 'TOTALUM_DB_PROVIDER=turso requires TURSO_DATABASE_URL and TURSO_AUTH_TOKEN');
+    }
+    const web = (await import('@libsql/client/web'));
+    return libsqlExecutor(web.createClient({ url, authToken, intMode: 'bigint' }));
+}

package/dist/d1/lazy.d.ts

@@ -0,0 +1,7 @@
+import type { D1Database, Executor } from './types.js';
+/**
+ * The object `totalumD1()` hands out: no I/O and no environment detection until the first statement runs;
+ * the target is resolved once and cached (plan 05 §3.1). Statements remember `sql` + params and are
+ * materialised on the resolved target when executed, so `drizzle(totalumD1())` at module scope is legal.
+ */
+export declare function lazyD1(resolve: () => Promise<Executor>, migrate: boolean): D1Database;

package/dist/d1/lazy.js

@@ -0,0 +1,72 @@
+import { TotalumD1Error } from './errors.js';
+import { splitStatements } from './sql.js';
+/**
+ * The object `totalumD1()` hands out: no I/O and no environment detection until the first statement runs;
+ * the target is resolved once and cached (plan 05 §3.1). Statements remember `sql` + params and are
+ * materialised on the resolved target when executed, so `drizzle(totalumD1())` at module scope is legal.
+ */
+export function lazyD1(resolve, migrate) {
+    let target;
+    // a failed resolution is not cached, so a transient failure does not poison the module-scope instance
+    const resolved = () => (target ??= resolve().catch((e) => {
+        target = undefined;
+        throw e;
+    }));
+    class LazyStatement {
+        sql;
+        params;
+        constructor(sql, params = []) {
+            this.sql = sql;
+            this.params = params;
+        }
+        bind(...values) {
+            return new LazyStatement(this.sql, values);
+        }
+        async real() {
+            return (await resolved()).prepare(this.sql).bind(...this.params);
+        }
+        async first(colName) {
+            return (await this.real()).first(colName);
+        }
+        async run() {
+            return (await this.real()).run();
+        }
+        async all() {
+            return (await this.real()).all();
+        }
+        async raw(options) {
+            const s = await this.real();
+            return options?.columnNames === true ? s.raw({ columnNames: true }) : s.raw();
+        }
+    }
+    const batch = async (statements) => {
+        const t = await resolved();
+        const real = statements.map((s) => {
+            if (!(s instanceof LazyStatement)) {
+                throw TotalumD1Error.client('BATCH_FOREIGN_STATEMENT', 'batch() only accepts statements prepared by this totalumD1() instance');
+            }
+            return t.prepare(s.sql).bind(...s.params);
+        });
+        return t.batch(real);
+    };
+    const exec = async (script) => {
+        if (!migrate) {
+            throw TotalumD1Error.client('EXEC_REQUIRES_MIGRATE_MODE', 'exec() runs DDL scripts: use totalumD1({ mode: "migrate" }) from scripts/migrate.ts, or db.batch([...]) for data');
+        }
+        const t = await resolved();
+        if (t.exec)
+            return t.exec(script);
+        const statements = splitStatements(script);
+        const results = await t.batch(statements.map((sql) => t.prepare(sql)));
+        return { count: statements.length, duration: results.reduce((sum, r) => sum + r.meta.duration, 0) };
+    };
+    return {
+        prepare: (sql) => new LazyStatement(sql),
+        batch,
+        exec,
+        dump: () => Promise.reject(TotalumD1Error.client('NOT_SUPPORTED', 'dump() is not available; use the platform backups')),
+        withSession: () => {
+            throw TotalumD1Error.client('NOT_SUPPORTED', 'withSession() is not available in this SDK version');
+        },
+    };
+}

package/dist/d1/libsql.d.ts

@@ -0,0 +1,23 @@
+import type { Executor } from './types.js';
+/** The slice of `@libsql/client`'s `Client` the adapter uses, declared structurally (no third-party types leak). */
+export interface LibsqlClient {
+    execute(statement: LibsqlStatement): Promise<LibsqlResultSet>;
+    batch(statements: LibsqlStatement[], mode: 'write'): Promise<LibsqlResultSet[]>;
+}
+export type LibsqlValue = string | number | bigint | boolean | null | ArrayBuffer | Uint8Array;
+export interface LibsqlStatement {
+    sql: string;
+    args: LibsqlValue[];
+}
+export interface LibsqlResultSet {
+    columns: string[];
+    rows: ArrayLike<unknown>[];
+    rowsAffected: number;
+    lastInsertRowid: bigint | undefined | null;
+}
+/**
+ * The Turso path (A3.8, plan 05 §3.10): a `D1Database`-compatible executor over a libsql client created with
+ * `intMode: 'bigint'` (integers beyond 2^53 then degrade to the same double D1 returns instead of throwing).
+ * `meta` is synthesised from what libsql reports; `size_after` is not reported by libsql and is 0.
+ */
+export declare function libsqlExecutor(client: LibsqlClient): Executor;

package/dist/d1/libsql.js

@@ -0,0 +1,92 @@
+import { TotalumD1Error } from './errors.js';
+import { assertBindable, pickFirst } from './sql.js';
+/**
+ * The Turso path (A3.8, plan 05 §3.10): a `D1Database`-compatible executor over a libsql client created with
+ * `intMode: 'bigint'` (integers beyond 2^53 then degrade to the same double D1 returns instead of throwing).
+ * `meta` is synthesised from what libsql reports; `size_after` is not reported by libsql and is 0.
+ */
+export function libsqlExecutor(client) {
+    let lastRowId = 0;
+    const toResult = (rs) => {
+        if (rs.lastInsertRowid !== undefined && rs.lastInsertRowid !== null)
+            lastRowId = Number(rs.lastInsertRowid);
+        const rows = rs.rows.map((row) => Array.from(row, fromLibsqlValue));
+        const meta = {
+            duration: 0,
+            changes: rs.rowsAffected,
+            last_row_id: lastRowId,
+            rows_read: rows.length,
+            rows_written: rs.rowsAffected,
+            changed_db: rs.rowsAffected > 0,
+            size_after: 0,
+        };
+        const results = rows.map((row) => Object.fromEntries(row.map((cell, i) => [rs.columns[i], cell])));
+        return { results, success: true, meta };
+    };
+    const run = async (f) => {
+        try {
+            return await f();
+        }
+        catch (e) {
+            throw mapLibsqlError(e);
+        }
+    };
+    class LibsqlD1Statement {
+        sql;
+        args;
+        constructor(sql, args = []) {
+            this.sql = sql;
+            this.args = args;
+        }
+        bind(...values) {
+            assertBindable(values);
+            return new LibsqlD1Statement(this.sql, values);
+        }
+        execute() {
+            return run(() => client.execute({ sql: this.sql, args: this.args }));
+        }
+        async first(colName) {
+            return pickFirst(toResult(await this.execute()).results, colName);
+        }
+        async run() {
+            return toResult(await this.execute());
+        }
+        all() {
+            return this.run();
+        }
+        async raw(options) {
+            const rs = await this.execute();
+            toResult(rs);
+            const rows = rs.rows.map((row) => Array.from(row, fromLibsqlValue));
+            return options?.columnNames === true ? [rs.columns, ...rows] : rows;
+        }
+    }
+    return {
+        prepare: (sql) => new LibsqlD1Statement(sql),
+        async batch(statements) {
+            const stmts = statements.map((s) => ({
+                sql: s.sql,
+                args: s.args,
+            }));
+            return (await run(() => client.batch(stmts, 'write'))).map((rs) => toResult(rs));
+        },
+    };
+}
+function fromLibsqlValue(v) {
+    if (typeof v === 'bigint')
+        return Number(v);
+    if (v instanceof ArrayBuffer)
+        return Array.from(new Uint8Array(v));
+    return v;
+}
+/** `LibsqlError { code, message: '<CODE>: <sqlite message>' }` → the `D1_ERROR: <sqlite message>: <CODE>` shape. */
+function mapLibsqlError(e) {
+    const err = e;
+    if (typeof err.code !== 'string' || !err.code.startsWith('SQLITE_') || typeof err.message !== 'string')
+        return e;
+    const sqliteMessage = `${err.message.replace(/^(SQLITE_\w+: )+/, '')}: ${err.code}`;
+    return new TotalumD1Error('SQL_ERROR', `D1_ERROR: ${sqliteMessage}`, {
+        status: 400,
+        details: { sqliteMessage },
+    });
+}

package/dist/d1/sql.d.ts

@@ -0,0 +1,9 @@
+/** Native D1 refuses these at `bind()` time with `D1_TYPE_ERROR`; both non-native paths do the same, synchronously. */
+export declare function assertBindable(values: unknown[]): void;
+/** `first(col)` as the binding does it: `null` on no rows, `D1_COLUMN_NOTFOUND` on an unknown column. */
+export declare function pickFirst(results: unknown[], colName: string | undefined): unknown;
+/**
+ * Splits an `exec()` script on statement boundaries — `;` inside string literals, quoted identifiers and
+ * comments is not a boundary (plan 05 §3.4). Empty trailing fragments are dropped.
+ */
+export declare function splitStatements(script: string): string[];

package/dist/d1/sql.js

@@ -0,0 +1,87 @@
+import { isRecord } from './errors.js';
+/** Native D1 refuses these at `bind()` time with `D1_TYPE_ERROR`; both non-native paths do the same, synchronously. */
+export function assertBindable(values) {
+    for (const v of values) {
+        const ok = v === null ||
+            typeof v === 'string' ||
+            typeof v === 'number' ||
+            typeof v === 'boolean' ||
+            v instanceof ArrayBuffer ||
+            ArrayBuffer.isView(v);
+        if (!ok)
+            throw new Error(`D1_TYPE_ERROR: Type '${typeof v}' not supported for value '${describe(v)}'`);
+    }
+}
+/** The value as D1 prints it in `D1_TYPE_ERROR` (`${value}`). */
+function describe(v) {
+    switch (typeof v) {
+        case 'bigint':
+        case 'number':
+        case 'boolean':
+        case 'string':
+        case 'symbol':
+            return v.toString();
+        case 'undefined':
+            return 'undefined';
+        case 'function':
+            return 'function';
+        default:
+            return '[object Object]';
+    }
+}
+/** `first(col)` as the binding does it: `null` on no rows, `D1_COLUMN_NOTFOUND` on an unknown column. */
+export function pickFirst(results, colName) {
+    const row = results[0];
+    if (row === undefined)
+        return null;
+    if (colName === undefined)
+        return row;
+    if (!isRecord(row) || !(colName in row))
+        throw new Error(`D1_COLUMN_NOTFOUND: Column not found (${colName})`);
+    return row[colName];
+}
+/**
+ * Splits an `exec()` script on statement boundaries — `;` inside string literals, quoted identifiers and
+ * comments is not a boundary (plan 05 §3.4). Empty trailing fragments are dropped.
+ */
+export function splitStatements(script) {
+    const out = [];
+    let start = 0;
+    let i = 0;
+    while (i < script.length) {
+        const c = script[i];
+        const next = script[i + 1];
+        if (c === "'" || c === '"' || c === '`' || c === '[') {
+            const close = c === '[' ? ']' : c;
+            i = script.indexOf(close, i + 1);
+            if (i === -1)
+                break;
+            // a doubled quote is an escaped quote inside the literal
+            while (close !== ']' && script[i + 1] === close)
+                i = script.indexOf(close, i + 2);
+            if (i === -1)
+                break;
+            i++;
+        }
+        else if (c === '-' && next === '-') {
+            i = script.indexOf('\n', i);
+            if (i === -1)
+                break;
+        }
+        else if (c === '/' && next === '*') {
+            i = script.indexOf('*/', i + 2);
+            if (i === -1)
+                break;
+            i += 2;
+        }
+        else if (c === ';') {
+            out.push(script.slice(start, i));
+            start = ++i;
+        }
+        else {
+            i++;
+        }
+    }
+    out.push(script.slice(start));
+    return out.map((s) => s.trim()).filter((s) => s.length > 0);
+}

package/dist/d1/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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).
+ */
+export 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;
+};
+export interface D1Result<T = Record<string, unknown>> {
+    results: T[];
+    success: true;
+    meta: D1Meta;
+}
+export interface D1ExecResult {
+    count: number;
+    duration: number;
+}
+export 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[]>;
+}
+export interface D1DatabaseSession {
+    prepare(sql: string): D1PreparedStatement;
+    batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+    getBookmark(): string | null;
+}
+export 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;
+}
+/** What a resolved target must offer; a native binding satisfies it, the HTTPS and libsql executors implement it. */
+export interface Executor {
+    prepare(sql: string): D1PreparedStatement;
+    batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+    /** Native only: the binding's own line-based `exec`. Executors without it run `exec` as one atomic batch. */
+    exec?(sql: string): Promise<D1ExecResult>;
+}
+export interface TotalumD1Options {
+    /** `'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;
+    /** HTTPS path only; default `TOTALUM_ENV`, then `'live'`. */
+    env?: 'dev' | 'live';
+    /** Default `TOTALUM_SDK_API_URL`, then `https://sdk-api.totalum.app`. */
+    apiUrl?: string;
+    /** Default `TOTALUM_PROJECT_KEY`. */
+    key?: string;
+    /** 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';
+}

package/dist/d1/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "totalum-sdk",
+  "version": "0.1.0-dev.2",
+  "description": "The SDK generated Totalum apps import: totalum-sdk/d1 (D1 driver — native binding in a Worker, HTTPS to SDK-API elsewhere)",
+  "license": "UNLICENSED",
+  "type": "module",
+  "packageManager": "pnpm@10.34.5",
+  "engines": {
+    "node": ">=22 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/francesc-commits/totalum-sdk.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./d1": {
+      "types": "./dist/d1/index.d.ts",
+      "default": "./dist/d1/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:node": "vitest run --project node",
+    "test:workerd": "vitest run --project workerd",
+    "prepare": "lefthook install || echo \"lefthook: hooks not installed (git >= 2.31 required)\""
+  },
+  "peerDependencies": {
+    "@libsql/client": "0.18.0"
+  },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "0.22.0",
+    "@cloudflare/workers-types": "5.20260922.1",
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-conventional": "21.2.3",
+    "@eslint/js": "9.39.5",
+    "@libsql/client": "0.18.0",
+    "@speed-paradigm/totalum-contracts": "link:../totalum-contracts",
+    "@types/node": "22.20.4",
+    "drizzle-orm": "0.45.3",
+    "esbuild": "0.28.1",
+    "eslint": "9.39.5",
+    "eslint-plugin-import-x": "4.17.1",
+    "eslint-plugin-no-only-tests": "3.4.0",
+    "lefthook": "2.1.14",
+    "miniflare": "5.20260921.0-alpha",
+    "prettier": "3.9.8",
+    "totalum-sdk-api": "link:../totalum-sdk-api",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.70.1",
+    "vitest": "4.1.11",
+    "wrangler": "4.136.2"
+  },
+  "prettier": "@speed-paradigm/totalum-contracts/configs/prettier.json"
+}