totalum-sdk 0.1.0-dev.10

package/dist/ai/index.js

@@ -0,0 +1,185 @@
+import { assertNode, TotalumError } from '../errors.js';
+import { jsonClient, projectKey, rawClient, readEnv } from '../http.js';
+import { totalumSpeech } from '../speech/index.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+const resultOf = (c) => ({
+    id: c.id ?? '',
+    model: c.model ?? '',
+    text: c.choices?.[0]?.message?.content ?? '',
+    toolCalls: c.choices?.[0]?.message?.tool_calls ?? [],
+    finishReason: c.choices?.[0]?.finish_reason ?? null,
+    usage: {
+        inputTokens: c.usage?.prompt_tokens ?? 0,
+        outputTokens: c.usage?.completion_tokens ?? 0,
+        costUsd: c.usage?.costUsd ?? 0,
+        credits: c.usage?.credits ?? 0,
+    },
+    raw: c,
+});
+/** SSE `data:` payloads of a stream, in order (`[DONE]` ends it). */
+async function* events(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (!done)
+            pending += decoder.decode(value, { stream: true });
+        let end = pending.indexOf('\n\n');
+        while (end !== -1) {
+            const data = /^data:\s*(.*)$/m.exec(pending.slice(0, end))?.[1]?.trim() ?? '';
+            pending = pending.slice(end + 2);
+            end = pending.indexOf('\n\n');
+            if (data === '[DONE]')
+                return;
+            if (data.startsWith('{'))
+                yield JSON.parse(data);
+        }
+        if (done)
+            return;
+    }
+}
+function chatStream(body) {
+    const [raw, parsed] = body.tee();
+    const acc = { text: '', choices: [{ message: {} }] };
+    let credits = 0;
+    const source = (async function* () {
+        for await (const e of events(parsed)) {
+            const totalum = e.totalum;
+            if (totalum) {
+                credits = totalum.credits ?? 0;
+                continue;
+            }
+            const chunk = e;
+            if (!acc.id && chunk.id)
+                acc.id = chunk.id;
+            if (!acc.model && chunk.model)
+                acc.model = chunk.model;
+            if (chunk.usage)
+                acc.usage = chunk.usage;
+            const choice = chunk.choices?.[0];
+            if (choice?.finish_reason && acc.choices?.[0])
+                acc.choices[0].finish_reason = choice.finish_reason;
+            const delta = choice?.delta?.content;
+            if (delta) {
+                acc.text += delta;
+                yield delta;
+            }
+        }
+    })();
+    const drain = async () => {
+        while (!(await source.next()).done) {
+            /* read to the end: the usage and credits chunks come last */
+        }
+    };
+    return {
+        raw,
+        /** The text deltas as they arrive (one pass; `result()` afterwards reads the rest). */
+        text: () => source,
+        async result() {
+            await drain();
+            const r = resultOf({
+                ...acc,
+                choices: [{ message: { content: acc.text }, finish_reason: acc.choices?.[0]?.finish_reason ?? null }],
+            });
+            return { ...r, usage: { ...r.usage, costUsd: acc.usage?.costUsd ?? 0, credits } };
+        },
+    };
+}
+/**
+ * `totalum.ai` (plan 05 §6.1, plan 04 §5.1) over SDK-API `/v1/ai/*` (scope `ai`): aliases `cheap|normal|best` or any
+ * OpenRouter slug, every call priced `usage.cost × 28` and returned with its credits. No `ai.agent()` (A5.27) — the
+ * agent loop is the template's `src/agents/` on the Vercel AI SDK, pointed at `gatewayConfig()`.
+ */
+export function totalumAi(options = {}) {
+    const call = jsonClient(options);
+    const raw = rawClient(options);
+    const speech = totalumSpeech(options);
+    /**
+     * A chat completion; `model` is an alias (`cheap`, `normal`, `best`) or any OpenRouter slug.
+     *
+     * @example
+     * const { text } = await ai.chat({ model: 'cheap', messages: [{ role: 'user', content: 'Hi' }] });
+     */
+    const chat = Object.assign(async (req) => resultOf(await call('POST', '/v1/ai/chat', { ...req, stream: false })), {
+        /**
+         * The same request streamed: `raw` is the OpenAI-format SSE (return it from a route), `text()` its deltas,
+         * `result()` the final result with its credits.
+         */
+        stream: async (req) => {
+            const res = await raw('/v1/ai/chat', { ...req, stream: true });
+            if (!res.body)
+                throw new TotalumError('RESPONSE_PARSE_ERROR', 'The chat stream has no body', res.status);
+            return chatStream(res.body);
+        },
+    });
+    const videoJob = (jobId) => call('GET', `/v1/ai/video/${encodeURIComponent(jobId)}`);
+    /** A JSON object matching `schema` (JSON Schema). */
+    const generateObject = (req) => call('POST', '/v1/ai/object', req);
+    return {
+        chat,
+        generateObject,
+        /** Sugar over `generateObject`: one of `options`, chosen by the model. */
+        async classify(req) {
+            const { object } = await generateObject({
+                ...(req.model ? { model: req.model } : {}),
+                prompt: `${req.instructions ?? 'Classify the input into exactly one label.'}\n\nInput:\n${req.input}`,
+                schema: {
+                    type: 'object',
+                    properties: { label: { type: 'string', enum: [...req.options] } },
+                    required: ['label'],
+                    additionalProperties: false,
+                },
+            });
+            const label = object?.label;
+            return { label: typeof label === 'string' ? label : '' };
+        },
+        /** Embedding vectors for one or more texts. */
+        embed: (req) => call('POST', '/v1/ai/embed', req),
+        image: {
+            /** Images from a prompt; `store: true` keeps them as project files. */
+            generate: (req) => call('POST', '/v1/ai/image', req),
+            /** An image edited by a prompt. */
+            edit: (req) => call('POST', '/v1/ai/image/edit', req),
+        },
+        video: {
+            /** `202`: the job and the credits reserved for it; poll `get(jobId)` (the clip is stored when it completes). */
+            generate: (req) => call('POST', '/v1/ai/video', req),
+            /** The video job: `status`, and the stored clip once completed. */
+            get: videoJob,
+            /**
+             * ⚠ NODE-ONLY: polls `get(jobId)` until the job leaves `queued`/`running` (default every 5 s, at most 10 min).
+             * In a Worker it throws `NODE_ONLY` — store the `jobId` and read `get(jobId)` later instead.
+             */
+            async wait(jobId, opts = {}) {
+                assertNode('totalum.ai.video.wait()', 'Start the job with ai.video.generate(), store the jobId, and read ai.video.get(jobId) when the page is refreshed.', 'https://totalum.app/docs/sdk/ai#node-only');
+                const until = Date.now() + (opts.timeoutMs ?? 600_000);
+                for (;;) {
+                    const job = await videoJob(jobId);
+                    if ((job.status !== 'queued' && job.status !== 'running') || Date.now() > until)
+                        return job;
+                    await new Promise((r) => setTimeout(r, opts.intervalMs ?? 5000));
+                }
+            },
+        },
+        vision: {
+            /** A text description of an image (URL, data URL or project file key). */
+            describe: (req) => call('POST', '/v1/ai/vision/describe', req),
+        },
+        speech: {
+            /** Same as `speech.synthesize`. */
+            speak: speech.synthesize,
+            /** Same as `speech.transcribe`. */
+            transcribe: speech.transcribe,
+        },
+        models: {
+            /** The model aliases and the models a project may call, with their prices. */
+            list: () => call('GET', '/v1/ai/models'),
+        },
+        /** The exact OpenRouter API for any OpenRouter/OpenAI client (A6.19): `new OpenAI(ai.gatewayConfig())`. Server-side only. */
+        gatewayConfig: () => ({
+            baseURL: options.aiBaseUrl ?? readEnv('TOTALUM_AI_BASE_URL') ?? 'https://ai.totalum.app/api/v1',
+            apiKey: projectKey(options),
+        }),
+    };
+}

package/dist/analytics/index.d.ts

@@ -0,0 +1,35 @@
+import { b as SiteMetric, a as SiteDimension, S as SiteAnalyticsOutput } 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';
+
+interface SiteAnalyticsQuery {
+    /** ISO; default the last 7 days. */
+    from?: string;
+    to?: string;
+    /** `minute` only within the last 30 minutes. */
+    granularity?: 'minute' | 'hour' | 'day';
+    /** Up to 4. */
+    metric?: SiteMetric | SiteMetric[];
+    /** Omit for a time series (`series`); set for a top-N (`top`). */
+    dimension?: SiteDimension;
+    /** Top-N, ≤ 100. */
+    limit?: number;
+    bots?: 'exclude' | 'include' | 'only';
+    /** `dev` = the preview host, `live` = the published and custom hosts; omitted = both. */
+    env?: 'dev' | 'live';
+}
+/** `totalum.analytics` (plan 05 §6.13) over SDK-API `/v1/analytics/site` (scope `analytics:read`): the site's own traffic. Free. */
+declare function totalumAnalytics(options?: TotalumClientOptions): {
+    /**
+     * Page views, visits, uniques, errors, bytes or TTFB as a series or a top-N.
+     *
+     * @example
+     * const { top } = await analytics.site({ dimension: 'path', metric: 'page_views', limit: 10 });
+     */
+    site: (q?: SiteAnalyticsQuery) => Promise<SiteAnalyticsOutput>;
+};
+type TotalumAnalytics = ReturnType<typeof totalumAnalytics>;
+
+export { SiteAnalyticsOutput, SiteDimension, SiteMetric, TotalumClientOptions, totalumAnalytics };
+export type { SiteAnalyticsQuery, TotalumAnalytics };

package/dist/analytics/index.js

@@ -0,0 +1,15 @@
+import { jsonClient, query } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** `totalum.analytics` (plan 05 §6.13) over SDK-API `/v1/analytics/site` (scope `analytics:read`): the site's own traffic. Free. */
+export function totalumAnalytics(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /**
+         * Page views, visits, uniques, errors, bytes or TTFB as a series or a top-N.
+         *
+         * @example
+         * const { top } = await analytics.site({ dimension: 'path', metric: 'page_views', limit: 10 });
+         */
+        site: (q = {}) => call('GET', `/v1/analytics/site${query({ ...q, metric: typeof q.metric === 'string' ? [q.metric] : q.metric })}`),
+    };
+}