@ai-sdk/provider 4.0.34 → 4.0.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,8 +3,16 @@ import type {
3
3
  RealtimeModelV4ClientSecretResult,
4
4
  } from './realtime-model-v4-client-secret';
5
5
  import type { RealtimeModelV4ClientEvent } from './realtime-model-v4-client-event';
6
+ import type {
7
+ RealtimeModelV4ServerConnection,
8
+ RealtimeModelV4SessionIntent,
9
+ } from './realtime-model-v4-server-connection';
6
10
  import type { RealtimeModelV4ServerEvent } from './realtime-model-v4-server-event';
7
11
  import type { RealtimeModelV4SessionConfig } from './realtime-model-v4-session-config';
12
+ import type {
13
+ RealtimeModelV4Transport,
14
+ RealtimeModelV4TransportOptions,
15
+ } from './realtime-model-v4-transport';
8
16
 
9
17
  /**
10
18
  * Specification for a realtime model that supports bidirectional
@@ -38,6 +46,7 @@ export type RealtimeModelV4 = {
38
46
  | 'client-secret-websocket'
39
47
  | 'server-websocket'
40
48
  | 'webrtc'
49
+ | 'provider'
41
50
  )[];
42
51
  /** Omission preserves session-update startup. WebRTC setup may start the session. */
43
52
  startup?: 'session-start' | 'session-update';
@@ -45,10 +54,10 @@ export type RealtimeModelV4 = {
45
54
  finalization?: 'session-close' | 'transport-close';
46
55
  };
47
56
 
48
- /** Server-only connection settings. Headers can contain long-lived credentials. */
49
- getServerWebSocketConfig?():
50
- | { url: string; headers: Record<string, string> }
51
- | PromiseLike<{ url: string; headers: Record<string, string> }>;
57
+ /** Create a provider-owned browser transport without opening a connection. */
58
+ createTransport?(
59
+ options: RealtimeModelV4TransportOptions,
60
+ ): RealtimeModelV4Transport;
52
61
 
53
62
  /** Provider-specific setup for the WebRTC event channel. */
54
63
  getWebRTCConfig?(): { dataChannelLabel: string };
@@ -100,19 +109,43 @@ export type RealtimeModelV4 = {
100
109
  ) => RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
101
110
 
102
111
  /**
103
- * Browser-side: Serializes a normalized client event into the
104
- * provider's native JSON format for sending over the WebSocket.
112
+ * Browser-side: Serializes a normalized client event into the provider's
113
+ * native WebSocket format. Server-side callers should pass the same `intent`
114
+ * used for `getServerWebSocketConfig`.
105
115
  */
106
116
  serializeClientEvent(
107
117
  event: RealtimeModelV4ClientEvent,
118
+ options?: { intent?: RealtimeModelV4SessionIntent },
108
119
  ): unknown | PromiseLike<unknown>;
109
120
 
110
121
  /**
111
- * Browser-side: Builds the provider-specific session configuration
112
- * payload from a normalized session config. Used to construct the
113
- * session.update event sent after WebSocket connection.
122
+ * Browser-side: Builds the provider-specific session configuration payload.
123
+ * Server-side callers should pass the same `intent` used for
124
+ * `getServerWebSocketConfig`.
125
+ */
126
+ buildSessionConfig(
127
+ config: RealtimeModelV4SessionConfig,
128
+ options?: { intent?: RealtimeModelV4SessionIntent },
129
+ ): unknown;
130
+
131
+ /**
132
+ * Server-side: Returns the upstream WebSocket URL and auth headers for a
133
+ * server-initiated connection — e.g. a proxy or gateway that holds the
134
+ * long-lived provider credential and owns the socket itself.
135
+ *
136
+ * Unlike `getWebSocketConfig` (browser-side, authenticates with a short-lived
137
+ * token carried in a subprotocol), this uses the provider credential the
138
+ * model was constructed with (header auth) and selects supported provider
139
+ * endpoint variants via `intent` (e.g. transcription).
140
+ *
141
+ * May return a promise for providers whose server connection requires a
142
+ * round-trip (e.g. minting an ephemeral connection token).
114
143
  */
115
- buildSessionConfig(config: RealtimeModelV4SessionConfig): unknown;
144
+ getServerWebSocketConfig?(options?: {
145
+ intent?: RealtimeModelV4SessionIntent;
146
+ }):
147
+ | RealtimeModelV4ServerConnection
148
+ | PromiseLike<RealtimeModelV4ServerConnection>;
116
149
 
117
150
  /**
118
151
  * Browser-side: Returns a message to auto-send back over the WebSocket
@@ -1,5 +1,8 @@
1
1
  export type { TranscriptionModelV4 } from './transcription-model-v4';
2
- export type { TranscriptionModelV4CallOptions } from './transcription-model-v4-call-options';
2
+ export type {
3
+ TranscriptionModelV4CallOptions,
4
+ TranscriptionModelV4TimestampGranularity,
5
+ } from './transcription-model-v4-call-options';
3
6
  export type { TranscriptionModelV4Result } from './transcription-model-v4-result';
4
7
  export type { TranscriptionModelV4StreamOptions as Experimental_TranscriptionModelV4StreamOptions } from './transcription-model-v4-stream-options';
5
8
  export type { TranscriptionModelV4StreamPart as Experimental_TranscriptionModelV4StreamPart } from './transcription-model-v4-stream-part';
@@ -2,6 +2,12 @@ import type { JSONObject } from '../../json-value/json-value';
2
2
 
3
3
  type TranscriptionModelV4ProviderOptions = Record<string, JSONObject>;
4
4
 
5
+ /**
6
+ * Timing detail to request from a transcription model.
7
+ * `word` is for word highlighting. `segment` is for caption-sized phrases.
8
+ */
9
+ export type TranscriptionModelV4TimestampGranularity = 'word' | 'segment';
10
+
5
11
  export type TranscriptionModelV4CallOptions = {
6
12
  /**
7
13
  * Audio data to transcribe.
@@ -16,6 +22,17 @@ export type TranscriptionModelV4CallOptions = {
16
22
  */
17
23
  mediaType: string;
18
24
 
25
+ /**
26
+ * Word and segment timings to request.
27
+ *
28
+ * Supporting adapters map this onto the provider's native control when that
29
+ * provider option is omitted. An explicit provider option wins. Supporting
30
+ * adapters warn when they cannot provide a requested granularity.
31
+ * An empty array requests no additional timing detail; it does not suppress
32
+ * timings returned by default.
33
+ */
34
+ timestampGranularities?: Array<TranscriptionModelV4TimestampGranularity>;
35
+
19
36
  /**
20
37
  * Additional provider-specific options that are passed through to the provider
21
38
  * as body parameters.
@@ -30,6 +30,26 @@ export type TranscriptionModelV4Result = {
30
30
  endSecond: number;
31
31
  }>;
32
32
 
33
+ /**
34
+ * Word-level timings reported by the provider, whether requested or returned
35
+ * by default. Existing `segments` behavior is preserved; some providers also
36
+ * put word timings in `segments`. Omitted when word timings are unavailable.
37
+ */
38
+ words?: Array<{
39
+ /**
40
+ * The text of this word.
41
+ */
42
+ text: string;
43
+ /**
44
+ * The start time of this word in seconds.
45
+ */
46
+ startSecond: number;
47
+ /**
48
+ * The end time of this word in seconds.
49
+ */
50
+ endSecond: number;
51
+ }>;
52
+
33
53
  /**
34
54
  * The detected language of the audio content, as an ISO-639-1 code (e.g., 'en' for English).
35
55
  * May be undefined if the language couldn't be detected.
@@ -33,6 +33,23 @@ export type TranscriptionModelV4 = {
33
33
  options: TranscriptionModelV4CallOptions,
34
34
  ): PromiseLike<TranscriptionModelV4Result>;
35
35
 
36
+ /**
37
+ * Optional native URL transcription. Its presence signals that HTTP(S)
38
+ * audio URLs can be sent to the provider without downloading them locally.
39
+ * The provider is responsible for fetching the audio; request headers are
40
+ * for the provider API and are not forwarded to the audio host.
41
+ *
42
+ * Return `undefined` if the provider cannot fetch this URL and the SDK
43
+ * should fall back to downloading it locally and calling `doGenerate`.
44
+ * Throw for other errors (such as authentication or invalid audio).
45
+ * Existing providers can continue implementing only `doGenerate`.
46
+ */
47
+ doGenerateFromUrl?(
48
+ options: Omit<TranscriptionModelV4CallOptions, 'audio' | 'mediaType'> & {
49
+ audio: URL;
50
+ },
51
+ ): PromiseLike<TranscriptionModelV4Result | undefined>;
52
+
36
53
  /**
37
54
  * Streams a transcript for live audio.
38
55
  *
@@ -2,9 +2,18 @@ import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provide
2
2
  import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
3
3
 
4
4
  /**
5
- * Generated video data. Can be a URL, base64-encoded string, or binary data.
5
+ * Generated video data, or confirmation of delivery to caller-managed storage.
6
6
  */
7
7
  export type VideoModelV4VideoData =
8
+ | {
9
+ /**
10
+ * The provider completed delivery to caller-managed storage.
11
+ * No downloadable URL or video bytes are available to the SDK.
12
+ * Never include a signed upload URL in this result.
13
+ */
14
+ type: 'uploaded';
15
+ mediaType: string;
16
+ }
8
17
  | {
9
18
  /**
10
19
  * Video available as a URL (most common for video providers).
@@ -35,7 +44,7 @@ export type VideoModelV4VideoData =
35
44
  */
36
45
  export type VideoModelV4Result = {
37
46
  /**
38
- * Generated videos as URLs, base64 strings, or binary data.
47
+ * Generated videos as URLs, base64 strings, binary data, or upload confirmations.
39
48
  *
40
49
  * Most providers return URLs to video files (MP4, WebM) due to large file sizes.
41
50
  * Use the discriminated union to indicate the type of video data being returned.