@yolk-sdk/emulators 0.1.0-canary.96

package/dist/responses.d.mts

@@ -0,0 +1,231 @@
+import { EmulatorEvidence, EmulatorRouteEvidence } from "./route-evidence.mjs";
+import { EmulatorApi } from "./emulator-kernel.mjs";
+import * as Schema from "effect/Schema";
+
+//#region src/responses.d.ts
+/** A mid-stream Responses error: a machine `code` and a message. */
+declare const ResponsesStreamError: Schema.Struct<{
+  readonly code: Schema.NonEmptyString;
+  readonly message: Schema.String;
+}>;
+type ResponsesStreamError = typeof ResponsesStreamError.Type;
+/**
+ * Send `chunks` SSE events, then one error event and close without `response.completed`:
+ * `event: 'error'` (the default) sends `{ type: 'error', code, message }`, and
+ * `event: 'response.failed'` sends a `response.failed` event whose `response.error` carries the
+ * code and message. The error defaults to `server_error`. Streamed responses only; it must come
+ * before `response.completed`.
+ */
+declare const ResponsesErrorEventFault: Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-event-after-chunks">;
+  readonly chunks: Schema.Int;
+  readonly event: Schema.optionalKey<Schema.Literals<readonly ["error", "response.failed"]>>;
+  readonly error: Schema.optionalKey<Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly message: Schema.String;
+  }>>;
+}>;
+/**
+ * Wire faults: `status` (the body defaults to the subpath's 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).
+ */
+declare const ResponsesFault: Schema.Union<readonly [Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"status">;
+  readonly status: Schema.Int;
+  readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly body: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"truncate-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-event-after-chunks">;
+  readonly chunks: Schema.Int;
+  readonly event: Schema.optionalKey<Schema.Literals<readonly ["error", "response.failed"]>>;
+  readonly error: Schema.optionalKey<Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly message: Schema.String;
+  }>>;
+}>]>;
+type ResponsesFault = typeof ResponsesFault.Type;
+type ResponsesFaultKind = ResponsesFault['kind'];
+/** Usage for a scripted turn (sent in `response.completed` or the JSON body). */
+declare const ResponsesScriptedUsage: Schema.Struct<{
+  readonly inputTokens: Schema.Int;
+  readonly outputTokens: Schema.Int;
+  readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+}>;
+type ResponsesScriptedUsage = typeof ResponsesScriptedUsage.Type;
+/** One scripted `function_call` item; its arguments stream as these fragments. */
+declare const ResponsesScriptedFunctionCall: Schema.Struct<{
+  readonly name: Schema.NonEmptyString;
+  readonly argumentFragments: Schema.$Array<Schema.String>;
+  readonly callId: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+type ResponsesScriptedFunctionCall = typeof ResponsesScriptedFunctionCall.Type;
+/**
+ * A scripted response. Every field is exact (nothing is filled in) except: an item is sent only
+ * when its field is present (`reasoning` is one summary part, `text` one message); `usage`
+ * omitted is synthesized and `null` drops `usage` from the wire; `order` defaults to
+ * `reasoning-first` (`text-first` sends the reasoning item after the message); `format` defaults
+ * to the request's `stream` (`sse` streams even for `stream: false`, `json` answers one JSON body
+ * even for `stream: true`, as the JSON fallback some endpoints use).
+ */
+declare const ResponsesScriptedResponse: Schema.Struct<{
+  readonly reasoning: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly functionCalls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly argumentFragments: Schema.$Array<Schema.String>;
+    readonly callId: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["reasoning-first", "text-first"]>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+  }>>>;
+  readonly format: Schema.optionalKey<Schema.Literals<readonly ["sse", "json"]>>;
+}>;
+type ResponsesScriptedResponse = typeof ResponsesScriptedResponse.Type;
+/** A turn queued for the next Responses request. */
+declare const ResponsesScriptedTurn: Schema.Union<readonly [Schema.Struct<{
+  readonly error: Schema.Struct<{
+    readonly status: Schema.Int;
+    readonly body: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  }>;
+}>, Schema.Struct<{
+  readonly reasoning: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly functionCalls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly argumentFragments: Schema.$Array<Schema.String>;
+    readonly callId: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["reasoning-first", "text-first"]>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+  }>>>;
+  readonly format: Schema.optionalKey<Schema.Literals<readonly ["sse", "json"]>>;
+}>]>;
+type ResponsesScriptedTurn = typeof ResponsesScriptedTurn.Type;
+type ResponsesLedgerEntry = {
+  /** 1-based arrival order since the last ledger clear or reset. */readonly seq: number;
+  readonly method: string;
+  readonly path: string; /** Parsed JSON request body, when it was valid JSON. */
+  readonly body?: Schema.Json;
+  readonly model?: string;
+  readonly stream?: boolean;
+  readonly store?: boolean; /** The request's `max_output_tokens`, when it is a number. */
+  readonly maxOutputTokens?: number;
+  readonly reasoning?: Schema.Json;
+  readonly toolChoice?: Schema.Json; /** Names of the offered `function` tools. */
+  readonly toolNames: ReadonlyArray<string>; /** Values of the non-credential headers the subpath records (lower-case names). */
+  readonly headers: Readonly<Record<string, string>>; /** Kind of the fault that shaped the response. */
+  readonly fault?: ResponsesFaultKind; /** Why a matching fault could not take effect (the response was a 500 emulator error). */
+  readonly faultError?: string;
+  /**
+   * Set when the emulator could not build the planned response; the request was answered with a
+   * 500 emulator error (still evidence-tagged) and no fault was used up.
+   */
+  readonly responseError?: string; /** Set when a scripted turn answered the request. */
+  readonly scripted?: 'response' | 'error'; /** Evidence of the matched route; `unknown-route` for requests that failed closed. */
+  readonly evidence: EmulatorEvidence | 'unknown-route';
+  readonly status: number; /** Body chunks handed to the transport so far (each produced when pulled). */
+  readonly bodyChunks: number;
+};
+type ResponsesEmulator = EmulatorApi<ResponsesScriptedTurn, ResponsesFault, ResponsesLedgerEntry>;
+/** A Responses wire error, rendered by the subpath's `errorEnvelope`. */
+type ResponsesWireError = {
+  readonly message: string;
+  readonly type: string;
+  readonly code: string;
+  readonly param?: string;
+};
+/**
+ * One request header rule. `record` keeps the header value in the ledger `headers` (never set it
+ * for credential headers); `required` answers a request without a non-empty value with that
+ * status and error (the value itself is never checked).
+ */
+type ResponsesHeaderRule = {
+  /** Lower-case header name. */readonly name: string;
+  readonly record: boolean;
+  readonly required?: {
+    readonly status: number;
+    readonly error: ResponsesWireError;
+  };
+};
+/**
+ * What differs between Responses emulators. The core owns everything else (framing, faults,
+ * scripting, ledger, control plane, evidence).
+ */
+type ResponsesEmulatorConfig = {
+  /** The Responses path, for example `/v1/responses`. */readonly path: string; /** Route evidence manifest; must list exactly the Responses route. */
+  readonly routes: ReadonlyArray<EmulatorRouteEvidence>;
+  readonly knownModels: ReadonlyArray<string>; /** Renders a wire error as the service's JSON error envelope. */
+  readonly errorEnvelope: (error: ResponsesWireError) => Schema.Json; /** Status and error for an unknown model id. */
+  readonly unknownModel: {
+    readonly status: number;
+    readonly error: ResponsesWireError;
+  };
+  /**
+   * Requests authenticate with a non-empty `Authorization: Bearer` credential, never checked or
+   * stored; anything else answers 401 with `unauthorized`.
+   */
+  readonly unauthorized: ResponsesWireError; /** Extra header rules, checked in order after the bearer credential. */
+  readonly headers: ReadonlyArray<ResponsesHeaderRule>;
+  /**
+   * `optional`: `max_output_tokens` may be sent (a positive integer, or 400) and is recorded, not
+   * enforced; `rejected`: any `max_output_tokens` answers 400 `unsupported_parameter`.
+   */
+  readonly outputTokenLimit: 'optional' | 'rejected'; /** Default answer text deltas. */
+  readonly defaultText: ReadonlyArray<string>; /** Builds the error thrown by the JS API (`faults.add`, `script.enqueue`) for invalid input. */
+  readonly inputInvalid: (input: 'fault' | 'turn', reason: string) => Error;
+};
+/**
+ * Create a Responses emulator from its config. Each call has independent ledger, fault, and
+ * script state.
+ *
+ * Precedence per request: the bearer credential, the header rules in order, JSON and request
+ * validation (an `input` string or array, and the `max_output_tokens` policy), then the first
+ * matching fault if it is a `status` fault, then the next scripted turn, then model validation and
+ * defaults; a first matching body fault then shapes the body. Only the first matching fault (in
+ * insertion order) applies. Credential headers are never recorded, and credential values are
+ * never checked or stored.
+ */
+declare const makeResponsesEmulator: (config: ResponsesEmulatorConfig) => ResponsesEmulator;
+//#endregion
+export { ResponsesEmulator, ResponsesEmulatorConfig, ResponsesErrorEventFault, ResponsesFault, ResponsesFaultKind, ResponsesHeaderRule, ResponsesLedgerEntry, ResponsesScriptedFunctionCall, ResponsesScriptedResponse, ResponsesScriptedTurn, ResponsesScriptedUsage, ResponsesStreamError, ResponsesWireError, makeResponsesEmulator };
+//# sourceMappingURL=responses.d.mts.map

package/dist/responses.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.mts","names":[],"sources":["../src/responses.ts"],"mappings":";;;;;;cA0Da,oBAAA,EAAoB,MAAA,CAAA,MAAA;EAAA;;;KAKrB,oBAAA,UAA8B,oBAAA,CAAqB,IAAI;;;;;;;;cAStD,wBAAA,EAAwB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;cAcxB,cAAA,EAAc,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAOf,cAAA,UAAwB,cAAA,CAAe,IAAI;AAAA,KAE3C,kBAAA,GAAqB,cAAc;;cAKlC,sBAAA,EAAsB,MAAA,CAAA,MAAA;EAAA;;;;KAMvB,sBAAA,UAAgC,sBAAA,CAAuB,IAAI;;cAG1D,6BAAA,EAA6B,MAAA,CAAA,MAAA;EAAA;;;;KAM9B,6BAAA,UAAuC,6BAAA,CAA8B,IAAI;;;;;AA7BrF;;;;cAuCa,yBAAA,EAAyB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;KAS1B,yBAAA,UAAmC,yBAAA,CAA0B,IAAI;;cAGhE,qBAAA,EAAqB,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;KAKtB,qBAAA,UAA+B,qBAAA,CAAsB,IAAI;AAAA,KAEzD,oBAAA;6EAED,GAAA;EAAA,SACA,MAAA;EAAA,SACA,IAAA;WAEA,IAAA,GAAO,MAAA,CAAO,IAAA;EAAA,SACd,KAAA;EAAA,SACA,MAAA;EAAA,SACA,KAAA;WAEA,eAAA;EAAA,SACA,SAAA,GAAY,MAAA,CAAO,IAAA;EAAA,SACnB,UAAA,GAAa,MAAA,CAAO,IAAA;WAEpB,SAAA,EAAW,aAAA,UAzEK;EAAA,SA2EhB,OAAA,EAAS,QAAA,CAAS,MAAA,mBA3EF;EAAA,SA6EhB,KAAA,GAAQ,kBAAA,EA7EQ;EAAA,SA+EhB,UAAA;EA/EgB;;;;EAAA,SAoFhB,aAAA;WAEA,QAAA;WAEA,QAAA,EAAU,gBAAA;EAAA,SACV,MAAA;WAEA,UAAA;AAAA;AAAA,KAGC,iBAAA,GAAoB,WAAA,CAC9B,qBAAA,EACA,cAAA,EACA,oBAAA;;KAIU,kBAAA;EAAA,SACD,OAAA;EAAA,SACA,IAAA;EAAA,SACA,IAAA;EAAA,SACA,KAAA;AAAA;;;;;;KAQC,mBAAA;yCAED,IAAA;EAAA,SACA,MAAA;EAAA,SACA,QAAA;IAAA,SAAsB,MAAA;IAAA,SAAyB,KAAA,EAAO,kBAAkB;EAAA;AAAA;;;;;KAOvE,uBAAA;kEAED,IAAA;WAEA,MAAA,EAAQ,aAAA,CAAc,qBAAA;EAAA,SACtB,WAAA,EAAa,aAAA;WAEb,aAAA,GAAgB,KAAA,EAAO,kBAAA,KAAuB,MAAA,CAAO,IAAA;WAErD,YAAA;IAAA,SAAyB,MAAA;IAAA,SAAyB,KAAA,EAAO,kBAAA;EAAA;;;;;WAKzD,YAAA,EAAc,kBAAA;WAEd,OAAA,EAAS,aAAA,CAAc,mBAAA;;;;;WAKvB,gBAAA;WAEA,WAAA,EAAa,aAAA;WAEb,YAAA,GAAe,KAAA,oBAAyB,MAAA,aAAmB,KAAA;AAAA;;;;;;;;;;;;cAobzD,qBAAA,GAAyB,MAAA,EAAQ,uBAAA,KAA0B,iBAqOvE"}