@audialize/sdk 0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# @audialize/sdk
+
+Official TypeScript/JavaScript SDK for the [Audialize](https://audialize.com) API — broadcast-grade audio localization and subtitle generation.
+
+## Installation
+
+```bash
+npm install @audialize/sdk
+# or
+pnpm add @audialize/sdk
+```
+
+**Requires Node.js ≥ 18** (native `fetch`).
+
+## Quick Start
+
+```typescript
+import { AudiolizeClient } from '@audialize/sdk';
+
+const client = new AudiolizeClient({
+  apiKey: process.env.AUDIALIZE_API_KEY,
+});
+
+// High-level: entire pipeline in one call
+const job = await client.localize({
+  file: './interview.mp4',
+  languages: ['nl', 'de'],
+  sourceLanguage: 'en',
+  onUploadProgress: (pct) => console.log(`Upload: ${pct}%`),
+  onProgress: (step, pct) => console.log(`${step}: ${pct}%`),
+});
+
+const srt = await client.subtitles.download(job.jobId, 'nl', 'srt');
+console.log(srt);
+```
+
+## API Reference
+
+### `new AudiolizeClient(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | **required** | Your Audialize API key |
+| `baseUrl` | `string` | `https://api.audialize.com` | API base URL override |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+| `maxRetries` | `number` | `3` | Max retry attempts for transient errors |
+
+---
+
+### `client.localize(options)` → `Promise<Job>`
+
+Full pipeline: upload → poll → return completed job.
+
+```typescript
+const job = await client.localize({
+  file: './speech.mp4',           // string path, Buffer, Blob, or File
+  languages: ['nl', 'de', 'fr'],
+  sourceLanguage: 'en',
+  context: { domain: 'sports' },
+  multipartThreshold: 100 * 1024 * 1024, // 100 MB (default)
+  onUploadProgress: (percent) => {},
+  onProgress: (step, percent) => {},
+  pollOptions: { interval: 3000, timeout: 600000 },
+});
+```
+
+`transcriptionMethod` is intentionally not exposed in the SDK API. The platform selects the optimal transcription engine automatically.
+
+---
+
+### `client.files`
+
+#### `client.files.upload(file, options)` → `Promise<{ jobId: string }>`
+
+Uploads a file (single PUT to GCS via presigned URL) and creates a job.
+
+```typescript
+const { jobId } = await client.files.upload('./speech.mp4', {
+  languages: ['nl'],
+  sourceLanguage: 'en',
+  onUploadProgress: (pct) => console.log(pct),
+});
+```
+
+#### `client.files.uploadMultipart(file, options)` → `Promise<{ jobId: string }>`
+
+Uploads large files (≥ 100 MB by default) in parallel parts.
+
+```typescript
+const { jobId } = await client.files.uploadMultipart(buffer, {
+  languages: ['nl'],
+  concurrency: 4,
+  onUploadProgress: (pct) => console.log(pct),
+});
+```
+
+---
+
+### `client.jobs`
+
+#### `client.jobs.get(jobId)` → `Promise<Job>`
+
+Fetch current job status.
+
+#### `client.jobs.list(options?)` → `Promise<PagedResponse<Job>>`
+
+List jobs with optional `limit` and `pageToken`.
+
+#### `client.jobs.waitForCompletion(jobId, options?)` → `Promise<Job>`
+
+Poll until the job completes or fails.
+
+```typescript
+const job = await client.jobs.waitForCompletion(jobId, {
+  interval: 3000,
+  timeout: 600_000,
+  onProgress: (step, percent) => console.log(`${step}: ${percent}%`),
+});
+```
+
+#### `client.jobs.poll(jobId, options?)` → `JobPoller`
+
+Returns an event-emitting `JobPoller` for fine-grained control.
+
+```typescript
+const poller = client.jobs.poll(jobId, { interval: 5000 });
+
+poller.on('progress', ({ step, progress }) => {
+  process.stdout.write(`\r${step}: ${progress}%`);
+});
+
+poller.on('completed', (job) => console.log('\nDone!', job.jobId));
+poller.on('failed', (err) => console.error(err));
+
+await poller.start();
+```
+
+---
+
+### `client.subtitles`
+
+#### `client.subtitles.download(jobId, language, format)` → `Promise<string | SubtitleResult>`
+
+Downloads subtitle output. `format` is `'srt'`, `'vtt'`, or `'json'`.
+
+```typescript
+const srt = await client.subtitles.download(jobId, 'nl', 'srt');
+const vtt = await client.subtitles.download(jobId, 'nl', 'vtt');
+const obj = await client.subtitles.download(jobId, 'nl', 'json'); // SubtitleResult
+```
+
+---
+
+### `client.languages`
+
+#### `client.languages.list()` → `Promise<Language[]>`
+
+Returns all supported transcription/translation languages.
+
+---
+
+## Error Handling
+
+All SDK errors extend `AudiolizeError`. Import them for typed `catch` blocks:
+
+```typescript
+import {
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  RateLimitError,
+  PaywallError,
+  ServerError,
+  AudiolizeUploadError,
+  AudiolizeTimeoutError,
+  AudiolizeValidationError,
+} from '@audialize/sdk';
+
+try {
+  await client.localize({ file: './video.mp4', languages: ['nl'] });
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (err instanceof PaywallError) {
+    console.error('Budget limit reached — upgrade your plan');
+  } else if (err instanceof AudiolizeTimeoutError) {
+    console.error('Job timed out');
+  } else {
+    throw err;
+  }
+}
+```
+
+---
+
+## Retry Behaviour
+
+| Scenario | Behaviour |
+|----------|-----------|
+| `429` with `Retry-After` | Waits exactly that many seconds |
+| `429` without header | Exponential backoff: 1s, 2s, 4s … cap 60s |
+| `502 / 503 / 504` | Exponential backoff, up to `maxRetries` |
+| `401 / 402 / 403 / 404` | Throws immediately |
+| Network error | Exponential backoff, up to `maxRetries` |
+| GCS presigned PUT | Up to 3 retries (independent counter) |
+
+---
+
+## Environment Variable
+
+For server-side and CI use, set `AUDIALIZE_API_KEY` and pass it via `process.env`:
+
+```typescript
+const client = new AudiolizeClient({
+  apiKey: process.env.AUDIALIZE_API_KEY,
+});
+```
+
+---
+
+## Browser Support
+
+The SDK is ESM-native and works in modern browsers. File system access (`node:fs`) is only used when a file path string is passed — the import is dynamic so it does not appear in browser bundles.
+
+## Frontend Safety
+
+Use this SDK from server-side boundaries for production apps:
+
+- ✅ Node backends, workers, server routes/actions
+- ⚠️ Browser-only usage only when credentials are short-lived and scoped
+- ❌ Never expose long-lived API keys in client-side bundles
+
+For a secure web-app pattern, see `../../docs/FRONTEND_SAFE_USAGE.md` and `../../examples/nextjs-server-route/README.md`.
+
+---
+
+## Troubleshooting
+
+| Problem | Likely cause | Fix |
+|---------|--------------|-----|
+| `AuthenticationError` | Missing/invalid API key | Verify `AUDIALIZE_API_KEY` on server runtime |
+| `RateLimitError` | Too many requests in short window | Back off and retry, honor `Retry-After` |
+| `AudiolizeTimeoutError` | Upstream slow response | Increase `timeout`, keep retries enabled |
+| Upload fails with `UPLOAD_ERROR` | Presigned PUT failed or multipart part issue | Retry upload and verify file/network constraints |
+| `PaywallError` | Subscription/budget limit reached | Upgrade plan or reduce requested workload |
+
+---
+
+## Release Readiness (Maintainers)
+
+Before publishing to npm, run:
+
+```bash
+pnpm release:check
+```
+
+This enforces lint, typecheck, unit tests, contract tests, strict OpenAPI validation, and build gates.
+
+---
+
+## License
+
+MIT © Audialize