@quicktane-sdk/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuickTane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# QuickTane Node SDK
+
+Run code in isolated, ephemeral cloud sandboxes ([QuickTane](https://quicktane.com)) — one API call. TypeScript-native, zero runtime dependencies (uses the built-in `fetch`).
+
+```bash
+npm install @quicktane-sdk/client
+```
+
+Requires Node 18+.
+
+## Quickstart
+
+```ts
+import { QuickTane } from "@quicktane-sdk/client";
+
+const qt = new QuickTane("sk_live_...");        // or set QUICKTANE_API_KEY
+
+const run = await qt.runAndWait("print('hello from the sandbox')", "python");
+
+console.log(run.status);    // "completed"
+console.log(run.output);    // "hello from the sandbox\n"
+console.log(run.exitCode);  // 0
+```
+
+Supported languages: `python`, `node`.
+
+## Fire-and-forget + webhooks
+
+```ts
+const run = await qt.run("console.log(2 + 2)", "node");
+console.log(run.runId, run.status); // 42 "running"
+
+const finished = await qt.getRun(run.runId);
+```
+
+Register a webhook endpoint in your dashboard, then verify deliveries with the **raw** body:
+
+```ts
+import { verifySignature } from "@quicktane-sdk/client";
+
+if (!verifySignature(rawBody, req.headers["x-quicktane-signature"], signingSecret)) {
+  return res.status(400).end();
+}
+```
+
+## Interactive sessions
+
+Run many commands in one live sandbox — file and process state persist between calls:
+
+```ts
+const sbx = await qt.createSandbox("python");   // waits until ready
+
+await sbx.files.write("app.py", "print('hello from a session')");
+const result = await sbx.execCommand("python app.py");
+console.log(result.stdout, result.ok);          // "hello from a session\n" true
+
+// state persists across execs:
+await sbx.execCommand("pip install requests");
+await sbx.exec("import requests; print(requests.__version__)");
+
+await sbx.kill();
+```
+
+## Configuration
+
+```ts
+new QuickTane(apiKey, {
+  baseUrl,          // override the API base (e.g. "http://localhost:8000" for local dev)
+  timeout,          // HTTP request timeout in ms (default 30000)
+});
+```
+
+`apiKey` falls back to `QUICKTANE_API_KEY`; `baseUrl` to `QUICKTANE_BASE_URL`.
+
+## Errors
+
+All errors extend `QuickTaneError`: `AuthenticationError` (401/403), `NotFoundError` (404),
+`ValidationError` (422), `RateLimitError` (429), `APIError` (other). Each carries
+`.statusCode` and `.body`.
+
+## Development
+
+```bash
+pnpm install
+pnpm test     # vitest
+pnpm build    # tsup → dist (ESM + CJS + types)
+```
+
+MIT licensed.

package/dist/index.cjs

@@ -0,0 +1,357 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  AuthenticationError: () => AuthenticationError,
+  Files: () => Files,
+  NotFoundError: () => NotFoundError,
+  QuickTane: () => QuickTane,
+  QuickTaneError: () => QuickTaneError,
+  RateLimitError: () => RateLimitError,
+  Run: () => Run,
+  Sandbox: () => Sandbox,
+  ValidationError: () => ValidationError,
+  verifySignature: () => verifySignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var QuickTaneError = class extends Error {
+  statusCode;
+  body;
+  constructor(message, statusCode, body) {
+    super(message);
+    this.name = new.target.name;
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+};
+var AuthenticationError = class extends QuickTaneError {
+};
+var NotFoundError = class extends QuickTaneError {
+};
+var ValidationError = class extends QuickTaneError {
+};
+var RateLimitError = class extends QuickTaneError {
+};
+var APIError = class extends QuickTaneError {
+};
+var STATUS_MAP = {
+  401: AuthenticationError,
+  403: AuthenticationError,
+  404: NotFoundError,
+  422: ValidationError,
+  429: RateLimitError
+};
+async function raiseForStatus(response) {
+  if (response.status < 400) {
+    return;
+  }
+  let body = null;
+  let message = response.statusText || "Request failed";
+  try {
+    body = await response.clone().json();
+    message = body?.message ?? firstValidationError(body) ?? message;
+  } catch {
+    try {
+      body = await response.clone().text();
+    } catch {
+    }
+  }
+  const ErrorClass = STATUS_MAP[response.status] ?? APIError;
+  throw new ErrorClass(message, response.status, body);
+}
+function firstValidationError(body) {
+  const errors = body?.errors;
+  if (errors && typeof errors === "object") {
+    for (const messages of Object.values(errors)) {
+      if (Array.isArray(messages) && messages.length > 0) {
+        return String(messages[0]);
+      }
+    }
+  }
+  return void 0;
+}
+
+// src/models.ts
+var TERMINAL = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "timeout",
+  "error",
+  "killed"
+]);
+var Run = class _Run {
+  constructor(runId, status, language, exitCode, durationMs, output, createdAt) {
+    this.runId = runId;
+    this.status = status;
+    this.language = language;
+    this.exitCode = exitCode;
+    this.durationMs = durationMs;
+    this.output = output;
+    this.createdAt = createdAt;
+  }
+  runId;
+  status;
+  language;
+  exitCode;
+  durationMs;
+  output;
+  createdAt;
+  /** True once the run has finished (in any terminal state). */
+  get isTerminal() {
+    return TERMINAL.has(this.status);
+  }
+  /** True when the run completed with a zero exit code. */
+  get succeeded() {
+    return this.status === "completed" && (this.exitCode === 0 || this.exitCode === null);
+  }
+  static fromJSON(data) {
+    return new _Run(
+      data.run_id,
+      data.status,
+      data.language,
+      data.exit_code ?? null,
+      data.duration_ms ?? null,
+      data.output ?? null,
+      data.created_at ?? null
+    );
+  }
+};
+
+// src/sandbox.ts
+var TERMINAL2 = /* @__PURE__ */ new Set(["stopped", "error"]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var Files = class {
+  constructor(sandbox) {
+    this.sandbox = sandbox;
+  }
+  sandbox;
+  async write(path, content) {
+    await this.sandbox.request("POST", "/files", { path, content });
+  }
+  async read(path) {
+    const data = await this.sandbox.request("GET", "/files", { path });
+    return data.content ?? "";
+  }
+};
+var Sandbox = class {
+  constructor(client, sessionId, language, status) {
+    this.client = client;
+    this.sessionId = sessionId;
+    this.language = language;
+    this.status = status;
+    this.files = new Files(this);
+  }
+  client;
+  sessionId;
+  language;
+  status;
+  files;
+  /** Run code (in the session language, or `options.language`) in the sandbox. */
+  async exec(code, options = {}) {
+    return this.run({
+      language: options.language ?? this.language,
+      code,
+      timeout: options.timeout ?? 30
+    });
+  }
+  /** Run a shell command in the sandbox. */
+  async execCommand(command, options = {}) {
+    return this.run({ command, timeout: options.timeout ?? 30 });
+  }
+  /** Stop the session and free its pod. */
+  async kill() {
+    await this.request("DELETE", "");
+    this.status = "stopped";
+  }
+  async run(payload) {
+    const data = await this.request("POST", "/exec", payload);
+    const exitCode = data.exit_code ?? null;
+    const timedOut = Boolean(data.timed_out);
+    return {
+      stdout: data.stdout ?? "",
+      stderr: data.stderr ?? "",
+      exitCode,
+      timedOut,
+      ok: exitCode === 0 && !timedOut
+    };
+  }
+  /** @internal */
+  async waitReady(pollInterval, maxWait) {
+    const start = Date.now();
+    while (this.status !== "ready" && !TERMINAL2.has(this.status)) {
+      if (Date.now() - start >= maxWait) {
+        throw new Error(`Session ${this.sessionId} was not ready within ${maxWait}ms`);
+      }
+      await sleep(pollInterval);
+      const data = await this.client.json("GET", `/sessions/${this.sessionId}`);
+      this.status = data.status;
+    }
+    if (this.status !== "ready") {
+      throw new Error(`Session ${this.sessionId} entered status "${this.status}"`);
+    }
+  }
+  /** @internal */
+  request(method, path, data) {
+    return this.client.json(method, `/sessions/${this.sessionId}${path}`, data);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.quicktane.com";
+var VERSION = "0.1.0";
+var QuickTane = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  fetchImpl;
+  constructor(apiKey, options = {}) {
+    const key = apiKey ?? options.apiKey ?? process.env.QUICKTANE_API_KEY;
+    if (!key) {
+      throw new Error(
+        "A QuickTane API key is required. Pass it in or set QUICKTANE_API_KEY."
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (options.baseUrl ?? process.env.QUICKTANE_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = options.timeout ?? 3e4;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "Global fetch is not available. Upgrade to Node 18+ or pass a `fetch` implementation."
+      );
+    }
+  }
+  /** Queue a sandbox run and return immediately (status is usually `running`). */
+  async run(code, language = "python", options = {}) {
+    const response = await this.request("POST", "/run", {
+      language,
+      code,
+      timeout: options.timeout ?? 30
+    });
+    return Run.fromJSON(await response.json());
+  }
+  /** Fetch the current state of a run. */
+  async getRun(runId) {
+    const response = await this.request("GET", `/runs/${runId}`);
+    return Run.fromJSON(await response.json());
+  }
+  /** Queue a run and poll until it reaches a terminal state, then return it. */
+  async runAndWait(code, language = "python", options = {}) {
+    const pollInterval = options.pollInterval ?? 1e3;
+    const maxWait = options.maxWait ?? 3e5;
+    let run = await this.run(code, language, { timeout: options.timeout });
+    const start = Date.now();
+    while (!run.isTerminal) {
+      if (Date.now() - start >= maxWait) {
+        throw new Error(`Run ${run.runId} did not finish within ${maxWait}ms`);
+      }
+      await sleep2(pollInterval);
+      run = await this.getRun(run.runId);
+    }
+    return run;
+  }
+  /** Start a live interactive session and (by default) wait until it is ready. */
+  async createSandbox(language = "python", options = {}) {
+    const data = await this.json("POST", "/sessions", { language });
+    const sandbox = new Sandbox(this, data.session_id, data.language, data.status);
+    if (options.wait ?? true) {
+      await sandbox.waitReady(options.pollInterval ?? 1e3, options.maxWait ?? 12e4);
+    }
+    return sandbox;
+  }
+  /** Reconnect to an existing session by id. */
+  async getSandbox(sessionId) {
+    const data = await this.json("GET", `/sessions/${sessionId}`);
+    return new Sandbox(this, data.session_id, data.language, data.status);
+  }
+  /** @internal — JSON request/response helper used by sessions. */
+  async json(method, path, data) {
+    let url = path;
+    let body;
+    if (method === "GET") {
+      if (data && Object.keys(data).length > 0) {
+        url = `${path}?${new URLSearchParams(data).toString()}`;
+      }
+    } else if (data !== void 0) {
+      body = data;
+    }
+    const response = await this.request(method, url, body);
+    const text = await response.text();
+    return text ? JSON.parse(text) : {};
+  }
+  async request(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}/v1${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          "User-Agent": `quicktane-node/${VERSION}`,
+          ...body ? { "Content-Type": "application/json" } : {}
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    await raiseForStatus(response);
+    return response;
+  }
+};
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/webhooks.ts
+var import_node_crypto = require("crypto");
+function verifySignature(payload, signatureHeader, secret) {
+  if (!signatureHeader) {
+    return false;
+  }
+  const body = typeof payload === "string" ? Buffer.from(payload) : payload;
+  const expected = "sha256=" + (0, import_node_crypto.createHmac)("sha256", secret).update(body).digest("hex");
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signatureHeader);
+  return a.length === b.length && (0, import_node_crypto.timingSafeEqual)(a, b);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  AuthenticationError,
+  Files,
+  NotFoundError,
+  QuickTane,
+  QuickTaneError,
+  RateLimitError,
+  Run,
+  Sandbox,
+  ValidationError,
+  verifySignature
+});

package/dist/index.d.cts

@@ -0,0 +1,138 @@
+type RunStatus = "pending" | "running" | "completed" | "failed" | "timeout" | "error" | "killed";
+/** A sandbox execution. */
+declare class Run {
+    readonly runId: number;
+    readonly status: string;
+    readonly language: string;
+    readonly exitCode: number | null;
+    readonly durationMs: number | null;
+    readonly output: string | null;
+    readonly createdAt: string | null;
+    constructor(runId: number, status: string, language: string, exitCode: number | null, durationMs: number | null, output: string | null, createdAt: string | null);
+    /** True once the run has finished (in any terminal state). */
+    get isTerminal(): boolean;
+    /** True when the run completed with a zero exit code. */
+    get succeeded(): boolean;
+    static fromJSON(data: Record<string, unknown>): Run;
+}
+
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    /** True when the command completed with a zero exit code. */
+    ok: boolean;
+}
+interface ExecOptions {
+    language?: string;
+    timeout?: number;
+}
+/** Filesystem access for a session workspace. */
+declare class Files {
+    private readonly sandbox;
+    constructor(sandbox: Sandbox);
+    write(path: string, content: string): Promise<void>;
+    read(path: string): Promise<string>;
+}
+/** A live interactive session — run many commands in one persistent environment. */
+declare class Sandbox {
+    private readonly client;
+    readonly sessionId: number;
+    readonly language: string;
+    status: string;
+    readonly files: Files;
+    constructor(client: QuickTane, sessionId: number, language: string, status: string);
+    /** Run code (in the session language, or `options.language`) in the sandbox. */
+    exec(code: string, options?: ExecOptions): Promise<ExecResult>;
+    /** Run a shell command in the sandbox. */
+    execCommand(command: string, options?: {
+        timeout?: number;
+    }): Promise<ExecResult>;
+    /** Stop the session and free its pod. */
+    kill(): Promise<void>;
+    private run;
+    /** @internal */
+    waitReady(pollInterval: number, maxWait: number): Promise<void>;
+    /** @internal */
+    request(method: string, path: string, data?: Record<string, unknown>): Promise<Record<string, any>>;
+}
+
+interface QuickTaneOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** HTTP request timeout in milliseconds (default 30000). */
+    timeout?: number;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+interface RunOptions {
+    /** Sandbox time limit in seconds (default 30). */
+    timeout?: number;
+}
+interface RunAndWaitOptions extends RunOptions {
+    /** Milliseconds between status polls (default 1000). */
+    pollInterval?: number;
+    /** Give up after this many milliseconds (default 300000). */
+    maxWait?: number;
+}
+declare class QuickTane {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(apiKey?: string, options?: QuickTaneOptions);
+    /** Queue a sandbox run and return immediately (status is usually `running`). */
+    run(code: string, language?: string, options?: RunOptions): Promise<Run>;
+    /** Fetch the current state of a run. */
+    getRun(runId: number | string): Promise<Run>;
+    /** Queue a run and poll until it reaches a terminal state, then return it. */
+    runAndWait(code: string, language?: string, options?: RunAndWaitOptions): Promise<Run>;
+    /** Start a live interactive session and (by default) wait until it is ready. */
+    createSandbox(language?: string, options?: {
+        wait?: boolean;
+        pollInterval?: number;
+        maxWait?: number;
+    }): Promise<Sandbox>;
+    /** Reconnect to an existing session by id. */
+    getSandbox(sessionId: number): Promise<Sandbox>;
+    /** @internal — JSON request/response helper used by sessions. */
+    json(method: string, path: string, data?: Record<string, unknown>): Promise<Record<string, any>>;
+    private request;
+}
+
+declare class QuickTaneError extends Error {
+    statusCode?: number;
+    body?: unknown;
+    constructor(message: string, statusCode?: number, body?: unknown);
+}
+/** Invalid, missing, or suspended API key (401 / 403). */
+declare class AuthenticationError extends QuickTaneError {
+}
+/** The requested run does not exist (404). */
+declare class NotFoundError extends QuickTaneError {
+}
+/** The request was rejected (422). */
+declare class ValidationError extends QuickTaneError {
+}
+/** Rate limit or plan concurrency limit exceeded (429). */
+declare class RateLimitError extends QuickTaneError {
+}
+/** Any other non-2xx response. */
+declare class APIError extends QuickTaneError {
+}
+
+/**
+ * Verify a QuickTane webhook signature.
+ *
+ * Compute the HMAC-SHA256 of the raw request body with your endpoint's signing
+ * secret and compare it, in constant time, to the `X-QuickTane-Signature`
+ * header (`sha256=<hex>`).
+ *
+ * @param payload the RAW request body (string or Buffer).
+ * @param signatureHeader the `X-QuickTane-Signature` header value.
+ * @param secret your endpoint's signing secret (`whsec_...`).
+ */
+declare function verifySignature(payload: string | Buffer, signatureHeader: string, secret: string): boolean;
+
+export { APIError, AuthenticationError, type ExecOptions, type ExecResult, Files, NotFoundError, QuickTane, QuickTaneError, type QuickTaneOptions, RateLimitError, Run, type RunAndWaitOptions, type RunOptions, type RunStatus, Sandbox, ValidationError, verifySignature };

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+type RunStatus = "pending" | "running" | "completed" | "failed" | "timeout" | "error" | "killed";
+/** A sandbox execution. */
+declare class Run {
+    readonly runId: number;
+    readonly status: string;
+    readonly language: string;
+    readonly exitCode: number | null;
+    readonly durationMs: number | null;
+    readonly output: string | null;
+    readonly createdAt: string | null;
+    constructor(runId: number, status: string, language: string, exitCode: number | null, durationMs: number | null, output: string | null, createdAt: string | null);
+    /** True once the run has finished (in any terminal state). */
+    get isTerminal(): boolean;
+    /** True when the run completed with a zero exit code. */
+    get succeeded(): boolean;
+    static fromJSON(data: Record<string, unknown>): Run;
+}
+
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    /** True when the command completed with a zero exit code. */
+    ok: boolean;
+}
+interface ExecOptions {
+    language?: string;
+    timeout?: number;
+}
+/** Filesystem access for a session workspace. */
+declare class Files {
+    private readonly sandbox;
+    constructor(sandbox: Sandbox);
+    write(path: string, content: string): Promise<void>;
+    read(path: string): Promise<string>;
+}
+/** A live interactive session — run many commands in one persistent environment. */
+declare class Sandbox {
+    private readonly client;
+    readonly sessionId: number;
+    readonly language: string;
+    status: string;
+    readonly files: Files;
+    constructor(client: QuickTane, sessionId: number, language: string, status: string);
+    /** Run code (in the session language, or `options.language`) in the sandbox. */
+    exec(code: string, options?: ExecOptions): Promise<ExecResult>;
+    /** Run a shell command in the sandbox. */
+    execCommand(command: string, options?: {
+        timeout?: number;
+    }): Promise<ExecResult>;
+    /** Stop the session and free its pod. */
+    kill(): Promise<void>;
+    private run;
+    /** @internal */
+    waitReady(pollInterval: number, maxWait: number): Promise<void>;
+    /** @internal */
+    request(method: string, path: string, data?: Record<string, unknown>): Promise<Record<string, any>>;
+}
+
+interface QuickTaneOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** HTTP request timeout in milliseconds (default 30000). */
+    timeout?: number;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+interface RunOptions {
+    /** Sandbox time limit in seconds (default 30). */
+    timeout?: number;
+}
+interface RunAndWaitOptions extends RunOptions {
+    /** Milliseconds between status polls (default 1000). */
+    pollInterval?: number;
+    /** Give up after this many milliseconds (default 300000). */
+    maxWait?: number;
+}
+declare class QuickTane {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(apiKey?: string, options?: QuickTaneOptions);
+    /** Queue a sandbox run and return immediately (status is usually `running`). */
+    run(code: string, language?: string, options?: RunOptions): Promise<Run>;
+    /** Fetch the current state of a run. */
+    getRun(runId: number | string): Promise<Run>;
+    /** Queue a run and poll until it reaches a terminal state, then return it. */
+    runAndWait(code: string, language?: string, options?: RunAndWaitOptions): Promise<Run>;
+    /** Start a live interactive session and (by default) wait until it is ready. */
+    createSandbox(language?: string, options?: {
+        wait?: boolean;
+        pollInterval?: number;
+        maxWait?: number;
+    }): Promise<Sandbox>;
+    /** Reconnect to an existing session by id. */
+    getSandbox(sessionId: number): Promise<Sandbox>;
+    /** @internal — JSON request/response helper used by sessions. */
+    json(method: string, path: string, data?: Record<string, unknown>): Promise<Record<string, any>>;
+    private request;
+}
+
+declare class QuickTaneError extends Error {
+    statusCode?: number;
+    body?: unknown;
+    constructor(message: string, statusCode?: number, body?: unknown);
+}
+/** Invalid, missing, or suspended API key (401 / 403). */
+declare class AuthenticationError extends QuickTaneError {
+}
+/** The requested run does not exist (404). */
+declare class NotFoundError extends QuickTaneError {
+}
+/** The request was rejected (422). */
+declare class ValidationError extends QuickTaneError {
+}
+/** Rate limit or plan concurrency limit exceeded (429). */
+declare class RateLimitError extends QuickTaneError {
+}
+/** Any other non-2xx response. */
+declare class APIError extends QuickTaneError {
+}
+
+/**
+ * Verify a QuickTane webhook signature.
+ *
+ * Compute the HMAC-SHA256 of the raw request body with your endpoint's signing
+ * secret and compare it, in constant time, to the `X-QuickTane-Signature`
+ * header (`sha256=<hex>`).
+ *
+ * @param payload the RAW request body (string or Buffer).
+ * @param signatureHeader the `X-QuickTane-Signature` header value.
+ * @param secret your endpoint's signing secret (`whsec_...`).
+ */
+declare function verifySignature(payload: string | Buffer, signatureHeader: string, secret: string): boolean;
+
+export { APIError, AuthenticationError, type ExecOptions, type ExecResult, Files, NotFoundError, QuickTane, QuickTaneError, type QuickTaneOptions, RateLimitError, Run, type RunAndWaitOptions, type RunOptions, type RunStatus, Sandbox, ValidationError, verifySignature };

package/dist/index.js

@@ -0,0 +1,320 @@
+// src/errors.ts
+var QuickTaneError = class extends Error {
+  statusCode;
+  body;
+  constructor(message, statusCode, body) {
+    super(message);
+    this.name = new.target.name;
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+};
+var AuthenticationError = class extends QuickTaneError {
+};
+var NotFoundError = class extends QuickTaneError {
+};
+var ValidationError = class extends QuickTaneError {
+};
+var RateLimitError = class extends QuickTaneError {
+};
+var APIError = class extends QuickTaneError {
+};
+var STATUS_MAP = {
+  401: AuthenticationError,
+  403: AuthenticationError,
+  404: NotFoundError,
+  422: ValidationError,
+  429: RateLimitError
+};
+async function raiseForStatus(response) {
+  if (response.status < 400) {
+    return;
+  }
+  let body = null;
+  let message = response.statusText || "Request failed";
+  try {
+    body = await response.clone().json();
+    message = body?.message ?? firstValidationError(body) ?? message;
+  } catch {
+    try {
+      body = await response.clone().text();
+    } catch {
+    }
+  }
+  const ErrorClass = STATUS_MAP[response.status] ?? APIError;
+  throw new ErrorClass(message, response.status, body);
+}
+function firstValidationError(body) {
+  const errors = body?.errors;
+  if (errors && typeof errors === "object") {
+    for (const messages of Object.values(errors)) {
+      if (Array.isArray(messages) && messages.length > 0) {
+        return String(messages[0]);
+      }
+    }
+  }
+  return void 0;
+}
+
+// src/models.ts
+var TERMINAL = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "timeout",
+  "error",
+  "killed"
+]);
+var Run = class _Run {
+  constructor(runId, status, language, exitCode, durationMs, output, createdAt) {
+    this.runId = runId;
+    this.status = status;
+    this.language = language;
+    this.exitCode = exitCode;
+    this.durationMs = durationMs;
+    this.output = output;
+    this.createdAt = createdAt;
+  }
+  runId;
+  status;
+  language;
+  exitCode;
+  durationMs;
+  output;
+  createdAt;
+  /** True once the run has finished (in any terminal state). */
+  get isTerminal() {
+    return TERMINAL.has(this.status);
+  }
+  /** True when the run completed with a zero exit code. */
+  get succeeded() {
+    return this.status === "completed" && (this.exitCode === 0 || this.exitCode === null);
+  }
+  static fromJSON(data) {
+    return new _Run(
+      data.run_id,
+      data.status,
+      data.language,
+      data.exit_code ?? null,
+      data.duration_ms ?? null,
+      data.output ?? null,
+      data.created_at ?? null
+    );
+  }
+};
+
+// src/sandbox.ts
+var TERMINAL2 = /* @__PURE__ */ new Set(["stopped", "error"]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var Files = class {
+  constructor(sandbox) {
+    this.sandbox = sandbox;
+  }
+  sandbox;
+  async write(path, content) {
+    await this.sandbox.request("POST", "/files", { path, content });
+  }
+  async read(path) {
+    const data = await this.sandbox.request("GET", "/files", { path });
+    return data.content ?? "";
+  }
+};
+var Sandbox = class {
+  constructor(client, sessionId, language, status) {
+    this.client = client;
+    this.sessionId = sessionId;
+    this.language = language;
+    this.status = status;
+    this.files = new Files(this);
+  }
+  client;
+  sessionId;
+  language;
+  status;
+  files;
+  /** Run code (in the session language, or `options.language`) in the sandbox. */
+  async exec(code, options = {}) {
+    return this.run({
+      language: options.language ?? this.language,
+      code,
+      timeout: options.timeout ?? 30
+    });
+  }
+  /** Run a shell command in the sandbox. */
+  async execCommand(command, options = {}) {
+    return this.run({ command, timeout: options.timeout ?? 30 });
+  }
+  /** Stop the session and free its pod. */
+  async kill() {
+    await this.request("DELETE", "");
+    this.status = "stopped";
+  }
+  async run(payload) {
+    const data = await this.request("POST", "/exec", payload);
+    const exitCode = data.exit_code ?? null;
+    const timedOut = Boolean(data.timed_out);
+    return {
+      stdout: data.stdout ?? "",
+      stderr: data.stderr ?? "",
+      exitCode,
+      timedOut,
+      ok: exitCode === 0 && !timedOut
+    };
+  }
+  /** @internal */
+  async waitReady(pollInterval, maxWait) {
+    const start = Date.now();
+    while (this.status !== "ready" && !TERMINAL2.has(this.status)) {
+      if (Date.now() - start >= maxWait) {
+        throw new Error(`Session ${this.sessionId} was not ready within ${maxWait}ms`);
+      }
+      await sleep(pollInterval);
+      const data = await this.client.json("GET", `/sessions/${this.sessionId}`);
+      this.status = data.status;
+    }
+    if (this.status !== "ready") {
+      throw new Error(`Session ${this.sessionId} entered status "${this.status}"`);
+    }
+  }
+  /** @internal */
+  request(method, path, data) {
+    return this.client.json(method, `/sessions/${this.sessionId}${path}`, data);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.quicktane.com";
+var VERSION = "0.1.0";
+var QuickTane = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  fetchImpl;
+  constructor(apiKey, options = {}) {
+    const key = apiKey ?? options.apiKey ?? process.env.QUICKTANE_API_KEY;
+    if (!key) {
+      throw new Error(
+        "A QuickTane API key is required. Pass it in or set QUICKTANE_API_KEY."
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (options.baseUrl ?? process.env.QUICKTANE_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = options.timeout ?? 3e4;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "Global fetch is not available. Upgrade to Node 18+ or pass a `fetch` implementation."
+      );
+    }
+  }
+  /** Queue a sandbox run and return immediately (status is usually `running`). */
+  async run(code, language = "python", options = {}) {
+    const response = await this.request("POST", "/run", {
+      language,
+      code,
+      timeout: options.timeout ?? 30
+    });
+    return Run.fromJSON(await response.json());
+  }
+  /** Fetch the current state of a run. */
+  async getRun(runId) {
+    const response = await this.request("GET", `/runs/${runId}`);
+    return Run.fromJSON(await response.json());
+  }
+  /** Queue a run and poll until it reaches a terminal state, then return it. */
+  async runAndWait(code, language = "python", options = {}) {
+    const pollInterval = options.pollInterval ?? 1e3;
+    const maxWait = options.maxWait ?? 3e5;
+    let run = await this.run(code, language, { timeout: options.timeout });
+    const start = Date.now();
+    while (!run.isTerminal) {
+      if (Date.now() - start >= maxWait) {
+        throw new Error(`Run ${run.runId} did not finish within ${maxWait}ms`);
+      }
+      await sleep2(pollInterval);
+      run = await this.getRun(run.runId);
+    }
+    return run;
+  }
+  /** Start a live interactive session and (by default) wait until it is ready. */
+  async createSandbox(language = "python", options = {}) {
+    const data = await this.json("POST", "/sessions", { language });
+    const sandbox = new Sandbox(this, data.session_id, data.language, data.status);
+    if (options.wait ?? true) {
+      await sandbox.waitReady(options.pollInterval ?? 1e3, options.maxWait ?? 12e4);
+    }
+    return sandbox;
+  }
+  /** Reconnect to an existing session by id. */
+  async getSandbox(sessionId) {
+    const data = await this.json("GET", `/sessions/${sessionId}`);
+    return new Sandbox(this, data.session_id, data.language, data.status);
+  }
+  /** @internal — JSON request/response helper used by sessions. */
+  async json(method, path, data) {
+    let url = path;
+    let body;
+    if (method === "GET") {
+      if (data && Object.keys(data).length > 0) {
+        url = `${path}?${new URLSearchParams(data).toString()}`;
+      }
+    } else if (data !== void 0) {
+      body = data;
+    }
+    const response = await this.request(method, url, body);
+    const text = await response.text();
+    return text ? JSON.parse(text) : {};
+  }
+  async request(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}/v1${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          "User-Agent": `quicktane-node/${VERSION}`,
+          ...body ? { "Content-Type": "application/json" } : {}
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    await raiseForStatus(response);
+    return response;
+  }
+};
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifySignature(payload, signatureHeader, secret) {
+  if (!signatureHeader) {
+    return false;
+  }
+  const body = typeof payload === "string" ? Buffer.from(payload) : payload;
+  const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signatureHeader);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+export {
+  APIError,
+  AuthenticationError,
+  Files,
+  NotFoundError,
+  QuickTane,
+  QuickTaneError,
+  RateLimitError,
+  Run,
+  Sandbox,
+  ValidationError,
+  verifySignature
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@quicktane-sdk/client",
+  "version": "0.1.0",
+  "description": "Node/TypeScript SDK for QuickTane — run code in isolated, ephemeral cloud sandboxes.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["sandbox", "code-execution", "gvisor", "ai-agents", "code-interpreter"],
+  "homepage": "https://quicktane.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quicktane/SDK-NodeJS.git"
+  },
+  "publishConfig": { "access": "public" },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8",
+    "typescript": "^5",
+    "vitest": "^2"
+  }
+}