@ai-sdk/provider 4.0.0-beta.2 → 4.0.0-beta.20

package/src/realtime-model/v4/realtime-model-v4.ts

@@ -0,0 +1,89 @@
+import type {
+  RealtimeModelV4ClientSecretOptions,
+  RealtimeModelV4ClientSecretResult,
+} from './realtime-model-v4-client-secret';
+import type { RealtimeModelV4ClientEvent } from './realtime-model-v4-client-event';
+import type { RealtimeModelV4ServerEvent } from './realtime-model-v4-server-event';
+import type { RealtimeModelV4SessionConfig } from './realtime-model-v4-session-config';
+
+/**
+ * Specification for a realtime model that supports bidirectional
+ * audio/text communication over WebSocket.
+ *
+ * Providers implement this interface to enable realtime voice
+ * conversations through the AI SDK.
+ */
+export type RealtimeModelV4 = {
+  /**
+   * The realtime model must specify which interface version it implements.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Provider ID (e.g. 'openai', 'xai').
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID (e.g. 'gpt-4o-realtime', 'grok-3').
+   */
+  readonly modelId: string;
+
+  /**
+   * Server-side: Creates an ephemeral client secret for authenticating
+   * browser-side WebSocket connections. The secret is short-lived and
+   * safe to expose to client code.
+   *
+   * Naming: "do" prefix to prevent accidental direct usage by the user.
+   */
+  doCreateClientSecret(
+    options: RealtimeModelV4ClientSecretOptions,
+  ): PromiseLike<RealtimeModelV4ClientSecretResult>;
+
+  /**
+   * Browser-side: Returns the WebSocket URL and subprotocols to use
+   * when connecting. Each provider has its own authentication mechanism
+   * (e.g. OpenAI uses subprotocol headers, xAI may use query params).
+   */
+  getWebSocketConfig(options: { token: string; url: string }): {
+    url: string;
+    protocols?: string[];
+  };
+
+  /**
+   * Browser-side: Parses a raw JSON event received over the WebSocket
+   * and returns one or more normalized events. Providers map their native
+   * event format to the common RealtimeModelV4ServerEvent union.
+   *
+   * Returns an array when a single provider message maps to multiple
+   * normalized events (e.g. Google's serverContent can contain audio,
+   * text, and turn-complete data in one message).
+   */
+  parseServerEvent(
+    raw: unknown,
+  ): RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
+
+  /**
+   * Browser-side: Serializes a normalized client event into the
+   * provider's native JSON format for sending over the WebSocket.
+   */
+  serializeClientEvent(
+    event: RealtimeModelV4ClientEvent,
+  ): unknown | PromiseLike<unknown>;
+
+  /**
+   * Browser-side: Builds the provider-specific session configuration
+   * payload from a normalized session config. Used to construct the
+   * session.update event sent after WebSocket connection.
+   */
+  buildSessionConfig(config: RealtimeModelV4SessionConfig): unknown;
+
+  /**
+   * Browser-side: Returns a message to auto-send back over the WebSocket
+   * in response to a raw incoming message, or null if no response is needed.
+   *
+   * Used for provider-specific keepalive protocols (e.g. ping/pong).
+   * Called by the session layer before parseServerEvent.
+   */
+  getHealthCheckResponse?(raw: unknown): unknown | null;
+};

package/src/reranking-model/v3/reranking-model-v3-call-options.ts

@@ -1,5 +1,5 @@
-import { JSONObject } from '../../json-value';
-import { SharedV3Headers, SharedV3ProviderOptions } from '../../shared/v3';
+import type { JSONObject } from '../../json-value';
+import type { SharedV3Headers, SharedV3ProviderOptions } from '../../shared/v3';
 
 export type RerankingModelV3CallOptions = {
   /**

package/src/reranking-model/v3/reranking-model-v3.ts

@@ -1,9 +1,9 @@
-import {
+import type {
   SharedV3Headers,
   SharedV3ProviderMetadata,
   SharedV3Warning,
 } from '../../shared/v3/';
-import { RerankingModelV3CallOptions } from './reranking-model-v3-call-options';
+import type { RerankingModelV3CallOptions } from './reranking-model-v3-call-options';
 
 /**
  * Specification for a reranking model that implements the reranking model interface version 3.

package/src/reranking-model/v4/index.ts

@@ -1,2 +1,3 @@
 export type { RerankingModelV4 } from './reranking-model-v4';
 export type { RerankingModelV4CallOptions } from './reranking-model-v4-call-options';
+export type { RerankingModelV4Result } from './reranking-model-v4-result';

package/src/reranking-model/v4/reranking-model-v4-call-options.ts

@@ -1,5 +1,5 @@
-import { JSONObject } from '../../json-value';
-import { SharedV4Headers, SharedV4ProviderOptions } from '../../shared/v4';
+import type { JSONObject } from '../../json-value';
+import type { SharedV4Headers, SharedV4ProviderOptions } from '../../shared/v4';
 
 export type RerankingModelV4CallOptions = {
   /**

package/src/reranking-model/v4/reranking-model-v4-result.ts

@@ -0,0 +1,68 @@
+import type {
+  SharedV4Headers,
+  SharedV4ProviderMetadata,
+  SharedV4Warning,
+} from '../../shared/v4/';
+
+/**
+ * The result of a reranking model doRerank call.
+ */
+export type RerankingModelV4Result = {
+  /**
+   * Ordered list of reranked documents (via index before reranking).
+   * The documents are sorted by the descending order of relevance scores.
+   */
+  ranking: Array<{
+    /**
+     * The index of the document in the original list of documents before reranking.
+     */
+    index: number;
+
+    /**
+     * The relevance score of the document after reranking.
+     */
+    relevanceScore: number;
+  }>;
+
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings?: Array<SharedV4Warning>;
+
+  /**
+   * Optional response information for debugging purposes.
+   */
+  response?: {
+    /**
+     * ID for the generated response, if the provider sends one.
+     */
+    id?: string;
+
+    /**
+     * Timestamp for the start of the generated response, if the provider sends one.
+     */
+    timestamp?: Date;
+
+    /**
+     * The ID of the response model that was used to generate the response, if the provider sends one.
+     */
+    modelId?: string;
+
+    /**
+     * Response headers.
+     */
+    headers?: SharedV4Headers;
+
+    /**
+     * Response body.
+     */
+    body?: unknown;
+  };
+};

package/src/reranking-model/v4/reranking-model-v4.ts

@@ -1,9 +1,5 @@
-import {
-  SharedV4Headers,
-  SharedV4ProviderMetadata,
-  SharedV4Warning,
-} from '../../shared/v4/';
-import { RerankingModelV4CallOptions } from './reranking-model-v4-call-options';
+import type { RerankingModelV4CallOptions } from './reranking-model-v4-call-options';
+import type { RerankingModelV4Result } from './reranking-model-v4-result';
 
 /**
  * Specification for a reranking model that implements the reranking model interface version 3.
@@ -28,63 +24,7 @@ export type RerankingModelV4 = {
    * Reranking a list of documents using the query.
    */
   // Naming: "do" prefix to prevent accidental direct usage of the method by the user.
-  doRerank(options: RerankingModelV4CallOptions): PromiseLike<{
-    /**
-     * Ordered list of reranked documents (via index before reranking).
-     * The documents are sorted by the descending order of relevance scores.
-     */
-    ranking: Array<{
-      /**
-       * The index of the document in the original list of documents before reranking.
-       */
-      index: number;
-
-      /**
-       * The relevance score of the document after reranking.
-       */
-      relevanceScore: number;
-    }>;
-
-    /**
-     * Additional provider-specific metadata. They are passed through
-     * to the provider from the AI SDK and enable provider-specific
-     * functionality that can be fully encapsulated in the provider.
-     */
-    providerMetadata?: SharedV4ProviderMetadata;
-
-    /**
-     * Warnings for the call, e.g. unsupported settings.
-     */
-    warnings?: Array<SharedV4Warning>;
-
-    /**
-     * Optional response information for debugging purposes.
-     */
-    response?: {
-      /**
-       * ID for the generated response, if the provider sends one.
-       */
-      id?: string;
-
-      /**
-       * Timestamp for the start of the generated response, if the provider sends one.
-       */
-      timestamp?: Date;
-
-      /**
-       * The ID of the response model that was used to generate the response, if the provider sends one.
-       */
-      modelId?: string;
-
-      /**
-       * Response headers.
-       */
-      headers?: SharedV4Headers;
-
-      /**
-       * Response body.
-       */
-      body?: unknown;
-    };
-  }>;
+  doRerank(
+    options: RerankingModelV4CallOptions,
+  ): PromiseLike<RerankingModelV4Result>;
 };

package/src/shared/v2/shared-v2-provider-metadata.ts

@@ -1,4 +1,4 @@
-import { JSONValue } from '../../json-value/json-value';
+import type { JSONValue } from '../../json-value/json-value';
 
 /**
  * Additional provider-specific metadata.

package/src/shared/v2/shared-v2-provider-options.ts

@@ -1,4 +1,4 @@
-import { JSONValue } from '../../json-value/json-value';
+import type { JSONValue } from '../../json-value/json-value';
 
 /**
  * Additional provider-specific options.

package/src/shared/v3/shared-v3-provider-metadata.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from '../../json-value/json-value';
+import type { JSONObject } from '../../json-value/json-value';
 
 /**
  * Additional provider-specific metadata.

package/src/shared/v3/shared-v3-provider-options.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from '../../json-value/json-value';
+import type { JSONObject } from '../../json-value/json-value';
 
 /**
  * Additional provider-specific options.

package/src/shared/v4/index.ts

@@ -1,4 +1,6 @@
+export * from './shared-v4-file-data';
 export * from './shared-v4-headers';
 export * from './shared-v4-provider-metadata';
 export * from './shared-v4-provider-options';
+export * from './shared-v4-provider-reference';
 export * from './shared-v4-warning';

package/src/shared/v4/shared-v4-file-data.ts

@@ -0,0 +1,49 @@
+import type { SharedV4ProviderReference } from './shared-v4-provider-reference';
+
+/**
+ * File data variant containing raw bytes (`Uint8Array`) or a base64-encoded
+ * string.
+ */
+export interface SharedV4FileDataData {
+  type: 'data';
+  data: Uint8Array | string;
+}
+
+/**
+ * File data variant containing a URL that points to the file.
+ */
+export interface SharedV4FileDataUrl {
+  type: 'url';
+  url: URL;
+}
+
+/**
+ * File data variant containing a provider reference (`{ [provider]: id }`).
+ */
+export interface SharedV4FileDataReference {
+  type: 'reference';
+  reference: SharedV4ProviderReference;
+}
+
+/**
+ * File data variant containing inline text content (e.g. an inline text
+ * document).
+ */
+export interface SharedV4FileDataText {
+  type: 'text';
+  text: string;
+}
+
+/**
+ * File data as a tagged discriminated union:
+ *
+ * - `{ type: 'data', data }`: raw bytes (`Uint8Array`) or base64-encoded string.
+ * - `{ type: 'url', url }`: a URL that points to the file.
+ * - `{ type: 'reference', reference }`: a provider reference (`{ [provider]: id }`).
+ * - `{ type: 'text', text }`: inline text content (e.g. an inline text document).
+ */
+export type SharedV4FileData =
+  | SharedV4FileDataData
+  | SharedV4FileDataUrl
+  | SharedV4FileDataReference
+  | SharedV4FileDataText;

package/src/shared/v4/shared-v4-provider-metadata.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from '../../json-value/json-value';
+import type { JSONObject } from '../../json-value/json-value';
 
 /**
  * Additional provider-specific metadata.

package/src/shared/v4/shared-v4-provider-options.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from '../../json-value/json-value';
+import type { JSONObject } from '../../json-value/json-value';
 
 /**
  * Additional provider-specific options.

package/src/shared/v4/shared-v4-provider-reference.ts

@@ -0,0 +1,22 @@
+/**
+ * A mapping of provider names to provider-specific file identifiers.
+ *
+ * Provider references allow files to be identified across different
+ * providers without re-uploading, by storing each provider's own
+ * identifier for the same logical file.
+ *
+ * ```ts
+ * {
+ *   "openai": "file-abc123",
+ *   "anthropic": "file-xyz789"
+ * }
+ * ```
+ *
+ * The `type?: never` constraint excludes any object that has a `type`
+ * property, so a `SharedV4ProviderReference` cannot be confused with a
+ * tagged file-data shape (e.g. `{ type: 'data', data }` or
+ * `{ type: 'reference', reference }`) when both appear in the same union.
+ */
+export type SharedV4ProviderReference = Record<string, string> & {
+  type?: never;
+};

package/src/shared/v4/shared-v4-warning.ts

@@ -37,6 +37,22 @@ export type SharedV4Warning =
        */
       details?: string;
     }
+  | {
+      /**
+       * A deprecated feature or option is being used.
+       */
+      type: 'deprecated';
+
+      /**
+       * The deprecated setting or feature name.
+       */
+      setting: string;
+
+      /**
+       * A human-readable message explaining what to use instead.
+       */
+      message: string;
+    }
   | {
       /**
        * Other warning.

package/src/skills/index.ts

@@ -0,0 +1 @@
+export * from './v4/index';

package/src/skills/v4/index.ts

@@ -0,0 +1,6 @@
+export type { SkillsV4 } from './skills-v4';
+export type {
+  SkillsV4File,
+  SkillsV4UploadSkillCallOptions,
+} from './skills-v4-upload-skill-call-options';
+export type { SkillsV4UploadSkillResult } from './skills-v4-upload-skill-result';

package/src/skills/v4/skills-v4-upload-skill-call-options.ts

@@ -0,0 +1,37 @@
+import type {
+  SharedV4FileDataData,
+  SharedV4FileDataText,
+} from '../../shared/v4/shared-v4-file-data';
+import type { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
+
+export interface SkillsV4File {
+  /**
+   * The path of the file relative to the skill root.
+   */
+  path: string;
+
+  /**
+   * The file data.
+   *
+   * - `{ type: 'data', data }`: raw bytes (`Uint8Array`) or a base64-encoded string.
+   * - `{ type: 'text', text }`: inline text (UTF-8).
+   */
+  data: SharedV4FileDataData | SharedV4FileDataText;
+}
+
+export interface SkillsV4UploadSkillCallOptions {
+  /**
+   * The files that make up the skill.
+   */
+  files: SkillsV4File[];
+
+  /**
+   * Optional human-readable title for the skill.
+   */
+  displayTitle?: string;
+
+  /**
+   * Additional provider-specific options.
+   */
+  providerOptions?: SharedV4ProviderOptions;
+}

package/src/skills/v4/skills-v4-upload-skill-result.ts

@@ -0,0 +1,40 @@
+import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import type { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+export interface SkillsV4UploadSkillResult {
+  /**
+   * A provider reference mapping provider names to provider-specific skill identifiers.
+   */
+  providerReference: SharedV4ProviderReference;
+
+  /**
+   * Optional human-readable title for the uploaded skill.
+   */
+  displayTitle?: string;
+
+  /**
+   * Optional name of the uploaded skill.
+   */
+  name?: string;
+
+  /**
+   * Optional description of what the uploaded skill does.
+   */
+  description?: string;
+
+  /**
+   * Optional latest version identifier of the uploaded skill.
+   */
+  latestVersion?: string;
+
+  /**
+   * Additional provider-specific metadata.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings: SharedV4Warning[];
+}

package/src/skills/v4/skills-v4.ts

@@ -0,0 +1,28 @@
+import type { SkillsV4UploadSkillCallOptions } from './skills-v4-upload-skill-call-options';
+import type { SkillsV4UploadSkillResult } from './skills-v4-upload-skill-result';
+
+/**
+ * Skills specification version 4.
+ */
+export interface SkillsV4 {
+  /**
+   * The skills implementation must specify which skills interface
+   * version it implements. This will allow us to evolve the skills
+   * interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Uploads a new skill from the given files.
+   */
+  uploadSkill(
+    params: SkillsV4UploadSkillCallOptions,
+  ): PromiseLike<SkillsV4UploadSkillResult>;
+}

package/src/speech-model/v2/speech-model-v2-call-options.ts

@@ -1,4 +1,4 @@
-import { JSONValue } from '../../json-value/json-value';
+import type { JSONValue } from '../../json-value/json-value';
 
 type SpeechModelV2ProviderOptions = Record<string, Record<string, JSONValue>>;
 

package/src/speech-model/v2/speech-model-v2-call-warning.ts

@@ -1,4 +1,4 @@
-import { SpeechModelV2CallOptions } from './speech-model-v2-call-options';
+import type { SpeechModelV2CallOptions } from './speech-model-v2-call-options';
 
 /**
  * Warning from the model provider for this call. The call will proceed, but e.g.

package/src/speech-model/v2/speech-model-v2.ts

@@ -1,7 +1,7 @@
-import { JSONValue } from '../../json-value';
-import { SharedV2Headers } from '../../shared';
-import { SpeechModelV2CallOptions } from './speech-model-v2-call-options';
-import { SpeechModelV2CallWarning } from './speech-model-v2-call-warning';
+import type { JSONValue } from '../../json-value';
+import type { SharedV2Headers } from '../../shared';
+import type { SpeechModelV2CallOptions } from './speech-model-v2-call-options';
+import type { SpeechModelV2CallWarning } from './speech-model-v2-call-warning';
 
 /**
  * Speech model specification version 2.

package/src/speech-model/v3/speech-model-v3-call-options.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from '../../json-value/json-value';
+import type { JSONObject } from '../../json-value/json-value';
 
 type SpeechModelV3ProviderOptions = Record<string, JSONObject>;
 

package/src/speech-model/v3/speech-model-v3.ts

@@ -1,7 +1,7 @@
-import { JSONObject } from '../../json-value';
-import { SharedV2Headers } from '../../shared';
-import { SharedV3Warning } from '../../shared/v3/shared-v3-warning';
-import { SpeechModelV3CallOptions } from './speech-model-v3-call-options';
+import type { JSONObject } from '../../json-value';
+import type { SharedV2Headers } from '../../shared';
+import type { SharedV3Warning } from '../../shared/v3/shared-v3-warning';
+import type { SpeechModelV3CallOptions } from './speech-model-v3-call-options';
 
 /**
  * Speech model specification version 3.

package/src/speech-model/v4/index.ts

@@ -1,2 +1,3 @@
 export type { SpeechModelV4 } from './speech-model-v4';
 export type { SpeechModelV4CallOptions } from './speech-model-v4-call-options';
+export type { SpeechModelV4Result } from './speech-model-v4-result';

package/src/speech-model/v4/speech-model-v4-call-options.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from '../../json-value/json-value';
+import type { JSONObject } from '../../json-value/json-value';
 
 type SpeechModelV4ProviderOptions = Record<string, JSONObject>;
 

package/src/speech-model/v4/speech-model-v4-result.ts

@@ -0,0 +1,64 @@
+import type { JSONObject } from '../../json-value';
+import type { SharedV2Headers } from '../../shared';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+/**
+ * The result of a speech model doGenerate call.
+ */
+export type SpeechModelV4Result = {
+  /**
+   * Generated audio as an ArrayBuffer.
+   * The audio should be returned without any unnecessary conversion.
+   * If the API returns base64 encoded strings, the audio should be returned
+   * as base64 encoded strings. If the API returns binary data, the audio
+   * should be returned as binary data.
+   */
+  audio: string | Uint8Array;
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings: Array<SharedV4Warning>;
+
+  /**
+   * Optional request information for telemetry and debugging purposes.
+   */
+  request?: {
+    /**
+     * Response body (available only for providers that use HTTP requests).
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Response information for telemetry and debugging purposes.
+   */
+  response: {
+    /**
+     * Timestamp for the start of the generated response.
+     */
+    timestamp: Date;
+
+    /**
+     * The ID of the response model that was used to generate the response.
+     */
+    modelId: string;
+
+    /**
+     * Response headers.
+     */
+    headers?: SharedV2Headers;
+
+    /**
+     * Response body.
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * from the provider to the AI SDK and enable provider-specific
+   * results that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: Record<string, JSONObject>;
+};