@yolk-sdk/emulators 0.1.0-canary.96

package/src/todoist.ts

@@ -0,0 +1,316 @@
+/**
+ * Stateful Todoist emulator (API v1 under `https://api.todoist.com/api/v1`), built on the upstream
+ * `@emulators/core` custom runtime, with a request ledger, status faults, and an `/_emulate/*`
+ * control plane.
+ *
+ * Fixture-only: it never imports SDK code; its wire shapes and default seed are copied as data
+ * from the synthetic Todoist conformance fixtures, and every route names the conformance cases it
+ * follows in `todoistEmulatorRoutes`. Only the routes the seven Todoist cases (with their cleanup)
+ * need are emulated; anything the fixtures do not record answers one ledgered 400
+ * `{ error: { type: 'not_emulated', message } }`. That includes the project listing of the
+ * read-only leftover lookup (`findTodoistConformanceLeftovers`), which no fixture records: the
+ * lookup fails (`todoist_list_projects_failed`, HTTP 400), and runners print their lookup-failed
+ * WARN instead of leftover warnings.
+ *
+ * Fail closed: a request on no emulated route (or with a raw id segment that is not a Todoist id)
+ * is ledgered and answered with constant text only (`/<unrecognised>`, a standard method or
+ * `<other>`, no query or body, a constant reason). So is a request whose `Authorization` header is
+ * present but is not one recognisable bearer, whatever its route: its credential cannot be
+ * extracted and scrubbed.
+ *
+ * No answer is synthesised: a seeded project (whose object no fixture records) answers
+ * not-emulated on a read; only items created through the recorded create flow are updated,
+ * closed, or deleted; a case project takes one task and a seeded parent one sub-project (the
+ * fixtures record `child_order: 1` only). Minted ids use the reserved prefix `6XEmu`, which seeds
+ * may not use. The bearer value is guarded like the Telegram token: scrubbed from everything
+ * ledgered or answered, and a path, query, or body that repeats it is refused.
+ *
+ * Request-shape latitude (the only accepted deviations from the fixture requests): any credential
+ * value of at least 8 characters that occurs nowhere else in the request (its path, query, or body;
+ * never checked against anything, stored, or ledgered); extra request headers; `content-type`
+ * parameters; query parameters in any order; any Todoist id (1-64 of `[A-Za-z0-9_-]`) of an
+ * existing item where a fixture has an id (reads: seeded or created tasks and created projects;
+ * task listings: the paging project with `limit=2` and case projects created here without `limit`;
+ * writes: only items created through the recorded create flow; a new project's `parent_id`: a
+ * seeded project); any `run-` run id (at most 40 characters) in a case project name; any non-empty
+ * task `content`; a task update sending `content`, `due_datetime`, or both; a label listing `limit`
+ * of 1 to 200 that covers every label.
+ *
+ * Node-only: `@emulators/core` imports Node builtins, so the core is loaded lazily by
+ * `makeTodoistEmulator` (importing this module has no side effects).
+ *
+ * @experimental
+ */
+import { Data, Predicate } from 'effect'
+import type { EmulatorRouteEvidence } from './route-evidence.ts'
+import { statefulCoreRuntime } from './stateful-core.ts'
+import {
+  makeHeaderlessStatefulEmulator,
+  routeEvidence,
+  type StatefulCoverage,
+  type StatefulFault,
+  type StatefulFaultState,
+  type StatefulHeaderlessLedgerEntry,
+  type StatefulErrorTexts,
+  type StatefulInputKind,
+  type StatefulResolution
+} from './stateful-emulator.ts'
+import {
+  matchTodoistRoute,
+  todoistApiRoutes,
+  todoistQueryProblem,
+  type TodoistApiEnv,
+  type TodoistCursor,
+  type TodoistEmulatorDrills
+} from './todoist/api.ts'
+import {
+  buildTodoistSeedState,
+  decodeTodoistState,
+  type TodoistEmulatorSeed,
+  type TodoistEmulatorState
+} from './todoist/state.ts'
+
+export type { EmulatorEvidence, EmulatorRouteEvidence } from './route-evidence.ts'
+
+export { emulatorEvidenceHeader } from './route-evidence.ts'
+
+export {
+  StatefulFault as TodoistFault,
+  StatefulFaultMatch as TodoistFaultMatch
+} from './stateful-emulator.ts'
+
+export { todoistEmulatorBasePath, type TodoistEmulatorDrills } from './todoist/api.ts'
+
+export {
+  TodoistEmulatorDue,
+  TodoistEmulatorLabel,
+  TodoistEmulatorProfile,
+  TodoistEmulatorProject,
+  TodoistEmulatorProjectSeed,
+  TodoistEmulatorSeed,
+  TodoistEmulatorStateSchema,
+  TodoistEmulatorTask,
+  TodoistEmulatorTaskSeed,
+  type TodoistEmulatorState
+} from './todoist/state.ts'
+
+/** Origin the connector calls. */
+export const todoistEmulatorDefaultOrigin = 'https://api.todoist.com'
+
+/**
+ * Route evidence manifest: every emulated route, whether it writes, and the conformance cases
+ * whose (currently synthetic, unverified) wire claims it follows. Kept in sync with the handlers
+ * by construction (both come from one route table). Every route cites at least one case.
+ */
+export const todoistEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence> = todoistApiRoutes.map(
+  ({ route }) => routeEvidence(route)
+)
+
+export type TodoistFaultState = StatefulFaultState
+
+export type TodoistLedgerEntry = StatefulHeaderlessLedgerEntry
+
+export type TodoistCoverage = StatefulCoverage
+
+/** Invalid emulator input from the JS API: a seed or a fault. A programmer error. */
+export class TodoistEmulatorInputInvalid extends Data.TaggedError('TodoistEmulatorInputInvalid')<{
+  readonly input: 'seed' | 'fault'
+  readonly reason: string
+}> {
+  override get message(): string {
+    return `Invalid Todoist emulator ${this.input}: ${this.reason}`
+  }
+}
+
+export type TodoistEmulatorOptions = {
+  /** Typed seed; defaults to the fixture entities (`profile: 'default'`). */
+  readonly seed?: TodoistEmulatorSeed
+  /** Clock in epoch milliseconds (created and closed timestamps). Defaults to `Date.now`. */
+  readonly now?: () => number
+  /** Drill knobs (tests only): make the emulator disagree with one conformance claim. */
+  readonly drills?: TodoistEmulatorDrills
+}
+
+export type TodoistEmulator = {
+  /** The fetch handler (Todoist routes and `/_emulate/*`). Never rejects. */
+  readonly fetch: (request: Request) => Promise<Response>
+  readonly ledger: {
+    readonly entries: () => ReadonlyArray<TodoistLedgerEntry>
+    readonly clear: () => void
+  }
+  readonly faults: {
+    /** Add a fault; throws `TodoistEmulatorInputInvalid` for an invalid fault. */
+    readonly add: (fault: StatefulFault) => TodoistFaultState
+    readonly list: () => ReadonlyArray<TodoistFaultState>
+    readonly clear: () => void
+  }
+  /** Task-listing cursors answered since the last reset or seed (runtime data). */
+  readonly cursors: () => ReadonlyArray<TodoistCursor>
+  /** Restore the current seed and clear the ledger, faults, and cursors. */
+  readonly reset: () => Promise<void>
+  /**
+   * Replace the state with a new seed, which becomes what `reset` restores (cursors are cleared).
+   * Rejects with `TodoistEmulatorInputInvalid` for an invalid seed.
+   */
+  readonly seed: (seed: TodoistEmulatorSeed) => Promise<void>
+  /** A deep copy of the current state (entities and counters). */
+  readonly snapshot: () => TodoistEmulatorState
+  readonly coverage: () => TodoistCoverage
+  /** Close the core runtime. Later requests answer 503. Idempotent. */
+  readonly close: () => Promise<void>
+}
+
+// A bearer credential of at least 8 characters. The value is never checked against anything,
+// stored, forwarded, or ledgered; it is guarded like the Telegram token: a path, query, or body
+// that repeats it is refused, and it is scrubbed from everything ledgered or answered.
+const bearerPattern = /^bearer\s+(\S{8,})\s*$/i
+
+const resolve = (
+  request: Request,
+  url: URL
+): StatefulResolution<TodoistEmulatorState, TodoistApiEnv> => {
+  const ledgerPath = url.pathname
+  const authorization = request.headers.get('authorization')
+  const bearer = bearerPattern.exec(authorization ?? '')?.[1]
+
+  // Fail closed: an Authorization header that is present but not one recognisable bearer (extra
+  // words, duplicated headers) means the credential cannot be extracted and scrubbed, so the
+  // request is ledgered and answered with constant text only, whatever the route.
+  if (authorization !== null && bearer === undefined) {
+    return {
+      kind: 'unrecognised',
+      reason: 'an unrecognisable Authorization header is not emulated'
+    }
+  }
+
+  // On a recognised route the bearer value is guarded (scrubbed and never repeated).
+  const secrets = bearer === undefined ? [] : [bearer]
+  const matched = matchTodoistRoute(request.method, url.pathname)
+
+  // Fail closed: a request on no emulated route is ledgered and answered with constant text only.
+  if (matched === undefined) {
+    return { kind: 'unrecognised', reason: 'no emulated Todoist route for this method and path' }
+  }
+
+  const refuse = (reason: string): StatefulResolution<TodoistEmulatorState, TodoistApiEnv> => ({
+    kind: 'refused',
+    ledgerPath,
+    reason,
+    route: matched.route.route,
+    secrets
+  })
+
+  if (bearer === undefined) {
+    return refuse(
+      'requests without Authorization: Bearer <token of at least 8 characters> are not emulated'
+    )
+  }
+
+  const problem = todoistQueryProblem(matched.route, url.searchParams)
+
+  if (problem !== undefined) return refuse(problem)
+
+  return {
+    kind: 'route',
+    ledgerPath,
+    route: matched.route.route,
+    params: matched.params,
+    // The path and query the request must not repeat the bearer in.
+    guardedPath: `${url.pathname}${url.search}`,
+    secrets
+  }
+}
+
+/** The texts of Todoist's recovery answers (500 failed, 503 closed, 500 unhandled). */
+const errorTexts: StatefulErrorTexts = {
+  failed: 'Synthetic: the emulator could not build the response.',
+  closed: 'Synthetic: the emulator is closed.',
+  unhandled: 'emulator failed to handle the request'
+}
+
+/** The wrapper reports invalid seeds and faults only (Todoist takes no other option input). */
+const inputInvalid = (input: StatefulInputKind, reason: string) =>
+  new TodoistEmulatorInputInvalid({ input: input === 'seed' ? 'seed' : 'fault', reason })
+
+/**
+ * Create a stateful Todoist emulator on the `@emulators/core` custom runtime. Each call has its
+ * own state, ledger, faults, and cursors. Rejects with `TodoistEmulatorInputInvalid` for an
+ * invalid seed.
+ *
+ * Routes (under `/api/v1`, `Authorization: Bearer <token of at least 8 characters>`): task
+ * listing with cursor paging, task read, create, update, and close, label listing, and project
+ * create, read, and delete.
+ * See `README.md` (Todoist emulator) for the wire claims.
+ */
+export const makeTodoistEmulator = async (
+  options: TodoistEmulatorOptions = {}
+): Promise<TodoistEmulator> => {
+  const initial = buildTodoistSeedState(options.seed ?? {})
+
+  if (Predicate.isString(initial)) {
+    throw new TodoistEmulatorInputInvalid({ input: 'seed', reason: initial })
+  }
+
+  const drills = options.drills ?? {}
+
+  const env: TodoistApiEnv = {
+    now: options.now ?? (() => Date.now()),
+    drills: {
+      cursorRestarts: drills.cursorRestarts ?? false,
+      notFoundWithoutError: drills.notFoundWithoutError ?? false,
+      taskLabelsAsIds: drills.taskLabelsAsIds ?? false,
+      listIncludesClosed: drills.listIncludesClosed ?? false,
+      ignoreDue: drills.ignoreDue ?? false,
+      createOmitsParent: drills.createOmitsParent ?? false,
+      deleteKeepsTasks: drills.deleteKeepsTasks ?? false
+    },
+    cursors: new Map(),
+    cursorCounter: { next: 1 }
+  }
+
+  const cursorList = (): ReadonlyArray<TodoistCursor> => [...env.cursors.values()]
+
+  const emulator = await makeHeaderlessStatefulEmulator<
+    TodoistEmulatorState,
+    TodoistApiEnv,
+    TodoistEmulatorSeed
+  >(
+    {
+      routes: todoistApiRoutes.map(({ route }) => route),
+      env,
+      initial,
+      buildSeed: buildTodoistSeedState,
+      resolveRequest: resolve,
+      errorTexts,
+      clearRuntime: () => {
+        env.cursors.clear()
+        env.cursorCounter.next = 1
+      },
+      runtimeState: () => ({ runtime: { cursors: cursorList().map(cursor => ({ ...cursor })) } }),
+      seedSummary: state => ({
+        projects: state.projects.length,
+        tasks: state.tasks.length,
+        labels: state.labels.length
+      }),
+      inputInvalid
+    },
+    statefulCoreRuntime({
+      name: 'todoist',
+      initial,
+      decodeState: decodeTodoistState,
+      inputInvalid
+    })
+  )
+
+  return {
+    fetch: emulator.fetch,
+    ledger: emulator.ledger,
+    faults: emulator.faults,
+    cursors: cursorList,
+    reset: emulator.reset,
+    seed: emulator.seed,
+    snapshot: emulator.snapshot,
+    coverage: emulator.coverage,
+    close: emulator.close
+  }
+}

package/src/xai.ts

@@ -0,0 +1,341 @@
+/**
+ * xAI Grok CLI proxy Responses emulator: a plain fetch handler for `POST /v1/responses` (origin
+ * `https://cli-chat-proxy.grok.com`), with scripted turns, wire faults, a request ledger, and an
+ * `/_emulate/*` control plane.
+ *
+ * It never imports SDK code: its wire shapes follow the synthetic Grok Responses conformance
+ * fixtures (Responses SSE with typed `event:` names, the `response` JSON body, and the
+ * `{ error: { message, type, param, code } }` envelope) and are linked to those conformance case
+ * ids in `xAiGrokEmulatorRoutes`. The Responses machinery lives in the internal `responses.ts`
+ * core and is shared with the Codex emulator.
+ *
+ * Requests authenticate with a non-empty `Authorization: Bearer` credential (a Grok OAuth access
+ * token) and must also send, in this order, a non-empty `X-XAI-Token-Auth` (401 without it; never
+ * recorded or checked), `x-grok-client-version` (426 without it: the proxy version-gates
+ * requests), and `x-grok-model-override` (400 without it). The client version and model override
+ * are recorded in the ledger; the version value itself is not checked.
+ *
+ * The same fetch handler also answers the Grok subscription-usage route
+ * (`GET /v1/billing?format=credits`, `emulator.usage`) with its own manifest
+ * (`xAiGrokSubscriptionUsageEmulatorRoutes`), ledger, faults, and turns; see
+ * `makeXAiGrokEmulator`.
+ *
+ * Runtime-portable Web APIs only (`Request`, `Response`, `ReadableStream`, `TextEncoder`, `URL`);
+ * no Effect runtime is required to use it.
+ *
+ * @experimental
+ */
+import { Data } from 'effect'
+import type * as Schema from 'effect/Schema'
+import { withSubscriptionUsage } from './emulator-compose.ts'
+import type {
+  EmulatorCoverage,
+  EmulatorFaultState,
+  EmulatorRouteCoverage
+} from './emulator-kernel.ts'
+import { EmulatorFaultMatch, EmulatorScriptedError } from './emulator-kernel.ts'
+import {
+  makeResponsesEmulator,
+  ResponsesErrorEventFault,
+  ResponsesFault,
+  ResponsesScriptedFunctionCall,
+  ResponsesScriptedResponse,
+  ResponsesScriptedTurn,
+  ResponsesScriptedUsage,
+  ResponsesStreamError,
+  type ResponsesEmulator,
+  type ResponsesFaultKind,
+  type ResponsesLedgerEntry,
+  type ResponsesWireError
+} from './responses.ts'
+import type { EmulatorRouteEvidence } from './route-evidence.ts'
+import {
+  makeSubscriptionUsageEmulator,
+  recordedUsageBody,
+  SubscriptionUsageFault,
+  type SubscriptionUsageEmulator,
+  type SubscriptionUsageLedgerEntry,
+  type SubscriptionUsageScriptedTurn
+} from './subscription-usage.ts'
+import { xAiGrokUsageRecording } from './subscription-usage-recordings.ts'
+
+export type { EmulatorEvidence, EmulatorRouteEvidence } from './route-evidence.ts'
+
+export { emulatorEvidenceHeader } from './route-evidence.ts'
+
+export const xAiGrokResponsesPath = '/v1/responses'
+
+/**
+ * The Grok subscription-usage path; the SDK fetcher (`xAiGrokSubscriptionUsageUrl`) adds
+ * `?format=credits`, the recorded query.
+ */
+export const xAiGrokSubscriptionUsagePath = '/v1/billing'
+
+/**
+ * Route evidence manifest of the Grok subscription-usage route (served by the same fetch handler
+ * as the Responses route, with its own ledger and coverage). Synthetic, unverified.
+ */
+export const xAiGrokSubscriptionUsageEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence> = [
+  {
+    method: 'GET',
+    path: xAiGrokSubscriptionUsagePath,
+    kind: 'provider',
+    write: false,
+    caseIds: ['xai.grok.usage.snapshot'],
+    evidence: 'unverified',
+    observedAt: undefined
+  }
+]
+
+/**
+ * The recorded Grok usage body (the synthetic `xai.grok.usage.snapshot` fixture, copied as data):
+ * `config.creditUsagePercent` and `config.currentPeriod` `{ type, start, end }`.
+ */
+export const xAiGrokSubscriptionUsageDefault: Schema.Json = recordedUsageBody(xAiGrokUsageRecording)
+
+/** Synthetic-safe default model ids, including the Grok conformance defaults. */
+export const xAiGrokEmulatorDefaultModels: ReadonlyArray<string> = ['grok-build', 'grok-4.6']
+
+/**
+ * Route evidence manifest: every emulated Grok route and the conformance cases whose (currently
+ * synthetic, unverified) wire shapes it follows.
+ */
+export const xAiGrokEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence> = [
+  {
+    method: 'POST',
+    path: xAiGrokResponsesPath,
+    kind: 'provider',
+    write: false,
+    caseIds: [
+      'xai.grok.stream.plain-text',
+      'xai.grok.stream.function-call-arguments',
+      'xai.grok.stream.error-envelope',
+      'xai.grok.stream.terminal-event'
+    ],
+    evidence: 'unverified',
+    observedAt: undefined
+  }
+]
+
+/** Optional fault filter; an omitted field matches every request. `path` ending in `*` is a prefix. */
+export const XAiGrokFaultMatch = EmulatorFaultMatch
+
+export type XAiGrokFaultMatch = typeof EmulatorFaultMatch.Type
+
+/** A mid-stream Responses error (`{ code, message }`). */
+export const XAiGrokStreamError = ResponsesStreamError
+
+export type XAiGrokStreamError = ResponsesStreamError
+
+/** A mid-stream `error` or `response.failed` event fault, streamed responses only. */
+export const XAiGrokErrorEventFault = ResponsesErrorEventFault
+
+export type XAiGrokErrorEventFault = typeof ResponsesErrorEventFault.Type
+
+/**
+ * Wire faults: `status` (for example 429 with `retry-after`; the body defaults to the error
+ * envelope for the status), `error-after-chunks` (a dropped connection),
+ * `truncate-after-chunks` (a clean close, for example before `response.completed`), and
+ * `error-event-after-chunks` (a mid-stream `error` or `response.failed` event). Statuses that
+ * cannot carry a body and redirects are rejected, as are invalid headers and `location`. A fault
+ * that cannot take effect answers 500 and is not consumed.
+ */
+export const XAiGrokFault = ResponsesFault
+
+export type XAiGrokFault = ResponsesFault
+
+export type XAiGrokFaultKind = ResponsesFaultKind
+
+/** Usage for a scripted turn (sent in `response.completed` or the JSON body). */
+export const XAiGrokScriptedUsage = ResponsesScriptedUsage
+
+export type XAiGrokScriptedUsage = ResponsesScriptedUsage
+
+/** One scripted `function_call` item; its arguments stream as these fragments. */
+export const XAiGrokScriptedFunctionCall = ResponsesScriptedFunctionCall
+
+export type XAiGrokScriptedFunctionCall = ResponsesScriptedFunctionCall
+
+/**
+ * A scripted response: `reasoning` (summary fragments), `text`, `functionCalls`, `order`,
+ * `usage` (`null` drops it), and `format` (`sse` or `json`, default: the request's `stream`).
+ */
+export const XAiGrokScriptedResponse = ResponsesScriptedResponse
+
+export type XAiGrokScriptedResponse = ResponsesScriptedResponse
+
+/** A scripted error response: status, body (a string is sent as is), and optional headers. */
+export const XAiGrokScriptedError = EmulatorScriptedError
+
+export type XAiGrokScriptedError = typeof EmulatorScriptedError.Type
+
+/** A turn queued for the next Grok request. */
+export const XAiGrokScriptedTurn = ResponsesScriptedTurn
+
+export type XAiGrokScriptedTurn = ResponsesScriptedTurn
+
+/** Thrown by the JS API (`faults.add`, `script.enqueue`) for invalid input; a programmer error. */
+export class XAiGrokEmulatorInputInvalid extends Data.TaggedError('XAiGrokEmulatorInputInvalid')<{
+  readonly input: 'fault' | 'turn'
+  readonly reason: string
+}> {
+  override get message(): string {
+    return `Invalid xAI Grok emulator ${this.input}: ${this.reason}`
+  }
+}
+
+export type XAiGrokLedgerEntry = ResponsesLedgerEntry
+
+export type XAiGrokFaultState = EmulatorFaultState<XAiGrokFault>
+
+export type XAiGrokRouteCoverage = EmulatorRouteCoverage
+
+export type XAiGrokCoverage = EmulatorCoverage
+
+/** A usage-route fault (`status`, `error-after-chunks`, `truncate-after-chunks`). */
+export const XAiGrokUsageFault = SubscriptionUsageFault
+
+export type XAiGrokUsageFault = SubscriptionUsageFault
+
+/** A usage turn: `{ usage }` (a body with the recorded JSON shape) or `{ error }`. */
+export type XAiGrokUsageScriptedTurn = SubscriptionUsageScriptedTurn
+
+export type XAiGrokUsageLedgerEntry = SubscriptionUsageLedgerEntry
+
+export type XAiGrokUsageEmulator = SubscriptionUsageEmulator
+
+export type XAiGrokEmulatorOptions = {
+  /** Model ids that exist. Defaults to `xAiGrokEmulatorDefaultModels`. */
+  readonly knownModels?: ReadonlyArray<string>
+  /**
+   * Replacement usage-route body; must have the recorded JSON shape (same keys and value kinds).
+   * Defaults to the recorded body (`xAiGrokSubscriptionUsageDefault`).
+   */
+  readonly subscriptionUsage?: Schema.Json
+}
+
+/** The Responses emulator, plus `usage`: the subscription-usage route's own emulator API. */
+export type XAiGrokEmulator = ResponsesEmulator & { readonly usage: XAiGrokUsageEmulator }
+
+const errorEnvelope = (error: ResponsesWireError): Schema.Json => ({
+  error: {
+    message: error.message,
+    type: error.type,
+    param: error.param ?? null,
+    code: error.code
+  }
+})
+
+/**
+ * Create a Grok CLI proxy Responses emulator. Each call has independent ledger, fault, and script
+ * state.
+ *
+ * Without a script, `POST /v1/responses` answers a known model with synthetic output: `stream:
+ * true` streams `response.created`, `response.in_progress`, the output items
+ * (`response.output_item.added`, their parts and deltas, `response.output_item.done`), and
+ * `response.completed` with usage; `stream: false` returns one `response` JSON body. A request
+ * whose `reasoning` asks for a `summary` gets a reasoning item first. A request with function
+ * `tools` gets one `function_call` item whose arguments are synthesized from the tool's JSON
+ * Schema and streamed as `response.function_call_arguments.delta` fragments. Unknown models get
+ * 400 `model_not_found`; a request without a bearer credential gets 401 `invalid_api_key`,
+ * without `X-XAI-Token-Auth` 401, without `x-grok-client-version` 426, and without
+ * `x-grok-model-override` 400; a non-positive `max_output_tokens` gets 400; unknown routes get a
+ * 404 envelope. Not enforced: that `x-grok-model-override` matches the body `model`, the client
+ * version value, and the output limit itself (recorded as `maxOutputTokens`).
+ *
+ * `GET /v1/billing?format=credits` is fixture-only: a request with the headers the SDK fetcher
+ * sends (a non-empty bearer, `X-XAI-Token-Auth: xai-grok-cli`, a non-empty `x-userid`, a
+ * non-empty `x-grok-client-version`, and `x-grok-client-mode: headless`; the bearer, user id, and
+ * client-version values are request-shape latitude, and the user id and token-auth are never
+ * recorded),
+ * `accept: application/json`, and exactly the recorded `format=credits` query gets the recorded
+ * body (`xAiGrokSubscriptionUsageDefault`, or a same-shaped `options.subscriptionUsage` / scripted
+ * `{ usage }`); anything else answers 400 not-emulated. The client version and mode are recorded.
+ * Its ledger, faults, turns, and coverage are `emulator.usage`
+ * (control plane `/_emulate/usage/*`); `reset()` and `POST /_emulate/reset` reset both routes.
+ */
+export const makeXAiGrokEmulator = (options: XAiGrokEmulatorOptions = {}): XAiGrokEmulator =>
+  withSubscriptionUsage(
+    makeXAiGrokResponsesEmulator(options),
+    makeXAiGrokUsageEmulator(options),
+    xAiGrokSubscriptionUsagePath
+  )
+
+const makeXAiGrokUsageEmulator = (options: XAiGrokEmulatorOptions): XAiGrokUsageEmulator =>
+  makeSubscriptionUsageEmulator({
+    path: xAiGrokSubscriptionUsagePath,
+    routes: xAiGrokSubscriptionUsageEmulatorRoutes,
+    recording: xAiGrokUsageRecording,
+    headers: [
+      { name: 'x-xai-token-auth', record: false, accepts: value => value === 'xai-grok-cli' },
+      { name: 'x-userid', record: false },
+      { name: 'x-grok-client-version', record: true },
+      { name: 'x-grok-client-mode', record: true, accepts: value => value === 'headless' }
+    ],
+    subscriptionUsage: options.subscriptionUsage,
+    inputInvalid: (input, reason) => new XAiGrokEmulatorInputInvalid({ input, reason })
+  })
+
+const makeXAiGrokResponsesEmulator = (options: XAiGrokEmulatorOptions): ResponsesEmulator =>
+  makeResponsesEmulator({
+    path: xAiGrokResponsesPath,
+    routes: xAiGrokEmulatorRoutes,
+    knownModels: options.knownModels ?? xAiGrokEmulatorDefaultModels,
+    errorEnvelope,
+    // Copied data shape of the synthetic Grok error-envelope fixture (unknown model id).
+    unknownModel: {
+      status: 400,
+      error: {
+        message: 'Synthetic placeholder: the requested model does not exist.',
+        type: 'invalid_request_error',
+        code: 'model_not_found',
+        param: 'model'
+      }
+    },
+    unauthorized: {
+      message: 'Synthetic: missing or invalid bearer credential.',
+      type: 'invalid_request_error',
+      code: 'invalid_api_key'
+    },
+    headers: [
+      {
+        name: 'x-xai-token-auth',
+        record: false,
+        required: {
+          status: 401,
+          error: {
+            message: 'Synthetic: the X-XAI-Token-Auth header is required.',
+            type: 'invalid_request_error',
+            code: 'missing_token_auth'
+          }
+        }
+      },
+      {
+        name: 'x-grok-client-version',
+        record: true,
+        required: {
+          status: 426,
+          error: {
+            message: 'Synthetic: a supported x-grok-client-version header is required.',
+            type: 'invalid_request_error',
+            code: 'upgrade_required'
+          }
+        }
+      },
+      {
+        name: 'x-grok-model-override',
+        record: true,
+        required: {
+          status: 400,
+          error: {
+            message: 'Synthetic: the x-grok-model-override header is required.',
+            type: 'invalid_request_error',
+            code: 'missing_model_override'
+          }
+        }
+      }
+    ],
+    outputTokenLimit: 'optional',
+    defaultText: ['Hello', ' from the', ' synthetic Grok emulator.'],
+    inputInvalid: (input, reason) => new XAiGrokEmulatorInputInvalid({ input, reason })
+  })