# api-mocker

Intelligent API mocking & fake-data microservice: turn a JSON Schema into realistic example instances (mockFromSchema), stand up a mock REST endpoint response envelope with N seeded rows...


Intelligent API mocking & fake-data microservice. Turn a JSON Schema or a `{ field: type }` spec into
realistic example data, mock REST response envelopes, seed datasets/fixtures, and canonical HTTP
status scenarios (200 / 4xx / 5xx bodies). Deterministic and seedable — great for prototyping
frontends, stubbing backends, contract tests, and demo data.

## Tools

| Tool | Purpose |
|---|---|
| `mockFromSchema` | JSON Schema → one realistic example instance (or N with `count`). Optional LLM enrichment via `options.enrich`. |
| `mockEndpoint` | A full mock REST response: N seeded rows from a schema wrapped with pagination `meta` + self link. |
| `fakeRecord` | One fake record from a `{ field: type }` spec. |
| `generateDataset` | A whole seed dataset / fixture table (rows + summary; optional CSV via `options.format:'csv'`). |
| `statusScenarios` | Canonical HTTP status responses with realistic JSON bodies for error-handling tests. |

### Field-type tokens (for `fields`)

`name`, `firstName`, `lastName`, `username`, `email`, `phone`, `uuid`, `id`, `url`, `image`, `ip`,
`city`, `address`, `company`, `country`, `zip`, `role`, `status`, `tag`, `color`, `bool`, `date`,
`datetime`, `price`, `currency`, `int:18-90`, `float:0-1`, `enum:admin|user|guest`, `string:12`,
`sentence`, `paragraph`, `slug`, `word`. Nested objects and `[elementType, count]` arrays are supported.

## Usage

```js
import mocker from './index.js';

// Fake records from a spec
mocker.adapters.fakeRecord({ fields: { id: 'uuid', name: 'name', email: 'email', role: 'enum:admin|user', age: 'int:18-90' }, seed: 1 });

// Seed dataset (10 rows) + CSV
mocker.adapters.generateDataset({ fields: { id: 'id', title: 'sentence', price: 'price' }, count: 10, seed: 2, options: { format: 'csv' } });

// Mock endpoint from a JSON Schema
mocker.adapters.mockEndpoint({ schema: { type: 'object', properties: { id: { type: 'integer' }, name: { type: 'string' } }, required: ['id', 'name'] }, count: 3, resource: 'users' });

// HTTP status scenarios
mocker.adapters.statusScenarios({ statuses: [200, 404, 422, 500], resource: 'user' });
```

## Hybrid intelligence

Every tool has a deterministic, offline heuristic core (seedable PRNG + field-type faker). `mockFromSchema`
additionally supports an optional LLM path (`options.enrich: true`) that asks a reachable model to fill
domain-plausible values; if no model is configured/reachable it silently falls back to the heuristic.
Results are tagged `{ mode: 'heuristic' | 'llm' }`. No tool ever requires a model.

## DRY boundaries

- **`schema`** owns real JSON-Schema authoring/validation/diff/merge/TS-emit. This pack reuses the
  schema→instance *concept* with a compact self-contained generator; it does not import `schema`.
- **`lorem`** owns themed placeholder prose and simple fake people. This pack has its own small faker
  banks tuned for API fixtures (roles, statuses, prices, endpoints); it does not import `lorem`.

Only cross-pack import: `../_shared/llm.js`.


---
Source: shared/engines/adapters/domain/api-mocker/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/api-mocker