totalum-sdk 0.1.0-dev.10

package/dist/react/index.js

@@ -0,0 +1,178 @@
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+const HEARTBEAT_MS = 30_000;
+const STALE_MS = 75_000;
+const PRESENCE = 'presence:';
+/** One room, one socket; framework-free (the hook below is a thin wrapper). */
+export class RealtimeChannel {
+    room;
+    options;
+    ws;
+    stopped = true;
+    attempt = 0;
+    timer;
+    heartbeat;
+    peers = new Map();
+    listeners = new Set();
+    connectionId = crypto.randomUUID();
+    snapshot = { status: 'closed', messages: [], others: [] };
+    constructor(room, options = {}) {
+        this.room = room;
+        this.options = options;
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    getSnapshot = () => this.snapshot;
+    connect() {
+        if (!this.stopped)
+            return;
+        this.stopped = false;
+        this.set({ status: 'connecting' });
+        void this.open();
+        if (this.options.presence)
+            this.heartbeat = setInterval(() => {
+                this.send(`${PRESENCE}here`, this.options.presence);
+                this.expire();
+            }, HEARTBEAT_MS);
+    }
+    /** Sends `data` to everyone in the room (you included); `false` when the socket is not open. */
+    publish = (data, event = 'message') => this.send(event, data);
+    close() {
+        if (this.options.presence)
+            this.send(`${PRESENCE}leave`, null);
+        this.stopped = true;
+        clearTimeout(this.timer);
+        clearInterval(this.heartbeat);
+        this.ws?.close(1000, 'closed');
+        this.ws = undefined;
+        this.peers.clear();
+        this.set({ status: 'closed', others: [] });
+    }
+    async open() {
+        try {
+            const { url } = await this.ticket();
+            if (this.stopped)
+                return;
+            const ws = new (this.options.WebSocket ?? WebSocket)(url);
+            this.ws = ws;
+            ws.addEventListener('open', () => {
+                this.attempt = 0;
+                this.set({ status: 'open' });
+                if (this.options.presence)
+                    this.send(`${PRESENCE}join`, this.options.presence);
+            });
+            ws.addEventListener('message', (e) => {
+                this.receive(String(e.data));
+            });
+            ws.addEventListener('close', () => {
+                if (this.ws === ws)
+                    this.retry();
+            });
+        }
+        catch {
+            this.retry();
+        }
+    }
+    async ticket() {
+        if (this.options.getTicket)
+            return this.options.getTicket(this.room);
+        const res = await fetch(this.options.ticketUrl ?? '/api/realtime/ticket', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ room: this.room }),
+        });
+        if (!res.ok)
+            throw new Error(`ticket ${String(res.status)}`);
+        const body = await res.json();
+        const { url, data } = body;
+        return { url: url ?? data?.url ?? '' };
+    }
+    /** A drop is normal (every deploy drops every socket): re-ticket and reconnect, 0.5 s … 30 s apart. */
+    retry() {
+        this.ws = undefined;
+        if (this.stopped)
+            return;
+        this.peers.clear();
+        this.set({ status: 'reconnecting', others: [] });
+        const delay = Math.min(30_000, 500 * 2 ** this.attempt++) * (0.75 + Math.random() / 2);
+        this.timer = setTimeout(() => void this.open(), delay);
+    }
+    send(event, data) {
+        if (this.ws?.readyState !== 1)
+            return false;
+        const payload = event.startsWith(PRESENCE) ? { connectionId: this.connectionId, meta: data } : data;
+        this.ws.send(JSON.stringify({ type: 'publish', event, data: payload }));
+        return true;
+    }
+    receive(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (frame.type !== 'message' || !frame.event || !frame.identity)
+            return;
+        if (!frame.event.startsWith(PRESENCE)) {
+            const keep = this.options.keep ?? 100;
+            this.set({ messages: [...this.snapshot.messages, frame].slice(-keep) });
+            return;
+        }
+        const { connectionId, meta } = (frame.data ?? {});
+        if (!this.options.presence || !connectionId || connectionId === this.connectionId)
+            return;
+        if (frame.event === `${PRESENCE}leave`)
+            this.peers.delete(connectionId);
+        else {
+            // a newcomer learns who is already here
+            if (frame.event === `${PRESENCE}join`)
+                this.send(`${PRESENCE}here`, this.options.presence);
+            this.peers.set(connectionId, {
+                connectionId,
+                identity: frame.identity,
+                meta: meta,
+                seen: Date.now(),
+            });
+        }
+        this.expire();
+    }
+    /** Peers whose socket dropped without a goodbye disappear after 75 s of silence. */
+    expire() {
+        for (const [id, peer] of this.peers)
+            if (Date.now() - peer.seen > STALE_MS)
+                this.peers.delete(id);
+        const others = [...this.peers.values()].map(({ connectionId, identity, meta }) => ({
+            connectionId,
+            identity,
+            meta,
+        }));
+        this.set({ others });
+    }
+    set(patch) {
+        this.snapshot = { ...this.snapshot, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+const SERVER = { status: 'connecting', messages: [], others: [] };
+/**
+ * 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 } });
+ */
+export function useRealtimeChannel(room, options = {}) {
+    // one channel per room; the options of its first render are the ones it keeps
+    const channel = useMemo(() => new RealtimeChannel(room, options), [room]);
+    useEffect(() => {
+        channel.connect();
+        return () => {
+            channel.close();
+        };
+    }, [channel]);
+    const snapshot = useSyncExternalStore(channel.subscribe, channel.getSnapshot, () => SERVER);
+    return { ...snapshot, publish: channel.publish };
+}

package/dist/realtime/index.d.ts

@@ -0,0 +1,103 @@
+import { Z as ZodObject, c as ZodOptional, d as ZodString, g as ZodUnknown, m as $strip, o as output, t as ZodISODateTime, l as ZodInt, h as ZodRecord, j as ZodBoolean, 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';
+
+/** `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>;
+/**
+ * `POST /v1/realtime/rooms/:room/publish` (scope `realtime`; plan 04 §5.16): server-side publish over HTTPS from the
+ * app's own routes or a cron job. The room is resolved inside the key's project (A8.6); `identity` defaults to
+ * `{id: 'server'}`. Answers `202`.
+ */
+declare const RealtimePublishInput: ZodObject<{
+    event: ZodOptional<ZodString>;
+    data: ZodUnknown;
+    identity: ZodOptional<ZodObject<{
+        id: ZodString;
+        name: ZodOptional<ZodString>;
+    }, $strip>>;
+}, $strip>;
+type RealtimePublishInput = output<typeof RealtimePublishInput>;
+/** The delivery confirmation: the message id and the number of sockets it was fanned out to. */
+declare const RealtimePublishOutput: ZodObject<{
+    messageId: ZodString;
+    at: ZodISODateTime;
+    connections: ZodInt;
+}, $strip>;
+type RealtimePublishOutput = output<typeof RealtimePublishOutput>;
+
+/**
+ * `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;
+    }>;
+    /**
+     * Publishes one message to every socket subscribed to `room`, from the app's own server (a route handler, a cron
+     * job): no socket needed. Subscribers receive the same `message` frame a socket publish sends, with `event`
+     * (default `message`) and `identity` (default `{ id: 'server' }`). Resolves with the message id, its timestamp
+     * and the number of sockets it was sent to (`0` when nobody is connected — it is not queued).
+     *
+     * @example
+     * const { connections } = await realtime.publish(`orders:${shopId}`, { event: 'order.created', data: { orderId } });
+     */
+    publish: (room: string, input: RealtimePublishInput) => Promise<{
+        messageId: string;
+        at: string;
+        connections: number;
+    }>;
+};
+type TotalumRealtime = ReturnType<typeof totalumRealtime>;
+
+export { RealtimePublishInput, RealtimePublishOutput, RealtimeTicketInput, RealtimeTicketOutput, TotalumClientOptions, totalumRealtime };
+export type { TotalumRealtime };

package/dist/realtime/index.js

@@ -0,0 +1,30 @@
+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),
+        /**
+         * Publishes one message to every socket subscribed to `room`, from the app's own server (a route handler, a cron
+         * job): no socket needed. Subscribers receive the same `message` frame a socket publish sends, with `event`
+         * (default `message`) and `identity` (default `{ id: 'server' }`). Resolves with the message id, its timestamp
+         * and the number of sockets it was sent to (`0` when nobody is connected — it is not queued).
+         *
+         * @example
+         * const { connections } = await realtime.publish(`orders:${shopId}`, { event: 'order.created', data: { orderId } });
+         */
+        publish: (room, input) => call('POST', `/v1/realtime/rooms/${encodeURIComponent(room)}/publish`, input),
+    };
+}

package/dist/scan/index.d.ts

@@ -0,0 +1,46 @@
+import { S as ScanDocumentInput, s as ScanOcrInput } from '../_types/integrations.d-BNGV70e3.js';
+export { t as ScanOcrOutput } 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';
+
+/** 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-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.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-BNGV70e3.js';
+export { A as TranscribeOutput } 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.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-BNGV70e3.js';
+export { J as JobCreated, v as ScreenshotOutput, W as WebJob, B as WebScrapeOutput, D as WebSearchOutput } 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.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)),
+    };
+}