fetchsandbox 0.2.0 → 0.3.0

package/dist/commands/run.d.ts

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

package/dist/commands/run.js

@@ -0,0 +1,167 @@
+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 {
+        // 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 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})`)}`);
+        }
+        // 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("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);
+    }
+}
+// ── 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.0";

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.0";

package/dist/index.js

@@ -14,6 +14,9 @@ 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";
 const program = new Command();
 program
     .name("fetchsandbox")
@@ -55,6 +58,13 @@ program
     .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));
+// ── Prove ─────────────────────────────────────────────────────────────
+program
+    .command("run <sandbox-id> <workflow>")
+    .description("Execute a workflow end-to-end and verify each step")
+    .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));
 // ── Test ──────────────────────────────────────────────────────────────
 program
     .command("status <sandbox-id>")
@@ -72,10 +82,22 @@ program
     .description("List or switch test scenarios")
     .option("-n, --name <name>", "Set active scenario")
     .action((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));
 program
     .command("reset <sandbox-id>")
     .description("Reset sandbox to its original seed data")
     .action(reset);
+// ── 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));
 // ── Go Live ───────────────────────────────────────────────────────────
 program
     .command("check <sandbox-id>")
@@ -100,12 +122,19 @@ 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();
     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();
+    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`);
     console.log();

package/dist/lib/api.d.ts

@@ -82,6 +82,29 @@ 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>;
@@ -120,4 +143,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

@@ -93,6 +93,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.0",
   "description": "Turn any OpenAPI spec into a live developer portal with a stateful sandbox",
   "type": "module",
   "bin": {