@watasu/sdk 0.1.0 → 0.1.4

package/README.md

@@ -0,0 +1,29 @@
+# Watasu TypeScript SDK
+
+TypeScript SDK for Watasu.
+
+## Install
+
+```bash
+npm install @watasu/sdk
+```
+
+Set `WATASU_API_KEY` before using the SDK.
+
+## Usage
+
+```ts
+import { Sandbox } from '@watasu/sdk'
+
+const sbx = await Sandbox.create()
+await sbx.files.write('/home/user/a.js', 'console.log(2 + 2)')
+const result = await sbx.commands.run('node /home/user/a.js')
+console.log(result.stdout)
+console.log(await sbx.isRunning())
+await sbx.kill()
+```
+
+`Sandbox.create` and `Sandbox.connect` return only after the Watasu API supplies
+a usable data-plane session. The SDK does not poll sandbox readiness.
+
+The SDK is ESM-first and ships TypeScript declarations.

package/dist/connectionConfig.d.ts

@@ -3,6 +3,7 @@ export declare const SESSION_OPERATION_REQUEST_TIMEOUT_MS = 150000;
 /** Connection options accepted by Watasu SDK entrypoints. */
 export interface ConnectionOpts {
     apiKey?: string;
+    accessToken?: string;
     domain?: string;
     apiUrl?: string;
     dataPlaneDomain?: string;

package/dist/connectionConfig.js

@@ -11,7 +11,10 @@ export class ConnectionConfig {
     proxy;
     constructor(opts = {}) {
         const env = typeof process !== 'undefined' ? process.env : {};
-        this.apiKey = opts.apiKey ?? env.WATASU_API_KEY;
+        this.apiKey =
+            opts.apiKey ??
+                opts.accessToken ??
+                env.WATASU_API_KEY;
         this.domain = opts.domain ?? env.WATASU_DOMAIN ?? 'watasu.io';
         this.apiUrl =
             opts.apiUrl ?? env.WATASU_API_URL ?? `https://api.${this.domain}/v1`;

package/dist/sandbox.d.ts

@@ -11,14 +11,7 @@ export interface SandboxCreateOpts extends ConnectionOpts {
     envs?: Record<string, string>;
     secure?: boolean;
     allowInternetAccess?: boolean;
-    templateVersionId?: number | string;
     team?: string;
-    cpu?: number;
-    memoryMb?: number;
-    diskMb?: number;
-    networkClass?: string;
-    allowPackageRegistryAccess?: boolean;
-    exposedPorts?: unknown[];
     mcp?: unknown;
     volumeMounts?: unknown;
 }
@@ -28,7 +21,8 @@ export interface SandboxConnectOpts extends ConnectionOpts {
 }
 export interface SandboxInfo {
     sandboxId: string;
-    templateVersionId?: number;
+    templateId?: string;
+    name?: string;
     state?: string;
     metadata: Record<string, string>;
     startedAt?: string;
@@ -49,6 +43,7 @@ export declare class Sandbox {
     };
     private readonly config;
     private readonly control;
+    private readonly envs;
     private dataPlane;
     private sandbox;
     constructor(opts: {
@@ -69,6 +64,8 @@ export declare class Sandbox {
     static kill(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy this sandbox. */
     kill(): Promise<boolean>;
+    /** Check if this sandbox is in a runtime-active lifecycle state. */
+    isRunning(opts?: Pick<ConnectionOpts, 'requestTimeoutMs'>): Promise<boolean>;
     /** Set a sandbox's lifetime by id. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /** Set this sandbox's lifetime. */
@@ -82,7 +79,7 @@ export declare class Sandbox {
         team?: string;
     }): Promise<SandboxInfo[]>;
     /** Return the public hostname for an exposed sandbox port. */
-    getHost(port: number): Promise<string>;
+    getHost(port: number): string;
     pause(): never;
     resume(): never;
     createSnapshot(): never;

package/dist/sandbox.js

@@ -1,7 +1,7 @@
 import { Commands } from './commands.js';
 import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
 import { DataPlaneClient, ControlClient } from './transport.js';
-import { SandboxError, unsupported } from './errors.js';
+import { NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export class Sandbox {
@@ -14,17 +14,19 @@ export class Sandbox {
     git = { clone: () => unsupported('sandbox.git') };
     config;
     control;
+    envs;
     dataPlane;
     sandbox;
     constructor(opts) {
         this.sandboxId = String(opts.sandboxId);
         this.config = opts.connectionConfig;
         this.control = opts.control ?? new ControlClient(this.config);
+        this.envs = opts.envs ?? {};
         this.sandbox = opts.sandbox ?? {};
         const dataPlane = dataPlaneFromSession(opts.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
-        this.commands = new Commands(dataPlane, this.config, opts.envs ?? {});
+        this.commands = new Commands(dataPlane, this.config, this.envs);
     }
     /** Create a sandbox and return it only after the API supplies a data-plane session. */
     static async create(templateOrOpts, opts = {}) {
@@ -39,21 +41,16 @@ export class Sandbox {
         const config = new ConnectionConfig(sandboxOpts);
         const control = new ControlClient(config);
         const sandboxPayload = {
-            template,
-            timeout_seconds: Math.ceil((sandboxOpts.timeoutMs ?? 300_000) / 1000),
+            template_id: template,
+            timeout: Math.ceil((sandboxOpts.timeoutMs ?? 300_000) / 1000),
             metadata: sandboxOpts.metadata ?? {},
+            env_vars: sandboxOpts.envs ?? {},
+            secure: sandboxOpts.secure ?? true,
             allow_internet_access: sandboxOpts.allowInternetAccess ?? true,
         };
-        putIfPresent(sandboxPayload, 'template_version_id', sandboxOpts.templateVersionId);
         putIfPresent(sandboxPayload, 'team', sandboxOpts.team);
-        putIfPresent(sandboxPayload, 'cpu', sandboxOpts.cpu);
-        putIfPresent(sandboxPayload, 'memory_mb', sandboxOpts.memoryMb);
-        putIfPresent(sandboxPayload, 'disk_mb', sandboxOpts.diskMb);
-        putIfPresent(sandboxPayload, 'network_class', sandboxOpts.networkClass);
-        putIfPresent(sandboxPayload, 'allow_package_registry_access', sandboxOpts.allowPackageRegistryAccess);
-        putIfPresent(sandboxPayload, 'exposed_ports', sandboxOpts.exposedPorts);
         const response = await control.post('/sandboxes', {
-            json: { sandbox: sandboxPayload },
+            json: sandboxPayload,
             requestTimeoutMs: sessionOperationRequestTimeout(config, sandboxOpts),
         });
         const sandbox = record(response.sandbox ?? response);
@@ -75,7 +72,7 @@ export class Sandbox {
         const control = new ControlClient(config);
         const info = await control.get(`/sandboxes/${sandboxId}`);
         const response = await control.post(`/sandboxes/${sandboxId}/connect`, {
-            json: { connect: opts.timeoutMs ? { timeout_seconds: Math.ceil(opts.timeoutMs / 1000) } : {} },
+            json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
         });
         return new Sandbox({
@@ -89,14 +86,14 @@ export class Sandbox {
     /** Refresh this sandbox's data-plane session in place. */
     async connect(opts = {}) {
         const response = await this.control.post(`/sandboxes/${this.sandboxId}/connect`, {
-            json: { connect: opts.timeoutMs ? { timeout_seconds: Math.ceil(opts.timeoutMs / 1000) } : {} },
+            json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(this.config, opts),
         });
         this.sandbox = record(response.sandbox ?? this.sandbox);
         const dataPlane = dataPlaneFromSession(response.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
-        this.commands = new Commands(dataPlane, this.config);
+        this.commands = new Commands(dataPlane, this.config, this.envs);
         return this;
     }
     /** Destroy a sandbox by id. */
@@ -110,17 +107,32 @@ export class Sandbox {
         await this.control.delete(`/sandboxes/${this.sandboxId}`);
         return true;
     }
+    /** Check if this sandbox is in a runtime-active lifecycle state. */
+    async isRunning(opts = {}) {
+        try {
+            const payload = await this.control.get(`/sandboxes/${this.sandboxId}`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            const item = record(payload.sandbox ?? payload);
+            return ['creating', 'ready', 'checkpointing', 'restoring', 'stopping'].includes(String(item.state ?? ''));
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return false;
+            throw error;
+        }
+    }
     /** Set a sandbox's lifetime by id. */
     static async setTimeout(sandboxId, timeoutMs, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
-        await control.patch(`/sandboxes/${sandboxId}`, {
-            json: { sandbox: { timeout_seconds: Math.ceil(timeoutMs / 1000) } },
+        await control.post(`/sandboxes/${sandboxId}/timeout`, {
+            json: { timeout: Math.ceil(timeoutMs / 1000) },
         });
     }
     /** Set this sandbox's lifetime. */
     async setTimeout(timeoutMs) {
-        await this.control.patch(`/sandboxes/${this.sandboxId}`, {
-            json: { sandbox: { timeout_seconds: Math.ceil(timeoutMs / 1000) } },
+        await this.control.post(`/sandboxes/${this.sandboxId}/timeout`, {
+            json: { timeout: Math.ceil(timeoutMs / 1000) },
         });
     }
     /** Fetch control-plane metadata for a sandbox by id. */
@@ -142,13 +154,10 @@ export class Sandbox {
         return sandboxes.map((item) => sandboxInfo(record(item)));
     }
     /** Return the public hostname for an exposed sandbox port. */
-    async getHost(port) {
-        const payload = await this.control.get(`/sandboxes/${this.sandboxId}/ports/${port}`);
-        const portInfo = record(payload.sandbox_port ?? payload.port ?? payload);
-        const value = portInfo.host ?? portInfo.url;
-        if (typeof value === 'string')
-            return hostOnly(value);
-        const routeToken = this.sandbox.route_token;
+    getHost(port) {
+        const routeToken = this.sandbox.route_token ??
+            this.sandbox.routeToken ??
+            routeTokenFromDataPlaneUrl(this.dataPlane.baseUrl, this.config.dataPlaneDomain);
         if (typeof routeToken !== 'string')
             throw new SandboxError('port response did not include host or url');
         return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
@@ -178,13 +187,22 @@ function sessionOperationRequestTimeout(config, opts) {
 function sandboxInfo(payload) {
     return {
         sandboxId: String(payload.id ?? payload.sandbox_id ?? ''),
-        templateVersionId: typeof payload.template_version_id === 'number' ? payload.template_version_id : undefined,
+        templateId: typeof payload.template_id === 'string' ? payload.template_id : templateSlug(payload.template),
+        name: typeof payload.name === 'string' ? payload.name : undefined,
         state: typeof payload.state === 'string' ? payload.state : undefined,
         metadata: recordOfStrings(payload.metadata),
-        startedAt: typeof payload.created_at === 'string' ? payload.created_at : undefined,
-        endAt: typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
+        startedAt: typeof payload.started_at === 'string'
+            ? payload.started_at
+            : typeof payload.created_at === 'string' ? payload.created_at : undefined,
+        endAt: typeof payload.end_at === 'string'
+            ? payload.end_at
+            : typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
     };
 }
+function templateSlug(value) {
+    const template = record(value);
+    return typeof template.slug === 'string' ? template.slug : undefined;
+}
 function putIfPresent(target, key, value) {
     if (value !== undefined && value !== null)
         target[key] = value;
@@ -202,3 +220,11 @@ function hostOnly(value) {
         return new URL(value).host;
     return value.split('/')[0];
 }
+function routeTokenFromDataPlaneUrl(value, dataPlaneDomain) {
+    const host = hostOnly(value);
+    const suffix = `.sandbox.${dataPlaneDomain}`;
+    if (!host.endsWith(suffix))
+        return undefined;
+    const token = host.slice(0, -suffix.length);
+    return token || undefined;
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "type": "module",
   "license": "MIT OR Apache-2.0",
-  "description": "TypeScript SDK for Watasu sandboxes",
+  "description": "TypeScript SDK for Watasu",
   "publishConfig": {
     "access": "public"
   },