fetchsandbox 0.2.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

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

package/dist/commands/run.js

@@ -0,0 +1,231 @@
+import pc from "picocolors";
+import ora from "ora";
+import { runWorkflow, getWorkflows, getSandbox, setScenario } from "../lib/api.js";
+import { fail, blank, heading, info, method as methodColor, friendlyError } from "../lib/output.js";
+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();
+            try {
+                await setScenario(sandboxId, options.scenario);
+                spinner.succeed(`  Scenario: ${options.scenario}`);
+            }
+            catch (err) {
+                spinner.fail(`  Failed to set scenario: ${friendlyError(err)}`);
+                blank();
+                process.exit(1);
+            }
+        }
+        // Run the workflow
+        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.`);
+            info("This confirms your error handling works.");
+        }
+        blank();
+        // Reset scenario back to default if we changed it
+        if (options.scenario) {
+            try {
+                await setScenario(sandboxId, "default");
+                info("Scenario reset to default.");
+                blank();
+            }
+            catch {
+                // Silent — best effort reset
+            }
+        }
+        // Exit with appropriate code
+        if (!result.passed && !options.scenario) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        fail(friendlyError(error));
+        blank();
+        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) {
+    const match = detail.match(/^(GET|POST|PUT|PATCH|DELETE|HEAD)\s+(\S+)/);
+    if (match) {
+        return { method: match[1], path: match[2] };
+    }
+    return { method: "", path: "" };
+}
+/** Format a human-readable detail line from step data. */
+function formatDetail(step) {
+    if (step.status === "failed") {
+        return pc.red(step.detail);
+    }
+    // Extract meaningful info from data
+    const id = step.data.id || step.data.resource_id || "";
+    const status = step.data.status || "";
+    const responseStatus = step.data.response_status;
+    const parts = [];
+    if (responseStatus)
+        parts.push(`→ ${pc.green(String(responseStatus))}`);
+    if (id)
+        parts.push(pc.white(String(id)));
+    if (status)
+        parts.push(pc.dim(`status: ${status}`));
+    return parts.length > 0 ? parts.join("  ") : "";
+}
+/** Show available workflows when one isn't found. */
+async function showAvailableWorkflows(sandboxId, attempted) {
+    fail(`Workflow "${attempted}" not found.`);
+    try {
+        const sb = await getSandbox(sandboxId);
+        const { workflows } = await getWorkflows(sb.spec_id);
+        if (workflows.length > 0) {
+            blank();
+            info("Available workflows:");
+            for (const wf of workflows) {
+                const id = wf.id || wf.name;
+                console.log(`  ${pc.dim("•")} ${id}`);
+            }
+            blank();
+            info(`Try: fetchsandbox run ${sandboxId} "${workflows[0].id || workflows[0].name}"`);
+        }
+    }
+    catch {
+        // Silent — best effort
+    }
+}

package/dist/commands/state.d.ts

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

package/dist/commands/state.js

@@ -0,0 +1,135 @@
+import pc from "picocolors";
+import { getSandboxState } from "../lib/api.js";
+import { fail, blank, heading, info, row, tableHeader, friendlyError } from "../lib/output.js";
+export async function state(sandboxId, resource, options = {}) {
+    blank();
+    try {
+        const snapshot = await getSandboxState(sandboxId);
+        const types = Object.entries(snapshot).filter(([, records]) => Array.isArray(records) && records.length > 0);
+        if (types.length === 0) {
+            info("No resources in this sandbox. Run some requests first.");
+            blank();
+            return;
+        }
+        // ── Single resource type ──────────────────────────────────────────
+        if (resource) {
+            const records = snapshot[resource];
+            if (!records || !Array.isArray(records) || records.length === 0) {
+                const available = types.map(([t]) => t).join(", ");
+                fail(`No resource type "${resource}" found.`);
+                info(`Available: ${available}`);
+                blank();
+                return;
+            }
+            // Single record by --id
+            if (options.id) {
+                const typedRecords = records;
+                const record = typedRecords.find((r) => r.id === options.id || r.ID === options.id);
+                if (!record) {
+                    fail(`No record with id "${options.id}" in ${resource}.`);
+                    info(`${records.length} records available. Try without --id to list all.`);
+                    blank();
+                    return;
+                }
+                heading(`${resource} / ${options.id}`);
+                blank();
+                console.log(formatJson(record));
+                blank();
+                return;
+            }
+            // Table view for all records of this type
+            heading(`${resource} — ${records.length} record${records.length === 1 ? "" : "s"}`);
+            blank();
+            const cols = pickColumns(records);
+            const widths = cols.map((c) => Math.max(c.length + 2, Math.min(30, maxWidth(records, c) + 2)));
+            tableHeader(cols, widths);
+            for (const record of records) {
+                const values = cols.map((c) => truncate(String(record[c] ?? ""), widths[cols.indexOf(c)] - 2));
+                row(values, widths);
+            }
+            blank();
+            return;
+        }
+        // ── Summary of all resource types ─────────────────────────────────
+        heading(`State snapshot — ${types.length} resource type${types.length === 1 ? "" : "s"}, ${types.reduce((sum, [, r]) => sum + r.length, 0)} records`);
+        blank();
+        for (const [type, records] of types) {
+            const items = records;
+            const dist = stateDistribution(items);
+            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 <sandbox> <resource> to see records");
+        blank();
+    }
+    catch (error) {
+        fail(friendlyError(error));
+        blank();
+        process.exit(1);
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+/** Pick the most useful columns to display in a table. */
+function pickColumns(records) {
+    if (records.length === 0)
+        return [];
+    const allKeys = Object.keys(records[0]);
+    // Priority: id first, then status, then name/email/type, then rest
+    const priority = ["id", "ID", "status", "state", "name", "email", "type", "amount", "currency", "description"];
+    const picked = [];
+    for (const key of priority) {
+        if (allKeys.includes(key) && !picked.includes(key)) {
+            picked.push(key);
+        }
+    }
+    // Fill up to 5 columns with remaining keys (skip large objects/arrays)
+    for (const key of allKeys) {
+        if (picked.length >= 5)
+            break;
+        if (picked.includes(key))
+            continue;
+        const sample = records[0][key];
+        if (typeof sample === "object" && sample !== null)
+            continue; // skip nested
+        picked.push(key);
+    }
+    return picked;
+}
+/** Get the max display width of a column across all records. */
+function maxWidth(records, key) {
+    let max = key.length;
+    for (const r of records) {
+        const len = String(r[key] ?? "").length;
+        if (len > max)
+            max = len;
+    }
+    return Math.min(max, 28);
+}
+/** Truncate a string to fit a column width. */
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+/** Compute state/status distribution string, e.g. "2 active, 1 suspended". */
+function stateDistribution(records) {
+    const field = records[0]?.status !== undefined ? "status" : records[0]?.state !== undefined ? "state" : null;
+    if (!field)
+        return "";
+    const counts = {};
+    for (const r of records) {
+        const val = String(r[field] ?? "unknown");
+        counts[val] = (counts[val] || 0) + 1;
+    }
+    return Object.entries(counts)
+        .sort(([, a], [, b]) => b - a)
+        .map(([val, count]) => `${count} ${val}`)
+        .join(", ");
+}
+/** Pretty-print a JSON object with 2-space indent, indented for CLI output. */
+function formatJson(obj) {
+    return JSON.stringify(obj, null, 2)
+        .split("\n")
+        .map((line) => `  ${pc.white(line)}`)
+        .join("\n");
+}

package/dist/commands/webhook.d.ts

@@ -0,0 +1,4 @@
+export declare function webhookListen(sandboxId: string, options?: {
+    verbose?: boolean;
+    eventType?: string;
+}): Promise<void>;

package/dist/commands/webhook.js

@@ -0,0 +1,111 @@
+import pc from "picocolors";
+import { getWebhookEvents } from "../lib/api.js";
+import { fail, blank, heading, info, friendlyError } from "../lib/output.js";
+export async function webhookListen(sandboxId, options = {}) {
+    blank();
+    try {
+        heading("Listening for webhook events... (Ctrl+C to stop)");
+        blank();
+        let lastSeen = "";
+        let totalShown = 0;
+        const poll = async () => {
+            const events = await getWebhookEvents(sandboxId, 30);
+            // Filter to only new events (same dedup pattern as logs --follow)
+            const newEvents = lastSeen
+                ? events.filter((e) => e.timestamp > lastSeen)
+                : events;
+            if (newEvents.length === 0)
+                return;
+            // Update watermark — events are newest-first from API
+            lastSeen = newEvents[0].timestamp;
+            // Display oldest-first for natural reading order
+            const ordered = [...newEvents].reverse();
+            for (const event of ordered) {
+                // Optional event type filter
+                if (options.eventType && !event.event_type.includes(options.eventType)) {
+                    continue;
+                }
+                const time = formatTime(event.timestamp);
+                const type = colorEventType(event.event_type);
+                const resourceId = extractResourceId(event.payload);
+                const statusField = extractStatus(event.payload);
+                console.log(`  ${pc.dim(time)}  ${type}  ${pc.white(resourceId)}${statusField}`);
+                if (options.verbose && event.payload) {
+                    const json = JSON.stringify(event.payload, null, 2);
+                    for (const line of json.split("\n")) {
+                        console.log(`  ${pc.dim("          ")}${pc.dim(line)}`);
+                    }
+                }
+                totalShown++;
+            }
+        };
+        // Initial poll
+        await poll();
+        if (totalShown === 0) {
+            info("No events yet. Make API calls in another terminal to see webhooks fire.");
+        }
+        // Poll every 2 seconds
+        const interval = setInterval(async () => {
+            try {
+                await poll();
+            }
+            catch {
+                // Silently retry on transient errors during polling
+            }
+        }, 2000);
+        process.on("SIGINT", () => {
+            clearInterval(interval);
+            blank();
+            if (totalShown > 0) {
+                console.log(`  ${pc.dim(`${totalShown} event${totalShown === 1 ? "" : "s"} received.`)}`);
+            }
+            blank();
+            process.exit(0);
+        });
+        // Keep alive
+        await new Promise(() => { });
+    }
+    catch (error) {
+        fail(friendlyError(error));
+        blank();
+        process.exit(1);
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+/** Format ISO timestamp to HH:MM:SS. */
+function formatTime(ts) {
+    try {
+        const d = new Date(ts);
+        return d.toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+    }
+    catch {
+        return ts.slice(11, 19);
+    }
+}
+/** Color event type based on action. */
+function colorEventType(eventType) {
+    const padded = eventType.padEnd(30);
+    if (eventType.includes("created"))
+        return pc.green(padded);
+    if (eventType.includes("succeeded") || eventType.includes("completed"))
+        return pc.green(padded);
+    if (eventType.includes("failed") || eventType.includes("declined"))
+        return pc.red(padded);
+    if (eventType.includes("deleted") || eventType.includes("canceled"))
+        return pc.red(padded);
+    if (eventType.includes("updated") || eventType.includes("captured"))
+        return pc.yellow(padded);
+    return pc.white(padded);
+}
+/** Extract the resource ID from a webhook payload. */
+function extractResourceId(payload) {
+    const id = payload?.id ?? payload?.ID ?? "";
+    return id ? String(id) : "";
+}
+/** Extract a status-like field from payload for compact display. */
+function extractStatus(payload) {
+    const status = payload?.status ?? payload?.state ?? null;
+    if (!status)
+        return "";
+    return pc.dim(` → ${status}`);
+}

package/dist/constants.d.ts

@@ -1,2 +1,2 @@
 export declare const API_BASE: string;
-export declare const VERSION = "0.2.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.2.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";
@@ -14,6 +15,26 @@ import { logs } from "./commands/logs.js";
 import { scenario } from "./commands/scenario.js";
 import { deleteCmd } from "./commands/delete.js";
 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")
@@ -30,57 +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 (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(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(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(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();
@@ -100,11 +146,20 @@ if (process.argv.length <= 2) {
     console.log(`  ${pc.dim("Implement:")}`);
     console.log(`  ${pc.white("request <id> <method> <path>")}  Make an API call`);
     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`);
+    console.log(`  ${pc.white("state <id> [type]")}   Inspect resource data (--id for single)`);
     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`);
     console.log();
     console.log(`  ${pc.dim("Go Live:")}`);
     console.log(`  ${pc.white("check <id>")}         Integration readiness score`);

package/dist/lib/api.d.ts

@@ -82,11 +82,41 @@ export interface WebhookRegistration {
     enabled: boolean;
     created_at: string;
 }
+export interface WebhookEvent {
+    id: string;
+    event_type: string;
+    timestamp: string;
+    payload: Record<string, unknown>;
+    delivered: boolean;
+    delivery_status: number;
+}
+export interface WorkflowRunStep {
+    name: string;
+    description: string;
+    status: "pending" | "passed" | "failed";
+    detail: string;
+    duration_ms: number;
+    data: Record<string, unknown>;
+}
+export interface WorkflowRunResult {
+    flow_name: string;
+    flow_description: string;
+    passed: boolean;
+    total_duration_ms: number;
+    steps: WorkflowRunStep[];
+}
 export interface SandboxProxyResponse {
     status: number;
     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>;
@@ -120,4 +150,6 @@ export declare function setScenario(sandboxId: string, scenario: string): Promis
 }>;
 export declare function deleteSandbox(id: string): Promise<void>;
 export declare function getWebhooks(sandboxId: string): Promise<WebhookRegistration[]>;
+export declare function getWebhookEvents(sandboxId: string, limit?: number): Promise<WebhookEvent[]>;
+export declare function runWorkflow(sandboxId: string, workflowName: string): Promise<WorkflowRunResult>;
 export declare function sandboxRequest(sandboxId: string, method: string, path: string, body?: string, apiKey?: string): Promise<SandboxProxyResponse>;

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;
@@ -93,6 +125,14 @@ export async function deleteSandbox(id) {
 export async function getWebhooks(sandboxId) {
     return request(`/api/sandboxes/${sandboxId}/webhooks`);
 }
+export async function getWebhookEvents(sandboxId, limit = 50) {
+    return request(`/api/sandboxes/${sandboxId}/webhooks/events?limit=${limit}`);
+}
+export async function runWorkflow(sandboxId, workflowName) {
+    return request(`/api/sandboxes/${sandboxId}/workflows/${encodeURIComponent(workflowName)}/run`, {
+        method: "POST",
+    });
+}
 export async function sandboxRequest(sandboxId, method, path, body, apiKey) {
     // Use the path-based proxy: /sandbox/{id}/{path}
     const sandboxPath = path.startsWith("/") ? path : `/${path}`;

package/package.json

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