diffio 0.3.37 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Diffio JS SDK
 
-The Diffio JS SDK helps you call the Diffio API from Node. This version covers project creation, edge upload, Diffio 4.6 generations, progress checks, and download URLs.
+The Diffio JS SDK helps you call the Diffio API from Node. This version covers project creation, edge upload, Diffio 4.7 generations, progress checks, and download URLs.
 
 ## Install
 
@@ -46,10 +46,11 @@ const projects = await client.listProjects({
 
 | Model | `model` value | Endpoint | Notes |
 |---|---|---|---|
-| Diffio 4.6 Flash | `diffio-4.6-flash` | `/v1/diffio-4.6-flash-generation` | Default. Fast, high quality speech restoration. |
-| Diffio 4.6 Pro | `diffio-4.6-pro` | `/v1/diffio-4.6-pro-generation` | Best quality. Paid accounts only. |
+| Diffio 4.7 Flash | `diffio-4.7-flash` | `/v1/diffio-4.7-flash-generation` | Default. Fast, high quality speech restoration. |
+| Diffio 4.7 Pro | `diffio-4.7-pro` | `/v1/diffio-4.7-pro-generation` | Best quality. Paid accounts only. |
 
-Omitting `model` uses `diffio-4.6-flash`. Earlier models (`diffio-2`, `diffio-2-flash`, `diffio-3.2`,
+Omitting `model` uses `diffio-4.7-flash`. Older model names still work and run Diffio 4.7 (Flash or
+Pro to match); they are deprecated. Earlier models (`diffio-2`, `diffio-2-flash`, `diffio-3.2`,
 `diffio-3.4`, `diffio-3.5`, `diffio-4.0-flash`, `diffio-4.0-pro`) are retired: the SDK refuses them
 before sending a request, and the API answers their endpoints with HTTP 410 `model_retired`.
 Generations created before a model was retired keep their original `modelKey`, so response
@@ -83,7 +84,7 @@ const project = await client.createProject({
 
 const generation = await client.createGeneration({
   apiProjectId: project.apiProjectId,
-  model: "diffio-4.6-flash",
+  model: "diffio-4.7-flash",
   idempotencyKey: "restore-sample-001"
 });
 
@@ -110,7 +111,7 @@ retrying after an uncertain response.
 `waitForGeneration` and `generations.waitForComplete` wait for the overall `status` to become
 `complete`. Individual stages reaching 100% or `complete` do not end polling while video publication
 or usage settlement is still pending. They poll for up to 600 seconds unless you pass `timeout`
-or `timeoutInSeconds`. `complete` means restored media is ready. Diffio 4.6 transcribes the recording before
+or `timeoutInSeconds`. `complete` means restored media is ready. Diffio 4.7 transcribes the recording before
 restoration starts, so a completed generation has its transcript unless transcription finished as
 `unavailable`; while a generation runs, transcription can be `pending`, `available`, or `unavailable`. Read
 `progress.transcription?.status` independently. Older responses omit `transcription`; absence does
@@ -124,7 +125,7 @@ import { DiffioClient } from "diffio";
 const client = new DiffioClient({ apiKey: "diffio_live_..." });
 const result = await client.audioIsolation.isolate({
   filePath: "sample.wav",
-  model: "diffio-4.6-flash",
+  model: "diffio-4.7-flash",
   idempotencyKey: "restore-sample-001"
 });
 
@@ -145,7 +146,7 @@ import { DiffioClient } from "diffio";
 const client = new DiffioClient({ apiKey: "diffio_live_..." });
 const [audioBytes, info] = await client.restoreAudio({
   filePath: "sample.wav",
-  model: "diffio-4.6-flash",
+  model: "diffio-4.7-flash",
   idempotencyKey: "restore-sample-001",
   onProgress: (progress) => console.log(progress.status)
 });
@@ -174,6 +175,14 @@ console.log(progress.status, progress.stage);
 console.log(progress.queue?.message ?? "not queued");
 console.log(progress.stageProgress?.overallPercent);
 console.log(progress.transcription?.status ?? "not reported");
+
+for (const warning of progress.warnings) {
+  console.log(warning.code, warning.languages, warning.message);
+}
+
+if (progress.status === "failed" && progress.retryable) {
+  // A new generation for the same project can retry this failure.
+}
 ```
 
 `stage` names the one step the generation is in (`pending`, `preparing`, `transcribing`, `queued`,
@@ -181,6 +190,17 @@ console.log(progress.transcription?.status ?? "not reported");
 `failed`). While it waits for a processing worker, `queue` reports its position and why it waits;
 while a worker runs it, `stageProgress` reports percentages and byte counts when known.
 
+`warnings` lists things to know about the recording; the generation still runs. It is an empty array
+until the transcript is ready (and when an older API version omits it). Each warning has a `code`,
+`languages`, and a readable `message`. Code `unsupported_language` means the transcript has speech in
+`languages` (ISO 639-1 codes such as `ja`, most words first) that Diffio does not support yet, so the
+result probably won't be usable.
+
+When `error` is present, `retryable` says whether a new generation for the same project can fix the
+failure (`true` when transcription did not succeed after its automatic retries; `false`, for example,
+when the upload has no speech). To retry, create a new generation for the project with a new
+`idempotencyKey`, or none; reusing the failed generation's key returns that failed generation.
+
 ## Generation download
 
 ```ts
@@ -304,7 +324,9 @@ Use the raw request body (not parsed JSON) plus the `svix-*` headers and your we
 Verified events expose the same optional `event.transcription` object as generation progress.
 A `generation.completed` event reports `available` transcription, or `unavailable` when no
 transcript could be produced; completion does not wait for a later transcript. Older events can omit
-`transcription`.
+`transcription`. Events include `event.warnings`, in the same shape as progress `warnings`, only when
+the generation has warnings. A `generation.failed` event includes `event.retryable`, as progress
+does, when the API sends it.
 
 ```ts
 import express from "express";
@@ -335,10 +357,12 @@ app.post("/webhooks/diffio", express.raw({ type: "application/json" }), (req, re
 });
 ```
 
-## Upgrading to 0.3.0
+## Upgrading to 0.4.0
 
-0.3.0 adds Diffio 4.6 Flash (`diffio-4.6-flash`) and Diffio 4.6 Pro (`diffio-4.6-pro`), and the
-default model is now `diffio-4.6-flash`. Request and response shapes are unchanged.
+0.4.0 adds Diffio 4.7 Flash (`diffio-4.7-flash`) and Diffio 4.7 Pro (`diffio-4.7-pro`), and the
+default model is now `diffio-4.7-flash`. Generation progress adds `warnings` (always an array) and
+`retryable`, and generation webhook events add optional `warnings` and `retryable`. If you build
+`GenerationProgressResponse` objects yourself, for example as test fixtures, add `warnings: []`.
 
 ## Runtime compatibility
 

package/dist/Client.d.ts

@@ -1,5 +1,5 @@
 import type { BaseClientOptions, BaseRequestOptions, NormalizedClientOptions } from "./BaseClient";
-import type { AccountSettingsResponse, ApiKeyResponse, ApiKeysListResponse, AudioIsolationResult, CompleteProjectUploadResponse, CreateGenerationResponse, CreateProjectResponse, GenerationDownloadResponse, GenerationProgressResponse, ListProjectGenerationsResponse, ListProjectsResponse, ModelKey, RestoreMetadata, UsageSummaryResponse, WebhookConfigureResponse, WebhookTestEventResponse } from "./api/types";
+import type { AccountSettingsResponse, ApiKeyResponse, ApiKeysListResponse, AudioIsolationResult, CompleteProjectUploadResponse, CreateGenerationResponse, CreateProjectResponse, GenerationDownloadResponse, GenerationProgressResponse, ListProjectGenerationsResponse, ListProjectsResponse, AcceptedModelKey, RestoreMetadata, UsageSummaryResponse, WebhookConfigureResponse, WebhookTestEventResponse } from "./api/types";
 import { AccountClient, ApiKeysClient, AudioIsolationClient, GenerationsClient, ProjectsClient, UsageClient, WebhooksClient } from "./api/resources";
 export declare namespace DiffioClient {
     type Options = BaseClientOptions;
@@ -38,7 +38,7 @@ export declare class DiffioClient {
     /** Retries generation admission only when the caller supplies a nonblank idempotency key. */
     createGeneration(options: {
         apiProjectId: string;
-        model?: ModelKey;
+        model?: AcceptedModelKey;
         sampling?: Record<string, unknown>;
         params?: Record<string, unknown>;
         idempotencyKey?: string;
@@ -120,7 +120,7 @@ export declare class DiffioClient {
         contentType?: string;
         contentLength?: number;
         fileFormat?: string;
-        model?: ModelKey;
+        model?: AcceptedModelKey;
         sampling?: Record<string, unknown>;
         projectParams?: Record<string, unknown>;
         generationParams?: Record<string, unknown>;
@@ -142,7 +142,7 @@ export declare class DiffioClient {
         contentType?: string;
         contentLength?: number;
         fileFormat?: string;
-        model?: ModelKey;
+        model?: AcceptedModelKey;
         sampling?: Record<string, unknown>;
         projectParams?: Record<string, unknown>;
         generationParams?: Record<string, unknown>;

package/dist/Client.js

@@ -48,21 +48,23 @@ const DEFAULT_BASE_URL = "https://api.diffio.ai";
 const API_PREFIX = "v1";
 /** Generation endpoint for each supported model, as api/model_registry.json in diffio-ui lists them. */
 const MODEL_ENDPOINTS = {
-    "diffio-4.6-flash": "diffio-4.6-flash-generation",
-    "diffio-4.6-pro": "diffio-4.6-pro-generation"
+    "diffio-4.7-flash": "diffio-4.7-flash-generation",
+    "diffio-4.7-pro": "diffio-4.7-pro-generation"
 };
-/** Keys accepted from code written against 0.2.x; they run the matching 4.6 model. Not part of ModelKey. */
-const LEGACY_MODEL_KEYS = {
-    "diffio-4.5-flash": "diffio-4.6-flash",
-    "diffio-4.5-pro": "diffio-4.6-pro"
+/** Deprecated aliases (the registry's `aliases`); each runs the matching 4.7 model, without a warning. */
+const DEPRECATED_MODEL_KEYS = {
+    "diffio-4.6-flash": "diffio-4.7-flash",
+    "diffio-4.6-pro": "diffio-4.7-pro",
+    "diffio-4.5-flash": "diffio-4.7-flash",
+    "diffio-4.5-pro": "diffio-4.7-pro"
 };
 /** The registry's `freeDefault` model; Pro is paid-only, so it cannot be the default for every key. */
-const DEFAULT_MODEL_KEY = "diffio-4.6-flash";
+const DEFAULT_MODEL_KEY = "diffio-4.7-flash";
 const SUPPORTED_MODEL_KEYS = Object.keys(MODEL_ENDPOINTS);
 const hasOwn = (record, key) => Object.prototype.hasOwnProperty.call(record, key);
 /** Returns the generation endpoint for a model key, or undefined when the SDK does not support it. */
 function generationEndpointForModel(model) {
-    const modelKey = hasOwn(LEGACY_MODEL_KEYS, model) ? LEGACY_MODEL_KEYS[model] : model;
+    const modelKey = hasOwn(DEPRECATED_MODEL_KEYS, model) ? DEPRECATED_MODEL_KEYS[model] : model;
     return hasOwn(MODEL_ENDPOINTS, modelKey) ? MODEL_ENDPOINTS[modelKey] : undefined;
 }
 /** Per-request timeout for one edge upload call; a 32 MiB part needs about 1 Mbit/s to finish in time. */

package/dist/api/resources/audioIsolation/client/Client.d.ts

@@ -1,11 +1,11 @@
 import type { DiffioClient } from "../../../../Client";
-import type { AudioIsolationResult, GenerationProgressResponse, ModelKey, RestoreMetadata } from "../../../types";
+import type { AcceptedModelKey, AudioIsolationResult, GenerationProgressResponse, RestoreMetadata } from "../../../types";
 export interface AudioIsolationRestoreOptions {
     filePath: string;
     contentType?: string;
     contentLength?: number;
     fileFormat?: string;
-    model?: ModelKey;
+    model?: AcceptedModelKey;
     sampling?: Record<string, unknown>;
     projectParams?: Record<string, unknown>;
     generationParams?: Record<string, unknown>;
@@ -26,7 +26,7 @@ export interface AudioIsolationIsolateOptions {
     contentType?: string;
     contentLength?: number;
     fileFormat?: string;
-    model?: ModelKey;
+    model?: AcceptedModelKey;
     sampling?: Record<string, unknown>;
     projectParams?: Record<string, unknown>;
     generationParams?: Record<string, unknown>;

package/dist/api/resources/generations/client/Client.d.ts

@@ -1,8 +1,8 @@
 import type { DiffioClient } from "../../../../Client";
-import type { CreateGenerationResponse, GenerationDownloadResponse, GenerationProgressResponse, ModelKey } from "../../../types";
+import type { AcceptedModelKey, CreateGenerationResponse, GenerationDownloadResponse, GenerationProgressResponse } from "../../../types";
 export interface GenerationCreateOptions {
     apiProjectId: string;
-    model?: ModelKey;
+    model?: AcceptedModelKey;
     sampling?: Record<string, unknown>;
     params?: Record<string, unknown>;
     idempotencyKey?: string;

package/dist/api/serialization.js

@@ -117,8 +117,10 @@ function parseGenerationProgressResponse(data) {
         ...(stageProgress ? { stageProgress } : {}),
         ...(queue ? { queue } : {}),
         ...(transcription ? { transcription } : {}),
+        warnings: parseGenerationWarnings(data?.warnings),
         error: data.error ?? null,
-        errorDetails: data.errorDetails ?? null
+        errorDetails: data.errorDetails ?? null,
+        ...(typeof data?.retryable === "boolean" ? { retryable: data.retryable } : {})
     };
 }
 function parseGenerationDownloadResponse(data) {
@@ -181,6 +183,7 @@ function parseWebhookConfigureResponse(data) {
 }
 function parseGenerationWebhookEvent(data) {
     const transcription = parseGenerationTranscription(data?.transcription);
+    const warnings = parseGenerationWarnings(data?.warnings);
     return {
         eventType: data.eventType,
         eventId: data.eventId,
@@ -192,8 +195,10 @@ function parseGenerationWebhookEvent(data) {
         hasVideo: data.hasVideo ?? null,
         modelKey: data.modelKey ?? null,
         ...(transcription ? { transcription } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
         error: data.error ?? null,
-        errorDetails: data.errorDetails ?? null
+        errorDetails: data.errorDetails ?? null,
+        ...(typeof data?.retryable === "boolean" ? { retryable: data.retryable } : {})
     };
 }
 const optionalNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
@@ -242,6 +247,28 @@ function parseGenerationTranscription(data) {
     }
     return undefined;
 }
+/** Keeps the warnings with a known code and well-formed fields; anything else in the array is dropped. */
+function parseGenerationWarnings(data) {
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    const warnings = [];
+    for (const item of data) {
+        if (item == null || typeof item !== "object" || Array.isArray(item)) {
+            continue;
+        }
+        const { code, languages, message } = item;
+        if (code !== "unsupported_language" || !Array.isArray(languages) || typeof message !== "string") {
+            continue;
+        }
+        warnings.push({
+            code,
+            languages: languages.filter((language) => typeof language === "string" && language !== ""),
+            message
+        });
+    }
+    return warnings;
+}
 function createAudioIsolationResult(project, generation) {
     return { project, generation };
 }

package/dist/api/types.d.ts

@@ -1,5 +1,14 @@
-/** Models new generations can use (api/model_registry.json in diffio-ui); each has its own endpoint. */
-export type ModelKey = "diffio-4.6-flash" | "diffio-4.6-pro";
+/** Current models for new generations (api/model_registry.json in diffio-ui); each has its own endpoint. */
+export type ModelKey = "diffio-4.7-flash" | "diffio-4.7-pro";
+/**
+ * Older model names the SDK still accepts. Each runs the matching Diffio 4.7 model on its endpoint:
+ * the `-flash` names run `diffio-4.7-flash` and the `-pro` names run `diffio-4.7-pro`.
+ *
+ * @deprecated Use `diffio-4.7-flash` or `diffio-4.7-pro`.
+ */
+export type DeprecatedModelKey = "diffio-4.6-flash" | "diffio-4.6-pro" | "diffio-4.5-flash" | "diffio-4.5-pro";
+/** Every value the `model` option accepts: a current {@link ModelKey} or a deprecated alias of one. */
+export type AcceptedModelKey = ModelKey | DeprecatedModelKey;
 export type DownloadType = "audio" | "video" | "transcript";
 export type WebhookMode = "test" | "live";
 export type WebhookEventType = "generation.queued" | "generation.processing" | "generation.failed" | "generation.completed";
@@ -8,6 +17,17 @@ export type TranscriptionStatus = "pending" | "available" | "unavailable";
 export interface GenerationTranscription {
     status: TranscriptionStatus;
 }
+/** Warning codes the SDK knows; warnings with other codes are left out of parsed responses. */
+export type GenerationWarningCode = "unsupported_language";
+/** Something about a generation's recording to know about; the generation still runs. */
+export interface GenerationWarning {
+    /** `unsupported_language`: the transcript has speech in a language Diffio does not support yet. */
+    code: GenerationWarningCode;
+    /** ISO 639-1 base codes such as `ja`, the language with the most words first. */
+    languages: string[];
+    /** A readable explanation, for example that the result probably won't be usable. */
+    message: string;
+}
 /** The edge upload session create_project opened; the upload token stays inside the SDK. */
 export interface ProjectUploadSession {
     uploadSessionId: string;
@@ -110,8 +130,12 @@ export interface GenerationProgressResponse {
     queue?: GenerationQueueStatus;
     /** Independent of media completion; omitted by older API versions. */
     transcription?: GenerationTranscription;
+    /** Empty until the transcript is ready, and when older API versions omit it. */
+    warnings: GenerationWarning[];
     error?: string | null;
     errorDetails?: string | null;
+    /** Present with `error`; true when a new generation for the same project can retry the failure. */
+    retryable?: boolean;
 }
 export interface GenerationDownloadResponse {
     generationId: string;
@@ -175,8 +199,12 @@ export interface GenerationWebhookEvent {
     modelKey?: string | null;
     /** A completed generation may still have a pending or unavailable transcript. */
     transcription?: GenerationTranscription;
+    /** Present only when the generation has warnings. */
+    warnings?: GenerationWarning[];
     error?: string | null;
     errorDetails?: string | null;
+    /** On `generation.failed`: true when a new generation for the same project can fix the failure. */
+    retryable?: boolean;
 }
 export interface RestoreMetadata {
     ok: boolean;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const DIFFIO_SDK_VERSION = "0.3.37";
+export declare const DIFFIO_SDK_VERSION = "0.4.0";

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DIFFIO_SDK_VERSION = void 0;
-exports.DIFFIO_SDK_VERSION = "0.3.37";
+exports.DIFFIO_SDK_VERSION = "0.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffio",
-  "version": "0.3.37",
+  "version": "0.4.0",
   "description": "Diffio API client for Node.js",
   "repository": {
     "type": "git",