ai-sdk-provider-flowspeech 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0 - 2026-10-26 (unreleased)
+
+- Validate complete RIFF/WAVE chunks and 24 kHz mono 16-bit PCM data; preserve valid bytes, reject malformed downloads and allow download-only recovery.
+- Correct quota documentation to canonical `subscription`, retaining optional `entitlement` compatibility.
+
+- Replace the retired synchronous endpoint with public API v1 submit, poll and credential-free WAV download.
+- Preserve the framework's buffered speech result contract and expose recovery request/job IDs.
+- Add single/multi input support through the exported client, quota/voices queries, job lookup and explicit cancellation.
+- Bound retries, response sizes, per-request timeouts and total deadlines; reuse submission UUID/body on retries.
+- Respect five-second polling and longer Retry-After values; report failed/cancelled/deleted/malformed jobs explicitly.
+- Reject unsupported legacy generation options, unsafe URLs, API credential overrides and redirects.
+- Add fake-transport framework tests and build/packed-artifact smoke tests; no paid generation tests.
+- Update server-only credential/subscription documentation and migration guidance.
+
+0.1.0 identifies the original repository code, not a verified npm release. Registry
+availability was unverified/404 during the 2026-10-26 audit. Publication of 0.2.0 is
+a separate maintainer action.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowSpeech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# FlowSpeech Provider for the AI SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A server-side FlowSpeech public API v1 adapter for the AI SDK `SpeechModelV4` contract. `generateSpeech` resolves after submission, polling and audio download, returning WAV bytes.
+
+## Local installation
+
+Requires Node.js 22 or newer. Until a registry release is verified, build the local checkout:
+
+```bash
+npm ci --ignore-scripts
+npm test
+npm run typecheck
+npm run build
+npm run test:dist
+npm pack
+# From your application:
+npm install ai /path/to/ai-sdk-provider-flowspeech-0.2.0.tgz
+```
+
+Set `FLOWSPEECH_API_KEY` in the server environment. Never put it in browser code or commit it.
+
+## Generate speech
+
+```ts
+import { randomUUID } from 'node:crypto'
+import { writeFile } from 'node:fs/promises'
+import { generateSpeech } from 'ai'
+import { createFlowSpeech, FlowSpeechClient } from 'ai-sdk-provider-flowspeech'
+
+const requestId = randomUUID() // Persist this before submission.
+const flowSpeech = createFlowSpeech({ timeoutMs: 600_000 })
+const result = await generateSpeech({
+  model: flowSpeech.speech('flowspeech-tts'),
+  text: 'Welcome to FlowSpeech.[pause]Here is the update.',
+  voice: 'Kore',
+  outputFormat: 'wav',
+  providerOptions: { flowspeech: { requestId } },
+})
+await writeFile('speech.wav', result.audio.uint8Array)
+console.log(result.providerMetadata?.flowspeech) // requestId, jobId, credit usage
+```
+
+`flowSpeech` is also exported as a default-configured provider. Only `flowspeech-tts` is a valid framework model identifier; it is not sent to the API. The response body contains the final job object, not the legacy base64 envelope.
+
+For multiple speakers, set the required framework `text` field to an empty string and supply explicit turns:
+
+```ts
+const result = await generateSpeech({
+  model: flowSpeech.speech(),
+  text: '',
+  providerOptions: {
+    flowspeech: {
+      requestId: randomUUID(),
+      segments: [
+        { speaker: 'Alice', text: 'Welcome.', voiceName: 'Kore' },
+        { speaker: 'Bob', text: 'Thank you.', voiceName: 'Puck' },
+      ],
+    },
+  },
+})
+```
+
+## Migration from local 0.1.0 code
+
+The synchronous endpoint and base64 response are gone. `baseUrl` now means an HTTPS origin, without an endpoint path. Separate `instructions`, `language` and numeric `speed` options are rejected rather than ignored. Only `outputFormat: 'wav'` is supported. Unknown FlowSpeech provider options are rejected.
+
+`createFlowSpeech` accepts `apiKey`, `baseUrl`, `defaultVoice`, `headers`, `fetch`, `timeoutMs`, `requestTimeoutMs`, `pollIntervalMs`, `maxRetries` and `maxAudioBytes`. Headers are API-only; neither provider nor per-call headers may override Authorization, Cookie, Host, Idempotency-Key or transport headers. Framework abort signals are preserved.
+
+## v1 behavior and recovery
+
+Requires a server-side developer API key and an active paid Basic, Pro or Scale subscription. Trials do not include API generation. Website cookies and plugin login tokens are not API credentials.
+
+The API origin is `https://flowspeech.io`. Calls submit `{ input: ... }` to `POST /api/v1/tts/jobs` with a UUID `Idempotency-Key`, poll the returned job, then download its result. No model or legacy speaker fields are sent. Audio is WAV, 24000 Hz, mono, 16 bit. HTTP 200 from a status query is not generation success.
+
+- Pending states: queued, running, merging, settling. Failed/cancelled jobs throw; a deleted success result throws `result_deleted`.
+- Polling defaults to 5000 ms and cannot be configured faster. Longer `Retry-After` values, including HTTP dates and rate limits, take precedence.
+- There are at most two transient retries per HTTP operation by default (configurable from zero to five). Submission retries preserve the exact UUID and JSON body.
+- The total deadline includes submit, polling, retry waits, response-body reads and download. The general client default is 600000 ms; each request defaults to 30000 ms.
+- Downloads use no API headers, Bearer token or cookies. HTTPS URLs with embedded credentials are rejected. API and storage redirects are rejected rather than followed. Downloads are bounded (64 MiB for the general client).
+- Custom fetch implementations are trusted application code and must preserve the supplied abort, redirect and credential settings.
+- Aborting or timing out stops local work; it does not cancel the server job or reverse a charge. Use `cancelJob` explicitly when cancellation is intended.
+
+Each package exports `FlowSpeechClient` and `FlowSpeechError`. Save a fresh UUID before each new recording and pass it as `requestId`. Reuse it only with unchanged input. Error properties include `code`, `status`, `traceId`, `requestId` and `jobId` when known; do not automatically start a new job after a timeout or download error.
+
+```ts
+const client = new FlowSpeechClient({ apiKey: process.env.FLOWSPEECH_API_KEY })
+const quota = await client.getQuota()
+console.log(quota.quota.available)
+const voices = await client.listVoices()
+
+// Use the UUID previously saved for the interrupted recording.
+const job = await client.findJob(savedRequestId)
+// Or: await client.getJob(savedJobId)
+// Poll pending jobs no faster than five seconds, or resume generate() with
+// the same UUID and unchanged input; it replays the existing job.
+if (job.status === 'success') {
+  const bytes = await client.downloadJob(job) // never creates a recording
+}
+// await client.cancelJob(job.id)
+```
+
+The quota response preserves canonical top-level `quota`, `subscription` and `limits`. An optional `entitlement` field is also retained for compatibility; it is not required. Result links grant public link access and should not be logged or shared unnecessarily. Deleting a result does not necessarily invalidate a previously copied link.
+
+Downloads validate the actual RIFF/WAVE container, chunk lengths and padding,
+PCM format (24000 Hz, mono, 16 bit), byte rate/block alignment, and complete
+nonempty aligned sample data. Truncated, malformed or mismatched audio is
+rejected even on HTTP 200. Bounded unknown chunks are skipped safely and valid
+files are returned byte-for-byte unchanged. Validation remains within the
+operation deadline; an invalid download never triggers another submission.
+
+Full API contract: [FlowSpeech public API](https://flowspeech.io/docs/public-api).
+
+## Development and release status
+
+These are local 0.2.0 release candidates. The npm-name audit on 2026-10-26 returned 404; do not assume an earlier npm release exists or claim this version is published. The GitHub repository exists independently of npm availability. Publication is a separate maintainer/coordinator action.
+
+Install locked dependencies, then run the package checks and pack locally. Tests use only fake transports and synthetic WAV data; they do not spend generation credits. See `RELEASE_CHECKLIST.md` for maintainer release steps.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { SpeechModelV4, ProviderV4 } from '@ai-sdk/provider';
+
+type FlowSpeechInput = {
+    mode: 'single';
+    text: string;
+    voiceName: string;
+} | {
+    mode: 'multi';
+    segments: Array<{
+        speaker: string;
+        text: string;
+        voiceName: string;
+    }>;
+};
+interface FlowSpeechResult {
+    url: string;
+    mimeType: 'audio/wav';
+    sampleRate: 24000;
+    channels: 1;
+    bitsPerSample: 16;
+}
+interface FlowSpeechJob {
+    id: string;
+    requestId: string;
+    status: 'queued' | 'running' | 'merging' | 'settling' | 'success' | 'failed' | 'cancelled';
+    result?: FlowSpeechResult | null;
+    resultDeleted?: boolean;
+    usage: {
+        billableCharacters: number;
+        reservedCredits: number;
+        chargedCredits: number;
+    };
+    error?: {
+        code: string;
+        message?: string;
+        retryable?: boolean;
+    } | null;
+}
+interface FlowSpeechQuota {
+    quota: {
+        remaining: number;
+        reserved: number;
+        available: number;
+    };
+    /** Optional compatibility field; production v1 returns subscription. */
+    entitlement?: Record<string, unknown> | null;
+    /** Canonical public API v1 subscription metadata. */
+    subscription?: Record<string, unknown> | null;
+    limits: Record<string, unknown>;
+}
+interface FlowSpeechVoice {
+    name: string;
+    description: string;
+    gender: string;
+}
+interface FlowSpeechClientOptions {
+    apiKey?: string | undefined;
+    /** HTTPS API origin, not an endpoint path. */
+    baseUrl?: string | undefined;
+    /** API-only headers. Authentication, cookies and idempotency headers cannot be overridden. */
+    headers?: Record<string, string> | undefined;
+    fetch?: typeof fetch | undefined;
+    /** Total operation deadline, including requests, waits, retries and audio download. */
+    timeoutMs?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    /** At least 5000 ms. */
+    pollIntervalMs?: number | undefined;
+    /** Number of retries per HTTP operation, between zero and five. */
+    maxRetries?: number | undefined;
+    maxAudioBytes?: number | undefined;
+}
+interface FlowSpeechOperationOptions {
+    requestId?: string | undefined;
+    signal?: AbortSignal | undefined;
+}
+declare class FlowSpeechError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly traceId?: string | undefined;
+    readonly retryable: boolean;
+    readonly name = "FlowSpeechError";
+    requestId?: string;
+    jobId?: string;
+    constructor(message: string, code: string, status?: number | undefined, traceId?: string | undefined, retryable?: boolean);
+}
+declare function rejectUnsupported(value: object, supported: readonly string[]): void;
+declare function normalizeApiOrigin(value?: string): string;
+declare class FlowSpeechClient {
+    private readonly key;
+    private readonly origin;
+    private readonly headers;
+    private readonly fetcher;
+    private readonly timeout;
+    private readonly requestTimeout;
+    private readonly interval;
+    private readonly retries;
+    private readonly maxAudio;
+    constructor(options?: FlowSpeechClientOptions);
+    private clean;
+    private operation;
+    private request;
+    private api;
+    generate(input: FlowSpeechInput, options?: FlowSpeechOperationOptions): Promise<{
+        audio: Uint8Array<ArrayBufferLike>;
+        job: FlowSpeechJob;
+        requestId: string;
+        requestBody: string;
+        headers: Record<string, string>;
+    }>;
+    private audio;
+    getJob(id: string, options?: FlowSpeechOperationOptions): Promise<FlowSpeechJob>;
+    findJob(requestId: string, options?: Omit<FlowSpeechOperationOptions, 'requestId'>): Promise<FlowSpeechJob>;
+    cancelJob(id: string, options?: FlowSpeechOperationOptions): Promise<FlowSpeechJob>;
+    /** Retries only the download of an existing successful job, never generation. */
+    downloadJob(current: FlowSpeechJob, options?: FlowSpeechOperationOptions): Promise<Uint8Array>;
+    getQuota(options?: FlowSpeechOperationOptions): Promise<FlowSpeechQuota>;
+    listVoices(options?: FlowSpeechOperationOptions): Promise<FlowSpeechVoice[]>;
+}
+
+/** Framework identifier only; no model field is sent to the API. */
+type FlowSpeechModelId = 'flowspeech-tts' | (string & {});
+interface FlowSpeechSpeechModelConfig extends FlowSpeechClientOptions {
+    provider: string;
+    defaultVoice: string;
+    currentDate?: () => Date;
+}
+declare class FlowSpeechSpeechModel implements SpeechModelV4 {
+    readonly modelId: FlowSpeechModelId;
+    private readonly config;
+    readonly specificationVersion = "v4";
+    get provider(): string;
+    constructor(modelId: FlowSpeechModelId, config: FlowSpeechSpeechModelConfig);
+    doGenerate(options: Parameters<SpeechModelV4['doGenerate']>[0]): Promise<Awaited<ReturnType<SpeechModelV4['doGenerate']>>>;
+}
+
+interface FlowSpeechProvider extends ProviderV4 {
+    speech(modelId?: FlowSpeechModelId): SpeechModelV4;
+}
+interface FlowSpeechProviderSettings extends FlowSpeechClientOptions {
+    defaultVoice?: string;
+}
+declare function createFlowSpeech(settings?: FlowSpeechProviderSettings): FlowSpeechProvider;
+declare const flowSpeech: FlowSpeechProvider;
+
+export { FlowSpeechClient, type FlowSpeechClientOptions, FlowSpeechError, type FlowSpeechInput, type FlowSpeechJob, type FlowSpeechModelId, type FlowSpeechOperationOptions, type FlowSpeechProvider, type FlowSpeechProviderSettings, type FlowSpeechQuota, type FlowSpeechResult, FlowSpeechSpeechModel, type FlowSpeechVoice, createFlowSpeech, flowSpeech, normalizeApiOrigin, rejectUnsupported };

package/dist/index.js

@@ -0,0 +1,479 @@
+// src/flowspeech-client.ts
+import { randomUUID } from "crypto";
+var FlowSpeechError = class extends Error {
+  constructor(message, code, status, traceId, retryable = false) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.traceId = traceId;
+    this.retryable = retryable;
+  }
+  code;
+  status;
+  traceId;
+  retryable;
+  name = "FlowSpeechError";
+  requestId;
+  jobId;
+};
+var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var statuses = /* @__PURE__ */ new Set(["queued", "running", "merging", "settling", "success", "failed", "cancelled"]);
+var forbiddenHeaders = /^(authorization|proxy-authorization|cookie|cookie2|host|idempotency-key|content-type|content-length|connection|transfer-encoding)$/i;
+function fail(message, code = "invalid_response") {
+  throw new FlowSpeechError(message, code);
+}
+function record(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function uuid(value, label) {
+  if (typeof value !== "string" || !uuidPattern.test(value)) fail("Invalid " + label + " UUID", "invalid_request");
+  return value.toLowerCase();
+}
+function text(value, label) {
+  if (typeof value !== "string" || !value.trim()) fail(label + " must not be empty", "invalid_request");
+}
+function number(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function integer(value, label, min = 1, max = 2147483647) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) fail("Invalid " + label, "invalid_configuration");
+  return value;
+}
+function rejectUnsupported(value, supported) {
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== void 0 && !supported.includes(key)) fail("Unsupported FlowSpeech option: " + key, "unsupported_option");
+  }
+}
+function normalizeApiOrigin(value = "https://flowspeech.io") {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return fail("Invalid FlowSpeech baseUrl", "invalid_configuration");
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+    fail("FlowSpeech baseUrl must be an HTTPS origin without credentials, path, query or fragment", "invalid_configuration");
+  }
+  return url.origin;
+}
+function audioUrl(value) {
+  if (typeof value !== "string") fail("Missing audio URL");
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return fail("Invalid audio URL");
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.hash) fail("Unsafe audio URL");
+  return url.href;
+}
+function validateInput(input) {
+  if (!record(input)) fail("Invalid input", "invalid_request");
+  if (input.mode === "single") {
+    rejectUnsupported(input, ["mode", "text", "voiceName"]);
+    text(input.text, "text");
+    text(input.voiceName, "voiceName");
+    if (input.text.length > 1e5) fail("Text exceeds 100000 UTF-16 code units", "invalid_request");
+    return { mode: "single", text: input.text, voiceName: input.voiceName };
+  }
+  if (input.mode !== "multi" || !Array.isArray(input.segments) || input.segments.length < 1 || input.segments.length > 1e3) {
+    fail("Multi input requires 1 to 1000 segments", "invalid_request");
+  }
+  rejectUnsupported(input, ["mode", "segments"]);
+  let length = 0;
+  const speakers = /* @__PURE__ */ new Map();
+  const segments = input.segments.map((segment) => {
+    if (!record(segment)) fail("Invalid segment", "invalid_request");
+    rejectUnsupported(segment, ["speaker", "text", "voiceName"]);
+    text(segment.speaker, "speaker");
+    text(segment.text, "text");
+    text(segment.voiceName, "voiceName");
+    if (segment.speaker.length > 100) fail("Speaker label exceeds 100 characters", "invalid_request");
+    if (speakers.has(segment.speaker) && speakers.get(segment.speaker) !== segment.voiceName) {
+      fail("A speaker must use the same voice in every segment", "invalid_request");
+    }
+    speakers.set(segment.speaker, segment.voiceName);
+    length += segment.text.length;
+    return { speaker: segment.speaker, text: segment.text, voiceName: segment.voiceName };
+  });
+  if (length > 1e5) fail("Text exceeds 100000 UTF-16 code units", "invalid_request");
+  return { mode: "multi", segments };
+}
+function job(value, ctx) {
+  if (!record(value)) fail("Malformed job");
+  const id = uuid(value.id, "job ID");
+  if (ctx.jobId && ctx.jobId !== id) fail("Job ID changed unexpectedly");
+  ctx.jobId = id;
+  if (typeof value.requestId !== "string" || !uuidPattern.test(value.requestId)) fail("Missing or invalid job request ID");
+  const requestId = value.requestId.toLowerCase();
+  if (ctx.requestId && ctx.requestId !== requestId) fail("Request ID changed unexpectedly");
+  ctx.requestId = requestId;
+  if (typeof value.status !== "string" || !statuses.has(value.status)) fail("Unknown job status");
+  if (!record(value.usage) || !["billableCharacters", "reservedCredits", "chargedCredits"].every((k) => number(value.usage[k]))) {
+    fail("Missing or invalid job usage");
+  }
+  if (value.resultDeleted !== void 0 && typeof value.resultDeleted !== "boolean") fail("Invalid resultDeleted flag");
+  if (value.status === "success" && !(value.result === null && value.resultDeleted === true)) {
+    const result = value.result;
+    if (!record(result) || result.mimeType !== "audio/wav" || result.sampleRate !== 24e3 || result.channels !== 1 || result.bitsPerSample !== 16) {
+      fail("Missing or malformed WAV result");
+    }
+    audioUrl(result.url);
+  }
+  return { ...value, id, requestId };
+}
+function retryAfter(value) {
+  if (!value) return 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+async function abortable(promise, signal) {
+  if (signal.aborted) throw signal.reason;
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+async function wait(ms, signal) {
+  if (signal.aborted) throw signal.reason;
+  let timer;
+  try {
+    await abortable(new Promise((resolve) => {
+      timer = setTimeout(resolve, Math.min(ms, 2147483647));
+    }), signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function boundedBody(response, max, signal) {
+  const length = response.headers.get("content-length");
+  if (length && Number(length) > max) {
+    void response.body?.cancel().catch(() => {
+    });
+    fail("FlowSpeech response exceeds " + max + " bytes", "response_too_large");
+  }
+  if (!response.body) fail("Empty response body");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await abortable(reader.read(), signal);
+      if (done) break;
+      size += value.byteLength;
+      if (size > max) fail("FlowSpeech response exceeds " + max + " bytes", "response_too_large");
+      chunks.push(value);
+    }
+  } catch (error) {
+    void reader.cancel().catch(() => {
+    });
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+  const output = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return output;
+}
+async function validateWav(bytes, signal) {
+  const invalid = () => fail("Invalid WAV: expected complete 24000 Hz mono 16-bit PCM with nonempty aligned data", "invalid_audio");
+  if (bytes.length < 12) invalid();
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const tag = (offset2) => view.getUint32(offset2);
+  if (tag(0) !== 1380533830 || tag(8) !== 1463899717 || view.getUint32(4, true) + 8 !== bytes.length) invalid();
+  let offset = 12;
+  let formatSeen = false;
+  let dataSeen = false;
+  let chunks = 0;
+  while (offset < bytes.length) {
+    if (signal.aborted) throw signal.reason;
+    if (++chunks % 1024 === 0) await wait(0, signal);
+    if (bytes.length - offset < 8) invalid();
+    const size = view.getUint32(offset + 4, true);
+    const start = offset + 8;
+    const end = start + size;
+    const next = end + (size & 1);
+    if (next > bytes.length) invalid();
+    switch (tag(offset)) {
+      case 1718449184:
+        if (formatSeen || dataSeen || size !== 16 && size !== 18) invalid();
+        if (view.getUint16(start, true) !== 1 || view.getUint16(start + 2, true) !== 1 || view.getUint32(start + 4, true) !== 24e3 || view.getUint32(start + 8, true) !== 48e3 || view.getUint16(start + 12, true) !== 2 || view.getUint16(start + 14, true) !== 16 || size === 18 && view.getUint16(start + 16, true) !== 0) invalid();
+        formatSeen = true;
+        break;
+      case 1684108385:
+        if (!formatSeen || dataSeen || size === 0 || size % 2 !== 0) invalid();
+        dataSeen = true;
+        break;
+    }
+    offset = next;
+  }
+  if (!formatSeen || !dataSeen) invalid();
+  if (signal.aborted) throw signal.reason;
+}
+var FlowSpeechClient = class {
+  key;
+  origin;
+  headers;
+  fetcher;
+  timeout;
+  requestTimeout;
+  interval;
+  retries;
+  maxAudio;
+  constructor(options = {}) {
+    if (typeof options !== "object" || options === null || Array.isArray(options) || Object.values(options).some((value) => value === null)) fail("Invalid FlowSpeech configuration", "invalid_configuration");
+    if (options.headers !== void 0 && (!record(options.headers) || Object.values(options.headers).some((value) => typeof value !== "string"))) fail("Invalid API headers", "invalid_configuration");
+    const key = options.apiKey ?? process.env.FLOWSPEECH_API_KEY;
+    if (typeof key !== "string" || !/^[\x21-\x7e]+$/.test(key)) fail("A valid server-side FlowSpeech API key is required", "invalid_configuration");
+    this.key = key;
+    this.origin = normalizeApiOrigin(options.baseUrl);
+    this.headers = new Headers();
+    for (const [name, value] of Object.entries(options.headers ?? {})) {
+      if (forbiddenHeaders.test(name)) fail("Reserved FlowSpeech header: " + name, "invalid_configuration");
+      try {
+        this.headers.set(name, value);
+      } catch {
+        fail("Invalid API header", "invalid_configuration");
+      }
+    }
+    this.fetcher = options.fetch ?? globalThis.fetch;
+    if (typeof this.fetcher !== "function") fail("A fetch implementation is required", "invalid_configuration");
+    this.timeout = integer(options.timeoutMs ?? 6e5, "timeoutMs");
+    this.requestTimeout = integer(options.requestTimeoutMs ?? 3e4, "requestTimeoutMs");
+    this.interval = integer(options.pollIntervalMs ?? 5e3, "pollIntervalMs", 5e3);
+    this.retries = integer(options.maxRetries ?? 2, "maxRetries", 0, 5);
+    this.maxAudio = integer(options.maxAudioBytes ?? 64 * 1024 * 1024, "maxAudioBytes");
+  }
+  clean(value) {
+    if (typeof value !== "string") return void 0;
+    let result = value.split(this.key).join("[redacted]");
+    for (const secret of this.headers.values()) if (secret) result = result.split(secret).join("[redacted]");
+    return result.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 500);
+  }
+  async operation(options, fn, jobId) {
+    const controller = new AbortController();
+    const cancel = () => controller.abort(new FlowSpeechError("FlowSpeech operation aborted; the server job was not cancelled", "aborted"));
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    if (options.signal?.aborted) cancel();
+    const timer = setTimeout(() => controller.abort(new FlowSpeechError("FlowSpeech total deadline exceeded; recover with the same request or job ID", "deadline_exceeded")), this.timeout);
+    const ctx = { signal: controller.signal };
+    try {
+      if (options.requestId !== void 0) ctx.requestId = uuid(options.requestId, "request ID");
+      if (jobId !== void 0) ctx.jobId = uuid(jobId, "job ID");
+      if (ctx.signal.aborted) throw ctx.signal.reason;
+      return await abortable(fn(ctx), ctx.signal);
+    } catch (error) {
+      const safe = error instanceof FlowSpeechError ? error : new FlowSpeechError("FlowSpeech request failed", "network_error", void 0, void 0, true);
+      if (ctx.requestId) safe.requestId = ctx.requestId;
+      if (ctx.jobId) safe.jobId = ctx.jobId;
+      throw safe;
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", cancel);
+    }
+  }
+  async request(url, init, ctx, download = false) {
+    for (let attempt = 0; ; attempt++) {
+      if (ctx.signal.aborted) throw ctx.signal.reason;
+      const controller = new AbortController();
+      const abort = () => controller.abort(ctx.signal.reason);
+      ctx.signal.addEventListener("abort", abort, { once: true });
+      const timer = setTimeout(() => controller.abort(new FlowSpeechError("FlowSpeech request timed out", "request_timeout", void 0, void 0, true)), this.requestTimeout);
+      let delay = this.interval;
+      try {
+        const response = await abortable(this.fetcher(url, {
+          ...init,
+          signal: controller.signal,
+          redirect: "manual",
+          credentials: "omit",
+          referrerPolicy: "no-referrer"
+        }), controller.signal);
+        if (response.redirected || response.status >= 300 && response.status < 400) {
+          void response.body?.cancel().catch(() => {
+          });
+          fail("Unexpected redirect rejected", "unexpected_redirect");
+        }
+        delay = Math.max(this.interval, retryAfter(response.headers.get("retry-after")));
+        if (download && !response.ok) {
+          void response.body?.cancel().catch(() => {
+          });
+          throw new FlowSpeechError("FlowSpeech audio download failed (HTTP " + response.status + ")", "download_error", response.status, void 0, response.status === 429 || response.status >= 500);
+        }
+        const bytes = !response.ok && !response.body ? new Uint8Array() : await boundedBody(response, download ? this.maxAudio : 1024 * 1024, controller.signal);
+        if (download) {
+          await validateWav(bytes, controller.signal);
+          return bytes;
+        }
+        let value;
+        try {
+          value = JSON.parse(new TextDecoder().decode(bytes));
+        } catch {
+          if (!response.ok) throw new FlowSpeechError("FlowSpeech API error (HTTP " + response.status + ")", "http_error", response.status, void 0, response.status === 429 || response.status >= 500);
+          fail("Malformed API JSON");
+        }
+        if (!response.ok) {
+          const error = record(value) && record(value.error) ? value.error : {};
+          const code = this.clean(error.code) ?? "http_error";
+          const message = this.clean(error.message) ?? "Request failed";
+          const traceId = record(value) ? this.clean(value.traceId) : void 0;
+          throw new FlowSpeechError(
+            "FlowSpeech API error (HTTP " + response.status + "): " + message,
+            code,
+            response.status,
+            traceId,
+            error.retryable === true || error.retryable !== false && (response.status === 429 || response.status >= 500)
+          );
+        }
+        return { value, retryAfter: delay, headers: Object.fromEntries(response.headers) };
+      } catch (error) {
+        if (ctx.signal.aborted) throw ctx.signal.reason;
+        const safe = error instanceof FlowSpeechError ? error : controller.signal.aborted ? controller.signal.reason : new FlowSpeechError("FlowSpeech network request failed", download ? "download_error" : "network_error", void 0, void 0, true);
+        if (!safe.retryable || attempt >= this.retries) throw safe;
+      } finally {
+        clearTimeout(timer);
+        ctx.signal.removeEventListener("abort", abort);
+      }
+      await wait(delay, ctx.signal);
+    }
+  }
+  async api(path, ctx, body, method = "GET") {
+    const headers = new Headers(this.headers);
+    headers.set("Authorization", "Bearer " + this.key);
+    headers.set("Accept", "application/json");
+    if (body !== void 0) {
+      headers.set("Content-Type", "application/json");
+      headers.set("Idempotency-Key", ctx.requestId);
+    }
+    return await this.request(this.origin + "/api/v1" + path, { method, headers, ...body === void 0 ? {} : { body } }, ctx);
+  }
+  async generate(input, options = {}) {
+    return this.operation({ ...options, requestId: options.requestId === void 0 ? randomUUID() : options.requestId }, async (ctx) => {
+      const body = JSON.stringify({ input: validateInput(input) });
+      if (Buffer.byteLength(body) > 1024 * 1024) fail("Input JSON exceeds 1 MiB", "invalid_request");
+      let response = await this.api("/tts/jobs", ctx, body, "POST");
+      let current = job(response.value, ctx);
+      while (!["success", "failed", "cancelled"].includes(current.status)) {
+        await wait(response.retryAfter, ctx.signal);
+        response = await this.api("/tts/jobs/" + ctx.jobId, ctx);
+        current = job(response.value, ctx);
+      }
+      const audio = await this.audio(current, ctx);
+      return { audio, job: current, requestId: ctx.requestId, requestBody: body, headers: response.headers };
+    });
+  }
+  async audio(current, ctx) {
+    if (current.status === "failed" || current.status === "cancelled") {
+      throw new FlowSpeechError("FlowSpeech job " + current.status + (current.error?.message ? ": " + this.clean(current.error.message) : ""), this.clean(current.error?.code) ?? "job_" + current.status);
+    }
+    if (current.status !== "success") fail("Job is not ready for download", "job_not_ready");
+    if (current.resultDeleted) fail("FlowSpeech result was deleted; no audio is available", "result_deleted");
+    if (!current.result) fail("Missing result");
+    return await this.request(audioUrl(current.result.url), { method: "GET" }, ctx, true);
+  }
+  async getJob(id, options = {}) {
+    return this.operation(options, async (ctx) => job((await this.api("/tts/jobs/" + ctx.jobId, ctx)).value, ctx), id);
+  }
+  async findJob(requestId, options = {}) {
+    return this.operation({ ...options, requestId }, async (ctx) => job((await this.api("/tts/jobs?requestId=" + ctx.requestId, ctx)).value, ctx));
+  }
+  async cancelJob(id, options = {}) {
+    return this.operation(options, async (ctx) => job((await this.api("/tts/jobs/" + ctx.jobId + "/cancel", ctx, void 0, "POST")).value, ctx), id);
+  }
+  /** Retries only the download of an existing successful job, never generation. */
+  async downloadJob(current, options = {}) {
+    return this.operation({ ...options, requestId: options.requestId ?? current.requestId }, async (ctx) => this.audio(job(current, ctx), ctx), current.id);
+  }
+  async getQuota(options = {}) {
+    return this.operation(options, async (ctx) => {
+      const { value } = await this.api("/quota", ctx);
+      if (!record(value) || !record(value.quota) || !record(value.limits) || !["remaining", "reserved", "available"].every((k) => number(value.quota[k]))) fail("Malformed quota response");
+      for (const field of ["entitlement", "subscription"]) {
+        if (value[field] !== void 0 && value[field] !== null && !record(value[field])) fail("Malformed subscription entitlement");
+      }
+      return value;
+    });
+  }
+  async listVoices(options = {}) {
+    return this.operation(options, async (ctx) => {
+      const { value } = await this.api("/voices", ctx);
+      if (!record(value) || !Array.isArray(value.voices) || !value.voices.every((v) => record(v) && typeof v.name === "string" && v.name.trim() && typeof v.description === "string" && typeof v.gender === "string")) fail("Malformed voices response");
+      return value.voices;
+    });
+  }
+};
+
+// src/flowspeech-provider.ts
+import { NoSuchModelError } from "@ai-sdk/provider";
+
+// src/flowspeech-speech-model.ts
+var FlowSpeechSpeechModel = class {
+  constructor(modelId, config) {
+    this.modelId = modelId;
+    this.config = config;
+    if (modelId !== "flowspeech-tts") throw new FlowSpeechError("Unsupported FlowSpeech model identifier", "unsupported_option");
+  }
+  modelId;
+  config;
+  specificationVersion = "v4";
+  get provider() {
+    return this.config.provider;
+  }
+  async doGenerate(options) {
+    rejectUnsupported({ instructions: options.instructions, speed: options.speed, language: options.language }, []);
+    if (options.outputFormat !== void 0 && options.outputFormat !== "wav") throw new FlowSpeechError("FlowSpeech v1 only supports WAV output", "unsupported_option");
+    const providerOptions = options.providerOptions?.flowspeech ?? {};
+    rejectUnsupported(providerOptions, ["segments", "requestId"]);
+    if (providerOptions.segments !== void 0 && options.text.trim()) throw new FlowSpeechError("Set text to an empty string when supplying explicit segments", "invalid_request");
+    const input = providerOptions.segments === void 0 ? { mode: "single", text: options.text, voiceName: options.voice ?? this.config.defaultVoice } : { mode: "multi", segments: providerOptions.segments };
+    const headers = new Headers(this.config.headers);
+    for (const [name, value] of Object.entries(options.headers ?? {})) if (value !== void 0) headers.set(name, value);
+    const result = await new FlowSpeechClient({ ...this.config, headers: Object.fromEntries(headers) }).generate(input, {
+      signal: options.abortSignal,
+      requestId: providerOptions.requestId
+    });
+    return {
+      audio: result.audio,
+      warnings: [],
+      request: { body: result.requestBody },
+      response: { timestamp: this.config.currentDate?.() ?? /* @__PURE__ */ new Date(), modelId: this.modelId, headers: result.headers, body: result.job },
+      providerMetadata: { flowspeech: { requestId: result.requestId, jobId: result.job.id, usage: { ...result.job.usage } } }
+    };
+  }
+};
+
+// src/flowspeech-provider.ts
+function createFlowSpeech(settings = {}) {
+  const createSpeechModel = (modelId = "flowspeech-tts") => new FlowSpeechSpeechModel(modelId, {
+    ...settings,
+    provider: "flowspeech.speech",
+    defaultVoice: settings.defaultVoice ?? "Kore"
+  });
+  const unsupported = (modelType, modelId) => {
+    throw new NoSuchModelError({ modelId, modelType, message: "FlowSpeech does not provide " + modelType + " models" });
+  };
+  return {
+    specificationVersion: "v4",
+    speech: createSpeechModel,
+    speechModel: createSpeechModel,
+    languageModel: (modelId) => unsupported("languageModel", modelId),
+    embeddingModel: (modelId) => unsupported("embeddingModel", modelId),
+    imageModel: (modelId) => unsupported("imageModel", modelId)
+  };
+}
+var flowSpeech = createFlowSpeech();
+export {
+  FlowSpeechClient,
+  FlowSpeechError,
+  FlowSpeechSpeechModel,
+  createFlowSpeech,
+  flowSpeech,
+  normalizeApiOrigin,
+  rejectUnsupported
+};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "ai-sdk-provider-flowspeech",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "FlowSpeech public API v1 asynchronous text-to-speech provider for the Vercel AI SDK.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check:runtime": "node scripts/check-runtime.mjs",
+    "test:runtime": "node --test tests/runtime-guard.mjs",
+    "pretest": "npm run check:runtime",
+    "prebuild": "npm run check:runtime",
+    "pretypecheck": "npm run check:runtime",
+    "pretest:dist": "npm run check:runtime",
+    "preaudit:package": "npm run check:runtime",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run check:runtime && npm run test:runtime && npm test && npm run typecheck && npm run build && npm run test:dist",
+    "test:dist": "node --test tests/artifact-smoke.mjs",
+    "prepack": "npm run build && npm run test:dist",
+    "audit:package": "node tests/package-audit.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/waeckerlinfederowicz66-sketch/ai-sdk-provider-flowspeech.git"
+  },
+  "homepage": "https://flowspeech.io/",
+  "bugs": {
+    "url": "https://github.com/waeckerlinfederowicz66-sketch/ai-sdk-provider-flowspeech/issues"
+  },
+  "keywords": [
+    "ai-sdk",
+    "vercel-ai-sdk",
+    "flowspeech",
+    "text-to-speech",
+    "tts",
+    "speech"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "^4.0.7",
+    "@ai-sdk/provider-utils": "^5.0.27"
+  },
+  "devDependencies": {
+    "ai": "^7.0.68",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@types/node": "24.13.3"
+  }
+}