viem 2.57.15 → 2.57.16

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 (111) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/_cjs/errors/version.js +1 -1
  3. package/_cjs/tempo/Gateway.js +195 -0
  4. package/_cjs/tempo/Gateway.js.map +1 -0
  5. package/_cjs/tempo/GatewayDecorator.js +168 -0
  6. package/_cjs/tempo/GatewayDecorator.js.map +1 -0
  7. package/_cjs/tempo/actions/ai.js +69 -0
  8. package/_cjs/tempo/actions/ai.js.map +1 -0
  9. package/_cjs/tempo/actions/bucket.js +85 -0
  10. package/_cjs/tempo/actions/bucket.js.map +1 -0
  11. package/_cjs/tempo/actions/compute.js +165 -0
  12. package/_cjs/tempo/actions/compute.js.map +1 -0
  13. package/_cjs/tempo/actions/gateway.js +8 -0
  14. package/_cjs/tempo/actions/gateway.js.map +1 -0
  15. package/_cjs/tempo/actions/index.js +6 -1
  16. package/_cjs/tempo/actions/index.js.map +1 -1
  17. package/_cjs/tempo/actions/kv.js +44 -0
  18. package/_cjs/tempo/actions/kv.js.map +1 -0
  19. package/_cjs/tempo/index.js +4 -1
  20. package/_cjs/tempo/index.js.map +1 -1
  21. package/_cjs/tempo/internal/ndjson.js +43 -0
  22. package/_cjs/tempo/internal/ndjson.js.map +1 -0
  23. package/_cjs/utils/buildRequest.js +4 -0
  24. package/_cjs/utils/buildRequest.js.map +1 -1
  25. package/_cjs/utils/hash/toSignatureHash.js +10 -1
  26. package/_cjs/utils/hash/toSignatureHash.js.map +1 -1
  27. package/_cjs/utils/rpc/http.js +6 -3
  28. package/_cjs/utils/rpc/http.js.map +1 -1
  29. package/_cjs/utils/rpc/socket.js +20 -9
  30. package/_cjs/utils/rpc/socket.js.map +1 -1
  31. package/_cjs/zksync/actions/finalizeWithdrawal.js +4 -2
  32. package/_cjs/zksync/actions/finalizeWithdrawal.js.map +1 -1
  33. package/_cjs/zksync/actions/isWithdrawalFinalized.js +4 -5
  34. package/_cjs/zksync/actions/isWithdrawalFinalized.js.map +1 -1
  35. package/_esm/errors/version.js +1 -1
  36. package/_esm/tempo/Gateway.js +294 -0
  37. package/_esm/tempo/Gateway.js.map +1 -0
  38. package/_esm/tempo/GatewayDecorator.js +207 -0
  39. package/_esm/tempo/GatewayDecorator.js.map +1 -0
  40. package/_esm/tempo/actions/ai.js +132 -0
  41. package/_esm/tempo/actions/ai.js.map +1 -0
  42. package/_esm/tempo/actions/bucket.js +181 -0
  43. package/_esm/tempo/actions/bucket.js.map +1 -0
  44. package/_esm/tempo/actions/compute.js +424 -0
  45. package/_esm/tempo/actions/compute.js.map +1 -0
  46. package/_esm/tempo/actions/gateway.js +22 -0
  47. package/_esm/tempo/actions/gateway.js.map +1 -0
  48. package/_esm/tempo/actions/index.js +10 -0
  49. package/_esm/tempo/actions/index.js.map +1 -1
  50. package/_esm/tempo/actions/kv.js +124 -0
  51. package/_esm/tempo/actions/kv.js.map +1 -0
  52. package/_esm/tempo/index.js +9 -0
  53. package/_esm/tempo/index.js.map +1 -1
  54. package/_esm/tempo/internal/ndjson.js +45 -0
  55. package/_esm/tempo/internal/ndjson.js.map +1 -0
  56. package/_esm/utils/buildRequest.js +6 -0
  57. package/_esm/utils/buildRequest.js.map +1 -1
  58. package/_esm/utils/hash/toSignatureHash.js +11 -1
  59. package/_esm/utils/hash/toSignatureHash.js.map +1 -1
  60. package/_esm/utils/rpc/http.js +11 -3
  61. package/_esm/utils/rpc/http.js.map +1 -1
  62. package/_esm/utils/rpc/socket.js +24 -9
  63. package/_esm/utils/rpc/socket.js.map +1 -1
  64. package/_esm/zksync/actions/finalizeWithdrawal.js +5 -2
  65. package/_esm/zksync/actions/finalizeWithdrawal.js.map +1 -1
  66. package/_esm/zksync/actions/isWithdrawalFinalized.js +5 -5
  67. package/_esm/zksync/actions/isWithdrawalFinalized.js.map +1 -1
  68. package/_types/errors/version.d.ts +1 -1
  69. package/_types/tempo/Gateway.d.ts +337 -0
  70. package/_types/tempo/Gateway.d.ts.map +1 -0
  71. package/_types/tempo/GatewayDecorator.d.ts +635 -0
  72. package/_types/tempo/GatewayDecorator.d.ts.map +1 -0
  73. package/_types/tempo/actions/ai.d.ts +145 -0
  74. package/_types/tempo/actions/ai.d.ts.map +1 -0
  75. package/_types/tempo/actions/bucket.d.ts +210 -0
  76. package/_types/tempo/actions/bucket.d.ts.map +1 -0
  77. package/_types/tempo/actions/compute.d.ts +628 -0
  78. package/_types/tempo/actions/compute.d.ts.map +1 -0
  79. package/_types/tempo/actions/gateway.d.ts +25 -0
  80. package/_types/tempo/actions/gateway.d.ts.map +1 -0
  81. package/_types/tempo/actions/index.d.ts +10 -0
  82. package/_types/tempo/actions/index.d.ts.map +1 -1
  83. package/_types/tempo/actions/kv.d.ts +167 -0
  84. package/_types/tempo/actions/kv.d.ts.map +1 -0
  85. package/_types/tempo/index.d.ts +11 -0
  86. package/_types/tempo/index.d.ts.map +1 -1
  87. package/_types/tempo/internal/ndjson.d.ts +9 -0
  88. package/_types/tempo/internal/ndjson.d.ts.map +1 -0
  89. package/_types/utils/buildRequest.d.ts.map +1 -1
  90. package/_types/utils/hash/toSignatureHash.d.ts +1 -1
  91. package/_types/utils/hash/toSignatureHash.d.ts.map +1 -1
  92. package/_types/utils/rpc/http.d.ts.map +1 -1
  93. package/_types/utils/rpc/socket.d.ts.map +1 -1
  94. package/errors/version.ts +1 -1
  95. package/package.json +5 -1
  96. package/tempo/Gateway.ts +477 -0
  97. package/tempo/GatewayDecorator.ts +909 -0
  98. package/tempo/actions/ai.ts +250 -0
  99. package/tempo/actions/bucket.ts +324 -0
  100. package/tempo/actions/compute.ts +894 -0
  101. package/tempo/actions/gateway.ts +33 -0
  102. package/tempo/actions/index.ts +10 -0
  103. package/tempo/actions/kv.ts +229 -0
  104. package/tempo/index.ts +12 -0
  105. package/tempo/internal/ndjson.ts +51 -0
  106. package/utils/buildRequest.ts +4 -0
  107. package/utils/hash/toSignatureHash.ts +12 -2
  108. package/utils/rpc/http.ts +11 -3
  109. package/utils/rpc/socket.ts +28 -15
  110. package/zksync/actions/finalizeWithdrawal.ts +5 -2
  111. package/zksync/actions/isWithdrawalFinalized.ts +5 -5
@@ -0,0 +1,894 @@
1
+ import * as Gateway from '../Gateway.js'
2
+ import * as Ndjson from '../internal/ndjson.js'
3
+
4
+ /**
5
+ * GPU types a Gateway sandbox can run on.
6
+ *
7
+ * @experimental
8
+ */
9
+ export type Gpu =
10
+ | 'A100-40GB'
11
+ | 'A100-80GB'
12
+ | 'A10G'
13
+ | 'B200'
14
+ | 'H100'
15
+ | 'H200'
16
+ | 'L4'
17
+ | 'L40S'
18
+ | 'T4'
19
+
20
+ /**
21
+ * Gateway sandbox.
22
+ *
23
+ * @experimental
24
+ */
25
+ export type Sandbox = {
26
+ /** Creation time as a Unix timestamp in milliseconds. */
27
+ createdAt: number
28
+ /** End of the paid lifetime as a Unix timestamp in milliseconds. */
29
+ expiresAt: number
30
+ /** GPU, such as `H100` or `H100:2`, or `null` on CPU. */
31
+ gpu: string | null
32
+ /** Container image, or the snapshot it started from. */
33
+ image: string
34
+ /** End of the paid lease as a Unix timestamp in milliseconds. */
35
+ paidUntil: number
36
+ /** Sandbox ID. */
37
+ sandboxId: string
38
+ }
39
+
40
+ /**
41
+ * Starts a sandbox that can live up to `timeout` seconds, from a container image
42
+ * with optional `apt/pip` layers or from a snapshot. Compute is metered: creation
43
+ * pays for `lease` seconds at the sandbox's GPU, CPU, and memory rate (see
44
+ * `Gateway.getCapabilities`), and `renew` pays for more. `ports` are served
45
+ * over public HTTPS tunnels returned in `tunnels`.
46
+ *
47
+ * @experimental
48
+ *
49
+ * @example
50
+ * ```ts
51
+ * import { Actions, Gateway } from 'viem/tempo'
52
+ *
53
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
54
+ *
55
+ * const sandbox = await Actions.compute.create(gateway, {
56
+ * gpu: 'T4',
57
+ * image: 'pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime',
58
+ * ports: [8000],
59
+ * timeout: 1200,
60
+ * })
61
+ * const url = sandbox.tunnels[8000]
62
+ * ```
63
+ *
64
+ * @param gateway - Gateway connection.
65
+ * @param parameters - Parameters.
66
+ * @returns The sandbox and its tunnels.
67
+ */
68
+ export async function create<
69
+ const ports extends readonly number[] = readonly [],
70
+ >(
71
+ gateway: Gateway.Gateway,
72
+ parameters: create.Parameters<ports> = {} as create.Parameters<ports>,
73
+ ): Promise<create.ReturnValue<ports>> {
74
+ const {
75
+ apt,
76
+ blockNetwork,
77
+ cpu,
78
+ env,
79
+ gpu,
80
+ gpuCount,
81
+ idleTimeout,
82
+ image,
83
+ lease,
84
+ memory,
85
+ pip,
86
+ ports,
87
+ signal,
88
+ snapshot,
89
+ timeout,
90
+ workdir,
91
+ } = parameters
92
+ const response = await Gateway.request(gateway, {
93
+ body: JSON.stringify({
94
+ apt,
95
+ blockNetwork,
96
+ cpu,
97
+ env,
98
+ gpu,
99
+ gpuCount,
100
+ idleTimeout,
101
+ image,
102
+ lease,
103
+ memory,
104
+ pip,
105
+ ports,
106
+ snapshot,
107
+ timeout,
108
+ workdir,
109
+ }),
110
+ path: '/compute/create',
111
+ signal,
112
+ })
113
+ return (await response.json()) as create.ReturnValue<ports>
114
+ }
115
+
116
+ export declare namespace create {
117
+ type Parameters<ports extends readonly number[] = readonly number[]> = {
118
+ /** Block all network access from the sandbox. */
119
+ blockNetwork?: boolean | undefined
120
+ /**
121
+ * CPU cores.
122
+ *
123
+ * @default 1
124
+ */
125
+ cpu?: number | undefined
126
+ /** Environment variables. */
127
+ env?: Record<string, string> | undefined
128
+ /** Seconds without activity after which the sandbox ends. */
129
+ idleTimeout?: number | undefined
130
+ /**
131
+ * Seconds paid at creation. Pay for more with `renew`; the sandbox is
132
+ * terminated about a minute after its lease ends.
133
+ *
134
+ * @default 300, or `timeout` if shorter
135
+ */
136
+ lease?: number | undefined
137
+ /**
138
+ * Memory in MiB.
139
+ *
140
+ * @default 1024
141
+ */
142
+ memory?: number | undefined
143
+ /** Ports to serve over public HTTPS tunnels, up to 4. */
144
+ ports?: ports | undefined
145
+ /** Signal to abort the request. */
146
+ signal?: AbortSignal | undefined
147
+ /**
148
+ * Longest lifetime in seconds, whatever is paid.
149
+ *
150
+ * @default 300
151
+ */
152
+ timeout?: number | undefined
153
+ /** Working directory. */
154
+ workdir?: string | undefined
155
+ } & (
156
+ | {
157
+ /** Debian packages to install on the image. */
158
+ apt?: readonly string[] | undefined
159
+ /**
160
+ * Container image.
161
+ *
162
+ * @default 'python:3.12-slim'
163
+ */
164
+ image?: string | undefined
165
+ /** pip requirements to install on the image. */
166
+ pip?: readonly string[] | undefined
167
+ snapshot?: undefined
168
+ }
169
+ | {
170
+ apt?: undefined
171
+ image?: undefined
172
+ pip?: undefined
173
+ /** Snapshot ID from `snapshot` to start from instead of an image. */
174
+ snapshot: string
175
+ }
176
+ ) &
177
+ (
178
+ | {
179
+ /** GPU type. Omit to run on CPU. */
180
+ gpu: Gpu
181
+ /**
182
+ * Number of GPUs.
183
+ *
184
+ * @default 1
185
+ */
186
+ gpuCount?: number | undefined
187
+ }
188
+ | {
189
+ gpu?: undefined
190
+ gpuCount?: undefined
191
+ }
192
+ )
193
+
194
+ type ReturnValue<ports extends readonly number[] = readonly number[]> =
195
+ Sandbox & {
196
+ /** Public HTTPS URL of each requested port. */
197
+ tunnels: { [port in ports[number] as `${port}`]: string }
198
+ }
199
+
200
+ type ErrorType = Gateway.request.ErrorType
201
+ }
202
+
203
+ /**
204
+ * Runs a command in a sandbox and waits up to `timeout` seconds (at most 120)
205
+ * for it to finish. Use `spawn` for longer jobs. Paid per request.
206
+ *
207
+ * @experimental
208
+ *
209
+ * @example
210
+ * ```ts
211
+ * import { Actions, Gateway } from 'viem/tempo'
212
+ *
213
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
214
+ *
215
+ * const { exitCode, stdout } = await Actions.compute.exec(gateway, {
216
+ * command: ['python', '-c', 'print(1 + 1)'],
217
+ * sandboxId: sandbox.sandboxId,
218
+ * })
219
+ * ```
220
+ *
221
+ * @param gateway - Gateway connection.
222
+ * @param parameters - Parameters.
223
+ * @returns The command's output and exit code.
224
+ */
225
+ export async function exec(
226
+ gateway: Gateway.Gateway,
227
+ parameters: exec.Parameters,
228
+ ): Promise<exec.ReturnValue> {
229
+ const { command, env, sandboxId, signal, timeout, workdir } = parameters
230
+ const response = await Gateway.request(gateway, {
231
+ body: JSON.stringify({ command, env, sandboxId, timeout, workdir }),
232
+ path: '/compute/exec',
233
+ signal,
234
+ })
235
+ return (await response.json()) as exec.ReturnValue
236
+ }
237
+
238
+ export declare namespace exec {
239
+ type Parameters = {
240
+ /** Program and arguments, run without a shell. */
241
+ command: readonly [string, ...string[]]
242
+ /** Environment variables. */
243
+ env?: Record<string, string> | undefined
244
+ /** Sandbox ID. */
245
+ sandboxId: string
246
+ /** Signal to abort the request. */
247
+ signal?: AbortSignal | undefined
248
+ /**
249
+ * Command timeout in seconds, at most 120.
250
+ *
251
+ * @default 30
252
+ */
253
+ timeout?: number | undefined
254
+ /** Working directory. */
255
+ workdir?: string | undefined
256
+ }
257
+
258
+ type ReturnValue = {
259
+ /** Exit code, or `null` if the command did not exit. */
260
+ exitCode: number | null
261
+ /** Standard error. */
262
+ stderr: string
263
+ /** Standard output. */
264
+ stdout: string
265
+ /** Whether the command was stopped at its timeout. */
266
+ timedOut: boolean
267
+ /** Whether output was cut at 1 MiB per stream. */
268
+ truncated: boolean
269
+ }
270
+
271
+ type ErrorType = Gateway.request.ErrorType
272
+ }
273
+
274
+ /**
275
+ * Lists the app's sandboxes that have not ended. Paid per request.
276
+ *
277
+ * @experimental
278
+ *
279
+ * @example
280
+ * ```ts
281
+ * import { Actions, Gateway } from 'viem/tempo'
282
+ *
283
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
284
+ *
285
+ * const { sandboxes } = await Actions.compute.list(gateway)
286
+ * ```
287
+ *
288
+ * @param gateway - Gateway connection.
289
+ * @param parameters - Parameters.
290
+ * @returns A page of sandboxes and the next cursor.
291
+ */
292
+ export async function list(
293
+ gateway: Gateway.Gateway,
294
+ parameters: list.Parameters = {},
295
+ ): Promise<list.ReturnValue> {
296
+ const { cursor, limit, signal } = parameters
297
+ const response = await Gateway.request(gateway, {
298
+ body: JSON.stringify({ cursor, limit }),
299
+ path: '/compute/list',
300
+ signal,
301
+ })
302
+ return (await response.json()) as list.ReturnValue
303
+ }
304
+
305
+ export declare namespace list {
306
+ type Parameters = {
307
+ /** Cursor from a previous page. */
308
+ cursor?: string | undefined
309
+ /** Maximum sandboxes per page. */
310
+ limit?: number | undefined
311
+ /** Signal to abort the request. */
312
+ signal?: AbortSignal | undefined
313
+ }
314
+
315
+ type ReturnValue = {
316
+ /** Cursor of the next page, or `null` on the last page. */
317
+ cursor: string | null
318
+ /** Sandboxes on this page. */
319
+ sandboxes: readonly Sandbox[]
320
+ }
321
+
322
+ type ErrorType = Gateway.request.ErrorType
323
+ }
324
+
325
+ /**
326
+ * Reads a file from a sandbox, from `offset` for up to `length` bytes (8 MiB
327
+ * per request). Returns `null` when the file does not exist. Paid per request.
328
+ *
329
+ * @experimental
330
+ *
331
+ * @example
332
+ * ```ts
333
+ * import { Actions, Gateway } from 'viem/tempo'
334
+ *
335
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
336
+ *
337
+ * const log = await Actions.compute.read(gateway, {
338
+ * offset: 0,
339
+ * path: job.logPath,
340
+ * sandboxId: sandbox.sandboxId,
341
+ * })
342
+ * const text = log && (await new Response(log.body).text())
343
+ * ```
344
+ *
345
+ * @param gateway - Gateway connection.
346
+ * @param parameters - Parameters.
347
+ * @returns The bytes read and the whole file size, or `null`.
348
+ */
349
+ export async function read(
350
+ gateway: Gateway.Gateway,
351
+ parameters: read.Parameters,
352
+ ): Promise<read.ReturnValue> {
353
+ const { length, offset, path, sandboxId, signal } = parameters
354
+ const response = await Gateway.request(gateway, {
355
+ body: JSON.stringify({ length, offset, path, sandboxId }),
356
+ path: '/compute/read',
357
+ signal,
358
+ }).catch((error) => {
359
+ if (error instanceof Gateway.RequestError && error.code === 'not_found')
360
+ return null
361
+ throw error
362
+ })
363
+ if (!response?.body) return null
364
+
365
+ return {
366
+ body: response.body,
367
+ offset: offset ?? 0,
368
+ size: Number(response.headers.get('gateway-file-size')),
369
+ }
370
+ }
371
+
372
+ export declare namespace read {
373
+ type Parameters = {
374
+ /** Maximum bytes to read, at most 8 MiB. */
375
+ length?: number | undefined
376
+ /**
377
+ * Byte offset to read from.
378
+ *
379
+ * @default 0
380
+ */
381
+ offset?: number | undefined
382
+ /** Absolute file path. */
383
+ path: string
384
+ /** Sandbox ID. */
385
+ sandboxId: string
386
+ /** Signal to abort the request. */
387
+ signal?: AbortSignal | undefined
388
+ }
389
+
390
+ type ReturnValue = {
391
+ /** Bytes read. */
392
+ body: ReadableStream<Uint8Array>
393
+ /** Offset the bytes start at. */
394
+ offset: number
395
+ /** Size of the whole file in bytes. */
396
+ size: number
397
+ } | null
398
+
399
+ type ErrorType = Gateway.request.ErrorType
400
+ }
401
+
402
+ /**
403
+ * Saves a sandbox's filesystem as a snapshot kept for 30 days. Pass it to
404
+ * `create` to start new sandboxes from it. Paid per request.
405
+ *
406
+ * @experimental
407
+ *
408
+ * @example
409
+ * ```ts
410
+ * import { Actions, Gateway } from 'viem/tempo'
411
+ *
412
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
413
+ *
414
+ * const { snapshot } = await Actions.compute.snapshot(gateway, {
415
+ * sandboxId: sandbox.sandboxId,
416
+ * })
417
+ * const copy = await Actions.compute.create(gateway, { snapshot })
418
+ * ```
419
+ *
420
+ * @param gateway - Gateway connection.
421
+ * @param parameters - Parameters.
422
+ * @returns The snapshot ID and its expiry.
423
+ */
424
+ export async function snapshot(
425
+ gateway: Gateway.Gateway,
426
+ parameters: snapshot.Parameters,
427
+ ): Promise<snapshot.ReturnValue> {
428
+ const { sandboxId, signal } = parameters
429
+ const response = await Gateway.request(gateway, {
430
+ body: JSON.stringify({ sandboxId }),
431
+ path: '/compute/snapshot',
432
+ signal,
433
+ })
434
+ return (await response.json()) as snapshot.ReturnValue
435
+ }
436
+
437
+ export declare namespace snapshot {
438
+ type Parameters = {
439
+ /** Sandbox ID. */
440
+ sandboxId: string
441
+ /** Signal to abort the request. */
442
+ signal?: AbortSignal | undefined
443
+ }
444
+
445
+ type ReturnValue = {
446
+ /** Creation time as a Unix timestamp in milliseconds. */
447
+ createdAt: number
448
+ /** Expiry as a Unix timestamp in milliseconds. */
449
+ expiresAt: number
450
+ /** Snapshot ID. */
451
+ snapshot: string
452
+ }
453
+
454
+ type ErrorType = Gateway.request.ErrorType
455
+ }
456
+
457
+ /**
458
+ * Starts a command in the background and returns at once. Its output goes to
459
+ * `logPath` and its exit code to `exitPath` when it finishes; poll both with
460
+ * `read`. Paid per request.
461
+ *
462
+ * @experimental
463
+ *
464
+ * @example
465
+ * ```ts
466
+ * import { Actions, Gateway } from 'viem/tempo'
467
+ *
468
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
469
+ *
470
+ * const job = await Actions.compute.spawn(gateway, {
471
+ * command: ['python', 'train.py'],
472
+ * sandboxId: sandbox.sandboxId,
473
+ * })
474
+ * ```
475
+ *
476
+ * @param gateway - Gateway connection.
477
+ * @param parameters - Parameters.
478
+ * @returns The process ID and the paths of its log and exit code.
479
+ */
480
+ export async function spawn(
481
+ gateway: Gateway.Gateway,
482
+ parameters: spawn.Parameters,
483
+ ): Promise<spawn.ReturnValue> {
484
+ const { command, env, sandboxId, signal, workdir } = parameters
485
+ const response = await Gateway.request(gateway, {
486
+ body: JSON.stringify({ command, env, sandboxId, workdir }),
487
+ path: '/compute/spawn',
488
+ signal,
489
+ })
490
+ return (await response.json()) as spawn.ReturnValue
491
+ }
492
+
493
+ export declare namespace spawn {
494
+ type Parameters = {
495
+ /** Program and arguments, run without a shell. */
496
+ command: readonly [string, ...string[]]
497
+ /** Environment variables. */
498
+ env?: Record<string, string> | undefined
499
+ /** Sandbox ID. */
500
+ sandboxId: string
501
+ /** Signal to abort the request. */
502
+ signal?: AbortSignal | undefined
503
+ /** Working directory. */
504
+ workdir?: string | undefined
505
+ }
506
+
507
+ type ReturnValue = {
508
+ /** File that holds the exit code once the command finishes. */
509
+ exitPath: string
510
+ /** File with the command's standard output and error. */
511
+ logPath: string
512
+ /** Process ID. */
513
+ pid: number
514
+ }
515
+
516
+ type ErrorType = Gateway.request.ErrorType
517
+ }
518
+
519
+ /**
520
+ * Reads whether a sandbox is running. Paid per request.
521
+ *
522
+ * @experimental
523
+ *
524
+ * @example
525
+ * ```ts
526
+ * import { Actions, Gateway } from 'viem/tempo'
527
+ *
528
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
529
+ *
530
+ * const { status } = await Actions.compute.status(gateway, {
531
+ * sandboxId: sandbox.sandboxId,
532
+ * })
533
+ * ```
534
+ *
535
+ * @param gateway - Gateway connection.
536
+ * @param parameters - Parameters.
537
+ * @returns The sandbox and its status.
538
+ */
539
+ export async function status(
540
+ gateway: Gateway.Gateway,
541
+ parameters: status.Parameters,
542
+ ): Promise<status.ReturnValue> {
543
+ const { sandboxId, signal } = parameters
544
+ const response = await Gateway.request(gateway, {
545
+ body: JSON.stringify({ sandboxId }),
546
+ path: '/compute/status',
547
+ signal,
548
+ })
549
+ return (await response.json()) as status.ReturnValue
550
+ }
551
+
552
+ export declare namespace status {
553
+ type Parameters = {
554
+ /** Sandbox ID. */
555
+ sandboxId: string
556
+ /** Signal to abort the request. */
557
+ signal?: AbortSignal | undefined
558
+ }
559
+
560
+ type ReturnValue = Sandbox & {
561
+ /** Exit code once terminated, otherwise `null`. */
562
+ exitCode: number | null
563
+ /** Sandbox status. */
564
+ status: 'running' | 'terminated'
565
+ }
566
+
567
+ type ErrorType = Gateway.request.ErrorType
568
+ }
569
+
570
+ /**
571
+ * Terminates a sandbox. The Gateway credits the unused rest of its lease back
572
+ * to the payment channel. Paid per request.
573
+ *
574
+ * @experimental
575
+ *
576
+ * @example
577
+ * ```ts
578
+ * import { Actions, Gateway } from 'viem/tempo'
579
+ *
580
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
581
+ *
582
+ * await Actions.compute.terminate(gateway, { sandboxId: sandbox.sandboxId })
583
+ * ```
584
+ *
585
+ * @param gateway - Gateway connection.
586
+ * @param parameters - Parameters.
587
+ * @returns The final status.
588
+ */
589
+ export async function terminate(
590
+ gateway: Gateway.Gateway,
591
+ parameters: terminate.Parameters,
592
+ ): Promise<terminate.ReturnValue> {
593
+ const { sandboxId, signal } = parameters
594
+ const response = await Gateway.request(gateway, {
595
+ body: JSON.stringify({ sandboxId }),
596
+ path: '/compute/terminate',
597
+ signal,
598
+ })
599
+ return (await response.json()) as terminate.ReturnValue
600
+ }
601
+
602
+ export declare namespace terminate {
603
+ type Parameters = {
604
+ /** Sandbox ID. */
605
+ sandboxId: string
606
+ /** Signal to abort the request. */
607
+ signal?: AbortSignal | undefined
608
+ }
609
+
610
+ type ReturnValue = {
611
+ /** Exit code of the sandbox, or `null`. */
612
+ exitCode: number | null
613
+ /** Amount credited back for the unused lease, in currency units. */
614
+ refunded: number
615
+ /** Sandbox ID. */
616
+ sandboxId: string
617
+ /** Sandbox status. */
618
+ status: 'terminated'
619
+ }
620
+
621
+ type ErrorType = Gateway.request.ErrorType
622
+ }
623
+
624
+ /**
625
+ * Writes a file into a sandbox at an absolute path, creating its directories.
626
+ * Up to 8 MiB. Paid per request.
627
+ *
628
+ * @experimental
629
+ *
630
+ * @example
631
+ * ```ts
632
+ * import { Actions, Gateway } from 'viem/tempo'
633
+ *
634
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
635
+ *
636
+ * await Actions.compute.write(gateway, {
637
+ * path: '/root/train.py',
638
+ * sandboxId: sandbox.sandboxId,
639
+ * value: 'print("training")',
640
+ * })
641
+ * ```
642
+ *
643
+ * @param gateway - Gateway connection.
644
+ * @param parameters - Parameters.
645
+ * @returns The path and size written.
646
+ */
647
+ export async function write(
648
+ gateway: Gateway.Gateway,
649
+ parameters: write.Parameters,
650
+ ): Promise<write.ReturnValue> {
651
+ const { path, sandboxId, signal, value } = parameters
652
+ const body =
653
+ typeof value === 'string' ? new TextEncoder().encode(value) : value
654
+ const size = isBlob(body) ? body.size : body.byteLength
655
+ const response = await Gateway.request(gateway, {
656
+ body: body as BodyInit,
657
+ headers: {
658
+ 'content-type': 'application/octet-stream',
659
+ 'gateway-path': path,
660
+ 'gateway-sandbox': sandboxId,
661
+ 'gateway-size': String(size),
662
+ },
663
+ path: '/compute/write',
664
+ signal,
665
+ })
666
+ return (await response.json()) as write.ReturnValue
667
+ }
668
+
669
+ export declare namespace write {
670
+ type Parameters = {
671
+ /** Absolute file path. */
672
+ path: string
673
+ /** Sandbox ID. */
674
+ sandboxId: string
675
+ /** Signal to abort the request. */
676
+ signal?: AbortSignal | undefined
677
+ /** File contents. */
678
+ value: Blob | Uint8Array | ArrayBuffer | string
679
+ }
680
+
681
+ type ReturnValue = {
682
+ /** Absolute file path. */
683
+ path: string
684
+ /** Bytes written. */
685
+ size: number
686
+ }
687
+
688
+ type ErrorType = Gateway.request.ErrorType
689
+ }
690
+
691
+ /**
692
+ * Pays for more seconds of a sandbox at its per-second rate, up to its
693
+ * `timeout`. A sandbox whose `paidUntil` passes is terminated within about a
694
+ * minute. Paid per request.
695
+ *
696
+ * @experimental
697
+ *
698
+ * @example
699
+ * ```ts
700
+ * import { Actions, Gateway } from 'viem/tempo'
701
+ *
702
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
703
+ *
704
+ * const { paidUntil } = await Actions.compute.renew(gateway, {
705
+ * sandboxId: sandbox.sandboxId,
706
+ * seconds: 300,
707
+ * })
708
+ * ```
709
+ *
710
+ * @param gateway - Gateway connection.
711
+ * @param parameters - Parameters.
712
+ * @returns The sandbox with its new `paidUntil`.
713
+ */
714
+ export async function renew(
715
+ gateway: Gateway.Gateway,
716
+ parameters: renew.Parameters,
717
+ ): Promise<renew.ReturnValue> {
718
+ const { sandboxId, seconds, signal } = parameters
719
+ const response = await Gateway.request(gateway, {
720
+ body: JSON.stringify({ sandboxId, seconds }),
721
+ path: '/compute/renew',
722
+ signal,
723
+ })
724
+ return (await response.json()) as renew.ReturnValue
725
+ }
726
+
727
+ export declare namespace renew {
728
+ type Parameters = {
729
+ /** Sandbox ID. */
730
+ sandboxId: string
731
+ /** Seconds to pay for. */
732
+ seconds: number
733
+ /** Signal to abort the request. */
734
+ signal?: AbortSignal | undefined
735
+ }
736
+
737
+ type ReturnValue = Sandbox
738
+
739
+ type ErrorType = Gateway.request.ErrorType
740
+ }
741
+
742
+ /**
743
+ * Runs a command in a sandbox and yields its output as it is written, then
744
+ * its exit. Up to `timeout` seconds (at most 3600). Paid per request.
745
+ *
746
+ * @experimental
747
+ *
748
+ * @example
749
+ * ```ts
750
+ * import { Actions, Gateway } from 'viem/tempo'
751
+ *
752
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
753
+ *
754
+ * for await (const event of Actions.compute.stream(gateway, {
755
+ * command: ['python', 'train.py'],
756
+ * sandboxId: sandbox.sandboxId,
757
+ * })) {
758
+ * if (event.type === 'exit') console.log('exit', event.exitCode)
759
+ * else process.stdout.write(event.data)
760
+ * }
761
+ * ```
762
+ *
763
+ * @param gateway - Gateway connection.
764
+ * @param parameters - Parameters.
765
+ * @returns Output and exit events.
766
+ */
767
+ export async function* stream(
768
+ gateway: Gateway.Gateway,
769
+ parameters: stream.Parameters,
770
+ ): AsyncGenerator<stream.Event> {
771
+ const { command, env, sandboxId, signal, timeout, workdir } = parameters
772
+ const response = await Gateway.request(gateway, {
773
+ body: JSON.stringify({ command, env, sandboxId, timeout, workdir }),
774
+ path: '/compute/stream',
775
+ signal,
776
+ })
777
+ yield* Ndjson.read<stream.Event>(response)
778
+ }
779
+
780
+ export declare namespace stream {
781
+ type Parameters = Omit<exec.Parameters, 'timeout'> & {
782
+ /**
783
+ * Command timeout in seconds, at most `limits.streamSeconds` (3600).
784
+ *
785
+ * @default 600
786
+ */
787
+ timeout?: number | undefined
788
+ }
789
+
790
+ type Event =
791
+ | {
792
+ /** Output text. */
793
+ data: string
794
+ /** Output stream. */
795
+ type: 'stderr' | 'stdout'
796
+ }
797
+ | {
798
+ /** Exit code, or `null` if the command did not exit. */
799
+ exitCode: number | null
800
+ /** Whether the command was stopped at its timeout. */
801
+ timedOut: boolean
802
+ type: 'exit'
803
+ }
804
+
805
+ type ErrorType = Gateway.request.ErrorType
806
+ }
807
+
808
+ /**
809
+ * Follows the log of a command started with `spawn` from `offset` and yields
810
+ * it as it grows, then the exit code. After an hour it yields `end` with the
811
+ * offset to resume from. Paid per request.
812
+ *
813
+ * @experimental
814
+ *
815
+ * @example
816
+ * ```ts
817
+ * import { Actions, Gateway } from 'viem/tempo'
818
+ *
819
+ * const gateway = Gateway.from({ fetch: mppx.fetch })
820
+ *
821
+ * for await (const event of Actions.compute.logs(gateway, {
822
+ * logPath: job.logPath,
823
+ * sandboxId: sandbox.sandboxId,
824
+ * })) {
825
+ * if (event.type === 'log') process.stdout.write(event.data)
826
+ * }
827
+ * ```
828
+ *
829
+ * @param gateway - Gateway connection.
830
+ * @param parameters - Parameters.
831
+ * @returns Log, exit, and end events.
832
+ */
833
+ export async function* logs(
834
+ gateway: Gateway.Gateway,
835
+ parameters: logs.Parameters,
836
+ ): AsyncGenerator<logs.Event> {
837
+ const { logPath, offset, sandboxId, signal } = parameters
838
+ const response = await Gateway.request(gateway, {
839
+ body: JSON.stringify({ logPath, offset, sandboxId }),
840
+ path: '/compute/logs',
841
+ signal,
842
+ })
843
+ yield* Ndjson.read<logs.Event>(response)
844
+ }
845
+
846
+ export declare namespace logs {
847
+ type Parameters = {
848
+ /** Log path returned by `spawn`. */
849
+ logPath: string
850
+ /**
851
+ * Byte offset to start from.
852
+ *
853
+ * @default 0
854
+ */
855
+ offset?: number | undefined
856
+ /** Sandbox ID. */
857
+ sandboxId: string
858
+ /** Signal to abort the request. */
859
+ signal?: AbortSignal | undefined
860
+ }
861
+
862
+ type Event =
863
+ | {
864
+ /** Log text. */
865
+ data: string
866
+ /** Byte offset after this chunk. */
867
+ offset: number
868
+ type: 'log'
869
+ }
870
+ | {
871
+ /** Exit code of the command. */
872
+ exitCode: number | null
873
+ /** Byte offset at the end of the log. */
874
+ offset: number
875
+ type: 'exit'
876
+ }
877
+ | {
878
+ /** Byte offset to resume from. */
879
+ offset: number
880
+ type: 'end'
881
+ }
882
+
883
+ type ErrorType = Gateway.request.ErrorType
884
+ }
885
+
886
+ /** Detects a `Blob` without `instanceof`, so ones from another realm count. */
887
+ function isBlob(value: unknown): value is Blob {
888
+ return (
889
+ typeof value === 'object' &&
890
+ value !== null &&
891
+ typeof (value as Blob).arrayBuffer === 'function' &&
892
+ typeof (value as Blob).size === 'number'
893
+ )
894
+ }