@wirebench/engine 2.2.1 → 3.1.0

package/dist/rest/scripting.d.ts

@@ -0,0 +1,38 @@
+import type { ProtocolScripting } from '../protocol/module.js';
+import type { HeaderPair } from '../script/model.js';
+import type { RestExchange, RestSendInput } from './send.js';
+/** A REST request body as a script sees it: text it can read and replace, or a kind it cannot edit. */
+export type RestBodySnapshot = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly language: string;
+}
+/** A form, multipart or binary body: kept as it is, and not editable from a script. */
+ | {
+    readonly kind: 'other';
+    readonly description: string;
+};
+export interface RestRequestSnapshot {
+    readonly protocol: 'rest';
+    readonly method: string;
+    /** The full URL, query included, as it will be sent. */
+    readonly url: string;
+    readonly headers: readonly HeaderPair[];
+    readonly body: RestBodySnapshot;
+}
+export interface RestResponseSnapshot {
+    readonly protocol: 'rest';
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: readonly HeaderPair[];
+    readonly text: string;
+    readonly durationMs: number;
+}
+export declare function restRequestSnapshot(input: RestSendInput): RestRequestSnapshot;
+/** The send with a pre-request script's changes. The URL is rebuilt only when the script changed it. */
+export declare function applyRestSnapshot(input: RestSendInput, before: RestRequestSnapshot, after: RestRequestSnapshot): RestSendInput;
+export declare function restResponseSnapshot(exchange: RestExchange): RestResponseSnapshot;
+/** REST's scripting facet. */
+export declare const restScripting: ProtocolScripting<RestRequestSnapshot, RestResponseSnapshot>;

package/dist/rest/scripting.js

@@ -0,0 +1,282 @@
+/**
+ * What a script sees of a REST request and its response (spec §3.4): the snapshots, the converters
+ * between a prepared send and a snapshot, the API's declarations, its sandbox-side source, and what
+ * the script rules check.
+ */
+import { z } from 'zod';
+import { headerPairSchema } from '../script/apply.js';
+import { entriesOf, pairsOf } from '../script/send.js';
+import { composeUrl } from './url.js';
+const RAW_LANGUAGES = ['json', 'xml', 'text', 'html', 'javascript'];
+export function restRequestSnapshot(input) {
+    const { request } = input;
+    const url = composeUrl(input.baseUrl, request.url, request.pathParams, request.query, {
+        encode: input.settings.encodeUrl ?? true,
+    }).url;
+    let body;
+    switch (request.body.kind) {
+        case 'none':
+            body = { kind: 'none' };
+            break;
+        case 'raw':
+            body = { kind: 'text', text: request.body.text, language: request.body.language };
+            break;
+        default:
+            body = { kind: 'other', description: `a ${request.body.kind} body` };
+    }
+    return { protocol: 'rest', method: request.method, url, headers: pairsOf(request.headers), body };
+}
+/** The send with a pre-request script's changes. The URL is rebuilt only when the script changed it. */
+export function applyRestSnapshot(input, before, after) {
+    const urlChanged = after.url !== before.url;
+    const body = (() => {
+        if (after.body.kind === 'other' || JSON.stringify(after.body) === JSON.stringify(before.body)) {
+            return input.request.body;
+        }
+        if (after.body.kind === 'none')
+            return { kind: 'none' };
+        const language = RAW_LANGUAGES.includes(after.body.language)
+            ? after.body.language
+            : 'text';
+        const was = input.request.body;
+        return {
+            kind: 'raw',
+            language,
+            ...(was.kind === 'raw' && was.contentType !== undefined ? { contentType: was.contentType } : {}),
+            text: after.body.text,
+        };
+    })();
+    return {
+        ...input,
+        // A changed URL is sent exactly as the script wrote it: the script's query API has already
+        // encoded what it added, so the send must not encode it again.
+        ...(urlChanged ? { baseUrl: '', settings: { ...input.settings, encodeUrl: false } } : {}),
+        request: {
+            ...input.request,
+            method: after.method,
+            ...(urlChanged ? { url: after.url, pathParams: [], query: [] } : {}),
+            headers: entriesOf(after.headers),
+            body,
+        },
+    };
+}
+export function restResponseSnapshot(exchange) {
+    return {
+        protocol: 'rest',
+        status: exchange.status,
+        statusText: exchange.statusText,
+        headers: exchange.rawHeaders.map(([n, v]) => [n, v]),
+        text: exchange.text,
+        durationMs: exchange.durationMs,
+    };
+}
+const range = (from, to) => Array.from({ length: to - from + 1 }, (_, i) => String(from + i)).join(' | ');
+/** Every HTTP status a response can have, as literals, so an arm's status narrows exactly. */
+const STATUS_TYPES = `
+/** Any HTTP status, as literals, so that checking \`response.status\` narrows the response. */
+type WbStatus = ${range(100, 599)};
+type WbRange1 = Extract<WbStatus, ${range(100, 199)}>;
+type WbRange2 = Extract<WbStatus, ${range(200, 299)}>;
+type WbRange3 = Extract<WbStatus, ${range(300, 399)}>;
+type WbRange4 = Extract<WbStatus, ${range(400, 499)}>;
+type WbRange5 = Extract<WbStatus, ${range(500, 599)}>;
+`;
+const REST_REQUEST = `
+interface WbRestQuery {
+  get(name: string): string | undefined;
+  getAll(name: string): string[];
+  list(): { name: string; value: string }[];
+}
+interface WbWritableRestQuery extends WbRestQuery {
+  set(name: string, value: string): void;
+  add(name: string, value: string): void;
+  delete(name: string): void;
+}
+interface WbRestBody {
+  /** \`other\` is a form, multipart or binary body, which a script cannot read or change. */
+  readonly kind: 'none' | 'text' | 'other';
+  readonly text: string;
+  readonly json: WbRequestBody;
+}
+interface WbResponseArm<S extends number, B> {
+  readonly status: S;
+  readonly statusText: string;
+  readonly headers: WbPairs;
+  readonly text: string;
+  /** The body parsed as JSON, typed from the contract's response for this status. */
+  json(): B;
+  readonly durationMs: number;
+}
+interface WbWritableRestBody {
+  readonly kind: 'none' | 'text' | 'other';
+  text: string;
+  json: WbRequestBody;
+}
+`;
+const REST_PRE = `
+declare const request: {
+  method: string;
+  /** The full URL. A script may change the path, query and fragment, never the scheme, host or port. */
+  url: string;
+  readonly query: WbWritableRestQuery;
+  readonly headers: WbWritablePairs;
+  readonly body: WbWritableRestBody;
+};
+`;
+const REST_POST = `
+declare const request: {
+  readonly method: string;
+  readonly url: string;
+  readonly query: WbRestQuery;
+  readonly headers: WbPairs;
+  readonly body: WbRestBody;
+};
+declare const response: WbResponse;
+`;
+/** Splits and joins a URL's query without a URL class, which QuickJS lacks. */
+const REST = String.raw `
+const splitUrl = (url) => {
+  const hashAt = url.indexOf('#');
+  const fragment = hashAt === -1 ? '' : url.slice(hashAt);
+  const beforeHash = hashAt === -1 ? url : url.slice(0, hashAt);
+  const queryAt = beforeHash.indexOf('?');
+  return {
+    base: queryAt === -1 ? beforeHash : beforeHash.slice(0, queryAt),
+    query: queryAt === -1 ? '' : beforeHash.slice(queryAt + 1),
+    fragment,
+  };
+};
+const decode = (text) => { try { return decodeURIComponent(text.replace(/\+/g, ' ')); } catch { return text; } };
+const encode = (text) => encodeURIComponent(text);
+
+const restRequest = (snapshot, writable) => {
+  const data = {
+    method: snapshot.method,
+    url: snapshot.url,
+    headers: snapshot.headers.map(([n, v]) => [n, v]),
+    body: JSON.parse(JSON.stringify(snapshot.body)),
+  };
+  const queryPairs = () => {
+    const { query } = splitUrl(data.url);
+    return query === '' ? [] : query.split('&').filter((p) => p !== '').map((part) => {
+      const eq = part.indexOf('=');
+      return eq === -1 ? [decode(part), ''] : [decode(part.slice(0, eq)), decode(part.slice(eq + 1))];
+    });
+  };
+  const writeQuery = (pairs) => {
+    const { base, fragment } = splitUrl(data.url);
+    const query = pairs.map(([n, v]) => encode(n) + '=' + encode(v)).join('&');
+    data.url = base + (query === '' ? '' : '?' + query) + fragment;
+  };
+  const refuse = (what) => () => { throw new TypeError('The ' + what + ' of a sent request cannot be changed'); };
+  const query = Object.freeze({
+    get: (name) => { const hit = queryPairs().find(([n]) => n === String(name)); return hit === undefined ? undefined : hit[1]; },
+    getAll: (name) => queryPairs().filter(([n]) => n === String(name)).map(([, v]) => v),
+    list: () => queryPairs().map(([name, value]) => ({ name, value })),
+    set: writable ? (name, value) => {
+      const pairs = queryPairs().filter(([n]) => n !== String(name));
+      pairs.push([String(name), String(value)]);
+      writeQuery(pairs);
+    } : refuse('query'),
+    add: writable ? (name, value) => { const pairs = queryPairs(); pairs.push([String(name), String(value)]); writeQuery(pairs); } : refuse('query'),
+    delete: writable ? (name) => writeQuery(queryPairs().filter(([n]) => n !== String(name))) : refuse('query'),
+  });
+  const headers = pairsApi(data.headers, writable, 'header');
+  const bodyText = () => {
+    if (data.body.kind === 'text') return data.body.text;
+    if (data.body.kind === 'none') return '';
+    throw new TypeError('This request\'s body is ' + data.body.description + ', which a script cannot read or change');
+  };
+  const body = Object.freeze({
+    get kind() { return data.body.kind === 'other' ? 'other' : data.body.kind; },
+    get text() { return bodyText(); },
+    set text(value) {
+      if (!writable) refuse('body')();
+      if (data.body.kind === 'other') bodyText();
+      data.body = { kind: 'text', text: String(value), language: data.body.kind === 'text' ? data.body.language : 'text' };
+    },
+    get json() { return JSON.parse(bodyText()); },
+    set json(value) {
+      if (!writable) refuse('body')();
+      if (data.body.kind === 'other') bodyText();
+      const text = JSON.stringify(value);
+      if (text === undefined) throw new TypeError('body.json must be a JSON value');
+      data.body = { kind: 'text', text, language: 'json' };
+    },
+  });
+  const request = Object.freeze({
+    get method() { return data.method; },
+    set method(value) { if (!writable) refuse('method')(); data.method = String(value).toUpperCase(); },
+    get url() { return data.url; },
+    set url(value) { if (!writable) refuse('URL')(); data.url = String(value); },
+    query,
+    headers,
+    body,
+  });
+  const snapshotOf = () => ({ protocol: 'rest', method: data.method, url: data.url, headers: data.headers, body: data.body });
+  return { request, snapshotOf };
+};
+
+const restResponse = (snapshot) => deepFreeze({
+  status: snapshot.status,
+  statusText: snapshot.statusText,
+  headers: pairsApi(snapshot.headers.map(([n, v]) => [n, v]), false, 'header'),
+  text: snapshot.text,
+  json: () => JSON.parse(snapshot.text),
+  durationMs: snapshot.durationMs,
+});
+
+if (input.phase === 'pre') {
+  const built = restRequest(input.request, true);
+  define('request', built.request);
+  state.request = built.snapshotOf;
+} else {
+  define('request', restRequest(input.request, false).request);
+  define('response', restResponse(input.response));
+}
+`;
+/** An HTTP method token. The generic rules do not know what a method is, so this one is REST's own. */
+const METHOD = /^[A-Z][A-Z0-9_-]{0,31}$/;
+const bodySchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('none') }),
+    z.object({ kind: z.literal('text'), text: z.string(), language: z.string() }),
+    z.object({ kind: z.literal('other'), description: z.string() }),
+]);
+const requestSchema = z.object({
+    protocol: z.literal('rest'),
+    method: z.string(),
+    url: z.string(),
+    headers: z.array(headerPairSchema),
+    body: bodySchema,
+});
+/** REST's scripting facet. */
+export const restScripting = {
+    declarations: (phase) => [STATUS_TYPES, REST_REQUEST, phase === 'pre' ? REST_PRE : REST_POST].join('\n'),
+    reference: () => [
+        { title: 'REST: shared by both phases', declarations: REST_REQUEST },
+        { title: 'REST: pre-request', declarations: REST_PRE },
+        { title: 'REST: post-response', declarations: REST_POST },
+    ],
+    prelude: () => REST,
+    requestSchema,
+    inspect(snapshot) {
+        return {
+            destination: snapshot.url,
+            // A form, multipart or binary body comes back exactly as it went; a text body is the script's.
+            fixed: snapshot.body.kind === 'other' ? snapshot.body : null,
+            pairs: snapshot.headers,
+            lines: [snapshot.url],
+            texts: [
+                snapshot.method,
+                snapshot.url,
+                ...snapshot.headers.flat(),
+                ...(snapshot.body.kind === 'text' ? [snapshot.body.text] : []),
+            ],
+        };
+    },
+    validate(_before, after) {
+        return METHOD.test(after.method)
+            ? undefined
+            : { code: 'script-value-invalid', message: `"${after.method}" is not an HTTP method` };
+    },
+};

package/dist/rest/send-input.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Turns a saved REST request plus the settings around it into the {@link RestSendInput} the
+ * transport receives. The precedence between the layers of configuration is fixed here rather than
+ * in the host: the request's own setting wins, then the API's, then the project's, then the user's
+ * preference. A setting left unset is therefore never "off" — it is "inherit".
+ */
+import type { SendAuth } from '../http/auth/send-auth.js';
+import type { Cookie } from '../http/cookies.js';
+import type { KeyValueEntry } from '../http/entries.js';
+import type { ProxyOptions, TlsOptions } from '../http/types.js';
+import type { ProjectSettings } from '../project/model.js';
+import type { Preferences } from '../project/preferences.js';
+import type { FileResolver } from './body.js';
+import type { RestBody, RestMethod, RestRequestSettings } from './model.js';
+import type { RestSendInput } from './send.js';
+/** The parts of a REST request {@link toRestSendInput} reads. */
+export interface RestSendRequestInput {
+    readonly method: RestMethod;
+    readonly url: string;
+    readonly pathParams: readonly KeyValueEntry[];
+    readonly query: readonly KeyValueEntry[];
+    readonly headers: readonly KeyValueEntry[];
+    readonly body: RestBody;
+    readonly settings: RestRequestSettings;
+}
+/** Everything {@link toRestSendInput} needs beyond the request itself. */
+export interface ToRestSendInputArgs {
+    readonly request: RestSendRequestInput;
+    /** The API's effective base URL, environment override applied and properties expanded. */
+    readonly baseUrl: string;
+    /** The API's own settings, which a request inherits where it sets nothing. */
+    readonly apiSettings?: RestRequestSettings;
+    readonly preferences?: Preferences;
+    readonly projectSettings?: Pick<ProjectSettings, 'defaultTimeoutMs'>;
+    /** Resolved credentials; the host turns `secretRef`s into values and tokens into `oauth2`. */
+    readonly auth?: SendAuth;
+    /** Cookies already matched against the URL, when the request asks for them. */
+    readonly cookies?: readonly Cookie[];
+    /** How a multipart file part or a binary body is read. */
+    readonly resolveFile?: FileResolver;
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Builds the send input for one REST request.
+ *
+ * Precedence is request → API → project → preference, the same ladder a SOAP request's properties
+ * climb, and for the same reason: a setting the request leaves unset means *inherit*, never *off*.
+ * The headers the host adds on the request's behalf — `User-Agent`, `Accept-Encoding`, `Connection`,
+ * a default `Accept` — are passed separately from the request's own, so `rest/send.ts` can let the
+ * user's typed header win without having to guess which came from where.
+ */
+export declare function toRestSendInput(args: ToRestSendInputArgs): RestSendInput;

package/dist/rest/send-input.js

@@ -0,0 +1,73 @@
+/**
+ * Turns a saved REST request plus the settings around it into the {@link RestSendInput} the
+ * transport receives. The precedence between the layers of configuration is fixed here rather than
+ * in the host: the request's own setting wins, then the API's, then the project's, then the user's
+ * preference. A setting left unset is therefore never "off" — it is "inherit".
+ */
+import { inherited } from '../project/inherit.js';
+import { DEFAULT_PREFERENCES } from '../project/preferences.js';
+/**
+ * Builds the send input for one REST request.
+ *
+ * Precedence is request → API → project → preference, the same ladder a SOAP request's properties
+ * climb, and for the same reason: a setting the request leaves unset means *inherit*, never *off*.
+ * The headers the host adds on the request's behalf — `User-Agent`, `Accept-Encoding`, `Connection`,
+ * a default `Accept` — are passed separately from the request's own, so `rest/send.ts` can let the
+ * user's typed header win without having to guess which came from where.
+ */
+export function toRestSendInput(args) {
+    const preferences = args.preferences ?? DEFAULT_PREFERENCES;
+    const request = args.request;
+    const api = args.apiSettings ?? {};
+    const defaultHeaders = {};
+    if (preferences.http.userAgent.length > 0) {
+        defaultHeaders['User-Agent'] = preferences.http.userAgent;
+    }
+    if (preferences.http.responseCompression) {
+        defaultHeaders['Accept-Encoding'] = 'gzip, deflate, br';
+    }
+    if (preferences.http.closeConnections) {
+        defaultHeaders.Connection = 'close';
+    }
+    if (preferences.rest.defaultAccept.length > 0) {
+        defaultHeaders.Accept = preferences.rest.defaultAccept;
+    }
+    const timeoutMs = inherited(request.settings.timeoutMs, api.timeoutMs, args.projectSettings?.defaultTimeoutMs) ??
+        preferences.http.socketTimeoutMs;
+    const followRedirects = inherited(request.settings.followRedirects, api.followRedirects) ?? preferences.rest.followRedirects;
+    const maxRedirects = inherited(request.settings.maxRedirects, api.maxRedirects) ?? preferences.rest.maxRedirects;
+    const keepBodyOnRedirect = inherited(request.settings.keepBodyOnRedirect, api.keepBodyOnRedirect);
+    const encodeUrl = inherited(request.settings.encodeUrl, api.encodeUrl);
+    const maxSizeBytes = inherited(request.settings.maxSizeBytes, api.maxSizeBytes);
+    const bindAddress = inherited(request.settings.bindAddress, api.bindAddress);
+    return {
+        baseUrl: args.baseUrl,
+        request: {
+            method: request.method,
+            url: request.url,
+            pathParams: request.pathParams,
+            query: request.query,
+            headers: request.headers,
+            body: request.body,
+        },
+        settings: {
+            timeoutMs,
+            followRedirects,
+            maxRedirects,
+            ...(keepBodyOnRedirect !== undefined ? { keepBodyOnRedirect } : {}),
+            ...(encodeUrl !== undefined ? { encodeUrl } : {}),
+            ...(maxSizeBytes !== undefined ? { maxSizeBytes } : {}),
+            ...(bindAddress !== undefined && bindAddress.length > 0 ? { localAddress: bindAddress } : {}),
+            ...(preferences.http.allowH2 ? { allowH2: true } : {}),
+        },
+        defaultHeaders,
+        ...(args.auth !== undefined ? { auth: args.auth } : {}),
+        ...(args.cookies !== undefined ? { cookies: args.cookies } : {}),
+        // As for SOAP: the TLS floor is the user's one-off choice, and everything else in `tls` is
+        // resolved by the host, which reads files and secrets, and merged onto this.
+        tls: { minVersion: preferences.ssl.minVersion, ...args.tls },
+        ...(args.proxy !== undefined ? { proxy: args.proxy } : {}),
+        ...(args.resolveFile !== undefined ? { resolveFile: args.resolveFile } : {}),
+        ...(args.signal !== undefined ? { signal: args.signal } : {}),
+    };
+}

package/dist/rest/send.d.ts

@@ -8,11 +8,16 @@
  * runner send identically, and there is one implementation of redirects, timings and raw capture
  * rather than two.
  */
-import type { HttpExchange, HttpRequest, ProxyOptions, TlsOptions } from '../http/types.js';
-import type { AuthSummary, SendAuth } from '../types.js';
+import type { HttpExchange, HttpRequest, HttpStreamSink, ProxyOptions, TlsOptions } from '../http/types.js';
+import type { AuthSummary, SendAuth } from '../http/auth/send-auth.js';
+import type { SignatureScheme } from '../http/webhook-signature.js';
 import type { FileResolver } from './body.js';
+import type { CookieJarHost, CookieVerdict } from '../http/cookies.js';
 import type { KeyValueEntry, RestBody, RestMethod } from './model.js';
 import type { BodyLanguage, Cookie } from './response.js';
+import { createSseParser } from './sse.js';
+import type { SseRow } from './sse.js';
+import { createSseRowStore } from './sse-transcript.js';
 /** The parts of a saved request a send reads, with every property already expanded. */
 export interface RestSendRequest {
     readonly method: RestMethod;
@@ -49,24 +54,73 @@ export interface RestSendInput {
     readonly defaultHeaders?: Readonly<Record<string, string>>;
     /** Credentials, already resolved to values. */
     readonly auth?: SendAuth;
-    /** Cookies to send back, already matched against the URL (`rest/cookies.ts`). */
+    /** Cookies to send back, already matched against the URL. Kept for the engine's API; a run sends through `jar`.
+     * Exclusive with `jar`: when a jar is present this list is ignored. */
     readonly cookies?: readonly Cookie[];
+    /**
+     * The cookie jar this send stores into and, when `send` is set, reads from (cookie jar spec
+     * §1.4). Each hop of a redirect is matched and stored against its own URL. A hand-set `Cookie`
+     * header goes first and wins on the same name.
+     */
+    readonly jar?: {
+        readonly host: CookieJarHost;
+        readonly send: boolean;
+    };
     readonly tls?: TlsOptions;
     readonly proxy?: ProxyOptions;
     /** How a multipart file part or a binary body is read. */
     readonly resolveFile?: FileResolver;
     /** Fixed multipart boundary; tests inject it. */
     readonly boundary?: string;
+    /**
+     * A webhook item's signing (webhook-signatures §5.2), its secret already resolved. Applied last,
+     * over the encoded body bytes and the merged headers, so the signature covers exactly what goes
+     * on the wire. A signing header replaces a merged header of the same name.
+     */
+    readonly sign?: {
+        readonly scheme: SignatureScheme;
+        readonly secret: string;
+    };
     readonly signal?: AbortSignal;
+    /**
+     * Opt-in event-stream handling: when set and the response's `Content-Type` is `text/event-stream`,
+     * the body is parsed row by row as it arrives instead of being buffered. A response of any other
+     * content type is buffered exactly as without this — `onOpen`/`onRow` simply never fire.
+     */
+    readonly onStream?: {
+        /** Called once the response's status and headers are in, before any row. */
+        onOpen?(status: number, headers: Readonly<Record<string, string>>): void;
+        /** Called once per row, in order, as the parser produces it. */
+        onRow?(row: SseRow): void;
+    };
+}
+/** The rows and outcome of an event-stream response, once the send resolves. */
+export interface RestEventStream {
+    readonly rows: readonly SseRow[];
+    readonly counts: {
+        readonly events: number;
+        readonly comments: number;
+        readonly retries: number;
+        readonly bytes: number;
+    };
+    readonly lastEventId: string;
+    readonly retryMs?: number;
+    readonly endedBy: 'server' | 'client' | 'error';
+    readonly error?: string;
+    readonly droppedRows: number;
 }
 /** One REST exchange: everything the transport captured, plus what the body turned out to be. */
 export interface RestExchange extends HttpExchange {
+    /** Present only when `onStream` was given and the response was an event stream. */
+    readonly stream?: RestEventStream;
     /** The response body decoded to text; empty for a body with no text form. */
     readonly text: string;
     readonly language: BodyLanguage;
     /** Set when the declared charset could not be honoured and UTF-8 was used instead. */
     readonly decodeNote?: string;
     readonly cookies: readonly Cookie[];
+    /** The jar's verdict on each of `cookies`, in order; present when the send had a jar. */
+    readonly cookieVerdicts?: readonly CookieVerdict[];
     /** True when a redirect turned the request into a `GET`, which the HTTP log calls out. */
     readonly methodChanged: boolean;
     /** What authentication did, when credentials needed a round trip of their own. */
@@ -90,8 +144,26 @@ export interface RestExchange extends HttpExchange {
  * status is not a failure: it is a response, and the caller inspects it.
  *
  * @throws WirebenchError `rest-url-incomplete` when the URL could not be completed
+ * @throws WirebenchError `webhook-signing-secret` when a `standard` signing secret cannot be decoded
  */
 export declare function sendRest(input: RestSendInput): Promise<RestExchange>;
+/** Mutable state a streamed send accumulates as rows arrive, shared between the hook and decoding. */
+interface SseState {
+    hook(onStream: NonNullable<RestSendInput['onStream']>): {
+        accept(status: number, headers: Readonly<Record<string, string>>): HttpStreamSink | undefined;
+    };
+    readonly store: ReturnType<typeof createSseRowStore>;
+    readonly counts: {
+        events: number;
+        comments: number;
+        retries: number;
+        bytes: number;
+    };
+    lastEventId: string;
+    retryMs?: number;
+    /** Set once the response was accepted as an event stream; `decodeRestResponse` finalizes it. */
+    parser?: ReturnType<typeof createSseParser>;
+}
 /**
  * Turns a finished HTTP exchange into a REST one: body decoded to text, language detected, cookies
  * parsed, and a note when a redirect changed the method.
@@ -99,4 +171,5 @@ export declare function sendRest(input: RestSendInput): Promise<RestExchange>;
  * Split out so a response replayed from history or from the exchange cache is presented exactly as
  * a live one.
  */
-export declare function decodeRestResponse(exchange: HttpExchange, sentMethod: HttpRequest['method']): RestExchange;
+export declare function decodeRestResponse(exchange: HttpExchange, sentMethod: HttpRequest['method'], sse?: SseState): RestExchange;
+export {};