fetchsandbox 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# fetchsandbox
+
+Turn any OpenAPI spec into a live developer portal with a stateful sandbox.
+
+## Install
+
+```bash
+npm install -g fetchsandbox
+```
+
+Or run directly:
+
+```bash
+npx fetchsandbox generate ./openapi.yaml
+```
+
+## Commands
+
+### `generate <spec>`
+
+Create a portal from an OpenAPI spec file or URL.
+
+```bash
+# From a local file
+fetchsandbox generate ./stripe-openapi.yaml
+
+# From a URL
+fetchsandbox generate https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml
+```
+
+Output:
+
+```
+  Spec loaded: Stripe API v2024-06-20 (327 endpoints)
+  Sandbox created: beed86d499
+  Seed data: 63 resources across 21 types
+
+  Your sandbox is ready:
+
+  API Key    sandbox_3a4f93a4ea3ea857abb88deea90c3fcb
+  Base URL   https://stripe.fetchsandbox.com
+  Portal     https://fetchsandbox.com/docs/stripe
+
+  Try it:
+  curl https://stripe.fetchsandbox.com/v1/customers \
+    -H "api-key: sandbox_3a4f93a4ea3ea857abb88deea90c3fcb"
+```
+
+### `status <sandbox-id>`
+
+Show sandbox state, resources, and recent activity.
+
+```bash
+fetchsandbox status stripe
+```
+
+### `reset <sandbox-id>`
+
+Reset sandbox to its original seed data.
+
+```bash
+fetchsandbox reset stripe
+```
+
+### `list`
+
+List all sandboxes.
+
+```bash
+fetchsandbox list
+```
+
+## Environment
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FETCHSANDBOX_API_URL` | `https://fetchsandbox.com` | API base URL |
+
+## Learn more
+
+- [fetchsandbox.com](https://fetchsandbox.com) - Generate a portal from any OpenAPI spec
+- [Documentation](https://fetchsandbox.com/docs/stripe) - Example: Stripe API portal
+- [GitHub](https://github.com/fetchsandbox) - Source and showcases
+
+## License
+
+MIT

package/dist/commands/generate.d.ts

@@ -0,0 +1 @@
+export declare function generate(specInput: string): Promise<void>;

package/dist/commands/generate.js

@@ -0,0 +1,55 @@
+import ora from "ora";
+import { uploadSpec, createSandbox } from "../lib/api.js";
+import { ok, fail, label, blank, heading, code, friendlyError } from "../lib/output.js";
+import { API_BASE } from "../constants.js";
+export async function generate(specInput) {
+    blank();
+    const spinner = ora({ text: "Loading spec...", indent: 2 }).start();
+    try {
+        // Step 1: Upload spec
+        const spec = await uploadSpec(specInput);
+        spinner.stop();
+        ok(`Spec loaded: ${spec.name} v${spec.version} (${spec.endpoints_count} endpoints)`);
+        // Step 2: Create sandbox
+        const spinner2 = ora({ text: "Creating sandbox...", indent: 2 }).start();
+        const sb = await createSandbox(spec.id);
+        spinner2.stop();
+        ok(`Sandbox created: ${sb.id}`);
+        // Step 3: Show resource stats
+        const totalResources = Object.values(sb.resource_stats).reduce((s, c) => s + c, 0);
+        const typeCount = Object.values(sb.resource_stats).filter(c => c > 0).length;
+        if (totalResources > 0) {
+            ok(`Seed data: ${totalResources} resources across ${typeCount} types`);
+        }
+        // Step 4: Show results
+        blank();
+        heading("Your sandbox is ready:");
+        blank();
+        const apiKey = sb.credentials?.[0]?.api_key || "N/A";
+        const slug = sb.slug || sb.spec_id;
+        const portalUrl = `${API_BASE}/docs/${slug}`;
+        const subdomainBase = sb.slug ? `https://${sb.slug}.fetchsandbox.com` : `${API_BASE}/sandbox/${sb.id}`;
+        label("API Key", apiKey);
+        label("Base URL", subdomainBase);
+        label("Portal", portalUrl);
+        // Step 5: Show curl example
+        blank();
+        heading("Try it:");
+        code([
+            `curl ${subdomainBase}/v1 \\`,
+            `  -H "api-key: ${apiKey}"`,
+        ]);
+        blank();
+        heading("Next steps:");
+        label("Status", `fetchsandbox status ${slug}`);
+        label("Reset", `fetchsandbox reset ${slug}`);
+        label("Portal", portalUrl);
+        blank();
+    }
+    catch (error) {
+        spinner.stop();
+        fail(friendlyError(error));
+        blank();
+        process.exit(1);
+    }
+}

package/dist/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function list(): Promise<void>;

package/dist/commands/list.js

@@ -0,0 +1,31 @@
+import pc from "picocolors";
+import { listSandboxes } from "../lib/api.js";
+import { fail, blank, tableHeader, row, friendlyError } from "../lib/output.js";
+export async function list() {
+    blank();
+    try {
+        const sandboxes = await listSandboxes();
+        if (sandboxes.length === 0) {
+            console.log(`  ${pc.dim("No sandboxes found. Run")} fetchsandbox generate <spec> ${pc.dim("to create one.")}`);
+            blank();
+            return;
+        }
+        const widths = [13, 30, 10, 10];
+        tableHeader(["ID", "Name", "Status", "Endpoints"], widths);
+        for (const sb of sandboxes) {
+            const dot = sb.status === "running" ? pc.green("●") : pc.yellow("●");
+            row([
+                sb.id,
+                (sb.spec_name || sb.name).slice(0, 28),
+                `${dot} ${sb.status}`,
+                String(sb.endpoints_count),
+            ], widths);
+        }
+        blank();
+    }
+    catch (error) {
+        fail(friendlyError(error));
+        blank();
+        process.exit(1);
+    }
+}

package/dist/commands/reset.d.ts

@@ -0,0 +1 @@
+export declare function reset(sandboxId: string): Promise<void>;

package/dist/commands/reset.js

@@ -0,0 +1,21 @@
+import ora from "ora";
+import { resetSandbox } from "../lib/api.js";
+import { ok, fail, blank, friendlyError } from "../lib/output.js";
+export async function reset(sandboxId) {
+    blank();
+    const spinner = ora({ text: "Resetting sandbox...", indent: 2 }).start();
+    try {
+        const result = await resetSandbox(sandboxId);
+        spinner.stop();
+        const total = Object.values(result.resource_stats).reduce((s, c) => s + c, 0);
+        const types = Object.values(result.resource_stats).filter(c => c > 0).length;
+        ok(`Sandbox reset: ${total} resources restored across ${types} types`);
+        blank();
+    }
+    catch (error) {
+        spinner.stop();
+        fail(friendlyError(error));
+        blank();
+        process.exit(1);
+    }
+}

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function showStatus(sandboxId: string): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,54 @@
+import pc from "picocolors";
+import { getSandbox, getSandboxState, getSandboxLogs, validateSandbox } from "../lib/api.js";
+import { fail, blank, heading, label, method, status, timeAgo, friendlyError } from "../lib/output.js";
+export async function showStatus(sandboxId) {
+    blank();
+    try {
+        const [sb, state, logs, val] = await Promise.all([
+            getSandbox(sandboxId),
+            getSandboxState(sandboxId).catch(() => null),
+            getSandboxLogs(sandboxId, 10).catch(() => []),
+            validateSandbox(sandboxId).catch(() => null),
+        ]);
+        // Header
+        const dot = sb.status === "running" ? pc.green("●") : pc.yellow("●");
+        const health = val ? `${Math.round(val.pass_rate)}% healthy` : "";
+        console.log(`  ${pc.bold(sb.spec_name || sb.name)}  ${dot} ${sb.status}  ${pc.dim(health)}`);
+        blank();
+        // Resources
+        const resources = state
+            ? Object.entries(state).filter(([, v]) => Array.isArray(v) && v.length > 0)
+            : Object.entries(sb.resource_stats).filter(([, c]) => c > 0).map(([k, c]) => [k, Array(c).fill(null)]);
+        if (resources.length > 0) {
+            heading("Resources:");
+            for (const [type, items] of resources) {
+                const count = Array.isArray(items) ? items.length : 0;
+                console.log(`  ${pc.dim(String(type).padEnd(25))}${pc.bold(String(count))}`);
+            }
+            blank();
+        }
+        // Recent activity
+        if (logs.length > 0) {
+            heading("Recent activity:");
+            for (const log of logs.slice(0, 8)) {
+                const time = timeAgo(log.timestamp).padEnd(8);
+                const m = method(log.method);
+                const path = log.path.length > 35 ? log.path.slice(0, 35) + "…" : log.path;
+                console.log(`  ${pc.dim(time)}${m} ${path.padEnd(36)} ${status(log.response_status)}  ${pc.dim(log.duration_ms + "ms")}`);
+            }
+            blank();
+        }
+        // Credentials
+        if (sb.credentials?.[0]) {
+            heading("Credentials:");
+            label("API Key", sb.credentials[0].api_key);
+            label("Sandbox ID", sb.id);
+            blank();
+        }
+    }
+    catch (error) {
+        fail(friendlyError(error));
+        blank();
+        process.exit(1);
+    }
+}

package/dist/constants.d.ts

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

package/dist/constants.js

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import pc from "picocolors";
+import { VERSION } from "./constants.js";
+import { generate } from "./commands/generate.js";
+import { showStatus } from "./commands/status.js";
+import { reset } from "./commands/reset.js";
+import { list } from "./commands/list.js";
+const program = new Command();
+program
+    .name("fetchsandbox")
+    .description(pc.dim("Turn any OpenAPI spec into a live developer portal"))
+    .version(VERSION, "-v, --version");
+program
+    .command("generate <spec>")
+    .description("Create a portal from an OpenAPI spec file or URL")
+    .action(generate);
+program
+    .command("status <sandbox-id>")
+    .description("Show sandbox state, resources, and recent activity")
+    .action(showStatus);
+program
+    .command("reset <sandbox-id>")
+    .description("Reset sandbox to its original seed data")
+    .action(reset);
+program
+    .command("list")
+    .description("List all sandboxes")
+    .action(list);
+// If no command given, show help with a friendly message
+if (process.argv.length <= 2) {
+    console.log();
+    console.log(`  ${pc.bold("fetchsandbox")} ${pc.dim(`v${VERSION}`)}`);
+    console.log(`  ${pc.dim("Turn any OpenAPI spec into a live developer portal")}`);
+    console.log();
+    console.log(`  ${pc.dim("Quick start:")}`);
+    console.log(`  ${pc.cyan("fetchsandbox generate ./openapi.yaml")}`);
+    console.log(`  ${pc.cyan("fetchsandbox generate https://api.example.com/openapi.yaml")}`);
+    console.log();
+    console.log(`  ${pc.dim("Commands:")}`);
+    console.log(`  ${pc.white("generate <spec>")}    Create a portal from a spec file or URL`);
+    console.log(`  ${pc.white("status <id>")}        Show sandbox state and recent activity`);
+    console.log(`  ${pc.white("reset <id>")}         Reset sandbox to seed data`);
+    console.log(`  ${pc.white("list")}               List all sandboxes`);
+    console.log();
+    console.log(`  ${pc.dim("Learn more:")} ${pc.cyan("https://fetchsandbox.com")}`);
+    console.log();
+    process.exit(0);
+}
+program.parse();

package/dist/lib/api.d.ts

@@ -0,0 +1,47 @@
+export interface SpecResult {
+    id: string;
+    name: string;
+    version: string;
+    endpoints_count: number;
+}
+export interface SandboxResult {
+    id: string;
+    name: string;
+    status: string;
+    spec_id: string;
+    spec_name: string;
+    slug?: string;
+    base_url: string;
+    active_scenario: string;
+    endpoints_count: number;
+    resource_stats: Record<string, number>;
+    credentials: Array<{
+        api_key: string;
+        api_secret: string;
+    }>;
+    created_at: string;
+}
+export interface LogEntry {
+    id: string;
+    method: string;
+    path: string;
+    response_status: number;
+    duration_ms: number;
+    timestamp: 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>;
+export declare function listSandboxes(): Promise<SandboxResult[]>;
+export declare function getSandboxState(id: string): Promise<Record<string, unknown[]>>;
+export declare function getSandboxLogs(id: string, limit?: number): Promise<LogEntry[]>;
+export declare function resetSandbox(id: string): Promise<{
+    status: string;
+    resource_stats: Record<string, number>;
+}>;
+export declare function validateSandbox(id: string): Promise<{
+    total: number;
+    passed: number;
+    failed: number;
+    pass_rate: number;
+}>;

package/dist/lib/api.js

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { API_BASE } from "../constants.js";
+// ── Helpers ────────────────────────────────────────────────────────────
+async function request(path, options) {
+    const url = `${API_BASE}${path}`;
+    const res = await fetch(url, options);
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`${res.status}: ${body.slice(0, 200)}`);
+    }
+    if (res.status === 204)
+        return undefined;
+    return res.json();
+}
+function isUrl(input) {
+    return input.startsWith("http://") || input.startsWith("https://");
+}
+function githubBlobToRaw(url) {
+    // Convert GitHub blob URLs to raw content URLs
+    return url
+        .replace("github.com", "raw.githubusercontent.com")
+        .replace("/blob/", "/");
+}
+// ── API Functions ──────────────────────────────────────────────────────
+export async function uploadSpec(input) {
+    let content;
+    let filename;
+    if (isUrl(input)) {
+        const url = input.includes("github.com") && input.includes("/blob/")
+            ? githubBlobToRaw(input)
+            : input;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`Failed to fetch spec from URL: ${res.status}`);
+        content = await res.text();
+        filename = basename(new URL(url).pathname) || "openapi.yaml";
+    }
+    else {
+        content = readFileSync(input, "utf-8");
+        filename = basename(input);
+    }
+    const name = filename.replace(/\.(yaml|yml|json)$/i, "");
+    const form = new FormData();
+    form.append("name", name);
+    form.append("spec_content", new Blob([content], { type: "application/x-yaml" }), filename);
+    return request("/api/specs", { method: "POST", body: form });
+}
+export async function createSandbox(specId, name) {
+    return request("/api/sandboxes", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ spec_id: specId, name: name || "", scenario: "default" }),
+    });
+}
+export async function getSandbox(id) {
+    return request(`/api/sandboxes/${id}`);
+}
+export async function listSandboxes() {
+    return request("/api/sandboxes");
+}
+export async function getSandboxState(id) {
+    return request(`/api/sandboxes/${id}/state`);
+}
+export async function getSandboxLogs(id, limit = 10) {
+    return request(`/api/sandboxes/${id}/logs?limit=${limit}`);
+}
+export async function resetSandbox(id) {
+    return request(`/api/sandboxes/${id}/reset`, { method: "POST" });
+}
+export async function validateSandbox(id) {
+    return request(`/api/sandboxes/${id}/validate`);
+}

package/dist/lib/output.d.ts

@@ -0,0 +1,14 @@
+export declare const ok: (msg: string) => void;
+export declare const fail: (msg: string) => void;
+export declare const warn: (msg: string) => void;
+export declare const info: (msg: string) => void;
+export declare const blank: () => void;
+export declare const label: (key: string, val: string) => void;
+export declare const heading: (msg: string) => void;
+export declare const code: (lines: string[]) => void;
+export declare const row: (cols: string[], widths: number[]) => void;
+export declare const tableHeader: (cols: string[], widths: number[]) => void;
+export declare const method: (m: string) => string;
+export declare const status: (code: number) => string;
+export declare const timeAgo: (ts: string) => string;
+export declare const friendlyError: (error: unknown) => string;

package/dist/lib/output.js

@@ -0,0 +1,78 @@
+import pc from "picocolors";
+// ── Core output primitives ─────────────────────────────────────────────
+// Every line is indented 2 spaces for visual breathing room.
+// Colors aid comprehension, never decoration.
+export const ok = (msg) => console.log(`  ${pc.green("✓")} ${msg}`);
+export const fail = (msg) => console.log(`  ${pc.red("✗")} ${msg}`);
+export const warn = (msg) => console.log(`  ${pc.yellow("!")} ${msg}`);
+export const info = (msg) => console.log(`  ${pc.dim(msg)}`);
+export const blank = () => console.log();
+// Key-value pair with aligned labels
+export const label = (key, val) => console.log(`  ${pc.dim(key.padEnd(11))}${val}`);
+// Section header
+export const heading = (msg) => console.log(`  ${pc.bold(msg)}`);
+// Code block (for curl examples etc.)
+export const code = (lines) => {
+    for (const line of lines) {
+        console.log(`  ${pc.cyan(line)}`);
+    }
+};
+// Table row
+export const row = (cols, widths) => {
+    const formatted = cols.map((c, i) => c.padEnd(widths[i] || 15)).join("");
+    console.log(`  ${formatted}`);
+};
+// Table header
+export const tableHeader = (cols, widths) => {
+    const formatted = cols.map((c, i) => pc.dim(c.padEnd(widths[i] || 15))).join("");
+    console.log(`  ${formatted}`);
+};
+// Method pill (colored like the web UI)
+export const method = (m) => {
+    const colors = {
+        GET: pc.blue,
+        POST: pc.green,
+        PUT: pc.yellow,
+        PATCH: pc.magenta,
+        DELETE: pc.red,
+    };
+    return (colors[m] || pc.dim)(m.padEnd(6));
+};
+// Status code (colored)
+export const status = (code) => {
+    if (code < 300)
+        return pc.green(String(code));
+    if (code < 500)
+        return pc.yellow(String(code));
+    return pc.red(String(code));
+};
+// Relative time
+export const timeAgo = (ts) => {
+    const diff = Date.now() - new Date(ts).getTime();
+    if (diff < 10000)
+        return "now";
+    if (diff < 60000)
+        return `${Math.floor(diff / 1000)}s ago`;
+    if (diff < 3600000)
+        return `${Math.floor(diff / 60000)}m ago`;
+    if (diff < 86400000)
+        return `${Math.floor(diff / 3600000)}h ago`;
+    return new Date(ts).toLocaleDateString();
+};
+// Friendly error — never show stack traces to users
+export const friendlyError = (error) => {
+    if (error instanceof Error) {
+        if (error.message.includes("ECONNREFUSED"))
+            return "Cannot connect to FetchSandbox API. Is the server running?";
+        if (error.message.includes("ENOTFOUND"))
+            return "Cannot resolve FetchSandbox API hostname. Check your internet connection.";
+        if (error.message.includes("401"))
+            return "Authentication failed. Check your API key.";
+        if (error.message.includes("404"))
+            return "Not found. Check the sandbox ID.";
+        if (error.message.includes("413"))
+            return "Spec file too large. Maximum size is 5 MB.";
+        return error.message;
+    }
+    return String(error);
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "fetchsandbox",
+  "version": "0.1.0",
+  "description": "Turn any OpenAPI spec into a live developer portal with a stateful sandbox",
+  "type": "module",
+  "bin": {
+    "fetchsandbox": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fetchsandbox/cli"
+  },
+  "homepage": "https://fetchsandbox.com",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["openapi", "sandbox", "api", "developer-portal", "mock", "testing", "api-testing", "mock-server", "openapi-tools"],
+  "author": "FetchSandbox",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "ora": "^8.0.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}