@alineo-labs/opensandbox 0.3.0 → 0.3.2

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.
package/dist/index.d.mts CHANGED
@@ -12,7 +12,7 @@ interface ImageSpec {
12
12
  uri: string;
13
13
  auth?: ImageAuth;
14
14
  }
15
- declare enum SandboxState {
15
+ export declare enum SandboxState {
16
16
  Pending = "Pending",
17
17
  Running = "Running",
18
18
  Pausing = "Pausing",
@@ -87,7 +87,7 @@ interface ListSandboxesOptions {
87
87
  limit?: number;
88
88
  offset?: number;
89
89
  }
90
- declare enum SnapshotState {
90
+ export declare enum SnapshotState {
91
91
  Pending = "Pending",
92
92
  Committing = "Committing",
93
93
  Pushing = "Pushing",
@@ -120,7 +120,7 @@ interface DiagnosticEvent {
120
120
  type: string;
121
121
  message: string;
122
122
  }
123
- declare enum SSEEventType {
123
+ export declare enum SSEEventType {
124
124
  Init = "init",
125
125
  Status = "status",
126
126
  Stdout = "stdout",
@@ -145,7 +145,7 @@ interface SSEEvent {
145
145
  execution_time?: number;
146
146
  timestamp: number;
147
147
  }
148
- declare enum CodeLanguage {
148
+ export declare enum CodeLanguage {
149
149
  Python = "python",
150
150
  JavaScript = "javascript",
151
151
  TypeScript = "typescript",
@@ -241,11 +241,15 @@ type PtyServerMessage = {
241
241
  };
242
242
  //#endregion
243
243
  //#region src/control.d.ts
244
- declare class OpenSandboxError extends Error {
244
+ export declare class OpenSandboxError extends Error {
245
245
  readonly status: number;
246
- constructor(message: string, status: number);
246
+ /** OpenSandbox's error code, e.g. `DOCKER::SANDBOX_NOT_FOUND`, when the response carried one. */
247
+ readonly code?: string | undefined;
248
+ constructor(message: string, status: number,
249
+ /** OpenSandbox's error code, e.g. `DOCKER::SANDBOX_NOT_FOUND`, when the response carried one. */
250
+ code?: string | undefined);
247
251
  }
248
- declare class ControlClient {
252
+ export declare class ControlClient {
249
253
  private baseUrl;
250
254
  private apiKey;
251
255
  private signal?;
@@ -258,12 +262,24 @@ declare class ControlClient {
258
262
  withSignal(signal: AbortSignal): ControlClient;
259
263
  private request;
260
264
  createSandbox(options: CreateSandboxOptions): Promise<Sandbox>;
265
+ /**
266
+ * Every sandbox, optionally filtered by state. OpenSandbox paginates with `page`/`pageSize`
267
+ * (default 20, max 200) and ignores `limit`/`offset`, so this walks every page and applies
268
+ * `offset`/`limit` itself. Sending `limit`/`offset` as query parameters silently capped every
269
+ * listing at the server's first 20.
270
+ */
261
271
  listSandboxes(options?: ListSandboxesOptions): Promise<Sandbox[]>;
262
272
  getSandbox(id: string): Promise<Sandbox>;
263
273
  deleteSandbox(id: string): Promise<void>;
264
274
  pauseSandbox(id: string): Promise<void>;
265
275
  resumeSandbox(id: string): Promise<void>;
266
- renewExpiration(id: string): Promise<void>;
276
+ /**
277
+ * Move a sandbox's expiry to `expiresAt`, which must be in the future and later than its current
278
+ * expiry. Only meaningful for a sandbox created with a `timeout`: one created without it never
279
+ * expires (OpenSandbox's `CreateSandboxRequest.timeout` — "when omitted or null, the sandbox will
280
+ * not auto-terminate"). The countdown keeps running while a sandbox is paused.
281
+ */
282
+ renewExpiration(id: string, expiresAt: Date | string): Promise<void>;
267
283
  getEndpoint(sandboxId: string, port: number, useServerProxy?: boolean): Promise<SandboxEndpoint>;
268
284
  getDiagnosticLogs(sandboxId: string): Promise<DiagnosticLog[]>;
269
285
  getDiagnosticEvents(sandboxId: string): Promise<DiagnosticEvent[]>;
@@ -275,7 +291,7 @@ declare class ControlClient {
275
291
  //#endregion
276
292
  //#region src/egress.d.ts
277
293
  /** Thrown for a non-2xx response from the egress sidecar's policy API. */
278
- declare class EgressClientError extends Error {
294
+ export declare class EgressClientError extends Error {
279
295
  readonly status: number;
280
296
  constructor(message: string, status: number);
281
297
  }
@@ -309,7 +325,7 @@ interface EgressPolicyStatus {
309
325
  * `resume()`d sandbox's still-live changes back into its boot policy from the ledger. (A
310
326
  * `fork()` does not carry them.)
311
327
  */
312
- declare class EgressClient {
328
+ export declare class EgressClient {
313
329
  private readonly control;
314
330
  private readonly useServerProxy?;
315
331
  private static readonly PORT;
@@ -329,10 +345,10 @@ declare class EgressClient {
329
345
  * wildcard domain, a bare IPv4/IPv6 address, or a CIDR block. Whitespace-only, URL-shaped
330
346
  * (`http://…`), space-containing, or otherwise clearly-malformed strings return `false`.
331
347
  */
332
- declare function isValidEgressTarget(target: string): boolean;
348
+ export declare function isValidEgressTarget(target: string): boolean;
333
349
  //#endregion
334
350
  //#region src/exec.d.ts
335
- declare class ExecClient {
351
+ export declare class ExecClient {
336
352
  private baseUrl;
337
353
  private accessToken;
338
354
  private signal?;
@@ -402,7 +418,7 @@ type PtyExitListener = (exitCode: number) => void;
402
418
  * callbacks, `write()`/`resize()`/`signal()` send input, `close()` tears
403
419
  * down the socket.
404
420
  */
405
- declare class PtyClient {
421
+ export declare class PtyClient {
406
422
  private readonly baseUrl;
407
423
  private readonly accessToken;
408
424
  private ws;
@@ -424,4 +440,4 @@ declare class PtyClient {
424
440
  close(): void;
425
441
  }
426
442
  //#endregion
427
- export { type CodeContext, CodeLanguage, type CommandStatus, ControlClient, type CreatePtyOptions, type CreatePtyResponse, type CreateSandboxOptions, type CreateSessionRequest, type CreateSessionResponse, type CredentialProxyConfig, type DiagnosticEvent, type DiagnosticLog, EgressClient, EgressClientError, type EgressPolicyStatus, ExecClient, type ExecuteCodeOptions, type ExecuteCommandOptions, type FileInfo, type FileReplacement, type ImageAuth, type ImageSpec, type ListSandboxesOptions, type ListSnapshotsOptions, type Metrics, type NetworkPolicy, type NetworkRule, OpenSandboxError, PtyClient, type PtyClientMessage, type PtyExitListener, type PtyOutputListener, type PtyServerMessage, type Resources, type RunInSessionRequest, type SSEEvent, SSEEventType, type Sandbox, type SandboxEndpoint, SandboxState, type SandboxStatus, type Snapshot, SnapshotState, isValidEgressTarget };
443
+ export type { CodeContext, CommandStatus, CreatePtyOptions, CreatePtyResponse, CreateSandboxOptions, CreateSessionRequest, CreateSessionResponse, CredentialProxyConfig, DiagnosticEvent, DiagnosticLog, EgressPolicyStatus, ExecuteCodeOptions, ExecuteCommandOptions, FileInfo, FileReplacement, ImageAuth, ImageSpec, ListSandboxesOptions, ListSnapshotsOptions, Metrics, NetworkPolicy, NetworkRule, PtyClientMessage, PtyExitListener, PtyOutputListener, PtyServerMessage, Resources, RunInSessionRequest, SSEEvent, Sandbox, SandboxEndpoint, SandboxStatus, Snapshot };
package/dist/index.mjs CHANGED
@@ -9,12 +9,29 @@ function flattenSnapshot(raw) {
9
9
  }
10
10
  var OpenSandboxError = class extends Error {
11
11
  status;
12
- constructor(message, status) {
12
+ code;
13
+ constructor(message, status, code) {
13
14
  super(message);
14
15
  this.status = status;
16
+ this.code = code;
15
17
  this.name = "OpenSandboxError";
16
18
  }
17
19
  };
20
+ /**
21
+ * OpenSandbox answers an error with a JSON body, `{"code": "...", "message": "..."}`. Put the
22
+ * sentence in `message` (with the code after it), keep the code on `.code`, and fall back to the
23
+ * raw text when the body isn't that shape.
24
+ */
25
+ function errorFromBody(text, status) {
26
+ try {
27
+ const body = JSON.parse(text);
28
+ if (typeof body?.message === "string" && body.message) {
29
+ const code = typeof body.code === "string" && body.code ? body.code : void 0;
30
+ return new OpenSandboxError(code ? `${body.message} (${code})` : body.message, status, code);
31
+ }
32
+ } catch {}
33
+ return new OpenSandboxError(text || "OpenSandbox API error", status);
34
+ }
18
35
  var ControlClient = class ControlClient {
19
36
  baseUrl;
20
37
  apiKey;
@@ -42,20 +59,33 @@ var ControlClient = class ControlClient {
42
59
  ...body !== void 0 ? { body: JSON.stringify(body) } : {},
43
60
  signal: this.signal
44
61
  });
45
- if (!res.ok) throw new OpenSandboxError(await res.text().catch(() => "") || "OpenSandbox API error", res.status);
62
+ if (!res.ok) throw errorFromBody(await res.text().catch(() => ""), res.status);
46
63
  if (res.status === 204) return void 0;
47
64
  return res.json();
48
65
  }
49
66
  createSandbox(options) {
50
67
  return this.request("POST", "/v1/sandboxes", options);
51
68
  }
69
+ /**
70
+ * Every sandbox, optionally filtered by state. OpenSandbox paginates with `page`/`pageSize`
71
+ * (default 20, max 200) and ignores `limit`/`offset`, so this walks every page and applies
72
+ * `offset`/`limit` itself. Sending `limit`/`offset` as query parameters silently capped every
73
+ * listing at the server's first 20.
74
+ */
52
75
  async listSandboxes(options = {}) {
53
- const params = new URLSearchParams();
54
- if (options.state) params.set("state", options.state);
55
- if (options.limit !== void 0) params.set("limit", String(options.limit));
56
- if (options.offset !== void 0) params.set("offset", String(options.offset));
57
- const qs = params.toString();
58
- return (await this.request("GET", `/v1/sandboxes${qs ? `?${qs}` : ""}`)).items;
76
+ const all = [];
77
+ for (let page = 1;; page++) {
78
+ const params = new URLSearchParams({
79
+ page: String(page),
80
+ pageSize: "200"
81
+ });
82
+ if (options.state) params.set("state", options.state);
83
+ const res = await this.request("GET", `/v1/sandboxes?${params}`);
84
+ all.push(...res.items);
85
+ if (!res.pagination?.hasNextPage) break;
86
+ }
87
+ const start = options.offset ?? 0;
88
+ return all.slice(start, options.limit === void 0 ? void 0 : start + options.limit);
59
89
  }
60
90
  getSandbox(id) {
61
91
  return this.request("GET", `/v1/sandboxes/${id}`);
@@ -69,8 +99,15 @@ var ControlClient = class ControlClient {
69
99
  resumeSandbox(id) {
70
100
  return this.request("POST", `/v1/sandboxes/${id}/resume`);
71
101
  }
72
- renewExpiration(id) {
73
- return this.request("POST", `/v1/sandboxes/${id}/renew-expiration`);
102
+ /**
103
+ * Move a sandbox's expiry to `expiresAt`, which must be in the future and later than its current
104
+ * expiry. Only meaningful for a sandbox created with a `timeout`: one created without it never
105
+ * expires (OpenSandbox's `CreateSandboxRequest.timeout` — "when omitted or null, the sandbox will
106
+ * not auto-terminate"). The countdown keeps running while a sandbox is paused.
107
+ */
108
+ renewExpiration(id, expiresAt) {
109
+ const at = typeof expiresAt === "string" ? expiresAt : expiresAt.toISOString();
110
+ return this.request("POST", `/v1/sandboxes/${id}/renew-expiration`, { expiresAt: at });
74
111
  }
75
112
  getEndpoint(sandboxId, port, useServerProxy) {
76
113
  const qs = useServerProxy ? "?use_server_proxy=true" : "";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/opensandbox",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -30,9 +30,9 @@
30
30
  "test:watch": "vitest"
31
31
  },
32
32
  "devDependencies": {
33
- "bun-types": "1.3.14",
34
- "tsdown": "0.22.3",
33
+ "bun-types": "1.4.2",
34
+ "tsdown": "0.23.0",
35
35
  "typescript": "6.0.3",
36
- "vitest": "4.1.9"
36
+ "vitest": "5.0.0"
37
37
  }
38
38
  }