totalum-sdk 0.1.0-dev.3 → 0.1.0-dev.5

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-Cii20Vl4.js';
+export { e as CronRun, f as CronRunsPage } from '../_types/integrations.d-Cii20Vl4.js';
+import { T as TotalumClientOptions } from '../_types/errors.d-ZrZKjL3U.js';
+export { a as TotalumError, i as isTotalumError } from '../_types/errors.d-ZrZKjL3U.js';
+import '../_types/coerce.d-C1KWvgPp.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

@@ -1,20 +1,12 @@
+import { TotalumError } from '../errors.js';
 /**
- * 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.
+ * 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 Error {
+export class TotalumD1Error extends TotalumError {
     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;
+        super(errorCode, message, options.status ?? 500, options.details, options.requestId);
     }
     /** A client-side refusal (`D1_ERROR: <code>: <message>`). */
     static client(errorCode, message) {

package/dist/d1/index.d.ts

@@ -1,10 +1,95 @@
-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';
+import { S as SdkClientErrorCode, a as TotalumError, b as TotalumErrorCode, E as ErrorBody } from '../_types/errors.d-ZrZKjL3U.js';
+import { TotalumClientOptions } from '../ai/index.js';
+export { i as isTotalumError } from '../_types/errors.d-ZrZKjL3U.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;
+
 /**
  * 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;
+declare function totalumD1(options?: TotalumD1Options): D1Database;
+
+export { TotalumD1Error, TotalumError, TotalumErrorCode, isTotalumD1Error, totalumD1 };
+export type { D1Database, D1DatabaseSession, D1ExecResult, D1PreparedStatement, D1Result, TotalumD1ClientCode, TotalumD1ErrorCode, TotalumD1Options };

package/dist/d1/index.js

@@ -1,9 +1,11 @@
+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';
-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
@@ -15,8 +17,7 @@ export function totalumD1(options = {}) {
 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 (inWorker() && options.transport !== 'https') {
         if (readEnv('TOTALUM_DB_PROVIDER') === 'turso')
             return await tursoTarget();
         const binding = await openNextBinding();
@@ -28,18 +29,13 @@ async function resolveTarget(options) {
         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,
+        apiUrl: apiUrlOf(options),
         key,
-        env: options.env ?? readEnv('TOTALUM_ENV') ?? 'live',
+        env: envOf(options),
         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 {

package/dist/email/index.d.ts

@@ -0,0 +1,31 @@
+import { E as EmailSendInput, j as EmailView } from '../_types/integrations.d-Cii20Vl4.js';
+export { i as EmailSendOutput } from '../_types/integrations.d-Cii20Vl4.js';
+import { T as TotalumClientOptions } from '../_types/errors.d-ZrZKjL3U.js';
+export { a as TotalumError, i as isTotalumError } from '../_types/errors.d-ZrZKjL3U.js';
+import '../_types/coerce.d-C1KWvgPp.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;
+            }
+        },
+    };
+}