@0xinsider/sdk 0.14.0-bootstrap.0

package/dist/stream.d.ts

@@ -0,0 +1,509 @@
+/**
+ * SSE consumer for `GET /api/v1/stream`.
+ *
+ * The endpoint forwards the platform's live feed envelopes as Server-Sent
+ * Events. Source of truth: `web/public/api/v1/openapi.json` -> paths./api/v1/stream.
+ *
+ * Wire format (per the spec's response description):
+ *   - Each data frame is `id: <seq>\ndata: <json-envelope>\n\n`, where the JSON
+ *     envelope is `{ seq, published_at, type, ...event-specific }`. The SSE id
+ *     equals the envelope `seq`.
+ *   - A resync marker is `event: resync\nid: <seq>\ndata: <json>\n\n`, where the
+ *     JSON is `{ type: "resync", completeness, from_sequence, to_sequence }`.
+ *     It means the requested resume point is outside the retained window or a
+ *     live sequence gap was observed; treat it as "refetch current state".
+ *   - Idle connections emit `: keep-alive` comment lines (ignored).
+ *
+ * Resume is via the `Last-Event-ID` header set to the last `seq` you processed;
+ * the spec also accepts `last_event_id` / `seq` query fallbacks. This consumer
+ * sends the header and auto-tracks the last seen seq so a caller-driven
+ * reconnect resumes from the right place.
+ *
+ * Filters (per-connection, subscribe-time): `event` (comma-separated frame
+ * types), `condition_id`, and `min_grade` (S|A|B|C|D|F).
+ *
+ * Protocol validity (#16248). The decoder is bounded and fails visibly:
+ *   - A successful response whose media type is not `text/event-stream` is
+ *     `StreamProtocolError` (`unexpected_media_type`), not an empty stream.
+ *   - A data frame whose payload is not JSON, not an object, or has no usable
+ *     sequence (a finite `seq` in the envelope, or a finite SSE `id`) is a
+ *     `StreamProtocolError` (`invalid_json`, `invalid_envelope`,
+ *     `unusable_sequence`); a resync frame whose payload is not an object is
+ *     `invalid_resync`. Before #16248 such frames were skipped or yielded with
+ *     `NaN`, and the next valid frame moved the cursor past the gap.
+ *   - A frame larger than `maxFrameBytes` (default 1 MiB), whether or not its
+ *     blank-line delimiter has arrived, is `frame_too_large` before it is
+ *     parsed (#16644); the reader is released and the connection closed.
+ *   - The error carries `lastSeq`, the last sequence delivered before it, so a
+ *     malformed frame never moves the cursor and a caller can decide whether
+ *     to resume from there (which replays the frame while it is retained),
+ *     skip past `frameId`, or refetch state. No raw payload is on the error.
+ *   - A terminal `event: error` frame (the key was revoked, the account
+ *     lapsed, or the credential store could not confirm the key) throws the
+ *     typed `OxinsiderApiError` it carries and is never yielded (#16546);
+ *     `retry: false` is permanent to the resilient consumers.
+ *   Comment lines (`: keep-alive`), LF and CRLF framing, unknown SSE fields
+ *   and unknown-but-valid envelope `type`s are compatible as before.
+ */
+import { type Grade, type OxinsiderApiClient } from "./client.js";
+/** A live feed envelope frame: `{ seq, published_at, type, ...payload }`. */
+export interface FeedEnvelope {
+    /** Cluster-shared monotonic sequence id; also the SSE event id. */
+    seq: number;
+    /** ISO-8601 publish time, when present. */
+    published_at?: string;
+    /** Frame wire type, e.g. `"WhaleTradesInserted"`. */
+    type: string;
+    [key: string]: unknown;
+}
+/** A resync marker frame (SSE `event: resync`). */
+export interface ResyncMarker {
+    type: "resync";
+    completeness?: {
+        status?: string;
+        reason?: string;
+        [key: string]: unknown;
+    };
+    from_sequence?: number;
+    to_sequence?: number;
+    [key: string]: unknown;
+}
+export interface StreamFilters {
+    /**
+     * Subscribe only to these frame wire types. Sent as a comma-separated
+     * `event` query param. Empty/omitted = all frames.
+     */
+    event?: readonly string[];
+    /** Subscribe only to frames for this market (raw provider id or `mkt_*`). */
+    condition_id?: string;
+    /** Only deliver frames carrying a grade at or above this threshold. */
+    min_grade?: Grade;
+}
+export interface StreamOptions extends StreamFilters {
+    /**
+     * Resume after this cluster-shared sequence id (sets `Last-Event-ID`). It
+     * remains valid across replicas and process restarts while retained. When
+     * omitted the stream starts from the live head.
+     */
+    lastEventId?: number | string;
+    /** Cooperative cancellation; abort to close the stream. */
+    signal?: AbortSignal;
+    /** Invoked once for the resync marker frame, if one is emitted. */
+    onResync?: (marker: ResyncMarker) => void;
+    /**
+     * Optional cursor object whose `seq` is updated to the last DELIVERED
+     * envelope `seq` as frames arrive. Pass the same object back as
+     * `lastEventId: cursor.seq` on reconnect to resume from where you left off.
+     *
+     * Received, not processed (#16247). It is written before the frame reaches
+     * your code, so it says the frame arrived and nothing about whether your
+     * handling of it succeeded: resuming from it after a handler failure skips
+     * that event. When losing an event would lose work, drive the stream with
+     * `consumeStreamCheckpointed`, whose `StreamCheckpoint` advances only after
+     * the handler and your durable write resolve, and keep this cursor for
+     * transport progress.
+     */
+    cursor?: {
+        seq?: number;
+    };
+    /**
+     * Byte ceiling for one undelivered frame (#16248). Default
+     * `DEFAULT_MAX_STREAM_FRAME_BYTES` (1 MiB). A frame larger than this,
+     * delimited or not, ends the connection with `StreamProtocolError`
+     * (`frame_too_large`) before it is parsed or yielded, and the reader is
+     * released (#16644).
+     * A positive finite integer; the largest real frame is a few KB.
+     */
+    maxFrameBytes?: number;
+}
+/** Default for `StreamOptions.maxFrameBytes`: 1 MiB. */
+export declare const DEFAULT_MAX_STREAM_FRAME_BYTES = 1048576;
+/** What the stream did that the SSE contract does not allow. */
+export type StreamProtocolErrorReason = 
+/** A 2xx whose `Content-Type` is not `text/event-stream`. */
+"unexpected_media_type"
+/** A data frame whose payload is not JSON. */
+ | "invalid_json"
+/** A data frame whose payload is JSON but not an object (or is `null`, an array). */
+ | "invalid_envelope"
+/** A data frame with no finite `seq` in the envelope and no finite SSE `id`. */
+ | "unusable_sequence"
+/** A resync frame whose payload is not an object, or whose `type` is not `resync`. */
+ | "invalid_resync"
+/** A frame, delimited or not, is larger than `maxFrameBytes`. */
+ | "frame_too_large";
+/**
+ * The stream broke the SSE contract (#16248). The connection is closed and
+ * the reader released before this is thrown. `lastSeq` is the last sequence
+ * delivered on this connection, or `undefined` when none was: no malformed
+ * frame moves the cursor. `frameId` is the SSE `id` of the offending frame
+ * when it carried one, `event` its SSE event name, `bytes` its size, and
+ * `mediaType` the response's `Content-Type` for `unexpected_media_type`. The
+ * raw payload is deliberately not carried: it may hold data you would not
+ * want in a log, and `frameId` plus `lastSeq` name the frame exactly.
+ *
+ * `streamFeedResilient` treats this as permanent: reconnecting from
+ * `lastSeq` would replay the same frame while the server retains it. Decide:
+ * resume from `lastSeq` later, resume after `frameId` to skip it, or refetch
+ * state and attach live.
+ */
+export declare class StreamProtocolError extends Error {
+    readonly reason: StreamProtocolErrorReason;
+    readonly lastSeq: number | undefined;
+    readonly frameId: number | undefined;
+    readonly event: string | undefined;
+    readonly bytes: number | undefined;
+    readonly mediaType: string | undefined;
+    constructor(reason: StreamProtocolErrorReason, detail: {
+        lastSeq: number | undefined;
+        frameId?: number;
+        event?: string;
+        bytes?: number;
+        mediaType?: string | null;
+    });
+}
+/** `Content-Type` names an event stream: `text/event-stream`, with or without parameters. */
+export declare function isEventStreamMediaType(contentType: string | null): boolean;
+/** One yielded item from the stream iterator. */
+export type StreamEvent = {
+    kind: "event";
+    seq: number;
+    envelope: FeedEnvelope;
+} | {
+    kind: "resync";
+    seq: number | null;
+    marker: ResyncMarker;
+};
+/**
+ * Open the stream and async-iterate its frames. Yields a discriminated
+ * `StreamEvent`: `kind: "event"` carries the `FeedEnvelope`, `kind: "resync"`
+ * carries the `ResyncMarker`.
+ *
+ * Pass `options.cursor` (a `{ seq?: number }` object) to have the last
+ * delivered `seq` written back as frames arrive; reconnect with
+ * `lastEventId: cursor.seq` to resume after a transport drop.
+ *
+ * @example
+ * for await (const frame of streamFeed(client, { event: ["WhaleTradesInserted"], min_grade: "S" })) {
+ *   if (frame.kind === "event") console.log(frame.envelope.type, frame.seq);
+ * }
+ */
+export declare function streamFeed(client: OxinsiderApiClient, options?: StreamOptions): AsyncGenerator<StreamEvent, void, undefined>;
+export interface ResilientStreamOptions extends StreamOptions {
+    /**
+     * Consecutive failed connections tolerated before giving up with
+     * `StreamReconnectsExhaustedError`. A connection that delivers any frame
+     * resets the count. Default `DEFAULT_MAX_STREAM_RECONNECTS` (10).
+     */
+    maxReconnects?: number;
+    /**
+     * Called before each reconnect's backoff: the 1-based consecutive attempt,
+     * the seq the reconnect resumes after (`undefined` attaches live), and why
+     * the previous connection ended (`undefined` for a clean server close).
+     */
+    onReconnect?: (attempt: number, lastSeq: number | undefined, cause: unknown) => void;
+    /**
+     * The longest server-requested wait (`Retry-After` or `retry_at`) the loop holds
+     * in-process, in ms. Default `DEFAULT_MAX_STREAM_RETRY_AFTER_MS` (60 000,
+     * the REST client's ceiling). A refusal asking for longer ends the loop
+     * with `StreamRetryDeferredError`, which carries the not-before instant
+     * (`retryAt`) and the seq to resume after (`lastSeq`), so the wait is
+     * yours to schedule and no reconnect is spent on it. `Infinity` opts into
+     * waiting however long the server says, in timer-sized chunks; it can hold
+     * the process for days on a `monthly_quota_exceeded` refusal, which is why
+     * it is not the default (#16249).
+     */
+    maxRetryAfterMs?: number;
+}
+/** Default for `ResilientStreamOptions.maxReconnects`. */
+export declare const DEFAULT_MAX_STREAM_RECONNECTS = 10;
+/** Default for `ResilientStreamOptions.maxRetryAfterMs`. */
+export declare const DEFAULT_MAX_STREAM_RETRY_AFTER_MS = 60000;
+/**
+ * `streamFeedResilient` gave up after `maxReconnects` consecutive failed
+ * connections. `lastSeq` is the seq to resume after (pass it as `lastEventId`
+ * later); `cause` is the last connection's failure.
+ */
+export declare class StreamReconnectsExhaustedError extends Error {
+    readonly lastSeq: number | undefined;
+    readonly attempts: number;
+    constructor(attempts: number, lastSeq: number | undefined, cause: unknown);
+}
+/**
+ * `streamFeedResilient` received a server-requested wait longer than
+ * `maxRetryAfterMs`, so the wait is yours to schedule (#16249). `retryAt` is
+ * the server's not-before instant as this client read it (the header's
+ * seconds added to the local clock, the header's HTTP-date, or terminal
+ * `retry_at` when no usable header exists); `cause` is
+ * the refusal, whose `retryAt` (from the body's `retry_at`) is the server's
+ * own clock reading of the same instant. `lastSeq` is the seq to resume after:
+ * pass it as `lastEventId` when you reconnect at `retryAt`. `attempts` is how
+ * many consecutive failed connections preceded this one; the refusal itself
+ * spent none of `maxReconnects`.
+ *
+ * Nothing here was clamped: a wait the timer cannot hold is never shortened
+ * into an earlier reconnect.
+ */
+export declare class StreamRetryDeferredError extends Error {
+    readonly retryAt: Date;
+    readonly retryAfterMs: number;
+    readonly lastSeq: number | undefined;
+    readonly attempts: number;
+    constructor(retryAfterMs: number, lastSeq: number | undefined, attempts: number, cause: unknown);
+}
+/**
+ * `streamFeed` with the reconnect-and-resume loop built in (#14286).
+ *
+ * - A clean server close, a network error, a 429 or a 5xx reconnects,
+ *   resuming after the last delivered seq (`Last-Event-ID`). Before any frame
+ *   arrives it resumes from `lastEventId`, or attaches live when that is unset.
+ * - The wait is `Retry-After` (delta-seconds or an HTTP-date) plus jitter when
+ *   the refusal carries one, otherwise a jittered backoff from 1 s capped at
+ *   30 s. A `Retry-After` past `maxRetryAfterMs` (60 s by default) is not
+ *   waited out: the loop throws `StreamRetryDeferredError` with `retryAt` and
+ *   `lastSeq`, spending no reconnect, and never clamps the wait to an earlier
+ *   one (#16249).
+ * - Any other 4xx (400, 401, 402, 403, 423) is thrown at once: it cannot heal
+ *   on its own. So is `StreamProtocolError` (#16248): a resume from
+ *   `lastSeq` would replay the malformed frame, so the decision is yours.
+ * - After `maxReconnects` consecutive connections that delivered nothing, it
+ *   throws `StreamReconnectsExhaustedError` carrying `lastSeq`.
+ * - `resync` markers are yielded unchanged, and `onResync` still fires. The
+ *   marker's `id` becomes the resume cursor, as the server intends, so a
+ *   reconnect after one does not request the aged window again.
+ * - Aborting `signal` ends the iterator without throwing, during a connection
+ *   or a backoff. Each connection's body reader is cancelled when it ends, so
+ *   reconnects do not accumulate sockets.
+ * - No request deadline applies, as with `streamFeed`.
+ *
+ * `options.cursor`, when passed, tracks the last delivered seq across every
+ * connection -- delivered, not processed (#16247). This loop resumes from it,
+ * so a consumer whose handler can fail should drive the stream with
+ * `consumeStreamCheckpointed` instead, which resumes from an acknowledged
+ * checkpoint and replays the event it failed on.
+ *
+ * @example
+ * const controller = new AbortController();
+ * for await (const frame of streamFeedResilient(client, {
+ *   event: ["WhaleTradesInserted"],
+ *   signal: controller.signal,
+ *   onReconnect: (attempt, lastSeq, cause) => console.warn("reconnecting", attempt, lastSeq, cause),
+ * })) {
+ *   if (frame.kind === "resync") await refetchState();
+ *   else handle(frame.envelope);
+ * }
+ */
+export declare function streamFeedResilient(client: OxinsiderApiClient, options?: ResilientStreamOptions): AsyncGenerator<StreamEvent, void, undefined>;
+/**
+ * Callback-style stream consumer for environments where an async iterator is
+ * awkward. Returns a promise that resolves when the stream ends (or rejects on
+ * error / abort). Pass a `signal` to stop it.
+ *
+ * Delivery, not processing (#16247): `options.cursor` is written by
+ * `streamFeed` BEFORE the frame is yielded, so it has already moved past an
+ * event whose `onEvent` then throws. Reconnecting from it skips that event.
+ * For a consumer that must not lose work, use `consumeStreamCheckpointed`,
+ * which advances an acknowledged checkpoint only after the handler and your
+ * own durable write have both resolved.
+ */
+export declare function consumeStream(client: OxinsiderApiClient, handlers: {
+    onEvent?: (envelope: FeedEnvelope, seq: number) => void | Promise<void>;
+    onResync?: (marker: ResyncMarker, seq: number | null) => void | Promise<void>;
+}, options?: StreamOptions): Promise<void>;
+/**
+ * An acknowledged processing checkpoint (#16247): the last `seq` whose
+ * handling COMPLETED, which is not the same thing as the last `seq` that
+ * arrived. `StreamOptions.cursor` is the received cursor -- transport
+ * progress, written before the frame is handed to you. This is the processed
+ * one, written after your handler and your own durable write have resolved.
+ *
+ * Own the object if you persist the checkpoint yourself: pass it in, read
+ * `seq` after the consumer returns or throws, and pass the stored value back
+ * as `lastEventId` when you resume in a later process.
+ */
+export interface StreamCheckpoint {
+    /** The last acknowledged sequence, or `undefined` until one is acknowledged. */
+    seq?: number;
+}
+/** What the checkpoint advanced past: a feed envelope, or a resync refresh. */
+export type StreamCheckpointReason = "event" | "resync";
+/**
+ * Which awaited step rejected: your event handler, your resync refresh, or
+ * your `onCheckpoint` durable write.
+ */
+export type StreamHandlerStage = "event" | "resync" | "checkpoint";
+/** The recovery state around one handler failure, as it is decided. */
+export interface StreamHandlerFailure {
+    /**
+     * The sequence whose processing failed; `undefined` only for a resync
+     * marker that carried no SSE id.
+     */
+    seq: number | undefined;
+    /** Which awaited step rejected. */
+    stage: StreamHandlerStage;
+    /** 1-based consecutive failures at this sequence. Resets on any success. */
+    attempt: number;
+    /** Whether replay is planned; false means exhaustion or clean cancellation. */
+    willRetry: boolean;
+    /**
+     * Present and true when caller cancellation has stopped the consumer at
+     * this observation. It does not claim cancellation caused the rejection.
+     */
+    cancelled?: boolean;
+    /**
+     * The sequence the replay resumes AFTER, so the failed frame is delivered
+     * again while the server retains it. `undefined` means the replay attaches
+     * live and the failed frame is gone: that happens only when nothing has
+     * been acknowledged, no `lastEventId` was given, and the failing sequence
+     * is not a positive integer to step back from.
+     */
+    replayFrom: number | undefined;
+    /** The acknowledged checkpoint, which this failure did NOT advance. */
+    checkpoint: number | undefined;
+}
+/**
+ * `consumeStreamCheckpointed` gave up after `maxHandlerRetries` consecutive
+ * failures at the same sequence (#16247). `checkpoint` is the acknowledged
+ * sequence, still behind the failing one, and `replayFrom` is the point a
+ * later resume should pass as `lastEventId` to deliver the failed frame
+ * again while the server retains it. `cause` is the last rejection your
+ * handler produced.
+ */
+export declare class StreamHandlerFailedError extends Error {
+    readonly seq: number | undefined;
+    readonly stage: StreamHandlerStage;
+    readonly attempts: number;
+    readonly checkpoint: number | undefined;
+    readonly replayFrom: number | undefined;
+    constructor(detail: {
+        seq: number | undefined;
+        stage: StreamHandlerStage;
+        attempts: number;
+        checkpoint: number | undefined;
+        replayFrom: number | undefined;
+    }, cause: unknown);
+}
+/** Default for `CheckpointedStreamOptions.maxHandlerRetries`. */
+export declare const DEFAULT_MAX_HANDLER_RETRIES = 3;
+export interface CheckpointedStreamOptions extends ResilientStreamOptions {
+    /**
+     * Where the acknowledged checkpoint is written. Pass your own object to
+     * read it after the consumer returns; omit it and the consumer keeps one
+     * internally, which `onCheckpoint` still reports.
+     */
+    checkpoint?: StreamCheckpoint;
+    /**
+     * Consecutive failures at the SAME sequence tolerated before the consumer
+     * throws `StreamHandlerFailedError`. Each retry closes the connection and
+     * replays from the checkpoint after a jittered backoff (1 s to 30 s). `0`
+     * gives up on the first failure. Default `DEFAULT_MAX_HANDLER_RETRIES` (3).
+     */
+    maxHandlerRetries?: number;
+    /**
+     * Called on every handler failure with the recovery state, before backoff,
+     * exhaustion, or a clean cancellation return. Cancellation retains the
+     * original error with `willRetry: false` and `cancelled: true`, without
+     * spending a retry. It is not awaited and must not throw.
+     */
+    onHandlerError?: (error: unknown, failure: StreamHandlerFailure) => void;
+}
+export interface CheckpointedStreamHandlers {
+    /**
+     * Apply one feed envelope. Awaited: the connection is not read again until
+     * it settles. Reject to leave the checkpoint before this event.
+     */
+    onEvent: (envelope: FeedEnvelope, seq: number) => void | Promise<void>;
+    /**
+     * Refresh state after a resync marker. Awaited, so it is a real barrier:
+     * the checkpoint moves to the marker only once this resolves. Reject and
+     * the refresh is retried under the same bounded policy as an event.
+     */
+    onResync?: (marker: ResyncMarker, seq: number | null) => void | Promise<void>;
+    /**
+     * Persist the checkpoint. Awaited BEFORE the in-memory checkpoint advances,
+     * so a failed write leaves the checkpoint where it was and the event is
+     * replayed rather than lost.
+     */
+    onCheckpoint?: (seq: number, reason: StreamCheckpointReason) => void | Promise<void>;
+}
+/**
+ * The stream consumer for work that must not be silently dropped (#16247):
+ * it separates the received cursor from an acknowledged processing
+ * checkpoint, and only the checkpoint decides where a reconnect resumes.
+ *
+ * Ordering, per frame, for `kind: "event"`:
+ *   1. `onEvent` is awaited. Nothing is read from the connection while it
+ *      runs, so a slow handler is backpressure on the socket, never a queue:
+ *      at most one frame is ever in flight and nothing is buffered on your
+ *      behalf.
+ *   2. `onCheckpoint(seq, "event")` is awaited -- your durable write.
+ *   3. Only then does `checkpoint.seq` become `seq`, and only then does the
+ *      next reconnect resume after it.
+ * A rejection at step 1 or 2 leaves the checkpoint BEFORE the event: the
+ * connection is closed, a jittered backoff runs, and the consumer reconnects
+ * from the checkpoint, which replays the unacknowledged event while the
+ * server retains it. `onHandlerError` reports each failure with its attempt
+ * number, the replay point and whether another attempt follows. After
+ * `maxHandlerRetries` consecutive failures at the same sequence it throws
+ * `StreamHandlerFailedError`, carrying the unadvanced checkpoint.
+ *
+ * A `resync` marker is the same barrier: `onResync` is awaited, then
+ * `onCheckpoint(seq, "resync")`, and an interrupted refresh commits nothing,
+ * so the recovery is retried instead of being recorded as done. (The
+ * fire-and-forget `StreamOptions.onResync` notification is not awaited and is
+ * not a barrier -- do not use it as one.)
+ *
+ * Delivery is AT-LEAST-ONCE. A replay re-delivers every unacknowledged frame,
+ * and a handler that succeeded but whose `onCheckpoint` write failed sees its
+ * event again. Deduplicate on `seq` (it is monotonic per cluster) or make the
+ * side effect idempotent; nothing here can promise exactly-once side effects.
+ *
+ * `options.cursor` is untouched in meaning: it still tracks the last
+ * DELIVERED seq, including frames whose handler later failed, and it rewinds
+ * when a replay re-delivers them. Read it for transport progress; never as
+ * proof that the work was done.
+ *
+ * Transport recovery, `Retry-After` handling, permanent 4xx and
+ * `StreamProtocolError` behave exactly as in `streamFeedResilient`, which
+ * this drives. `StreamReconnectsExhaustedError` and
+ * `StreamRetryDeferredError` surface unchanged; their `lastSeq` is the
+ * acknowledged checkpoint, because a reconnect can only happen between
+ * handlers. Aborting `signal` ends the consumer without throwing: a handler
+ * already running is awaited (it is not cancelled for you -- pass the same
+ * signal into your own work if you want that), and if it succeeds its
+ * checkpoint is committed before the consumer returns. If an awaited event,
+ * resync, or checkpoint callback rejects during cancellation, the checkpoint
+ * stays unchanged and `onHandlerError` reports the original rejection with
+ * `willRetry: false` and `cancelled: true`; the consumer returns even when
+ * handler retries are disabled or exhausted. A coincident unrelated failure
+ * is still reported, without claiming cancellation caused it.
+ *
+ * @example
+ * const checkpoint = { seq: await loadCheckpoint() };
+ * await consumeStreamCheckpointed(client, {
+ *   onEvent: async (envelope, seq) => { await applyOnce(seq, envelope); },
+ *   onResync: async () => { await refetchCurrentState(); },
+ *   onCheckpoint: async (seq) => { await saveCheckpoint(seq); },
+ * }, {
+ *   event: ["WhaleTradesInserted"],
+ *   lastEventId: checkpoint.seq,
+ *   checkpoint,
+ *   signal: controller.signal,
+ *   onHandlerError: (error, failure) =>
+ *     console.warn("handler failed", failure.seq, failure.attempt, failure.willRetry, error),
+ * });
+ */
+export declare function consumeStreamCheckpointed(client: OxinsiderApiClient, handlers: CheckpointedStreamHandlers, options?: CheckpointedStreamOptions): Promise<void>;
+export interface ParsedSseFrame {
+    event?: string;
+    id?: number;
+    data: string;
+}
+/** Parse one SSE frame (without the trailing blank line). */
+export declare function parseSseFrame(raw: string): ParsedSseFrame | null;
+/**
+ * Turn one parsed SSE frame into a `StreamEvent`, or throw
+ * `StreamProtocolError` (#16248). `lastSeq` is only carried onto the error.
+ */
+export declare function decodeStreamFrame(parsed: ParsedSseFrame, lastSeq: number | undefined): StreamEvent;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

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