@vertesia/client 1.6.0-dev.20261022.120426Z → 1.7.0-dev.20261120.100641Z

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.
Files changed (200) hide show
  1. package/lib/AccountApi.d.ts +2 -0
  2. package/lib/AccountApi.d.ts.map +1 -1
  3. package/lib/AccountApi.js +3 -0
  4. package/lib/AccountApi.js.map +1 -1
  5. package/lib/AccountRolesApi.d.ts +11 -0
  6. package/lib/AccountRolesApi.d.ts.map +1 -0
  7. package/lib/AccountRolesApi.js +22 -0
  8. package/lib/AccountRolesApi.js.map +1 -0
  9. package/lib/AppsApi.d.ts +18 -3
  10. package/lib/AppsApi.d.ts.map +1 -1
  11. package/lib/AppsApi.js +34 -4
  12. package/lib/AppsApi.js.map +1 -1
  13. package/lib/AuditTrailApi.d.ts +6 -1
  14. package/lib/AuditTrailApi.d.ts.map +1 -1
  15. package/lib/AuditTrailApi.js +8 -0
  16. package/lib/AuditTrailApi.js.map +1 -1
  17. package/lib/EnvironmentsApi.d.ts +2 -2
  18. package/lib/EnvironmentsApi.d.ts.map +1 -1
  19. package/lib/IamApi.d.ts +1 -1
  20. package/lib/IamApi.js +1 -1
  21. package/lib/InteractionCatalogApi.d.ts +19 -1
  22. package/lib/InteractionCatalogApi.d.ts.map +1 -1
  23. package/lib/InteractionCatalogApi.js +30 -0
  24. package/lib/InteractionCatalogApi.js.map +1 -1
  25. package/lib/InteractionsApi.d.ts +3 -12
  26. package/lib/InteractionsApi.d.ts.map +1 -1
  27. package/lib/InteractionsApi.js +2 -23
  28. package/lib/InteractionsApi.js.map +1 -1
  29. package/lib/OAuthClientsApi.d.ts +3 -1
  30. package/lib/OAuthClientsApi.d.ts.map +1 -1
  31. package/lib/OAuthClientsApi.js +4 -0
  32. package/lib/OAuthClientsApi.js.map +1 -1
  33. package/lib/OAuthProvidersApi.d.ts +6 -2
  34. package/lib/OAuthProvidersApi.d.ts.map +1 -1
  35. package/lib/OAuthProvidersApi.js +6 -2
  36. package/lib/OAuthProvidersApi.js.map +1 -1
  37. package/lib/RemoteMcpConnectionsApi.d.ts +5 -1
  38. package/lib/RemoteMcpConnectionsApi.d.ts.map +1 -1
  39. package/lib/RemoteMcpConnectionsApi.js +6 -2
  40. package/lib/RemoteMcpConnectionsApi.js.map +1 -1
  41. package/lib/StreamSource.d.ts +19 -1
  42. package/lib/StreamSource.d.ts.map +1 -1
  43. package/lib/StreamSource.js +31 -1
  44. package/lib/StreamSource.js.map +1 -1
  45. package/lib/UsersApi.d.ts +7 -1
  46. package/lib/UsersApi.d.ts.map +1 -1
  47. package/lib/UsersApi.js +8 -0
  48. package/lib/UsersApi.js.map +1 -1
  49. package/lib/client.d.ts +14 -2
  50. package/lib/client.d.ts.map +1 -1
  51. package/lib/client.js +57 -8
  52. package/lib/client.js.map +1 -1
  53. package/lib/execute.d.ts.map +1 -1
  54. package/lib/execute.js +4 -2
  55. package/lib/execute.js.map +1 -1
  56. package/lib/idempotency-key.d.ts +19 -0
  57. package/lib/idempotency-key.d.ts.map +1 -0
  58. package/lib/idempotency-key.js +34 -0
  59. package/lib/idempotency-key.js.map +1 -0
  60. package/lib/nodejs/NodeStreamSource.d.ts +10 -1
  61. package/lib/nodejs/NodeStreamSource.d.ts.map +1 -1
  62. package/lib/nodejs/NodeStreamSource.js +40 -2
  63. package/lib/nodejs/NodeStreamSource.js.map +1 -1
  64. package/lib/store/AgentsApi.d.ts.map +1 -1
  65. package/lib/store/AgentsApi.js +5 -2
  66. package/lib/store/AgentsApi.js.map +1 -1
  67. package/lib/store/ContentSourcesApi.d.ts +57 -0
  68. package/lib/store/ContentSourcesApi.d.ts.map +1 -0
  69. package/lib/store/ContentSourcesApi.js +92 -0
  70. package/lib/store/ContentSourcesApi.js.map +1 -0
  71. package/lib/store/CostApi.d.ts +9 -1
  72. package/lib/store/CostApi.d.ts.map +1 -1
  73. package/lib/store/CostApi.js +16 -0
  74. package/lib/store/CostApi.js.map +1 -1
  75. package/lib/store/DashboardApi.d.ts +61 -19
  76. package/lib/store/DashboardApi.d.ts.map +1 -1
  77. package/lib/store/DashboardApi.js +75 -19
  78. package/lib/store/DashboardApi.js.map +1 -1
  79. package/lib/store/DataApi.d.ts +9 -9
  80. package/lib/store/DataApi.d.ts.map +1 -1
  81. package/lib/store/DataApi.js +14 -10
  82. package/lib/store/DataApi.js.map +1 -1
  83. package/lib/store/FilesApi.d.ts +15 -1
  84. package/lib/store/FilesApi.d.ts.map +1 -1
  85. package/lib/store/FilesApi.js +54 -75
  86. package/lib/store/FilesApi.js.map +1 -1
  87. package/lib/store/NotificationsApi.d.ts +39 -0
  88. package/lib/store/NotificationsApi.d.ts.map +1 -0
  89. package/lib/store/NotificationsApi.js +68 -0
  90. package/lib/store/NotificationsApi.js.map +1 -0
  91. package/lib/store/ObjectsApi.d.ts +6 -1
  92. package/lib/store/ObjectsApi.d.ts.map +1 -1
  93. package/lib/store/ObjectsApi.js +23 -30
  94. package/lib/store/ObjectsApi.js.map +1 -1
  95. package/lib/store/RenderingApi.d.ts.map +1 -1
  96. package/lib/store/RenderingApi.js +1 -0
  97. package/lib/store/RenderingApi.js.map +1 -1
  98. package/lib/store/WorkflowsApi.d.ts +19 -1
  99. package/lib/store/WorkflowsApi.d.ts.map +1 -1
  100. package/lib/store/WorkflowsApi.js +21 -0
  101. package/lib/store/WorkflowsApi.js.map +1 -1
  102. package/lib/store/chunked-upload.d.ts +71 -0
  103. package/lib/store/chunked-upload.d.ts.map +1 -0
  104. package/lib/store/chunked-upload.js +206 -0
  105. package/lib/store/chunked-upload.js.map +1 -0
  106. package/lib/store/client.d.ts +9 -1
  107. package/lib/store/client.d.ts.map +1 -1
  108. package/lib/store/client.js +17 -1
  109. package/lib/store/client.js.map +1 -1
  110. package/lib/store/index.d.ts +3 -0
  111. package/lib/store/index.d.ts.map +1 -1
  112. package/lib/store/index.js +3 -0
  113. package/lib/store/index.js.map +1 -1
  114. package/lib/store/node-request.browser.d.ts +14 -0
  115. package/lib/store/node-request.browser.d.ts.map +1 -0
  116. package/lib/store/node-request.browser.js +20 -0
  117. package/lib/store/node-request.browser.js.map +1 -0
  118. package/lib/store/node-request.d.ts +20 -0
  119. package/lib/store/node-request.d.ts.map +1 -0
  120. package/lib/store/node-request.js +116 -0
  121. package/lib/store/node-request.js.map +1 -0
  122. package/lib/store/node-sessions.browser.d.ts +3 -0
  123. package/lib/store/node-sessions.browser.d.ts.map +1 -0
  124. package/lib/store/node-sessions.browser.js +15 -0
  125. package/lib/store/node-sessions.browser.js.map +1 -0
  126. package/lib/store/node-sessions.d.ts +14 -0
  127. package/lib/store/node-sessions.d.ts.map +1 -0
  128. package/lib/store/node-sessions.js +88 -0
  129. package/lib/store/node-sessions.js.map +1 -0
  130. package/lib/store/signed-url.d.ts +12 -16
  131. package/lib/store/signed-url.d.ts.map +1 -1
  132. package/lib/store/signed-url.js +111 -71
  133. package/lib/store/signed-url.js.map +1 -1
  134. package/lib/store/stream-bytes.d.ts +16 -0
  135. package/lib/store/stream-bytes.d.ts.map +1 -0
  136. package/lib/store/stream-bytes.js +70 -0
  137. package/lib/store/stream-bytes.js.map +1 -0
  138. package/lib/store/stream-termination.d.ts.map +1 -1
  139. package/lib/store/stream-termination.js +17 -16
  140. package/lib/store/stream-termination.js.map +1 -1
  141. package/lib/store/upload-body.d.ts +21 -0
  142. package/lib/store/upload-body.d.ts.map +1 -0
  143. package/lib/store/upload-body.js +32 -0
  144. package/lib/store/upload-body.js.map +1 -0
  145. package/lib/store/upload-content.d.ts +21 -0
  146. package/lib/store/upload-content.d.ts.map +1 -0
  147. package/lib/store/upload-content.js +113 -0
  148. package/lib/store/upload-content.js.map +1 -0
  149. package/lib/store/upload-runtime.d.ts +21 -0
  150. package/lib/store/upload-runtime.d.ts.map +1 -0
  151. package/lib/store/upload-runtime.js +40 -0
  152. package/lib/store/upload-runtime.js.map +1 -0
  153. package/lib/user-agent.d.ts +11 -0
  154. package/lib/user-agent.d.ts.map +1 -0
  155. package/lib/user-agent.js +35 -0
  156. package/lib/user-agent.js.map +1 -0
  157. package/lib/vertesia-client.js +10 -9
  158. package/lib/vertesia-client.js.map +1 -1
  159. package/package.json +35 -11
  160. package/src/AccountApi.ts +3 -0
  161. package/src/AccountRolesApi.ts +29 -0
  162. package/src/AppsApi.ts +58 -4
  163. package/src/AuditTrailApi.ts +11 -0
  164. package/src/EnvironmentsApi.ts +2 -2
  165. package/src/IamApi.ts +1 -1
  166. package/src/InteractionCatalogApi.ts +44 -1
  167. package/src/InteractionsApi.ts +2 -31
  168. package/src/OAuthClientsApi.ts +6 -0
  169. package/src/OAuthProvidersApi.ts +7 -2
  170. package/src/RemoteMcpConnectionsApi.ts +7 -3
  171. package/src/StreamSource.ts +29 -0
  172. package/src/UsersApi.ts +10 -1
  173. package/src/client.ts +74 -8
  174. package/src/execute.ts +4 -2
  175. package/src/idempotency-key.ts +34 -0
  176. package/src/nodejs/NodeStreamSource.ts +37 -2
  177. package/src/store/AgentsApi.ts +5 -2
  178. package/src/store/ContentSourcesApi.ts +135 -0
  179. package/src/store/CostApi.ts +24 -0
  180. package/src/store/DashboardApi.ts +93 -18
  181. package/src/store/DataApi.ts +14 -10
  182. package/src/store/FilesApi.ts +84 -78
  183. package/src/store/NotificationsApi.ts +103 -0
  184. package/src/store/ObjectsApi.ts +30 -34
  185. package/src/store/RenderingApi.ts +1 -0
  186. package/src/store/WorkflowsApi.ts +25 -0
  187. package/src/store/chunked-upload.ts +272 -0
  188. package/src/store/client.ts +23 -1
  189. package/src/store/index.ts +3 -0
  190. package/src/store/node-request.browser.ts +22 -0
  191. package/src/store/node-request.ts +120 -0
  192. package/src/store/node-sessions.browser.ts +16 -0
  193. package/src/store/node-sessions.ts +109 -0
  194. package/src/store/signed-url.ts +126 -72
  195. package/src/store/stream-bytes.ts +79 -0
  196. package/src/store/stream-termination.ts +24 -24
  197. package/src/store/upload-body.ts +37 -0
  198. package/src/store/upload-content.ts +129 -0
  199. package/src/store/upload-runtime.ts +42 -0
  200. package/src/user-agent.ts +41 -0
@@ -9,10 +9,24 @@
9
9
  * restores retry behaviour for those storage hops.
10
10
  *
11
11
  * Note on streamed bodies: a `ReadableStream` body cannot be replayed once it has
12
- * been consumed, so it is buffered into memory before the first attempt to make
13
- * retries safe. Callers transferring very large streams should be aware of this
14
- * memory cost.
12
+ * been consumed. Up to {@link MAX_BUFFERED_STREAM_BYTES} of it is buffered so that
13
+ * small bodies keep their retries. In Node.js, a longer stream is never held whole in
14
+ * memory: where the storage service accepts a body of unknown length it is sent once,
15
+ * as a stream, without retries (see {@link acceptsStreamedUpload}). Send a `Blob` backed
16
+ * by a local file (Node's `fs.openAsBlob`) to keep retries for large files without a
17
+ * copy in memory. A browser buffers a stream whole, as most browsers cannot send one.
18
+ *
19
+ * A stream whose length the caller declares in a `Content-Length` header is, in Node.js,
20
+ * streamed with that length to any service, and fails if it ends short of it or runs
21
+ * past it.
22
+ *
23
+ * In Node.js, a body over that size, or a streamed one, is sent with Node's `http`
24
+ * client rather than `fetch`, which holds a streamed request body in memory until the
25
+ * request completes (see {@link nodeRequest}).
15
26
  */
27
+ import { hasNodeHttp, nodeRequest } from './node-request.js';
28
+ import { chunkToBlobPart, continueStream } from './stream-bytes.js';
29
+ import { ContentLengthMismatchError, contentLengthHeader } from './upload-runtime.js';
16
30
 
17
31
  /** HTTP statuses that storage backends return for transient, retryable conditions. */
18
32
  const DEFAULT_RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);
@@ -22,6 +36,9 @@ const DEFAULT_BASE_DELAY_MS = 500;
22
36
  const DEFAULT_MAX_DELAY_MS = 8_000;
23
37
  const MAX_RETRY_AFTER_MS = 60_000;
24
38
 
39
+ /** The most of a stream body that is buffered to allow retries: 16 MiB. */
40
+ export const MAX_BUFFERED_STREAM_BYTES = 16 * 1024 * 1024;
41
+
25
42
  export interface SignedUrlFetchOptions {
26
43
  method?: string;
27
44
  headers?: Record<string, string>;
@@ -36,12 +53,17 @@ export interface SignedUrlFetchOptions {
36
53
  retryableStatuses?: ReadonlySet<number>;
37
54
  }
38
55
 
39
- const AZURE_BLOB_HOST_SUFFIX = '.blob.core.windows.net';
56
+ /** Blob Storage host suffixes of the public Azure cloud and Azure Government. */
57
+ const AZURE_BLOB_HOST_SUFFIXES = ['.blob.core.windows.net', '.blob.core.usgovcloudapi.net'];
40
58
 
41
- /** Whether a signed URL points at Azure Blob Storage (a SAS URL on `<account>.blob.core.windows.net`). */
59
+ /**
60
+ * Whether a signed URL points at Azure Blob Storage: a SAS URL on `<account>.blob.core.windows.net`, or
61
+ * `<account>.blob.core.usgovcloudapi.net` in Azure Government.
62
+ */
42
63
  export function isAzureBlobUrl(url: string): boolean {
43
64
  try {
44
- return new URL(url).hostname.toLowerCase().endsWith(AZURE_BLOB_HOST_SUFFIX);
65
+ const hostname = new URL(url).hostname.toLowerCase();
66
+ return AZURE_BLOB_HOST_SUFFIXES.some((suffix) => hostname.endsWith(suffix));
45
67
  } catch {
46
68
  return false;
47
69
  }
@@ -63,6 +85,29 @@ export function signedUrlUploadHeaders(
63
85
  return { ...headers, 'x-ms-blob-type': 'BlockBlob' };
64
86
  }
65
87
 
88
+ /**
89
+ * Whether a signed URL's storage service accepts an upload of unknown length, sent with chunked transfer encoding
90
+ * and no `Content-Length`. Google Cloud Storage does; Amazon S3 (`MissingContentLength`) and Azure Blob Storage
91
+ * (411 Length Required) need the length up front.
92
+ */
93
+ export function acceptsStreamedUpload(url: string): boolean {
94
+ try {
95
+ const hostname = new URL(url).hostname.toLowerCase();
96
+ return hostname === 'storage.googleapis.com' || hostname.endsWith('.storage.googleapis.com');
97
+ } catch {
98
+ return false;
99
+ }
100
+ }
101
+
102
+ function isStream(body: BodyInit | null | undefined): boolean {
103
+ return typeof ReadableStream !== 'undefined' && body instanceof ReadableStream;
104
+ }
105
+
106
+ function withoutContentLength(headers: Record<string, string> | undefined): Record<string, string> | undefined {
107
+ if (!headers) return headers;
108
+ return Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== 'content-length'));
109
+ }
110
+
66
111
  function sleep(ms: number): Promise<void> {
67
112
  return new Promise((resolve) => setTimeout(resolve, ms));
68
113
  }
@@ -93,77 +138,61 @@ function backoffMs(attempt: number, baseDelayMs: number, maxDelayMs: number, res
93
138
  return Math.floor(Math.random() * capped);
94
139
  }
95
140
 
96
- const textEncoder = new TextEncoder();
97
-
98
- /**
99
- * Normalize one `ReadableStream` chunk to a byte-backed `BlobPart`.
100
- *
101
- * A web stream produced from a Node `Readable.from(<string>)` (e.g. via
102
- * `Readable.toWeb`, which `NodeStreamSource` uses) yields *string* chunks. Buffering
103
- * such a stream with `new Response(stream).blob()` throws under undici with
104
- * "TypeError: Received non-Uint8Array chunk", which breaks every signed-URL upload of
105
- * a text/JSON body (extracted text previews, agent artifacts, tool storage). Encoding
106
- * chunks ourselves keeps both string and binary bodies uploadable.
107
- */
108
- function chunkToBlobPart(chunk: unknown): BlobPart {
109
- if (typeof chunk === 'string') {
110
- return textEncoder.encode(chunk);
111
- }
112
- if (chunk instanceof Blob) {
113
- return chunk;
114
- }
115
- if (chunk instanceof ArrayBuffer) {
116
- return new Uint8Array(chunk);
117
- }
118
- // Covers Uint8Array and every other typed-array / DataView view.
119
- if (ArrayBuffer.isView(chunk)) {
120
- return new Uint8Array(chunk.buffer as ArrayBuffer, chunk.byteOffset, chunk.byteLength);
121
- }
122
- // Fail loud rather than uploading e.g. "[object Object]" from an accidental
123
- // object-mode stream — silently corrupting the stored content is worse than a clear error.
124
- throw new TypeError(
125
- `Unsupported signed-URL upload chunk of type "${typeof chunk}"; ` +
126
- `body streams must yield string or binary (Uint8Array/ArrayBuffer/DataView/Blob) chunks.`,
127
- );
141
+ /** A request body, and whether it can be sent again for a retry. */
142
+ interface PreparedBody {
143
+ body: BodyInit | undefined;
144
+ replayable: boolean;
128
145
  }
129
146
 
130
147
  /**
131
- * Buffer a `ReadableStream` body into a `Blob` so the request can be safely
132
- * replayed across retries. Other body types (`Blob`/`File`, `ArrayBuffer`,
133
- * typed arrays, strings, `URLSearchParams`) are already replayable and pass
134
- * through unchanged.
148
+ * Make a body safe to send. Bodies other than a `ReadableStream` (`Blob`/`File`, `ArrayBuffer`, typed arrays,
149
+ * strings, `URLSearchParams`) are already replayable and pass through unchanged.
150
+ *
151
+ * A stream is read until it ends or passes `maxBufferedBytes`. A stream that ends first is returned as a `Blob`, so
152
+ * it can be retried. A longer one is returned as a stream that yields the bytes read so far and then the rest,
153
+ * unless `bufferWhole` is set, in which case the rest is buffered too.
135
154
  *
136
- * The stream is drained manually (rather than `new Response(stream).blob()`) so that
137
- * string chunks are encoded to bytes — see {@link chunkToBlobPart}.
155
+ * Chunks are normalized one by one (rather than `new Response(stream).blob()`) so that string chunks are encoded to
156
+ * bytes — see {@link chunkToBlobPart}.
138
157
  */
139
- async function toReplayableBody(body: BodyInit | null | undefined): Promise<BodyInit | undefined> {
158
+ async function prepareBody(
159
+ body: BodyInit | null | undefined,
160
+ maxBufferedBytes: number,
161
+ bufferWhole: boolean,
162
+ ): Promise<PreparedBody> {
140
163
  if (body == null) {
141
- return undefined;
164
+ return { body: undefined, replayable: true };
142
165
  }
143
- if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
144
- const reader = (body as ReadableStream<unknown>).getReader();
145
- const parts: BlobPart[] = [];
146
- try {
147
- for (;;) {
148
- const { done, value } = await reader.read();
149
- if (done) {
150
- break;
151
- }
152
- // Normalize every chunk (a stray null/undefined is rejected by
153
- // chunkToBlobPart) so a malformed stream fails loudly instead of
154
- // silently uploading a truncated body.
155
- parts.push(chunkToBlobPart(value));
166
+ if (typeof ReadableStream === 'undefined' || !(body instanceof ReadableStream)) {
167
+ return { body, replayable: true };
168
+ }
169
+ const reader = (body as ReadableStream<unknown>).getReader();
170
+ const parts: BlobPart[] = [];
171
+ let buffered = 0;
172
+ try {
173
+ for (;;) {
174
+ if (!bufferWhole && buffered > maxBufferedBytes) {
175
+ return { body: continueStream(parts, reader), replayable: false };
156
176
  }
157
- } catch (err) {
158
- // Signal the producer to stop and release its resources before propagating.
159
- await reader.cancel(err).catch(() => undefined);
160
- throw err;
161
- } finally {
162
- reader.releaseLock();
177
+ const { done, value } = await reader.read();
178
+ if (done) {
179
+ break;
180
+ }
181
+ // Normalize every chunk (a stray null/undefined is rejected by
182
+ // chunkToBlobPart) so a malformed stream fails loudly instead of
183
+ // silently uploading a truncated body.
184
+ const part = chunkToBlobPart(value);
185
+ parts.push(part);
186
+ buffered += part instanceof Blob ? part.size : (part as Uint8Array).byteLength;
163
187
  }
164
- return new Blob(parts);
188
+ } catch (err) {
189
+ // Signal the producer to stop and release its resources before propagating.
190
+ await reader.cancel(err).catch(() => undefined);
191
+ reader.releaseLock();
192
+ throw err;
165
193
  }
166
- return body;
194
+ reader.releaseLock();
195
+ return { body: new Blob(parts), replayable: true };
167
196
  }
168
197
 
169
198
  /**
@@ -189,14 +218,39 @@ export async function fetchSignedUrl(url: string, options: SignedUrlFetchOptions
189
218
  retryableStatuses = DEFAULT_RETRYABLE_STATUSES,
190
219
  } = options;
191
220
 
192
- const body = await toReplayableBody(options.body);
193
- const requestHeaders = method.toUpperCase() === 'PUT' ? signedUrlUploadHeaders(url, headers) : headers;
221
+ // In Node.js, a stream longer than the buffer is sent once as a stream where that works: to a service that
222
+ // accepts a body of unknown length, or with the length the caller declared. Elsewhere it is still buffered
223
+ // whole: S3 and Azure reject a body without a length, and browsers can neither set one nor, in most of them,
224
+ // send a stream at all.
225
+ const declaredLength = isStream(options.body) ? contentLengthHeader(headers) : undefined;
226
+ const streamable = hasNodeHttp() && (acceptsStreamedUpload(url) || declaredLength !== undefined);
227
+ const { body, replayable } = await prepareBody(options.body, MAX_BUFFERED_STREAM_BYTES, !streamable);
228
+ let sendHeaders = headers;
229
+ if (declaredLength !== undefined && body instanceof Blob) {
230
+ if (body.size !== declaredLength) {
231
+ throw new ContentLengthMismatchError(
232
+ declaredLength,
233
+ body.size,
234
+ body.size < declaredLength ? 'short' : 'long',
235
+ );
236
+ }
237
+ // the buffered body sets its own length
238
+ sendHeaders = withoutContentLength(headers);
239
+ }
240
+ const requestHeaders = method.toUpperCase() === 'PUT' ? signedUrlUploadHeaders(url, sendHeaders) : sendHeaders;
241
+ const maxAttempts = replayable ? attempts : 1;
242
+ // Only Node.js streams a body (`streamable`), and always with Node's http client, so fetch only gets buffered ones.
243
+ const large = !replayable || (body instanceof Blob && body.size > MAX_BUFFERED_STREAM_BYTES);
244
+ const send =
245
+ large && hasNodeHttp()
246
+ ? () => nodeRequest(url, { method, headers: requestHeaders, body: body as Blob | ReadableStream })
247
+ : () => fetch(url, { method, headers: requestHeaders, body });
194
248
 
195
249
  let lastError: unknown;
196
- for (let attempt = 0; attempt < attempts; attempt++) {
197
- const isLastAttempt = attempt === attempts - 1;
250
+ for (let attempt = 0; attempt < maxAttempts; attempt++) {
251
+ const isLastAttempt = attempt === maxAttempts - 1;
198
252
  try {
199
- const res = await fetch(url, { method, headers: requestHeaders, body });
253
+ const res = await send();
200
254
  if (res.ok || !retryableStatuses.has(res.status) || isLastAttempt) {
201
255
  return res;
202
256
  }
@@ -0,0 +1,79 @@
1
+ /** Byte handling for upload bodies read from a `ReadableStream`. Internal: not exported from the package. */
2
+
3
+ const textEncoder = new TextEncoder();
4
+
5
+ /**
6
+ * Normalize one `ReadableStream` chunk to a byte-backed `BlobPart`.
7
+ *
8
+ * A web stream produced from a Node `Readable.from(<string>)` (e.g. via
9
+ * `Readable.toWeb`, which `NodeStreamSource` uses) yields *string* chunks. Buffering
10
+ * such a stream with `new Response(stream).blob()` throws under undici with
11
+ * "TypeError: Received non-Uint8Array chunk", which breaks every signed-URL upload of
12
+ * a text/JSON body (extracted text previews, agent artifacts, tool storage). Encoding
13
+ * chunks ourselves keeps both string and binary bodies uploadable.
14
+ */
15
+ export function chunkToBlobPart(chunk: unknown): BlobPart {
16
+ if (typeof chunk === 'string') {
17
+ return textEncoder.encode(chunk);
18
+ }
19
+ if (chunk instanceof Blob) {
20
+ return chunk;
21
+ }
22
+ if (chunk instanceof ArrayBuffer) {
23
+ return new Uint8Array(chunk);
24
+ }
25
+ // Covers Uint8Array and every other typed-array / DataView view.
26
+ if (ArrayBuffer.isView(chunk)) {
27
+ return new Uint8Array(chunk.buffer as ArrayBuffer, chunk.byteOffset, chunk.byteLength);
28
+ }
29
+ // Fail loud rather than uploading e.g. "[object Object]" from an accidental
30
+ // object-mode stream — silently corrupting the stored content is worse than a clear error.
31
+ throw new TypeError(
32
+ `Unsupported signed-URL upload chunk of type "${typeof chunk}"; ` +
33
+ `body streams must yield string or binary (Uint8Array/ArrayBuffer/DataView/Blob) chunks.`,
34
+ );
35
+ }
36
+
37
+ /** A byte stream of `head`, the parts already read, then what is left in `reader`. */
38
+ export function continueStream(
39
+ head: BlobPart[],
40
+ reader: ReadableStreamDefaultReader<unknown>,
41
+ ): ReadableStream<Uint8Array> {
42
+ const pending = [...head];
43
+ return new ReadableStream<Uint8Array>(
44
+ {
45
+ async pull(controller) {
46
+ const next = pending.shift();
47
+ if (next !== undefined) {
48
+ controller.enqueue(await partToBytes(next));
49
+ return;
50
+ }
51
+ try {
52
+ const { done, value } = await reader.read();
53
+ if (done) {
54
+ reader.releaseLock();
55
+ controller.close();
56
+ } else {
57
+ controller.enqueue(await partToBytes(chunkToBlobPart(value)));
58
+ }
59
+ } catch (err) {
60
+ // An error in pull errors this stream without calling cancel, so the source is cancelled here.
61
+ pending.length = 0;
62
+ await reader.cancel(err).catch(() => undefined);
63
+ reader.releaseLock();
64
+ throw err;
65
+ }
66
+ },
67
+ async cancel(reason) {
68
+ pending.length = 0;
69
+ await reader.cancel(reason);
70
+ reader.releaseLock();
71
+ },
72
+ },
73
+ { highWaterMark: 0 },
74
+ );
75
+ }
76
+
77
+ export async function partToBytes(part: BlobPart): Promise<Uint8Array> {
78
+ return part instanceof Blob ? new Uint8Array(await part.arrayBuffer()) : (part as Uint8Array);
79
+ }
@@ -15,32 +15,32 @@ function isRootProcessMessage(details: MessageDetails, rootRunId: string): boole
15
15
  return !processRunId || processRunId === rootRunId;
16
16
  }
17
17
 
18
- export function shouldCloseAgentRunStream(message: AgentMessage, rootRunId: string, closeOnIdle = false): boolean {
19
- if (message.type === AgentMessageType.TERMINATED) {
20
- return isRootProcessMessage(message.details, rootRunId);
21
- }
22
-
23
- if (
24
- (message.type === AgentMessageType.COMPLETE || (closeOnIdle && message.type === AgentMessageType.IDLE)) &&
25
- (message.workstream_id ?? 'main') === 'main'
26
- ) {
27
- return isRootProcessMessage(message.details, rootRunId);
28
- }
18
+ /**
19
+ * Only the main workstream's COMPLETE or TERMINATED ends the run (and IDLE when `closeOnIdle` is set).
20
+ * Sub-agents publish their own COMPLETE and TERMINATED on the parent's channel under their own
21
+ * workstream id, and child process runs publish theirs with a different `process_run_id`; neither
22
+ * ends the root run.
23
+ */
24
+ function isRunEndType(type: AgentMessageType, closeOnIdle: boolean): boolean {
25
+ return (
26
+ type === AgentMessageType.COMPLETE ||
27
+ type === AgentMessageType.TERMINATED ||
28
+ (closeOnIdle && type === AgentMessageType.IDLE)
29
+ );
30
+ }
29
31
 
30
- return false;
32
+ export function shouldCloseAgentRunStream(message: AgentMessage, rootRunId: string, closeOnIdle = false): boolean {
33
+ return (
34
+ isRunEndType(message.type, closeOnIdle) &&
35
+ (message.workstream_id ?? 'main') === 'main' &&
36
+ isRootProcessMessage(message.details, rootRunId)
37
+ );
31
38
  }
32
39
 
33
40
  export function shouldCloseCompactRunStream(message: CompactMessage, rootRunId: string, closeOnIdle = false): boolean {
34
- if (message.t === AgentMessageType.TERMINATED) {
35
- return isRootProcessMessage(message.d, rootRunId);
36
- }
37
-
38
- if (
39
- (message.t === AgentMessageType.COMPLETE || (closeOnIdle && message.t === AgentMessageType.IDLE)) &&
40
- (message.w ?? 'main') === 'main'
41
- ) {
42
- return isRootProcessMessage(message.d, rootRunId);
43
- }
44
-
45
- return false;
41
+ return (
42
+ isRunEndType(message.t, closeOnIdle) &&
43
+ (message.w ?? 'main') === 'main' &&
44
+ isRootProcessMessage(message.d, rootRunId)
45
+ );
46
46
  }
@@ -0,0 +1,37 @@
1
+ import { StreamSource } from '../StreamSource.js';
2
+
3
+ /** What to send to upload a source: the body, and the declared length of a stream body. */
4
+ export interface UploadBody {
5
+ body: Blob | ReadableStream;
6
+ /** Sent as `Content-Length` with a stream body whose length is known; a `Blob` carries its own. */
7
+ contentLength?: number;
8
+ }
9
+
10
+ /**
11
+ * The request body for uploading a source to a signed URL.
12
+ *
13
+ * A `File` is sent as it is. A stream source with a {@link StreamSource.replayableBody} (e.g. a local file) sends
14
+ * that instead, so a retry re-reads it rather than needing a buffered copy; its stream is cancelled, which releases
15
+ * what the stream holds, such as a file descriptor. Any other stream source sends its stream, with its
16
+ * {@link StreamSource.size} when known.
17
+ */
18
+ export async function getUploadBody(source: StreamSource | File): Promise<UploadBody> {
19
+ if (!(source instanceof StreamSource)) return { body: source };
20
+ const body = await source.replayableBody();
21
+ if (!body) return { body: source.stream, contentLength: source.size };
22
+ await source.stream.cancel().catch(() => undefined);
23
+ return { body };
24
+ }
25
+
26
+ /** Headers for an upload: the content type, and `Content-Length` when the body declares one. */
27
+ export function uploadHeaders(upload: UploadBody, contentType: string | undefined): Record<string, string> | undefined {
28
+ const headers: Record<string, string> = {};
29
+ if (contentType) headers['Content-Type'] = contentType;
30
+ if (upload.contentLength !== undefined) headers['Content-Length'] = String(upload.contentLength);
31
+ return Object.keys(headers).length > 0 ? headers : undefined;
32
+ }
33
+
34
+ /** An ETag without the quotes HTTP puts around it (RFC 9110), as the upload methods return it. */
35
+ export function unquoteEtag(etag: string | undefined): string | undefined {
36
+ return etag?.replace(/^"(.*)"$/, '$1');
37
+ }
@@ -0,0 +1,129 @@
1
+ /**
2
+ * The upload of a source to a file, shared by `FilesApi` and `ObjectsApi`. Internal: not exported from the package.
3
+ */
4
+ import { RequestError } from '@vertesia/api-fetch-client';
5
+ import type { CreateUploadSessionPayload, GetFileUrlResponse } from '@vertesia/common';
6
+ import type { StreamSource } from '../StreamSource.js';
7
+ import { partsAsUploadBody, planUpload, type UploadPlan, uploadInParts } from './chunked-upload.js';
8
+ import type { FilesApi } from './FilesApi.js';
9
+ import { fetchSignedUrl } from './signed-url.js';
10
+ import { type UploadBody, unquoteEtag, uploadHeaders } from './upload-body.js';
11
+ import { UploadSessionUnavailableError } from './upload-runtime.js';
12
+ import { resolveUploadMimeType } from './uploadMimeType.js';
13
+
14
+ /** A location without its query string or fragment, which hold a signed URL's credentials. */
15
+ export function fileLocationForError(location: string): string {
16
+ try {
17
+ const url = new URL(location);
18
+ return `${url.protocol}//${url.host}${url.pathname}`;
19
+ } catch {
20
+ return location.split(/[?#]/, 1)[0] || 'unknown file';
21
+ }
22
+ }
23
+
24
+ /** A copy of an error safe to log: every URL in its message is cut to its location. */
25
+ export function sanitizedErrorCause(error: unknown): Error | undefined {
26
+ if (!(error instanceof Error)) {
27
+ return undefined;
28
+ }
29
+ const message = error.message.replace(/https?:\/\/[^\s)\]}>"']+/g, (url) => fileLocationForError(url));
30
+ const cause = new Error(message);
31
+ cause.name = error.name;
32
+ return cause;
33
+ }
34
+
35
+ /**
36
+ * The statuses of a server without upload sessions (404, or 405 where another route matches the path), or whose
37
+ * storage has none (501).
38
+ */
39
+ const NO_UPLOAD_SESSION_STATUSES: ReadonlySet<number> = new Set([404, 405, 501]);
40
+
41
+ /** The stream of a plan, which a failed upload must cancel to release what it holds (a socket, a file). */
42
+ function planStream(plan: UploadPlan): ReadableStream | undefined {
43
+ const body = plan.kind === 'parts' ? plan.parts.body : plan.upload.body;
44
+ return body instanceof ReadableStream ? body : undefined;
45
+ }
46
+
47
+ /**
48
+ * Upload a source to the file `request` names: in one signed PUT, or, for a stream source longer than one part in
49
+ * Node.js, in parts through an upload session (see `chunked-upload.ts`). On failure the source's stream is cancelled.
50
+ *
51
+ * @param signUpload the signed PUT URL to use, when the caller already has one or signs it another way
52
+ * @param fallbackMimeType the content type when neither the source nor the server names one
53
+ */
54
+ export async function uploadContent(
55
+ files: FilesApi,
56
+ source: StreamSource | File,
57
+ request: CreateUploadSessionPayload,
58
+ signUpload: () => Promise<GetFileUrlResponse> = () => files.getUploadUrl(request),
59
+ fallbackMimeType?: string,
60
+ ): Promise<{ id: string; path: string; mime_type?: string; etag?: string }> {
61
+ const plan = await planUpload(source);
62
+ try {
63
+ return await sendPlan(files, source, request, plan, signUpload, fallbackMimeType);
64
+ } catch (err: unknown) {
65
+ // A stream already being sent is locked, and its sender cancels it; this one was never read whole.
66
+ await planStream(plan)
67
+ ?.cancel(err)
68
+ .catch(() => undefined);
69
+ throw err;
70
+ }
71
+ }
72
+
73
+ async function sendPlan(
74
+ files: FilesApi,
75
+ source: StreamSource | File,
76
+ request: CreateUploadSessionPayload,
77
+ plan: UploadPlan,
78
+ signUpload: () => Promise<GetFileUrlResponse>,
79
+ fallbackMimeType: string | undefined,
80
+ ): Promise<{ id: string; path: string; mime_type?: string; etag?: string }> {
81
+ let upload: UploadBody;
82
+ if (plan.kind === 'parts') {
83
+ const session = await files.createUploadSession(request).catch((err: unknown) => {
84
+ if (err instanceof RequestError && NO_UPLOAD_SESSION_STATUSES.has(err.status)) return undefined;
85
+ throw err;
86
+ });
87
+ if (!session) {
88
+ console.warn(`Upload sessions are not available; uploading ${request.name} in a single request`);
89
+ upload = partsAsUploadBody(plan.parts);
90
+ } else {
91
+ try {
92
+ const etag = await uploadInParts(files, session, plan.parts);
93
+ const mime_type = resolveUploadMimeType(source.type, session.mime_type) || fallbackMimeType;
94
+ return { id: session.id, path: session.path, mime_type, etag };
95
+ } catch (err: unknown) {
96
+ if (!(err instanceof UploadSessionUnavailableError)) {
97
+ console.error('Failed to upload file', { err: sanitizedErrorCause(err), id: session.id });
98
+ throw err;
99
+ }
100
+ console.warn(`${err.message}; uploading ${session.path} in a single request instead`);
101
+ upload = partsAsUploadBody(plan.parts);
102
+ }
103
+ }
104
+ } else {
105
+ upload = plan.upload;
106
+ }
107
+
108
+ const { url, id, path, mime_type } = await signUpload();
109
+ const sourceMimeType = resolveUploadMimeType(source.type, mime_type) || fallbackMimeType;
110
+ const res = await fetchSignedUrl(url, {
111
+ method: 'PUT',
112
+ body: upload.body,
113
+ headers: uploadHeaders(upload, sourceMimeType),
114
+ }).catch((err) => {
115
+ console.error('Failed to upload file', { err, location: fileLocationForError(url), id, path });
116
+ throw err;
117
+ });
118
+ if (!res.ok) {
119
+ console.error('Failed to upload file', {
120
+ status: res.status,
121
+ statusText: res.statusText,
122
+ location: fileLocationForError(url),
123
+ id,
124
+ path,
125
+ });
126
+ throw new Error(`Failed to upload file ${source.name}: ${res.statusText}`);
127
+ }
128
+ return { id, path, mime_type: sourceMimeType, etag: unquoteEtag(res.headers.get('etag') ?? undefined) };
129
+ }
@@ -0,0 +1,42 @@
1
+ /** Runtime checks and errors of the upload transports, safe to load in any runtime. */
2
+
3
+ /** Whether this runtime has Node's `http` client (Node.js, and runtimes compatible with it such as Bun). */
4
+ export function hasNodeHttp(): boolean {
5
+ return typeof process !== 'undefined' && typeof process.versions?.node === 'string';
6
+ }
7
+
8
+ /** The error for a body whose size differs from its declared `Content-Length`. */
9
+ export class ContentLengthMismatchError extends Error {
10
+ constructor(
11
+ readonly declared: number,
12
+ readonly actual: number,
13
+ readonly direction: 'short' | 'long',
14
+ ) {
15
+ super(
16
+ direction === 'short'
17
+ ? `Upload body ended after ${actual} bytes, short of its declared length of ${declared}`
18
+ : `Upload body ran past its declared length of ${declared} bytes`,
19
+ );
20
+ this.name = 'ContentLengthMismatchError';
21
+ }
22
+ }
23
+
24
+ /** This client cannot use the upload session: an SDK it needs is not installed, or it does not know its protocol. */
25
+ export class UploadSessionUnavailableError extends Error {
26
+ constructor(
27
+ /** What is missing, such as `the optional package @azure/storage-blob`. */
28
+ readonly requirement: string,
29
+ cause?: unknown,
30
+ ) {
31
+ super(`Uploading in parts needs ${requirement}`, { cause });
32
+ this.name = 'UploadSessionUnavailableError';
33
+ }
34
+ }
35
+
36
+ /** The `Content-Length` in `headers`, in any letter case; undefined when absent or not a whole byte count. */
37
+ export function contentLengthHeader(headers: Record<string, string> | undefined): number | undefined {
38
+ const entry = Object.entries(headers ?? {}).find(([name]) => name.toLowerCase() === 'content-length');
39
+ if (!entry || !/^\d+$/.test(entry[1].trim())) return undefined;
40
+ const length = Number(entry[1].trim());
41
+ return Number.isSafeInteger(length) ? length : undefined;
42
+ }
@@ -0,0 +1,41 @@
1
+ import packageMetadata from '../package.json' with { type: 'json' };
2
+
3
+ /** Product token every Vertesia SDK sends first in its User-Agent: `vertesia-client-<language>/<version>`. */
4
+ export const CLIENT_USER_AGENT_PRODUCT = `vertesia-client-ts/${packageMetadata.version}`;
5
+
6
+ /**
7
+ * The server-side JavaScript runtime, as `<name>/<version>`, or undefined in a browser.
8
+ */
9
+ function serverRuntime(): string | undefined {
10
+ const runtime = globalThis as typeof globalThis & {
11
+ Deno?: { version?: { deno?: string } };
12
+ process?: { versions?: { bun?: string; node?: string } };
13
+ window?: unknown;
14
+ };
15
+ if (typeof runtime.window !== 'undefined') {
16
+ return undefined;
17
+ }
18
+ const versions = runtime.process?.versions;
19
+ if (typeof versions?.bun === 'string') {
20
+ return `bun/${versions.bun}`;
21
+ }
22
+ if (typeof runtime.Deno?.version?.deno === 'string') {
23
+ return `deno/${runtime.Deno.version.deno}`;
24
+ }
25
+ if (typeof versions?.node === 'string') {
26
+ return `node/${versions.node}`;
27
+ }
28
+ return undefined;
29
+ }
30
+
31
+ /**
32
+ * The User-Agent header identifying this SDK and its version, e.g.
33
+ * `vertesia-client-ts/1.7.0 node/22.11.0`.
34
+ *
35
+ * Empty in a browser: the browser owns its User-Agent, and any other custom header would add a
36
+ * CORS preflight requirement that servers on an older release do not allow.
37
+ */
38
+ export function clientUserAgentHeaders(): Record<string, string> {
39
+ const runtime = serverRuntime();
40
+ return runtime ? { 'user-agent': `${CLIENT_USER_AGENT_PRODUCT} ${runtime}` } : {};
41
+ }