---
name: erp-kit-mock-scenario
description: Scaffold a new Mockoon mock scenario with CRUD routes, error scenarios, and registry updates
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Mock Scenario Scaffolder

Generate a complete Mockoon mock API config for a new provider scenario and wire it into the registry.

## Version Check

Run `npx erp-kit internal measure versions` from the repo root. If `status` is `"violations"`, relay the findings (each states its own fix) and stop; otherwise proceed.

## Workflow

### Step 1: Identify target API

Ask the user for:

- **Provider name** (e.g. `stripe`, `github`, `twilio`)
- **Scenario name** (e.g. `admin-api`, `payments-api`, `product-sync`)
- **Key resources to mock** (e.g. customers, invoices, messages)
- **Scenario to test** (e.g. initial full sync, incremental sync, webhook-triggered update, error recovery)

### Step 2: Research real API

Use web search to find:

- Base URL and API version
- Authentication scheme (API key, OAuth, bearer token)
- Endpoint patterns and HTTP methods
- Response shapes for the key resources
- Error response format (status codes, error body structure)
- Rate limit headers

### Step 3: Generate Mockoon JSON

Create `mocks/{provider}/{scenario}/mock.json` following the Shopify admin-api mock as the canonical reference (`mocks/shopify/admin-api/mock.json`).

The config must include:

- **uuid**: a valid UUID v4
- **name**: Human-readable API name
- **endpointPrefix**: Match the real API's base path
- **port**: `3000` (overridden at runtime by the reverse proxy launcher)
- **hostname**: `0.0.0.0`
- **latency**: `0`
- **folders**: `[]`
- **rootChildren**: `[]`
- **proxyMode**: `false`
- **proxyHost**: `""`
- **proxyRemovePrefix**: `false`
- **tlsOptions**: `{ "enabled": false, "type": "CERT", "pfxPath": "", "certPath": "", "keyPath": "", "caPath": "", "passphrase": "" }`
- **cors**: `true`
- **headers**: `[{ "key": "Content-Type", "value": "application/json" }]`
- **proxyReqHeaders**: `[]`
- **proxyResHeaders**: `[]`
- **callbacks**: `[]`

All UUIDs (environment, routes, responses, data buckets) must be valid UUID v4 values.

**Data buckets** — for each stateful/CRUD resource:

- 2–3 seed records with realistic field values
- Use the `id` field matching Mockoon's `"id"` property for CRUD lookup

**Routes:**

1. **CRUD routes** — for mutable resources:

   ```json
   {
     "type": "crud",
     "endpoint": "{resource}",
     "responses": [
       {
         "label": "CRUD {Resource}",
         "statusCode": 200,
         "headers": [{ "key": "Content-Type", "value": "application/json" }],
         "bodyType": "DATABUCKET",
         "databucketID": "{resource-bucket-id}"
       }
     ]
   }
   ```

2. **Static routes** — for read-only endpoints:
   - List endpoints returning JSON arrays
   - Single-item endpoints using `{{urlParam 'id'}}` interpolation

3. **Error scenarios** — triggered via `X-Test-Scenario` header:
   - `unauthorized` → 401
   - `not-found` → 404
   - `rate-limit` → 429 with `Retry-After` header
   - `server-error` → 500

4. **Catch-all** — `*` endpoint returning 500 when `X-Test-Scenario: server-error`

**Every route must have:** `type`, `documentation`, `responseMode: null`, `streamingMode: null`, `streamingInterval: 0`

**Every response must have:** `latency: 0`, `bodyType`, `databucketID`, `filePath: ""`, `sendFileAsBody: false`, `rules`, `rulesOperator: "OR"`, `disableTemplating: false`, `fallbackTo404: false`, `default`, `crudKey: "id"`, `callbacks: []`, a `Content-Type` header, and a non-empty `label`

**Every rule must have:** `target`, `modifier`, `value`, `operator`, `invert: false`

### Step 4: Generate scenario README

Create `mocks/{provider}/{scenario}/README.md` with:

- Title and one-line description
- Quick start with both methods: `erp-kit mock start` (proxy) and direct `npx @mockoon/cli start`
- Endpoints table (method, path, scenarios)
- CRUD workflow example with curl commands using proxy URL (`http://localhost:3000/{provider}/{scenario}/...`)
- Error scenario examples
- Test data description

### Step 5: Validate

```bash
npx erp-kit mock validate
```

Fix any failures before finishing.