@everfur/sdk 0.1.0

package/dist/testing/index.d.cts

@@ -0,0 +1,113 @@
+import { E as EverfurResult } from '../EverfurResult-D92-uL82.cjs';
+import { T as TransportPort, E as EverfurRequest, F as Frame } from '../config-BSjBdxrZ.cjs';
+
+/** One scripted stream outcome. Each block is a JSON `data:` payload string; MockTransport wraps it in SSE. */
+type StreamScript = {
+    readonly kind: 'sse';
+    readonly blocks: readonly string[];
+    readonly gapMs?: number;
+} | {
+    readonly kind: 'stall';
+    readonly preface?: readonly string[];
+} | {
+    readonly kind: 'drop';
+    readonly blocks: readonly string[];
+} | {
+    readonly kind: 'partialByte';
+    readonly body: string;
+    readonly splitAt: readonly number[];
+} | {
+    readonly kind: 'httpError';
+    readonly status: number;
+    readonly body?: unknown;
+} | {
+    readonly kind: 'network';
+};
+/** One scripted unary response (createConversation / getPrompts). */
+interface RequestScript {
+    readonly status?: number;
+    readonly body?: unknown;
+}
+/** A captured stream request, for auth-refresh assertions. */
+interface StreamRequestRecord {
+    readonly path: string;
+    readonly authorization: string | null;
+    readonly partnerKey: string | null;
+    readonly idempotencyKey: string | null;
+    /**
+     * The request body, so a test can assert WHAT was streamed, not merely that a stream happened.
+     *
+     * This was absent, and its absence had a real cost: the chat send body carried a `pet_ref` the server
+     * silently discarded (`extra="ignore"`) on every turn, and no test could observe it because the only
+     * captured streaming fields were the path and three headers.
+     */
+    readonly body?: unknown;
+    /**
+     * ALL request headers, so a test can assert any of them rather than only the three that happened to be
+     * named here. The narrow capture was its own blind spot: `x-everfur-session-id` is the header that makes
+     * anonymous identity stable, and no test could observe whether it was sent, or whether it matched the one
+     * on the unary create.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** A captured unary request. */
+interface RequestRecord {
+    readonly method: string;
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: unknown;
+    /**
+     * Query parameters, so a test can assert them. They were dropped from the record entirely, which is the
+     * same blind spot the missing stream `body` and `headers` were: a value the SDK puts on the wire that no
+     * test could see. `region` on the entitlements poll is one such parameter.
+     */
+    readonly query?: Readonly<Record<string, string | number | undefined>>;
+}
+/** Wire-payload builders so tests read declaratively (`wire.delta('Hi')`). */
+declare const wire: Readonly<{
+    accepted: (streamId?: string) => string;
+    heartbeat: () => string;
+    delta: (text: string) => string;
+    done: (fields?: Record<string, unknown>) => string;
+    error: (code: string, retryable?: boolean) => string;
+}>;
+/** Construction options. `strictPaths` is opt-OUT so the safe behaviour is the default. */
+interface MockTransportOptions {
+    /**
+     * Reject a request whose path the backend does not serve. Default true.
+     * Set false only to script a route deliberately outside the known set.
+     */
+    readonly strictPaths?: boolean;
+}
+declare class MockTransport implements TransportPort {
+    private readonly strictPaths;
+    private readonly streamQueue;
+    private readonly requestQueue;
+    /** The last script dequeued, replayed once the queue drains. See `request` for why. */
+    /**
+     * The last scripted response, KEYED BY ENDPOINT.
+     *
+     * It used to be a single field, so a `enqueueRequest({ status: 500 })` scripted for one endpoint kept
+     * replaying for every OTHER endpoint once the queue drained — the comment below says the fallback means
+     * "this endpoint is down", and a global field cannot mean that. A fault leaked across endpoints and a
+     * test could assert an outcome the SDK would never produce.
+     */
+    private lastRequestScript;
+    private openCount;
+    constructor(options?: MockTransportOptions);
+    readonly requests: RequestRecord[];
+    readonly streamRequests: StreamRequestRecord[];
+    /** Live count of streams that have opened but not yet torn down. MUST return to 0 after a cancel. */
+    get openStreams(): number;
+    /** Peak concurrent open streams observed (bulkhead assertions). */
+    private peak;
+    get peakOpenStreams(): number;
+    enqueueStream(...scripts: StreamScript[]): this;
+    enqueueRequest(...scripts: RequestScript[]): this;
+    request<T>(req: EverfurRequest): Promise<EverfurResult<T>>;
+    stream(req: EverfurRequest, signal: AbortSignal): AsyncIterable<Frame>;
+    private openStream;
+    private runScript;
+}
+
+export { MockTransport, type RequestRecord, type RequestScript, type StreamRequestRecord, type StreamScript, wire };

package/dist/testing/index.d.ts

@@ -0,0 +1,113 @@
+import { E as EverfurResult } from '../EverfurResult-D92-uL82.js';
+import { T as TransportPort, E as EverfurRequest, F as Frame } from '../config-CiJ0PVBB.js';
+
+/** One scripted stream outcome. Each block is a JSON `data:` payload string; MockTransport wraps it in SSE. */
+type StreamScript = {
+    readonly kind: 'sse';
+    readonly blocks: readonly string[];
+    readonly gapMs?: number;
+} | {
+    readonly kind: 'stall';
+    readonly preface?: readonly string[];
+} | {
+    readonly kind: 'drop';
+    readonly blocks: readonly string[];
+} | {
+    readonly kind: 'partialByte';
+    readonly body: string;
+    readonly splitAt: readonly number[];
+} | {
+    readonly kind: 'httpError';
+    readonly status: number;
+    readonly body?: unknown;
+} | {
+    readonly kind: 'network';
+};
+/** One scripted unary response (createConversation / getPrompts). */
+interface RequestScript {
+    readonly status?: number;
+    readonly body?: unknown;
+}
+/** A captured stream request, for auth-refresh assertions. */
+interface StreamRequestRecord {
+    readonly path: string;
+    readonly authorization: string | null;
+    readonly partnerKey: string | null;
+    readonly idempotencyKey: string | null;
+    /**
+     * The request body, so a test can assert WHAT was streamed, not merely that a stream happened.
+     *
+     * This was absent, and its absence had a real cost: the chat send body carried a `pet_ref` the server
+     * silently discarded (`extra="ignore"`) on every turn, and no test could observe it because the only
+     * captured streaming fields were the path and three headers.
+     */
+    readonly body?: unknown;
+    /**
+     * ALL request headers, so a test can assert any of them rather than only the three that happened to be
+     * named here. The narrow capture was its own blind spot: `x-everfur-session-id` is the header that makes
+     * anonymous identity stable, and no test could observe whether it was sent, or whether it matched the one
+     * on the unary create.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** A captured unary request. */
+interface RequestRecord {
+    readonly method: string;
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: unknown;
+    /**
+     * Query parameters, so a test can assert them. They were dropped from the record entirely, which is the
+     * same blind spot the missing stream `body` and `headers` were: a value the SDK puts on the wire that no
+     * test could see. `region` on the entitlements poll is one such parameter.
+     */
+    readonly query?: Readonly<Record<string, string | number | undefined>>;
+}
+/** Wire-payload builders so tests read declaratively (`wire.delta('Hi')`). */
+declare const wire: Readonly<{
+    accepted: (streamId?: string) => string;
+    heartbeat: () => string;
+    delta: (text: string) => string;
+    done: (fields?: Record<string, unknown>) => string;
+    error: (code: string, retryable?: boolean) => string;
+}>;
+/** Construction options. `strictPaths` is opt-OUT so the safe behaviour is the default. */
+interface MockTransportOptions {
+    /**
+     * Reject a request whose path the backend does not serve. Default true.
+     * Set false only to script a route deliberately outside the known set.
+     */
+    readonly strictPaths?: boolean;
+}
+declare class MockTransport implements TransportPort {
+    private readonly strictPaths;
+    private readonly streamQueue;
+    private readonly requestQueue;
+    /** The last script dequeued, replayed once the queue drains. See `request` for why. */
+    /**
+     * The last scripted response, KEYED BY ENDPOINT.
+     *
+     * It used to be a single field, so a `enqueueRequest({ status: 500 })` scripted for one endpoint kept
+     * replaying for every OTHER endpoint once the queue drained — the comment below says the fallback means
+     * "this endpoint is down", and a global field cannot mean that. A fault leaked across endpoints and a
+     * test could assert an outcome the SDK would never produce.
+     */
+    private lastRequestScript;
+    private openCount;
+    constructor(options?: MockTransportOptions);
+    readonly requests: RequestRecord[];
+    readonly streamRequests: StreamRequestRecord[];
+    /** Live count of streams that have opened but not yet torn down. MUST return to 0 after a cancel. */
+    get openStreams(): number;
+    /** Peak concurrent open streams observed (bulkhead assertions). */
+    private peak;
+    get peakOpenStreams(): number;
+    enqueueStream(...scripts: StreamScript[]): this;
+    enqueueRequest(...scripts: RequestScript[]): this;
+    request<T>(req: EverfurRequest): Promise<EverfurResult<T>>;
+    stream(req: EverfurRequest, signal: AbortSignal): AsyncIterable<Frame>;
+    private openStream;
+    private runScript;
+}
+
+export { MockTransport, type RequestRecord, type RequestScript, type StreamRequestRecord, type StreamScript, wire };