@rimelabs/sdk 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0-alpha.1
+
+Initial local alpha for Node.js 22+ and ESM. Adds Coda synthesis, discovery,
+API-key authentication, sentence buffering, PCM and mu-law profiles, typed errors,
+deadlines, and cancellation. The Themis wire contract is assumed and needs
+deployment validation.
+
+Review fixes preserve zero-width spaces and BOM characters during sentence
+mapping, distinguish token-exchange rate limits and service failures from
+rejected credentials, and cancel failed HTTP response bodies.
+
+Further review fixes stop pending reads after cancellation, preserve errors from
+responses without audio metadata, handle responses with only trailers, and
+collect discovery request IDs from headers and trailers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rime
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# Rime SDK for Node.js
+
+Requires Node.js 22 or later. The package uses ESM and includes TypeScript types.
+Browser use is not supported. This is an alpha release.
+Install it from npm using the `next` tag:
+
+```sh
+npm install @rimelabs/sdk@next
+```
+
+```javascript
+import { writeFile } from "node:fs/promises";
+import { Rime, AudioFormat } from "@rimelabs/sdk";
+
+const client = new Rime({ apiKey: "your-api-key" });
+try {
+  const audio = client.tts.stream("Hello. This is Rime.", {
+    voice: "clementine",
+    audioFormat: AudioFormat.PCM_24000,
+  });
+  await writeFile("speech.pcm", audio);
+  console.log(audio.requestId);
+} finally {
+  await client.close();
+}
+```
+
+Omit `apiKey` to read `RIME_API_KEY`. The default model is `coda`.
+The SDK selects its standard endpoint. Only `coda` is currently supported.
+For a custom deployment of that model, set `endpoint`:
+
+```javascript
+const client = new Rime({ model: "coda", endpoint: "coda.api.customer-name.rime.ai" });
+```
+
+Use a hostname with an optional port, such as `host:8443`. Omit the scheme and path.
+Connections always use TLS; the default port is `443`.
+The endpoint applies to speech, voices, and languages for this client.
+
+The default voice is `clementine`; the default language is `en`.
+`tts.stream()` also accepts `AsyncIterable<string>`. Do not await the factory.
+The first iterator read starts work. A `for await` loop exit cancels the stream.
+Use `await audio.cancel()` in a `finally` block if you read the iterator manually.
+
+`await client.voices.list({ language: "en" })` returns voice names.
+`await client.languages.list()` returns language codes.
+Both accept an options object with `timeout` in seconds.
+
+`new Rime({ timeout: 30 })` sets an overall timeout. An operation can replace
+it with `{ timeout: 10 }` or disable it with `{ timeout: null }`.
+An omitted or `undefined` option inherits the client setting. Internal connection
+and progress limits still apply. An overall timeout continues during caller pauses.
+
+`audio.format` is a read-only `AudioFormat` with `encoding`, `sampleRate`, and
+`channels`. `PCM_24000` is raw signed 16-bit little-endian mono PCM at 24 kHz.
+`MULAW_8000` is raw mono G.711 mu-law at 8 kHz. Neither includes a file header.
+The iterator yields `Uint8Array` chunks with complete sample frames.
+Chunk sizes are not fixed.
+
+`await audio.cancel()` cancels one operation. `await client.close()` cancels all
+client work. Both are idempotent. Both objects support `Symbol.asyncDispose`.
+Normal iterator completion means that the final service status was successful.
+Partial audio can precede a typed error. Synthesis is never replayed.
+
+Catch `RimeError` or one of `RimeAuthenticationError`, `RimePermissionError`,
+`RimeInputError`, `RimeResourceLimitError`, `RimeUnavailableError`,
+`RimeTimeoutError`, `RimeAudioFormatError`, `RimeCancelledError`, or
+`RimeStreamError`. Errors expose a message and optional `requestId`.
+Cancellation cannot stop application code that waits on an unrelated promise.
+The SDK stops its RPC and limits how long it waits for source cleanup.
+
+The SDK sends the API key as a bearer token over TLS.
+
+## Development for contributors
+
+These instructions require access to the source repository.
+Run the commands from its `typescript/` directory:
+
+```sh
+npm ci
+npm run check
+npm run lint
+npm test
+npm pack
+```
+
+The package includes a pinned Microsoft BlingFire WASM binary and its license.
+It does not download code at runtime. See [vendor provenance](vendor/README.md).
+
+## License
+
+The SDK is licensed under the [MIT License](LICENSE).
+BlingFire retains its [upstream license](vendor/LICENSE.blingfire).

package/dist/audio.d.ts

@@ -0,0 +1,19 @@
+export declare class AudioFormat {
+    readonly encoding: string;
+    readonly sampleRate: number;
+    readonly channels: number;
+    static readonly PCM_24000: Readonly<AudioFormat>;
+    static readonly MULAW_8000: Readonly<AudioFormat>;
+    private constructor();
+}
+export declare class Converter {
+    private profile;
+    private tail;
+    private samples;
+    private seen;
+    private emitted;
+    private inputSamples;
+    constructor(profile: AudioFormat);
+    private sample;
+    process(input: Uint8Array, final?: boolean): Buffer;
+}

package/dist/audio.js

@@ -0,0 +1,73 @@
+import { RimeAudioFormatError } from "./errors.js";
+export class AudioFormat {
+    encoding;
+    sampleRate;
+    channels;
+    static PCM_24000 = Object.freeze(new AudioFormat("pcm_s16le", 24000, 1));
+    static MULAW_8000 = Object.freeze(new AudioFormat("mulaw", 8000, 1));
+    constructor(encoding, sampleRate, channels) {
+        this.encoding = encoding;
+        this.sampleRate = sampleRate;
+        this.channels = channels;
+    }
+}
+const raw = Array.from({ length: 63 }, (_, i) => (i === 31
+    ? (2 * 3400) / 24000
+    : Math.sin(((2 * Math.PI * 3400) / 24000) * (i - 31)) /
+        (Math.PI * (i - 31))) *
+    (0.54 - 0.46 * Math.cos((2 * Math.PI * i) / 62)));
+const total = raw.reduce((a, b) => a + b, 0);
+const coefficients = raw.map((x) => x / total);
+function mulaw(sample) {
+    sample = Math.max(-32768, Math.min(32767, sample));
+    const sign = sample < 0 ? 128 : 0, magnitude = Math.min(Math.abs(sample), 32635) + 132;
+    const exponent = Math.max(0, Math.floor(Math.log2(magnitude)) - 7);
+    return ~(sign | (exponent << 4) | ((magnitude >> (exponent + 3)) & 15)) & 255;
+}
+export class Converter {
+    profile;
+    tail = Buffer.alloc(0);
+    samples = Array(63).fill(0);
+    seen = 0;
+    emitted = 0;
+    inputSamples = 0;
+    constructor(profile) {
+        this.profile = profile;
+    }
+    sample(sample) {
+        this.samples.pop();
+        this.samples.unshift(sample);
+        const position = this.seen++ - 31;
+        if (position >= 0 && position % 3 === 0) {
+            const value = coefficients.reduce((sum, c, i) => sum + c * this.samples[i], 0);
+            this.emitted++;
+            return mulaw(Math.floor(value + 0.5));
+        }
+        return null;
+    }
+    process(input, final = false) {
+        const data = Buffer.concat([this.tail, input]);
+        const size = Math.floor(data.length / 2) * 2;
+        this.tail = Buffer.from(data.subarray(size));
+        if (final && this.tail.length)
+            throw new RimeAudioFormatError("Incomplete final PCM sample frame");
+        if (this.profile === AudioFormat.PCM_24000)
+            return data.subarray(0, size);
+        const result = [];
+        for (let i = 0; i < size; i += 2) {
+            this.inputSamples++;
+            const value = this.sample(data.readInt16LE(i));
+            if (value !== null)
+                result.push(value);
+        }
+        if (final) {
+            const target = Math.ceil(this.inputSamples / 3);
+            while (this.emitted < target) {
+                const value = this.sample(0);
+                if (value !== null)
+                    result.push(value);
+            }
+        }
+        return Buffer.from(result);
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,23 @@
+import { policy } from "./policy.js";
+export interface Token {
+    value: string;
+    expiresAt: number;
+    audience: string;
+}
+export declare function exchangeKey(key: string, signal: AbortSignal, configuration?: Readonly<typeof policy>): Promise<Token>;
+export declare const authentication: {
+    exchangeKey: typeof exchangeKey;
+};
+export declare class Credentials {
+    private key;
+    private readonly configuration;
+    private token;
+    private refresh;
+    private refreshAt;
+    private controller;
+    private closed;
+    constructor(key: string, configuration?: Readonly<typeof policy>);
+    metadata(signal: AbortSignal): Promise<string>;
+    themisMetadata(signal: AbortSignal): Promise<string>;
+    close(): Promise<void>;
+}

package/dist/auth.js

@@ -0,0 +1,133 @@
+import { policy, abortable } from "./policy.js";
+import { RimeError, RimeAuthenticationError, RimePermissionError, RimeTimeoutError, RimeCancelledError, RimeResourceLimitError, RimeUnavailableError, } from "./errors.js";
+export async function exchangeKey(key, signal, configuration = policy) {
+    try {
+        const response = await fetch(configuration.exchangeUrl, {
+            method: "POST",
+            redirect: "error",
+            signal,
+            headers: {
+                Authorization: `Api-Key ${key}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ audience: configuration.audience }),
+        });
+        if (response.status !== 200) {
+            // The refresh timeout ends when this function rejects. Cancel the body
+            // now so an unfinished error response cannot retain the connection.
+            await response.body?.cancel().catch(() => { });
+            if (response.status === 403)
+                throw new RimePermissionError("Credential exchange denied permission");
+            if (response.status === 429)
+                throw new RimeResourceLimitError("Credential exchange rate limit exceeded");
+            if (response.status >= 500 && response.status < 600)
+                throw new RimeUnavailableError("Credential exchange service unavailable");
+            throw new RimeAuthenticationError("Credential exchange rejected the API key");
+        }
+        if (!response.body)
+            throw new Error("Missing response body");
+        const reader = response.body.getReader();
+        let size = 0;
+        const chunks = [];
+        try {
+            for (;;) {
+                const result = await reader.read();
+                if (result.done)
+                    break;
+                size += result.value.length;
+                if (size > 65536)
+                    throw new Error("Response too large");
+                chunks.push(result.value);
+            }
+        }
+        finally {
+            await reader.cancel();
+            reader.releaseLock();
+        }
+        const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (typeof body.access_token !== "string" ||
+            !body.access_token ||
+            /[^\x21-\x7e]/.test(body.access_token) ||
+            typeof body.expires_in !== "number" ||
+            !Number.isFinite(body.expires_in) ||
+            body.expires_in <= 0 ||
+            body.audience !== configuration.audience)
+            throw new RimeAuthenticationError("Credential exchange returned an invalid token");
+        return {
+            value: body.access_token,
+            expiresAt: Date.now() / 1000 + body.expires_in,
+            audience: body.audience,
+        };
+    }
+    catch (error) {
+        if (error instanceof RimeError)
+            throw error;
+        if (signal.aborted)
+            throw signal.reason;
+        throw new RimeAuthenticationError("Credential exchange failed");
+    }
+}
+// Private dependency seam for local conformance tests; not exported by the package.
+export const authentication = { exchangeKey };
+export class Credentials {
+    key;
+    configuration;
+    token = null;
+    refresh = null;
+    refreshAt = 0;
+    controller = new AbortController();
+    closed = false;
+    constructor(key, configuration = policy) {
+        this.key = key;
+        this.configuration = configuration;
+    }
+    async metadata(signal) {
+        // TEMPORARY until Themis is ready: replace this body with the call below.
+        // return this.themisMetadata(signal);
+        if (this.closed)
+            throw new RimeAuthenticationError("Credentials are closed");
+        signal.throwIfAborted();
+        return `Bearer ${this.key}`;
+    }
+    async themisMetadata(signal) {
+        if (this.closed)
+            throw new RimeAuthenticationError("Credentials are closed");
+        if (!this.token || Date.now() / 1000 >= this.refreshAt) {
+            if (!this.refresh) {
+                const timeoutController = new AbortController();
+                const timer = setTimeout(() => timeoutController.abort(new RimeTimeoutError("Credential acquisition timed out")), this.configuration.authTimeout * 1000);
+                const combined = AbortSignal.any([
+                    this.controller.signal,
+                    timeoutController.signal,
+                ]);
+                this.refresh = abortable(authentication.exchangeKey(this.key, combined, this.configuration), combined)
+                    .then((token) => {
+                    if (!token.value ||
+                        token.expiresAt <= Date.now() / 1000 ||
+                        token.audience !== this.configuration.audience)
+                        throw new RimeAuthenticationError("Credential exchange returned an invalid token");
+                    this.token = token;
+                    this.refreshAt =
+                        token.expiresAt -
+                            Math.min(30, (token.expiresAt - Date.now() / 1000) / 10);
+                    return token;
+                })
+                    .finally(() => {
+                    clearTimeout(timer);
+                    this.refresh = null;
+                });
+                this.refresh.catch(() => { });
+            }
+            const token = await abortable(this.refresh, signal);
+            return `Bearer ${token.value}`;
+        }
+        return `Bearer ${this.token.value}`;
+    }
+    async close() {
+        this.closed = true;
+        this.controller.abort(new RimeCancelledError("Client closed"));
+        await this.refresh?.catch(() => { });
+        this.token = null;
+        this.key = "";
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+import { AudioFormat } from "./audio.js";
+import { AudioStream, type TextSource } from "./stream.js";
+export interface RimeOptions {
+    apiKey?: string | null;
+    model?: string;
+    endpoint?: string | null;
+    timeout?: number | null;
+}
+export interface SynthesisOptions {
+    voice?: string | null;
+    language?: string;
+    audioFormat?: AudioFormat | null;
+    timeout?: number | null;
+}
+export interface DiscoveryOptions {
+    timeout?: number | null;
+}
+export interface VoiceListOptions extends DiscoveryOptions {
+    language?: string | null;
+}
+export declare class Rime {
+    private readonly deployment;
+    private credentials;
+    private client;
+    private closed;
+    private streams;
+    private discoveryControllers;
+    private closing;
+    private defaultTimeout;
+    readonly tts: {
+        stream: (text: TextSource, options?: SynthesisOptions) => AudioStream;
+    };
+    readonly voices: {
+        list: (options?: VoiceListOptions) => Promise<string[]>;
+    };
+    readonly languages: {
+        list: (options?: DiscoveryOptions) => Promise<string[]>;
+    };
+    constructor(options?: RimeOptions);
+    private checkOpen;
+    private prepare;
+    private stream;
+    private discover;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,125 @@
+import { AudioFormat } from "./audio.js";
+import { AudioStream, constructionKey } from "./stream.js";
+import { Credentials } from "./auth.js";
+import { policy, resolve, timeout, nonempty, abortable } from "./policy.js";
+import { transport, connect, metadata, discover, } from "./transport.js";
+import { RimeAuthenticationError, RimeInputError, RimeAudioFormatError, RimeCancelledError, RimeTimeoutError, RimeUnavailableError, } from "./errors.js";
+export class Rime {
+    deployment;
+    credentials;
+    client = null;
+    closed = false;
+    streams = new Set();
+    discoveryControllers = new Set();
+    closing = null;
+    defaultTimeout;
+    tts;
+    voices;
+    languages;
+    constructor(options = {}) {
+        const key = options.apiKey === undefined || options.apiKey === null
+            ? process.env.RIME_API_KEY
+            : options.apiKey;
+        if (typeof key !== "string" || !key.trim())
+            throw new RimeAuthenticationError("Provide apiKey or set RIME_API_KEY");
+        this.defaultTimeout = timeout(options.timeout);
+        this.deployment = resolve(options.model ?? "coda", options.endpoint);
+        this.credentials = new Credentials(key, this.deployment);
+        this.tts = { stream: (text, options = {}) => this.stream(text, options) };
+        this.voices = {
+            list: async (options = {}) => {
+                if (options.language !== undefined && options.language !== null)
+                    nonempty(options.language, "language");
+                return this.discover("voices", options.language, options.timeout);
+            },
+        };
+        this.languages = {
+            list: (options = {}) => this.discover("languages", undefined, options.timeout),
+        };
+    }
+    checkOpen() {
+        if (this.closed)
+            throw new RimeInputError("The Rime client is closed");
+    }
+    async prepare(signal) {
+        this.checkOpen();
+        const auth = await this.credentials.metadata(signal);
+        this.checkOpen();
+        this.client ??= transport.makeClient(this.deployment.target);
+        await connect(this.client, signal);
+        return { client: this.client, metadata: metadata(auth) };
+    }
+    stream(text, options) {
+        this.checkOpen();
+        if (typeof text === "string") {
+            if (!text.trim())
+                throw new RimeInputError("Text must contain non-whitespace characters");
+        }
+        else if (!text || typeof text[Symbol.asyncIterator] !== "function")
+            throw new RimeInputError("text must be a string or an async iterable of strings");
+        const voice = options.voice === undefined || options.voice === null
+            ? "clementine"
+            : nonempty(options.voice, "voice");
+        const language = nonempty(options.language ?? "en", "language");
+        const format = options.audioFormat ?? AudioFormat.PCM_24000;
+        if (format !== AudioFormat.PCM_24000 && format !== AudioFormat.MULAW_8000)
+            throw new RimeAudioFormatError("Select a named AudioFormat profile");
+        const audio = new AudioStream(constructionKey, {
+            prepare: (s) => this.prepare(s),
+            checkOpen: () => this.checkOpen(),
+            forget: (s) => this.streams.delete(s),
+        }, text, voice, language, format, timeout(options.timeout, this.defaultTimeout));
+        this.streams.add(audio);
+        return audio;
+    }
+    async discover(kind, language, override) {
+        this.checkOpen();
+        const budget = Math.min(timeout(override, this.defaultTimeout) ?? Infinity, policy.discoveryTimeout);
+        const controller = new AbortController();
+        let requestId = null;
+        this.discoveryControllers.add(controller);
+        const timer = setTimeout(() => controller.abort(new RimeTimeoutError("Discovery deadline expired")), budget * 1000);
+        try {
+            const prepared = await this.prepare(controller.signal);
+            for (let attempt = 0;; attempt++) {
+                requestId = null;
+                try {
+                    return await discover(prepared, kind, language, controller.signal);
+                }
+                catch (error) {
+                    if (!(error instanceof RimeUnavailableError) || attempt === 2)
+                        throw error;
+                    requestId = error.requestId;
+                    await abortable(new Promise((resolve) => setTimeout(resolve, 50 * 2 ** attempt)), controller.signal);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof RimeTimeoutError && requestId !== null)
+                throw new RimeTimeoutError(error.message, requestId, {
+                    cause: error.cause,
+                });
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            this.discoveryControllers.delete(controller);
+        }
+    }
+    async close() {
+        if (!this.closing) {
+            this.closed = true;
+            this.closing = (async () => {
+                for (const controller of this.discoveryControllers)
+                    controller.abort(new RimeCancelledError("Client closed during discovery"));
+                await Promise.all([...this.streams].map((stream) => stream.cancel()));
+                await this.credentials.close();
+                this.client?.close();
+            })();
+        }
+        await this.closing;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+export declare class RimeError extends Error {
+    readonly requestId: string | null;
+    constructor(message: string, requestId?: string | null, options?: ErrorOptions);
+}
+export declare class RimeAuthenticationError extends RimeError {
+}
+export declare class RimePermissionError extends RimeError {
+}
+export declare class RimeInputError extends RimeError {
+}
+export declare class RimeResourceLimitError extends RimeError {
+}
+export declare class RimeUnavailableError extends RimeError {
+}
+export declare class RimeTimeoutError extends RimeError {
+}
+export declare class RimeAudioFormatError extends RimeError {
+}
+export declare class RimeCancelledError extends RimeError {
+}
+export declare class RimeStreamError extends RimeError {
+}

package/dist/errors.js

@@ -0,0 +1,26 @@
+export class RimeError extends Error {
+    requestId;
+    constructor(message, requestId = null, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.requestId = requestId;
+    }
+}
+export class RimeAuthenticationError extends RimeError {
+}
+export class RimePermissionError extends RimeError {
+}
+export class RimeInputError extends RimeError {
+}
+export class RimeResourceLimitError extends RimeError {
+}
+export class RimeUnavailableError extends RimeError {
+}
+export class RimeTimeoutError extends RimeError {
+}
+export class RimeAudioFormatError extends RimeError {
+}
+export class RimeCancelledError extends RimeError {
+}
+export class RimeStreamError extends RimeError {
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Rime, type RimeOptions, type SynthesisOptions, type DiscoveryOptions, type VoiceListOptions, } from "./client.js";
+export { AudioStream } from "./stream.js";
+export { AudioFormat } from "./audio.js";
+export * from "./errors.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Rime, } from "./client.js";
+export { AudioStream } from "./stream.js";
+export { AudioFormat } from "./audio.js";
+export * from "./errors.js";

package/dist/policy.d.ts

@@ -0,0 +1,20 @@
+export declare const policy: {
+    target: string;
+    audience: string;
+    exchangeUrl: string;
+    sentenceBytes: number;
+    sourceChars: number;
+    outputBytes: number;
+    outputChunkBytes: number;
+    receiveBytes: number;
+    authTimeout: number;
+    connectionTimeout: number;
+    firstAudioTimeout: number;
+    progressTimeout: number;
+    discoveryTimeout: number;
+    cleanupTimeout: number;
+};
+export declare function resolve(model: string, endpoint?: string | null): Readonly<typeof policy>;
+export declare function timeout(value: unknown, inherited?: number | null): number | null;
+export declare function nonempty(value: unknown, name: string): string;
+export declare function abortable<T>(promise: PromiseLike<T>, signal: AbortSignal): Promise<T>;