fetchsandbox 0.3.0 → 0.3.1

package/dist/commands/check.js

@@ -69,20 +69,27 @@ export async function check(sandboxId) {
         console.log(`  ${pc.bold("Overall:")} ${overallColor(pc.bold(`${overall}%`))}`);
         // ── Next Steps ────────────────────────────────────────────────
         const nextSteps = [];
+        if (wfs.length > 0 && completedWorkflows < wfs.length) {
+            if (completedWorkflows === 0) {
+                nextSteps.push(`Prove all workflows: ${pc.cyan(`fetchsandbox run ${sandboxId} --all`)}`);
+            }
+            else {
+                for (const inc of incompleteWorkflows.slice(0, 2)) {
+                    nextSteps.push(`Complete workflow: ${pc.cyan(`fetchsandbox run ${sandboxId} "${inc.name}"`)}`);
+                }
+            }
+        }
         if (coveragePct < 10) {
             nextSteps.push(`Try an API call: ${pc.cyan(`fetchsandbox request ${sandboxId} GET /v1`)}`);
         }
-        if (wfs.length > 0 && completedWorkflows === 0) {
-            nextSteps.push(`Run a workflow: ${pc.cyan(`fetchsandbox workflows ${sandboxId}`)}`);
-        }
         if (webhookScore === 0) {
-            nextSteps.push(`Register a webhook in the sandbox dashboard`);
+            nextSteps.push(`Watch webhooks: ${pc.cyan(`fetchsandbox webhook-listen ${sandboxId}`)}`);
         }
         if (healthPct < 90 && healthPct > 0) {
-            nextSteps.push(`Check failing endpoints: ${pc.cyan(`fetchsandbox endpoints ${sandboxId}`)}`);
+            nextSteps.push(`Inspect state: ${pc.cyan(`fetchsandbox state ${sandboxId}`)}`);
         }
-        if (sb.active_scenario === "default") {
-            nextSteps.push(`Test error scenarios: ${pc.cyan(`fetchsandbox scenario ${sandboxId} auth-failure`)}`);
+        if (sb.active_scenario === "default" && overall >= 50) {
+            nextSteps.push(`Test error handling: ${pc.cyan(`fetchsandbox run ${sandboxId} --all --scenario auth_failure`)}`);
         }
         if (nextSteps.length > 0) {
             blank();

package/dist/commands/diff.d.ts

@@ -0,0 +1,3 @@
+export declare function diff(sandboxId: string, options?: {
+    last?: string;
+}): Promise<void>;

package/dist/commands/diff.js

@@ -0,0 +1,133 @@
+import pc from "picocolors";
+import { getSandboxState, getSandboxLogs } from "../lib/api.js";
+import { fail, blank, heading, info, method as methodColor, timeAgo, friendlyError } from "../lib/output.js";
+export async function diff(sandboxId, options = {}) {
+    blank();
+    try {
+        // Fetch current state and recent logs in parallel
+        const [state, logs] = await Promise.all([
+            getSandboxState(sandboxId),
+            getSandboxLogs(sandboxId, 100).catch(() => []),
+        ]);
+        // Determine the time window for "recent" changes
+        const lastN = options.last ? parseInt(options.last, 10) : 0;
+        // Separate mutation logs (POST/PUT/PATCH/DELETE) from reads
+        const mutations = logs.filter((l) => ["POST", "PUT", "PATCH", "DELETE"].includes(l.method) && l.response_status < 400);
+        if (mutations.length === 0 && lastN === 0) {
+            info("No mutations found in recent logs. Make some API calls first.");
+            blank();
+            info(`Tip: fetchsandbox run ${sandboxId} --all`);
+            blank();
+            return;
+        }
+        // Show recent mutations
+        const recentMutations = lastN > 0 ? mutations.slice(0, lastN) : mutations;
+        heading(`Recent changes — ${recentMutations.length} mutation${recentMutations.length === 1 ? "" : "s"}`);
+        blank();
+        // Group mutations by resource type (inferred from path)
+        const byResource = new Map();
+        for (const log of recentMutations) {
+            const resource = inferResource(log.path);
+            if (!byResource.has(resource))
+                byResource.set(resource, []);
+            byResource.get(resource).push(log);
+        }
+        for (const [resource, resourceLogs] of byResource) {
+            const stateRecords = state[resource];
+            const count = Array.isArray(stateRecords) ? stateRecords.length : 0;
+            console.log(`  ${pc.bold(resource)} ${pc.dim(`(${count} record${count === 1 ? "" : "s"} now)`)}`);
+            for (const log of resourceLogs) {
+                const time = timeAgo(log.timestamp);
+                const m = methodColor(log.method);
+                const action = actionFromMethod(log.method);
+                const icon = actionIcon(log.method);
+                // Try to extract resource ID from response
+                const resId = extractIdFromResponse(log.response_body);
+                const idStr = resId ? pc.white(resId) : "";
+                console.log(`    ${icon} ${m} ${log.path.length > 40 ? log.path.slice(0, 37) + "..." : log.path}  ${idStr}  ${pc.dim(time)}`);
+            }
+            blank();
+        }
+        // Show current state summary
+        heading("Current state:");
+        blank();
+        const types = Object.entries(state).filter(([, records]) => Array.isArray(records) && records.length > 0);
+        for (const [type, records] of types) {
+            const items = records;
+            const statusField = items[0]?.status !== undefined ? "status" : items[0]?.state !== undefined ? "state" : null;
+            let dist = "";
+            if (statusField) {
+                const counts = {};
+                for (const r of items) {
+                    const val = String(r[statusField] ?? "unknown");
+                    counts[val] = (counts[val] || 0) + 1;
+                }
+                dist = Object.entries(counts)
+                    .sort(([, a], [, b]) => b - a)
+                    .map(([val, count]) => `${count} ${val}`)
+                    .join(", ");
+            }
+            const countStr = pc.bold(String(items.length));
+            const distStr = dist ? pc.dim(`  (${dist})`) : "";
+            console.log(`  ${type.padEnd(25)} ${countStr}${distStr}`);
+        }
+        blank();
+        info(`Tip: fetchsandbox state ${sandboxId} <resource> to inspect records`);
+        blank();
+    }
+    catch (error) {
+        fail(friendlyError(error));
+        blank();
+        process.exit(1);
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+/** Infer resource type from API path. */
+function inferResource(path) {
+    const segments = path.split("/").filter(Boolean);
+    // Walk backwards, skip path params (they contain IDs)
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const seg = segments[i];
+        // Skip version prefixes
+        if (/^v\d+/.test(seg))
+            continue;
+        // Skip segments that look like IDs
+        if (seg.includes("_") && seg.length > 15)
+            continue;
+        if (/^[0-9a-f]{8,}$/i.test(seg))
+            continue;
+        // Skip common action verbs
+        if (["capture", "confirm", "cancel", "refund", "void", "close", "approve", "reject", "send"].includes(seg))
+            continue;
+        return seg;
+    }
+    return segments[0] || "unknown";
+}
+/** Action description from HTTP method. */
+function actionFromMethod(method) {
+    switch (method) {
+        case "POST": return "created";
+        case "PUT": return "replaced";
+        case "PATCH": return "updated";
+        case "DELETE": return "deleted";
+        default: return "modified";
+    }
+}
+/** Action icon from HTTP method. */
+function actionIcon(method) {
+    switch (method) {
+        case "POST": return pc.green("+");
+        case "PUT": return pc.yellow("~");
+        case "PATCH": return pc.yellow("~");
+        case "DELETE": return pc.red("-");
+        default: return pc.dim("·");
+    }
+}
+/** Extract resource ID from a response body. */
+function extractIdFromResponse(body) {
+    if (!body || typeof body !== "object")
+        return "";
+    const obj = body;
+    const id = obj.id || obj.ID || "";
+    return id ? String(id) : "";
+}

package/dist/commands/run.d.ts

@@ -1,4 +1,5 @@
-export declare function run(sandboxId: string, workflowName: string, options?: {
+export declare function run(sandboxId: string, workflowName: string | undefined, options?: {
     scenario?: string;
     verbose?: boolean;
+    all?: boolean;
 }): Promise<void>;

package/dist/commands/run.js

@@ -5,6 +5,11 @@ import { fail, blank, heading, info, method as methodColor, friendlyError } from
 export async function run(sandboxId, workflowName, options = {}) {
     blank();
     try {
+        // --all mode: run every workflow and report summary
+        if (options.all || workflowName === undefined) {
+            await runAll(sandboxId, options);
+            return;
+        }
         // If a scenario was requested, switch to it first
         if (options.scenario) {
             const spinner = ora({ text: `  Switching to scenario: ${options.scenario}`, indent: 0 }).start();
@@ -19,79 +24,11 @@ export async function run(sandboxId, workflowName, options = {}) {
             }
         }
         // Run the workflow
-        const spinner = ora({ text: `  Running workflow...`, indent: 0 }).start();
-        let result;
-        try {
-            result = await runWorkflow(sandboxId, workflowName);
-            spinner.stop();
-        }
-        catch (err) {
-            spinner.fail(`  Failed to run workflow`);
-            blank();
-            // If 404, try to list available workflows and show helpful error
-            const errMsg = friendlyError(err);
-            if (errMsg.includes("404") || errMsg.includes("not found") || errMsg.includes("Not found")) {
-                await showAvailableWorkflows(sandboxId, workflowName);
-            }
-            else {
-                fail(errMsg);
-            }
-            blank();
-            process.exit(1);
-        }
-        // Display results
-        const totalSteps = result.steps.length;
-        const passedSteps = result.steps.filter((s) => s.status === "passed").length;
-        const workflowLabel = result.flow_description || result.flow_name;
-        heading(`${workflowLabel} (${totalSteps} step${totalSteps === 1 ? "" : "s"})`);
-        blank();
-        for (let i = 0; i < result.steps.length; i++) {
-            const step = result.steps[i];
-            const stepNum = `Step ${i + 1}/${totalSteps}`;
-            const icon = step.status === "passed" ? pc.green("✓") : pc.red("✗");
-            const duration = pc.dim(`${step.duration_ms}ms`);
-            // Parse method and path from detail or step name
-            const { method: httpMethod, path } = parseMethodPath(step.detail);
-            // Step header
-            if (httpMethod && path) {
-                console.log(`  ${icon} ${pc.dim(stepNum)}  ${methodColor(httpMethod)} ${path}  ${duration}`);
-            }
-            else {
-                console.log(`  ${icon} ${pc.dim(stepNum)}  ${step.name}  ${duration}`);
-            }
-            // Step detail
-            const detail = formatDetail(step);
-            if (detail) {
-                console.log(`    ${detail}`);
-            }
-            // Verbose: show full data
-            if (options.verbose && Object.keys(step.data).length > 0) {
-                const json = JSON.stringify(step.data, null, 2);
-                for (const line of json.split("\n")) {
-                    console.log(`    ${pc.dim(line)}`);
-                }
-            }
-            // Show webhook events in step
-            if (step.name === "webhook_verification") {
-                const matched = (step.data.matched || []);
-                for (const evt of matched) {
-                    console.log(`    ${pc.yellow("⚡")} ${evt}`);
-                }
-            }
-        }
-        blank();
-        // Summary
-        const totalTime = `${result.total_duration_ms}ms`;
-        if (result.passed) {
-            console.log(`  ${pc.green("✓")} Workflow complete — ${passedSteps}/${totalSteps} steps passed ${pc.dim(`(${totalTime})`)}`);
-        }
-        else {
-            console.log(`  ${pc.red("✗")} Workflow failed at step ${passedSteps + 1}/${totalSteps} ${pc.dim(`(${totalTime})`)}`);
-        }
+        const result = await executeAndDisplay(sandboxId, workflowName, options);
         // If using a scenario and it failed as expected, that's actually a good thing
         if (options.scenario && !result.passed) {
             blank();
-            info(`Scenario "${options.scenario}" correctly caused failure at step ${passedSteps + 1}.`);
+            info(`Scenario "${options.scenario}" correctly caused failure.`);
             info("This confirms your error handling works.");
         }
         blank();
@@ -117,6 +54,133 @@ export async function run(sandboxId, workflowName, options = {}) {
         process.exit(1);
     }
 }
+// ── Run All ─────────────────────────────────────────────────────────────
+async function runAll(sandboxId, options = {}) {
+    const spinner = ora({ text: `  Loading workflows...`, indent: 0 }).start();
+    let sb;
+    let workflows;
+    try {
+        sb = await getSandbox(sandboxId);
+        const data = await getWorkflows(sb.spec_id);
+        workflows = data.workflows;
+        spinner.stop();
+    }
+    catch (err) {
+        spinner.fail(`  Failed to load workflows`);
+        blank();
+        fail(friendlyError(err));
+        blank();
+        process.exit(1);
+    }
+    if (workflows.length === 0) {
+        info("No workflows configured for this sandbox.");
+        blank();
+        return;
+    }
+    heading(`Running all ${workflows.length} workflows for ${sb.spec_name || sb.name}`);
+    blank();
+    const results = [];
+    let totalPassed = 0;
+    for (const wf of workflows) {
+        const wfId = wf.id || wf.name;
+        const result = await executeAndDisplay(sandboxId, wfId, options);
+        results.push({
+            name: wf.name,
+            passed: result.passed,
+            steps: result.steps.length,
+            duration: result.total_duration_ms,
+        });
+        if (result.passed)
+            totalPassed++;
+        blank();
+    }
+    // Summary
+    const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
+    const allPassed = totalPassed === results.length;
+    console.log(`  ${pc.bold("━".repeat(50))}`);
+    blank();
+    if (allPassed) {
+        console.log(`  ${pc.green("✓")} All workflows passed — ${totalPassed}/${results.length} ${pc.dim(`(${totalDuration.toFixed(1)}ms)`)}`);
+    }
+    else {
+        console.log(`  ${pc.red("✗")} ${totalPassed}/${results.length} workflows passed ${pc.dim(`(${totalDuration.toFixed(1)}ms)`)}`);
+        blank();
+        for (const r of results) {
+            if (!r.passed) {
+                console.log(`    ${pc.red("✗")} ${r.name}`);
+            }
+        }
+    }
+    blank();
+    if (!allPassed) {
+        process.exit(1);
+    }
+}
+// ── Execute and Display ─────────────────────────────────────────────────
+async function executeAndDisplay(sandboxId, workflowName, options = {}) {
+    const spinner = ora({ text: `  Running ${workflowName}...`, indent: 0 }).start();
+    let result;
+    try {
+        result = await runWorkflow(sandboxId, workflowName);
+        spinner.stop();
+    }
+    catch (err) {
+        spinner.fail(`  Failed to run ${workflowName}`);
+        blank();
+        const errMsg = friendlyError(err);
+        if (errMsg.includes("404") || errMsg.includes("not found") || errMsg.includes("Not found")) {
+            await showAvailableWorkflows(sandboxId, workflowName);
+        }
+        else {
+            fail(errMsg);
+        }
+        blank();
+        process.exit(1);
+    }
+    const totalSteps = result.steps.length;
+    const passedSteps = result.steps.filter((s) => s.status === "passed").length;
+    const workflowLabel = result.flow_description || result.flow_name;
+    heading(`${workflowLabel} (${totalSteps} step${totalSteps === 1 ? "" : "s"})`);
+    blank();
+    for (let i = 0; i < result.steps.length; i++) {
+        const step = result.steps[i];
+        const stepNum = `Step ${i + 1}/${totalSteps}`;
+        const icon = step.status === "passed" ? pc.green("✓") : pc.red("✗");
+        const duration = pc.dim(`${step.duration_ms}ms`);
+        const { method: httpMethod, path } = parseMethodPath(step.detail);
+        if (httpMethod && path) {
+            console.log(`  ${icon} ${pc.dim(stepNum)}  ${methodColor(httpMethod)} ${path}  ${duration}`);
+        }
+        else {
+            console.log(`  ${icon} ${pc.dim(stepNum)}  ${step.name}  ${duration}`);
+        }
+        const detail = formatDetail(step);
+        if (detail) {
+            console.log(`    ${detail}`);
+        }
+        if (options.verbose && Object.keys(step.data).length > 0) {
+            const json = JSON.stringify(step.data, null, 2);
+            for (const line of json.split("\n")) {
+                console.log(`    ${pc.dim(line)}`);
+            }
+        }
+        if (step.name === "webhook_verification") {
+            const matched = (step.data.matched || []);
+            for (const evt of matched) {
+                console.log(`    ${pc.yellow("⚡")} ${evt}`);
+            }
+        }
+    }
+    blank();
+    const totalTime = `${result.total_duration_ms}ms`;
+    if (result.passed) {
+        console.log(`  ${pc.green("✓")} Workflow complete — ${passedSteps}/${totalSteps} steps passed ${pc.dim(`(${totalTime})`)}`);
+    }
+    else {
+        console.log(`  ${pc.red("✗")} Workflow failed at step ${passedSteps + 1}/${totalSteps} ${pc.dim(`(${totalTime})`)}`);
+    }
+    return result;
+}
 // ── Helpers ──────────────────────────────────────────────────────────────
 /** Parse HTTP method and path from step detail string. */
 function parseMethodPath(detail) {

package/dist/constants.d.ts

@@ -1,2 +1,2 @@
 export declare const API_BASE: string;
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.3.1";

package/dist/constants.js

@@ -1,2 +1,2 @@
 export const API_BASE = process.env.FETCHSANDBOX_API_URL ?? "https://fetchsandbox.com";
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.1";

package/dist/index.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import pc from "picocolors";
 import { VERSION } from "./constants.js";
+import { resolveSandboxId } from "./lib/api.js";
 import { generate } from "./commands/generate.js";
 import { showStatus } from "./commands/status.js";
 import { reset } from "./commands/reset.js";
@@ -17,6 +18,23 @@ import { docs } from "./commands/docs.js";
 import { state } from "./commands/state.js";
 import { webhookListen } from "./commands/webhook.js";
 import { run } from "./commands/run.js";
+import { diff } from "./commands/diff.js";
+/** Wraps a handler to resolve sandbox name → ID before calling. */
+function withResolve(fn) {
+    return async (id, ...rest) => {
+        try {
+            const resolved = await resolveSandboxId(id);
+            if (resolved !== id) {
+                console.log(`  ${pc.dim(`→ resolved "${id}" to ${resolved}`)}`);
+            }
+            await fn(resolved, ...rest);
+        }
+        catch (err) {
+            console.error(`\n  ${pc.red("✗")} ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    };
+}
 const program = new Command();
 program
     .name("fetchsandbox")
@@ -33,76 +51,82 @@ program
     .action(list);
 program
     .command("delete <sandbox-id>")
-    .description("Delete a sandbox")
+    .description("Delete a sandbox (accepts name or ID)")
     .option("-f, --force", "Skip confirmation prompt")
-    .action((id, opts) => deleteCmd(id, opts));
+    .action(withResolve((id, opts) => deleteCmd(id, opts)));
 // ── Understand ────────────────────────────────────────────────────────
 program
     .command("endpoints <sandbox-id>")
     .description("List all endpoints (use --search to filter)")
     .option("-s, --search <term>", "Filter by path, summary, or tag")
-    .action((id, opts) => endpoints(id, opts));
+    .action(withResolve((id, opts) => endpoints(id, opts)));
 program
     .command("docs <sandbox-id>")
     .description("Open the docs portal in your browser")
-    .action(docs);
+    .action(withResolve(docs));
 // ── Plan ──────────────────────────────────────────────────────────────
 program
     .command("workflows <sandbox-id>")
     .description("List integration workflows (use --name for detail)")
     .option("-n, --name <name>", "Show detail for a specific workflow")
-    .action((id, opts) => workflows(id, opts));
+    .action(withResolve((id, opts) => workflows(id, opts)));
 // ── Implement ─────────────────────────────────────────────────────────
 program
     .command("request <sandbox-id> <method> <path>")
     .description("Make an API call to the sandbox")
     .option("-d, --data <json>", "Request body (JSON string)")
-    .action((id, method, path, opts) => sendRequest(id, method, path, opts));
+    .action(withResolve((id, method, path, opts) => sendRequest(id, method, path, opts)));
 // ── Prove ─────────────────────────────────────────────────────────────
 program
-    .command("run <sandbox-id> <workflow>")
-    .description("Execute a workflow end-to-end and verify each step")
+    .command("run <sandbox-id> [workflow]")
+    .description("Execute a workflow end-to-end (use --all for every workflow)")
+    .option("--all", "Run all workflows and report summary")
     .option("--scenario <name>", "Run under an error scenario (resets after)")
     .option("--verbose", "Show full response data for each step")
-    .action((id, workflow, opts) => run(id, workflow, opts));
+    .action(withResolve((id, workflow, opts) => run(id, workflow, opts)));
 // ── Test ──────────────────────────────────────────────────────────────
 program
     .command("status <sandbox-id>")
     .description("Show sandbox state, resources, and recent activity")
-    .action(showStatus);
+    .action(withResolve(showStatus));
 program
     .command("logs <sandbox-id>")
     .description("Show request logs (use --follow for live tail)")
     .option("-f, --follow", "Tail logs in real-time")
     .option("--status <code>", "Filter by status code (e.g. 200, 4xx, 5xx)")
     .option("-l, --limit <n>", "Number of log entries (default: 30)")
-    .action((id, opts) => logs(id, opts));
+    .action(withResolve((id, opts) => logs(id, opts)));
 program
     .command("scenario <sandbox-id>")
     .description("List or switch test scenarios")
     .option("-n, --name <name>", "Set active scenario")
-    .action((id, opts) => scenario(id, opts));
+    .action(withResolve((id, opts) => scenario(id, opts)));
 program
     .command("state <sandbox-id> [resource]")
     .description("Inspect resource state (use --id for single record)")
     .option("--id <resource-id>", "Show a single record by ID")
-    .action((id, resource, opts) => state(id, resource, opts));
+    .action(withResolve((id, resource, opts) => state(id, resource, opts)));
 program
     .command("reset <sandbox-id>")
     .description("Reset sandbox to its original seed data")
-    .action(reset);
+    .action(withResolve(reset));
+program
+    .command("diff <sandbox-id>")
+    .description("Show recent mutations and current state summary")
+    .option("--last <n>", "Show only the last N mutations")
+    .action(withResolve((id, opts) => diff(id, opts)));
 // ── Observe ──────────────────────────────────────────────────────────
 program
     .command("webhook-listen <sandbox-id>")
     .description("Live-tail webhook events (Ctrl+C to stop)")
     .option("--verbose", "Show full event payload")
     .option("--event-type <type>", "Filter by event type (e.g. charge.created)")
-    .action((id, opts) => webhookListen(id, opts));
+    .action(withResolve((id, opts) => webhookListen(id, opts)));
 // ── Go Live ───────────────────────────────────────────────────────────
 program
     .command("check <sandbox-id>")
     .description("Run integration readiness check")
-    .action(check);
+    .action(withResolve(check));
 // If no command given, show help with a friendly message
 if (process.argv.length <= 2) {
     console.log();
@@ -124,6 +148,7 @@ if (process.argv.length <= 2) {
     console.log();
     console.log(`  ${pc.dim("Prove:")}`);
     console.log(`  ${pc.white("run <id> <workflow>")}  Run a workflow end-to-end`);
+    console.log(`  ${pc.white("run <id> --all")}      Run every workflow, report summary`);
     console.log();
     console.log(`  ${pc.dim("Test:")}`);
     console.log(`  ${pc.white("status <id>")}        Show sandbox state and activity`);
@@ -131,6 +156,7 @@ if (process.argv.length <= 2) {
     console.log(`  ${pc.white("logs <id>")}          Show request logs (--follow for live)`);
     console.log(`  ${pc.white("scenario <id>")}      List or switch test scenarios`);
     console.log(`  ${pc.white("reset <id>")}         Reset sandbox to seed data`);
+    console.log(`  ${pc.white("diff <id>")}          Show recent mutations + state summary`);
     console.log();
     console.log(`  ${pc.dim("Observe:")}`);
     console.log(`  ${pc.white("webhook-listen <id>")} Live-tail webhook events`);

package/dist/lib/api.d.ts

@@ -110,6 +110,13 @@ export interface SandboxProxyResponse {
     headers: Record<string, string>;
     body: unknown;
 }
+/**
+ * Resolve a sandbox identifier — accepts either a hash ID (beed86d499)
+ * or a name/keyword (stripe, workos, elevenlabs). Name matching is
+ * case-insensitive and matches against spec_name, name, and slug.
+ * Returns the hash ID.
+ */
+export declare function resolveSandboxId(input: string): Promise<string>;
 export declare function uploadSpec(input: string): Promise<SpecResult>;
 export declare function createSandbox(specId: string, name?: string): Promise<SandboxResult>;
 export declare function getSandbox(id: string): Promise<SandboxResult>;

package/dist/lib/api.js

@@ -22,6 +22,38 @@ function githubBlobToRaw(url) {
         .replace("github.com", "raw.githubusercontent.com")
         .replace("/blob/", "/");
 }
+// ── Sandbox ID Resolution ─────────────────────────────────────────────
+/**
+ * Resolve a sandbox identifier — accepts either a hash ID (beed86d499)
+ * or a name/keyword (stripe, workos, elevenlabs). Name matching is
+ * case-insensitive and matches against spec_name, name, and slug.
+ * Returns the hash ID.
+ */
+export async function resolveSandboxId(input) {
+    // If it looks like a hex hash (all hex chars, 8-12 length), use as-is
+    if (/^[a-f0-9]{6,14}$/.test(input))
+        return input;
+    // Otherwise, search by name
+    const sandboxes = await listSandboxes();
+    const lower = input.toLowerCase();
+    // Exact match first (name, spec_name, slug)
+    const exact = sandboxes.find((sb) => sb.name?.toLowerCase() === lower ||
+        sb.spec_name?.toLowerCase() === lower ||
+        sb.slug?.toLowerCase() === lower);
+    if (exact)
+        return exact.id;
+    // Partial match — input appears anywhere in the name
+    const partial = sandboxes.filter((sb) => sb.name?.toLowerCase().includes(lower) ||
+        sb.spec_name?.toLowerCase().includes(lower) ||
+        (sb.slug && sb.slug.toLowerCase().includes(lower)));
+    if (partial.length === 1)
+        return partial[0].id;
+    if (partial.length > 1) {
+        const names = partial.map((sb) => `  • ${sb.id}  ${sb.spec_name || sb.name}`).join("\n");
+        throw new Error(`Multiple sandboxes match "${input}":\n${names}\nUse the full ID to be specific.`);
+    }
+    throw new Error(`No sandbox found matching "${input}". Run \`fetchsandbox list\` to see available sandboxes.`);
+}
 // ── API Functions ──────────────────────────────────────────────────────
 export async function uploadSpec(input) {
     let content;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fetchsandbox",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Turn any OpenAPI spec into a live developer portal with a stateful sandbox",
   "type": "module",
   "bin": {