@durable-streams/client 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -1,627 +1,1072 @@
+//#region src/asyncIterableReadableStream.d.ts
 /**
- * Durable Streams TypeScript Client Types
- *
- * Following the Electric Durable Stream Protocol specification.
- */
+* Async iterable polyfill for ReadableStream.
+*
+* Safari/iOS may not implement ReadableStream.prototype[Symbol.asyncIterator],
+* preventing `for await...of` consumption. This module provides a soft polyfill
+* that defines [Symbol.asyncIterator] on individual stream instances when missing,
+* without patching the global prototype.
+*
+* The returned stream is still the original ReadableStream instance (not wrapped),
+* so `instanceof ReadableStream` continues to work correctly.
+*
+* **Note on derived streams**: Streams created via `.pipeThrough()` or similar
+* transformations will NOT be automatically patched. Use the exported
+* `asAsyncIterableReadableStream()` helper to patch derived streams:
+*
+* ```typescript
+* import { asAsyncIterableReadableStream } from "@durable-streams/client"
+*
+* const derived = res.bodyStream().pipeThrough(myTransform)
+* const iterable = asAsyncIterableReadableStream(derived)
+* for await (const chunk of iterable) { ... }
+* ```
+*/
 /**
- * Offset string - opaque to the client.
- * Format: "<read-seq>_<byte-offset>"
- *
- * Always use the returned `offset` field from reads/follows as the next `offset` you pass in.
- */
+* A ReadableStream that is guaranteed to be async-iterable.
+*
+* This intersection type ensures TypeScript knows the stream can be consumed
+* via `for await...of` syntax.
+*/
+type ReadableStreamAsyncIterable<T> = ReadableStream<T> & AsyncIterable<T>;
+/**
+* Ensure a ReadableStream is async-iterable.
+*
+* If the stream already has [Symbol.asyncIterator] defined (native or polyfilled),
+* it is returned as-is. Otherwise, [Symbol.asyncIterator] is defined on the
+* stream instance (not the prototype).
+*
+* The returned value is the same ReadableStream instance, so:
+* - `stream instanceof ReadableStream` remains true
+* - Any code relying on native branding/internal slots continues to work
+*
+* @example
+* ```typescript
+* const stream = someApiReturningReadableStream();
+* const iterableStream = asAsyncIterableReadableStream(stream);
+*
+* // Now works on Safari/iOS:
+* for await (const chunk of iterableStream) {
+*   console.log(chunk);
+* }
+* ```
+*/
+declare function asAsyncIterableReadableStream<T>(stream: ReadableStream<T>): ReadableStreamAsyncIterable<T>;
+
+//#endregion
+//#region src/fetch.d.ts
+/**
+* Options for configuring exponential backoff retry behavior.
+*/
+interface BackoffOptions {
+  /**
+  * Initial delay before retrying in milliseconds.
+  */
+  initialDelay: number;
+  /**
+  * Maximum retry delay in milliseconds.
+  * After reaching this, delay stays constant.
+  */
+  maxDelay: number;
+  /**
+  * Multiplier for exponential backoff.
+  */
+  multiplier: number;
+  /**
+  * Callback invoked on each failed attempt.
+  */
+  onFailedAttempt?: () => void;
+  /**
+  * Enable debug logging.
+  */
+  debug?: boolean;
+  /**
+  * Maximum number of retry attempts before giving up.
+  * Set to Infinity for indefinite retries (useful for offline scenarios).
+  */
+  maxRetries?: number;
+}
+/**
+* Default backoff options.
+*/
+declare const BackoffDefaults: BackoffOptions;
+/**
+* Parse Retry-After header value and return delay in milliseconds.
+* Supports both delta-seconds format and HTTP-date format.
+* Returns 0 if header is not present or invalid.
+*/
+
+/**
+* Creates a fetch client that retries failed requests with exponential backoff.
+*
+* @param fetchClient - The base fetch client to wrap
+* @param backoffOptions - Options for retry behavior
+* @returns A fetch function with automatic retry
+*/
+declare function createFetchWithBackoff(fetchClient: typeof fetch, backoffOptions?: BackoffOptions): typeof fetch;
+/**
+* Creates a fetch client that ensures the response body is fully consumed.
+* This prevents issues with connection pooling when bodies aren't read.
+*
+* Uses arrayBuffer() instead of text() to preserve binary data integrity.
+*
+* @param fetchClient - The base fetch client to wrap
+* @returns A fetch function that consumes response bodies
+*/
+declare function createFetchWithConsumedBody(fetchClient: typeof fetch): typeof fetch;
+
+//#endregion
+//#region src/types.d.ts
+/**
+* Chains an AbortController to an optional source signal.
+* If the source signal is aborted, the provided controller will also abort.
+*/
+/**
+* Offset string - opaque to the client.
+* Format: "<read-seq>_<byte-offset>"
+*
+* **Special value**: `-1` means "start of stream" - use this to read from the beginning.
+*
+* Always use the returned `offset` field from reads/follows as the next `offset` you pass in.
+*/
 type Offset = string;
 /**
- * Type for values that can be provided immediately or resolved asynchronously.
- */
+* Type for values that can be provided immediately or resolved asynchronously.
+*/
 type MaybePromise<T> = T | Promise<T>;
 /**
- * Auth configuration for requests.
- *
- * Supports:
- * - Fixed tokens with optional custom header name
- * - Arbitrary static headers
- * - Async header resolution (e.g., for short-lived tokens)
- */
-type Auth = {
-    token: string;
-    headerName?: string;
-} | {
-    headers: Record<string, string>;
-} | {
-    getHeaders: () => Promise<Record<string, string>>;
-};
-/**
- * Headers record where values can be static strings or async functions.
- * Following the @electric-sql/client pattern for dynamic headers.
- */
+* Headers record where values can be static strings or async functions.
+* Following the @electric-sql/client pattern for dynamic headers.
+*
+* **Important**: Functions are called **for each request**, not once per session.
+* In live mode with long-polling, the same function may be called many times
+* to fetch fresh values (e.g., refreshed auth tokens) for each poll.
+*
+* @example
+* ```typescript
+* headers: {
+*   Authorization: `Bearer ${token}`,           // Static - same for all requests
+*   'X-Tenant-Id': () => getCurrentTenant(),    // Called per-request
+*   'X-Auth': async () => await refreshToken()  // Called per-request (can refresh)
+* }
+* ```
+*/
 type HeadersRecord = {
-    [key: string]: string | (() => MaybePromise<string>);
+  [key: string]: string | (() => MaybePromise<string>);
 };
 /**
- * Params record where values can be static or async functions.
- * Following the @electric-sql/client pattern for dynamic params.
- */
+* Params record where values can be static or async functions.
+* Following the @electric-sql/client pattern for dynamic params.
+*
+* **Important**: Functions are called **for each request**, not once per session.
+* In live mode, the same function may be called multiple times to fetch
+* fresh parameter values for each poll.
+*/
 type ParamsRecord = {
-    [key: string]: string | (() => MaybePromise<string>) | undefined;
+  [key: string]: string | (() => MaybePromise<string>) | undefined;
 };
 /**
- * Base options for all stream operations.
- */
+* Live mode for reading from a stream.
+* - false: Catch-up only, stop at first `upToDate`
+* - "auto": Behavior driven by consumption method (default)
+* - "long-poll": Explicit long-poll mode for live updates
+* - "sse": Explicit server-sent events for live updates
+*/
+type LiveMode = false | `auto` | `long-poll` | `sse`;
+/**
+* Options for the stream() function (read-only API).
+*/
 interface StreamOptions {
-    /**
-     * The full URL to the durable stream.
-     * E.g., "https://streams.example.com/my-account/chat/room-1"
-     */
-    url: string;
-    /**
-     * Authentication configuration.
-     * If using auth, you can provide:
-     * - A token (sent as Bearer token in Authorization header by default)
-     * - Custom headers
-     * - An async function to get headers (for refreshing tokens)
-     */
-    auth?: Auth;
-    /**
-     * Additional headers to include in requests.
-     * Values can be strings or functions (sync or async) that return strings.
-     * Function values are resolved when needed, making this useful
-     * for dynamic headers like authentication tokens.
-     */
-    headers?: HeadersRecord;
-    /**
-     * Additional query parameters to include in requests.
-     * Values can be strings or functions (sync or async) that return strings.
-     */
-    params?: ParamsRecord;
-    /**
-     * Custom fetch implementation.
-     * Defaults to globalThis.fetch.
-     */
-    fetch?: typeof globalThis.fetch;
-    /**
-     * Default AbortSignal for operations.
-     * Individual operations can override this.
-     */
-    signal?: AbortSignal;
+  /**
+  * The full URL to the durable stream.
+  * E.g., "https://streams.example.com/my-account/chat/room-1"
+  */
+  url: string | URL;
+  /**
+  * HTTP headers to include in requests.
+  * Values can be strings or functions (sync or async) that return strings.
+  *
+  * **Important**: Functions are evaluated **per-request** (not per-session).
+  * In live mode, functions are called for each poll, allowing fresh values
+  * like refreshed auth tokens.
+  *
+  * @example
+  * ```typescript
+  * headers: {
+  *   Authorization: `Bearer ${token}`,           // Static
+  *   'X-Tenant-Id': () => getCurrentTenant(),    // Evaluated per-request
+  *   'X-Auth': async () => await refreshToken()  // Evaluated per-request
+  * }
+  * ```
+  */
+  headers?: HeadersRecord;
+  /**
+  * Query parameters to include in requests.
+  * Values can be strings or functions (sync or async) that return strings.
+  *
+  * **Important**: Functions are evaluated **per-request** (not per-session).
+  */
+  params?: ParamsRecord;
+  /**
+  * AbortSignal for cancellation.
+  */
+  signal?: AbortSignal;
+  /**
+  * Custom fetch implementation (for auth layers, proxies, etc.).
+  * Defaults to globalThis.fetch.
+  */
+  fetch?: typeof globalThis.fetch;
+  /**
+  * Backoff options for retry behavior.
+  * Defaults to exponential backoff with jitter.
+  */
+  backoffOptions?: BackoffOptions;
+  /**
+  * Starting offset (query param ?offset=...).
+  * If omitted, defaults to "-1" (start of stream).
+  * You can also explicitly pass "-1" to read from the beginning.
+  */
+  offset?: Offset;
+  /**
+  * Live mode behavior:
+  * - false: Catch-up only, stop at first `upToDate`
+  * - "auto" (default): Behavior driven by consumption method
+  * - "long-poll": Explicit long-poll mode for live updates
+  * - "sse": Explicit server-sent events for live updates
+  */
+  live?: LiveMode;
+  /**
+  * Hint: treat content as JSON even if Content-Type doesn't say so.
+  */
+  json?: boolean;
+  /**
+  * Error handler for recoverable errors (following Electric client pattern).
+  */
+  onError?: StreamErrorHandler;
+  /**
+  * SSE resilience options.
+  * When SSE connections fail repeatedly, the client can automatically
+  * fall back to long-polling mode.
+  */
+  sseResilience?: SSEResilienceOptions;
 }
 /**
- * Options for creating a new stream.
- */
-interface CreateOptions extends StreamOptions {
-    /**
-     * The content type for the stream.
-     * This is set once on creation and cannot be changed.
-     */
-    contentType?: string;
-    /**
-     * Time-to-live in seconds (relative TTL).
-     */
-    ttlSeconds?: number;
-    /**
-     * Absolute expiry time (RFC3339 format).
-     */
-    expiresAt?: string;
-    /**
-     * Initial body to append on creation.
-     */
-    body?: BodyInit | Uint8Array | string;
+* Options for SSE connection resilience.
+*/
+interface SSEResilienceOptions {
+  /**
+  * Minimum expected SSE connection duration in milliseconds.
+  * Connections shorter than this are considered "short" and may indicate
+  * proxy buffering or server misconfiguration.
+  * @default 1000
+  */
+  minConnectionDuration?: number;
+  /**
+  * Maximum number of consecutive short connections before falling back to long-poll.
+  * @default 3
+  */
+  maxShortConnections?: number;
+  /**
+  * Base delay for exponential backoff between short connection retries (ms).
+  * @default 100
+  */
+  backoffBaseDelay?: number;
+  /**
+  * Maximum delay cap for exponential backoff (ms).
+  * @default 5000
+  */
+  backoffMaxDelay?: number;
+  /**
+  * Whether to log warnings when falling back to long-poll.
+  * @default true
+  */
+  logWarnings?: boolean;
 }
 /**
- * Options for appending data to a stream.
- */
-interface AppendOptions {
-    /**
-     * Writer coordination sequence (stream-seq header).
-     * Monotonic, lexicographic sequence for coordinating multiple writers.
-     * If lower than last appended seq, server returns 409 Conflict.
-     * Not related to read offsets.
-     */
-    seq?: string;
-    /**
-     * Content type for this append.
-     * Must match the stream's content type.
-     */
-    contentType?: string;
-    /**
-     * AbortSignal for this operation.
-     */
-    signal?: AbortSignal;
+* Metadata for a JSON batch or chunk.
+*/
+interface JsonBatchMeta {
+  /**
+  * Last Stream-Next-Offset for this batch.
+  */
+  offset: Offset;
+  /**
+  * True if this batch ends at the current end of the stream.
+  */
+  upToDate: boolean;
+  /**
+  * Last Stream-Cursor / streamCursor, if present.
+  */
+  cursor?: string;
 }
 /**
- * Live mode for reading from a stream.
- */
-type LiveMode = `catchup` | `long-poll` | `sse`;
-/**
- * Options for reading from a stream.
- */
-interface ReadOptions {
-    /**
-     * Starting offset, passed as ?offset=...
-     * If omitted, reads from the start of the stream.
-     */
-    offset?: Offset;
-    /**
-     * Live mode behavior:
-     * - undefined (default for follow()): Start catch-up, then auto-select SSE or long-poll
-     * - "catchup": Only catch-up, stop after up-to-date
-     * - "long-poll": Skip catch-up, start long-polling immediately
-     * - "sse": Skip catch-up, start SSE immediately (throws if unsupported)
-     */
-    live?: LiveMode;
-    /**
-     * Override cursor for the request.
-     * By default, the client echoes the last stream-cursor value.
-     */
-    cursor?: string;
-    /**
-     * AbortSignal for this operation.
-     */
-    signal?: AbortSignal;
+* A batch of parsed JSON items with metadata.
+*/
+interface JsonBatch<T = unknown> extends JsonBatchMeta {
+  /**
+  * The parsed JSON items in this batch.
+  */
+  items: ReadonlyArray<T>;
 }
 /**
- * Result from a HEAD request on a stream.
- */
-interface HeadResult {
-    /**
-     * Whether the stream exists.
-     */
-    exists: true;
-    /**
-     * The stream's content type.
-     */
-    contentType?: string;
-    /**
-     * The tail offset (next offset after current end of stream).
-     * Provided by server as stream-offset header on HEAD.
-     */
-    offset?: Offset;
-    /**
-     * ETag for the stream (format: {internal_stream_id}:{end_offset}).
-     */
-    etag?: string;
-    /**
-     * Cache-Control header value.
-     */
-    cacheControl?: string;
+* A chunk of raw bytes with metadata.
+*/
+interface ByteChunk extends JsonBatchMeta {
+  /**
+  * The raw byte data.
+  */
+  data: Uint8Array;
 }
 /**
- * Result from a read operation.
- */
-interface ReadResult {
-    /**
-     * The data read from the stream.
-     */
-    data: Uint8Array;
-    /**
-     * Next offset to read from.
-     * This is the HTTP stream-offset header value.
-     */
-    offset: Offset;
-    /**
-     * Cursor for CDN collapsing (stream-cursor header).
-     */
-    cursor?: string;
-    /**
-     * True if stream-up-to-date header was present.
-     * Indicates the response ends at the current end of the stream.
-     */
-    upToDate: boolean;
-    /**
-     * ETag for caching.
-     */
-    etag?: string;
-    /**
-     * Content type of the data.
-     */
-    contentType?: string;
+* A chunk of text with metadata.
+*/
+interface TextChunk extends JsonBatchMeta {
+  /**
+  * The text content.
+  */
+  text: string;
 }
 /**
- * A chunk returned from follow() or toReadableStream().
- * Same structure as ReadResult.
- */
-interface StreamChunk extends ReadResult {
+* Base options for StreamHandle operations.
+*/
+interface StreamHandleOptions {
+  /**
+  * The full URL to the durable stream.
+  * E.g., "https://streams.example.com/my-account/chat/room-1"
+  */
+  url: string | URL;
+  /**
+  * HTTP headers to include in requests.
+  * Values can be strings or functions (sync or async) that return strings.
+  *
+  * Functions are evaluated **per-request** (not per-session).
+  */
+  headers?: HeadersRecord;
+  /**
+  * Query parameters to include in requests.
+  * Values can be strings or functions (sync or async) that return strings.
+  *
+  * Functions are evaluated **per-request** (not per-session).
+  */
+  params?: ParamsRecord;
+  /**
+  * Custom fetch implementation.
+  * Defaults to globalThis.fetch.
+  */
+  fetch?: typeof globalThis.fetch;
+  /**
+  * Default AbortSignal for operations.
+  */
+  signal?: AbortSignal;
+  /**
+  * The content type for the stream.
+  */
+  contentType?: string;
+  /**
+  * Error handler for recoverable errors.
+  */
+  onError?: StreamErrorHandler;
+  /**
+  * Enable automatic batching for append() calls.
+  * When true, multiple append() calls made while a POST is in-flight
+  * will be batched together into a single request.
+  *
+  * @default true
+  */
+  batching?: boolean;
 }
 /**
- * Error codes for DurableStreamError.
- */
-type DurableStreamErrorCode = `NOT_FOUND` | `CONFLICT_SEQ` | `CONFLICT_EXISTS` | `BAD_REQUEST` | `BUSY` | `SSE_NOT_SUPPORTED` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `UNKNOWN`;
+* Options for creating a new stream.
+*/
+interface CreateOptions extends StreamHandleOptions {
+  /**
+  * Time-to-live in seconds (relative TTL).
+  */
+  ttlSeconds?: number;
+  /**
+  * Absolute expiry time (RFC3339 format).
+  */
+  expiresAt?: string;
+  /**
+  * Initial body to append on creation.
+  */
+  body?: BodyInit | Uint8Array | string;
+  /**
+  * Enable automatic batching for append() calls.
+  * When true, multiple append() calls made while a POST is in-flight
+  * will be batched together into a single request.
+  *
+  * @default true
+  */
+  batching?: boolean;
+}
 /**
- * Options returned from onError handler to retry with modified params/headers.
- * Following the Electric client pattern.
- */
-type RetryOpts = {
-    params?: ParamsRecord;
-    headers?: HeadersRecord;
-};
+* Options for appending data to a stream.
+*/
+interface AppendOptions {
+  /**
+  * Writer coordination sequence (stream-seq header).
+  * Monotonic, lexicographic sequence for coordinating multiple writers.
+  * If lower than last appended seq, server returns 409 Conflict.
+  * Not related to read offsets.
+  */
+  seq?: string;
+  /**
+  * Content type for this append.
+  * Must match the stream's content type.
+  */
+  contentType?: string;
+  /**
+  * AbortSignal for this operation.
+  */
+  signal?: AbortSignal;
+}
 /**
- * Error handler callback type.
- *
- * Called when a recoverable error occurs during streaming.
- *
- * **Return value behavior** (following Electric client pattern):
- * - Return `{}` to retry with the same params/headers
- * - Return `{ params }` to retry with merged params (existing params are preserved)
- * - Return `{ headers }` to retry with merged headers (existing headers are preserved)
- * - Return `void`/`undefined` to stop the stream and propagate the error
- *
- * Note: Automatic retries with exponential backoff are already applied
- * for 5xx server errors, network errors, and 429 rate limits before
- * this handler is called.
- *
- * @example
- * ```typescript
- * // Retry on any error
- * onError: (error) => ({})
- *
- * // Refresh auth token on 401
- * onError: async (error) => {
- *   if (error instanceof FetchError && error.status === 401) {
- *     const newToken = await refreshAuthToken()
- *     return { headers: { Authorization: `Bearer ${newToken}` } }
- *   }
- *   // Don't retry other errors
- * }
- * ```
- */
-type StreamErrorHandler = (error: Error) => void | RetryOpts | Promise<void | RetryOpts>;
-
+* Legacy live mode type (internal use only).
+* @internal
+*/
+type LegacyLiveMode = `long-poll` | `sse`;
 /**
- * Fetch utilities with retry and backoff support.
- * Based on @electric-sql/client patterns.
- */
+* Options for reading from a stream (internal iterator options).
+* @internal
+*/
+interface ReadOptions {
+  /**
+  * Starting offset, passed as ?offset=...
+  * If omitted, defaults to "-1" (start of stream).
+  */
+  offset?: Offset;
+  /**
+  * Live mode behavior:
+  * - undefined/true (default): Catch-up then auto-select SSE or long-poll for live updates
+  * - false: Only catch-up, stop after up-to-date (no live updates)
+  * - "long-poll": Use long-polling for live updates
+  * - "sse": Use SSE for live updates (throws if unsupported)
+  */
+  live?: boolean | LegacyLiveMode;
+  /**
+  * Override cursor for the request.
+  * By default, the client echoes the last stream-cursor value.
+  */
+  cursor?: string;
+  /**
+  * AbortSignal for this operation.
+  */
+  signal?: AbortSignal;
+}
 /**
- * Options for configuring exponential backoff retry behavior.
- */
-interface BackoffOptions {
-    /**
-     * Initial delay before retrying in milliseconds.
-     */
-    initialDelay: number;
-    /**
-     * Maximum retry delay in milliseconds.
-     * After reaching this, delay stays constant.
-     */
-    maxDelay: number;
-    /**
-     * Multiplier for exponential backoff.
-     */
-    multiplier: number;
-    /**
-     * Callback invoked on each failed attempt.
-     */
-    onFailedAttempt?: () => void;
-    /**
-     * Enable debug logging.
-     */
-    debug?: boolean;
-    /**
-     * Maximum number of retry attempts before giving up.
-     * Set to Infinity for indefinite retries (useful for offline scenarios).
-     */
-    maxRetries?: number;
+* Result from a HEAD request on a stream.
+*/
+interface HeadResult {
+  /**
+  * Whether the stream exists.
+  */
+  exists: true;
+  /**
+  * The stream's content type.
+  */
+  contentType?: string;
+  /**
+  * The tail offset (next offset after current end of stream).
+  * Provided by server as stream-offset header on HEAD.
+  */
+  offset?: Offset;
+  /**
+  * ETag for the stream (format: {internal_stream_id}:{end_offset}).
+  */
+  etag?: string;
+  /**
+  * Cache-Control header value.
+  */
+  cacheControl?: string;
 }
 /**
- * Default backoff options.
- */
-declare const BackoffDefaults: BackoffOptions;
+* Metadata extracted from a stream response.
+* Contains headers and control information from the stream server.
+*/
+
 /**
- * Creates a fetch client that retries failed requests with exponential backoff.
- *
- * @param fetchClient - The base fetch client to wrap
- * @param backoffOptions - Options for retry behavior
- * @returns A fetch function with automatic retry
- */
-declare function createFetchWithBackoff(fetchClient: typeof fetch, backoffOptions?: BackoffOptions): typeof fetch;
+* Error codes for DurableStreamError.
+*/
+type DurableStreamErrorCode = `NOT_FOUND` | `CONFLICT_SEQ` | `CONFLICT_EXISTS` | `BAD_REQUEST` | `BUSY` | `SSE_NOT_SUPPORTED` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `ALREADY_CONSUMED` | `ALREADY_CLOSED` | `UNKNOWN`;
 /**
- * Creates a fetch client that ensures the response body is fully consumed.
- * This prevents issues with connection pooling when bodies aren't read.
- *
- * Uses arrayBuffer() instead of text() to preserve binary data integrity.
- *
- * @param fetchClient - The base fetch client to wrap
- * @returns A fetch function that consumes response bodies
- */
-declare function createFetchWithConsumedBody(fetchClient: typeof fetch): typeof fetch;
-
+* Options returned from onError handler to retry with modified params/headers.
+* Following the Electric client pattern.
+*/
+type RetryOpts = {
+  params?: ParamsRecord;
+  headers?: HeadersRecord;
+};
 /**
- * DurableStream - A handle to a remote durable stream.
- *
- * Following the Electric Durable Stream Protocol specification.
- */
+* Error handler callback type.
+*
+* Called when a recoverable error occurs during streaming.
+*
+* **Return value behavior** (following Electric client pattern):
+* - Return `{}` (empty object) → Retry immediately with same params/headers
+* - Return `{ params }` → Retry with merged params (existing params preserved)
+* - Return `{ headers }` → Retry with merged headers (existing headers preserved)
+* - Return `void` or `undefined` → Stop stream and propagate the error
+* - Return `null` → INVALID (will cause error - use `{}` instead)
+*
+* **Important**: To retry, you MUST return an object (can be empty `{}`).
+* Returning nothing (`void`), explicitly returning `undefined`, or omitting
+* a return statement all stop the stream. Do NOT return `null`.
+*
+* Note: Automatic retries with exponential backoff are already applied
+* for 5xx server errors, network errors, and 429 rate limits before
+* this handler is called.
+*
+* @example
+* ```typescript
+* // Retry on any error (returns empty object)
+* onError: (error) => ({})
+*
+* // Refresh auth token on 401, propagate other errors
+* onError: async (error) => {
+*   if (error instanceof FetchError && error.status === 401) {
+*     const newToken = await refreshAuthToken()
+*     return { headers: { Authorization: `Bearer ${newToken}` } }
+*   }
+*   // Implicitly returns undefined - error will propagate
+* }
+*
+* // Conditionally retry with explicit propagation
+* onError: (error) => {
+*   if (shouldRetry(error)) {
+*     return {} // Retry
+*   }
+*   return undefined // Explicitly propagate error
+* }
+* ```
+*/
+type StreamErrorHandler = (error: Error) => void | RetryOpts | Promise<void | RetryOpts>;
+/**
+* A streaming session returned by stream() or DurableStream.stream().
+*
+* Represents a live session with fixed `url`, `offset`, and `live` parameters.
+* Supports multiple consumption styles: Promise helpers, ReadableStreams,
+* and Subscribers.
+*
+* @typeParam TJson - The type of JSON items in the stream.
+*/
+interface StreamResponse<TJson = unknown> {
+  /**
+  * The stream URL.
+  */
+  readonly url: string;
+  /**
+  * The stream's content type (from first response).
+  */
+  readonly contentType?: string;
+  /**
+  * The live mode for this session.
+  */
+  readonly live: LiveMode;
+  /**
+  * The starting offset for this session.
+  */
+  readonly startOffset: Offset;
+  /**
+  * HTTP response headers from the most recent server response.
+  * Updated on each long-poll/SSE response.
+  */
+  readonly headers: Headers;
+  /**
+  * HTTP status code from the most recent server response.
+  * Updated on each long-poll/SSE response.
+  */
+  readonly status: number;
+  /**
+  * HTTP status text from the most recent server response.
+  * Updated on each long-poll/SSE response.
+  */
+  readonly statusText: string;
+  /**
+  * Whether the most recent response was successful (status 200-299).
+  * Always true for active streams (errors are thrown).
+  */
+  readonly ok: boolean;
+  /**
+  * Whether the stream is waiting for initial data.
+  *
+  * Note: Always false in current implementation because stream() awaits
+  * the first response before returning. A future async iterator API
+  * could expose this as true during initial connection.
+  */
+  readonly isLoading: boolean;
+  /**
+  * The next offset to read from (Stream-Next-Offset header).
+  *
+  * **Important**: This value advances **after data is delivered to the consumer**,
+  * not just after fetching from the server. The offset represents the position
+  * in the stream that follows the data most recently provided to your consumption
+  * method (body(), json(), bodyStream(), subscriber callback, etc.).
+  *
+  * Use this for resuming reads after a disconnect or saving checkpoints.
+  */
+  offset: Offset;
+  /**
+  * Stream cursor for CDN collapsing (stream-cursor header).
+  *
+  * Updated after each chunk is delivered to the consumer.
+  */
+  cursor?: string;
+  /**
+  * Whether we've reached the current end of the stream (stream-up-to-date header).
+  *
+  * Updated after each chunk is delivered to the consumer.
+  */
+  upToDate: boolean;
+  /**
+  * Accumulate raw bytes until first `upToDate` batch, then resolve.
+  * When used with `live: "auto"`, signals the session to stop after upToDate.
+  */
+  body: () => Promise<Uint8Array>;
+  /**
+  * Accumulate JSON *items* across batches into a single array, resolve at `upToDate`.
+  * Only valid in JSON-mode; throws otherwise.
+  * When used with `live: "auto"`, signals the session to stop after upToDate.
+  */
+  json: <T = TJson>() => Promise<Array<T>>;
+  /**
+  * Accumulate text chunks into a single string, resolve at `upToDate`.
+  * When used with `live: "auto"`, signals the session to stop after upToDate.
+  */
+  text: () => Promise<string>;
+  /**
+  * Raw bytes as a ReadableStream<Uint8Array>.
+  *
+  * The returned stream is guaranteed to be async-iterable, so you can use
+  * `for await...of` syntax even on Safari/iOS which may lack native support.
+  */
+  bodyStream: () => ReadableStreamAsyncIterable<Uint8Array>;
+  /**
+  * Individual JSON items (flattened) as a ReadableStream<TJson>.
+  * Built on jsonBatches().
+  *
+  * The returned stream is guaranteed to be async-iterable, so you can use
+  * `for await...of` syntax even on Safari/iOS which may lack native support.
+  */
+  jsonStream: () => ReadableStreamAsyncIterable<TJson>;
+  /**
+  * Text chunks as ReadableStream<string>.
+  *
+  * The returned stream is guaranteed to be async-iterable, so you can use
+  * `for await...of` syntax even on Safari/iOS which may lack native support.
+  */
+  textStream: () => ReadableStreamAsyncIterable<string>;
+  /**
+  * Subscribe to JSON batches as they arrive.
+  * Returns unsubscribe function.
+  */
+  subscribeJson: <T = TJson>(subscriber: (batch: JsonBatch<T>) => Promise<void>) => () => void;
+  /**
+  * Subscribe to raw byte chunks as they arrive.
+  * Returns unsubscribe function.
+  */
+  subscribeBytes: (subscriber: (chunk: ByteChunk) => Promise<void>) => () => void;
+  /**
+  * Subscribe to text chunks as they arrive.
+  * Returns unsubscribe function.
+  */
+  subscribeText: (subscriber: (chunk: TextChunk) => Promise<void>) => () => void;
+  /**
+  * Cancel the underlying session (abort HTTP, close SSE, stop long-polls).
+  */
+  cancel: (reason?: unknown) => void;
+  /**
+  * Resolves when the session has fully closed:
+  * - `live:false` and up-to-date reached,
+  * - manual cancellation,
+  * - terminal error.
+  */
+  readonly closed: Promise<void>;
+} //#endregion
+//#region src/stream-api.d.ts
+/**
+* Create a streaming session to read from a durable stream.
+*
+* This is a fetch-like API:
+* - The promise resolves after the first network request succeeds
+* - It rejects for auth/404/other protocol errors
+* - Returns a StreamResponse for consuming the data
+*
+* @example
+* ```typescript
+* // Catch-up JSON:
+* const res = await stream<{ message: string }>({
+*   url,
+*   auth,
+*   offset: "0",
+*   live: false,
+* })
+* const items = await res.json()
+*
+* // Live JSON:
+* const live = await stream<{ message: string }>({
+*   url,
+*   auth,
+*   offset: savedOffset,
+*   live: "auto",
+* })
+* live.subscribeJson(async (batch) => {
+*   for (const item of batch.items) {
+*     handle(item)
+*   }
+* })
+* ```
+*/
+declare function stream<TJson = unknown>(options: StreamOptions): Promise<StreamResponse<TJson>>;
 
+//#endregion
+//#region src/stream.d.ts
 /**
- * Options for DurableStream constructor.
- */
-interface DurableStreamOptions extends StreamOptions {
-    /**
-     * Backoff options for retry behavior.
-     */
-    backoffOptions?: BackoffOptions;
-    /**
-     * Error handler for recoverable errors.
-     *
-     * **Automatic retries**: The client automatically retries 5xx server errors, network
-     * errors, and 429 rate limits with exponential backoff. The `onError` callback is
-     * only invoked after these automatic retries are exhausted, or for non-retryable errors.
-     *
-     * **Return value behavior** (following Electric client pattern):
-     * - Return `{}` to retry with the same params/headers
-     * - Return `{ params }` to retry with merged params
-     * - Return `{ headers }` to retry with merged headers
-     * - Return `void`/`undefined` to stop the stream and propagate the error
-     *
-     * @example
-     * ```typescript
-     * // Refresh auth token on 401
-     * onError: async (error) => {
-     *   if (error instanceof FetchError && error.status === 401) {
-     *     const newToken = await refreshAuthToken()
-     *     return { headers: { Authorization: `Bearer ${newToken}` } }
-     *   }
-     * }
-     * ```
-     */
-    onError?: StreamErrorHandler;
+* Options for DurableStream constructor.
+*/
+interface DurableStreamOptions extends StreamHandleOptions {
+  /**
+  * Additional query parameters to include in requests.
+  */
+  params?: {
+    [key: string]: string | (() => MaybePromise<string>) | undefined;
+  };
+  /**
+  * Backoff options for retry behavior.
+  */
+  backoffOptions?: BackoffOptions;
+  /**
+  * Enable automatic batching for append() calls.
+  * When true, multiple append() calls made while a POST is in-flight
+  * will be batched together into a single request.
+  *
+  * @default true
+  */
+  batching?: boolean;
 }
 /**
- * A handle to a remote durable stream.
- *
- * This is a lightweight, reusable handle - not a persistent connection.
- * It does not automatically start reading or listening.
- * Create sessions as needed via read(), follow(), or toReadableStream().
- *
- * @example
- * ```typescript
- * // Create a handle without any network IO
- * const stream = new DurableStream({
- *   url: "https://streams.example.com/my-stream",
- *   auth: { token: "my-token" }
- * });
- *
- * // One-shot read
- * const result = await stream.read({ offset: savedOffset });
- *
- * // Follow for live updates
- * for await (const chunk of stream.follow()) {
- *   console.log(new TextDecoder().decode(chunk.data));
- * }
- * ```
- */
+* A handle to a remote durable stream for read/write operations.
+*
+* This is a lightweight, reusable handle - not a persistent connection.
+* It does not automatically start reading or listening.
+* Create sessions as needed via stream().
+*
+* @example
+* ```typescript
+* // Create a new stream
+* const stream = await DurableStream.create({
+*   url: "https://streams.example.com/my-stream",
+*   headers: { Authorization: "Bearer my-token" },
+*   contentType: "application/json"
+* });
+*
+* // Write data
+* await stream.append({ message: "hello" });
+*
+* // Read with the new API
+* const res = await stream.stream<{ message: string }>();
+* res.subscribeJson(async (batch) => {
+*   for (const item of batch.items) {
+*     console.log(item.message);
+*   }
+* });
+* ```
+*/
 declare class DurableStream {
-    #private;
-    /**
-     * The URL of the durable stream.
-     */
-    readonly url: string;
-    /**
-     * The content type of the stream (populated after connect/head/read).
-     */
-    contentType?: string;
-    /**
-     * Create a cold handle to a stream.
-     * No network IO is performed by the constructor.
-     */
-    constructor(opts: DurableStreamOptions);
-    /**
-     * Create a new stream (create-only PUT) and return a handle.
-     * Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
-     */
-    static create(opts: CreateOptions): Promise<DurableStream>;
-    /**
-     * Validate that a stream exists and fetch metadata via HEAD.
-     * Returns a handle with contentType populated (if sent by server).
-     */
-    static connect(opts: StreamOptions): Promise<DurableStream>;
-    /**
-     * HEAD metadata for a stream without creating a handle.
-     */
-    static head(opts: StreamOptions): Promise<HeadResult>;
-    /**
-     * Delete a stream without creating a handle.
-     */
-    static delete(opts: StreamOptions): Promise<void>;
-    /**
-     * HEAD metadata for this stream.
-     */
-    head(opts?: {
-        signal?: AbortSignal;
-    }): Promise<HeadResult>;
-    /**
-     * Create this stream (create-only PUT) using the URL/auth from the handle.
-     */
-    create(opts?: Omit<CreateOptions, keyof StreamOptions>): Promise<this>;
-    /**
-     * Delete this stream.
-     */
-    delete(opts?: {
-        signal?: AbortSignal;
-    }): Promise<void>;
-    /**
-     * Append a single payload to the stream.
-     *
-     * - `body` may be Uint8Array, string, or any Fetch BodyInit.
-     * - Strings are encoded as UTF-8.
-     * - `seq` (if provided) is sent as stream-seq (writer coordination).
-     */
-    append(body: BodyInit | Uint8Array | string, opts?: AppendOptions): Promise<void>;
-    /**
-     * Append a streaming body to the stream.
-     *
-     * - `source` yields Uint8Array or string chunks.
-     * - Strings are encoded as UTF-8; no delimiters are added.
-     * - Internally uses chunked transfer or HTTP/2 streaming.
-     */
-    appendStream(source: ReadableStream<Uint8Array | string> | AsyncIterable<Uint8Array | string>, opts?: AppendOptions): Promise<void>;
-    /**
-     * One-shot read.
-     *
-     * Performs a single GET from the specified offset/mode and returns a chunk.
-     * Caller is responsible for persisting the returned offset if they want to resume.
-     */
-    read(opts?: ReadOptions): Promise<ReadResult>;
-    /**
-     * Follow the stream as an AsyncIterable of chunks.
-     *
-     * Default behaviour:
-     * - From `offset` (or start if omitted), repeatedly perform catch-up reads
-     *   until a chunk with upToDate=true.
-     * - Then switch to live mode:
-     *   - SSE if content-type is text/* or application/json;
-     *   - otherwise long-poll.
-     *
-     * Explicit live override:
-     * - live="catchup": only catch-up, stop at upToDate.
-     * - live="long-poll": start long-polling immediately from offset.
-     * - live="sse": start SSE immediately (throws if SSE not supported).
-     */
-    follow(opts?: ReadOptions): AsyncIterable<StreamChunk>;
-    /**
-     * Wrap follow() in a Web ReadableStream for piping.
-     *
-     * Backpressure:
-     * - One chunk is pulled from follow() per pull() call, so standard
-     *   Web Streams backpressure semantics apply.
-     *
-     * Cancellation:
-     * - rs.cancel() will stop follow() and abort any in-flight request.
-     */
-    toReadableStream(opts?: ReadOptions & {
-        signal?: AbortSignal;
-    }): ReadableStream<StreamChunk>;
-    /**
-     * Wrap follow() in a Web ReadableStream<Uint8Array> for piping raw bytes.
-     *
-     * This is the native format for many web stream APIs.
-     */
-    toByteStream(opts?: ReadOptions & {
-        signal?: AbortSignal;
-    }): ReadableStream<Uint8Array>;
-    /**
-     * Convenience: interpret data as JSON messages.
-     * Parses each chunk's data as JSON and yields the parsed values.
-     */
-    json<T = unknown>(opts?: ReadOptions): AsyncIterable<T>;
-    /**
-     * Convenience: interpret data as text (UTF-8).
-     */
-    text(opts?: ReadOptions & {
-        decoder?: TextDecoder;
-    }): AsyncIterable<string>;
+  #private;
+  /**
+  * The URL of the durable stream.
+  */
+  readonly url: string;
+  /**
+  * The content type of the stream (populated after connect/head/read).
+  */
+  contentType?: string;
+  /**
+  * Create a cold handle to a stream.
+  * No network IO is performed by the constructor.
+  */
+  constructor(opts: DurableStreamOptions);
+  /**
+  * Create a new stream (create-only PUT) and return a handle.
+  * Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
+  */
+  static create(opts: CreateOptions): Promise<DurableStream>;
+  /**
+  * Validate that a stream exists and fetch metadata via HEAD.
+  * Returns a handle with contentType populated (if sent by server).
+  *
+  * **Important**: This only performs a HEAD request for validation - it does
+  * NOT open a session or start reading data. To read from the stream, call
+  * `stream()` on the returned handle.
+  *
+  * @example
+  * ```typescript
+  * // Validate stream exists before reading
+  * const handle = await DurableStream.connect({ url })
+  * const res = await handle.stream() // Now actually read
+  * ```
+  */
+  static connect(opts: DurableStreamOptions): Promise<DurableStream>;
+  /**
+  * HEAD metadata for a stream without creating a handle.
+  */
+  static head(opts: DurableStreamOptions): Promise<HeadResult>;
+  /**
+  * Delete a stream without creating a handle.
+  */
+  static delete(opts: DurableStreamOptions): Promise<void>;
+  /**
+  * HEAD metadata for this stream.
+  */
+  head(opts?: {
+    signal?: AbortSignal;
+  }): Promise<HeadResult>;
+  /**
+  * Create this stream (create-only PUT) using the URL/auth from the handle.
+  */
+  create(opts?: Omit<CreateOptions, keyof StreamOptions>): Promise<this>;
+  /**
+  * Delete this stream.
+  */
+  delete(opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+  * Append a single payload to the stream.
+  *
+  * When batching is enabled (default), multiple append() calls made while
+  * a POST is in-flight will be batched together into a single request.
+  * This significantly improves throughput for high-frequency writes.
+  *
+  * - `body` may be Uint8Array, string, or any JSON-serializable value (for JSON streams).
+  * - `body` may also be a Promise that resolves to any of the above types.
+  * - Strings are encoded as UTF-8.
+  * - `seq` (if provided) is sent as stream-seq (writer coordination).
+  *
+  * @example
+  * ```typescript
+  * // Direct value
+  * await stream.append({ message: "hello" });
+  *
+  * // Promise value - awaited before buffering
+  * await stream.append(fetchData());
+  * await stream.append(Promise.all([a, b, c]));
+  * ```
+  */
+  append(body: BodyInit | Uint8Array | string | unknown, opts?: AppendOptions): Promise<void>;
+  /**
+  * Append a streaming body to the stream.
+  *
+  * Supports piping from any ReadableStream or async iterable:
+  * - `source` yields Uint8Array or string chunks.
+  * - Strings are encoded as UTF-8; no delimiters are added.
+  * - Internally uses chunked transfer or HTTP/2 streaming.
+  *
+  * @example
+  * ```typescript
+  * // Pipe from a ReadableStream
+  * const readable = new ReadableStream({
+  *   start(controller) {
+  *     controller.enqueue("chunk 1");
+  *     controller.enqueue("chunk 2");
+  *     controller.close();
+  *   }
+  * });
+  * await stream.appendStream(readable);
+  *
+  * // Pipe from an async generator
+  * async function* generate() {
+  *   yield "line 1\n";
+  *   yield "line 2\n";
+  * }
+  * await stream.appendStream(generate());
+  *
+  * // Pipe from fetch response body
+  * const response = await fetch("https://example.com/data");
+  * await stream.appendStream(response.body!);
+  * ```
+  */
+  appendStream(source: ReadableStream<Uint8Array | string> | AsyncIterable<Uint8Array | string>, opts?: AppendOptions): Promise<void>;
+  /**
+  * Create a writable stream that pipes data to this durable stream.
+  *
+  * Returns a WritableStream that can be used with `pipeTo()` or
+  * `pipeThrough()` from any ReadableStream source.
+  *
+  * @example
+  * ```typescript
+  * // Pipe from fetch response
+  * const response = await fetch("https://example.com/data");
+  * await response.body!.pipeTo(stream.writable());
+  *
+  * // Pipe through a transform
+  * const readable = someStream.pipeThrough(new TextEncoderStream());
+  * await readable.pipeTo(stream.writable());
+  * ```
+  */
+  writable(opts?: AppendOptions): WritableStream<Uint8Array | string>;
+  /**
+  * Start a fetch-like streaming session against this handle's URL/headers/params.
+  * The first request is made inside this method; it resolves when we have
+  * a valid first response, or rejects on errors.
+  *
+  * Call-specific headers and params are merged with handle-level ones,
+  * with call-specific values taking precedence.
+  *
+  * @example
+  * ```typescript
+  * const handle = await DurableStream.connect({
+  *   url,
+  *   headers: { Authorization: `Bearer ${token}` }
+  * });
+  * const res = await handle.stream<{ message: string }>();
+  *
+  * // Accumulate all JSON items
+  * const items = await res.json();
+  *
+  * // Or stream live with ReadableStream
+  * const reader = res.jsonStream().getReader();
+  * let result = await reader.read();
+  * while (!result.done) {
+  *   console.log(result.value);
+  *   result = await reader.read();
+  * }
+  *
+  * // Or use subscriber for backpressure-aware consumption
+  * res.subscribeJson(async (batch) => {
+  *   for (const item of batch.items) {
+  *     console.log(item);
+  *   }
+  * });
+  * ```
+  */
+  stream<TJson = unknown>(options?: Omit<StreamOptions, `url`>): Promise<StreamResponse<TJson>>;
 }
 
+//#endregion
+//#region src/error.d.ts
 /**
- * Error thrown for transport/network errors.
- * Following the @electric-sql/client FetchError pattern.
- */
+* Error thrown for transport/network errors.
+* Following the @electric-sql/client FetchError pattern.
+*/
 declare class FetchError extends Error {
-    url: string;
-    status: number;
-    text?: string;
-    json?: object;
-    headers: Record<string, string>;
-    constructor(status: number, text: string | undefined, json: object | undefined, headers: Record<string, string>, url: string, message?: string);
-    static fromResponse(response: Response, url: string): Promise<FetchError>;
+  url: string;
+  status: number;
+  text?: string;
+  json?: object;
+  headers: Record<string, string>;
+  constructor(status: number, text: string | undefined, json: object | undefined, headers: Record<string, string>, url: string, message?: string);
+  static fromResponse(response: Response, url: string): Promise<FetchError>;
 }
 /**
- * Error thrown when a fetch operation is aborted during backoff.
- */
+* Error thrown when a fetch operation is aborted during backoff.
+*/
 declare class FetchBackoffAbortError extends Error {
-    constructor();
+  constructor();
 }
 /**
- * Protocol-level error for Durable Streams operations.
- * Provides structured error handling with error codes.
- */
+* Protocol-level error for Durable Streams operations.
+* Provides structured error handling with error codes.
+*/
 declare class DurableStreamError extends Error {
-    /**
-     * HTTP status code, if applicable.
-     */
-    status?: number;
-    /**
-     * Structured error code for programmatic handling.
-     */
-    code: DurableStreamErrorCode;
-    /**
-     * Additional error details (e.g., raw response body).
-     */
-    details?: unknown;
-    constructor(message: string, code: DurableStreamErrorCode, status?: number, details?: unknown);
-    /**
-     * Create a DurableStreamError from an HTTP response.
-     */
-    static fromResponse(response: Response, url: string): Promise<DurableStreamError>;
-    /**
-     * Create a DurableStreamError from a FetchError.
-     */
-    static fromFetchError(error: FetchError): DurableStreamError;
+  /**
+  * HTTP status code, if applicable.
+  */
+  status?: number;
+  /**
+  * Structured error code for programmatic handling.
+  */
+  code: DurableStreamErrorCode;
+  /**
+  * Additional error details (e.g., raw response body).
+  */
+  details?: unknown;
+  constructor(message: string, code: DurableStreamErrorCode, status?: number, details?: unknown);
+  /**
+  * Create a DurableStreamError from an HTTP response.
+  */
+  static fromResponse(response: Response, url: string): Promise<DurableStreamError>;
+  /**
+  * Create a DurableStreamError from a FetchError.
+  */
+  static fromFetchError(error: FetchError): DurableStreamError;
 }
 /**
- * Error thrown when stream URL is missing.
- */
+* Error thrown when stream URL is missing.
+*/
 declare class MissingStreamUrlError extends Error {
-    constructor();
+  constructor();
 }
 /**
- * Error thrown when signal option is invalid.
- */
+* Error thrown when signal option is invalid.
+*/
 declare class InvalidSignalError extends Error {
-    constructor();
+  constructor();
 }
 
+//#endregion
+//#region src/constants.d.ts
+/**
+* Durable Streams Protocol Constants
+*
+* Header and query parameter names following the Electric Durable Stream Protocol.
+*/
+/**
+* Response header containing the next offset to read from.
+* Offsets are opaque tokens - clients MUST NOT interpret the format.
+*/
+declare const STREAM_OFFSET_HEADER = "Stream-Next-Offset";
 /**
- * Durable Streams Protocol Constants
- *
- * Header and query parameter names following the Electric Durable Stream Protocol.
- */
-/**
- * Response header containing the next offset to read from.
- * Format: "<read-seq>_<byte-offset>"
- */
-declare const STREAM_OFFSET_HEADER = "stream-offset";
-/**
- * Response header for cursor (used for CDN collapsing).
- * Echo this value in subsequent long-poll requests.
- */
-declare const STREAM_CURSOR_HEADER = "stream-cursor";
-/**
- * Presence header indicating response ends at current end of stream.
- * When present (any value), indicates up-to-date.
- */
-declare const STREAM_UP_TO_DATE_HEADER = "stream-up-to-date";
-/**
- * Request header for writer coordination sequence.
- * Monotonic, lexicographic. If lower than last appended seq -> 409 Conflict.
- */
-declare const STREAM_SEQ_HEADER = "stream-seq";
-/**
- * Request header for stream TTL in seconds (on create).
- */
-declare const STREAM_TTL_HEADER = "stream-ttl";
-/**
- * Request header for absolute stream expiry time (RFC3339, on create).
- */
-declare const STREAM_EXPIRES_AT_HEADER = "stream-expires-at";
-/**
- * Query parameter for starting offset.
- */
+* Response header for cursor (used for CDN collapsing).
+* Echo this value in subsequent long-poll requests.
+*/
+declare const STREAM_CURSOR_HEADER = "Stream-Cursor";
+/**
+* Presence header indicating response ends at current end of stream.
+* When present (any value), indicates up-to-date.
+*/
+declare const STREAM_UP_TO_DATE_HEADER = "Stream-Up-To-Date";
+/**
+* Request header for writer coordination sequence.
+* Monotonic, lexicographic. If lower than last appended seq -> 409 Conflict.
+*/
+declare const STREAM_SEQ_HEADER = "Stream-Seq";
+/**
+* Request header for stream TTL in seconds (on create).
+*/
+declare const STREAM_TTL_HEADER = "Stream-TTL";
+/**
+* Request header for absolute stream expiry time (RFC3339, on create).
+*/
+declare const STREAM_EXPIRES_AT_HEADER = "Stream-Expires-At";
+/**
+* Query parameter for starting offset.
+*/
 declare const OFFSET_QUERY_PARAM = "offset";
 /**
- * Query parameter for live mode.
- * Values: "long-poll", "sse"
- */
+* Query parameter for live mode.
+* Values: "long-poll", "sse"
+*/
 declare const LIVE_QUERY_PARAM = "live";
 /**
- * Query parameter for echoing cursor (CDN collapsing).
- */
+* Query parameter for echoing cursor (CDN collapsing).
+*/
 declare const CURSOR_QUERY_PARAM = "cursor";
 /**
- * Content types that support SSE mode.
- * SSE is only valid for text/* or application/json streams.
- */
-declare const SSE_COMPATIBLE_CONTENT_TYPES: string[];
+* SSE control event field for the next offset.
+* Note: Different from HTTP header name (camelCase vs Header-Case).
+*/
+
+/**
+* Content types that support SSE mode.
+* SSE is only valid for text/* or application/json streams.
+*/
+declare const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string>;
 /**
- * Protocol query parameters that should not be set by users.
- */
+* Protocol query parameters that should not be set by users.
+*/
 declare const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: Array<string>;
 
-export { type AppendOptions, type Auth, BackoffDefaults, type BackoffOptions, CURSOR_QUERY_PARAM, type CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, type DurableStreamErrorCode, type DurableStreamOptions, FetchBackoffAbortError, FetchError, type HeadResult, type HeadersRecord, InvalidSignalError, LIVE_QUERY_PARAM, type LiveMode, type MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, type Offset, type ParamsRecord, type ReadOptions, type ReadResult, type RetryOpts, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, type StreamChunk, type StreamErrorHandler, type StreamOptions, createFetchWithBackoff, createFetchWithConsumedBody };
+//#endregion
+export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream };