API Mock Generator

---
name: api-mock
description: >
  Generate realistic mock API responses for a frontend or integration
  scenario. Produces JSON / XML / gRPC payloads with deterministic,
  schema-true data — useful for development without a backend, snapshot
  tests, demos, and offline previews. Use when a downstream API is rate
  limited or down, when seeding Storybook, or when capturing golden
  fixtures for visual regression.
when-to-use:
  - Stubbing an unbuilt backend during frontend work
  - Seeding Storybook / Ladle / Histoire with realistic data
  - Capturing golden fixtures for snapshot tests
  - Powering a demo without leaking real customer data
---

# API Mock Generator

Generate deterministic, schema-true mock payloads on demand so the
front-end can keep moving when the real backend isn't ready.

## Overview

The skill takes a description of the endpoint (path, method, params) plus
an optional schema, and emits one or more realistic responses. It picks
plausible values from Faker-style pools but pins them to a seed so the
output is reproducible across runs — re-running with the same seed
returns byte-identical JSON.

Outputs include:

- The response body, content-type, and status code.
- Suggested response variants for happy path, edge case, and error case.
- Optional latency / failure injection knobs for chaos testing.

## Usage examples

```bash
# Mock one GET endpoint with a JSON:API schema
npx skills run api-mock \
  --method GET \
  --path /api/users/:id \
  --schema schemas/user.json

# Generate a fixed set of fixtures for a Storybook story
npx skills run api-mock \
  --path /api/products \
  --variants empty,single,many,error \
  --seed 42 \
  --format fixtures > src/fixtures/products.ts
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `method` | enum | `GET` | HTTP verb. |
| `path` | string | — | Endpoint, with `:param` placeholders. |
| `schema` | string | — | Path to JSON Schema, OpenAPI fragment, or Zod schema. |
| `variants` | string[] | `happy` | Subset of `happy`, `empty`, `single`, `many`, `error`, `slow`, `flaky`. |
| `seed` | int | `0` | RNG seed; `0` means time-based. |
| `format` | enum | `json` | `json`, `ts`, `msw-handler`, `fetch-mock`. |
| `count` | int | `1` | How many responses to emit per variant. |
| `latency_ms` | int | `0` | Inject this much artificial latency. |

## Expected output

The skill writes one file per variant to the chosen format — JSON files,
TypeScript modules with `as const` types, or an MSW handler you can drop
straight into `setupServer`. A `manifest.json` records the seed, schema
hash, and file paths so a CI step can flag stale fixtures.