@lumavox/server 0.0.0-stage → 0.2.1

package/dist/resources/ephemeral-keys.js

@@ -0,0 +1,129 @@
+/**
+ * `client.ephemeralKeys`: the keys an end user's device talks to agents
+ * with — `/v1/ephemeral-keys*` and `/v1/token`.
+ *
+ * - **A key is prepaid**: its `credit_limit` is set aside from the balance
+ *   when it is minted (402 when it cannot be), and what it does not spend
+ *   comes back when it settles.
+ * - **`create` clamps the lifetime by default** to the platform's maximum,
+ *   read from `limits()` — which the API never does: past a cap is a 422
+ *   (`apps/api/src/org/minting.ts`). The plan's own caps for one end
+ *   user's key are not reported yet (left-overs #107), so a key within the
+ *   platform's can still be refused.
+ * - **`limits()` is cached five minutes per client**, so a mint is two
+ *   requests cold and one warm. Concurrent cold callers share one read.
+ * - **`revoke` answers at once**, with the figures from before the key's
+ *   end user DO settles: revocation leaves through the org DO's outbox
+ *   (`apps/api/src/org/areas/keys.ts` `revokeEphemeral`). Waiting for the
+ *   final figures needs the key's read route (left-overs #106).
+ * - **`inspect` reads a key as itself** (`GET /v1/token` with that key).
+ *   Its `credits_spent` moves only when the key settles — at the end, or
+ *   daily — so a live key reads as unspent (left-overs #105).
+ */
+import { AuthenticationError } from "../errors.js";
+import { byOffset } from "../paging.js";
+import { orNull } from "../transport.js";
+import { Resource } from "./resource.js";
+const LIMITS_TTL_MS = 5 * 60_000;
+/** The route's own page bound. */
+const PAGE = 500;
+/** `promise`, or the signal's reason when it aborts first. */
+function until(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const stop = () => reject(signal.reason);
+        signal.addEventListener("abort", stop, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", stop);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", stop);
+            reject(error);
+        });
+    });
+}
+export class EphemeralKeys extends Resource {
+    cached = null;
+    /**
+     * What a key may be minted with: the **platform's** longest lifetime and
+     * largest credit limit, and the scopes this API key may grant. Cached
+     * five minutes per client.
+     */
+    limits(options = {}) {
+        const now = Date.now();
+        if (!this.cached || now - this.cached.at > LIMITS_TTL_MS) {
+            // Shared by every caller until it settles, so it is read without
+            // any one caller's signal; each waits on its own below.
+            const { signal: _, ...shared } = options;
+            const limits = this.send("GET", "/limits", shared);
+            const entry = { at: now, limits };
+            this.cached = entry;
+            limits.catch(() => {
+                // swallowed: a failed read is not cached; its callers get the error.
+                if (this.cached === entry)
+                    this.cached = null;
+            });
+        }
+        return until(this.cached.limits, options.signal);
+    }
+    /**
+     * Mints a key for one end user — returned **once**, as `key`. Scopes
+     * are exactly `["agent"]` (the default). 402 when the balance cannot set
+     * `credit_limit` aside, 422 past a cap, 429 past the plan's mints a
+     * minute (retried after its `Retry-After`).
+     */
+    async create(body, options = {}) {
+        const { clampTtl = true, ...request } = options;
+        let sent = body;
+        if (clampTtl) {
+            const limits = await this.limits(request);
+            const wanted = body.expires_in_seconds ?? limits.default_ttl_seconds;
+            sent = {
+                ...body,
+                expires_in_seconds: Math.min(wanted, limits.max_ttl_seconds),
+            };
+        }
+        return this.send("POST", "", request, sent);
+    }
+    /**
+     * Revokes a key: it is refused from now on, and what it did not spend
+     * comes back when it settles. `null` when there is no such key — a
+     * revoked, expired or unknown id answers as itself, a non-UUID as none.
+     */
+    revoke(id, options) {
+        return orNull(this.send("DELETE", this.at(id), options));
+    }
+    /**
+     * A key as it reads itself: its scopes, limit, spend and expiry. `null`
+     * when the key is refused — expired, revoked, spent or not a key.
+     */
+    async inspect(key, options = {}) {
+        let self;
+        try {
+            const answer = await this.api.request({ method: "GET", path: "/v1/token", token: key }, options);
+            self = answer.data;
+        }
+        catch (error) {
+            if (error instanceof AuthenticationError)
+                return null;
+            throw error;
+        }
+        if (self.kind !== "ephemeral") {
+            throw new TypeError("inspect() reads an ephemeral key; this is an API key.");
+        }
+        return self;
+    }
+    /** One page of this organisation's keys: live ones unless `live_only` is `false`. */
+    page(params = {}, options) {
+        return this.send("GET", "", options, params);
+    }
+    /** Every key, page after page (`limit` a page, 500 by default). */
+    list(params = {}, options) {
+        return byOffset(async (offset, limit) => ({
+            items: await this.page({ ...params, offset, limit }, options),
+        }), params.limit ?? PAGE);
+    }
+}

package/dist/resources/generations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Everything queued that a provider makes: `client.images`, `videos`,
+ * `audio`, `skybox` and `transcriptions` — each a create that answers 202
+ * with a `gen_…` id, and its own read — and `client.generations`, every
+ * capability's at once.
+ *
+ * - **Charged when accepted**, refunded in full when it fails or is
+ *   moderated. A create is a POST, so the transport resends it only after
+ *   a 429, which the API answers before charging (left-overs #108 would
+ *   make it safe to resend).
+ * - **`generate(body)` is `create` and `wait`**, answering the finished
+ *   generation; `wait(id)` polls the capability's own read (`wait.ts` has
+ *   the intervals and their ceiling). A video takes minutes: give it a
+ *   `signal` with the deadline you want.
+ * - **Each read sees its own capability**: an image's id is a 404 on
+ *   `videos.get`. `generations.get` reads any the key may generate.
+ */
+import type { GenerationInfo, GenerationPage, ListGenerationsData, SkyboxStyle } from "../gen/index.js";
+import type { RequestOptions } from "../transport.js";
+import { Polled } from "./resource.js";
+export type GenerationListParams = NonNullable<ListGenerationsData["query"]>;
+/** One capability's queue: `/v1/images`, `/v1/videos`, … */
+export declare class Jobs<Body> extends Polled<GenerationInfo> {
+    /** Accepts and charges it, answering at once with its `gen_…` id. */
+    create(body: Body, options?: RequestOptions): Promise<GenerationInfo>;
+    /** Creates it and waits: the generation once it is final. */
+    generate(body: Body, options?: RequestOptions): Promise<GenerationInfo>;
+}
+/** `/v1/skybox`, and the provider's styles. */
+export declare class Skybox<Body> extends Jobs<Body> {
+    /** The styles available now, each with its `style_id`; empty when the provider is unreachable. */
+    styles(options?: RequestOptions): Promise<SkyboxStyle[]>;
+}
+/** Every generation the key may make, read-only. */
+export declare class Generations extends Polled<GenerationInfo> {
+    /** One page, newest first, with the `next_cursor` of the next. */
+    page(params?: GenerationListParams, options?: RequestOptions): Promise<GenerationPage>;
+    /** Every generation, newest first, page after page (100 a page by default). */
+    list(params?: Omit<GenerationListParams, "cursor">, options?: RequestOptions): AsyncGenerator<GenerationInfo, void, undefined>;
+}

package/dist/resources/generations.js

@@ -0,0 +1,55 @@
+/**
+ * Everything queued that a provider makes: `client.images`, `videos`,
+ * `audio`, `skybox` and `transcriptions` — each a create that answers 202
+ * with a `gen_…` id, and its own read — and `client.generations`, every
+ * capability's at once.
+ *
+ * - **Charged when accepted**, refunded in full when it fails or is
+ *   moderated. A create is a POST, so the transport resends it only after
+ *   a 429, which the API answers before charging (left-overs #108 would
+ *   make it safe to resend).
+ * - **`generate(body)` is `create` and `wait`**, answering the finished
+ *   generation; `wait(id)` polls the capability's own read (`wait.ts` has
+ *   the intervals and their ceiling). A video takes minutes: give it a
+ *   `signal` with the deadline you want.
+ * - **Each read sees its own capability**: an image's id is a 404 on
+ *   `videos.get`. `generations.get` reads any the key may generate.
+ */
+import { byCursor } from "../paging.js";
+import { poll } from "../wait.js";
+import { Polled } from "./resource.js";
+/** The route's own page bound. */
+const PAGE = 100;
+/** One capability's queue: `/v1/images`, `/v1/videos`, … */
+export class Jobs extends Polled {
+    /** Accepts and charges it, answering at once with its `gen_…` id. */
+    create(body, options) {
+        return this.send("POST", "", options, body);
+    }
+    /** Creates it and waits: the generation once it is final. */
+    async generate(body, options) {
+        const job = await this.create(body, options);
+        return poll(() => this.get(job.id, options), options, job);
+    }
+}
+/** `/v1/skybox`, and the provider's styles. */
+export class Skybox extends Jobs {
+    /** The styles available now, each with its `style_id`; empty when the provider is unreachable. */
+    styles(options) {
+        return this.send("GET", "/styles", options);
+    }
+}
+/** Every generation the key may make, read-only. */
+export class Generations extends Polled {
+    /** One page, newest first, with the `next_cursor` of the next. */
+    page(params = {}, options) {
+        return this.send("GET", "", options, params);
+    }
+    /** Every generation, newest first, page after page (100 a page by default). */
+    list(params = {}, options) {
+        return byCursor(async (cursor) => {
+            const page = await this.page({ limit: PAGE, ...params, cursor }, options);
+            return { items: page.generations, next: page.next_cursor };
+        });
+    }
+}

package/dist/resources/knowledge.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `client.knowledge`: what agents may look up — `/v1/knowledge*`. An entry
+ * is written, read from a page (`fromUrl`) or from a file (`fromFile`,
+ * `upload`), indexed on the jobs Worker, and found by the agents it is
+ * given to (`setAgents`, or `agents.knowledge.set`).
+ *
+ * - **Indexing is a job**: an entry is `pending` until it is `ready` or
+ *   `failed` (`error` says why); `wait(id)` reads it until then. An edit
+ *   or a failed re-index keeps the previous version `searchable`.
+ * - **`upload(file, fields)`** is the ticket, the `PUT` and `fromFile` in
+ *   one (`upload.ts`); the file's extension says how it is read, 10 MB at
+ *   most.
+ * - **`list()` pages by offset**, 200 a page, with the `total` the filter
+ *   matches.
+ * - **`update` with `expected_version`** refuses an edit made over
+ *   somebody else's (409); `delete` answers the entry as it was, and
+ *   `null` for one already gone.
+ */
+import type { KnowledgeAssigned, KnowledgeAssignment, KnowledgeBulk, KnowledgeBulkResult, KnowledgeCategories, KnowledgeCreate, KnowledgeFileCreate, KnowledgeInfo, KnowledgeInsights, KnowledgeInsightsData, KnowledgeSearchList, KnowledgeSearchRequest, KnowledgeSearchResult, KnowledgeUpdate, KnowledgeUploadRequest, KnowledgeUploadTicket, KnowledgeUrlCreate, ListKnowledgeData } from "../gen/index.js";
+import type { RequestOptions } from "../transport.js";
+import { type UploadData, type UploadOptions } from "../upload.js";
+import { Waitable } from "./resource.js";
+export type KnowledgeListParams = NonNullable<ListKnowledgeData["query"]>;
+export type KnowledgeInsightsParams = NonNullable<KnowledgeInsightsData["query"]>;
+/** A file's entry: `fromFile`'s fields, and its type when not its extension's. */
+export type KnowledgeUploadFields = Omit<KnowledgeFileCreate, "upload_id"> & {
+    content_type?: string | null;
+};
+export declare class Knowledge extends Waitable<KnowledgeInfo, KnowledgeUpdate> {
+    /** One page, with the `total` the filter matches. */
+    page(params?: KnowledgeListParams, options?: RequestOptions): Promise<KnowledgeSearchList>;
+    /** Every entry the filter matches, page after page (200 a page by default). */
+    list(params?: Omit<KnowledgeListParams, "offset">, options?: RequestOptions): AsyncGenerator<KnowledgeInfo, void, undefined>;
+    /** A written entry, indexed after it is saved. */
+    create(body: KnowledgeCreate, options?: RequestOptions): Promise<KnowledgeInfo>;
+    /** Many written entries at once: what was made, and what was refused. */
+    bulk(body: KnowledgeBulk, options?: RequestOptions): Promise<KnowledgeBulkResult>;
+    /** An entry read from a page, and refreshed on its schedule. */
+    fromUrl(body: KnowledgeUrlCreate, options?: RequestOptions): Promise<KnowledgeInfo>;
+    /** A signed URL to `PUT` a file to. */
+    uploadUrl(body: KnowledgeUploadRequest, options?: RequestOptions): Promise<KnowledgeUploadTicket>;
+    /** An entry read from a file already `PUT` to its ticket. */
+    fromFile(body: KnowledgeFileCreate, options?: RequestOptions): Promise<KnowledgeInfo>;
+    /** Uploads a file and reads it: `uploadUrl`, the `PUT`, `fromFile`. */
+    upload(file: UploadData, fields: KnowledgeUploadFields, options?: UploadOptions): Promise<KnowledgeInfo>;
+    /** Indexes the body it has again. */
+    reindex(id: string, options?: RequestOptions): Promise<KnowledgeInfo>;
+    /** Reads its page again now. */
+    refresh(id: string, options?: RequestOptions): Promise<KnowledgeInfo>;
+    /** Replaces the agents that may look it up. */
+    setAgents(id: string, body: KnowledgeAssignment, options?: RequestOptions): Promise<KnowledgeAssigned>;
+    /** What an agent would find for a question. */
+    search(body: KnowledgeSearchRequest, options?: RequestOptions): Promise<KnowledgeSearchResult>;
+    /** The categories in use. */
+    categories(options?: RequestOptions): Promise<KnowledgeCategories>;
+    /** What was looked up, and what went unanswered: 7 days by default. */
+    insights(params?: KnowledgeInsightsParams, options?: RequestOptions): Promise<KnowledgeInsights>;
+}

package/dist/resources/knowledge.js

@@ -0,0 +1,91 @@
+/**
+ * `client.knowledge`: what agents may look up — `/v1/knowledge*`. An entry
+ * is written, read from a page (`fromUrl`) or from a file (`fromFile`,
+ * `upload`), indexed on the jobs Worker, and found by the agents it is
+ * given to (`setAgents`, or `agents.knowledge.set`).
+ *
+ * - **Indexing is a job**: an entry is `pending` until it is `ready` or
+ *   `failed` (`error` says why); `wait(id)` reads it until then. An edit
+ *   or a failed re-index keeps the previous version `searchable`.
+ * - **`upload(file, fields)`** is the ticket, the `PUT` and `fromFile` in
+ *   one (`upload.ts`); the file's extension says how it is read, 10 MB at
+ *   most.
+ * - **`list()` pages by offset**, 200 a page, with the `total` the filter
+ *   matches.
+ * - **`update` with `expected_version`** refuses an edit made over
+ *   somebody else's (409); `delete` answers the entry as it was, and
+ *   `null` for one already gone.
+ */
+import { byOffset } from "../paging.js";
+import { put, sizeOf, typeOf, } from "../upload.js";
+import { Waitable } from "./resource.js";
+/** The route's own page bound. */
+const PAGE = 200;
+export class Knowledge extends Waitable {
+    /** One page, with the `total` the filter matches. */
+    page(params = {}, options) {
+        return this.send("GET", "", options, params);
+    }
+    /** Every entry the filter matches, page after page (200 a page by default). */
+    list(params = {}, options) {
+        return byOffset(async (offset, limit) => {
+            const page = await this.page({ ...params, offset, limit }, options);
+            return { items: page.entries, total: page.total };
+        }, params.limit ?? PAGE);
+    }
+    /** A written entry, indexed after it is saved. */
+    create(body, options) {
+        return this.send("POST", "", options, body);
+    }
+    /** Many written entries at once: what was made, and what was refused. */
+    bulk(body, options) {
+        return this.send("POST", "/bulk", options, body);
+    }
+    /** An entry read from a page, and refreshed on its schedule. */
+    fromUrl(body, options) {
+        return this.send("POST", "/urls", options, body);
+    }
+    /** A signed URL to `PUT` a file to. */
+    uploadUrl(body, options) {
+        return this.send("POST", "/upload-url", options, body);
+    }
+    /** An entry read from a file already `PUT` to its ticket. */
+    fromFile(body, options) {
+        return this.send("POST", "/files", options, body);
+    }
+    /** Uploads a file and reads it: `uploadUrl`, the `PUT`, `fromFile`. */
+    async upload(file, fields, options = {}) {
+        const { content_type, ...body } = fields;
+        const ticket = await this.uploadUrl({
+            filename: body.filename,
+            size: sizeOf(file, options.size) ?? null,
+            content_type: typeOf(file, content_type) || null,
+        }, options);
+        await put(this.api, ticket, file, ticket.content_type, options);
+        return this.settled(await this.fromFile({ ...body, upload_id: ticket.upload_id }, options), options);
+    }
+    /** Indexes the body it has again. */
+    reindex(id, options) {
+        return this.send("POST", this.at(id, "/reindex"), options);
+    }
+    /** Reads its page again now. */
+    refresh(id, options) {
+        return this.send("POST", this.at(id, "/refresh"), options);
+    }
+    /** Replaces the agents that may look it up. */
+    setAgents(id, body, options) {
+        return this.send("PUT", this.at(id, "/agents"), options, body);
+    }
+    /** What an agent would find for a question. */
+    search(body, options) {
+        return this.send("POST", "/search", options, body);
+    }
+    /** The categories in use. */
+    categories(options) {
+        return this.send("GET", "/categories", options);
+    }
+    /** What was looked up, and what went unanswered: 7 days by default. */
+    insights(params = {}, options) {
+        return this.send("GET", "/insights", options, params);
+    }
+}

package/dist/resources/resource.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What every resource shares, as a ladder of bases each method is written
+ * once in — the SDK's size is a budget (`test/dist.test.ts`):
+ *
+ * - **`Resource`**: the transport, and the path its routes start with.
+ *   `send` takes the rest of the path, and `at(id)` is one item's, the id
+ *   encoded (an id the caller holds may carry `/` or `?`).
+ * - **`Readable`**: `get(id)`; **`Polled`** adds `wait(id)` (`wait.ts`),
+ *   for a generation, which is read and waited on and nothing else.
+ * - **`Editable`**: `update(id, body)` (`PATCH`) and `delete(id)`, which
+ *   answers `null` when there is nothing by that id — already done.
+ * - **`Waitable`**: an editable whose items are jobs — a voice, an asset,
+ *   a knowledge entry — with `wait(id)` and `settled`, which an upload
+ *   answers through.
+ *
+ * Fields are `declare`d, not defined: each is assigned in a constructor,
+ * and a definition is bytes in every customer's bundle.
+ */
+import { type Method, type RequestOptions, type Transport } from "../transport.js";
+import type { UploadOptions } from "../upload.js";
+import { type Job } from "../wait.js";
+export declare class Resource {
+    protected readonly api: Transport;
+    protected readonly base: string;
+    constructor(api: Transport, base: string);
+    /** A JSON call to `base` + `rest`: a GET's `data` is its query, any other's its body. */
+    protected send<T>(method: Method, rest: string, options?: RequestOptions, data?: unknown): Promise<T>;
+    /** The rest of item `id`'s path, and of what follows it. */
+    protected at(id: string, rest?: string): string;
+}
+export declare class Readable<Item> extends Resource {
+    /** One of them. A `NotFoundError` when there is none. */
+    get(id: string, options?: RequestOptions): Promise<Item>;
+}
+export declare class Polled<Item extends Job> extends Readable<Item> {
+    /** Reads it until its `status` is final (`wait.ts`). */
+    wait(id: string, options?: RequestOptions): Promise<Item>;
+}
+export declare class Editable<Item, Update, Updated = Item, Deleted = Item> extends Readable<Item> {
+    /** Changes what `body` gives; absent fields are untouched. */
+    update(id: string, body: Update, options?: RequestOptions): Promise<Updated>;
+    /** Deletes it; `null` when there is none by that id — already done. */
+    delete(id: string, options?: RequestOptions): Promise<Deleted | null>;
+}
+export declare class Waitable<Item extends Job & {
+    id: string;
+}, Update, Updated = Item, Deleted = Item> extends Editable<Item, Update, Updated, Deleted> {
+    /** Reads it until its `status` is final (`wait.ts`). */
+    wait(id: string, options?: RequestOptions): Promise<Item>;
+    /** `item` as made, or as it ended when `options.wait` says to wait. */
+    protected settled(item: Item, options: UploadOptions): Promise<Item>;
+}

package/dist/resources/resource.js

@@ -0,0 +1,68 @@
+/**
+ * What every resource shares, as a ladder of bases each method is written
+ * once in — the SDK's size is a budget (`test/dist.test.ts`):
+ *
+ * - **`Resource`**: the transport, and the path its routes start with.
+ *   `send` takes the rest of the path, and `at(id)` is one item's, the id
+ *   encoded (an id the caller holds may carry `/` or `?`).
+ * - **`Readable`**: `get(id)`; **`Polled`** adds `wait(id)` (`wait.ts`),
+ *   for a generation, which is read and waited on and nothing else.
+ * - **`Editable`**: `update(id, body)` (`PATCH`) and `delete(id)`, which
+ *   answers `null` when there is nothing by that id — already done.
+ * - **`Waitable`**: an editable whose items are jobs — a voice, an asset,
+ *   a knowledge entry — with `wait(id)` and `settled`, which an upload
+ *   answers through.
+ *
+ * Fields are `declare`d, not defined: each is assigned in a constructor,
+ * and a definition is bytes in every customer's bundle.
+ */
+import { orNull, segment, } from "../transport.js";
+import { poll } from "../wait.js";
+export class Resource {
+    constructor(api, base) {
+        this.api = api;
+        this.base = base;
+    }
+    /** A JSON call to `base` + `rest`: a GET's `data` is its query, any other's its body. */
+    send(method, rest, options, data) {
+        return this.api.send(method, this.base + rest, options, data);
+    }
+    /** The rest of item `id`'s path, and of what follows it. */
+    at(id, rest = "") {
+        return `/${segment(id)}${rest}`;
+    }
+}
+export class Readable extends Resource {
+    /** One of them. A `NotFoundError` when there is none. */
+    get(id, options) {
+        return this.send("GET", this.at(id), options);
+    }
+}
+export class Polled extends Readable {
+    /** Reads it until its `status` is final (`wait.ts`). */
+    wait(id, options) {
+        return poll(() => this.get(id, options), options);
+    }
+}
+export class Editable extends Readable {
+    /** Changes what `body` gives; absent fields are untouched. */
+    update(id, body, options) {
+        return this.send("PATCH", this.at(id), options, body);
+    }
+    /** Deletes it; `null` when there is none by that id — already done. */
+    delete(id, options) {
+        return orNull(this.send("DELETE", this.at(id), options));
+    }
+}
+export class Waitable extends Editable {
+    /** Reads it until its `status` is final (`wait.ts`). */
+    wait(id, options) {
+        return poll(() => this.get(id, options), options);
+    }
+    /** `item` as made, or as it ended when `options.wait` says to wait. */
+    async settled(item, options) {
+        return options.wait
+            ? poll(() => this.get(item.id, options), options, item)
+            : item;
+    }
+}

package/dist/resources/speech.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Speech answered in the call: `client.tts` — `POST /v1/tts`, text to
+ * audio — and `client.stt` — `POST /v1/stt`, audio to text. Both metered
+ * POSTs, resent only after a 429. For long text or audio, the queued doors
+ * are `audio` and `transcriptions` (`generations.ts`).
+ *
+ * - **`tts.create(body)` answers the audio whole** (an `ArrayBuffer`, WAV
+ *   or raw `pcm`) **or, with `stream: true`, as it is made** (a
+ *   `ReadableStream` of `pcm`), beside what its headers say. A whole
+ *   answer names its sample rate (`X-Sample-Rate`); a stream names none,
+ *   so its rate is the one asked for, 24 000 Hz unset (the API's default,
+ *   `@ino/core/speech/catalog`; left-overs #111).
+ * - **`stt.create(audio, params)` sends the audio as the body**, the
+ *   options as the query — the route's raw form, which a stream can be
+ *   sent as, unlike a multipart one. It answers the transcript, or with
+ *   `stream: true` an async iterator of its NDJSON events (WAV or raw PCM
+ *   only). Up to 25 MB.
+ * - **A stream's timeout ends at its headers**; `signal` still ends it.
+ */
+import type { StreamDone, StreamError, StreamSegment, StreamTranscript, TranscribeData, TranscriptWord, TtsRequest } from "../gen/index.js";
+import type { RequestOptions } from "../transport.js";
+import { type UploadData } from "../upload.js";
+import { Resource } from "./resource.js";
+/** Speech, and what the response's headers say about it. */
+export interface Speech<Body> {
+    /** The audio: an `ArrayBuffer`, or a `ReadableStream` when streamed. */
+    body: Body;
+    /** `audio/wav` or `audio/pcm` (16-bit, mono, little-endian). */
+    contentType: string;
+    /** Hz: what was produced, or for a stream the rate asked for. */
+    sampleRate: number;
+    /** The model that spoke. */
+    model: string | null;
+    /** Seconds of audio; `null` for a stream, which is not measured up front. */
+    audioSeconds: number | null;
+    requestId: string;
+}
+export declare class Tts extends Resource {
+    /** The audio as it is made: `pcm` only. */
+    create(body: TtsRequest & {
+        stream: true;
+    }, options?: RequestOptions): Promise<Speech<ReadableStream<Uint8Array>>>;
+    /** The audio whole, once it is all made. */
+    create(body: TtsRequest & {
+        stream?: false;
+    }, options?: RequestOptions): Promise<Speech<ArrayBuffer>>;
+}
+/** The options `/v1/stt` takes, and the audio's type when it is no `Blob`'s. */
+export type SttParams = Omit<TranscribeData["body"], "file"> & {
+    /** The audio's `Content-Type`; a Blob's own, or `application/octet-stream`. */
+    content_type?: string;
+};
+/**
+ * `POST /v1/stt`'s whole answer. The document declares no schema for it
+ * (left-overs #112), so this is the route's own (`transcript()` in
+ * `apps/api/src/routes/stt.ts`), written out; `apps/api/test/sdk.test.ts`
+ * holds the two together.
+ */
+export interface Transcript {
+    text: string;
+    language_code: string | null;
+    language_probability: number | null;
+    /** What was charged, per minute. */
+    duration_seconds: number;
+    model: string;
+    /** With `timestamps: true`; `null` otherwise. */
+    words: TranscriptWord[] | null;
+}
+/** One line of a streamed transcript. */
+export type SttEvent = StreamSegment | StreamTranscript | StreamError | StreamDone;
+export declare class Stt extends Resource {
+    /** The transcript as it is made: an iterator of its events. */
+    create(audio: UploadData, params: SttParams & {
+        stream: true;
+    }, options?: RequestOptions): AsyncGenerator<SttEvent, void, undefined>;
+    /** The transcript, once it is all made. */
+    create(audio: UploadData, params?: SttParams & {
+        stream?: false;
+    }, options?: RequestOptions): Promise<Transcript>;
+}

package/dist/resources/speech.js

@@ -0,0 +1,64 @@
+/**
+ * Speech answered in the call: `client.tts` — `POST /v1/tts`, text to
+ * audio — and `client.stt` — `POST /v1/stt`, audio to text. Both metered
+ * POSTs, resent only after a 429. For long text or audio, the queued doors
+ * are `audio` and `transcriptions` (`generations.ts`).
+ *
+ * - **`tts.create(body)` answers the audio whole** (an `ArrayBuffer`, WAV
+ *   or raw `pcm`) **or, with `stream: true`, as it is made** (a
+ *   `ReadableStream` of `pcm`), beside what its headers say. A whole
+ *   answer names its sample rate (`X-Sample-Rate`); a stream names none,
+ *   so its rate is the one asked for, 24 000 Hz unset (the API's default,
+ *   `@ino/core/speech/catalog`; left-overs #111).
+ * - **`stt.create(audio, params)` sends the audio as the body**, the
+ *   options as the query — the route's raw form, which a stream can be
+ *   sent as, unlike a multipart one. It answers the transcript, or with
+ *   `stream: true` an async iterator of its NDJSON events (WAV or raw PCM
+ *   only). Up to 25 MB.
+ * - **A stream's timeout ends at its headers**; `signal` still ends it.
+ */
+import { ndjson } from "../stream.js";
+import { typeOf } from "../upload.js";
+import { Resource } from "./resource.js";
+/** The rate a streamed `pcm` is spoken at when the request named none. */
+const DEFAULT_SAMPLE_RATE = 24_000;
+export class Tts extends Resource {
+    async create(body, options) {
+        const answer = await this.api.request({
+            method: "POST",
+            path: this.base,
+            body,
+            read: body.stream ? "stream" : "bytes",
+        }, options);
+        const header = (name) => answer.headers.get(name);
+        const seconds = header("x-audio-seconds");
+        return {
+            body: answer.data,
+            contentType: header("content-type") ?? "",
+            sampleRate: Number(header("x-sample-rate") ?? body.sample_rate ?? DEFAULT_SAMPLE_RATE),
+            model: header("x-model"),
+            audioSeconds: seconds === null ? null : Number(seconds),
+            requestId: answer.requestId,
+        };
+    }
+}
+export class Stt extends Resource {
+    create(audio, params = {}, options) {
+        const { content_type, ...query } = params;
+        const call = {
+            method: "POST",
+            path: this.base,
+            query: query,
+            raw: audio,
+            type: typeOf(audio, content_type) || "application/octet-stream",
+        };
+        if (!params.stream) {
+            return this.api.request(call, options).then((a) => a.data);
+        }
+        const api = this.api;
+        return (async function* () {
+            const answer = await api.request({ ...call, read: "stream" }, options);
+            yield* ndjson(answer.data, answer.requestId);
+        })();
+    }
+}