@transcribe-api/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,75 @@
-# Transcribe API JavaScript SDK
+# Transcribe API JavaScript SDK
+
+Official JavaScript SDK for Transcribe API.
+
+## Installation
+
+```bash
+npm install @transcribe-api/sdk
+```
+
+## Usage
+
+```js
+import { TranscribeAPI } from "@transcribe-api/sdk";
+
+const client = new TranscribeAPI({
+  apiKey: "YOUR_API_KEY",
+  showLogs: true,
+  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({
+  files: [
+    { reference_id: "episode_1", file: "a.mp3" },
+    { reference_id: "episode_2", file: "b.wav" },
+  ],
+});
 
-Official JavaScript SDK for Transcribe API.
+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" },
+  ],
+});
+```
 
-## Installation
+For Cloudflare Workers and other web-style runtimes, use the Worker entrypoint:
 
-```bash
-npm install @transcribe-api/sdk
-import { TranscribeAPI } from "@transcribe-api/sdk";
+```js
+import { TranscribeAPI } from "@transcribe-api/sdk/worker";
+```
+
+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`.
 
-const client = new TranscribeAPI({
-  apiKey: "YOUR_API_KEY"
-});
+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.