===============
LIBRARY RULES
===============
From library maintainers:
- transcript options.url must be a public YouTube video ID or supported HTTPS YouTube URL. Use dQw4w9WgXcQ in examples. Direct audio files and arbitrary media URLs are unsupported.
- The SDK returns JSON bodies: immediate HTTP 200 has content, lang, availableLangs, source, cached and requestId. Accepted HTTP 202 has jobId, status and requestId without content. Use the complete examples in docs/http-contract.md.
- Read docs/http-contract.md for the maintained HTTP response contract and docs/client.md for SDK signatures. Completed job content is a segment array and requestId is required. A completed status without content can mean the stored result expired.
- Only transcript options.url is required. mode is optional, accepts native, auto or generate, and defaults to auto. TranscriptResult.content is string or TranscriptSegment[], with segments by default and a string only for an immediate text:true result.
- Import CapslaneClient and CapslaneError from @webba_tech/capslane. Keep CAPSLANE_API_KEY in the server environment, outside browser bundles, prompts and source control.
- SDK 0.1.4: import importTranscript and resumeTranscript from @webba_tech/capslane/workflows. Read docs/import.md. Await saveJob with jobId and video URL. Result: { url, transcript, timestampedText }; segments are in transcript.content.
- Cache lookup happens before mode selection. On a cache miss, native never starts generation; auto falls back only after confirmed missing captions. Inspect source and cached in every result.
- Use transcriptJob(jobId, signal) to check an existing job once; its second argument is an AbortSignal. waitForTranscript(jobId, { signal }) takes an options object. HTTP 200 can contain a pending or failed job. Preserve the ID and bound polling.
- Completed jobs return canonical timestamped segments. text and chunkSize affect immediate results only. Join segment.text locally when plain text is required after polling.
- Segment offset and duration values are milliseconds. lang is a preferred caption language, not a translation request.
- A transcript submission reserves a monthly unit before cache lookup. Cache hits and later failures can consume it. Polling an existing job does not reserve another transcript unit.
- Read CapslaneError.code before retrying. Use bounded backoff for temporary failures. Monthly allowance errors need a reset or allowance change. Client cancellation does not cancel an accepted server job.
- The raw API uses content for transcript text or segments and status for job state. Check content before jobId, even for completed jobs. HTTP status is separate. There is no root segments or state field.

### Install @webba_tech/capslane

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/README.md

Installs the Capslane JavaScript/TypeScript SDK. Requires Node.js 20 or later; the example uses Node.js 22 or later. Store your Capslane API key in the CAPSLANE_API_KEY environment variable before running.

```bash
npm install @webba_tech/capslane
```

--------------------------------

### GET /v1/account response

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Response body for GET /v1/account. Returns HTTP 200 with workspace, plan, and monthlyLimit. Reserves no transcript unit.

```json
{
  "workspace": "Fixture",
  "plan": "free",
  "monthlyLimit": 50
}
```

--------------------------------

### GET /v1/account

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Retrieves workspace information, plan, and monthly limit. Requires a workspace key in the x-api-key header. Reserves no transcript unit.

```APIDOC
## GET /v1/account

### Description
Retrieves workspace information, plan, and monthly limit. Requires a workspace key in the x-api-key header. Reserves no transcript unit.

### Method
GET

### Endpoint
/v1/account

### Authentication
Send a workspace key in the x-api-key header over HTTPS to https://capslane.com.

### Response
#### Success Response (200)
- **workspace** (string) - Workspace name
- **plan** (string) - Plan type
- **monthlyLimit** (integer) - Monthly limit

#### Response Example
{
  "workspace": "Fixture",
  "plan": "free",
  "monthlyLimit": 50
}
```

--------------------------------

### Import and resume transcript with CapslaneClient

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

Complete runnable example for importing and resuming transcripts using the Capslane SDK. Requires Node.js 22 or later. The importVideo function submits a job and awaits durable storage via saveJob; resumeVideo resumes a saved job without resubmitting. Both use the default native mode unless auto is specified.

```javascript
import { CapslaneClient } from '@webba_tech/capslane'
import { importTranscript, resumeTranscript } from '@webba_tech/capslane/workflows'

// supply saveJob from your durable storage layer
export async function importVideo(url, saveJob) {
  const client = new CapslaneClient({ apiKey: process.env.CAPSLANE_API_KEY, timeoutMs: 45_000 })
  return importTranscript(client, url, { mode: 'auto', saveJob })
}

export async function resumeVideo(savedJob) {
  const client = new CapslaneClient({ apiKey: process.env.CAPSLANE_API_KEY, timeoutMs: 45_000 })
  return resumeTranscript(client, savedJob)
}
```

--------------------------------

### GET /v1/transcript immediate response

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Immediate response body for GET /v1/transcript with default mode and text=false. content is an array of segments; each segment has text, offset, duration, and lang. offset and duration are nonnegative integers in milliseconds.

```json
{
  "content": [{ "text": "Synthetic fixture.", "offset": 1000, "duration": 2000, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "generated",
  "cached": true,
  "requestId": "req_example"
}
```

--------------------------------

### Submit a transcript and wait for completion

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

JavaScript example of submitting a transcript with mode 'auto' and text false. If the result is an accepted job (no 'content' property), it logs the jobId and waits up to 20 minutes using waitForTranscript. Then logs the transcript content.

```javascript
let result = await client.transcript({ url: 'dQw4w9WgXcQ', mode: 'auto', text: false })
if (!('content' in result)) {
  console.error('Accepted job:', result.jobId)
  result = await client.waitForTranscript(result, { timeoutMs: 20 * 60_000 })
}
console.log(result.content)
```

--------------------------------

### Extract plain text from result content

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/README.md

Use this snippet inside the quickstart's try block, after waiting and before console.log, to obtain plain text from either result shape. It checks if result.content is a string; if not, it maps over segments and joins their text with spaces.

```javascript
const plain = typeof result.content === "string"
  ? result.content
  : result.content.map((segment) => segment.text).join(" ")
```

--------------------------------

### GET /v1/transcript

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Returns an immediate transcript for a public YouTube URL or video ID. Supports optional parameters for mode, language, text format, and chunk size.

```APIDOC
## GET /v1/transcript

### Description
Returns an immediate transcript for a public YouTube URL or video ID. Supports optional parameters for mode, language, text format, and chunk size.

### Method
GET

### Endpoint
/v1/transcript

### Parameters
#### Query Parameters
- **url** (string) - Required - Public YouTube URL or 11-character video ID
- **mode** (string) - Optional - Defaults to auto; accepts native, auto, or generate
- **lang** (string) - Optional - Preferred caption language; does not request translation
- **text** (boolean) - Optional - Defaults to false; if true, content is a string and takes precedence over chunkSize
- **chunkSize** (integer) - Optional - Character budget from 50 to 10,000; groups whole segments, one source segment can exceed budget

### Response
#### Success Response (200)
- **content** (array or string) - Array of segments by default; string if text=true
- **lang** (string) - Language of the transcript
- **availableLangs** (array of strings) - Available languages
- **source** (string) - Source of the transcript
- **cached** (boolean) - Whether the response was cached
- **requestId** (string) - Request identifier

#### Segment Fields
- **text** (string) - Segment text
- **offset** (integer) - Nonnegative integer in milliseconds
- **duration** (integer) - Nonnegative integer in milliseconds
- **lang** (string) - Segment language

#### Response Example
{
  "content": [{ "text": "Synthetic fixture.", "offset": 1000, "duration": 2000, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "generated",
  "cached": true,
  "requestId": "req_example"
}
```

--------------------------------

### Submit a transcript with client.transcript

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

TypeScript method signature for client.transcript. Only options.url is required; lang, mode, text, chunkSize, and signal are optional. Returns a Promise resolving to TranscriptResult or TranscriptJob. The SDK forwards options to GET /v1/transcript and does not automatically wait for an accepted job.

```typescript
client.transcript(options): Promise<TranscriptResult | TranscriptJob>
```

--------------------------------

### Retrieve transcript with CapslaneClient.transcript

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/README.md

Retrieves a transcript in auto mode, which can start audio generation. A ready result contains content; an accepted job contains jobId and status. Check for content first because a completed job response contains both. Save as transcript-sdk.mjs and run with node transcript-sdk.mjs.

```js
import { CapslaneClient, CapslaneError } from '@webba_tech/capslane'

const apiKey = process.env.CAPSLANE_API_KEY
if (!apiKey) throw new Error('Set CAPSLANE_API_KEY')
const client = new CapslaneClient({ apiKey, timeoutMs: 45_000 })
const signal = AbortSignal.timeout(20 * 60_000)

try {
  let result = await client.transcript({ url: 'dQw4w9WgXcQ', mode: 'auto', signal })
  if (!('content' in result)) {
    console.error('Accepted job:', result.jobId)
    result = await client.waitForTranscript(result, { signal })
  }
  console.log(JSON.stringify(result, null, 2))
} catch (error) {
  if (error instanceof CapslaneError) {
    console.error(error.status, error.code, error.requestId)
  }
  throw error
}
```

--------------------------------

### GET /v1/transcript/{jobId}

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Retrieves the status and result of a transcription generation job.

```APIDOC
## GET /v1/transcript/{jobId}

### Description
Checks the status of an existing transcription generation job in the workspace of the API key. Returns HTTP 200 for all job statuses, but HTTP 200 alone does not indicate completion.

### Method
GET

### Endpoint
/v1/transcript/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the generation job.

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier of the job.
- **status** (string) - The current status of the job. Possible values: queued, downloading, processing, persisting, completed, failed, cancelled.
- **requestId** (string) - A unique identifier for the request.
- **progress** (integer, optional) - Progress percentage from 0 to 100.
- **error** (string, optional) - Error code if the job failed.
- **content** (array, optional) - Array of timestamped segments when the job is completed and content is available.
- **lang** (string, optional) - The language of the transcript.
- **availableLangs** (array, optional) - List of available languages.
- **source** (string, optional) - The source of the content, e.g., "generated".
- **cached** (boolean, optional) - Whether the result is cached.

#### Response Example
```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "progress": 50,
  "error": "upstream_unavailable",
  "requestId": "req_example"
}
```

### Error Handling
- **404 Not Found** - Returned when the job ID is valid but unknown, including jobs from another workspace. Error code: `job_not_found`.

### Notes
- A completed job response may omit `content` after the stored result expires; this is not a ready transcript. The endpoint still returns HTTP 200 in this case.
- The endpoint does not return plain text, even if the initial submission used `text=true`. It does not reapply `chunkSize`.
- Check for `content` before checking `jobId` in a completed response.
- Join segment text locally for plain text after polling.
```

--------------------------------

### Check an existing job with client.transcriptJob

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

Checks an existing transcript job by ID. The optional second argument is an AbortSignal; pass it directly. Issues one GET /v1/transcript/{jobId}. A completed result has both jobId and content; check for content first. HTTP 200 also covers pending, failed and cancelled jobs, and a valid unknown ID returns job_not_found.

```ts
client.transcriptJob(jobId, signal?): Promise<TranscriptResult | TranscriptJob>
```

```js
const signal = AbortSignal.timeout(45_000)
const result = await client.transcriptJob(jobId, signal)
```

--------------------------------

### Import a video transcript with importTranscript and resume it with resumeTranscript

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/import.md

Create a CapslaneClient with your API key and a 45-second timeout. importVideo submits a new import job using auto mode and a durable saveJob callback; resumeVideo resumes an existing saved job without resubmitting.

```javascript
import { CapslaneClient } from '@webba_tech/capslane'
import { importTranscript, resumeTranscript } from '@webba_tech/capslane/workflows'

// supply saveJob from your durable storage layer
export async function importVideo(url, saveJob) {
  const client = new CapslaneClient({ apiKey: process.env.CAPSLANE_API_KEY, timeoutMs: 45_000 })
  return importTranscript(client, { url, mode: 'auto', saveJob })
}

export async function resumeVideo(savedJob) {
  const client = new CapslaneClient({ apiKey: process.env.CAPSLANE_API_KEY, timeoutMs: 45_000 })
  return resumeTranscript(client, savedJob)
}
```

--------------------------------

### new CapslaneClient({ apiKey, baseUrl, timeoutMs, fetch })

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

Constructor for the Capslane client. Requires an API key and supports optional base URL, timeout, and fetch implementation.

```APIDOC
## [CONSTRUCTOR] new CapslaneClient({ apiKey, baseUrl, timeoutMs, fetch })

### Description
Creates a new Capslane client instance. Construction does not contact the API or validate the key remotely.

### Parameters
- **apiKey** (string) - Required - Workspace key. An empty or whitespace-only key throws TypeError.
- **baseUrl** (string) - Optional - Defaults to https://capslane.com.
- **timeoutMs** (number) - Optional - Defaults to 20000 for each HTTP request.
- **fetch** (function) - Optional - A compatible fetch implementation for a server or a test.

### Example
```ts
new CapslaneClient({ apiKey, baseUrl, timeoutMs, fetch })
```
```

--------------------------------

### client.transcript(options)

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

Submits a transcript request for a public YouTube video. Returns either an immediate transcript result or an accepted job.

```APIDOC
## [METHOD] client.transcript(options): Promise<TranscriptResult | TranscriptJob>

### Description
Submits a transcript request for a public YouTube video. The SDK forwards options to GET /v1/transcript and does not automatically wait for an accepted job.

### Parameters
- **options.url** (string) - Required - Public YouTube video: an 11-character ID or a supported HTTPS YouTube URL. Direct audio files and arbitrary media URLs are unsupported.
- **options.lang** (string) - Optional - Language for the transcript.
- **options.mode** (string) - Optional - Defaults to auto at the API. Accepts native, auto, or generate.
- **options.text** (boolean) - Optional - Defaults to false, so immediate content is a segment array. An immediate text:true result has string content.
- **options.chunkSize** (number) - Optional - Chunk size for the transcript.
- **options.signal** (AbortSignal) - Optional - Abort signal for the request.

### Request Example
```js
let result = await client.transcript({ url: 'dQw4w9WgXcQ', mode: 'auto', text: false })
if (!('content' in result)) {
  console.error('Accepted job:', result.jobId)
  result = await client.waitForTranscript(result, { timeoutMs: 20 * 60_000 })
}
console.log(result.content)
```

### Response
An immediate HTTP 200 body contains content, lang, availableLangs, source, cached, and requestId. An accepted HTTP 202 body contains jobId, status, and requestId without content. A job status read later can contain both content and jobId; check content first.
```

--------------------------------

### CapslaneClient constructor signature

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

TypeScript constructor signature for CapslaneClient. Requires apiKey; optional baseUrl defaults to https://capslane.com, timeoutMs defaults to 20000, and fetch can be supplied for server or test environments. Construction does not contact the API.

```typescript
new CapslaneClient({ apiKey, baseUrl, timeoutMs, fetch })
```

--------------------------------

### Resume a transcript job with resumeTranscript

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/README.md

Resumes an accepted transcript job using the resumeTranscript workflow. Requires CAPSLANE_API_KEY and CAPSLANE_JOB_ID in the environment. The resume module checks the saved job ID every two seconds with a twenty-minute deadline. Errors retain jobId and requestId.

```js
import { resumeTranscript } from './resume-transcript.mjs'

try {
  const result = await resumeTranscript(process.env.CAPSLANE_JOB_ID)
  console.log(JSON.stringify(result, null, 2))
} catch (error) {
  console.error(error.jobId, error.code ?? error.name, error.requestId)
  throw error
}
```

--------------------------------

### Wait for a transcript with client.waitForTranscript

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

Waits for a transcript to be ready. job is a saved job ID string or an accepted TranscriptJob object. options can contain intervalMs, timeoutMs and signal; defaults are intervalMs=2000, timeoutMs=1200000 and no caller signal. Returns content when ready and raises CapslaneError with status 422 on failed or cancelled jobs. A polling deadline raises status 504 and code processing_timeout.

```ts
client.waitForTranscript(job, options?): Promise<TranscriptResult>
```

--------------------------------

### Accepted generation response (HTTP 202)

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

HTTP 202 response for an accepted generation job. jobId, status, and requestId are required; progress is optional. Preserve jobId before waiting so a timeout does not force another submission.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "requestId": "req_example"
}
```

--------------------------------

### Transcript Job Operations

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/client.md

Documentation for checking an existing transcript job and waiting for a transcript result.

```APIDOC
## GET /v1/transcript/{jobId}

### Description
Checks the status and content of an existing transcript job. Returns the transcript result if the job is completed, or the job status otherwise.

### Method
GET

### Endpoint
/v1/transcript/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the transcript job to check.

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the transcript job.
- **content** (array) - The transcript content as a segment array, present only when the job is completed.
- **requestId** (string) - Required - The request ID associated with the job.

#### Response Example
```json
{
  "jobId": "string",
  "content": [
    {
      "segment": "string"
    }
  ],
  "requestId": "string"
}
```

### Error Handling
- **job_not_found** - Returned when the job ID is unknown or owned by another workspace.
- **transcript_expired** - Returned when the stored result has expired; the status endpoint still returns HTTP 200.

## Wait for a transcript

### Description
Polls the transcript job until it is completed or a timeout occurs. Returns the transcript result when ready.

### Method
Polling helper (not an HTTP endpoint)

### Parameters
#### Request Body
- **job** (string | TranscriptJob) - Required - The saved job ID string or an accepted TranscriptJob object.
- **options** (object) - Optional - Configuration options.
  - **intervalMs** (number) - Optional - Polling interval in milliseconds. Default: 2000.
  - **timeoutMs** (number) - Optional - Polling timeout in milliseconds. Default: 1200000.
  - **signal** (AbortSignal) - Optional - An AbortSignal to cancel the polling.

### Response
#### Success Response
- **TranscriptResult** - The transcript result when the job is completed.

### Error Handling
- **status 422** - Raised when the job is failed or cancelled.
- **status 504** - Raised when the polling deadline is reached; code `processing_timeout`.
- **status 410** - Raised when the stored result has expired; code `transcript_expired`.

### Notes
- The polling window bounds both delays and in-flight requests through an abort signal.
- `intervalMs` and `timeoutMs` must be positive integers no greater than 2147483647.
- A custom fetch implementation must honor the abort signal.
```

--------------------------------

### Completed job response with content

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Completed job response with stored content. Requires jobId, status, content, lang, availableLangs, source, cached, and requestId. content is always an array of timestamped segments; the endpoint does not return plain text even if text=true was used, and does not reapply chunkSize.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "content": [{ "text": "Synthetic fixture.", "offset": 1000, "duration": 2000, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "generated",
  "cached": true,
  "requestId": "req_example"
}
```

--------------------------------

### Job status response with failed status

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Job status response for a failed job. HTTP 200 does not indicate completion; error is an optional code on a failed job. progress is an optional integer from 0 to 100.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "progress": 50,
  "error": "upstream_unavailable",
  "requestId": "req_example"
}
```

--------------------------------

### Completed job response without content

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/docs/http-contract.md

Completed job response without content after stored result expires. This is not a ready transcript; the public endpoint still returns HTTP 200. Bound polling and report missing content to the caller; never wait indefinitely or automatically submit another generation.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 50,
  "requestId": "req_example"
}
```

--------------------------------

### Default TranscriptResult content shape

Source: https://github.com/webba-creative-technologies/capslane-js/blob/main/README.md

Default shape of TranscriptResult.content when text is not requested. Content is an array of segments with text, offset, duration, and lang fields. The response also includes lang, availableLangs, source, cached, and requestId.

```json
{
  "content": [{ "text": "Example segment.", "offset": 8150, "duration": 1200, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "native",
  "cached": false,
  "requestId": "req_example"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.