@tryhakim/voice 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hakim AI
+
+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,188 @@
+# @tryhakim/voice
+
+Official Node.js / TypeScript client for the [Hakim](https://tryhakim.ai) API.
+
+> **Status:** `1.0.0` — stable.
+
+## Install
+
+```bash
+npm install @tryhakim/voice
+```
+
+Requires Node.js **>= 18** (uses native `fetch`, `AbortController`,
+`FormData`, `Blob`). Works on Bun and Deno too.
+
+## Quickstart
+
+```ts
+import { Hakim } from '@tryhakim/voice';
+import { writeFile } from 'node:fs/promises';
+
+const hakim = new Hakim({
+  apiKey: process.env.HAKIM_API_KEY!,
+});
+
+// 0. Discover available voices. Each row carries an `id` (stable,
+//    unique — recommended for production traffic) and a `slug` (e.g.
+//    `priya-hi`) for readability.
+const voices = await hakim.audio.voices.list();
+const priya = voices.find((v) => v.slug === 'priya-hi');
+if (!priya) throw new Error('voice not provisioned');
+
+// 1. Synthesize speech (buffered). Pass `id` rather than `slug` —
+//    slugs may collide between a preset and an org clone with the
+//    same name, and they shift if a voice is renamed.
+const speech = await hakim.audio.speech.create({
+  model: 'hakim-fast-v1',
+  input: 'مرحبا بك في منصتنا',
+  voice: priya.id,
+  response_format: 'mp3',
+});
+await writeFile('out.mp3', speech.audio);
+console.log('billed', speech.usageCharacters, 'characters');
+
+// 2. Streaming synthesis (low-latency start).
+const { stream } = await hakim.audio.speech.stream({
+  model: 'hakim-fast-v1',
+  input: 'مرحبا',
+  voice: priya.id,
+});
+for await (const chunk of stream) {
+  process.stdout.write(chunk);
+}
+
+// 3. Transcribe audio.
+import { readFile } from 'node:fs/promises';
+const audio = await readFile('clip.wav');
+const result = await hakim.audio.transcriptions.create({
+  file: audio,
+  model: 'hakim-arab-v2',
+  language: 'ar',
+  response_format: 'json',
+});
+if (result.kind === 'sync_json') console.log(result.data.text);
+
+// 4. List voices.
+const { data: voices } = await hakim.audio.voices.list({ language: 'ar' });
+
+// 5. Usage summary.
+const summary = await hakim.usage.summary();
+console.log(`${summary.tts.characters} / ${summary.tts.included} TTS characters used`);
+```
+
+## Chat completions (`hakim.chat.completions`)
+
+OpenAI-compatible chat API backed by Hakim's Arabic-first LLM
+(`hakim-chat-v1`). Drop-in compatible with any code that targets
+the OpenAI Chat Completions reference — swap the base URL and key
+and you're done.
+
+```ts
+// Non-streaming.
+const completion = await hakim.chat.completions.create({
+  model: 'hakim-chat-v1',
+  messages: [
+    { role: 'system', content: 'أنت مساعد عربي مفيد.' },
+    { role: 'user', content: 'اكتب قصيدة قصيرة عن البحر.' },
+  ],
+  temperature: 0.7,
+});
+console.log(completion.choices[0].message.content);
+console.log('billed', completion.usage_headers?.credits, 'credits');
+
+// Streaming (SSE). Stream replies token-by-token; the final chunk
+// carries the rolled-up `usage` block.
+const { stream } = await hakim.chat.completions.stream({
+  model: 'hakim-chat-v1',
+  messages: [{ role: 'user', content: 'مرحبا!' }],
+});
+for await (const chunk of stream) {
+  const delta = chunk.choices[0]?.delta.content;
+  if (delta) process.stdout.write(delta);
+  if (chunk.usage) console.log('\n[usage]', chunk.usage);
+}
+```
+
+### Reasoning / chain-of-thought
+
+`hakim-chat-v1` is a thinking-capable model. The chain-of-thought
+trace is **off by default** — it adds 10–50× latency and burns
+completion tokens that don't reach your UI in time.
+
+Opt in on **non-streaming** requests only:
+
+```ts
+const completion = await hakim.chat.completions.create({
+  model: 'hakim-chat-v1',
+  messages: [{ role: 'user', content: 'حلّ ٢٤ × ١٧ خطوة بخطوة.' }],
+  reasoning: { enabled: true },
+});
+console.log(completion.choices[0].message.reasoning); // chain-of-thought
+console.log(completion.choices[0].message.content); // final answer
+```
+
+Streaming requests with `reasoning: { enabled: true }` are
+rejected with a `400 invalid_request_error` — real-time agents
+cannot afford the latency cost. Make a non-streaming request if
+you need CoT.
+
+## Configuration
+
+```ts
+new Hakim({
+  apiKey: 'hk_live_...', // or HAKIM_API_KEY env
+  baseURL: 'https://api.tryhakim.ai', // or HAKIM_BASE_URL env
+  timeoutMs: 120_000, // per-request; TTS can be slow
+  maxRetries: 2, // on 5xx / 429 / connection errors
+  userAgentSuffix: 'my-app/1.0.0', // appended to the SDK UA
+});
+```
+
+## Feature highlights
+
+- **Native `fetch`** — no `axios` / `undici` dependency; bundle stays small.
+- **Typed request/response shapes** mirroring the Hakim API schema.
+- **Uniform error model**: every non-2xx surfaces as a `HakimError`
+  subclass (`AuthenticationError`, `RateLimitError`, `QuotaExceededError`,
+  `IdempotencyConflictError`, …). All errors carry `status`, `type`,
+  `code`, and `requestId` for support tickets.
+- **Automatic retries** with jittered exponential backoff on `5xx`,
+  `429`, `408`, and low-level connection errors. Honors `Retry-After`.
+- **Auto-`Idempotency-Key`** on mutating JSON calls (can be overridden
+  per call via `{ idempotencyKey: '…' }`).
+- **`X-Request-Id`** generated per call and echoed back on both
+  success (`response.meta.requestId`) and failure (`err.requestId`).
+- **Streaming TTS** via `AsyncIterable<Uint8Array>` — no need to touch
+  the raw `ReadableStream`.
+- **AbortSignal support** on every call.
+- **Cursor pagination** auto-walked by `usage.eventsIter`.
+
+## Errors
+
+```ts
+import {
+  Hakim,
+  HakimError,
+  RateLimitError,
+  QuotaExceededError,
+} from '@tryhakim/voice';
+
+try {
+  await hakim.audio.speech.create({ ... });
+} catch (err) {
+  if (err instanceof RateLimitError && err.retryAfterMs) {
+    await new Promise((r) => setTimeout(r, err.retryAfterMs));
+  } else if (err instanceof QuotaExceededError) {
+    console.error('plan exhausted — upgrade at /app/settings/billing');
+  } else if (err instanceof HakimError) {
+    console.error(`[${err.requestId}] ${err.type}/${err.code}: ${err.message}`);
+  } else {
+    throw err;
+  }
+}
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/audio/speech-stream-ws.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Realtime TTS over WebSocket (`WSS /v1/audio/speech/stream`).
+ *
+ * The SDK translates server frames into friendly `SpeechStreamEvent`s
+ * and emits caller `sendSpeech({...})` requests as `speech.create`
+ * frames upstream.
+ *
+ * Like the STT counterpart in `./stream.ts`, this helper stays
+ * dependency-free. We prefer `globalThis.WebSocket` when present
+ * (Node 22+, Bun, Deno, browsers). On Node 18/20 the global isn't
+ * there — we dynamically import `ws` at runtime and surface a
+ * helpful error if it's missing.
+ *
+ * The handle is lazy: the socket opens on the first `sendSpeech` /
+ * iteration of `events` / `audio` / `close`. This keeps the hot
+ * path fast and avoids dangling connections when a caller
+ * constructs a handle but bails before using it.
+ *
+ * Binary chunks coming back from the server are surfaced as
+ * `speech.audio` events (each carries a `chunk: Uint8Array`) so
+ * consumers can iterate a single stream of events instead of
+ * juggling a separate audio channel. The companion `audio` iterable
+ * filters to those chunks for callers who only want raw PCM.
+ */
+import type { Transport } from '../transport.js';
+import type { SpeechStreamEvent, SpeechStreamHandle, SpeechStreamOptions } from '../types.js';
+export declare function openSpeechStream(transport: Transport, opts?: SpeechStreamOptions): SpeechStreamHandle;
+export declare function translateFrame(frame: unknown): SpeechStreamEvent | null;
+export declare function buildSessionUpdate(session: Partial<SpeechStreamOptions>): {
+    type: 'session.update';
+    session: Record<string, unknown>;
+} | null;
+declare function buildWsUrl(baseURL: string): string;
+export declare const __internals: {
+    translateFrame: typeof translateFrame;
+    buildSessionUpdate: typeof buildSessionUpdate;
+    buildWsUrl: typeof buildWsUrl;
+};
+export {};
+//# sourceMappingURL=speech-stream-ws.d.ts.map

package/dist/audio/speech-stream-ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech-stream-ws.d.ts","sourceRoot":"","sources":["../../src/audio/speech-stream-ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EAEpB,MAAM,aAAa,CAAC;AAcrB,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,EACpB,IAAI,GAAE,mBAAwB,GAC7B,kBAAkB,CAmTpB;AAyGD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAqEvE;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACpC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAQrE;AAED,iBAAS,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK3C;AAqED,eAAO,MAAM,WAAW;;;;CAAqD,CAAC"}