@boxrouter/sdk 0.0.1-alpha.0 → 0.12.190

package/dist/core/responseValidators/volumes.cjs

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./compact.cjs")({"roots":{"validate0":{"$":0},"validate1":{"$":1},"validate2":{"$":1},"validate3":{"$":7},"validate4":{"$":8},"validate5":{"$":8},"validate6":{"$":12},"validate7":{"$":16},"validate8":{"$":17},"validate9":{"$":18}},"definitions":[{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$":1}},"next_cursor":{"type":["string","null"]},"stored_bytes":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"live_volume_policy":{"$":6},"allowance_bytes":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"gib_hours_this_month":{"minimum":0,"allOf":[{"anyOf":[{"type":"number"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}}}},{"type":"object","required":["id","name","state","labels","created_at","updated_at","last_used_at","head_checkpoint","checkpoint_count","stored_bytes","limits","attachments"],"properties":{"id":{"$":2},"name":{"$":3},"state":{"type":"string"},"labels":{"type":"object","additionalProperties":{"type":"string"}},"observed_volume_bytes":{"minimum":0,"allOf":[{"anyOf":[{"type":["integer","null"]},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"head_checkpoint":{"minimum":1,"allOf":[{"anyOf":[{"type":["integer","null"]},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":1}},"checkpoint_count":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"stored_bytes":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"limits":{"$":4},"attachments":{"type":"array","items":{"$":5}}}},{"type":"string","pattern":"^vol_[0-9a-f]{32}$"},{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"},{"type":"object","required":["max_checkpoints"],"properties":{"max_checkpoints":{"minimum":1,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":1}}}},{"type":"object","required":["sandbox_id","access","attached_at","restored_checkpoint"],"properties":{"sandbox_id":{"type":"string"},"access":{"type":"string","enum":["write","read","shared","branch"]},"attached_at":{"type":["string","null"],"format":"date-time"},"restored_checkpoint":{"minimum":1,"allOf":[{"anyOf":[{"type":["integer","null"]},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":1}}}},{"type":"object","required":["enabled","soft_quota_bytes"],"properties":{"enabled":{"type":"boolean"},"soft_quota_bytes":{"minimum":1,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":1}}}},{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$":8}},"next_cursor":{"type":["string","null"]}}},{"type":"object","required":["volume_id","checkpoint","state","created_at","reason","saved_on","image","arch","user","path","observed_volume_bytes","duration_ms","message"],"properties":{"volume_id":{"$":2},"checkpoint":{"minimum":1,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":1}},"state":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"reason":{"type":"string"},"saved_on":{"$":9},"image":{"$":10},"arch":{"type":"string","enum":["amd64","arm64"]},"user":{"$":11},"path":{"type":"string","pattern":"^/[^\\u0000]*$"},"observed_volume_bytes":{"minimum":0,"allOf":[{"anyOf":[{"type":["integer","null"]},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"duration_ms":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"message":{"type":["string","null"],"maxLength":500}}},{"type":"object","required":["sandbox_id","provider","class","region"],"properties":{"sandbox_id":{"type":"string"},"provider":{"type":"string"},"class":{"type":["string","null"]},"region":{"type":["string","null"]}}},{"type":"object","required":["value","digest"],"properties":{"value":{"type":"string"},"digest":{"type":["string","null"]}}},{"type":"object","required":["name","uid"],"properties":{"name":{"type":"string"},"uid":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}}}},{"type":"object","required":["id","volume_id","path","size","part_size","parts","expires_at"],"properties":{"id":{"$":13},"volume_id":{"$":2},"path":{"$":14},"size":{"minimum":0,"maximum":5497558138880,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0,"maximum":5497558138880}},"part_size":{"minimum":1,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":1}},"parts":{"type":"array","minItems":1,"maxItems":10000,"items":{"$":15}},"expires_at":{"type":"string","format":"date-time"}}},{"type":"string","pattern":"^vup_[0-9a-f]{32}$"},{"type":"string","minLength":1,"maxLength":1024,"pattern":"^(?!/)(?!.*//)(?!\\.{1,2}(?:/|$))(?!.*\\/\\.{1,2}(?:/|$))(?!.*\\u0000).+$"},{"type":"object","required":["number","size","url"],"properties":{"number":{"minimum":1,"maximum":10000,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":1,"maximum":10000}},"size":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"url":{"type":"string","format":"uri"}}},{"type":"object","required":["path","size"],"properties":{"path":{"$":14},"size":{"minimum":0,"maximum":5497558138880,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0,"maximum":5497558138880}}}},{"type":"object","required":["url","path","size","expires_at"],"properties":{"url":{"type":"string","format":"uri"},"path":{"$":14},"size":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"expires_at":{"type":"string","format":"date-time"}}},{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$":19}},"next_cursor":{"type":["string","null"]}}},{"type":"object","required":["path","size","modified_at"],"properties":{"path":{"$":14},"size":{"minimum":0,"allOf":[{"anyOf":[{"type":"integer"},{"x-boxrouter-bigint":true}]}],"x-boxrouter-bigint-range":{"minimum":0}},"modified_at":{"type":"string","format":"date-time"}}}]});

package/dist/core/responseValidators/volumes.d.cts

@@ -0,0 +1,10 @@
+export declare const validate0: (value: unknown) => boolean;
+export declare const validate1: (value: unknown) => boolean;
+export declare const validate2: (value: unknown) => boolean;
+export declare const validate3: (value: unknown) => boolean;
+export declare const validate4: (value: unknown) => boolean;
+export declare const validate5: (value: unknown) => boolean;
+export declare const validate6: (value: unknown) => boolean;
+export declare const validate7: (value: unknown) => boolean;
+export declare const validate8: (value: unknown) => boolean;
+export declare const validate9: (value: unknown) => boolean;

package/dist/core/serverSentEvents.gen.d.ts

@@ -1,71 +1,30 @@
-import type { Config } from './types.gen.js';
+import { StreamHTTPError } from './streamErrors';
+import type { Config } from './types.gen';
+type EventValue<T> = T extends Record<string, unknown> ? T[keyof T] : T;
+export interface StreamEvent<TData = unknown> {
+    data: TData;
+    event?: string;
+    id?: string;
+}
 export type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, 'method'> & Pick<Config, 'method' | 'responseTransformer' | 'responseValidator'> & {
-    /**
-     * Fetch API implementation. You can use this option to provide a custom
-     * fetch instance.
-     *
-     * @default globalThis.fetch
-     */
     fetch?: typeof fetch;
-    /**
-     * Implementing clients can call request interceptors inside this hook.
-     */
     onRequest?: (url: string, init: RequestInit) => Promise<Request>;
-    /**
-     * Callback invoked when a network or parsing error occurs during streaming.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @param error The error that occurred.
-     */
     onSseError?: (error: unknown) => void;
-    /**
-     * Callback invoked when an event is streamed from the server.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @param event Event streamed from the server.
-     * @returns Nothing (void).
-     */
-    onSseEvent?: (event: StreamEvent<TData>) => void;
+    onSseEvent?: (event: TData) => void;
     serializedBody?: RequestInit['body'];
-    /**
-     * Default retry delay in milliseconds.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @default 3000
-     */
-    sseDefaultRetryDelay?: number;
-    /**
-     * Maximum number of retry attempts before giving up.
-     */
-    sseMaxRetryAttempts?: number;
-    /**
-     * Maximum retry delay in milliseconds.
-     *
-     * Applies only when exponential backoff is used.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @default 30000
-     */
-    sseMaxRetryDelay?: number;
-    /**
-     * Optional sleep function for retry backoff.
-     *
-     * Defaults to using `setTimeout`.
-     */
-    sseSleepFn?: (ms: number) => Promise<void>;
+    /** Maximum SSE block bytes after CR/CRLF normalization, including fields and delimiters. */
+    sseMaxBufferSize?: number;
+    /** @internal Generated operation completion check, before successful EOF. */
+    validateStreamEnd?: () => void;
+    /** @internal Canonical generated path, before parameter substitution. */
+    telemetryPath?: string;
     url: string;
 };
-export interface StreamEvent<TData = unknown> {
-    data: TData;
-    event?: string;
-    id?: string;
-    retry?: number;
-}
 export type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unknown> = {
-    stream: AsyncGenerator<TData extends Record<string, unknown> ? TData[keyof TData] : TData, TReturn, TNext>;
+    stream: AsyncGenerator<EventValue<TData>, TReturn, TNext>;
+    /** Interrupt pending reads and close this HTTP stream, without cancelling remote work. */
+    close: () => void;
 };
-export declare function createSseClient<TData = unknown>({ onRequest, onSseError, onSseEvent, responseTransformer, responseValidator, sseDefaultRetryDelay, sseMaxRetryAttempts, sseMaxRetryDelay, sseSleepFn, url, ...options }: ServerSentEventsOptions): ServerSentEventsResult<TData>;
+export { StreamHTTPError };
+/** One request, incremental SSE envelopes, no reconnect or mutation replay. */
+export declare function createSseClient<TData = unknown>({ onRequest, onSseError, onSseEvent, responseTransformer, responseValidator, fetch: fetchImplementation, serializedBody, sseMaxBufferSize, validateStreamEnd, telemetryPath, url, signal, ...options }: ServerSentEventsOptions): ServerSentEventsResult<TData>;

package/dist/core/serverSentEvents.gen.js

@@ -1,132 +1,313 @@
-// This file is auto-generated by @hey-api/openapi-ts
-export function createSseClient({ onRequest, onSseError, onSseEvent, responseTransformer, responseValidator, sseDefaultRetryDelay, sseMaxRetryAttempts, sseMaxRetryDelay, sseSleepFn, url, ...options }) {
-    let lastEventId;
-    const sleep = sseSleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-    const createStream = async function* () {
-        let retryDelay = sseDefaultRetryDelay ?? 3000;
-        let attempt = 0;
-        const signal = options.signal ?? new AbortController().signal;
-        while (true) {
-            if (signal.aborted)
-                break;
-            attempt++;
-            const headers = options.headers instanceof Headers
-                ? options.headers
-                : new Headers(options.headers);
-            if (lastEventId !== undefined) {
-                headers.set('Last-Event-ID', lastEventId);
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamHTTPError = void 0;
+exports.createSseClient = createSseClient;
+const eventsource_parser_1 = require("eventsource-parser");
+const api_1 = require("@opentelemetry/api");
+const json_1 = require("./json");
+const api_error_1 = require("../api-error");
+const streamErrors_1 = require("./streamErrors");
+Object.defineProperty(exports, "StreamHTTPError", { enumerable: true, get: function () { return streamErrors_1.StreamHTTPError; } });
+const telemetry_1 = require("../telemetry");
+const workflow_policy_gen_1 = require("../workflow-policy.gen");
+function monotonicMilliseconds() {
+    try {
+        const performance = globalThis.performance;
+        const value = performance?.now?.call(performance);
+        return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Bound raw bytes before text decoding or the library can buffer a partial event. */
+function boundedInput(limit) {
+    let size = 0;
+    let lineBytes = 0;
+    let skipLf = false;
+    return new TransformStream({
+        transform(chunk, controller) {
+            for (const byte of chunk) {
+                if (byte === 10 && skipLf) {
+                    skipLf = false;
+                    continue;
+                }
+                if (++size > limit)
+                    throw Object.assign(new RangeError(`SSE block exceeds ${limit} normalized bytes`), { type: 'max-buffer-size-exceeded' });
+                if (byte === 10 || byte === 13) {
+                    if (lineBytes === 0)
+                        size = 0;
+                    lineBytes = 0;
+                    skipLf = byte === 13;
+                }
+                else {
+                    skipLf = false;
+                    lineBytes++;
+                }
             }
-            try {
-                const requestInit = {
-                    redirect: 'follow',
-                    ...options,
-                    body: options.serializedBody,
-                    headers,
-                    signal,
-                };
-                let request = new Request(url, requestInit);
-                if (onRequest) {
-                    request = await onRequest(url, requestInit);
+            controller.enqueue(chunk);
+        },
+    });
+}
+function eventParser(maxBufferSize) {
+    let parser;
+    let lastId;
+    return new TransformStream({
+        start(controller) {
+            parser = (0, eventsource_parser_1.createParser)({
+                maxBufferSize,
+                onId(id) { lastId = id; },
+                onEvent(event) {
+                    // Snapshot the cursor before later blocks in this chunk can update it.
+                    controller.enqueue({ ...event, id: lastId });
+                },
+                onError(error) {
+                    if (error.type === 'max-buffer-size-exceeded')
+                        controller.error(error);
+                },
+            });
+        },
+        transform(chunk) { parser.feed(chunk); },
+    });
+}
+async function httpError(request, response, signal) {
+    const reader = response.body?.getReader();
+    const abort = () => { void reader?.cancel(signal.reason).catch(() => { }); };
+    const buffer = new Uint8Array(workflow_policy_gen_1.MAX_ERROR_BYTES);
+    let length = 0;
+    let truncated = false;
+    signal.addEventListener('abort', abort, { once: true });
+    try {
+        if (signal.aborted)
+            abort();
+        signal.throwIfAborted();
+        if (reader) {
+            while (true) {
+                const { done, value } = await reader.read();
+                signal.throwIfAborted();
+                if (done)
+                    break;
+                const remaining = workflow_policy_gen_1.MAX_ERROR_BYTES - length;
+                buffer.set(value.subarray(0, remaining), length);
+                length += Math.min(value.byteLength, remaining);
+                if (value.byteLength > remaining) {
+                    truncated = true;
+                    break;
                 }
-                // fetch must be assigned here, otherwise it would throw the error:
-                // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
-                const _fetch = options.fetch ?? globalThis.fetch;
-                const response = await _fetch(request);
-                if (!response.ok)
-                    throw new Error(`SSE failed: ${response.status} ${response.statusText}`);
-                if (!response.body)
-                    throw new Error('No body in SSE response');
-                const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
-                let buffer = '';
-                const abortHandler = () => {
-                    try {
-                        reader.cancel();
-                    }
-                    catch {
-                        // noop
-                    }
-                };
-                signal.addEventListener('abort', abortHandler);
+            }
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        if (reader) {
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+    }
+    // Fetch supplies decoded bytes. Keep upstream headers for diagnostics; their
+    // Content-Length describes the original response, not the bounded body copy.
+    const captured = new Response(length ? buffer.slice(0, length) : null, {
+        status: response.status, statusText: response.statusText, headers: response.headers,
+    });
+    let payload;
+    try {
+        payload = (0, json_1.parseJson)(new TextDecoder().decode(buffer.subarray(0, length)));
+    }
+    catch { /* Malformed diagnostics do not replace the HTTP failure. */ }
+    return new streamErrors_1.StreamHTTPError(request, captured, truncated, payload);
+}
+/** One request, incremental SSE envelopes, no reconnect or mutation replay. */
+function createSseClient({ onRequest, onSseError, onSseEvent, responseTransformer, responseValidator, fetch: fetchImplementation = globalThis.fetch, serializedBody, sseMaxBufferSize = workflow_policy_gen_1.DEFAULT_EVENT_BYTES, validateStreamEnd, telemetryPath, url, signal, ...options }) {
+    const controller = new AbortController();
+    const parent = api_1.context.active();
+    async function* receive() {
+        let reader;
+        let pipes = [];
+        let response;
+        let request;
+        const telemetry = new telemetry_1.RequestTrace(options.method, telemetryPath, parent);
+        let completed = false;
+        let failed = false;
+        let events = 0;
+        let eventProcessingChecked = false;
+        let eventProcessingRecording = false;
+        let eventProcessingMeasured = true;
+        let eventProcessingMilliseconds = 0;
+        let firstEventReadyStarted;
+        let firstEventReadyMeasured = true;
+        let firstEventReadyMilliseconds;
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            if (signal?.aborted)
+                abort();
+            controller.signal.throwIfAborted();
+            if (!Number.isSafeInteger(sseMaxBufferSize) || sseMaxBufferSize < 1) {
+                throw new RangeError('sseMaxBufferSize must be a positive safe integer');
+            }
+            const headers = new Headers(options.headers);
+            if (!headers.has('Accept'))
+                headers.set('Accept', 'text/event-stream');
+            const init = {
+                redirect: 'error', ...options, headers, body: serializedBody, signal: controller.signal,
+            };
+            request = onRequest ? await onRequest(url, init) : new Request(url, init);
+            controller.signal.throwIfAborted();
+            telemetry.inject(request.headers);
+            const sentRequest = request;
+            response = await telemetry.fetchResponse(() => api_1.context.with(telemetry.context, () => fetchImplementation(sentRequest)));
+            telemetry.response(response);
+            if (!response.ok) {
+                throw await httpError(request, response, controller.signal);
+            }
+            if (response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase() !== 'text/event-stream') {
+                throw new streamErrors_1.StreamParseError('Expected text/event-stream response');
+            }
+            if (!response.body)
+                throw new streamErrors_1.StreamParseError('Missing event stream body');
+            telemetry.finishObserverOutcome('success');
+            telemetry.startStreamLifetime();
+            const bounded = boundedInput(sseMaxBufferSize);
+            const decoder = new TextDecoderStream('utf-8', { fatal: true });
+            const parser = eventParser(sseMaxBufferSize);
+            if (!eventProcessingChecked) {
+                eventProcessingChecked = true;
                 try {
-                    while (true) {
-                        const { done, value } = await reader.read();
-                        if (done)
-                            break;
-                        buffer += value;
-                        buffer = buffer.replace(/\r\n?/g, '\n'); // normalize line endings
-                        const chunks = buffer.split('\n\n');
-                        buffer = chunks.pop() ?? '';
-                        for (const chunk of chunks) {
-                            const lines = chunk.split('\n');
-                            const dataLines = [];
-                            let eventName;
-                            for (const line of lines) {
-                                if (line.startsWith('data:')) {
-                                    dataLines.push(line.replace(/^data:\s*/, ''));
-                                }
-                                else if (line.startsWith('event:')) {
-                                    eventName = line.replace(/^event:\s*/, '');
-                                }
-                                else if (line.startsWith('id:')) {
-                                    lastEventId = line.replace(/^id:\s*/, '');
-                                }
-                                else if (line.startsWith('retry:')) {
-                                    const parsed = Number.parseInt(line.replace(/^retry:\s*/, ''), 10);
-                                    if (!Number.isNaN(parsed)) {
-                                        retryDelay = parsed;
-                                    }
-                                }
-                            }
-                            let data;
-                            let parsedJson = false;
-                            if (dataLines.length) {
-                                const rawData = dataLines.join('\n');
-                                try {
-                                    data = JSON.parse(rawData);
-                                    parsedJson = true;
-                                }
-                                catch {
-                                    data = rawData;
-                                }
-                            }
-                            if (parsedJson) {
-                                if (responseValidator) {
-                                    await responseValidator(data);
-                                }
-                                if (responseTransformer) {
-                                    data = await responseTransformer(data);
-                                }
+                    eventProcessingRecording = telemetry.span.isRecording();
+                }
+                catch { /* Optional timing observation. */ }
+            }
+            if (eventProcessingRecording) {
+                firstEventReadyStarted = monotonicMilliseconds();
+                if (firstEventReadyStarted === undefined)
+                    firstEventReadyMeasured = false;
+            }
+            pipes = [
+                response.body.pipeTo(bounded.writable, { signal: controller.signal }),
+                bounded.readable.pipeTo(decoder.writable, { signal: controller.signal }),
+                decoder.readable.pipeTo(parser.writable, { signal: controller.signal }),
+            ].map(pipe => pipe.catch(() => { })); // Reader errors retain the original failure.
+            reader = parser.readable.getReader();
+            while (true) {
+                const { done, value } = await reader.read();
+                controller.signal.throwIfAborted();
+                if (done) {
+                    validateStreamEnd?.();
+                    completed = true;
+                    return;
+                }
+                const processingStarted = eventProcessingRecording ? monotonicMilliseconds() : undefined;
+                if (eventProcessingRecording && processingStarted === undefined)
+                    eventProcessingMeasured = false;
+                let skip = false;
+                let event;
+                try {
+                    event = {
+                        data: (0, json_1.parseJson)(value.data),
+                        ...(value.event === undefined ? {} : { event: value.event }),
+                        ...(value.id === undefined ? {} : { id: value.id }),
+                    };
+                    if (responseValidator) {
+                        try {
+                            await responseValidator(event);
+                        }
+                        catch (error) {
+                            if (error instanceof streamErrors_1.UnknownEventKind)
+                                skip = true;
+                            else
+                                throw error;
+                        }
+                    }
+                    if (!skip) {
+                        if (responseTransformer)
+                            event = await responseTransformer(event);
+                        if (firstEventReadyStarted !== undefined && firstEventReadyMeasured && firstEventReadyMilliseconds === undefined) {
+                            const ready = monotonicMilliseconds();
+                            if (ready === undefined || ready < firstEventReadyStarted ||
+                                (processingStarted !== undefined && ready < processingStarted)) {
+                                firstEventReadyMeasured = false;
                             }
-                            onSseEvent?.({
-                                data,
-                                event: eventName,
-                                id: lastEventId,
-                                retry: retryDelay,
-                            });
-                            if (dataLines.length) {
-                                yield data;
+                            else {
+                                const elapsed = ready - firstEventReadyStarted;
+                                if (Number.isFinite(elapsed))
+                                    firstEventReadyMilliseconds = elapsed;
+                                else
+                                    firstEventReadyMeasured = false;
                             }
                         }
+                        onSseEvent?.(event);
+                        events++;
                     }
                 }
                 finally {
-                    signal.removeEventListener('abort', abortHandler);
-                    reader.releaseLock();
+                    if (eventProcessingRecording) {
+                        const processingFinished = monotonicMilliseconds();
+                        if (processingStarted === undefined || processingFinished === undefined || processingFinished < processingStarted) {
+                            eventProcessingMeasured = false;
+                        }
+                        else {
+                            eventProcessingMilliseconds += processingFinished - processingStarted;
+                            if (!Number.isFinite(eventProcessingMilliseconds))
+                                eventProcessingMeasured = false;
+                        }
+                    }
                 }
-                break; // exit loop on normal completion
+                if (skip)
+                    continue;
+                yield event;
+            }
+        }
+        catch (error) {
+            failed = !controller.signal.aborted || (0, telemetry_1.isTimeoutError)(controller.signal.reason);
+            if (failed)
+                telemetry.error(error);
+            try {
+                const outcome = telemetry.responseOutcome(error);
+                telemetry.finishRequestPreparationOutcome(outcome);
+                telemetry.finishObserverOutcome(outcome);
             }
-            catch (error) {
-                // connection failed or aborted; retry after delay
-                onSseError?.(error);
-                if (sseMaxRetryAttempts !== undefined && attempt >= sseMaxRetryAttempts) {
-                    break; // stop after firing error
+            catch { /* Preserve the caller's original failure. */ }
+            // Observation hooks cannot turn a failed stream into successful iteration.
+            const failure = (0, api_error_1.requestFailure)(error, request, response);
+            try {
+                onSseError?.(failure);
+            }
+            finally {
+                throw failure;
+            }
+        }
+        finally {
+            signal?.removeEventListener('abort', abort);
+            if (reader) {
+                await reader.cancel().catch(() => { });
+                reader.releaseLock();
+                await Promise.all(pipes);
+            }
+            else if (response?.ok) {
+                await response.body?.cancel().catch(() => { });
+            }
+            // Failed HTTP bodies are closed; only a bounded diagnostic copy is retained.
+            telemetry.span.setAttribute('boxrouter.stream.events', events);
+            telemetry.span.setAttribute('boxrouter.stream.end', completed ? 'completed' : failed ? 'error' : 'cancelled');
+            // Sum only local decode/validation/transform/callback intervals. Reader and caller waits stay out.
+            if (eventProcessingRecording && eventProcessingMeasured) {
+                try {
+                    telemetry.span.setAttribute('boxrouter.stream.event_processing_ms', eventProcessingMilliseconds);
+                }
+                catch { /* Preserve the stream result. */ }
+            }
+            if (eventProcessingRecording && firstEventReadyMeasured && firstEventReadyMilliseconds !== undefined) {
+                try {
+                    telemetry.span.setAttribute('boxrouter.stream.first_event_ready_ms', firstEventReadyMilliseconds);
                 }
-                // exponential backoff: double retry each attempt, cap at 30s
-                const backoff = Math.min(retryDelay * 2 ** (attempt - 1), sseMaxRetryDelay ?? 30000);
-                await sleep(backoff);
+                catch { /* Preserve the stream result. */ }
             }
+            telemetry.finishStreamLifetime(completed ? 'success' : failed ? 'stream_error' : 'stream_cancelled');
+            telemetry.span.end();
         }
+    }
+    return {
+        stream: receive(),
+        close: () => controller.abort(new DOMException('Stream closed', 'AbortError')),
     };
-    const stream = createStream();
-    return { stream };
 }

package/dist/core/streamErrors.d.ts

@@ -0,0 +1,32 @@
+import { APIError } from '../api-error';
+export declare class StreamValidationError extends TypeError {
+    readonly schema: string;
+    readonly issues: ReadonlyArray<{
+        instancePath: string;
+        keyword: string;
+        message?: string;
+    }>;
+    constructor(schema: string, issues: ReadonlyArray<{
+        instancePath: string;
+        keyword: string;
+        message?: string;
+    }>);
+}
+/** An event of a kind this client does not know; the stream skips it. Never thrown to callers. */
+export declare class UnknownEventKind extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+export declare class IncompleteStream extends Error {
+    constructor();
+}
+/** A successful HTTP response that cannot be consumed as the requested stream. */
+export declare class StreamParseError extends TypeError {
+    readonly code = "parse_error";
+    constructor(message: string);
+}
+export declare class StreamHTTPError extends APIError {
+    readonly bodyTruncated: boolean;
+    readonly request: Request;
+    constructor(request: Request, response: Response, bodyTruncated?: boolean, payload?: unknown);
+}

package/dist/core/streamErrors.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamHTTPError = exports.StreamParseError = exports.IncompleteStream = exports.UnknownEventKind = exports.StreamValidationError = void 0;
+const api_error_1 = require("../api-error");
+// One definition for every generated surface, so callers catch the same classes.
+class StreamValidationError extends TypeError {
+    schema;
+    issues;
+    constructor(schema, issues) {
+        super(`Event does not match ${schema}`);
+        this.schema = schema;
+        this.issues = issues;
+        this.name = 'StreamValidationError';
+    }
+}
+exports.StreamValidationError = StreamValidationError;
+/** An event of a kind this client does not know; the stream skips it. Never thrown to callers. */
+class UnknownEventKind extends Error {
+    kind;
+    constructor(kind) {
+        super(`Skipped an event of unknown kind ${JSON.stringify(kind)}`);
+        this.kind = kind;
+        this.name = 'UnknownEventKind';
+    }
+}
+exports.UnknownEventKind = UnknownEventKind;
+class IncompleteStream extends Error {
+    constructor() {
+        super('Stream ended before a terminal event');
+        this.name = 'IncompleteStream';
+    }
+}
+exports.IncompleteStream = IncompleteStream;
+/** A successful HTTP response that cannot be consumed as the requested stream. */
+class StreamParseError extends TypeError {
+    code = 'parse_error';
+    constructor(message) {
+        super(message);
+        this.name = 'StreamParseError';
+    }
+}
+exports.StreamParseError = StreamParseError;
+class StreamHTTPError extends api_error_1.APIError {
+    bodyTruncated;
+    constructor(request, response, bodyTruncated = false, payload) {
+        super(payload, response, request, 'Stream request failed.');
+        this.bodyTruncated = bodyTruncated;
+        this.name = 'StreamHTTPError';
+    }
+}
+exports.StreamHTTPError = StreamHTTPError;