opinionated-machine 10.3.0 → 10.5.0

package/dist/lib/sse/sseSendDiagnostics.js

@@ -0,0 +1,277 @@
+/**
+ * Request header carrying the id of an open diagnostics scope.
+ *
+ * The SSE test helpers (`injectApiSSE`, `connectApiSSE`) set it on every request they make;
+ * routes built with `buildApiRoute` honour it by instrumenting the session they hand to the
+ * handler. A value that does not name a scope opened in this process is ignored, so the
+ * header is inert outside a test run — a client cannot make a production server record
+ * anything by sending it.
+ */
+export const SSE_DIAGNOSTICS_HEADER = 'x-om-sse-diagnostics-id';
+/** Cap per scope, so a handler failing in a loop can't grow the registry without bound. */
+const MAX_FAILURES_PER_SCOPE = 50;
+/** How far to walk an error's `cause` chain when matching it to a recorded failure. */
+const MAX_CAUSE_DEPTH = 10;
+/**
+ * The failures of one observed request, plus whether the route recovered from them.
+ *
+ * Split from {@link SSEDiagnosticsScope} because the two ends see different things: the scope
+ * is the reader's handle (it can only snapshot and unregister), while the recorder is what the
+ * instrumented route writes to.
+ */
+class SSEDiagnosticsRecorder {
+    failures = [];
+    settled = false;
+    /** Record a send that threw, and the Zod issues behind it when the payload explains it. */
+    recordSendFailure(schemaByEventName, eventName, data, error) {
+        if (this.failures.length >= MAX_FAILURES_PER_SCOPE) {
+            return;
+        }
+        const issues = issuesFor(schemaByEventName, eventName, data);
+        this.failures.push({
+            eventName,
+            data,
+            message: messageOf(error),
+            ...(issues && { issues }),
+            error,
+            handled: false,
+        });
+    }
+    /** Record a `sendStream()` source that threw while producing its next message. */
+    recordSourceFailure(error) {
+        if (this.failures.length >= MAX_FAILURES_PER_SCOPE) {
+            return;
+        }
+        this.failures.push({ message: messageOf(error), error, handled: false });
+    }
+    /**
+     * The route handler settled: everything recorded so far that did not escape it was caught
+     * by the route, which went on to produce the rest of the response.
+     *
+     * Called once per request, before the response ends, so the helpers reading the stream see
+     * final `handled` flags. Failures recorded afterwards — a send on a `keepAlive` session the
+     * handler already returned from — stay unhandled: nothing observably recovered from them.
+     *
+     * @param escaped - The error the handler threw, if it threw
+     */
+    settle(escaped) {
+        if (this.settled) {
+            return;
+        }
+        this.settled = true;
+        for (const failure of this.failures) {
+            failure.handled = !causedBy(escaped, failure.error);
+        }
+    }
+}
+const openScopes = new Map();
+let nextScopeId = 0;
+/**
+ * Open a diagnostics scope for a single request.
+ *
+ * @internal Used by the SSE test helpers; tests reach the failures through the helper they
+ * called, not through this registry.
+ */
+export function openSSEDiagnosticsScope() {
+    const id = `sse-diag-${++nextScopeId}`;
+    openScopes.set(id, new SSEDiagnosticsRecorder());
+    let snapshot;
+    return {
+        id,
+        headers: { [SSE_DIAGNOSTICS_HEADER]: id },
+        failures: () => snapshot ?? [...(openScopes.get(id)?.failures ?? [])],
+        dispose: () => {
+            if (!snapshot) {
+                snapshot = [...(openScopes.get(id)?.failures ?? [])];
+                openScopes.delete(id);
+            }
+        },
+    };
+}
+/**
+ * How many diagnostics scopes are registered right now.
+ *
+ * @internal Exists so the helpers' own specs can prove that every path out of a request
+ * unregisters its scope: a leaked one keeps its records alive for the rest of the process and
+ * costs every later request the fast path below.
+ */
+export function countOpenSSEDiagnosticsScopes() {
+    return openScopes.size;
+}
+/** The recorder a request writes to, or `undefined` when it belongs to no open scope. */
+function resolveRecorder(headers) {
+    // Fast path for production traffic: with no scope open the header can't match anything.
+    if (openScopes.size === 0) {
+        return undefined;
+    }
+    const header = headers[SSE_DIAGNOSTICS_HEADER];
+    const id = Array.isArray(header) ? header[0] : header;
+    return id === undefined ? undefined : openScopes.get(id);
+}
+/** Re-validate a payload to recover the structured issues the thrown error only carries as text. */
+function issuesFor(schemaByEventName, eventName, data) {
+    const schema = schemaByEventName[eventName];
+    if (!schema) {
+        return undefined;
+    }
+    const result = schema.safeParse(data);
+    return result.success ? undefined : result.error.issues;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Whether `error` is `candidate`, or was thrown wrapping it as a `cause`.
+ *
+ * A handler that rethrows the send error as-is is the common case; one that wraps it in its
+ * own error still did not recover from it, so the chain is walked (to a bounded depth, since
+ * a `cause` chain can be cyclic).
+ */
+function causedBy(error, candidate) {
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current !== undefined && current !== null; depth++) {
+        if (current === candidate) {
+            return true;
+        }
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return false;
+}
+/**
+ * Instrument an SSE session so that failed sends are recorded against the diagnostics scope
+ * the request names, then rethrown unchanged.
+ *
+ * A no-op unless the request carries {@link SSE_DIAGNOSTICS_HEADER} with the id of a scope
+ * open in this process, which only the SSE test helpers ever produce.
+ *
+ * @param session - The session handed to the handler by `sse.start()`
+ * @param schemaByEventName - The contract's merged SSE event schemas, used to recover the
+ *   Zod issues behind a validation failure
+ *
+ * @internal Called by `buildApiRoute`; not part of the application-facing API.
+ */
+export function attachSSESendDiagnostics(session, schemaByEventName) {
+    const recorder = resolveRecorder(session.request.headers);
+    if (!recorder) {
+        return;
+    }
+    const originalSend = session.send.bind(session);
+    session.send = async (eventName, data, options) => {
+        try {
+            return await originalSend(eventName, data, options);
+        }
+        catch (error) {
+            recorder.recordSendFailure(schemaByEventName, eventName, data, error);
+            throw error;
+        }
+    };
+    const originalSendStream = session.sendStream.bind(session);
+    session.sendStream = async (messages) => {
+        // The send that throws happens inside `sendStream`, which reports neither the event name
+        // nor the payload. Wrapping the source names it: `pending` holds the message handed to
+        // the sender, and is cleared when the sender comes back for the next one — which only
+        // happens once the previous send resolved. So a rejection with `pending` set is a failed
+        // send of that message, and one without is the source itself throwing.
+        let pending;
+        async function* tracked() {
+            for await (const message of messages) {
+                pending = message;
+                yield message;
+                pending = undefined;
+            }
+        }
+        try {
+            await originalSendStream(tracked());
+        }
+        catch (error) {
+            if (pending) {
+                recorder.recordSendFailure(schemaByEventName, pending.event, pending.data, error);
+            }
+            else {
+                recorder.recordSourceFailure(error);
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Wrap a route handler so the diagnostics scope learns whether the route recovered from the
+ * sends it could not make.
+ *
+ * A send that throws is only a reason for a test to fail when nothing caught it: a handler
+ * that catches its own failed send and streams a fallback instead produced exactly the
+ * response it meant to. Observing how the handler settled is what tells the two apart —
+ * {@link SSESendFailure.handled}.
+ *
+ * A no-op for requests that name no open diagnostics scope: outside a test run this is one
+ * `Map.size` check per request on SSE routes.
+ *
+ * @internal Applied by `buildApiRoute` to SSE-capable routes.
+ */
+export function reportSSEHandlerOutcome(handler) {
+    const instrumented = function instrumentedHandler(request, reply) {
+        const recorder = resolveRecorder(request.headers);
+        if (!recorder) {
+            return handler.call(this, request, reply);
+        }
+        let result;
+        try {
+            result = handler.call(this, request, reply);
+        }
+        catch (error) {
+            // A handler that throws before returning a promise never opened a stream to recover in.
+            recorder.settle(error);
+            throw error;
+        }
+        return Promise.resolve(result).then((value) => {
+            recorder.settle();
+            // Whatever the wrapped handler resolves to is what Fastify sends: pass it through.
+            return value;
+        }, (error) => {
+            recorder.settle(error);
+            throw error;
+        });
+    };
+    return instrumented;
+}
+/**
+ * The failures the route did not recover from — the ones that truncated the response, and so
+ * explain an event a test waited for and never saw.
+ *
+ * @internal
+ */
+export function unhandledSendFailures(failures) {
+    return failures.filter((failure) => !failure.handled);
+}
+/**
+ * Render recorded failures as the message of the error the test helpers throw.
+ *
+ * @internal
+ */
+export function describeSendFailures(failures) {
+    const lines = failures.map((failure) => `  - ${describeSendFailure(failure)}`);
+    const subject = failures.length === 1 ? 'failure' : 'failures';
+    return `${failures.length} SSE send ${subject} recorded for this request:\n${lines.join('\n')}`;
+}
+function describeSendFailure(failure) {
+    const recovered = failure.handled ? ' (caught by the route, which completed the response)' : '';
+    if (failure.eventName === undefined) {
+        return `the sendStream() source threw before the next event: ${failure.message}${recovered}`;
+    }
+    const detail = failure.issues
+        ? failure.issues
+            .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+            .join('; ')
+        : failure.message;
+    return `event "${failure.eventName}" was never sent: ${detail}; payload: ${safeStringify(failure.data)}${recovered}`;
+}
+/** JSON for an error message, degrading to `String()` for anything JSON can't take. */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=sseSendDiagnostics.js.map

package/dist/lib/sse/sseSendDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseSendDiagnostics.js","sourceRoot":"","sources":["../../../lib/sse/sseSendDiagnostics.ts"],"names":[],"mappings":"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"}

package/dist/lib/testing/apiSseEventValidation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Contract-aware SSE event validation, shared by the inject helpers (`injectApiSSE`) and the
+ * real-HTTP ones (`connectApiSSE`, `SSEHttpClient.apiEvents`) so both paths produce the same
+ * discriminated union, validated against the same schemas and reporting the same errors.
+ *
+ * @internal
+ */
+import type { SSEEventSchemas } from '@lokalise/api-contracts';
+import { type ApiContract } from '@lokalise/api-contracts';
+import type { ParsedSSEEvent } from '../sse/sseParser.ts';
+import type { ApiSSEEvent } from './apiSseTestTypes.ts';
+/**
+ * The contract's SSE schemas, merged across every declared status, or a thrown error naming
+ * the reader that asked for them.
+ */
+export declare function resolveApiSseSchemas(contract: ApiContract, reader: string): SSEEventSchemas;
+/**
+ * Validate one parsed event against the contract's schemas and return it as a member of the
+ * contract's event union.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @throws if the contract declares no schema for the event name, if `data` isn't valid JSON,
+ *   or if the payload doesn't match the declared schema
+ */
+export declare function validateApiSseEvent<Contract extends ApiContract>(schemaByEventName: SSEEventSchemas, event: ParsedSSEEvent, reader: string): ApiSSEEvent<Contract>;
+/** Media type an SSE response must carry. */
+export declare const SSE_CONTENT_TYPE = "text/event-stream";
+/** Strip `; charset=…` style parameters from a media type. */
+export declare function mediaTypeOf(contentType: string | undefined): string | undefined;
+/**
+ * Reject a response that is not an event stream, naming the reader that asked for one.
+ *
+ * Shared by both read paths so an endpoint answering with a JSON error (a 401 before
+ * `sse.start()`, say) fails with its status and body on either — rather than as zero events,
+ * which reads as a timeout on the HTTP path and an empty array on the inject one.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @param body - Response body, when the caller can produce it without consuming a live stream
+ */
+export declare function assertSSEResponse(statusCode: number, contentType: string | undefined, reader: string, body?: string): void;

package/dist/lib/testing/apiSseEventValidation.js

@@ -0,0 +1,78 @@
+/**
+ * Contract-aware SSE event validation, shared by the inject helpers (`injectApiSSE`) and the
+ * real-HTTP ones (`connectApiSSE`, `SSEHttpClient.apiEvents`) so both paths produce the same
+ * discriminated union, validated against the same schemas and reporting the same errors.
+ *
+ * @internal
+ */
+import { getSseSchemaByEventName } from '@lokalise/api-contracts';
+import { truncateBody } from "./sseInjectShared.js";
+/**
+ * The contract's SSE schemas, merged across every declared status, or a thrown error naming
+ * the reader that asked for them.
+ */
+export function resolveApiSseSchemas(contract, reader) {
+    const schemaByEventName = getSseSchemaByEventName(contract);
+    if (!schemaByEventName) {
+        throw new Error(`${reader} — the contract declares no SSE response`);
+    }
+    return schemaByEventName;
+}
+/**
+ * Validate one parsed event against the contract's schemas and return it as a member of the
+ * contract's event union.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @throws if the contract declares no schema for the event name, if `data` isn't valid JSON,
+ *   or if the payload doesn't match the declared schema
+ */
+export function validateApiSseEvent(schemaByEventName, event, reader) {
+    // An SSE event without an `event:` field is a `message` event per the spec.
+    const name = event.event ?? 'message';
+    const schema = schemaByEventName[name];
+    if (!schema) {
+        throw new Error(`${reader} — the contract declares no schema for event "${name}"`);
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(event.data);
+    }
+    catch (err) {
+        throw new Error(`${reader} — data of event "${name}" is not valid JSON: ${err.message}; data: ${truncateBody(event.data)}`);
+    }
+    const parsed = schema.safeParse(parsedJson);
+    if (!parsed.success) {
+        throw new Error(`${reader} — data of event "${name}" does not match the declared schema: ${parsed.error.message}; data: ${truncateBody(event.data)}`);
+    }
+    return {
+        ...(event.id !== undefined && { id: event.id }),
+        ...(event.retry !== undefined && { retry: event.retry }),
+        event: name,
+        data: parsed.data,
+    };
+}
+/** Media type an SSE response must carry. */
+export const SSE_CONTENT_TYPE = 'text/event-stream';
+/** Strip `; charset=…` style parameters from a media type. */
+export function mediaTypeOf(contentType) {
+    return contentType?.split(';')[0]?.trim().toLowerCase();
+}
+/**
+ * Reject a response that is not an event stream, naming the reader that asked for one.
+ *
+ * Shared by both read paths so an endpoint answering with a JSON error (a 401 before
+ * `sse.start()`, say) fails with its status and body on either — rather than as zero events,
+ * which reads as a timeout on the HTTP path and an empty array on the inject one.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @param body - Response body, when the caller can produce it without consuming a live stream
+ */
+export function assertSSEResponse(statusCode, contentType, reader, body) {
+    const mediaType = mediaTypeOf(contentType);
+    if (mediaType === SSE_CONTENT_TYPE) {
+        return;
+    }
+    const bodySuffix = body === undefined || body === '' ? '' : ` Body: ${truncateBody(body)}`;
+    throw new Error(`${reader} — response is not an SSE stream (status ${statusCode}, content-type ${mediaType ?? 'absent'}); use bodyForStatus(${statusCode}) for declared error responses.${bodySuffix}`);
+}
+//# sourceMappingURL=apiSseEventValidation.js.map

package/dist/lib/testing/apiSseEventValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiSseEventValidation.js","sourceRoot":"","sources":["../../../lib/testing/apiSseEventValidation.ts"],"names":[],"mappings":"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"}

package/dist/lib/testing/apiSseHttpHelpers.d.ts

@@ -0,0 +1,168 @@
+import { type ApiContract } from '@lokalise/api-contracts';
+import type { SpiedSSESession, SSESessionSpy } from '../sse/SSESessionSpy.ts';
+import { type SSEDiagnosticsScope, type SSESendFailure } from '../sse/sseSendDiagnostics.ts';
+import type { ApiSSEEvent, InjectApiSSEParams } from './apiSseTestTypes.ts';
+import { SSEHttpClient } from './sseHttpClient.ts';
+/**
+ * Request params for {@link connectApiSSE}, derived from a `defineApiContract` contract.
+ *
+ * The same shape `injectApiSSE` takes — `pathParams`, `body`, `queryParams` and `headers` are
+ * each required only when the contract declares the matching request schema, `headers` also
+ * accepts a (sync or async) factory, and `pathPrefix` is always optional.
+ */
+export type ConnectApiSSEParams<Contract extends ApiContract> = InjectApiSSEParams<Contract>;
+/** Options for waiting on server-side registration, driven by a standalone session spy. */
+export type ConnectApiSSEWithSpyOptions<TSession extends SpiedSSESession> = {
+    /**
+     * Wait for server-side connection registration after HTTP headers are received, removing
+     * the race between `connect()` returning and the handler finishing its registration.
+     *
+     * Only meaningful for `keepAlive` sessions — an `autoClose` route closes its session as the
+     * handler returns, before the wait can claim it.
+     */
+    awaitServerConnection: {
+        /** A standalone spy, wired to the route via `createSSESessionSpy()`'s `routeOptions` */
+        spy: SSESessionSpy<TSession>;
+        /** Timeout in milliseconds (default: 5000) */
+        timeout?: number;
+    };
+};
+/** Result of {@link connectApiSSE} when `awaitServerConnection` is used. */
+export type ConnectApiSSEResult<Contract extends ApiContract, TSession extends SpiedSSESession> = {
+    client: ApiSSEHttpClient<Contract>;
+    serverConnection: TSession;
+};
+/**
+ * A live SSE connection over real HTTP, read through the contract that declares it.
+ *
+ * The contract-typed counterpart of {@link SSEHttpClient}: events arrive incrementally, as
+ * they do there, but each one is JSON-parsed, validated against the contract's `sseResponse` /
+ * `sseBody` schemas and typed as a discriminated union on `event` — the same events
+ * `injectApiSSE` produces, so a suite can move an assertion between the two paths unchanged.
+ */
+export declare class ApiSSEHttpClient<Contract extends ApiContract> {
+    /** The underlying untyped client, for the parts of it this wrapper doesn't cover. */
+    readonly raw: SSEHttpClient;
+    private readonly contract;
+    private readonly scope;
+    /** @internal Built by {@link connectApiSSE}. */
+    constructor(raw: SSEHttpClient, contract: Contract, scope: SSEDiagnosticsScope);
+    /**
+     * The fetch `Response`, available before any event is consumed — so status and headers can
+     * be asserted while the handler is still producing events.
+     */
+    get response(): Response;
+    /**
+     * Yield the contract's events as they arrive, typed and validated per event name.
+     *
+     * Throws — before yielding anything — if the endpoint answered with something other than an
+     * event stream (an error raised before `sse.start()`, say), naming its status and body
+     * instead of reporting an empty stream.
+     *
+     * @param signal - Optional `AbortSignal` to stop the generator early
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.events()) {
+     *   if (event.event === 'issue') expect(event.data.severity).toBe('minor')
+     *   if (event.event === 'review') break
+     * }
+     * ```
+     */
+    events(signal?: AbortSignal): AsyncGenerator<ApiSSEEvent<Contract>, void, unknown>;
+    /**
+     * Collect events until a count is reached or a predicate matches, each one typed and
+     * validated against the contract.
+     *
+     * A collection that ends short — the stream closed early, or the wait timed out — usually
+     * means the handler failed to send an event it was supposed to; when that is what happened,
+     * the thrown error names the event and its validation issues instead of leaving the test to
+     * report a missing event with no reason.
+     *
+     * Throws straight away if the endpoint answered with something other than an event stream,
+     * rather than waiting out the timeout on a stream that was never going to arrive.
+     *
+     * @param countOrPredicate - Number of events to collect, or a predicate that ends collection
+     *   (the matching event is included). The predicate is invoked exactly once per event.
+     * @param timeout - Maximum time to wait in milliseconds (default: 5000)
+     */
+    collectEvents(countOrPredicate: number | ((event: ApiSSEEvent<Contract>) => boolean), timeout?: number): Promise<ApiSSEEvent<Contract>[]>;
+    /**
+     * Throw what the handler failed to send and did not recover from, if anything was recorded
+     * for this connection.
+     *
+     * A failure the route caught and streamed around left the response it meant to produce, so
+     * it is reported through {@link ApiSSEHttpClient.sendFailures} instead of failing the read.
+     */
+    private assertNoSendFailures;
+    /**
+     * Reject a response that is not an event stream, with its status and body.
+     *
+     * Without this a `401` (or any other pre-stream error response) reads as a stream that
+     * never produced an event: `collectEvents` waits out its full timeout and reports "got 0",
+     * with the actual status nowhere in the failure.
+     */
+    private assertStreamResponse;
+    /**
+     * Unregister the diagnostics scope once the stream is over, keeping what it recorded.
+     *
+     * `close()` is the usual trigger; a test that reads a stream to its end and never closes the
+     * client would otherwise leave the scope registered for the rest of the process.
+     */
+    private releaseScopeIfClosed;
+    /**
+     * The sends the handler could not make on this connection — a payload that failed the
+     * contract's schema for its event, say — recorded instead of being left in the server log.
+     *
+     * Includes the failures the route recovered from (`handled: true`), which the readers pass
+     * over precisely because the response was still the one the route meant to produce.
+     *
+     * Only routes built with this package's `buildApiRoute` report them.
+     */
+    sendFailures(): SSESendFailure[];
+    /** Close the connection from the client side. */
+    close(): void;
+}
+/**
+ * Connect to an SSE endpoint over real HTTP using a contract built with `defineApiContract`.
+ *
+ * The contract-aware counterpart of `SSEHttpClient.connect`: the method, path, query params,
+ * headers and body all come from the contract instead of being repeated as string literals
+ * next to it, and the events are typed and validated the way `injectApiSSE().events()` types
+ * them — so the tests that read a stream as it arrives keep the contract typing rather than
+ * casting `ParsedSSEEvent.data` by hand.
+ *
+ * Use this (over `injectApiSSE`) when the endpoint keeps its connection open: a `keepAlive`
+ * session never completes its response, so only a real HTTP connection can read it.
+ *
+ * @param baseUrl - Base URL of the running server (e.g. `SSETestServer.baseUrl`)
+ * @param contract - Contract built with `defineApiContract`
+ * @param params - Request params derived from the contract
+ * @param options - `awaitServerConnection`, to also wait for server-side registration
+ *
+ * @example
+ * ```typescript
+ * const client = await connectApiSSE(server.baseUrl, lqaTextSegmentContract, { body })
+ *
+ * expect(client.response.status).toBe(200)  // asserted while the handler is still working
+ * for await (const event of client.events()) {
+ *   if (event.event === 'issue') expect(event.data.severity).toBe('minor')  // typed
+ * }
+ * client.close()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // keepAlive route: wait for the server-side session, then drive it from the test
+ * const { spy, routeOptions } = createSSESessionSpy()
+ * const { client, serverConnection } = await connectApiSSE(
+ *   server.baseUrl,
+ *   tickStreamContract,
+ *   { pathParams: { channelId: 'c1' }, queryParams: { count: 2 }, headers },
+ *   { awaitServerConnection: { spy } },
+ * )
+ * await serverConnection.send('tick', { channelId: 'c1', n: 1 })
+ * ```
+ */
+export declare function connectApiSSE<const Contract extends ApiContract>(baseUrl: string, contract: Contract, params: ConnectApiSSEParams<Contract>): Promise<ApiSSEHttpClient<Contract>>;
+export declare function connectApiSSE<const Contract extends ApiContract, TSession extends SpiedSSESession>(baseUrl: string, contract: Contract, params: ConnectApiSSEParams<Contract>, options: ConnectApiSSEWithSpyOptions<TSession>): Promise<ConnectApiSSEResult<Contract, TSession>>;