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

package/dist/realtime/index.d.ts

@@ -0,0 +1,68 @@
+import { Z as ZodObject, d as ZodString, c as ZodOptional, h as ZodRecord, g as ZodUnknown, m as $strip, j as ZodBoolean, l as ZodInt, o as output, t as ZodISODateTime, T as TotalumClientOptions } from '../_types/errors.d-ZrZKjL3U.js';
+export { a as TotalumError, i as isTotalumError } from '../_types/errors.d-ZrZKjL3U.js';
+
+/** `POST /v1/realtime/tickets` (scope `realtime`). `ttl` is the join window in seconds, not the session length. */
+declare const RealtimeTicketInput: ZodObject<{
+    room: ZodString;
+    identity: ZodObject<{
+        id: ZodString;
+        name: ZodOptional<ZodString>;
+        metadata: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
+    }, $strip>;
+    permissions: ZodOptional<ZodObject<{
+        subscribe: ZodOptional<ZodBoolean>;
+        publish: ZodOptional<ZodBoolean>;
+    }, $strip>>;
+    ttl: ZodOptional<ZodInt>;
+}, $strip>;
+type RealtimeTicketInput = output<typeof RealtimeTicketInput>;
+declare const RealtimeTicketOutput: ZodObject<{
+    ticket: ZodString;
+    url: ZodString;
+    room: ZodString;
+    identity: ZodObject<{
+        id: ZodString;
+        name: ZodOptional<ZodString>;
+        metadata: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
+    }, $strip>;
+    permissions: ZodObject<{
+        subscribe: ZodBoolean;
+        publish: ZodBoolean;
+    }, $strip>;
+    expiresAt: ZodISODateTime;
+}, $strip>;
+type RealtimeTicketOutput = output<typeof RealtimeTicketOutput>;
+
+/**
+ * `totalum.realtime` server side (plan 05 §6.14.1) over SDK-API `/v1/realtime/*` (scope `realtime`). The app's own
+ * server mints a short-lived ticket after its own auth check and hands `{ticket, url}` to the page; the page opens the
+ * `wss://` `url` and never holds a key. A room costs awake room-minutes × 4, never connections or messages.
+ */
+declare function totalumRealtime(options?: TotalumClientOptions): {
+    /**
+     * A ticket for one room, one identity and one permission set (default subscribe only), valid to join for `ttl`
+     * seconds (5–300, default 60).
+     *
+     * @example
+     * const { url } = await realtime.ticket({ room: `chat:${orgId}`, identity: { id: user.id }, permissions: { publish: true } });
+     */
+    ticket: (input: RealtimeTicketInput) => Promise<{
+        ticket: string;
+        url: string;
+        room: string;
+        identity: {
+            id: string;
+            name?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        };
+        permissions: {
+            subscribe: boolean;
+            publish: boolean;
+        };
+        expiresAt: string;
+    }>;
+};
+type TotalumRealtime = ReturnType<typeof totalumRealtime>;
+
+export { RealtimeTicketInput, RealtimeTicketOutput, TotalumClientOptions, totalumRealtime };
+export type { TotalumRealtime };

package/dist/realtime/index.js

@@ -0,0 +1,20 @@
+import { jsonClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/**
+ * `totalum.realtime` server side (plan 05 §6.14.1) over SDK-API `/v1/realtime/*` (scope `realtime`). The app's own
+ * server mints a short-lived ticket after its own auth check and hands `{ticket, url}` to the page; the page opens the
+ * `wss://` `url` and never holds a key. A room costs awake room-minutes × 4, never connections or messages.
+ */
+export function totalumRealtime(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /**
+         * A ticket for one room, one identity and one permission set (default subscribe only), valid to join for `ttl`
+         * seconds (5–300, default 60).
+         *
+         * @example
+         * const { url } = await realtime.ticket({ room: `chat:${orgId}`, identity: { id: user.id }, permissions: { publish: true } });
+         */
+        ticket: (input) => call('POST', '/v1/realtime/tickets', input),
+    };
+}

package/dist/scan/index.d.ts

@@ -0,0 +1,46 @@
+import { S as ScanDocumentInput, s as ScanOcrInput } from '../_types/integrations.d-Cii20Vl4.js';
+export { t as ScanOcrOutput } 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';
+
+/** The v1 scan result: the extracted fields (one set per page with `processEveryPdfPageAsDifferentScan`) + `metadata`. */
+interface ScanDocumentResult {
+    data: Record<string, unknown> | Record<string, unknown>[];
+    metadata: {
+        usageUnits: number;
+        exactUsageUnits: number;
+        pages: number;
+        provider: string;
+        credits: number;
+    };
+}
+/** `totalum.scan` (plan 05 §6.7) over `/v1/scan/*` (scope `scan`): a vision model through Totalum's AI gateway. */
+declare function totalumScan(options?: TotalumClientOptions): {
+    /** Extracts the fields described by `properties` from a document or image (one set per page on request). */
+    document: (input: ScanDocumentInput) => Promise<ScanDocumentResult>;
+    /** The text of a document or image, per page as Markdown. */
+    ocr: (input: ScanOcrInput) => Promise<{
+        text: string;
+        pages: {
+            markdown: string;
+            width: number;
+            height: number;
+            words?: {
+                text: string;
+                bbox: number[];
+            }[] | undefined;
+        }[];
+        fullDetails?: unknown;
+    } & {
+        usage: {
+            vendor?: string | undefined;
+            units?: number | undefined;
+            credits: number;
+        };
+    }>;
+};
+type TotalumScan = ReturnType<typeof totalumScan>;
+
+export { ScanDocumentInput, ScanOcrInput, TotalumClientOptions, totalumScan };
+export type { ScanDocumentResult, TotalumScan };

package/dist/scan/index.js

@@ -0,0 +1,12 @@
+import { envelopeClient, withUsage } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** `totalum.scan` (plan 05 §6.7) over `/v1/scan/*` (scope `scan`): a vision model through Totalum's AI gateway. */
+export function totalumScan(options = {}) {
+    const call = envelopeClient(options);
+    return {
+        /** Extracts the fields described by `properties` from a document or image (one set per page on request). */
+        document: async (input) => (await call('POST', '/v1/scan/document', input)),
+        /** The text of a document or image, per page as Markdown. */
+        ocr: async (input) => withUsage(await call('POST', '/v1/scan/ocr', input)),
+    };
+}

package/dist/seo/index.d.ts

@@ -0,0 +1,23 @@
+export { w as SeoIndexNowKey, x as SeoNotifyOutput } 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.seo` (plan 05 §6.10) over SDK-API `/v1/seo/*` (scope `seo`): IndexNow for verified custom domains, free. */
+declare function totalumSeo(options?: TotalumClientOptions): {
+    /** Tells search engines (IndexNow) that these URLs of the project's custom domains changed. */
+    notifyChanged: (urls: string[]) => Promise<{
+        accepted: number;
+        indexNow: "error" | "sent" | "skipped_no_custom_domain";
+        sitemapsPinged: boolean;
+    }>;
+    /** The key the template serves at `/<key>.txt`. */
+    indexNowKey: () => Promise<{
+        key: string;
+        keyLocation: string;
+    }>;
+};
+type TotalumSeo = ReturnType<typeof totalumSeo>;
+
+export { TotalumClientOptions, totalumSeo };
+export type { TotalumSeo };

package/dist/seo/index.js

@@ -0,0 +1,12 @@
+import { jsonClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** `totalum.seo` (plan 05 §6.10) over SDK-API `/v1/seo/*` (scope `seo`): IndexNow for verified custom domains, free. */
+export function totalumSeo(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /** Tells search engines (IndexNow) that these URLs of the project's custom domains changed. */
+        notifyChanged: (urls) => call('POST', '/v1/seo/notify-changed', { urls }),
+        /** The key the template serves at `/<key>.txt`. */
+        indexNowKey: () => call('GET', '/v1/seo/indexnow-key'),
+    };
+}

package/dist/speech/index.d.ts

@@ -0,0 +1,41 @@
+import { T as TranscribeInput, y as SpeakInput, z as StoredMedia } from '../_types/integrations.d-Cii20Vl4.js';
+export { A as TranscribeOutput } 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.speech` (plan 05 §6.8) over `/v1/speech/*` (scope `speech`): OpenRouter speech through Totalum. */
+declare function totalumSpeech(options?: TotalumClientOptions): {
+    /** Speech to text from `audioBase64` or a `url`; optional language, word timestamps and speakers. */
+    transcribe: (input: TranscribeInput) => Promise<{
+        text: string;
+        durationSec: number;
+        usage: {
+            credits: number;
+            vendor?: string | undefined;
+            units?: number | undefined;
+            vendorCostUsd?: number | undefined;
+        };
+        language?: string | undefined;
+        segments?: {
+            start: number;
+            end: number;
+            text: string;
+        }[] | undefined;
+        words?: {
+            word: string;
+            start: number;
+            end: number;
+        }[] | undefined;
+    }>;
+    /** The audio bytes, or with `store: true` the stored file `{key, url, usage}`; `credits` is the call's hold. */
+    synthesize: (input: SpeakInput) => Promise<StoredMedia | {
+        audio: ArrayBuffer;
+        contentType: string;
+        credits: number;
+    }>;
+};
+type TotalumSpeech = ReturnType<typeof totalumSpeech>;
+
+export { SpeakInput, StoredMedia, TotalumClientOptions, TranscribeInput, totalumSpeech };
+export type { TotalumSpeech };

package/dist/speech/index.js

@@ -0,0 +1,22 @@
+import { jsonClient, rawClient } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** `totalum.speech` (plan 05 §6.8) over `/v1/speech/*` (scope `speech`): OpenRouter speech through Totalum. */
+export function totalumSpeech(options = {}) {
+    const call = jsonClient(options);
+    const raw = rawClient(options);
+    return {
+        /** Speech to text from `audioBase64` or a `url`; optional language, word timestamps and speakers. */
+        transcribe: (input) => call('POST', '/v1/speech/transcribe', input),
+        /** The audio bytes, or with `store: true` the stored file `{key, url, usage}`; `credits` is the call's hold. */
+        synthesize: async (input) => {
+            if (input.store)
+                return call('POST', '/v1/speech/speak', input);
+            const res = await raw('/v1/speech/speak', input);
+            return {
+                audio: await res.arrayBuffer(),
+                contentType: res.headers.get('content-type') ?? 'audio/mpeg',
+                credits: Number(res.headers.get('x-totalum-credits') ?? 0),
+            };
+        },
+    };
+}

package/dist/web/index.d.ts

@@ -0,0 +1,170 @@
+import { G as WebScrapeInput, H as WebSearchInput, I as WebMapInput, K as WebCrawlInput, u as ScreenshotInput } from '../_types/integrations.d-Cii20Vl4.js';
+export { J as JobCreated, v as ScreenshotOutput, W as WebJob, B as WebScrapeOutput, D as WebSearchOutput } 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.web` (plan 05 §6.2) over SDK-API `/v1/web/*` (scope `web`): Firecrawl scrape/search/map/crawl and Browser
+ * Run screenshots, charged provider cost × 28 — every result carries `usage.credits`.
+ */
+declare function totalumWeb(options?: TotalumClientOptions): {
+    /**
+     * One page as `markdown`, `html`, `links`, … (Firecrawl).
+     *
+     * @example
+     * const { markdown } = await web.scrape('https://example.com', { formats: ['markdown'] });
+     */
+    scrape: (url: string, opts?: Omit<WebScrapeInput, "url">) => Promise<{
+        url: string;
+        statusCode: number;
+        metadata: {
+            sourceURL: string;
+            title?: string | undefined;
+            description?: string | undefined;
+            language?: string | undefined;
+        };
+        usage: {
+            credits: number;
+            vendor?: string | undefined;
+            units?: number | undefined;
+            vendorCostUsd?: number | undefined;
+        };
+        markdown?: string | undefined;
+        html?: string | undefined;
+        rawHtml?: string | undefined;
+        links?: string[] | undefined;
+        screenshotUrl?: string | undefined;
+        json?: unknown;
+        summary?: string | undefined;
+        contentUrl?: string | undefined;
+    }>;
+    /** A web search; with `scrapeOptions` each result also carries its page content. */
+    search: (query: string, opts?: Omit<WebSearchInput, "query">) => Promise<{
+        web: {
+            title: string;
+            url: string;
+            position: number;
+            snippet?: string | undefined;
+        }[];
+        news?: {
+            title: string;
+            url: string;
+            position: number;
+            snippet?: string | undefined;
+        }[] | undefined;
+        images?: Record<string, unknown>[] | undefined;
+        scraped?: {
+            url: string;
+            statusCode: number;
+            metadata: {
+                sourceURL: string;
+                title?: string | undefined;
+                description?: string | undefined;
+                language?: string | undefined;
+            };
+            markdown?: string | undefined;
+            html?: string | undefined;
+            rawHtml?: string | undefined;
+            links?: string[] | undefined;
+            screenshotUrl?: string | undefined;
+            json?: unknown;
+            summary?: string | undefined;
+            contentUrl?: string | undefined;
+        }[] | undefined;
+    } & {
+        usage: {
+            vendor?: string | undefined;
+            units?: number | undefined;
+            credits: number;
+        };
+    }>;
+    /** The URLs of a site (sitemap and links), without fetching the pages. */
+    map: (url: string, opts?: Omit<WebMapInput, "url">) => Promise<{
+        links: string[];
+    } & {
+        usage: {
+            vendor?: string | undefined;
+            units?: number | undefined;
+            credits: number;
+        };
+    }>;
+    /** `202 {jobId}`: poll `crawlStatus` until the job leaves `running`; that read settles its charge. */
+    crawl: (url: string, opts?: Omit<WebCrawlInput, "url">) => Promise<{
+        jobId: string;
+        estimatedCredits?: number | undefined;
+    }>;
+    /** The crawl job: `status`, pages so far and their content. */
+    crawlStatus: (jobId: string) => Promise<{
+        jobId: string;
+        status: "queued" | "running" | "completed" | "failed" | "cancelled" | "expired";
+        total: number;
+        completed: number;
+        creditsUsed: number;
+        data: {
+            url: string;
+            statusCode: number;
+            metadata: {
+                sourceURL: string;
+                title?: string | undefined;
+                description?: string | undefined;
+                language?: string | undefined;
+            };
+            markdown?: string | undefined;
+            html?: string | undefined;
+            rawHtml?: string | undefined;
+            links?: string[] | undefined;
+            screenshotUrl?: string | undefined;
+            json?: unknown;
+            summary?: string | undefined;
+            contentUrl?: string | undefined;
+        }[];
+        next?: string | undefined;
+        resultUrl?: string | undefined;
+    }>;
+    /** Stops a running crawl; pages already crawled are charged. */
+    cancelCrawl: (jobId: string) => Promise<{
+        jobId: string;
+        status: "queued" | "running" | "completed" | "failed" | "cancelled" | "expired";
+        total: number;
+        completed: number;
+        creditsUsed: number;
+        data: {
+            url: string;
+            statusCode: number;
+            metadata: {
+                sourceURL: string;
+                title?: string | undefined;
+                description?: string | undefined;
+                language?: string | undefined;
+            };
+            markdown?: string | undefined;
+            html?: string | undefined;
+            rawHtml?: string | undefined;
+            links?: string[] | undefined;
+            screenshotUrl?: string | undefined;
+            json?: unknown;
+            summary?: string | undefined;
+            contentUrl?: string | undefined;
+        }[];
+        next?: string | undefined;
+        resultUrl?: string | undefined;
+    }>;
+    /** A screenshot of a `url` or of inline `html`, stored as a project file (`key`, `url`). */
+    screenshot: (input: ScreenshotInput) => Promise<{
+        key: string;
+        url: string;
+        format: "png" | "jpeg" | "webp";
+        base64?: string | undefined;
+    } & {
+        usage: {
+            vendor?: string | undefined;
+            units?: number | undefined;
+            credits: number;
+        };
+    }>;
+};
+type TotalumWeb = ReturnType<typeof totalumWeb>;
+
+export { ScreenshotInput, TotalumClientOptions, totalumWeb };
+export type { TotalumWeb };

package/dist/web/index.js

@@ -0,0 +1,31 @@
+import { envelopeClient, withUsage } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/**
+ * `totalum.web` (plan 05 §6.2) over SDK-API `/v1/web/*` (scope `web`): Firecrawl scrape/search/map/crawl and Browser
+ * Run screenshots, charged provider cost × 28 — every result carries `usage.credits`.
+ */
+export function totalumWeb(options = {}) {
+    const call = envelopeClient(options);
+    const job = (jobId) => `/v1/web/jobs/${encodeURIComponent(jobId)}`;
+    return {
+        /**
+         * One page as `markdown`, `html`, `links`, … (Firecrawl).
+         *
+         * @example
+         * const { markdown } = await web.scrape('https://example.com', { formats: ['markdown'] });
+         */
+        scrape: async (url, opts = {}) => (await call('POST', '/v1/web/scrape', { ...opts, url })).data,
+        /** A web search; with `scrapeOptions` each result also carries its page content. */
+        search: async (query, opts = {}) => withUsage(await call('POST', '/v1/web/search', { ...opts, query })),
+        /** The URLs of a site (sitemap and links), without fetching the pages. */
+        map: async (url, opts = {}) => withUsage(await call('POST', '/v1/web/map', { ...opts, url })),
+        /** `202 {jobId}`: poll `crawlStatus` until the job leaves `running`; that read settles its charge. */
+        crawl: async (url, opts = {}) => (await call('POST', '/v1/web/crawl', { ...opts, url })).data,
+        /** The crawl job: `status`, pages so far and their content. */
+        crawlStatus: async (jobId) => (await call('GET', job(jobId))).data,
+        /** Stops a running crawl; pages already crawled are charged. */
+        cancelCrawl: async (jobId) => (await call('DELETE', job(jobId))).data,
+        /** A screenshot of a `url` or of inline `html`, stored as a project file (`key`, `url`). */
+        screenshot: async (input) => withUsage(await call('POST', '/v1/web/screenshot', input)),
+    };
+}

package/dist/webhooks/index.d.ts

@@ -0,0 +1,48 @@
+import { a as WebhookEvent } from '../_types/billing.d-Cj9gNbAW.js';
+export { W as WebhookConfig, b as WebhookSecretOutput } from '../_types/billing.d-Cj9gNbAW.js';
+import { T as TotalumClientOptions, a as TotalumError } from '../_types/errors.d-ZrZKjL3U.js';
+export { i as isTotalumError } from '../_types/errors.d-ZrZKjL3U.js';
+
+/** A webhook refusal (plan 05 §7.2): the codes never travel, the app answers 400. */
+declare class TotalumWebhookError extends TotalumError {
+    name: string;
+    readonly errorCode: 'WEBHOOK_SECRET_MISSING' | 'WEBHOOK_SIGNATURE_INVALID' | 'WEBHOOK_TIMESTAMP_EXPIRED';
+    constructor(errorCode: TotalumWebhookError['errorCode'], message: string);
+}
+/**
+ * `totalum.webhooks.verify` (plan 04 §5.13): checks `Totalum-Signature: t=…,v1=…` — HMAC-SHA256 keyed with the
+ * endpoint's secret string over `${t}.${rawBody}` — within ±300 s, and returns the parsed event. Pass the body exactly
+ * as received (`await request.text()`). `secret` defaults to `TOTALUM_WEBHOOK_SECRET`.
+ *
+ * @example
+ * const event = await verifyWebhook(await request.text(), request.headers);
+ */
+declare function verifyWebhook(rawBody: string, headers: Headers | Record<string, string | undefined>, secret?: string | undefined, now?: number): Promise<WebhookEvent>;
+/**
+ * `totalum.webhooks` (plan 04 §5.13) over SDK-API `/v1/webhooks` (a key with scope `*`): where the project receives its
+ * signed events (payments, e-mail, browser programs, `project.credits.exhausted`) and the secret they are signed with.
+ */
+declare function totalumWebhooks(options?: TotalumClientOptions): {
+    /** Same as `verifyWebhook`: checks `Totalum-Signature` and returns the parsed event. */
+    verify: typeof verifyWebhook;
+    /** The endpoint and the first characters of its secret (the secret itself is shown only by `rotateSecret`). */
+    get: () => Promise<{
+        url: string | null;
+        enabled: boolean;
+        secretPrefix: string | null;
+    }>;
+    /** Sets the `https://` URL the project's events are delivered to. */
+    setUrl: (url: string) => Promise<{
+        url: string | null;
+        enabled: boolean;
+        secretPrefix: string | null;
+    }>;
+    /** A new signing secret, shown once; the old one keeps co-signing for 24 h. Store it as `TOTALUM_WEBHOOK_SECRET`. */
+    rotateSecret: () => Promise<{
+        secret: string;
+    }>;
+};
+type TotalumWebhooks = ReturnType<typeof totalumWebhooks>;
+
+export { TotalumClientOptions, TotalumError, TotalumWebhookError, WebhookEvent, totalumWebhooks, verifyWebhook };
+export type { TotalumWebhooks };

package/dist/webhooks/index.js

@@ -0,0 +1,61 @@
+import { TotalumError } from '../errors.js';
+import { jsonClient, readEnv } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** Literals type-locked to contracts, so the published package imports nothing at runtime (plan 05 §1). */
+const SIGNATURE_HEADER = 'Totalum-Signature';
+const TOLERANCE_SECONDS = 300;
+/** A webhook refusal (plan 05 §7.2): the codes never travel, the app answers 400. */
+export class TotalumWebhookError extends TotalumError {
+    name = 'TotalumWebhookError';
+    constructor(errorCode, message) {
+        super(errorCode, message, errorCode === 'WEBHOOK_SECRET_MISSING' ? 500 : 401);
+    }
+}
+const enc = new TextEncoder();
+/**
+ * `totalum.webhooks.verify` (plan 04 §5.13): checks `Totalum-Signature: t=…,v1=…` — HMAC-SHA256 keyed with the
+ * endpoint's secret string over `${t}.${rawBody}` — within ±300 s, and returns the parsed event. Pass the body exactly
+ * as received (`await request.text()`). `secret` defaults to `TOTALUM_WEBHOOK_SECRET`.
+ *
+ * @example
+ * const event = await verifyWebhook(await request.text(), request.headers);
+ */
+export async function verifyWebhook(rawBody, headers, secret = readEnv('TOTALUM_WEBHOOK_SECRET'), now = Date.now()) {
+    if (!secret)
+        throw new TotalumWebhookError('WEBHOOK_SECRET_MISSING', 'Set TOTALUM_WEBHOOK_SECRET or pass the secret.');
+    const name = SIGNATURE_HEADER;
+    const header = headers instanceof Headers ? headers.get(name) : (headers[name] ?? headers[name.toLowerCase()] ?? null);
+    const parts = (header ?? '').split(',').map((p) => p.split('=', 2));
+    const t = Number(parts.find(([k]) => k === 't')?.[1]);
+    if (!Number.isInteger(t))
+        throw new TotalumWebhookError('WEBHOOK_SIGNATURE_INVALID', 'Missing Totalum-Signature');
+    if (Math.abs(now / 1000 - t) > TOLERANCE_SECONDS)
+        throw new TotalumWebhookError('WEBHOOK_TIMESTAMP_EXPIRED', 'Signature timestamp outside ±300 s');
+    const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const payload = enc.encode(`${String(t)}.${rawBody}`);
+    for (const [k, v] of parts) {
+        if (k !== 'v1' || !v || !/^[0-9a-f]{64}$/.test(v))
+            continue;
+        const sig = new Uint8Array(v.match(/../g)?.map((h) => parseInt(h, 16)) ?? []);
+        if (await crypto.subtle.verify('HMAC', key, sig, payload))
+            return JSON.parse(rawBody);
+    }
+    throw new TotalumWebhookError('WEBHOOK_SIGNATURE_INVALID', 'Totalum-Signature does not match');
+}
+/**
+ * `totalum.webhooks` (plan 04 §5.13) over SDK-API `/v1/webhooks` (a key with scope `*`): where the project receives its
+ * signed events (payments, e-mail, browser programs, `project.credits.exhausted`) and the secret they are signed with.
+ */
+export function totalumWebhooks(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /** Same as `verifyWebhook`: checks `Totalum-Signature` and returns the parsed event. */
+        verify: verifyWebhook,
+        /** The endpoint and the first characters of its secret (the secret itself is shown only by `rotateSecret`). */
+        get: () => call('GET', '/v1/webhooks'),
+        /** Sets the `https://` URL the project's events are delivered to. */
+        setUrl: (url) => call('PUT', '/v1/webhooks', { url }),
+        /** A new signing secret, shown once; the old one keeps co-signing for 24 h. Store it as `TOTALUM_WEBHOOK_SECRET`. */
+        rotateSecret: () => call('POST', '/v1/webhooks/rotate-secret'),
+    };
+}