@watasu/sdk 0.1.25 → 0.1.40

package/dist/sandbox.js

@@ -1,6 +1,6 @@
 import { Commands } from './commands.js';
 import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
-import { DataPlaneClient, ControlClient } from './transport.js';
+import { DataPlaneClient, ControlClient, withQuery } from './transport.js';
 import { ConflictError, FileNotFoundError, NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
 import { Git } from './git.js';
@@ -24,6 +24,7 @@ export class SnapshotPaginator {
         const control = new ControlClient(config);
         const payload = await control.get(snapshotListPath(this.opts, this.nextToken), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
         this.hasNext = this.nextToken !== undefined;
@@ -57,6 +58,7 @@ export class SandboxPaginator {
         const control = new ControlClient(config);
         const payload = await control.get(sandboxListPath(this.opts, this.nextToken), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
         this.hasNext = this.nextToken !== undefined;
@@ -80,14 +82,12 @@ export class Sandbox {
     /** Default sandbox lifetime in milliseconds. */
     static defaultSandboxTimeoutMs = 300_000;
     files;
-    filesystem;
     commands;
     process;
     pty;
     terminal;
     git;
     cwd;
-    envVars;
     sandboxId;
     mcpPort = 50005;
     mcpToken;
@@ -101,12 +101,10 @@ export class Sandbox {
         this.config = opts.connectionConfig;
         this.control = opts.control ?? new ControlClient(this.config);
         this.envs = opts.envs ?? {};
-        this.envVars = this.envs;
         this.sandbox = opts.sandbox ?? {};
         const dataPlane = dataPlaneFromSession(opts.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
-        this.filesystem = this.files;
         this.commands = new Commands(dataPlane, this.config, this.envs);
         this.process = new ProcessManager(this.commands);
         this.pty = new Pty(dataPlane, this.config);
@@ -123,8 +121,6 @@ export class Sandbox {
         const template = typeof templateOrOpts === 'string'
             ? templateOrOpts
             : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? this.defaultTemplate : undefined);
-        if (sandboxOpts.volumeMounts !== undefined)
-            unsupported('volumeMounts');
         const config = new ConnectionConfig(sandboxOpts);
         const control = new ControlClient(config);
         const sandboxPayload = {
@@ -136,11 +132,14 @@ export class Sandbox {
         };
         putIfPresent(sandboxPayload, 'template_id', template);
         putIfPresent(sandboxPayload, 'mcp', sandboxOpts.mcp);
+        putIfPresent(sandboxPayload, 'lifecycle', lifecyclePayload(sandboxOpts.lifecycle));
+        putIfPresent(sandboxPayload, 'volume_mounts', volumeMountsPayload(sandboxOpts.volumeMounts));
         Object.assign(sandboxPayload, networkUpdatePayload(sandboxOpts.network));
         putIfPresent(sandboxPayload, 'team', sandboxOpts.team);
         const response = await control.post('/sandboxes', {
             json: sandboxPayload,
             requestTimeoutMs: sessionOperationRequestTimeout(config, sandboxOpts),
+            signal: sandboxOpts.signal,
         });
         const sandbox = record(response.sandbox ?? response);
         const sandboxId = sandbox.id ?? sandbox.sandbox_id;
@@ -160,10 +159,14 @@ export class Sandbox {
     static async connect(sandboxId, opts = {}) {
         const config = new ConnectionConfig(opts);
         const control = new ControlClient(config);
-        const info = await control.get(`/sandboxes/${sandboxId}`);
+        const info = await control.get(`/sandboxes/${sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         const response = await control.post(`/sandboxes/${sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
+            signal: opts.signal,
         });
         return new this({
             sandboxId,
@@ -173,22 +176,17 @@ export class Sandbox {
             sandbox: record(response.sandbox ?? info.sandbox ?? {}),
         });
     }
-    static async reconnect(sandboxOrOpts, opts = {}) {
-        if (typeof sandboxOrOpts === 'string')
-            return this.connect(sandboxOrOpts, opts);
-        return this.connect(sandboxOrOpts.sandboxID, sandboxOrOpts);
-    }
     /** Refresh this sandbox's data-plane session in place. */
     async connect(opts = {}) {
         const response = await this.control.post(`/sandboxes/${this.sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(this.config, opts),
+            signal: opts.signal,
         });
         this.sandbox = record(response.sandbox ?? this.sandbox);
         const dataPlane = dataPlaneFromSession(response.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
-        this.filesystem = this.files;
         this.commands = new Commands(dataPlane, this.config, this.envs);
         this.process = new ProcessManager(this.commands);
         this.pty = new Pty(dataPlane, this.config);
@@ -207,6 +205,7 @@ export class Sandbox {
         try {
             await control.post(`/sandboxes/${sandboxId}/pause`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
+                signal: opts.signal,
             });
             return true;
         }
@@ -216,21 +215,26 @@ export class Sandbox {
             throw error;
         }
     }
-    /** Alias for `betaPause`. */
+    /** Pause a sandbox by id. */
     static async pause(sandboxId, opts = {}) {
         return this.betaPause(sandboxId, opts);
     }
     /** Destroy a sandbox by id. */
     static async kill(sandboxId, opts = {}) {
+        const requestOpts = typeof opts === 'string' ? {} : opts;
         const control = new ControlClient(new ConnectionConfig(typeof opts === 'string' ? { apiKey: opts } : opts));
-        await control.delete(`/sandboxes/${sandboxId}`);
+        await control.delete(`/sandboxes/${sandboxId}`, {
+            requestTimeoutMs: requestOpts.requestTimeoutMs,
+            signal: requestOpts.signal,
+        });
         return true;
     }
     /** Fetch sandbox metrics by id. */
     static async getMetrics(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
-        const payload = await control.get(`/sandboxes/${sandboxId}/metrics`, {
+        const payload = await control.get(metricsPath(sandboxId, opts), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return metricsList(payload.metrics ?? payload);
     }
@@ -243,19 +247,17 @@ export class Sandbox {
         const response = await control.put(`/sandboxes/${sandboxId}/network`, {
             json: networkUpdatePayload(network),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return response.sandbox === undefined ? undefined : record(response.sandbox);
     }
-    /** Deprecated alias for `getInfo`. */
-    static async getFullInfo(sandboxId, opts = {}) {
-        return this.getInfo(sandboxId, opts);
-    }
     /** Create a Watasu checkpoint using snapshot naming. */
     static async createSnapshot(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
         const payload = await control.post(`/sandboxes/${sandboxId}/snapshots`, {
             json: snapshotPayload(opts),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return snapshotInfo(record(payload.sandbox_checkpoint ?? payload.snapshot ?? payload));
     }
@@ -269,6 +271,7 @@ export class Sandbox {
         try {
             await control.delete(`/sandbox_snapshots/${snapshotId}`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
+                signal: opts.signal,
             });
             return true;
         }
@@ -279,8 +282,11 @@ export class Sandbox {
         }
     }
     /** Destroy this sandbox. */
-    async kill() {
-        await this.control.delete(`/sandboxes/${this.sandboxId}`);
+    async kill(opts = {}) {
+        await this.control.delete(`/sandboxes/${this.sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         return true;
     }
     /** Check if this sandbox is in a runtime-active lifecycle state. */
@@ -288,6 +294,7 @@ export class Sandbox {
         try {
             const payload = await this.control.get(`/sandboxes/${this.sandboxId}`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
+                signal: opts.signal,
             });
             const item = record(payload.sandbox ?? payload);
             return ['creating', 'ready', 'checkpointing', 'restoring', 'stopping'].includes(String(item.state ?? ''));
@@ -303,27 +310,33 @@ export class Sandbox {
         const control = new ControlClient(new ConnectionConfig(opts));
         await control.post(`/sandboxes/${sandboxId}/timeout`, {
             json: { timeout: Math.ceil(timeoutMs / 1000) },
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
     /** Set this sandbox's lifetime. */
-    async setTimeout(timeoutMs) {
+    async setTimeout(timeoutMs, opts = {}) {
         await this.control.post(`/sandboxes/${this.sandboxId}/timeout`, {
             json: { timeout: Math.ceil(timeoutMs / 1000) },
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
-    /** Keep the sandbox alive for `duration` milliseconds. */
-    async keepAlive(duration) {
-        await this.setTimeout(duration);
-    }
     /** Fetch control-plane metadata for a sandbox by id. */
     static async getInfo(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
-        const payload = await control.get(`/sandboxes/${sandboxId}`);
+        const payload = await control.get(`/sandboxes/${sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         return sandboxInfo(record(payload.sandbox ?? payload));
     }
     /** Fetch the latest control-plane metadata for this sandbox. */
-    async getInfo() {
-        const payload = await this.control.get(`/sandboxes/${this.sandboxId}`);
+    async getInfo(opts = {}) {
+        const payload = await this.control.get(`/sandboxes/${this.sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         return sandboxInfo(record(payload.sandbox ?? payload));
     }
     /** Fetch latest sandbox metrics. */
@@ -355,13 +368,12 @@ export class Sandbox {
         if (checkpointId === undefined)
             throw new SandboxError('checkpointId or snapshotId is required');
         const payload = { checkpoint_id: checkpointId };
-        if (restoreOpts.timeout !== undefined)
-            payload.timeout_seconds = restoreOpts.timeout;
         if (restoreOpts.timeoutMs !== undefined)
             payload.timeout_seconds = Math.ceil(restoreOpts.timeoutMs / 1000);
         const response = await this.control.post(`/sandboxes/${this.sandboxId}/restore`, {
             json: payload,
             requestTimeoutMs: restoreOpts.requestTimeoutMs,
+            signal: restoreOpts.signal,
         });
         return sandboxInfo(record(response.sandbox ?? response));
     }
@@ -379,12 +391,6 @@ export class Sandbox {
             throw new SandboxError('port response did not include host or url');
         return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
     }
-    /** Return the public hostname for the sandbox or an exposed sandbox port. */
-    getHostname(port) {
-        if (port !== undefined)
-            return this.getHost(port);
-        return new URL(this.dataPlane.baseUrl).host;
-    }
     /** Return the conventional MCP URL for this sandbox. */
     getMcpUrl() {
         return `https://${this.getHost(this.mcpPort)}/mcp`;
@@ -404,12 +410,6 @@ export class Sandbox {
             throw error;
         }
     }
-    /** Return a protocol string for a secure or insecure sandbox URL. */
-    getProtocol(baseProtocol = 'http', secure = true) {
-        return `${baseProtocol}${secure ? 's' : ''}`;
-    }
-    /** Close the local SDK attachment. This does not destroy the sandbox. */
-    async close() { }
     /** Get a signed URL that accepts a POST upload for a sandbox file path. */
     async uploadUrl(path = '', opts = {}) {
         const fileUrl = await this.fileUrl('/upload_url', path, opts);
@@ -437,7 +437,7 @@ export class Sandbox {
     async betaPause(opts = {}) {
         return Sandbox.betaPause(this.sandboxId, { ...this.configOptions(), ...opts });
     }
-    /** Alias for `betaPause`. */
+    /** Pause this sandbox. Returns false when it was already paused. */
     async pause(opts = {}) {
         return this.betaPause(opts);
     }
@@ -455,6 +455,7 @@ export class Sandbox {
                 expires_in_seconds: opts.expiresInSeconds,
             }),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return fileUrlInfo(record(payload.file_url ?? payload));
     }
@@ -463,21 +464,42 @@ export class Sandbox {
         return this.dataPlane.postJson(path, {
             json,
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
+    }
+    /** GET JSON from the sandbox data-plane runtime API. */
+    async runtimeGetJson(path, opts = {}) {
+        return this.dataPlane.getJson(path, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
+    }
+    /** DELETE JSON from the sandbox data-plane runtime API. */
+    async runtimeDeleteJson(path, opts = {}) {
+        return this.dataPlane.deleteJson(path, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
     configOptions() {
         return {
             apiKey: this.config.apiKey,
             apiUrl: this.config.apiUrl,
+            sandboxUrl: this.config.sandboxUrl,
             dataPlaneDomain: this.config.dataPlaneDomain,
             requestTimeoutMs: this.config.requestTimeoutMs,
+            headers: this.config.headers,
+            apiHeaders: this.config.apiHeaders,
+            debug: this.config.debug,
+            signal: this.config.signal,
+            proxy: this.config.proxy,
         };
     }
 }
 function dataPlaneFromSession(session, config) {
     const item = record(session);
     const token = item.token ?? item.access_token;
-    const url = item.data_plane_url;
+    const url = config.sandboxUrl ?? item.data_plane_url;
     if (!session)
         throw new SandboxError('sandbox session is required for data-plane operations');
     if (typeof token !== 'string' || typeof url !== 'string') {
@@ -487,8 +509,8 @@ function dataPlaneFromSession(session, config) {
 }
 function sandboxListPath(opts, nextToken) {
     const params = new URLSearchParams();
-    if (opts.team)
-        params.set('team', opts.team);
+    if (opts.team !== undefined)
+        params.set('team', String(opts.team));
     if (opts.limit !== undefined)
         params.set('limit', String(opts.limit));
     if (nextToken)
@@ -515,6 +537,15 @@ function snapshotListPath(opts, nextToken) {
     const query = params.toString();
     return query ? `/sandbox_snapshots?${query}` : '/sandbox_snapshots';
 }
+function metricsPath(sandboxId, opts) {
+    return withQuery(`/sandboxes/${sandboxId}/metrics`, {
+        start: dateTimestampSeconds(opts.start),
+        end: dateTimestampSeconds(opts.end),
+    });
+}
+function dateTimestampSeconds(value) {
+    return value === undefined ? undefined : Math.round(value.getTime() / 1000);
+}
 function fileUrlInfo(payload) {
     return {
         method: String(payload.method ?? ''),
@@ -538,6 +569,8 @@ function sandboxInfo(payload) {
         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,
+        lifecycle: sandboxLifecycleInfo(payload.lifecycle),
+        volumeMounts: volumeMountsInfo(payload.volume_mounts ?? payload.volumeMounts),
         metadata: recordOfStrings(payload.metadata),
         startedAt: typeof payload.started_at === 'string'
             ? payload.started_at
@@ -547,6 +580,45 @@ function sandboxInfo(payload) {
             : typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
     };
 }
+function lifecyclePayload(lifecycle) {
+    if (lifecycle === undefined)
+        return undefined;
+    const onTimeout = lifecycle.onTimeout ?? 'kill';
+    const autoResume = lifecycle.autoResume ?? false;
+    if (autoResume && onTimeout !== 'pause') {
+        throw new SandboxError("lifecycle.autoResume can only be true when lifecycle.onTimeout is 'pause'");
+    }
+    return { on_timeout: onTimeout, auto_resume: autoResume };
+}
+function volumeMountsPayload(volumeMounts) {
+    if (volumeMounts === undefined)
+        return undefined;
+    return Object.entries(volumeMounts).map(([path, volume]) => ({
+        path,
+        name: typeof volume === 'string' ? volume : volume.name,
+    }));
+}
+function volumeMountsInfo(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .map((item) => {
+        const entry = record(item);
+        return { name: String(entry.name ?? ''), path: String(entry.path ?? '') };
+    })
+        .filter((entry) => entry.name !== '' && entry.path !== '');
+}
+function sandboxLifecycleInfo(value) {
+    const lifecycle = record(value);
+    const onTimeout = stringValue(lifecycle.on_timeout ?? lifecycle.onTimeout);
+    const autoResume = booleanValue(lifecycle.auto_resume ?? lifecycle.autoResume);
+    if (onTimeout === undefined && autoResume === undefined)
+        return undefined;
+    return {
+        onTimeout: onTimeout ?? 'kill',
+        autoResume: autoResume ?? false,
+    };
+}
 function metricsList(value) {
     if (Array.isArray(value))
         return value.map((item) => metricsInfo(record(item)));
@@ -596,6 +668,15 @@ function stringValue(value) {
 function numberValue(value) {
     return typeof value === 'number' ? value : undefined;
 }
+function booleanValue(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    return undefined;
+}
 function templateSlug(value) {
     const template = record(value);
     return typeof template.slug === 'string' ? template.slug : undefined;

package/dist/template.d.ts

@@ -102,8 +102,6 @@ export declare class ReadyCmd {
 export declare function waitForPort(port: number): ReadyCmd;
 /** Return a ready check that waits for a URL to return an HTTP status code. */
 export declare function waitForURL(url: string, statusCode?: number): ReadyCmd;
-/** Alias for `waitForURL`. */
-export declare const waitForUrl: typeof waitForURL;
 /** Return a ready check that waits for a process name. */
 export declare function waitForProcess(processName: string): ReadyCmd;
 /** Return a ready check that waits for a file to exist. */
@@ -204,10 +202,13 @@ export declare class TemplateBase {
     }): TemplateBuilder;
     setStartCmd(startCommand: string, readyCommand: ReadyCommand): TemplateFinal;
     setReadyCmd(readyCommand: ReadyCommand): TemplateFinal;
+    betaDevContainerPrebuild(devcontainerDirectory: string): TemplateBuilder;
+    betaSetDevContainerStart(devcontainerDirectory: string): TemplateFinal;
     setEnvs(envs: Record<string, string>): TemplateBuilder;
     skipCache(): TemplateBuilder;
     toBuildSpec(): BuildSpec;
     private addPackages;
+    private requireDevContainerTemplate;
     private addCopySource;
     private addFileSpec;
     private resolveContextPath;

package/dist/template.js

@@ -22,8 +22,6 @@ export function waitForPort(port) {
 export function waitForURL(url, statusCode = 200) {
     return new ReadyCmd(`curl -s -o /dev/null -w "%{http_code}" ${url} | grep -q "${statusCode}"`);
 }
-/** Alias for `waitForURL`. */
-export const waitForUrl = waitForURL;
 /** Return a ready check that waits for a process name. */
 export function waitForProcess(processName) {
     return new ReadyCmd(`pgrep ${processName} > /dev/null`);
@@ -286,6 +284,14 @@ export class TemplateBase {
         this.readyCmd = readyCommandText(readyCommand);
         return this;
     }
+    betaDevContainerPrebuild(devcontainerDirectory) {
+        this.requireDevContainerTemplate('betaDevContainerPrebuild');
+        return this.runCmd(`devcontainer build --workspace-folder ${devcontainerDirectory}`, { user: 'root' });
+    }
+    betaSetDevContainerStart(devcontainerDirectory) {
+        this.requireDevContainerTemplate('betaSetDevContainerStart');
+        return this.setStartCmd(`sudo devcontainer up --workspace-folder ${devcontainerDirectory} && sudo /prepare-exec.sh ${devcontainerDirectory} | sudo tee /devcontainer.sh > /dev/null && sudo chmod +x /devcontainer.sh && sudo touch /devcontainer.up`, waitForFile('/devcontainer.up'));
+    }
     setEnvs(envs) {
         Object.assign(this.env, envs);
         return this;
@@ -315,6 +321,11 @@ export class TemplateBase {
     addPackages(manager, packages) {
         this.packages[manager] = [...(this.packages[manager] ?? []), ...packages];
     }
+    requireDevContainerTemplate(method) {
+        if (this.base !== 'devcontainer') {
+            throw new SandboxError(`${method} can only be used with the devcontainer template`);
+        }
+    }
     addCopySource(source, dest, options, multipleSources) {
         const sourcePath = this.resolveContextPath(source);
         const stat = fs.statSync(sourcePath);

package/dist/terminal.d.ts

@@ -13,9 +13,8 @@ export type TerminalOpts = {
     terminalID?: string;
     cmd?: string;
     cwd?: string;
-    rootDir?: string;
-    envVars?: Record<string, string>;
-    timeout?: number;
+    envs?: Record<string, string>;
+    timeoutMs?: number;
 };
 /** A running terminal session in a sandbox. */
 export declare class Terminal {

package/dist/terminal.js

@@ -59,10 +59,9 @@ export class TerminalManager {
         const handle = await this.pty.create({
             cmd: opts.cmd,
             cwd: opts.cwd,
-            rootDir: opts.rootDir,
-            envVars: opts.envVars,
+            envs: opts.envs,
             size: opts.size,
-            timeout: opts.timeout,
+            timeoutMs: opts.timeoutMs,
             onData: async (bytes) => {
                 const data = new TextDecoder().decode(bytes);
                 output.addData(data);

package/dist/transport.d.ts

@@ -15,6 +15,7 @@ export declare class DataPlaneClient {
     readonly token: string;
     private readonly config;
     constructor(baseUrl: string, token: string, config: ConnectionConfig);
+    get headers(): Record<string, string>;
     getJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
     postJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
     deleteJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
@@ -29,6 +30,7 @@ export interface RequestOpts {
     body?: BodyInit | Uint8Array;
     headers?: Record<string, string>;
     requestTimeoutMs?: number;
+    signal?: AbortSignal;
 }
 export declare function withQuery(path: string, params: Record<string, string | number | boolean | undefined>): string;
 export {};

package/dist/transport.js

@@ -28,9 +28,10 @@ export class ControlClient {
             headers: {
                 ...this.config.authHeaders,
                 ...(opts.json ? { 'content-type': 'application/json' } : {}),
+                ...(opts.headers ?? {}),
             },
             body: opts.json ? JSON.stringify(opts.json) : undefined,
-        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs);
+        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs, opts.signal ?? this.config.signal);
         return parseJsonResponse(response);
     }
 }
@@ -43,6 +44,9 @@ export class DataPlaneClient {
         this.token = token;
         this.config = config;
     }
+    get headers() {
+        return this.config.headers;
+    }
     getJson(path, opts = {}) {
         return this.request(path, { ...opts, method: 'GET' });
     }
@@ -68,12 +72,13 @@ export class DataPlaneClient {
         const response = await fetchWithTimeout(joinUrl(this.baseUrl, path), {
             method: opts.method,
             headers: {
+                ...this.config.headers,
                 Authorization: `Bearer ${this.token}`,
                 ...(opts.json ? { 'content-type': 'application/json' } : {}),
                 ...(opts.headers ?? {}),
             },
             body: opts.json ? JSON.stringify(opts.json) : opts.body,
-        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs);
+        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs, opts.signal ?? this.config.signal);
         if (!response.ok) {
             throw errorFromResponse(response.status, await readJsonOrText(response));
         }
@@ -109,14 +114,26 @@ async function readJsonOrText(response) {
         return { message: text };
     }
 }
-function fetchWithTimeout(url, init, timeoutMs) {
+function fetchWithTimeout(url, init, timeoutMs, signal) {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    let timedOut = false;
+    const abortFromCaller = () => controller.abort();
+    if (signal?.aborted)
+        controller.abort();
+    else
+        signal?.addEventListener('abort', abortFromCaller, { once: true });
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
     return fetch(url, { ...init, signal: controller.signal }).catch((error) => {
-        if (error?.name === 'AbortError')
+        if (error?.name === 'AbortError' && timedOut)
             throw new TimeoutError();
         throw error;
-    }).finally(() => clearTimeout(timeout));
+    }).finally(() => {
+        clearTimeout(timeout);
+        signal?.removeEventListener('abort', abortFromCaller);
+    });
 }
 function joinUrl(base, path) {
     const normalizedBase = base.replace(/\/+$/, '');