@transcribe-api/sdk 0.1.3 → 0.1.6

package/README.md

@@ -1,75 +1,413 @@
-# Transcribe API JavaScript SDK
-
-Official JavaScript SDK for Transcribe API.
-
-## Installation
-
-```bash
-npm install @transcribe-api/sdk
-```
-
-## Usage
-
+# Transcribe API JavaScript SDK
+
+Official JavaScript SDK for Transcribe API.
+
+Use this SDK to send one file, many files, local uploads, remote audio URLs, webhook jobs, and large multipart uploads to the Transcribe API from Node.js and modern JavaScript runtimes.
+
+## Installation
+
+```bash
+npm install @transcribe-api/sdk
+```
+
+## Import
+
+```js
+import { TranscribeAPI, TranscribeAPIError } from "@transcribe-api/sdk";
+```
+
+The default export is also `TranscribeAPI`:
+
+```js
+import TranscribeAPI from "@transcribe-api/sdk";
+```
+
+## Quick start
+
 ```js
 import { TranscribeAPI } from "@transcribe-api/sdk";
-
+
+const client = new TranscribeAPI({
+  apiKey: process.env.TRANSCRIBE_API_KEY,
+  polling: {
+    interval: 10,
+    timeout: 15 * 60,
+  },
+});
+
+const result = await client.transcribe({
+  language: "en",
+  files: [
+    { reference_id: "meeting_001", file: "./meeting.mp3" },
+  ],
+});
+
+console.log(result);
+```
+
+`client.transcribe({ files: [...] })` is the main API for both single-file and multi-file transcription.
+
+## How `transcribe` routes work
+
+The SDK automatically chooses the right API flow:
+
+- One small local file is sent through the direct synchronous upload path.
+- One remote URL is sent through the direct `/v1/transcribe` endpoint and the API decides whether it can finish immediately or should continue as an async job.
+- Multiple files, files larger than 30 MB, and files estimated over 10 minutes are sent through the async job flow.
+- Large local async uploads use signed R2 upload URLs returned by the API.
+- Multipart upload is used automatically when the backend returns multipart upload instructions.
+- If `polling` is configured, async calls wait until the job reaches a terminal status.
+- If `polling` is not configured, async calls return the upload-completion/job response. Use `client.jobs.get(job_id)` or `client.waitForJobCompletion(job_id, ...)` to check later.
+
+Terminal job statuses are `completed`, `failed`, and `insufficient_funds`. Completed job responses include `result_url` when the API has a result file ready.
+
+## Client options
+
+```js
 const client = new TranscribeAPI({
   apiKey: "YOUR_API_KEY",
+  baseUrl: "https://api.transcribeapi.com/v1",
+  uploadConcurrency: 4,
   showLogs: true,
+  logger: console,
   polling: {
     interval: 10,
     timeout: 15 * 60,
   },
 });
-
-const transcript = await client.transcribe({
-  file: "audio.mp3",
-});
-
-const asyncJob = await client.transcribe({
-  file: "long-audio.mp3",
-  multipartConcurrency: 8,
-});
-
-const batchJob = await client.batch.transcribe({
+```
+
+| Option | Description |
+| --- | --- |
+| `apiKey` | Required. Your Transcribe API key. |
+| `baseUrl` | Optional. Defaults to `https://api.transcribeapi.com/v1`. |
+| `uploadConcurrency` | Optional. Number of in-flight upload PUTs. Defaults to `1` and is capped at `32`. |
+| `showLogs` | Optional. Prints upload progress, upload completion, polling status, and final result info. |
+| `logger` | Optional. Logger object with a `log` method. Defaults to `console`. |
+| `polling` | Optional. `{ interval, timeout }` in seconds. `interval` must be at least `10`. Omit or set to `null`/`false` to disable automatic polling. |
+
+## File inputs
+
+Each item in `files` must be an object with either `file` or `url`:
+
+```js
+{ reference_id: "episode_1", file: "./episode.mp3" }
+{ reference_id: "episode_2", url: "https://example.com/signed-audio-url.mp3" }
+```
+
+Supported local/upload inputs:
+
+- Node.js local file path strings, such as `"./audio.mp3"`.
+- `File` objects.
+- `Blob` objects.
+- `{ data, name, type }`, where `data` is a `Uint8Array` or `ArrayBuffer`.
+
+Supported remote inputs:
+
+- Public or signed URLs using `{ url: "https://..." }`.
+
+Do not include both `file` and `url` in the same item.
+
+## Single local file
+
+```js
+const result = await client.transcribe({
+  files: [
+    { reference_id: "call_001", file: "./call.mp3" },
+  ],
+  language: "en",
+});
+```
+
+For one small local file, this usually uses the direct upload path. Larger files automatically become async jobs.
+
+## Remote URL transcription
+
+```js
+const job = await client.transcribe({
+  files: [
+    { reference_id: "remote_001", url: "https://example.com/audio.mp3" },
+  ],
+  language: "en",
+});
+```
+
+For one remote URL, the SDK submits the request to the direct `/v1/transcribe` endpoint and lets the API decide the final route. Small remote files may complete immediately, while larger or longer remote files automatically fall back to the async job flow.
+
+## Batch and mixed input transcription
+
+```js
+const job = await client.transcribe({
+  language: "en",
+  uploadConcurrency: 8,
+  files: [
+    { reference_id: "episode_1", file: "./episode-1.mp3" },
+    { reference_id: "episode_2", file: "./episode-2.wav" },
+    { reference_id: "episode_3", url: "https://example.com/episode-3.m4a" },
+  ],
+});
+```
+
+Local files and remote URLs can be mixed in the same batch. When sending multiple files through `transcribe`, provide a unique `reference_id` for every item.
+
+## Per-file language
+
+Set `language` at the top level to apply a default to the whole job. Set `language` on a file item to override the default for that file.
+
+```js
+const job = await client.transcribe({
+  language: "en",
+  files: [
+    { reference_id: "intro", file: "./intro.mp3" },
+    { reference_id: "french_segment", file: "./segment.m4a", language: "fr" },
+  ],
+});
+```
+
+`language` must be a two-letter language code such as `en`, `fr`, or `es`. Omit it, pass an empty value, or pass `"auto"` to avoid sending an explicit language.
+
+## Excluding outputs or features
+
+Use `exclude` to pass API exclusions. Arrays are joined with commas before sending. Valid values are only `vtt`, `segments`, `metadata`, `billing`, and `detected_language`.
+
+```js
+const result = await client.transcribe({
+  files: [
+    { reference_id: "meeting", file: "./meeting.mp3" },
+  ],
+  exclude: ["vtt", "segments"],
+});
+```
+
+You can also pass a comma-separated string:
+
+```js
+exclude: "metadata,billing"
+```
+
+If `exclude` leaves only one transcript field and removes metadata, billing, and detected language, the API returns that remaining value directly instead of a JSON object. For example, text-only responses return a plain string, VTT-only responses return a plain string, and segments-only responses return an array.
+
+## Webhooks
+
+```js
+const job = await client.transcribe({
+  webhookUrl: "https://example.com/transcribe-webhook",
+  files: [
+    { reference_id: "upload_001", file: "./long-audio.mp3" },
+  ],
+});
+```
+
+For a single file or URL, `webhookUrl` is sent through the direct `/v1/transcribe` endpoint and the API decides whether it can finish immediately or should continue as a job. Multi-file requests still use the async batch flow.
+
+## Progress and logs
+
+Use `onProgress` to receive structured progress events:
+
+```js
+const job = await client.transcribe({
+  files: [
+    { reference_id: "episode_1", file: "./episode-1.mp3" },
+    { reference_id: "episode_2", file: "./episode-2.mp3" },
+  ],
+  uploadConcurrency: 4,
+  onProgress(event) {
+    console.log(event);
+  },
+});
+```
+
+Common event names:
+
+- `upload_urls_received`
+- `upload_started`
+- `upload_progress`
+- `upload_completed`
+
+Progress events may include `jobId`, `jobStatus`, `referenceId`, `loaded`, `total`, `fileLoaded`, `fileTotal`, `batchLoaded`, `batchTotal`, `uploadType`, `partNumber`, `totalParts`, and `multipartConcurrency`.
+
+Set `showLogs: true` on the client or on a single call to print built-in progress and polling logs:
+
+```js
+const client = new TranscribeAPI({
+  apiKey: process.env.TRANSCRIBE_API_KEY,
+  showLogs: true,
+});
+```
+
+## Manual async jobs
+
+`transcribe` uploads automatically. Use `createBatchJob` when you want to separate job creation from upload.
+
+```js
+const job = await client.createBatchJob({
+  language: "en",
   files: [
-    { reference_id: "episode_1", file: "a.mp3" },
-    { reference_id: "episode_2", file: "b.wav" },
+    { reference_id: "part_1", file: "./part-1.mp3" },
+    { reference_id: "part_2", url: "https://example.com/part-2.mp3" },
   ],
 });
 
-const remoteJob = await client.transcribe({
-  file: { url: "https://signed-get-url-from-s3-or-r2" },
-});
-
-const remoteBatchJob = await client.batch.transcribe({
-  files: [
-    { reference_id: "episode_1", url: "https://signed-get-url-1" },
-    { reference_id: "episode_2", url: "https://signed-get-url-2" },
-  ],
-});
-
-const mixedBatchJob = await client.batch.transcribe({
-  files: [
-    { reference_id: "episode_1", file: "local.mp3" },
-    { reference_id: "episode_2", url: "https://signed-get-url-2" },
-  ],
+console.log(job.jobId);
+
+const completion = await job.upload();
+console.log(completion);
+```
+
+For a single large local file, you can also use `createBigFileJob`:
+
+```js
+const job = await client.createBigFileJob({
+  file: { reference_id: "large_001", file: "./large.wav" },
+});
+
+const completion = await job.upload();
+```
+
+## Job helpers
+
+```js
+const job = await client.jobs.get("job_id_here");
+const sameJob = await client.jobs.result("job_id_here");
+
+const finalJob = await client.waitForJobCompletion("job_id_here", {
+  polling: { interval: 10, timeout: 15 * 60 },
 });
 ```
 
-For Cloudflare Workers and other web-style runtimes, use the Worker entrypoint:
+Available job helpers:
+
+| Method | Description |
+| --- | --- |
+| `client.jobs.get(jobId)` | Fetches `GET /v1/transcribe/{job_id}`. |
+| `client.jobs.result(jobId)` | Alias for `jobs.get`. |
+| `client.jobs.uploadCompleted(jobId)` | Calls `POST /v1/transcribe/{job_id}/upload-completed`. |
+| `client.jobs.complete(jobId)` | Alias for `jobs.uploadCompleted`. |
+| `client.jobs.createBatch(options)` | Creates a batch job and returns a `BatchJob`. |
+| `client.jobs.createBigFile(options)` | Creates a one-file async upload job and returns a `BatchJob`. |
+| `client.waitForJobCompletion(jobId, options)` | Polls until a terminal job status or timeout. |
+
+## Limits and validation
+
+- Batch jobs support up to `10,000` files.
+- Batch local upload payloads support up to `10 GB` total local file size.
+- Direct sync routing is used only for one local file up to `30 MB` and about `10 minutes`.
+- Multipart upload starts when the backend returns multipart upload instructions. The SDK sends `size_bytes` for local files at least `128 MB` so the backend can choose multipart.
+- `uploadConcurrency` defaults to `1` and is capped at `32`.
+- `polling.interval` must be at least `10` seconds.
+- Batch local uploads support `mp3`, `mpeg`, `mpga`, `m4a`, `wav`, and `webm`.
+- `.mp4` is not supported.
+
+## Error handling
+
+```js
+try {
+  const result = await client.transcribe({
+    files: [
+      { reference_id: "bad_file", file: "./missing.mp3" },
+    ],
+  });
+  console.log(result);
+} catch (error) {
+  if (error instanceof TranscribeAPIError) {
+    console.error(error.message);
+    console.error(error.code);
+    console.error(error.status);
+    console.error(error.response);
+    console.error(error.toJSON());
+  } else {
+    throw error;
+  }
+}
+```
+
+`TranscribeAPIError` includes `message`, `code`, `status`, `response`, and any extra fields returned by the API or generated by the SDK.
+
+## Cloudflare Workers and web runtimes
+
+Use the Worker entrypoint when running in Cloudflare Workers or other web-standard runtimes:
+
+```js
+import { TranscribeAPI, TranscribeAPIError } from "@transcribe-api/sdk/worker";
+```
+
+The Worker entrypoint keeps the same public client API, but these runtimes do not support Node local file path strings such as `"./audio.mp3"`.
+
+Supported Worker-safe inputs:
+
+- `File` objects, such as files from `request.formData()`.
+- `Blob` objects.
+- `{ data, name, type }`, where `data` is a `Uint8Array` or `ArrayBuffer`.
+- Remote URLs using `{ url: "https://..." }`.
+
+Not supported in Worker runtimes:
+
+- Local file path strings.
+- Node.js streams.
+- Node-only filesystem APIs.
+
+## Cloudflare Worker quick start
 
 ```js
 import { TranscribeAPI } from "@transcribe-api/sdk/worker";
+
+export default {
+  async fetch(request, env) {
+    const client = new TranscribeAPI({
+      apiKey: env.TRANSCRIBE_API_KEY,
+      polling: {
+        interval: 10,
+        timeout: 15 * 60,
+      },
+    });
+
+    const result = await client.transcribe({
+      language: "en",
+      files: [
+        {
+          reference_id: "sample_001",
+          url: "https://example.com/audio.mp3",
+        },
+      ],
+    });
+
+    return Response.json(result);
+  },
+};
 ```
-
-Async uploads use signed R2 URLs returned by the API. Multipart upload is used automatically when the backend returns a multipart flow.
-Async job creation now goes through `POST /v1/transcribe` for single-file and batch jobs. For batch calls, each item must be `{ reference_id, file }` or `{ reference_id, url }`, and local plus remote entries can be mixed in the same batch. The SDK adds `size_bytes` automatically for large local files when the backend needs multipart upload.
-Set `polling.interval` and optional `polling.timeout` in seconds on the client to make async jobs wait for completion automatically. The SDK enforces a minimum polling interval of `10` seconds and stops on `completed`, `failed`, or `insufficient_funds`.
-If polling is not configured, use `GET /v1/transcribe/{job_id}` manually. The response always includes the core job fields and adds `result_url` when `job_status` is `completed`.
-The SDK defaults `multipartConcurrency` to `8` for reliability. You can increase it up to `32` when your network path is stable.
-For Node path uploads, multipart progress is persisted to a sidecar resume file and the SDK will resume the existing big-file job on the next run instead of starting over.
-Multipart uploads also adaptively reduce concurrency on retryable transport errors instead of failing the whole upload immediately.
-Set `showLogs: true` on the client or per async call to let the SDK print upload URL receipt, upload progress, and the final `/upload-completed` response automatically. Pass a custom `logger` object if you want those messages redirected somewhere other than `console`.
-
-Use `@transcribe-api/sdk/worker` when you need a runtime-safe build for Cloudflare Workers. The Worker entrypoint supports remote URLs, `Blob`, `File`, and byte inputs, but does not support local file path strings or Node.js filesystem resume state.
+
+## Uploading a request file in a Worker
+
+```js
+import { TranscribeAPI } from "@transcribe-api/sdk/worker";
+
+export default {
+  async fetch(request, env) {
+    const form = await request.formData();
+    const audio = form.get("file");
+
+    if (!(audio instanceof File)) {
+      return Response.json({ error: "Missing file" }, { status: 400 });
+    }
+
+    const client = new TranscribeAPI({
+      apiKey: env.TRANSCRIBE_API_KEY,
+      polling: {
+        interval: 10,
+        timeout: 15 * 60,
+      },
+    });
+
+    const result = await client.transcribe({
+      language: "en",
+      files: [
+        { reference_id: "upload_001", file: audio },
+      ],
+    });
+
+    return Response.json(result);
+  },
+};
+```
+
+Remote URL transcription is usually the best fit for Workers when audio is already stored in R2, S3, or another storage service.