@ai-sdk/provider - npm Package Compare versions

Comparing version 4.0.4 to 4.0.5

src/video-model/v4/video-model-v4-operation-start-result.ts

+import type { JSONValue } from '../../json-value/json-value';
+import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+/**
+ * Result returned by `doStart` when initiating an asynchronous video generation.
+ */
+export type VideoModelV4OperationStartResult = {
+  /**
+   * JSON-serializable opaque reference passed to `doStatus` to check the
+   * status of the generation (e.g., a task ID or prediction URL).
+   */
+  operation: JSONValue;
+
+  /**
+   * Warnings for the call, e.g. unsupported features.
+   */
+  warnings: Array<SharedV4Warning>;
+
+  /**
+   * Additional provider-specific metadata.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
+  /**
+   * Response information for telemetry and debugging purposes.
+   */
+  response: {
+    /**
+     * Timestamp for the start of the response.
+     */
+    timestamp: Date;
+
+    /**
+     * The ID of the response model that was used.
+     */
+    modelId: string;
+
+    /**
+     * Response headers.
+     */
+    headers: Record<string, string> | undefined;
+  };
+};

src/video-model/v4/video-model-v4-operation-status-result.ts

+import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+import type { VideoModelV4VideoData } from './video-model-v4-result';
+
+/**
+ * Result returned by `doStatus` when checking the status of an
+ * asynchronous video generation.
+ */
+export type VideoModelV4OperationStatusResult =
+  | {
+      /**
+       * The video generation is still in progress.
+       */
+      status: 'pending';
+
+      /**
+       * Warnings for the call.
+       */
+      warnings?: Array<SharedV4Warning>;
+
+      /**
+       * Additional provider-specific metadata.
+       */
+      providerMetadata?: SharedV4ProviderMetadata;
+
+      /**
+       * Response information for telemetry and debugging purposes.
+       */
+      response: {
+        timestamp: Date;
+        modelId: string;
+        headers: Record<string, string> | undefined;
+      };
+    }
+  | {
+      /**
+       * The video generation is complete.
+       */
+      status: 'completed';
+
+      /**
+       * Generated videos.
+       */
+      videos: Array<VideoModelV4VideoData>;
+
+      /**
+       * Warnings for the call.
+       */
+      warnings: Array<SharedV4Warning>;
+
+      /**
+       * Additional provider-specific metadata.
+       */
+      providerMetadata?: SharedV4ProviderMetadata;
+
+      /**
+       * Response information for telemetry and debugging purposes.
+       */
+      response: {
+        timestamp: Date;
+        modelId: string;
+        headers: Record<string, string> | undefined;
+      };
+    }
+  | {
+      /**
+       * The video generation failed.
+       */
+      status: 'error';
+
+      /**
+       * A human-readable error message describing why the generation failed.
+       */
+      error: string;
+
+      /**
+       * Additional provider-specific metadata.
+       */
+      providerMetadata?: SharedV4ProviderMetadata;
+
+      /**
+       * Response information for telemetry and debugging purposes.
+       */
+      response: {
+        timestamp: Date;
+        modelId: string;
+        headers: Record<string, string> | undefined;
+      };
+    };

src/video-model/v4/video-model-v4-operation-webhook.ts

+import type { JSONValue } from '../../json-value/json-value';
+
+/**
+ * Data received from a webhook notification during asynchronous video
+ * generation. Generic over the body type so providers/consumers can
+ * narrow it to a specific shape.
+ */
+export type VideoModelV4OperationWebhook<TBody = JSONValue> = {
+  headers: Record<string, string>;
+  body: TBody;
+};

CHANGELOG.md

 # @ai-sdk/provider
 
+## 4.0.5
+
+### Patch Changes
+
+- 79e133c: async APIs for generateVideo (poll, webhook)
+
+  Adds an asynchronous start/status flow to the experimental video model
+  interface (`VideoModelV4`): models may now implement `doStart`, `doStatus`,
+  and `handleWebhookOption` instead of (or in addition to) `doGenerate`, and
+  `experimental_generateVideo` accepts `poll` and `webhook` options to
+  orchestrate completion via polling or webhooks. Polling configuration can use
+  a custom delay implementation for durable workflow compatibility.
+
 ## 4.0.4
@@ -4,0 +17,0 @@

package.json

 {
   "name": "@ai-sdk/provider",
-  "version": "4.0.4",
+  "version": "4.0.5",
   "type": "module",
@@ -5,0 +5,0 @@ "license": "Apache-2.0",

src/video-model/v4/index.ts

@@ -8,2 +8,5 @@ export type { VideoModelV4 as Experimental_VideoModelV4 } from './video-model-v4';
 export type { VideoModelV4File as Experimental_VideoModelV4File } from './video-model-v4-file';
+export type { VideoModelV4OperationStartResult as Experimental_VideoModelV4OperationStartResult } from './video-model-v4-operation-start-result';
+export type { VideoModelV4OperationStatusResult as Experimental_VideoModelV4OperationStatusResult } from './video-model-v4-operation-status-result';
+export type { VideoModelV4OperationWebhook as Experimental_VideoModelV4OperationWebhook } from './video-model-v4-operation-webhook';
 export type {
@@ -10,0 +13,0 @@ VideoModelV4FrameImage as Experimental_VideoModelV4FrameImage,

src/video-model/v4/video-model-v4.ts

@@ -0,3 +1,7 @@
+import type { JSONValue } from '../../json-value/json-value';
 import type { VideoModelV4CallOptions } from './video-model-v4-call-options';
 import type { VideoModelV4Result } from './video-model-v4-result';
+import type { VideoModelV4OperationStartResult } from './video-model-v4-operation-start-result';
+import type { VideoModelV4OperationStatusResult } from './video-model-v4-operation-status-result';
+import type { VideoModelV4OperationWebhook } from './video-model-v4-operation-webhook';
 
@@ -44,4 +48,85 @@ type GetMaxVideosPerCallFunction = (options: {
    * Generates an array of videos.
+   *
+   * Optional when `doStart` and `doStatus` are provided to support
+   * the asynchronous start/status flow.
    */
-  doGenerate(options: VideoModelV4CallOptions): PromiseLike<VideoModelV4Result>;
+  doGenerate?(
+    options: VideoModelV4CallOptions,
+  ): PromiseLike<VideoModelV4Result>;
+
+  /**
+   * Optional method that handles the user's `webhook` option for the
+   * asynchronous start/status flow.
+   *
+   * Its presence on the model signals that the provider's API natively
+   * supports webhooks. The SDK checks for this method before invoking the
+   * user-provided `webhook` factory:
+   *
+   * - **Present**: The SDK calls this method with the user's webhook factory.
+   *   The implementation should invoke the factory to obtain a webhook URL
+   *   and a `received` promise. The URL is then forwarded to `doStart` via
+   *   `webhookUrl`, and the SDK awaits `received` instead of polling.
+   *
+   * - **Absent**: The SDK never calls the user's `webhook` factory and falls
+   *   back to polling via `doStatus`. This avoids unnecessary webhook
+   *   endpoint creation for providers whose APIs have no native webhook
+   *   mechanism.
+   *
+   * This method exists because the SDK must decide whether to invoke the
+   * user's webhook factory — which may create real HTTP endpoints or
+   * external resources — *before* calling `doStart`. Without an explicit
+   * capability signal on the model, the SDK would eagerly create a webhook
+   * endpoint for every provider, even those that silently ignore the URL.
+   */
+  handleWebhookOption?: (options: {
+    webhook: () => PromiseLike<{
+      url: string;
+      received: PromiseLike<VideoModelV4OperationWebhook>;
+    }>;
+  }) => PromiseLike<{
+    webhookUrl: string;
+    received: PromiseLike<VideoModelV4OperationWebhook>;
+  }>;
+
+  /**
+   * Starts an asynchronous video generation and returns an opaque operation
+   * reference that can be passed to `doStatus` to poll for completion.
+   *
+   * When both `doStart` and `doStatus` are implemented, the SDK core can
+   * orchestrate polling or webhook-based completion instead of requiring
+   * the provider to implement its own polling loop in `doGenerate`.
+   */
+  doStart?(
+    options: VideoModelV4CallOptions & {
+      /**
+       * When provided, the provider should register this URL to receive
+       * a webhook notification when the video generation completes.
+       */
+      webhookUrl?: string;
+    },
+  ): PromiseLike<VideoModelV4OperationStartResult>;
+
+  /**
+   * Checks the status of an asynchronous video generation that was
+   * started with `doStart`.
+   *
+   * Returns either a `pending` status or a `completed` status with the
+   * generated videos.
+   */
+  doStatus?(options: {
+    /**
+     * The JSON-serializable opaque operation reference returned by `doStart`.
+     */
+    operation: JSONValue;
+
+    /**
+     * Abort signal for cancelling the operation.
+     */
+    abortSignal?: AbortSignal;
+
+    /**
+     * Additional HTTP headers.
+     */
+    headers?: Record<string, string | undefined>;
+  }): PromiseLike<VideoModelV4OperationStatusResult>;
 };

No alert changes

Improved metrics

Total package byte prevSize

612629

2.36%

Number of package files

243

1.25%

Lines of code

17026

2.39%

No dependency changes