@audicle/sdk 0.1.0

package/README.md

@@ -0,0 +1,244 @@
+# Audicle Node.js SDK
+
+The official Node.js/TypeScript client for the [Audicle](https://audicle.ai) transcription API. Supports batch transcription, real-time streaming over WebSocket, and full transcript management.
+
+## Installation
+
+```bash
+npm install @audicle/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Audicle } from "@audicle/sdk";
+
+const client = new Audicle({ apiKey: "ak_..." });
+
+// Transcribe a file — returns completed transcript synchronously for small files
+const result = await client.transcribe({
+  file: new Blob([audioBuffer], { type: "audio/wav" }),
+});
+console.log(result.result.text);
+```
+
+## Batch Transcription
+
+### From a file
+
+```typescript
+import { readFileSync } from "fs";
+
+const audio = readFileSync("recording.mp3");
+const result = await client.transcribe({
+  file: new Blob([audio], { type: "audio/mpeg" }),
+});
+```
+
+### From a URL
+
+```typescript
+const result = await client.transcribe({
+  audioUrl: "https://example.com/audio.mp3",
+});
+```
+
+### With options
+
+```typescript
+const result = await client.transcribe(
+  { file: audioBlob },
+  {
+    model: "default",
+    language: "en",
+    speakerLabels: true,
+    wordTimestamps: true,
+    webhookUrl: "https://example.com/webhook",
+    metadata: { source: "upload" },
+  },
+);
+```
+
+### Async mode for large files
+
+Small files are transcribed synchronously (result returned inline). For large files or when you want immediate acknowledgment:
+
+```typescript
+// Force async — returns immediately with status "queued"
+const job = await client.transcribe({ file: largeFile }, { async: true });
+
+// Poll until complete
+const done = await client.transcripts.wait(job.id);
+console.log(done.result.text);
+```
+
+### Idempotency
+
+```typescript
+const result = await client.transcribe(
+  { file: audioBlob },
+  { idempotencyKey: "upload-abc-123" },
+);
+// Retrying with the same key returns the cached result
+```
+
+## Transcripts
+
+```typescript
+// Get a transcript
+const txn = await client.transcripts.get("txn_abc123");
+
+// Get as plain text, SRT, or VTT
+const text = await client.transcripts.getText("txn_abc123");
+const srt = await client.transcripts.getSrt("txn_abc123");
+const vtt = await client.transcripts.getVtt("txn_abc123");
+
+// List with filters
+const page = await client.transcripts.list({
+  status: "completed",
+  limit: 25,
+});
+
+// Auto-paginate through all results
+for await (const txn of client.transcripts.listAll()) {
+  console.log(txn.id, txn.status);
+}
+
+// Delete
+await client.transcripts.delete("txn_abc123");
+```
+
+### Polling
+
+```typescript
+// Wait for a queued/processing transcript to finish
+const result = await client.transcripts.wait("txn_abc123", {
+  interval: 2000, // poll every 2s (default: 3s, minimum: 500ms)
+  timeout: 60000, // give up after 60s (default: 5 min)
+});
+```
+
+## Real-Time Streaming
+
+Stream audio over WebSocket for live transcription:
+
+```typescript
+const stream = client.streaming.transcribe({
+  model: "default",
+  sample_rate: 16000,
+  encoding: "pcm_s16le",
+});
+
+stream.on("session.begin", (msg) => {
+  console.log(`Session started: ${msg.id}`);
+});
+
+stream.on("transcript", (msg) => {
+  if (msg.is_final) {
+    console.log(msg.transcript.text);
+  }
+});
+
+stream.on("session.end", (msg) => {
+  console.log(`Done — ${msg.usage.duration_seconds}s`);
+});
+
+// Send PCM audio chunks
+stream.sendAudio(pcmBuffer);
+
+// Signal end of audio
+stream.finalize();
+```
+
+### Models
+
+| Model | Description |
+|---|---|
+| `default` | Whisper-based streaming transcription |
+| `turbo` | Faster Whisper variant |
+| `deepgram-nova-3` | Deepgram Nova 3 (supports interim results + VAD) |
+| `gpt-realtime-mini` | OpenAI Realtime |
+
+### Observing a session
+
+Watch a live transcription session from the dashboard or another client:
+
+```typescript
+const observer = client.streaming.observe("txn_abc123");
+
+observer.on("transcript", (msg) => {
+  console.log(msg.transcript.text);
+});
+```
+
+## Usage
+
+```typescript
+const usage = await client.usage.get({
+  startDate: "2025-01-01",
+  endDate: "2025-01-31",
+  granularity: "day", // "hour" | "day"
+});
+
+console.log(`${usage.total_requests} requests`);
+console.log(`${usage.total_duration_seconds}s total audio`);
+console.log(`$${(usage.total_cost_cents / 100).toFixed(2)} cost`);
+```
+
+## Health Check
+
+```typescript
+const health = await client.health();
+// { status: "healthy", version: "1.0.0", checks: { ... } }
+```
+
+## Error Handling
+
+All API errors throw typed exceptions:
+
+```typescript
+import {
+  AudicleApiError,
+  AudicleAuthError,
+  AudicleNotFoundError,
+  AudicleRateLimitError,
+  AudicleTimeoutError,
+} from "@audicle/sdk";
+
+try {
+  await client.transcripts.get("txn_nonexistent");
+} catch (err) {
+  if (err instanceof AudicleNotFoundError) {
+    console.log(err.status); // 404
+    console.log(err.code); // "transcription_not_found"
+    console.log(err.message); // "Transcription not found"
+    console.log(err.requestId); // "req_..."
+  }
+}
+```
+
+| Error Class | Status | When |
+|---|---|---|
+| `AudicleAuthError` | 401 | Invalid or missing API key |
+| `AudicleNotFoundError` | 404 | Resource doesn't exist |
+| `AudicleRateLimitError` | 429 | Too many requests |
+| `AudicleApiError` | any | All other API errors (400, 402, 500, etc.) |
+| `AudicleTimeoutError` | — | `transcripts.wait()` exceeded timeout |
+
+## Configuration
+
+```typescript
+const client = new Audicle({
+  apiKey: "ak_...", // required
+  baseUrl: "https://api.audicle.ai", // default
+});
+```
+
+## Requirements
+
+- Node.js 18+ or any runtime with `fetch` and `WebSocket` globals
+- Works in Node.js, Bun, Deno, and Cloudflare Workers
+
+## License
+
+MIT