totalum-sdk 0.1.0-dev.10

package/dist/d1/index.js

@@ -0,0 +1,73 @@
+import { inWorker } from '../errors.js';
+import { apiUrlOf, envOf, readEnv } from '../http.js';
+import { TotalumD1Error } from './errors.js';
+import { httpsExecutor } from './https.js';
+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, 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).
+ */
+export function totalumD1(options = {}) {
+    return lazyD1(() => resolveTarget(options), options.mode === 'migrate');
+}
+async function resolveTarget(options) {
+    if (options.binding)
+        return options.binding;
+    if (options.transport !== 'https') {
+        if (inWorker() && 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: apiUrlOf(options),
+        key,
+        env: envOf(options),
+        migrate: options.mode === 'migrate',
+        destructive: options.destructive === true,
+    });
+}
+/**
+ * OpenNext exposes the request's bindings, in a Worker and under `next dev` (Miniflare's local D1); absent (`next
+ * start`, a script) 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 {
+        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');
+    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.js

@@ -0,0 +1,112 @@
+import { TotalumD1Error } from './errors.js';
+import { splitStatements } from './sql.js';
+const READ = /^\s*(select|with)\b/i;
+/**
+ * `batch()` answers rows as objects keyed by column name (no `raw()` mode), so a select with two columns of one name
+ * (`requests.id`, `users.id`) loses one, and Drizzle — which maps a batch row positionally from `Object.keys(row)` —
+ * shifts every later field. As a subquery, SQLite names the second `id:1`: every column survives, in order.
+ */
+const uniqueColumns = (sql) => READ.test(sql) ? `SELECT * FROM (\n${sql.replace(/[\s;]+$/, '')}\n)` : sql;
+/**
+ * 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) — 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;
+    // 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;
+        on;
+        constructor(sql, params = [], on = resolved) {
+            this.sql = sql;
+            this.params = params;
+            this.on = on;
+        }
+        bind(...values) {
+            return new LazyStatement(this.sql, values, this.on);
+        }
+        async real() {
+            return (await this.on()).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 batchOn = (on) => async (statements) => {
+        const t = await on();
+        const lazy = statements.map((s) => {
+            if (!(s instanceof LazyStatement)) {
+                throw TotalumD1Error.client('BATCH_FOREIGN_STATEMENT', 'batch() only accepts statements prepared by this totalumD1() instance');
+            }
+            return s;
+        });
+        const run = (sql) => t.batch(lazy.map((s) => t.prepare(sql(s.sql)).bind(...s.params)));
+        if (!lazy.some((s) => READ.test(s.sql)))
+            return run((s) => s);
+        try {
+            return await run(uniqueColumns);
+        }
+        catch (e) {
+            // a SQL error is deterministic and rolled the batch back: answer it as the statements were written
+            if (e instanceof Error && e.message.endsWith('SQLITE_ERROR'))
+                return run((s) => s);
+            throw e;
+        }
+    };
+    /**
+     * 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');
+        }
+        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: batchOn(resolved),
+        exec,
+        dump: () => Promise.reject(TotalumD1Error.client('NOT_SUPPORTED', 'dump() is not available; use the platform backups')),
+        withSession,
+    };
+}

package/dist/d1/libsql.js

@@ -0,0 +1,125 @@
+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).
+ * `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);
+        }
+        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);
+        }
+        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([FOREIGN_KEYS_ON, ...stmts], 'write')))
+                .slice(1)
+                .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;
+}
+/**
+ * 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
+ * says `SQLITE_ERROR`, reports name resolution as `SQL_INPUT_ERROR` (`SQLite input error: … (at offset N)`) and its own
+ * parser's failures as `SQL_PARSE_ERROR` (wording not SQLite's).
+ */
+function mapLibsqlError(e) {
+    const err = e;
+    if (typeof err.code !== 'string' || typeof err.message !== 'string')
+        return e;
+    const remote = err.code === 'SQL_PARSE_ERROR' || err.code === 'SQL_INPUT_ERROR';
+    if (!remote && !err.code.startsWith('SQLITE_'))
+        return e;
+    const code = remote || err.code === 'SQLITE_UNKNOWN' ? 'SQLITE_ERROR' : err.code;
+    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(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,
+        details: { sqliteMessage },
+    });
+}

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/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.js

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

package/dist/email/index.d.ts

@@ -0,0 +1,31 @@
+import { E as EmailSendInput, j as EmailView } from '../_types/integrations.d-BNGV70e3.js';
+export { i as EmailSendOutput } 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.email` (plan 05 §6.4) over SDK-API `/v1/email/*` (scope `email`): Resend, HTML sent byte for byte, charged
+ * per recipient. On dev only allow-listed recipients are accepted (`DEV_RECIPIENT_NOT_ALLOWED`).
+ */
+declare function totalumEmail(options?: TotalumClientOptions): {
+    /**
+     * Sends one e-mail (HTML byte for byte); charged per recipient.
+     *
+     * @example
+     * await email.send({ to: 'ana@example.com', subject: 'Welcome', html: '<p>Hi Ana</p>' });
+     */
+    send: (msg: EmailSendInput) => Promise<{
+        success: true;
+        message: "Email sent successfully";
+        messageId: string;
+        id: string;
+        status: "queued" | "sent";
+    }>;
+    /** `null` when the e-mail is not this project's. */
+    get: (id: string) => Promise<EmailView | null>;
+};
+type TotalumEmail = ReturnType<typeof totalumEmail>;
+
+export { EmailSendInput, EmailView, TotalumClientOptions, totalumEmail };
+export type { TotalumEmail };

package/dist/email/index.js

@@ -0,0 +1,30 @@
+import { isTotalumError } from '../errors.js';
+import { jsonClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/**
+ * `totalum.email` (plan 05 §6.4) over SDK-API `/v1/email/*` (scope `email`): Resend, HTML sent byte for byte, charged
+ * per recipient. On dev only allow-listed recipients are accepted (`DEV_RECIPIENT_NOT_ALLOWED`).
+ */
+export function totalumEmail(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /**
+         * Sends one e-mail (HTML byte for byte); charged per recipient.
+         *
+         * @example
+         * await email.send({ to: 'ana@example.com', subject: 'Welcome', html: '<p>Hi Ana</p>' });
+         */
+        send: (msg) => call('POST', '/v1/email/send', msg),
+        /** `null` when the e-mail is not this project's. */
+        get: async (id) => {
+            try {
+                return await call('GET', `/v1/email/${encodeURIComponent(id)}`);
+            }
+            catch (e) {
+                if (isTotalumError(e) && e.status === 404)
+                    return null;
+                throw e;
+            }
+        },
+    };
+}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/**
+ * The one error every `totalum-sdk` call throws (plan 05 §7.1): the SDK-API envelope's frozen `errorCode`, the HTTP
+ * status and `details`. `TotalumD1Error` (`totalum-sdk/d1`) and `TotalumWebhookError` (`totalum-sdk/webhooks`)
+ * extend it, so one `isTotalumError(e)` check covers the whole package.
+ */
+export class TotalumError extends Error {
+    name = 'TotalumError';
+    errorCode;
+    /** HTTP status; 0 for network errors, 500 for client-side refusals. */
+    status;
+    details;
+    /** SDK-API's request id, for support and the logs explorer. */
+    requestId;
+    constructor(errorCode, message, status = 500, details, requestId) {
+        super(message);
+        this.errorCode = errorCode;
+        this.status = status;
+        this.details = details;
+        this.requestId = requestId;
+    }
+}
+export function isTotalumError(e) {
+    return e instanceof TotalumError;
+}
+/** Inside workerd: the preview and the published app (A7.14). */
+export const inWorker = () => typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers';
+/**
+ * Refuses a Node-only method inside a Worker (plan 05 §7.2b): the message says where the app runs, what was called and
+ * the HTTPS replacement; `details {method, replacement, docsUrl}` lets a caller render the hint.
+ */
+export function assertNode(method, replacement, docsUrl) {
+    if (!inWorker())
+        return;
+    throw new TotalumError('NODE_ONLY', `NODE_ONLY: ${method} needs a Node runtime, and your preview and published app both run on Cloudflare Workers. ${replacement} See ${docsUrl}`, 500, { method, replacement, docsUrl });
+}

package/dist/files/index.d.ts

@@ -0,0 +1,119 @@
+import { F as FileDescriptor, k as FileUploadUrlInput, m as FilesListQuery } from '../_types/integrations.d-BNGV70e3.js';
+export { l as FileUploadUrlOutput, n as FilesPage } from '../_types/integrations.d-BNGV70e3.js';
+import { TotalumClientOptions } from '../ai/index.js';
+export { a as TotalumError, b as TotalumErrorCode, i as isTotalumError } from '../_types/errors.d-Cu3q_E_r.js';
+import '../_types/coerce.d-C0KIW76L.js';
+
+interface TotalumFilesOptions extends TotalumClientOptions {
+    /** The public files host; default `TOTALUM_FILES_URL`, else `https://files.totalum-project.com` (A10.1). */
+    filesUrl?: string;
+}
+interface UploadOptions {
+    name?: string;
+    contentType?: string;
+    /** `true` stores the file under the private prefix: no public URL, read it through `getSignedUrl` (A10.1). */
+    private?: boolean;
+    folder?: string;
+}
+/**
+ * `totalum.files` (plan 05 §5; SDK-API plan 04 §5.4) over HTTPS with the project key. Every call returns the file
+ * descriptor `{key, fileName, fileSize, contentType, fileUrl, visibility, createdAt}` meant to be stored as-is in the
+ * row's file column; failures throw `TotalumError` with SDK-API's frozen code.
+ */
+declare function totalumFiles(options?: TotalumFilesOptions): {
+    /** Up to 25 MB through SDK-API; larger files go through `getUploadUrl` + `complete`. */
+    upload(input: Blob | ArrayBuffer | Uint8Array | string, opts?: UploadOptions): Promise<FileDescriptor>;
+    /** A presigned PUT (15 min, bound to this type and size) for a direct browser/Node upload; then `complete(key)`. */
+    getUploadUrl: (input: FileUploadUrlInput) => Promise<{
+        uploadUrl: string;
+        key: string;
+        headers: Record<string, string>;
+        expiresAt: string;
+    }>;
+    /** Registers a file uploaded with `getUploadUrl` and returns its descriptor. */
+    complete: (key: string) => Promise<{
+        key: string;
+        fileName: string;
+        fileSize: number;
+        contentType: string;
+        fileUrl: string | null;
+        visibility: "public-by-link" | "private";
+        createdAt: string;
+        etag?: string | undefined;
+        storageClass?: "Standard" | "InfrequentAccess" | undefined;
+        name?: string | undefined;
+        url?: string | null | undefined;
+        size?: number | undefined;
+        id?: string | undefined;
+        fileNameId?: string | undefined;
+    }>;
+    /**
+     * One page of the project's files, newest first: filter by `folder`, `name`, `type`, created and size ranges; `cursor`
+     * from the previous page's `nextCursor`.
+     */
+    list: (q?: Partial<Record<keyof FilesListQuery, string | number>>) => Promise<{
+        items: {
+            key: string;
+            fileName: string;
+            fileSize: number;
+            contentType: string;
+            fileUrl: string | null;
+            visibility: "public-by-link" | "private";
+            createdAt: string;
+            etag?: string | undefined;
+            storageClass?: "Standard" | "InfrequentAccess" | undefined;
+            name?: string | undefined;
+            url?: string | null | undefined;
+            size?: number | undefined;
+            id?: string | undefined;
+            fileNameId?: string | undefined;
+        }[];
+        nextCursor: string | null;
+        totalBytes: number;
+        fileCount: number;
+    }>;
+    /** The descriptor of one file; `FILE_NOT_FOUND` (404) when it does not exist. */
+    get: (key: string) => Promise<{
+        key: string;
+        fileName: string;
+        fileSize: number;
+        contentType: string;
+        fileUrl: string | null;
+        visibility: "public-by-link" | "private";
+        createdAt: string;
+        etag?: string | undefined;
+        storageClass?: "Standard" | "InfrequentAccess" | undefined;
+        name?: string | undefined;
+        url?: string | null | undefined;
+        size?: number | undefined;
+        id?: string | undefined;
+        fileNameId?: string | undefined;
+    }>;
+    /** A presigned GET that R2 verifies: 15 min by default, at most 7 days — the way to hand a private file to a browser. */
+    getSignedUrl: (key: string, opts?: {
+        expiresInSeconds?: number;
+        download?: boolean;
+    }) => Promise<string>;
+    /** Same as `getSignedUrl`. */
+    getDownloadUrl: (key: string, opts?: {
+        expiresInSeconds?: number;
+        download?: boolean;
+    }) => Promise<string>;
+    /** Signed GET URLs for many keys at once (`ttl` in seconds, ≤ 7 days). */
+    presign(keys: string[], opts?: {
+        ttl?: number;
+        download?: boolean;
+    }): Promise<Record<string, string>>;
+    /** Deletes one key, or up to 1000 keys at once. */
+    delete(keys: string | string[]): Promise<void>;
+    /** The object itself (private files included), with `Range` support; errors throw like every other call. */
+    stream: (key: string, opts?: {
+        range?: string;
+    }) => Promise<Response>;
+    /** Sync, no I/O: the public URL of a `p/` key, or the authenticated SDK-API URL of a private `pv/` key. */
+    url(key: string): string;
+};
+type TotalumFiles = ReturnType<typeof totalumFiles>;
+
+export { FileDescriptor, FileUploadUrlInput, FilesListQuery, totalumFiles };
+export type { TotalumFiles, TotalumFilesOptions, UploadOptions };