totalum-sdk 0.1.0-dev.10

package/dist/files/index.js

@@ -0,0 +1,63 @@
+import { apiUrlOf, jsonClient, query, rawClient, readEnv } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+const DEFAULT_FILES_URL = 'https://files.totalum-project.com';
+/**
+ * `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.
+ */
+export function totalumFiles(options = {}) {
+    const call = jsonClient(options);
+    const raw = rawClient(options);
+    const filesUrl = () => options.filesUrl ?? readEnv('TOTALUM_FILES_URL') ?? DEFAULT_FILES_URL;
+    const path = (key) => `/v1/files/${key.split('/').map(encodeURIComponent).join('/')}`;
+    const getSignedUrl = async (key, opts = {}) => {
+        const q = query({ expiresInSeconds: opts.expiresInSeconds, download: opts.download || undefined });
+        return (await call('GET', `${path(key)}/download-url${q}`)).url;
+    };
+    return {
+        /** Up to 25 MB through SDK-API; larger files go through `getUploadUrl` + `complete`. */
+        upload(input, opts = {}) {
+            const type = opts.contentType ?? (input instanceof Blob ? input.type : '');
+            const name = opts.name ?? (input instanceof File ? input.name : 'file');
+            const form = new FormData();
+            form.set('file', new Blob([input], { type: type || 'application/octet-stream' }), name);
+            form.set('name', name);
+            if (opts.private)
+                form.set('private', 'true');
+            if (opts.folder)
+                form.set('folder', opts.folder);
+            return call('POST', '/v1/files', form);
+        },
+        /** A presigned PUT (15 min, bound to this type and size) for a direct browser/Node upload; then `complete(key)`. */
+        getUploadUrl: (input) => call('POST', '/v1/files/upload-url', input),
+        /** Registers a file uploaded with `getUploadUrl` and returns its descriptor. */
+        complete: (key) => call('POST', '/v1/files/complete', { key }),
+        /**
+         * 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 = {}) => call('GET', `/v1/files${query(q)}`),
+        /** The descriptor of one file; `FILE_NOT_FOUND` (404) when it does not exist. */
+        get: (key) => call('GET', `${path(key)}/meta`),
+        /** 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,
+        /** Same as `getSignedUrl`. */
+        getDownloadUrl: getSignedUrl,
+        /** Signed GET URLs for many keys at once (`ttl` in seconds, ≤ 7 days). */
+        async presign(keys, opts = {}) {
+            return (await call('POST', '/v1/files/presign', { keys, ...opts }))
+                .urls;
+        },
+        /** Deletes one key, or up to 1000 keys at once. */
+        async delete(keys) {
+            await (Array.isArray(keys) ? call('POST', '/v1/files/delete', { keys }) : call('DELETE', path(keys)));
+        },
+        /** The object itself (private files included), with `Range` support; errors throw like every other call. */
+        stream: (key, opts = {}) => raw(path(key), undefined, 'GET', opts.range ? { range: opts.range } : {}),
+        /** Sync, no I/O: the public URL of a `p/` key, or the authenticated SDK-API URL of a private `pv/` key. */
+        url(key) {
+            return key.startsWith('pv/') ? apiUrlOf(options) + path(key) : `${filesUrl()}/${key}`;
+        },
+    };
+}

package/dist/http.js

@@ -0,0 +1,85 @@
+import { TotalumError } from './errors.js';
+export const DEFAULT_API_URL = 'https://sdk-api.totalum.app';
+const MISSING_KEY = 'Set TOTALUM_PROJECT_KEY (server-side) or pass { key }.';
+/** `process.env` (Node; workerd with `nodejs_compat`, where OpenNext and Miniflare populate it from bindings); `''` = unset. */
+export function readEnv(name) {
+    const value = typeof process === 'undefined' ? undefined : process.env[name];
+    return value === '' ? undefined : value;
+}
+/** The project key: the option, else `TOTALUM_PROJECT_KEY`, else `SDK_NOT_CONFIGURED`. Read at call time, never at import. */
+export function projectKey(options) {
+    const key = options.key ?? readEnv('TOTALUM_PROJECT_KEY');
+    if (key === undefined)
+        throw new TotalumError('SDK_NOT_CONFIGURED', MISSING_KEY);
+    return key;
+}
+export const apiUrlOf = (options) => options.apiUrl ?? readEnv('TOTALUM_SDK_API_URL') ?? DEFAULT_API_URL;
+export const envOf = (options) => options.env ?? (readEnv('TOTALUM_ENV') === 'dev' ? 'dev' : 'live');
+/** One HTTPS call to SDK-API with the project key; a transport failure is `NETWORK_ERROR`. */
+export async function send(options, method, route, body, extra = {}) {
+    const headers = {
+        ...extra,
+        authorization: `Bearer ${projectKey(options)}`,
+        'x-totalum-env': envOf(options),
+    };
+    const form = body instanceof FormData;
+    if (body !== undefined && !form)
+        headers['content-type'] = 'application/json';
+    try {
+        return await fetch(apiUrlOf(options) + route, {
+            method,
+            headers,
+            ...(body === undefined ? {} : { body: form ? body : JSON.stringify(body) }),
+        });
+    }
+    catch (e) {
+        throw new TotalumError('NETWORK_ERROR', e instanceof Error ? e.message : String(e), 0);
+    }
+}
+/** The envelope of a response, or the typed error its `errors` carry. */
+export async function envelopeOf(res) {
+    let envelope;
+    try {
+        const parsed = await res.json();
+        envelope = parsed;
+    }
+    catch {
+        throw new TotalumError('RESPONSE_PARSE_ERROR', `HTTP ${String(res.status)} without a JSON envelope`, res.status);
+    }
+    if (envelope.errors) {
+        const details = envelope.errors.errorDetails;
+        throw new TotalumError(envelope.errors.errorCode, envelope.errors.errorMessage, res.status, typeof details === 'object' && details !== null ? details : undefined, envelope.metadata?.requestId);
+    }
+    return envelope;
+}
+/** JSON calls to SDK-API with the project key: the whole envelope, or `TotalumError` with the frozen code. */
+export function envelopeClient(options) {
+    return async (method, route, body) => envelopeOf(await send(options, method, route, body));
+}
+/** JSON calls to SDK-API with the project key: the envelope's `data`, or `TotalumError` with the frozen code. */
+export function jsonClient(options) {
+    const call = envelopeClient(options);
+    return async (method, route, body) => (await call(method, route, body)).data;
+}
+/** A call whose success is not JSON (audio, a stream, a file): the raw `Response`, or the envelope's refusal thrown. */
+export function rawClient(options) {
+    return async (route, body, method = 'POST', extra) => {
+        const res = await send(options, method, route, body, extra);
+        if (!res.ok)
+            await envelopeOf(res);
+        return res;
+    };
+}
+/** `?a=1&b=2` from the defined entries (arrays joined with commas), or `''`. */
+export function query(params) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined)
+            q.set(k, Array.isArray(v) ? v.join(',') : String(v));
+    return q.size ? `?${q.toString()}` : '';
+}
+/** `data` + `usage {credits, vendor?, units?}` from `metadata` (plan 11 §0.8: every integration result shows its price). */
+export const withUsage = ({ data, metadata }) => ({
+    ...data,
+    usage: { credits: metadata?.credits ?? 0, ...metadata?.usage },
+});

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { totalumAi, TotalumAiOptions } from './ai/index.js';
+export { AiChatInput, AiEmbedInput, AiEmbedOutput, AiImageEditInput, AiImageInput, AiImageOutput, AiModelsOutput, AiTextOutput, AiVideoCreated, AiVideoInput, AiVideoJob, AiVisionDescribeInput, ChatResult, ChatStream, ChatUsage, TotalumAi } from './ai/index.js';
+import { totalumAnalytics } from './analytics/index.js';
+export { SiteAnalyticsQuery, TotalumAnalytics } from './analytics/index.js';
+import { totalumBrowser } from './browser/index.js';
+export { BrowserActionsOutput, BrowserCommand, BrowserCommandResult, BrowserCommands, BrowserProgram, BrowserProgramStatus, BrowserSession, BrowserSessionCreated, BrowserSessionInput, BrowserSessionStatus, TotalumBrowser } from './browser/index.js';
+import { totalumCron } from './cron/index.js';
+export { TotalumCron } from './cron/index.js';
+import { totalumEmail } from './email/index.js';
+export { TotalumEmail } from './email/index.js';
+import { totalumFiles, TotalumFilesOptions } from './files/index.js';
+export { TotalumFiles, UploadOptions } from './files/index.js';
+import { totalumLogs } from './logs/index.js';
+export { LogsQuery, TotalumLogs } from './logs/index.js';
+import { totalumPayments } from './payments/index.js';
+export { TotalumPayments } from './payments/index.js';
+import { totalumPdf } from './pdf/index.js';
+export { TotalumPdf } from './pdf/index.js';
+import { totalumRealtime } from './realtime/index.js';
+export { RealtimePublishInput, RealtimePublishOutput, RealtimeTicketInput, RealtimeTicketOutput, TotalumRealtime } from './realtime/index.js';
+import { totalumScan } from './scan/index.js';
+export { ScanDocumentResult, TotalumScan } from './scan/index.js';
+import { totalumSeo } from './seo/index.js';
+export { TotalumSeo } from './seo/index.js';
+import { totalumSpeech } from './speech/index.js';
+export { TotalumSpeech } from './speech/index.js';
+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, 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-Cu3q_E_r.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-BNGV70e3.js';
+export { L as LogsPage, S as SiteAnalyticsOutput, a as SiteDimension, b as SiteMetric } from './_types/ops.d-C9375KIG.js';
+export { W as WebhookConfig, a as WebhookEvent, b as WebhookSecretOutput } from './_types/billing.d-BbSZh1wY.js';
+import './_types/coerce.d-C0KIW76L.js';
+
+/** The options of `createTotalum()`: every namespace's options in one object (each falls back to its env var). */
+type TotalumOptions = TotalumAiOptions & TotalumFilesOptions;
+declare const namespaces: {
+    ai: typeof totalumAi;
+    analytics: typeof totalumAnalytics;
+    browser: typeof totalumBrowser;
+    cron: typeof totalumCron;
+    email: typeof totalumEmail;
+    files: typeof totalumFiles;
+    logs: typeof totalumLogs;
+    payments: typeof totalumPayments;
+    pdf: typeof totalumPdf;
+    realtime: typeof totalumRealtime;
+    scan: typeof totalumScan;
+    seo: typeof totalumSeo;
+    speech: typeof totalumSpeech;
+    web: typeof totalumWeb;
+    webhooks: typeof totalumWebhooks;
+};
+type Totalum = {
+    readonly [K in keyof typeof namespaces]: ReturnType<(typeof namespaces)[K]>;
+};
+/**
+ * Every integration namespace on one object (plan 05 §2.1), each built on first access with the same options — no I/O
+ * and no env read until a method is called. The database is `totalumD1()` from `totalum-sdk/d1`, not a namespace.
+ *
+ * @example
+ * const totalum = createTotalum({ env: 'dev' });
+ * await totalum.email.send({ to: 'a@b.c', subject: 'Hi', html: '<p>Hi</p>' });
+ */
+declare function createTotalum(options?: TotalumOptions): Totalum;
+/** The default instance, configured from the environment (`TOTALUM_PROJECT_KEY`, `TOTALUM_SDK_API_URL`, `TOTALUM_ENV`). */
+declare const totalum: Totalum;
+
+export { TotalumAiOptions, TotalumFilesOptions, createTotalum, totalum, totalumAi, totalumAnalytics, totalumBrowser, totalumCron, totalumEmail, totalumFiles, totalumLogs, totalumPayments, totalumPdf, totalumRealtime, totalumScan, totalumSeo, totalumSpeech, totalumWeb, totalumWebhooks };
+export type { Totalum, TotalumOptions };

package/dist/index.js

@@ -0,0 +1,68 @@
+import { totalumAi } from './ai/index.js';
+import { totalumAnalytics } from './analytics/index.js';
+import { totalumBrowser } from './browser/index.js';
+import { totalumCron } from './cron/index.js';
+import { totalumEmail } from './email/index.js';
+import { totalumFiles } from './files/index.js';
+import { totalumLogs } from './logs/index.js';
+import { totalumPayments } from './payments/index.js';
+import { totalumPdf } from './pdf/index.js';
+import { totalumRealtime } from './realtime/index.js';
+import { totalumScan } from './scan/index.js';
+import { totalumSeo } from './seo/index.js';
+import { totalumSpeech } from './speech/index.js';
+import { totalumWeb } from './web/index.js';
+import { totalumWebhooks } from './webhooks/index.js';
+export * from './ai/index.js';
+export * from './analytics/index.js';
+export * from './browser/index.js';
+export * from './cron/index.js';
+export * from './d1/index.js';
+export * from './email/index.js';
+export * from './files/index.js';
+export * from './logs/index.js';
+export * from './payments/index.js';
+export * from './pdf/index.js';
+export * from './realtime/index.js';
+export * from './scan/index.js';
+export * from './seo/index.js';
+export * from './speech/index.js';
+export * from './web/index.js';
+export * from './webhooks/index.js';
+const namespaces = {
+    ai: totalumAi,
+    analytics: totalumAnalytics,
+    browser: totalumBrowser,
+    cron: totalumCron,
+    email: totalumEmail,
+    files: totalumFiles,
+    logs: totalumLogs,
+    payments: totalumPayments,
+    pdf: totalumPdf,
+    realtime: totalumRealtime,
+    scan: totalumScan,
+    seo: totalumSeo,
+    speech: totalumSpeech,
+    web: totalumWeb,
+    webhooks: totalumWebhooks,
+};
+/**
+ * Every integration namespace on one object (plan 05 §2.1), each built on first access with the same options — no I/O
+ * and no env read until a method is called. The database is `totalumD1()` from `totalum-sdk/d1`, not a namespace.
+ *
+ * @example
+ * const totalum = createTotalum({ env: 'dev' });
+ * await totalum.email.send({ to: 'a@b.c', subject: 'Hi', html: '<p>Hi</p>' });
+ */
+export function createTotalum(options = {}) {
+    const built = {};
+    const totalum = {};
+    for (const name of Object.keys(namespaces))
+        Object.defineProperty(totalum, name, {
+            enumerable: true,
+            get: () => (built[name] ??= namespaces[name](options)),
+        });
+    return totalum;
+}
+/** The default instance, configured from the environment (`TOTALUM_PROJECT_KEY`, `TOTALUM_SDK_API_URL`, `TOTALUM_ENV`). */
+export const totalum = /* @__PURE__ */ createTotalum();

package/dist/logs/index.d.ts

@@ -0,0 +1,51 @@
+import { c as LogsQueryInput } from '../_types/ops.d-C9375KIG.js';
+export { L as LogsPage } from '../_types/ops.d-C9375KIG.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';
+
+/** A `logs.query` filter: the window (default the last hour), level, substring, status class, path, request id, env. */
+type LogsQuery = Omit<LogsQueryInput, 'caller' | 'runId'>;
+/**
+ * `totalum.logs` (plan 05 §6.11) over SDK-API `/v1/logs` (scope `logs:read`; the agent's sandbox key reads its dev
+ * preview for free): the Worker invocations of the published app (`env: 'live'`) or the preview (`'dev'`). Free.
+ */
+declare function totalumLogs(options?: TotalumClientOptions): {
+    /**
+     * Up to `limit` (≤ 500) log lines, newest first; `window` is always the window actually searched.
+     *
+     * @example
+     * const { items } = await logs.query({ level: 'error', env: 'live' });
+     */
+    query: (q?: LogsQuery) => Promise<{
+        items: {
+            ts: string;
+            level: "error" | "log" | "debug" | "info" | "warn";
+            message: string;
+            requestId: string | null;
+            method: string | null;
+            path: string | null;
+            status: number | null;
+            cpuMs: number | null;
+            wallMs: number | null;
+            outcome: string;
+            exception?: {
+                name: string;
+                message: string;
+                stack?: string | undefined;
+            } | undefined;
+        }[];
+        window: {
+            from: string;
+            to: string;
+            source: "live" | "buffer";
+        };
+        nextCursor: string | null;
+        sampled: boolean;
+        hint?: string | undefined;
+    }>;
+};
+type TotalumLogs = ReturnType<typeof totalumLogs>;
+
+export { TotalumClientOptions, totalumLogs };
+export type { LogsQuery, TotalumLogs };

package/dist/logs/index.js

@@ -0,0 +1,18 @@
+import { jsonClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/**
+ * `totalum.logs` (plan 05 §6.11) over SDK-API `/v1/logs` (scope `logs:read`; the agent's sandbox key reads its dev
+ * preview for free): the Worker invocations of the published app (`env: 'live'`) or the preview (`'dev'`). Free.
+ */
+export function totalumLogs(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /**
+         * Up to `limit` (≤ 500) log lines, newest first; `window` is always the window actually searched.
+         *
+         * @example
+         * const { items } = await logs.query({ level: 'error', env: 'live' });
+         */
+        query: (q = {}) => call('POST', '/v1/logs/query', q),
+    };
+}

package/dist/payments/index.d.ts

@@ -0,0 +1,47 @@
+import { O as OnboardingLinkInput, C as CheckoutInput, g as CustomerPortalLinkInput } from '../_types/integrations.d-BNGV70e3.js';
+export { a as CheckoutOutput, h as CustomerPortalLinkOutput, o as OnboardingLinkOutput, P as PaymentsStatus } 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.payments` (plan 05, plan 11 §9.5) over SDK-API `/v1/payments/*` with a project key (scope `payments`): Stripe
+ * Connect direct charges on the project's own connected account. Card data never passes through here — send buyers to
+ * the hosted Checkout `url` (SAQ-A); SDK-API refuses card fields with `CARD_DATA_NOT_ACCEPTED`.
+ */
+declare function totalumPayments(options?: TotalumClientOptions): {
+    /** Whether the project's Stripe account can take payments (charges, payouts, pending requirements). */
+    getStatus: () => Promise<{
+        enabled: boolean;
+        mode: "connect" | "own_key";
+        accountId: string | null;
+        livemode: boolean;
+        chargesEnabled: boolean;
+        payoutsEnabled: boolean;
+        detailsSubmitted: boolean;
+        requirements: {
+            currentlyDue: string[];
+            pastDue: string[];
+            eventuallyDue: string[];
+        };
+        applicationFeeBps: number;
+    }>;
+    /** Stripe's hosted onboarding for the project owner (single use; never for the agent's sandbox key). */
+    onboardingLink: (input: OnboardingLinkInput) => Promise<{
+        url: string;
+        expiresAt: string;
+    }>;
+    /** A hosted Checkout Session: `payment`, `subscription`, or `setup` (save a card for later). Redirect to `url`. */
+    createCheckout: (input: CheckoutInput) => Promise<{
+        id: string;
+        url: string;
+    }>;
+    /** Stripe's hosted portal where a customer manages their subscriptions and saved cards. */
+    customerPortalLink: (input: CustomerPortalLinkInput) => Promise<{
+        url: string;
+    }>;
+};
+type TotalumPayments = ReturnType<typeof totalumPayments>;
+
+export { CheckoutInput, CustomerPortalLinkInput, OnboardingLinkInput, TotalumClientOptions, totalumPayments };
+export type { TotalumPayments };

package/dist/payments/index.js

@@ -0,0 +1,20 @@
+import { jsonClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/**
+ * `totalum.payments` (plan 05, plan 11 §9.5) over SDK-API `/v1/payments/*` with a project key (scope `payments`): Stripe
+ * Connect direct charges on the project's own connected account. Card data never passes through here — send buyers to
+ * the hosted Checkout `url` (SAQ-A); SDK-API refuses card fields with `CARD_DATA_NOT_ACCEPTED`.
+ */
+export function totalumPayments(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /** Whether the project's Stripe account can take payments (charges, payouts, pending requirements). */
+        getStatus: () => call('GET', '/v1/payments/status'),
+        /** Stripe's hosted onboarding for the project owner (single use; never for the agent's sandbox key). */
+        onboardingLink: (input) => call('POST', '/v1/payments/onboarding-link', input),
+        /** A hosted Checkout Session: `payment`, `subscription`, or `setup` (save a card for later). Redirect to `url`. */
+        createCheckout: (input) => call('POST', '/v1/payments/checkout', input),
+        /** Stripe's hosted portal where a customer manages their subscriptions and saved cards. */
+        customerPortalLink: (input) => call('POST', '/v1/payments/customer-portal-link', input),
+    };
+}

package/dist/pdf/index.d.ts

@@ -0,0 +1,42 @@
+import { p as PdfFromHtmlInput, q as PdfFromUrlInput } from '../_types/integrations.d-BNGV70e3.js';
+export { r as PdfOutput } 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.pdf` (plan 04 §5.5) over `/v1/pdf/*` (scope `files:write`): a new file in the project's storage each time. */
+declare function totalumPdf(options?: TotalumClientOptions): {
+    /**
+     * A PDF rendered from HTML, stored as a project file (`key`, `url`).
+     *
+     * @example
+     * const { url } = await pdf.fromHtml({ html: '<h1>Invoice 12</h1>', name: 'invoice-12' });
+     */
+    fromHtml: (input: PdfFromHtmlInput) => Promise<{
+        url: string;
+        fileName: string;
+        key: string;
+    } & {
+        usage: {
+            vendor?: string | undefined;
+            units?: number | undefined;
+            credits: number;
+        };
+    }>;
+    /** A PDF of a web page, stored as a project file. */
+    fromUrl: (input: PdfFromUrlInput) => Promise<{
+        url: string;
+        fileName: string;
+        key: string;
+    } & {
+        usage: {
+            vendor?: string | undefined;
+            units?: number | undefined;
+            credits: number;
+        };
+    }>;
+};
+type TotalumPdf = ReturnType<typeof totalumPdf>;
+
+export { PdfFromHtmlInput, PdfFromUrlInput, TotalumClientOptions, totalumPdf };
+export type { TotalumPdf };

package/dist/pdf/index.js

@@ -0,0 +1,17 @@
+import { envelopeClient, withUsage } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** `totalum.pdf` (plan 04 §5.5) over `/v1/pdf/*` (scope `files:write`): a new file in the project's storage each time. */
+export function totalumPdf(options = {}) {
+    const call = envelopeClient(options);
+    return {
+        /**
+         * A PDF rendered from HTML, stored as a project file (`key`, `url`).
+         *
+         * @example
+         * const { url } = await pdf.fromHtml({ html: '<h1>Invoice 12</h1>', name: 'invoice-12' });
+         */
+        fromHtml: async (input) => withUsage(await call('POST', '/v1/pdf/from-html', input)),
+        /** A PDF of a web page, stored as a project file. */
+        fromUrl: async (input) => withUsage(await call('POST', '/v1/pdf/from-url', input)),
+    };
+}

package/dist/react/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `totalum-sdk/react` (plan 06 §12.5, A6.33): the browser side of `totalum.realtime`. The page never holds a key: it
+ * asks the app's own server for a ticket (`POST ticketUrl {room}`, default `/api/realtime/ticket`), opens the room's
+ * socket, and on every drop — a Totalum deploy drops them all — re-tickets and reconnects with backoff. Presence is
+ * built on the same socket: `presence:*` messages plus a 30 s heartbeat (a room with present users stays awake).
+ */
+type RealtimeStatus = 'connecting' | 'open' | 'reconnecting' | 'closed';
+interface RealtimeMessage<T = unknown> {
+    id: string;
+    event: string;
+    identity: {
+        id: string;
+        name?: string;
+    };
+    data: T;
+    ts: string;
+}
+interface RealtimePeer<M = Record<string, unknown>> {
+    /** One per open socket: the same user in two tabs is two peers with the same `identity`. */
+    connectionId: string;
+    identity: {
+        id: string;
+        name?: string;
+    };
+    meta: M;
+}
+interface RealtimeChannelOptions<M = Record<string, unknown>> {
+    /** The app's route that mints the ticket; it receives `{ room }` and answers `{ url }` or `{ data: { url } }`. */
+    ticketUrl?: string;
+    /** Or mint the ticket yourself. */
+    getTicket?: (room: string) => Promise<{
+        url: string;
+    }>;
+    /** Announce this connection's presence with this metadata (name, colour…); `others` lists everyone else's. */
+    presence?: M;
+    /** Messages kept in memory, newest last (default 100). */
+    keep?: number;
+    /** Tests only. */
+    WebSocket?: typeof WebSocket;
+}
+interface RealtimeSnapshot<M = Record<string, unknown>> {
+    status: RealtimeStatus;
+    messages: RealtimeMessage[];
+    others: RealtimePeer<M>[];
+}
+/** One room, one socket; framework-free (the hook below is a thin wrapper). */
+declare class RealtimeChannel<M = Record<string, unknown>> {
+    readonly room: string;
+    private readonly options;
+    private ws;
+    private stopped;
+    private attempt;
+    private timer;
+    private heartbeat;
+    private readonly peers;
+    private readonly listeners;
+    private readonly connectionId;
+    private snapshot;
+    constructor(room: string, options?: RealtimeChannelOptions<M>);
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => RealtimeSnapshot<M>;
+    connect(): void;
+    /** Sends `data` to everyone in the room (you included); `false` when the socket is not open. */
+    publish: (data: unknown, event?: string) => boolean;
+    close(): void;
+    private open;
+    private ticket;
+    /** A drop is normal (every deploy drops every socket): re-ticket and reconnect, 0.5 s … 30 s apart. */
+    private retry;
+    private send;
+    private receive;
+    /** Peers whose socket dropped without a goodbye disappear after 75 s of silence. */
+    private expire;
+    private set;
+}
+/**
+ * A room in a client component: `status`, the `messages` received since it opened, `others` (with `presence`), and
+ * `publish(data, event?)`. Render `status === 'reconnecting'` as an ordinary state, not an error.
+ *
+ * @example
+ * const { messages, others, publish, status } = useRealtimeChannel(`chat:${roomId}`, { presence: { name } });
+ */
+declare function useRealtimeChannel<M = Record<string, unknown>>(room: string, options?: RealtimeChannelOptions<M>): {
+    publish: (data: unknown, event?: string) => boolean;
+    status: RealtimeStatus;
+    messages: RealtimeMessage[];
+    others: RealtimePeer<M>[];
+};
+
+export { RealtimeChannel, useRealtimeChannel };
+export type { RealtimeChannelOptions, RealtimeMessage, RealtimePeer, RealtimeSnapshot, RealtimeStatus };