totalum-sdk 0.1.0-dev.6 → 0.1.0-dev.7

package/dist/d1/index.d.ts

@@ -84,6 +84,17 @@ declare class TotalumD1Error extends TotalumError {
 }
 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, and an HTTPS client to
@@ -91,5 +102,5 @@ declare function isTotalumD1Error(e: unknown): e is TotalumD1Error;
  */
 declare function totalumD1(options?: TotalumD1Options): D1Database;
 
-export { TotalumD1Error, TotalumError, TotalumErrorCode, isTotalumD1Error, totalumD1 };
+export { READ_YOUR_WRITES_COOKIE, TotalumD1Error, TotalumError, TotalumErrorCode, isTotalumD1Error, totalumD1, withTotalumSession };
 export type { D1Database, D1DatabaseSession, D1ExecResult, D1PreparedStatement, D1Result, TotalumD1ClientCode, TotalumD1ErrorCode, TotalumD1Options };

package/dist/d1/index.js

@@ -6,6 +6,7 @@ import { lazyD1 } from './lazy.js';
 import { libsqlExecutor } from './libsql.js';
 export { TotalumError, isTotalumError } from '../errors.js';
 export { TotalumD1Error, isTotalumD1Error } from './errors.js';
+export { READ_YOUR_WRITES_COOKIE, withTotalumSession } from './session.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
@@ -36,15 +37,28 @@ async function resolveTarget(options) {
         destructive: options.destructive === true,
     });
 }
-/** OpenNext exposes the request's bindings; absent (a laptop) or outside a request, there is no binding. */
+/**
+ * OpenNext exposes the request's bindings; absent (a laptop) or outside a request, there is no binding. The executor
+ * reads `TOTALUM_DB` again on every statement: it is the current request's database — the plain binding, or the
+ * read-replica session `withTotalumSession` put there — never the first request's for the isolate's life.
+ */
 async function openNextBinding() {
+    let openNext;
     try {
-        const openNext = (await import('@opennextjs/cloudflare'));
-        return openNext.getCloudflareContext().env['TOTALUM_DB'];
+        openNext = (await import('@opennextjs/cloudflare'));
+        if (!openNext.getCloudflareContext().env['TOTALUM_DB'])
+            return undefined;
     }
     catch {
         return undefined;
     }
+    const current = () => openNext.getCloudflareContext().env['TOTALUM_DB'];
+    return {
+        prepare: (sql) => current().prepare(sql),
+        batch: (statements) => current().batch(statements),
+        exec: (sql) => current().exec(sql),
+        withSession: (c) => current().withSession(c),
+    };
 }
 async function tursoTarget() {
     const url = readEnv('TURSO_DATABASE_URL');

package/dist/d1/lazy.js

@@ -2,8 +2,10 @@ 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.
+ * the target is resolved once and cached (plan 05 §3.1) — in a Worker that target reads the request's own binding on
+ * every statement (`index.ts`), so one module-scope instance serves every request with that request's database.
+ * Statements remember `sql` + params and are materialised on the target when executed, so `drizzle(totalumD1())` at
+ * module scope is legal.
  */
 export function lazyD1(resolve, migrate) {
     let target;
@@ -15,15 +17,17 @@ export function lazyD1(resolve, migrate) {
     class LazyStatement {
         sql;
         params;
-        constructor(sql, params = []) {
+        on;
+        constructor(sql, params = [], on = resolved) {
             this.sql = sql;
             this.params = params;
+            this.on = on;
         }
         bind(...values) {
-            return new LazyStatement(this.sql, values);
+            return new LazyStatement(this.sql, values, this.on);
         }
         async real() {
-            return (await resolved()).prepare(this.sql).bind(...this.params);
+            return (await this.on()).prepare(this.sql).bind(...this.params);
         }
         async first(colName) {
             return (await this.real()).first(colName);
@@ -39,8 +43,8 @@ export function lazyD1(resolve, migrate) {
             return options?.columnNames === true ? s.raw({ columnNames: true }) : s.raw();
         }
     }
-    const batch = async (statements) => {
-        const t = await resolved();
+    const batchOn = (on) => async (statements) => {
+        const t = await on();
         const real = statements.map((s) => {
             if (!(s instanceof LazyStatement)) {
                 throw TotalumD1Error.client('BATCH_FOREIGN_STATEMENT', 'batch() only accepts statements prepared by this totalumD1() instance');
@@ -49,6 +53,26 @@ export function lazyD1(resolve, migrate) {
         });
         return t.batch(real);
     };
+    /**
+     * A D1 session (read replication, A3.23): on the native binding the binding's own `withSession()`, created on the
+     * first statement, so bookmarks work in hand-written code; on HTTPS and Turso there are no replicas and the session
+     * is the database itself, `getBookmark()` → `null`.
+     */
+    const withSession = (constraintOrBookmark) => {
+        let session;
+        let real;
+        const on = () => (session ??= resolved().then((t) => {
+            if (!t.withSession)
+                return t;
+            real = t.withSession(constraintOrBookmark);
+            return real;
+        }));
+        return {
+            prepare: (sql) => new LazyStatement(sql, [], on),
+            batch: batchOn(on),
+            getBookmark: () => real?.getBookmark() ?? null,
+        };
+    };
     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');
@@ -62,11 +86,9 @@ export function lazyD1(resolve, migrate) {
     };
     return {
         prepare: (sql) => new LazyStatement(sql),
-        batch,
+        batch: batchOn(resolved),
         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');
-        },
+        withSession,
     };
 }

package/dist/d1/libsql.js

@@ -1,5 +1,11 @@
 import { TotalumD1Error } from './errors.js';
 import { assertBindable, pickFirst } from './sql.js';
+/**
+ * D1 enforces foreign keys; a Turso database on the new engine (A3.24) starts every connection with them off, and each
+ * Hrana request is a new connection. So every request carries the pragma, inside the one transaction libsql opens for
+ * it (the new engine applies it there; libSQL has them on already and ignores it inside a transaction).
+ */
+const FOREIGN_KEYS_ON = { sql: 'PRAGMA foreign_keys = ON', args: [] };
 /**
  * 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).
@@ -42,8 +48,9 @@ export function libsqlExecutor(client) {
             assertBindable(values);
             return new LibsqlD1Statement(this.sql, values);
         }
-        execute() {
-            return run(() => client.execute({ sql: this.sql, args: this.args }));
+        async execute() {
+            const [, rs] = await run(() => client.batch([FOREIGN_KEYS_ON, { sql: this.sql, args: this.args }], 'deferred'));
+            return rs;
         }
         async first(colName) {
             return pickFirst(toResult(await this.execute()).results, colName);
@@ -68,7 +75,9 @@ export function libsqlExecutor(client) {
                 sql: s.sql,
                 args: s.args,
             }));
-            return (await run(() => client.batch(stmts, 'write'))).map((rs) => toResult(rs));
+            return (await run(() => client.batch([FOREIGN_KEYS_ON, ...stmts], 'write')))
+                .slice(1)
+                .map((rs) => toResult(rs));
         },
     };
 }
@@ -79,6 +88,11 @@ function fromLibsqlValue(v) {
         return Array.from(new Uint8Array(v));
     return v;
 }
+/**
+ * The new engine (A3.24, recorded 2026-09-24) words the same SQLite failures as `Tursodb error: Runtime error: <msg> (19)`
+ * or `Tursodb error: Parse error: <msg>`, and a composite key as `t.(a, b)` where SQLite says `t.a, t.b`.
+ */
+const TURSODB_PREFIX = /^Tursodb error: [A-Za-z ]+ error: /;
 /**
  * `LibsqlError { code, message: '<CODE>: <sqlite message>' }` → the `D1_ERROR: <sqlite message>: <CODE>` shape. A
  * remote Turso database (recorded 2026-09-23) also prefixes `SQLite error: `, answers `SQLITE_UNKNOWN` where SQLite
@@ -96,7 +110,13 @@ function mapLibsqlError(e) {
     const text = err.message
         .replace(/^((SQLITE_\w+|SQL_PARSE_ERROR|SQL_INPUT_ERROR): )+/, '')
         .replace(/^SQLite (input )?error: /, '')
-        .replace(/ \(at offset (\d+)\)$/, ' at offset $1');
+        .replace(/ \(at offset (\d+)\)$/, ' at offset $1')
+        .replace(TURSODB_PREFIX, '')
+        .replace(/ \(\d+\)$/, '')
+        .replace(/(\w+)\.\(([^)]+)\)/, (_, t, cols) => cols
+        .split(', ')
+        .map((c) => `${t}.${c}`)
+        .join(', '));
     const sqliteMessage = `${text}: ${code}`;
     return new TotalumD1Error('SQL_ERROR', `D1_ERROR: ${sqliteMessage}`, {
         status: 400,

package/dist/d1/session.js

@@ -0,0 +1,38 @@
+/** Set on every mutating response; while the browser holds it, its reads go to the primary (read-your-writes). */
+export const READ_YOUR_WRITES_COOKIE = '__tlm_d1_w';
+/** Replicas lag the primary by 30–75 ms (Cloudflare); 10 s leaves a wide margin (research 46 §6.3). */
+const WINDOW_SECONDS = 10;
+const READS = new Set(['GET', 'HEAD']);
+/**
+ * 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.
+ */
+export async function withTotalumSession(request, env, run) {
+    const db = env.TOTALUM_DB;
+    if (typeof db?.withSession !== 'function')
+        return run(env);
+    const binding = db;
+    if (!READS.has(request.method)) {
+        const res = await run(env);
+        if (res.status === 101)
+            return res; // a WebSocket upgrade cannot be re-wrapped
+        const out = new Response(res.body, res);
+        out.headers.append('set-cookie', `${READ_YOUR_WRITES_COOKIE}=1; Max-Age=${String(WINDOW_SECONDS)}; Path=/; HttpOnly; Secure; SameSite=None; Partitioned`);
+        return out;
+    }
+    const cookies = request.headers.get('cookie') ?? '';
+    if (new RegExp(`(?:^|;\\s*)${READ_YOUR_WRITES_COOKIE}=`).test(cookies))
+        return run(env);
+    const session = binding.withSession('first-unconstrained');
+    const replicaDb = {
+        prepare: (sql) => session.prepare(sql),
+        batch: (statements) => session.batch(statements),
+        exec: (sql) => binding.exec(sql),
+        dump: () => binding.dump(),
+        withSession: (c) => binding.withSession(c),
+    };
+    return run({ ...env, TOTALUM_DB: replicaDb });
+}

package/dist/index.d.ts

@@ -28,7 +28,7 @@ import { totalumWeb } from './web/index.js';
 export { TotalumWeb } from './web/index.js';
 import { totalumWebhooks } from './webhooks/index.js';
 export { TotalumWebhookError, TotalumWebhooks, verifyWebhook } from './webhooks/index.js';
-export { D1Database, D1DatabaseSession, D1ExecResult, D1PreparedStatement, D1Result, TotalumD1ClientCode, TotalumD1Error, TotalumD1ErrorCode, TotalumD1Options, isTotalumD1Error, totalumD1 } from './d1/index.js';
+export { D1Database, D1DatabaseSession, D1ExecResult, D1PreparedStatement, D1Result, READ_YOUR_WRITES_COOKIE, TotalumD1ClientCode, TotalumD1Error, TotalumD1ErrorCode, TotalumD1Options, isTotalumD1Error, totalumD1, withTotalumSession } from './d1/index.js';
 export { T as TotalumClientOptions, a as TotalumError, b as TotalumErrorCode, i as isTotalumError } from './_types/errors.d-yrue1e9O.js';
 export { C as CheckoutInput, a as CheckoutOutput, b as CronJob, c as CronJobInput, d as CronJobPatch, e as CronRun, f as CronRunsPage, g as CustomerPortalLinkInput, h as CustomerPortalLinkOutput, E as EmailSendInput, i as EmailSendOutput, j as EmailView, F as FileDescriptor, k as FileUploadUrlInput, l as FileUploadUrlOutput, m as FilesListQuery, n as FilesPage, J as JobCreated, O as OnboardingLinkInput, o as OnboardingLinkOutput, P as PaymentsStatus, p as PdfFromHtmlInput, q as PdfFromUrlInput, r as PdfOutput, S as ScanDocumentInput, s as ScanOcrInput, t as ScanOcrOutput, u as ScreenshotInput, v as ScreenshotOutput, w as SeoIndexNowKey, x as SeoNotifyOutput, y as SpeakInput, z as StoredMedia, T as TranscribeInput, A as TranscribeOutput, W as WebJob, B as WebScrapeOutput, D as WebSearchOutput } from './_types/integrations.d-BKPWost0.js';
 export { L as LogsPage, S as SiteAnalyticsOutput, a as SiteDimension, b as SiteMetric } from './_types/ops.d-BOMT9yln.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totalum-sdk",
-  "version": "0.1.0-dev.6",
+  "version": "0.1.0-dev.7",
   "description": "The SDK generated Totalum apps import: every integration namespace over SDK-API (totalum-sdk, or one subpath each: /files, /ai, /web, …) and totalum-sdk/d1, the D1 driver",
   "license": "UNLICENSED",
   "type": "module",