@kaana.ai/sdk 0.0.0-stage → 1.0.0

package/NOTICE

@@ -0,0 +1,21 @@
+============================================================================
+ NOTICE
+ @kaana.ai/sdk
+ Copyright (c) 2026-present The Oxy Collective, Inc.
+============================================================================
+
+This product is licensed under the Breathe License 1.0, license identifier
+LicenseRef-Breathe-1.0. See the LICENSE file in this directory. Commercial
+terms are available at
+https://github.com/OxyHQ/.github/blob/main/LICENSE-COMMERCIAL.md
+
+Attribution under Section 3.1 of the Breathe License is required of
+everyone, including paying commercial licensees, and cannot be waived.
+
+----------------------------------------------------------------------------
+ THIRD PARTY COMPONENTS
+----------------------------------------------------------------------------
+
+This package contains no third party source. Its dependencies are resolved
+and installed by the package manager and remain governed by their own
+licenses.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# @kaana.ai/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript client of Kaana's public API, `https://kaana.ai/v1`. It runs in
+Node 20+, browsers and React Native, validates every response against
+[`@kaana.ai/contracts`](https://www.npmjs.com/package/@kaana.ai/contracts) and
+reports failures as typed errors.
+
+Applications, API keys (`oxy_sk_…`), limits, budgets, usage and billing are
+managed in [Oxy Console](https://console.oxy.so). Kaana has no console and
+issues no keys of its own.
+
+```sh
+npm install @kaana.ai/sdk
+```
+
+## Credentials
+
+The credential is the value of `Authorization: Bearer`: a string, or a
+function called on every request. The SDK never caches it; whoever supplies
+the function already caches and renews.
+
+```ts
+import { Kaana } from '@kaana.ai/sdk';
+
+new Kaana({ credential: process.env.KAANA_API_KEY! });                 // oxy_sk_ from Console
+new Kaana({ credential: () => oxyServer.serviceToken({ audience: 'kaana.ai' }) }); // an Oxy service
+new Kaana({ credential: async () => (await oxy.getAccessToken())! });  // an Oxy app session
+```
+
+Options: `baseURL` (only `https://kaana.ai/v1`, or a loopback origin in
+development), `fetch`, `WebSocket` (for realtime where there is no global
+one, e.g. `ws` in older Node), `timeoutMs` (default 120 000) and `maxRetries`
+(default 2: only before the first byte, only for retryable codes, honouring
+`retryAfterMs`).
+
+Every method takes `RequestOptions`: `signal`, `idempotencyKey`
+(`Idempotency-Key`, reused by every retry), `onBehalfOfUserId`
+(`X-Oxy-User-Id`, honoured only with a service token) and `timeoutMs`.
+
+## Methods
+
+```ts
+const kaana = new Kaana({ credential: process.env.KAANA_API_KEY! });
+
+await kaana.models.list();
+await kaana.models.get('elevenlabs/eleven-multilingual@v2');
+await kaana.powerLevels.list();
+
+await kaana.responses.create({ model: 'auto', input: 'Hola' });
+const stream = kaana.responses.stream({ model: 'high', input: 'Cuéntame un cuento' });
+for await (const event of stream) if (event.type === 'delta') process.stdout.write(event.text);
+const response = await stream.final; // the folded Response
+
+await kaana.chat.completions.create({ model: 'instant', messages: [{ role: 'user', content: 'Hola' }] });
+kaana.chat.completions.stream({ model: 'instant', messages: [{ role: 'user', content: 'Hola' }] });
+
+await kaana.embeddings.create({ model: 'openai/text-embedding-3-small', input: ['hola'] });
+await kaana.images.generate({ model: 'openai/gpt-image-1', prompt: 'A fox' });
+await kaana.decisions.create({ model: 'openai/gpt-5@2026-06-01', state: '…', questions: [/* … */] });
+await kaana.generations.get('gen_…');
+await kaana.generations.getByIdempotencyKey('my-key');
+```
+
+A stream is iterated once. Breaking out of the loop, or `stream.abort()`,
+cancels the request upstream. Awaiting `final` alone drains the stream.
+
+The API is also compatible with the OpenAI SDK for chat completions:
+`new OpenAI({ baseURL: 'https://kaana.ai/v1', apiKey: 'oxy_sk_…' })`.
+
+## Audio
+
+```ts
+const speech = await kaana.audio.speech({
+  model: 'elevenlabs/eleven-multilingual',
+  input: 'Hola',
+  voice: 'rachel',
+});
+speech.audio; // Uint8Array, speech.mediaType, speech.model (the served revision), speech.usage
+
+const live = kaana.audio.speechStream({ model: 'elevenlabs/eleven-multilingual', input: 'Hola', voice: 'rachel' });
+for await (const chunk of live) play(chunk); // mp3 or pcm, in order, as produced
+const { model, usage } = await live.done;
+live.toReadableStream(); // the same audio as a ReadableStream
+
+await kaana.audio.transcriptions.create({
+  model: 'openai/whisper-1',
+  file: bytesOrBlob,        // a Blob is sent as multipart; a Uint8Array as JSON with base64
+  mediaType: 'audio/wav',
+  language: 'es-ES',
+});
+```
+
+Voices, languages, formats, the `speed` range and the character limit of each
+speech model are in `models.get(...).audio`; the server checks them before
+anything is reserved.
+
+## Realtime
+
+```ts
+const session = await kaana.realtime.connect({
+  model: 'openai/gpt-realtime',
+  type: 'session.open',
+  kind: 'conversation',
+  config: {
+    outputModalities: ['audio'],
+    voice: 'marin',
+    inputAudioFormat: 'pcm16_24khz',
+    outputAudioFormat: 'pcm16_24khz',
+    turnDetection: { type: 'server_vad', createResponse: true, interruptResponse: true },
+    tools: [{ type: 'function', name: 'lookup', parameters: { type: 'object' } }],
+  },
+});
+
+session.appendAudio(pcm16);            // split into frames of at most 49 152 bytes
+session.send({ type: 'response.create' }); // schemaVersion, requestId and commandId are filled in
+for await (const event of session) {
+  if (event.type === 'tool_call' && event.complete) {
+    session.send({
+      type: 'conversation.item.create',
+      item: { type: 'function_call_output', callId: event.toolCallId, output: '{}' },
+    });
+  }
+}
+const usage = await session.close(); // settles exactly once
+```
+
+The credential travels as a WebSocket subprotocol (`kaana.bearer.…`), so
+realtime works where a WebSocket cannot set headers (browsers, React Native).
+If the connection drops, iteration throws a `KaanaConnectionError`; call
+`session.resume()` within the session's resume window and iterate again:
+what was missed is replayed once, in order.
+
+## Errors
+
+| Class | Codes |
+|---|---|
+| `KaanaAuthenticationError` | `authentication_failed` (keys are managed in [Oxy Console](https://console.oxy.so)) |
+| `KaanaPermissionError` | `permission_denied`, `insufficient_scope`, `commercial_permission_denied`, `policy_violation` |
+| `KaanaInvalidRequestError` | `invalid_request`, `model_not_found`, `unsupported_modality`, `context_length_exceeded`, `request_too_large`, `output_limit_exceeded`, `idempotency_conflict`, `byok_credential_invalid` |
+| `KaanaBillingError` | `insufficient_balance`, `spending_limit_exceeded`, `quota_exceeded` |
+| `KaanaRateLimitError` | `rate_limited` |
+| `KaanaUnavailableError` | `no_route_available`, `service_unavailable`, `provider_error`, `provider_timeout`, `provider_overloaded` |
+| `KaanaContentFilteredError` | `upstream_content_filtered` |
+| `KaanaCancelledError` | `cancelled`, including a request you aborted |
+| `KaanaInternalError` | `internal_error` |
+
+Each `KaanaError` has `code`, `status` (`null` when it arrived as a terminal
+stream event), `requestId`, `retryable`, `retryAfterMs`, `param` and
+`afterOutput` (output reached you before the failure). `KaanaProtocolError` is a
+response outside the contract and is never retried; `KaanaConnectionError` is
+the network or a timeout (`timedOut`) before a response.
+
+## React Native
+
+Non-streaming methods work with React Native's built-in `fetch`. The streaming
+methods (`responses.stream`, `chat.completions.stream`, `audio.speechStream`)
+need a `fetch` whose response body is a `ReadableStream`; install a streaming
+fetch polyfill and pass it as `fetch`. Without one they fail with a clear
+`KaanaConnectionError` instead of buffering silently. Transcription of bytes
+uses JSON with base64, so no `Blob` support is required. React Native's
+`WebSocket` carries realtime sessions as is.
+
+## License
+
+Breathe License 1.0 — see `LICENSE` and `NOTICE`.

package/dist/audio.d.ts

@@ -0,0 +1,39 @@
+/** `POST /v1/audio/speech` (whole and streamed) and `POST /v1/audio/transcriptions`. */
+import { type AudioInputMediaType, type AudioMediaType, type ModelReference, type SpeechRequest, type Transcription, type Usage } from '@kaana.ai/contracts';
+import { type RequestOptions, type Transport } from './http.js';
+export interface SpeechResult {
+    audio: Uint8Array;
+    /** 'audio/mpeg' | 'audio/wav' | 'audio/ogg' | 'audio/aac' | 'audio/flac' | 'audio/pcm' */
+    mediaType: AudioMediaType;
+    /** The revision that actually served the request. */
+    model: ModelReference;
+    requestId: string;
+    usage: Usage;
+}
+/**
+ * Audio in order, as soon as it is produced (`stream_format: 'sse'`, so a
+ * failure mid-stream arrives typed).
+ */
+export interface SpeechStream extends AsyncIterable<Uint8Array> {
+    readonly mediaType: Promise<AudioMediaType>;
+    readonly requestId: Promise<string>;
+    toReadableStream(): ReadableStream<Uint8Array>;
+    /** Model, usage and requestId at the end; rejects with KaanaError. */
+    readonly done: Promise<Omit<SpeechResult, 'audio'>>;
+    abort(reason?: unknown): void;
+}
+export interface TranscriptionRequest {
+    model: ModelReference;
+    /** A Blob is uploaded as multipart; bytes are sent as JSON with inline base64. */
+    file: Blob | Uint8Array;
+    mediaType: AudioInputMediaType;
+    /** BCP 47, validated against the catalogue. */
+    language?: string;
+    prompt?: string;
+    timestamps?: 'none' | 'segment' | 'word';
+}
+export declare function speech(transport: Transport, request: SpeechRequest, options: RequestOptions): Promise<SpeechResult>;
+export declare function speechStream(transport: Transport, request: SpeechRequest, options: RequestOptions): SpeechStream;
+/** `unit=quantity,unit=quantity`, each unit once. */
+export declare function parseUsageHeader(header: string | null, requestId: string): Usage;
+export declare function transcribe(transport: Transport, request: TranscriptionRequest, options: RequestOptions): Promise<Transcription>;

package/dist/audio.js

@@ -0,0 +1,250 @@
+/** `POST /v1/audio/speech` (whole and streamed) and `POST /v1/audio/transcriptions`. */
+import { audioInputMediaTypeSchema, KAANA_MODEL_HEADER, KAANA_USAGE_HEADER, MAX_INFERENCE_AUDIO_BYTES, MAX_TRANSCRIPTION_FILE_BYTES, modelReferenceSchema, STREAMABLE_SPEECH_FORMATS, speechMediaType, speechRequestSchema, speechStreamEventSchema, transcriptionJsonRequestSchema, transcriptionRequestSchema, transcriptionSchema, usageSchema, } from '@kaana.ai/contracts';
+import { concatBytes, decodeBase64, encodeBase64 } from './base64.js';
+import { clientRefusal, fromPublicError, KaanaProtocolError } from './errors.js';
+import { cutOff, frameJson, readFrames, streamingBody } from './events.js';
+import { bodyReadFailure, mediaTypeOf, validate, } from './http.js';
+import { deferred, StreamHandle } from './stream.js';
+/* -------------------------------------------------------------------------- */
+/*  Speech                                                                     */
+/* -------------------------------------------------------------------------- */
+export async function speech(transport, request, options) {
+    if (request.stream === true || request.stream_format !== undefined) {
+        throw clientRefusal('stream', 'audio.speech returns whole audio; use audio.speechStream');
+    }
+    const body = checked(request);
+    const sent = await transport.send({
+        method: 'POST',
+        path: '/audio/speech',
+        body,
+        accept: 'audio/*',
+        options,
+    });
+    const requestId = sent.requestId;
+    const mediaType = speechMediaType(request.response_format ?? 'mp3');
+    try {
+        if (mediaTypeOf(sent.response) !== mediaType) {
+            throw new KaanaProtocolError(`Speech in ${request.response_format ?? 'mp3'} was answered with ${mediaTypeOf(sent.response) ?? 'no Content-Type'}.`, requestId);
+        }
+        const model = validate(sent.response.headers.get(KAANA_MODEL_HEADER), modelReferenceSchema, requestId, `${KAANA_MODEL_HEADER} header`);
+        const usage = parseUsageHeader(sent.response.headers.get(KAANA_USAGE_HEADER), requestId);
+        const audio = await readAudio(sent);
+        if (audio.byteLength === 0) {
+            throw new KaanaProtocolError('The speech response carries no audio.', requestId);
+        }
+        return { audio, mediaType, model, requestId, usage };
+    }
+    catch (error) {
+        sent.abort();
+        throw error;
+    }
+    finally {
+        sent.release();
+    }
+}
+export function speechStream(transport, request, options) {
+    const format = request.response_format ?? 'mp3';
+    if (!STREAMABLE_SPEECH_FORMATS.includes(format)) {
+        throw clientRefusal('response_format', `streamed speech is ${STREAMABLE_SPEECH_FORMATS.join(' or ')}; ${format} exists only whole`);
+    }
+    const body = checked({ ...request, stream: true, stream_format: 'sse' });
+    const mediaType = speechMediaType(format);
+    const handle = new StreamHandle(async function* (context) {
+        const sent = await transport.send({
+            method: 'POST',
+            path: '/audio/speech',
+            body,
+            accept: 'text/event-stream',
+            options: { ...options, signal: context.signal },
+            stream: true,
+        });
+        const requestId = sent.requestId;
+        context.setRequestId(requestId);
+        let output = false;
+        for await (const frame of readFrames(sent, () => output)) {
+            const event = validate(frameJson(frame, requestId), speechStreamEventSchema, requestId, 'speech event');
+            if (frame.event !== event.type) {
+                throw new KaanaProtocolError(`The stream framed a ${event.type} event as ${frame.event || 'unnamed'}.`, requestId);
+            }
+            switch (event.type) {
+                case 'speech.audio.delta':
+                    output = true;
+                    context.markOutput();
+                    yield decodeBase64(event.audio);
+                    break;
+                case 'speech.audio.done':
+                    if (event.requestId !== requestId) {
+                        throw new KaanaProtocolError('The stream ended for another request.', requestId);
+                    }
+                    return { mediaType, model: event.model, requestId, usage: event.usage };
+                case 'error':
+                    throw fromPublicError(event.error, null, output);
+            }
+        }
+        throw cutOff(requestId);
+    }, options.signal);
+    const mediaTypePromise = deferred();
+    mediaTypePromise.resolve(mediaType);
+    return {
+        mediaType: mediaTypePromise.promise,
+        get requestId() {
+            return handle.requestId;
+        },
+        get done() {
+            return handle.final;
+        },
+        abort: (reason) => handle.abort(reason),
+        [Symbol.asyncIterator]: () => handle[Symbol.asyncIterator](),
+        toReadableStream() {
+            const iterator = handle[Symbol.asyncIterator]();
+            return new ReadableStream({
+                async pull(controller) {
+                    try {
+                        const next = await iterator.next();
+                        if (next.done)
+                            controller.close();
+                        else
+                            controller.enqueue(next.value);
+                    }
+                    catch (error) {
+                        controller.error(error);
+                    }
+                },
+                async cancel() {
+                    await iterator.return?.();
+                },
+            });
+        },
+    };
+}
+function checked(request) {
+    const parsed = speechRequestSchema.safeParse(request);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw clientRefusal(String(issue?.path[0] ?? 'request'), issue?.message ?? 'invalid request');
+    }
+    return JSON.stringify(request);
+}
+/** `unit=quantity,unit=quantity`, each unit once. */
+export function parseUsageHeader(header, requestId) {
+    if (header === null) {
+        throw new KaanaProtocolError(`The response carries no ${KAANA_USAGE_HEADER}.`, requestId);
+    }
+    const units = header.trim().length === 0
+        ? []
+        : header.split(',').map((pair) => {
+            const [unit, quantity, extra] = pair.trim().split('=');
+            if (extra !== undefined || quantity === undefined || !/^\d+$/.test(quantity)) {
+                throw new KaanaProtocolError(`${KAANA_USAGE_HEADER} is malformed.`, requestId);
+            }
+            return { unit, quantity: Number(quantity) };
+        });
+    return validate(units, usageSchema, requestId, `${KAANA_USAGE_HEADER} header`);
+}
+async function readAudio(sent) {
+    const body = sent.response.body;
+    if (body === null || typeof body.getReader !== 'function') {
+        // Runtimes without a streaming body still give the whole buffer.
+        let buffer;
+        try {
+            buffer = await sent.response.arrayBuffer();
+        }
+        catch (cause) {
+            throw bodyReadFailure(sent, cause);
+        }
+        if (buffer.byteLength > MAX_INFERENCE_AUDIO_BYTES) {
+            throw new KaanaProtocolError('The speech audio exceeds its size limit.', sent.requestId);
+        }
+        return new Uint8Array(buffer);
+    }
+    const reader = streamingBody(sent).getReader();
+    const chunks = [];
+    let size = 0;
+    let completed = false;
+    try {
+        while (true) {
+            let next;
+            try {
+                next = await reader.read();
+            }
+            catch (cause) {
+                throw bodyReadFailure(sent, cause);
+            }
+            if (next.done) {
+                completed = true;
+                break;
+            }
+            size += next.value.byteLength;
+            if (size > MAX_INFERENCE_AUDIO_BYTES) {
+                throw new KaanaProtocolError('The speech audio exceeds its size limit.', sent.requestId);
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        if (!completed)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+    return concatBytes(chunks);
+}
+/* -------------------------------------------------------------------------- */
+/*  Transcription                                                              */
+/* -------------------------------------------------------------------------- */
+const EXTENSIONS = {
+    'audio/mpeg': 'mp3',
+    'audio/mp4': 'm4a',
+    'audio/wav': 'wav',
+    'audio/ogg': 'ogg',
+    'audio/webm': 'webm',
+    'audio/flac': 'flac',
+    'audio/aac': 'aac',
+    'audio/pcm': 'pcm',
+};
+export async function transcribe(transport, request, options) {
+    const fields = {
+        model: request.model,
+        ...(request.language === undefined ? {} : { language: request.language }),
+        ...(request.prompt === undefined ? {} : { prompt: request.prompt }),
+        ...(request.timestamps === undefined ? {} : { timestamps: request.timestamps }),
+    };
+    const parsedFields = transcriptionRequestSchema.safeParse(fields);
+    if (!parsedFields.success) {
+        const issue = parsedFields.error.issues[0];
+        throw clientRefusal(String(issue?.path[0] ?? 'request'), issue?.message ?? 'invalid request');
+    }
+    if (!audioInputMediaTypeSchema.safeParse(request.mediaType).success) {
+        throw clientRefusal('mediaType', `${String(request.mediaType)} is not an accepted audio type`);
+    }
+    const isBlob = typeof Blob !== 'undefined' && request.file instanceof Blob;
+    const size = isBlob ? request.file.size : request.file.byteLength;
+    if (size === 0)
+        throw clientRefusal('file', 'the audio file is empty');
+    if (size > MAX_TRANSCRIPTION_FILE_BYTES) {
+        throw clientRefusal('file', `the audio file exceeds ${MAX_TRANSCRIPTION_FILE_BYTES} bytes`);
+    }
+    let body;
+    if (isBlob) {
+        const blob = request.file;
+        const part = blob.type === request.mediaType ? blob : new Blob([blob], { type: request.mediaType });
+        const form = new FormData();
+        form.append('file', part, `audio.${EXTENSIONS[request.mediaType]}`);
+        for (const [name, value] of Object.entries(fields))
+            form.append(name, value);
+        body = form;
+    }
+    else {
+        const json = {
+            ...fields,
+            audio: { mediaType: request.mediaType, data: encodeBase64(request.file) },
+        };
+        const parsedJson = transcriptionJsonRequestSchema.safeParse(json);
+        if (!parsedJson.success) {
+            const issue = parsedJson.error.issues[0];
+            throw clientRefusal(issue?.path.map(String).join('.') || 'file', issue?.message ?? 'invalid');
+        }
+        body = JSON.stringify(json);
+    }
+    const { value } = await transport.json({ method: 'POST', path: '/audio/transcriptions', body, accept: 'application/json', options }, transcriptionSchema);
+    return value;
+}

package/dist/base64.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base64 without a platform module: no `Buffer`, no `btoa`/`atob` (which are
+ * Latin-1 string APIs and absent from some React Native runtimes). The SDK
+ * encodes audio frames and credentials with these and nothing else.
+ */
+/** Standard padded base64 (RFC 4648 §4). */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/** Unpadded base64url (RFC 4648 §5), the form a WebSocket subprotocol token can carry. */
+export declare function encodeBase64Url(bytes: Uint8Array): string;
+/**
+ * Decode standard or url-safe base64, padded or not. Throws on any character
+ * outside the alphabet or an impossible length, never silently skipping.
+ */
+export declare function decodeBase64(text: string): Uint8Array;
+/** UTF-8 bytes of a string. */
+export declare function utf8(text: string): Uint8Array;
+/** Concatenate byte chunks. */
+export declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;

package/dist/base64.js

@@ -0,0 +1,87 @@
+/**
+ * Base64 without a platform module: no `Buffer`, no `btoa`/`atob` (which are
+ * Latin-1 string APIs and absent from some React Native runtimes). The SDK
+ * encodes audio frames and credentials with these and nothing else.
+ */
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const DECODE = (() => {
+    const table = new Int16Array(128).fill(-1);
+    for (let index = 0; index < ALPHABET.length; index += 1) {
+        table[ALPHABET.charCodeAt(index)] = index;
+    }
+    // base64url spellings decode to the same values.
+    table['-'.charCodeAt(0)] = 62;
+    table['_'.charCodeAt(0)] = 63;
+    return table;
+})();
+/** Standard padded base64 (RFC 4648 §4). */
+export function encodeBase64(bytes) {
+    let out = '';
+    let index = 0;
+    for (; index + 2 < bytes.length; index += 3) {
+        const chunk = (bytes[index] << 16) | (bytes[index + 1] << 8) | bytes[index + 2];
+        out +=
+            ALPHABET[(chunk >> 18) & 63] +
+                ALPHABET[(chunk >> 12) & 63] +
+                ALPHABET[(chunk >> 6) & 63] +
+                ALPHABET[chunk & 63];
+    }
+    const rest = bytes.length - index;
+    if (rest === 1) {
+        const chunk = bytes[index] << 16;
+        out += `${ALPHABET[(chunk >> 18) & 63]}${ALPHABET[(chunk >> 12) & 63]}==`;
+    }
+    else if (rest === 2) {
+        const chunk = (bytes[index] << 16) | (bytes[index + 1] << 8);
+        out += `${ALPHABET[(chunk >> 18) & 63]}${ALPHABET[(chunk >> 12) & 63]}${ALPHABET[(chunk >> 6) & 63]}=`;
+    }
+    return out;
+}
+/** Unpadded base64url (RFC 4648 §5), the form a WebSocket subprotocol token can carry. */
+export function encodeBase64Url(bytes) {
+    return encodeBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Decode standard or url-safe base64, padded or not. Throws on any character
+ * outside the alphabet or an impossible length, never silently skipping.
+ */
+export function decodeBase64(text) {
+    const trimmed = text.replace(/=+$/, '');
+    if (trimmed.length % 4 === 1)
+        throw new Error('base64 has an impossible length');
+    const out = new Uint8Array(Math.floor((trimmed.length * 3) / 4));
+    let buffer = 0;
+    let bits = 0;
+    let position = 0;
+    for (let index = 0; index < trimmed.length; index += 1) {
+        const code = trimmed.charCodeAt(index);
+        const value = code < 128 ? DECODE[code] : -1;
+        if (value < 0)
+            throw new Error('base64 contains a character outside its alphabet');
+        buffer = (buffer << 6) | value;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[position] = (buffer >> bits) & 0xff;
+            position += 1;
+        }
+    }
+    return out;
+}
+/** UTF-8 bytes of a string. */
+export function utf8(text) {
+    return new TextEncoder().encode(text);
+}
+/** Concatenate byte chunks. */
+export function concatBytes(chunks) {
+    let size = 0;
+    for (const chunk of chunks)
+        size += chunk.byteLength;
+    const out = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}

package/dist/chat.d.ts

@@ -0,0 +1,11 @@
+/** `POST /v1/chat/completions`, the OpenAI dialect: whole and streamed. */
+import { type ChatCompletion, type ChatCompletionChunk } from '@kaana.ai/contracts';
+import { type RequestOptions, type Transport } from './http.js';
+import { type KaanaStream } from './stream.js';
+export declare function chatStream(transport: Transport, body: string, options: RequestOptions): KaanaStream<ChatCompletionChunk, ChatCompletion>;
+/** Folds the chunks of one completion into the `ChatCompletion` it describes. */
+export declare class ChatFold {
+    #private;
+    add(chunk: ChatCompletionChunk): void;
+    completion(requestId: string): ChatCompletion;
+}