@durable-streams/client 0.1.4 → 0.2.0

package/dist/index.cjs

@@ -506,7 +506,10 @@ async function* parseSSEStream(stream$1, signal) {
 							streamCursor: control.streamCursor,
 							upToDate: control.upToDate
 						};
-					} catch {}
+					} catch (err) {
+						const preview = dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr;
+						throw new DurableStreamError(`Failed to parse SSE control event: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+					}
 				}
 				currentEvent = { data: [] };
 			} else if (line.startsWith(`event:`)) currentEvent.type = line.slice(6).trim();
@@ -531,7 +534,10 @@ async function* parseSSEStream(stream$1, signal) {
 					streamCursor: control.streamCursor,
 					upToDate: control.upToDate
 				};
-			} catch {}
+			} catch (err) {
+				const preview = dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr;
+				throw new DurableStreamError(`Failed to parse SSE control event: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+			}
 		}
 	} finally {
 		reader.releaseLock();
@@ -541,6 +547,10 @@ async function* parseSSEStream(stream$1, signal) {
 //#endregion
 //#region src/response.ts
 /**
+* Constant used as abort reason when pausing the stream due to visibility change.
+*/
+const PAUSE_STREAM = `PAUSE_STREAM`;
+/**
 * Implementation of the StreamResponse interface.
 */
 var StreamResponseImpl = class {
@@ -553,9 +563,9 @@ var StreamResponseImpl = class {
 	#statusText;
 	#ok;
 	#isLoading;
-	offset;
-	cursor;
-	upToDate;
+	#offset;
+	#cursor;
+	#upToDate;
 	#isJsonMode;
 	#abortController;
 	#fetchNext;
@@ -565,6 +575,12 @@ var StreamResponseImpl = class {
 	#closed;
 	#stopAfterUpToDate = false;
 	#consumptionMethod = null;
+	#state = `active`;
+	#requestAbortController;
+	#unsubscribeFromVisibilityChanges;
+	#pausePromise;
+	#pauseResolve;
+	#justResumedFromPause = false;
 	#sseResilience;
 	#lastSSEConnectionStartTime;
 	#consecutiveShortSSEConnections = 0;
@@ -575,9 +591,9 @@ var StreamResponseImpl = class {
 		this.contentType = config.contentType;
 		this.live = config.live;
 		this.startOffset = config.startOffset;
-		this.offset = config.initialOffset;
-		this.cursor = config.initialCursor;
-		this.upToDate = config.initialUpToDate;
+		this.#offset = config.initialOffset;
+		this.#cursor = config.initialCursor;
+		this.#upToDate = config.initialUpToDate;
 		this.#headers = config.firstResponse.headers;
 		this.#status = config.firstResponse.status;
 		this.#statusText = config.firstResponse.statusText;
@@ -599,6 +615,59 @@ var StreamResponseImpl = class {
 			this.#closedReject = reject;
 		});
 		this.#responseStream = this.#createResponseStream(config.firstResponse);
+		this.#abortController.signal.addEventListener(`abort`, () => {
+			this.#requestAbortController?.abort(this.#abortController.signal.reason);
+			this.#pauseResolve?.();
+			this.#pausePromise = void 0;
+			this.#pauseResolve = void 0;
+		}, { once: true });
+		this.#subscribeToVisibilityChanges();
+	}
+	/**
+	* Subscribe to document visibility changes to pause/resume syncing.
+	* When the page is hidden, we pause to save battery and bandwidth.
+	* When visible again, we resume syncing.
+	*/
+	#subscribeToVisibilityChanges() {
+		if (typeof document === `object` && typeof document.hidden === `boolean` && typeof document.addEventListener === `function`) {
+			const visibilityHandler = () => {
+				if (document.hidden) this.#pause();
+				else this.#resume();
+			};
+			document.addEventListener(`visibilitychange`, visibilityHandler);
+			this.#unsubscribeFromVisibilityChanges = () => {
+				if (typeof document === `object`) document.removeEventListener(`visibilitychange`, visibilityHandler);
+			};
+			if (document.hidden) this.#pause();
+		}
+	}
+	/**
+	* Pause the stream when page becomes hidden.
+	* Aborts any in-flight request to free resources.
+	* Creates a promise that pull() will await while paused.
+	*/
+	#pause() {
+		if (this.#state === `active`) {
+			this.#state = `pause-requested`;
+			this.#pausePromise = new Promise((resolve) => {
+				this.#pauseResolve = resolve;
+			});
+			this.#requestAbortController?.abort(PAUSE_STREAM);
+		}
+	}
+	/**
+	* Resume the stream when page becomes visible.
+	* Resolves the pause promise to unblock pull().
+	*/
+	#resume() {
+		if (this.#state === `paused` || this.#state === `pause-requested`) {
+			if (this.#abortController.signal.aborted) return;
+			this.#state = `active`;
+			this.#justResumedFromPause = true;
+			this.#pauseResolve?.();
+			this.#pausePromise = void 0;
+			this.#pauseResolve = void 0;
+		}
 	}
 	get headers() {
 		return this.#headers;
@@ -615,13 +684,24 @@ var StreamResponseImpl = class {
 	get isLoading() {
 		return this.#isLoading;
 	}
+	get offset() {
+		return this.#offset;
+	}
+	get cursor() {
+		return this.#cursor;
+	}
+	get upToDate() {
+		return this.#upToDate;
+	}
 	#ensureJsonMode() {
 		if (!this.#isJsonMode) throw new DurableStreamError(`JSON methods are only valid for JSON-mode streams. Content-Type is "${this.contentType}" and json hint was not set.`, `BAD_REQUEST`);
 	}
 	#markClosed() {
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#closedResolve();
 	}
 	#markError(err) {
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#closedReject(err);
 	}
 	/**
@@ -646,10 +726,10 @@ var StreamResponseImpl = class {
 	*/
 	#updateStateFromResponse(response) {
 		const offset = response.headers.get(STREAM_OFFSET_HEADER);
-		if (offset) this.offset = offset;
+		if (offset) this.#offset = offset;
 		const cursor = response.headers.get(STREAM_CURSOR_HEADER);
-		if (cursor) this.cursor = cursor;
-		this.upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER);
+		if (cursor) this.#cursor = cursor;
+		this.#upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER);
 		this.#headers = response.headers;
 		this.#status = response.status;
 		this.#statusText = response.statusText;
@@ -691,9 +771,9 @@ var StreamResponseImpl = class {
 	* Update instance state from an SSE control event.
 	*/
 	#updateStateFromSSEControl(controlEvent) {
-		this.offset = controlEvent.streamNextOffset;
-		if (controlEvent.streamCursor) this.cursor = controlEvent.streamCursor;
-		if (controlEvent.upToDate !== void 0) this.upToDate = controlEvent.upToDate;
+		this.#offset = controlEvent.streamNextOffset;
+		if (controlEvent.streamCursor) this.#cursor = controlEvent.streamCursor;
+		if (controlEvent.upToDate !== void 0) this.#upToDate = controlEvent.upToDate;
 	}
 	/**
 	* Mark the start of an SSE connection for duration tracking.
@@ -734,8 +814,9 @@ var StreamResponseImpl = class {
 		const delayOrNull = await this.#handleSSEConnectionEnd();
 		if (delayOrNull === null) return null;
 		this.#markSSEConnectionStart();
-		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#abortController.signal);
-		if (newSSEResponse.body) return parseSSEStream(newSSEResponse.body, this.#abortController.signal);
+		this.#requestAbortController = new AbortController();
+		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#requestAbortController.signal);
+		if (newSSEResponse.body) return parseSSEStream(newSSEResponse.body, this.#requestAbortController.signal);
 		return null;
 	}
 	/**
@@ -821,7 +902,8 @@ var StreamResponseImpl = class {
 						const isSSE = firstResponse.headers.get(`content-type`)?.includes(`text/event-stream`) ?? false;
 						if (isSSE && firstResponse.body) {
 							this.#markSSEConnectionStart();
-							sseEventIterator = parseSSEStream(firstResponse.body, this.#abortController.signal);
+							this.#requestAbortController = new AbortController();
+							sseEventIterator = parseSSEStream(firstResponse.body, this.#requestAbortController.signal);
 						} else {
 							controller.enqueue(firstResponse);
 							if (this.upToDate && !this.#shouldContinueLive()) {
@@ -832,33 +914,63 @@ var StreamResponseImpl = class {
 							return;
 						}
 					}
-					if (sseEventIterator) while (true) {
-						const result = await this.#processSSEEvents(sseEventIterator);
-						switch (result.type) {
-							case `response`:
-								if (result.newIterator) sseEventIterator = result.newIterator;
-								controller.enqueue(result.response);
-								return;
-							case `closed`:
+					if (sseEventIterator) {
+						if (this.#state === `pause-requested` || this.#state === `paused`) {
+							this.#state = `paused`;
+							if (this.#pausePromise) await this.#pausePromise;
+							if (this.#abortController.signal.aborted) {
 								this.#markClosed();
 								controller.close();
 								return;
-							case `error`:
-								this.#markError(result.error);
-								controller.error(result.error);
+							}
+							const newIterator = await this.#trySSEReconnect();
+							if (newIterator) sseEventIterator = newIterator;
+							else {
+								this.#markClosed();
+								controller.close();
 								return;
-							case `continue`:
-								if (result.newIterator) sseEventIterator = result.newIterator;
-								continue;
+							}
+						}
+						while (true) {
+							const result = await this.#processSSEEvents(sseEventIterator);
+							switch (result.type) {
+								case `response`:
+									if (result.newIterator) sseEventIterator = result.newIterator;
+									controller.enqueue(result.response);
+									return;
+								case `closed`:
+									this.#markClosed();
+									controller.close();
+									return;
+								case `error`:
+									this.#markError(result.error);
+									controller.error(result.error);
+									return;
+								case `continue`:
+									if (result.newIterator) sseEventIterator = result.newIterator;
+									continue;
+							}
 						}
 					}
 					if (this.#shouldContinueLive()) {
+						if (this.#state === `pause-requested` || this.#state === `paused`) {
+							this.#state = `paused`;
+							if (this.#pausePromise) await this.#pausePromise;
+							if (this.#abortController.signal.aborted) {
+								this.#markClosed();
+								controller.close();
+								return;
+							}
+						}
 						if (this.#abortController.signal.aborted) {
 							this.#markClosed();
 							controller.close();
 							return;
 						}
-						const response = await this.#fetchNext(this.offset, this.cursor, this.#abortController.signal);
+						const resumingFromPause = this.#justResumedFromPause;
+						this.#justResumedFromPause = false;
+						this.#requestAbortController = new AbortController();
+						const response = await this.#fetchNext(this.offset, this.cursor, this.#requestAbortController.signal, resumingFromPause);
 						this.#updateStateFromResponse(response);
 						controller.enqueue(response);
 						return;
@@ -866,6 +978,10 @@ var StreamResponseImpl = class {
 					this.#markClosed();
 					controller.close();
 				} catch (err) {
+					if (this.#requestAbortController?.signal.aborted && this.#requestAbortController.signal.reason === PAUSE_STREAM) {
+						if (this.#state === `pause-requested`) this.#state = `paused`;
+						return;
+					}
 					if (this.#abortController.signal.aborted) {
 						this.#markClosed();
 						controller.close();
@@ -877,6 +993,7 @@ var StreamResponseImpl = class {
 			},
 			cancel: () => {
 				this.#abortController.abort();
+				this.#unsubscribeFromVisibilityChanges?.();
 				this.#markClosed();
 			}
 		});
@@ -922,7 +1039,13 @@ var StreamResponseImpl = class {
 				const wasUpToDate = this.upToDate;
 				const text = await result.value.text();
 				const content = text.trim() || `[]`;
-				const parsed = JSON.parse(content);
+				let parsed;
+				try {
+					parsed = JSON.parse(content);
+				} catch (err) {
+					const preview = content.length > 100 ? content.slice(0, 100) + `...` : content;
+					throw new DurableStreamError(`Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+				}
 				if (Array.isArray(parsed)) items.push(...parsed);
 				else items.push(parsed);
 				if (wasUpToDate) break;
@@ -1019,7 +1142,13 @@ var StreamResponseImpl = class {
 				}
 				const text = await response.text();
 				const content = text.trim() || `[]`;
-				const parsed = JSON.parse(content);
+				let parsed;
+				try {
+					parsed = JSON.parse(content);
+				} catch (err) {
+					const preview = content.length > 100 ? content.slice(0, 100) + `...` : content;
+					throw new DurableStreamError(`Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+				}
 				pendingItems = Array.isArray(parsed) ? parsed : [parsed];
 				if (pendingItems.length > 0) controller.enqueue(pendingItems.shift());
 			},
@@ -1058,7 +1187,13 @@ var StreamResponseImpl = class {
 					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
 					const text = await response.text();
 					const content = text.trim() || `[]`;
-					const parsed = JSON.parse(content);
+					let parsed;
+					try {
+						parsed = JSON.parse(content);
+					} catch (err) {
+						const preview = content.length > 100 ? content.slice(0, 100) + `...` : content;
+						throw new DurableStreamError(`Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+					}
 					const items = Array.isArray(parsed) ? parsed : [parsed];
 					await subscriber({
 						items,
@@ -1158,6 +1293,7 @@ var StreamResponseImpl = class {
 	}
 	cancel(reason) {
 		this.#abortController.abort(reason);
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#markClosed();
 	}
 	get closed() {
@@ -1302,7 +1438,7 @@ function _resetHttpWarningForTesting() {
 *   url,
 *   auth,
 *   offset: savedOffset,
-*   live: "auto",
+*   live: true,
 * })
 * live.subscribeJson(async (batch) => {
 *   for (const item of batch.items) {
@@ -1343,10 +1479,11 @@ async function stream(options) {
 */
 async function streamInternal(options) {
 	const url = options.url instanceof URL ? options.url.toString() : options.url;
+	warnIfUsingHttpInBrowser(url, options.warnOnHttp);
 	const fetchUrl = new URL(url);
 	const startOffset = options.offset ?? `-1`;
 	fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, startOffset);
-	const live = options.live ?? `auto`;
+	const live = options.live ?? true;
 	if (live === `long-poll` || live === `sse`) fetchUrl.searchParams.set(LIVE_QUERY_PARAM, live);
 	const params = await resolveParams(options.params);
 	for (const [key, value] of Object.entries(params)) fetchUrl.searchParams.set(key, value);
@@ -1372,11 +1509,13 @@ async function streamInternal(options) {
 	const initialCursor = firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? void 0;
 	const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER);
 	const isJsonMode = options.json === true || (contentType?.includes(`application/json`) ?? false);
-	const fetchNext = async (offset, cursor, signal) => {
+	const fetchNext = async (offset, cursor, signal, resumingFromPause) => {
 		const nextUrl = new URL(url);
 		nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
-		if (live === `auto` || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
-		else if (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+		if (!resumingFromPause) {
+			if (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+			else if (live === true || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
+		}
 		if (cursor) nextUrl.searchParams.set(`cursor`, cursor);
 		const nextParams = await resolveParams(options.params);
 		for (const [key, value] of Object.entries(nextParams)) nextUrl.searchParams.set(key, value);
@@ -1423,927 +1562,947 @@ async function streamInternal(options) {
 }
 
 //#endregion
-//#region src/stream.ts
+//#region src/idempotent-producer.ts
+/**
+* Error thrown when a producer's epoch is stale (zombie fencing).
+*/
+var StaleEpochError = class extends Error {
+	/**
+	* The current epoch on the server.
+	*/
+	currentEpoch;
+	constructor(currentEpoch) {
+		super(`Producer epoch is stale. Current server epoch: ${currentEpoch}. Call restart() or create a new producer with a higher epoch.`);
+		this.name = `StaleEpochError`;
+		this.currentEpoch = currentEpoch;
+	}
+};
+/**
+* Error thrown when an unrecoverable sequence gap is detected.
+*
+* With maxInFlight > 1, HTTP requests can arrive out of order at the server,
+* causing temporary 409 responses. The client automatically handles these
+* by waiting for earlier sequences to complete, then retrying.
+*
+* This error is only thrown when the gap cannot be resolved (e.g., the
+* expected sequence is >= our sequence, indicating a true protocol violation).
+*/
+var SequenceGapError = class extends Error {
+	expectedSeq;
+	receivedSeq;
+	constructor(expectedSeq, receivedSeq) {
+		super(`Producer sequence gap: expected ${expectedSeq}, received ${receivedSeq}`);
+		this.name = `SequenceGapError`;
+		this.expectedSeq = expectedSeq;
+		this.receivedSeq = receivedSeq;
+	}
+};
 /**
 * Normalize content-type by extracting the media type (before any semicolon).
-* Handles cases like "application/json; charset=utf-8".
 */
 function normalizeContentType$1(contentType) {
 	if (!contentType) return ``;
 	return contentType.split(`;`)[0].trim().toLowerCase();
 }
 /**
-* Check if a value is a Promise or Promise-like (thenable).
-*/
-function isPromiseLike(value) {
-	return value !== null && typeof value === `object` && `then` in value && typeof value.then === `function`;
-}
-/**
-* A handle to a remote durable stream for read/write operations.
+* An idempotent producer for exactly-once writes to a 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 stream().
+* Features:
+* - Fire-and-forget: append() returns immediately, batches in background
+* - Exactly-once: server deduplicates using (producerId, epoch, seq)
+* - Batching: multiple appends batched into single HTTP request
+* - Pipelining: up to maxInFlight concurrent batches
+* - Zombie fencing: stale producers rejected via epoch validation
 *
 * @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"
+* const stream = new DurableStream({ url: "https://..." });
+* const producer = new IdempotentProducer(stream, "order-service-1", {
+*   epoch: 0,
+*   autoClaim: true,
 * });
 *
-* // Write data
-* await stream.append({ message: "hello" });
+* // Fire-and-forget writes (synchronous, returns immediately)
+* producer.append("message 1");
+* producer.append("message 2");
 *
-* // 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);
-*   }
-* });
+* // Ensure all messages are delivered before shutdown
+* await producer.flush();
+* await producer.close();
 * ```
 */
-var DurableStream = class DurableStream {
-	/**
-	* The URL of the durable stream.
-	*/
-	url;
-	/**
-	* The content type of the stream (populated after connect/head/read).
-	*/
-	contentType;
-	#options;
+var IdempotentProducer = class {
+	#stream;
+	#producerId;
+	#epoch;
+	#nextSeq = 0;
+	#autoClaim;
+	#maxBatchBytes;
+	#lingerMs;
 	#fetchClient;
+	#signal;
 	#onError;
-	#batchingEnabled;
+	#pendingBatch = [];
+	#batchBytes = 0;
+	#lingerTimeout = null;
 	#queue;
-	#buffer = [];
-	/**
-	* Create a cold handle to a stream.
-	* No network IO is performed by the constructor.
-	*/
-	constructor(opts) {
-		validateOptions(opts);
-		const urlStr = opts.url instanceof URL ? opts.url.toString() : opts.url;
-		this.url = urlStr;
-		this.#options = {
-			...opts,
-			url: urlStr
-		};
-		this.#onError = opts.onError;
-		if (opts.contentType) this.contentType = opts.contentType;
-		this.#batchingEnabled = opts.batching !== false;
-		if (this.#batchingEnabled) this.#queue = fastq.default.promise(this.#batchWorker.bind(this), 1);
-		const baseFetchClient = opts.fetch ?? ((...args) => fetch(...args));
-		const backOffOpts = { ...opts.backoffOptions ?? BackoffDefaults };
-		const fetchWithBackoffClient = createFetchWithBackoff(baseFetchClient, backOffOpts);
-		this.#fetchClient = createFetchWithConsumedBody(fetchWithBackoffClient);
-	}
+	#maxInFlight;
+	#closed = false;
+	#epochClaimed;
+	#seqState = new Map();
 	/**
-	* Create a new stream (create-only PUT) and return a handle.
-	* Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
+	* Create an idempotent producer for a stream.
+	*
+	* @param stream - The DurableStream to write to
+	* @param producerId - Stable identifier for this producer (e.g., "order-service-1")
+	* @param opts - Producer options
 	*/
-	static async create(opts) {
-		const stream$1 = new DurableStream(opts);
-		await stream$1.create({
-			contentType: opts.contentType,
-			ttlSeconds: opts.ttlSeconds,
-			expiresAt: opts.expiresAt,
-			body: opts.body
-		});
-		return stream$1;
+	constructor(stream$1, producerId, opts) {
+		const epoch = opts?.epoch ?? 0;
+		const maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024;
+		const maxInFlight = opts?.maxInFlight ?? 5;
+		const lingerMs = opts?.lingerMs ?? 5;
+		if (epoch < 0) throw new Error(`epoch must be >= 0`);
+		if (maxBatchBytes <= 0) throw new Error(`maxBatchBytes must be > 0`);
+		if (maxInFlight <= 0) throw new Error(`maxInFlight must be > 0`);
+		if (lingerMs < 0) throw new Error(`lingerMs must be >= 0`);
+		this.#stream = stream$1;
+		this.#producerId = producerId;
+		this.#epoch = epoch;
+		this.#autoClaim = opts?.autoClaim ?? false;
+		this.#maxBatchBytes = maxBatchBytes;
+		this.#lingerMs = lingerMs;
+		this.#signal = opts?.signal;
+		this.#onError = opts?.onError;
+		this.#fetchClient = opts?.fetch ?? ((...args) => fetch(...args));
+		this.#maxInFlight = maxInFlight;
+		this.#epochClaimed = !this.#autoClaim;
+		this.#queue = fastq.default.promise(this.#batchWorker.bind(this), this.#maxInFlight);
+		if (this.#signal) this.#signal.addEventListener(`abort`, () => {
+			this.#rejectPendingBatch(new DurableStreamError(`Producer aborted`, `ALREADY_CLOSED`, void 0, void 0));
+		}, { once: true });
 	}
 	/**
-	* Validate that a stream exists and fetch metadata via HEAD.
-	* Returns a handle with contentType populated (if sent by server).
+	* Append data to the stream.
 	*
-	* **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.
+	* This is fire-and-forget: returns immediately after adding to the batch.
+	* The message is batched and sent when:
+	* - maxBatchBytes is reached
+	* - lingerMs elapses
+	* - flush() is called
+	*
+	* Errors are reported via onError callback if configured. Use flush() to
+	* wait for all pending messages to be sent.
+	*
+	* For JSON streams, pass pre-serialized JSON strings.
+	* For byte streams, pass string or Uint8Array.
+	*
+	* @param body - Data to append (string or Uint8Array)
 	*
 	* @example
 	* ```typescript
-	* // Validate stream exists before reading
-	* const handle = await DurableStream.connect({ url })
-	* const res = await handle.stream() // Now actually read
+	* // JSON stream
+	* producer.append(JSON.stringify({ message: "hello" }));
+	*
+	* // Byte stream
+	* producer.append("raw text data");
+	* producer.append(new Uint8Array([1, 2, 3]));
 	* ```
 	*/
-	static async connect(opts) {
-		const stream$1 = new DurableStream(opts);
-		await stream$1.head();
-		return stream$1;
+	append(body) {
+		if (this.#closed) throw new DurableStreamError(`Producer is closed`, `ALREADY_CLOSED`, void 0, void 0);
+		let bytes;
+		if (typeof body === `string`) bytes = new TextEncoder().encode(body);
+		else if (body instanceof Uint8Array) bytes = body;
+		else throw new DurableStreamError(`append() requires string or Uint8Array. For objects, use JSON.stringify().`, `BAD_REQUEST`, 400, void 0);
+		this.#pendingBatch.push({ body: bytes });
+		this.#batchBytes += bytes.length;
+		if (this.#batchBytes >= this.#maxBatchBytes) this.#enqueuePendingBatch();
+		else if (!this.#lingerTimeout) this.#lingerTimeout = setTimeout(() => {
+			this.#lingerTimeout = null;
+			if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
+		}, this.#lingerMs);
 	}
 	/**
-	* HEAD metadata for a stream without creating a handle.
+	* Send any pending batch immediately and wait for all in-flight batches.
+	*
+	* Call this before shutdown to ensure all messages are delivered.
 	*/
-	static async head(opts) {
-		const stream$1 = new DurableStream(opts);
-		return stream$1.head();
+	async flush() {
+		if (this.#lingerTimeout) {
+			clearTimeout(this.#lingerTimeout);
+			this.#lingerTimeout = null;
+		}
+		if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
+		await this.#queue.drained();
 	}
 	/**
-	* Delete a stream without creating a handle.
+	* Flush pending messages and close the producer.
+	*
+	* After calling close(), further append() calls will throw.
 	*/
-	static async delete(opts) {
-		const stream$1 = new DurableStream(opts);
-		return stream$1.delete();
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		try {
+			await this.flush();
+		} catch {}
 	}
 	/**
-	* HEAD metadata for this stream.
+	* Increment epoch and reset sequence.
+	*
+	* Call this when restarting the producer to establish a new session.
+	* Flushes any pending messages first.
 	*/
-	async head(opts) {
-		const { requestHeaders, fetchUrl } = await this.#buildRequest();
-		const response = await this.#fetchClient(fetchUrl.toString(), {
-			method: `HEAD`,
-			headers: requestHeaders,
-			signal: opts?.signal ?? this.#options.signal
-		});
-		if (!response.ok) await handleErrorResponse(response, this.url);
-		const contentType = response.headers.get(`content-type`) ?? void 0;
-		const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
-		const etag = response.headers.get(`etag`) ?? void 0;
-		const cacheControl = response.headers.get(`cache-control`) ?? void 0;
-		if (contentType) this.contentType = contentType;
-		return {
-			exists: true,
-			contentType,
-			offset,
-			etag,
-			cacheControl
-		};
+	async restart() {
+		await this.flush();
+		this.#epoch++;
+		this.#nextSeq = 0;
 	}
 	/**
-	* Create this stream (create-only PUT) using the URL/auth from the handle.
+	* Current epoch for this producer.
 	*/
-	async create(opts) {
-		const { requestHeaders, fetchUrl } = await this.#buildRequest();
-		const contentType = opts?.contentType ?? this.#options.contentType;
-		if (contentType) requestHeaders[`content-type`] = contentType;
-		if (opts?.ttlSeconds !== void 0) requestHeaders[STREAM_TTL_HEADER] = String(opts.ttlSeconds);
-		if (opts?.expiresAt) requestHeaders[STREAM_EXPIRES_AT_HEADER] = opts.expiresAt;
-		const body = encodeBody(opts?.body);
-		const response = await this.#fetchClient(fetchUrl.toString(), {
-			method: `PUT`,
-			headers: requestHeaders,
-			body,
-			signal: this.#options.signal
-		});
-		if (!response.ok) await handleErrorResponse(response, this.url, { operation: `create` });
-		const responseContentType = response.headers.get(`content-type`);
-		if (responseContentType) this.contentType = responseContentType;
-		else if (contentType) this.contentType = contentType;
-		return this;
+	get epoch() {
+		return this.#epoch;
 	}
 	/**
-	* Delete this stream.
+	* Next sequence number to be assigned.
 	*/
-	async delete(opts) {
-		const { requestHeaders, fetchUrl } = await this.#buildRequest();
-		const response = await this.#fetchClient(fetchUrl.toString(), {
-			method: `DELETE`,
-			headers: requestHeaders,
-			signal: opts?.signal ?? this.#options.signal
-		});
-		if (!response.ok) await handleErrorResponse(response, this.url);
+	get nextSeq() {
+		return this.#nextSeq;
 	}
 	/**
-	* 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]));
-	* ```
+	* Number of messages in the current pending batch.
 	*/
-	async append(body, opts) {
-		const resolvedBody = isPromiseLike(body) ? await body : body;
-		if (this.#batchingEnabled && this.#queue) return this.#appendWithBatching(resolvedBody, opts);
-		return this.#appendDirect(resolvedBody, opts);
+	get pendingCount() {
+		return this.#pendingBatch.length;
 	}
 	/**
-	* Direct append without batching (used when batching is disabled).
+	* Number of batches currently in flight.
 	*/
-	async #appendDirect(body, opts) {
-		const { requestHeaders, fetchUrl } = await this.#buildRequest();
-		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
-		if (contentType) requestHeaders[`content-type`] = contentType;
-		if (opts?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
-		const isJson = normalizeContentType$1(contentType) === `application/json`;
-		const bodyToEncode = isJson ? [body] : body;
-		const encodedBody = encodeBody(bodyToEncode);
-		const response = await this.#fetchClient(fetchUrl.toString(), {
-			method: `POST`,
-			headers: requestHeaders,
-			body: encodedBody,
-			signal: opts?.signal ?? this.#options.signal
-		});
-		if (!response.ok) await handleErrorResponse(response, this.url);
+	get inFlightCount() {
+		return this.#queue.length();
 	}
 	/**
-	* Append with batching - buffers messages and sends them in batches.
+	* Enqueue the current pending batch for processing.
 	*/
-	async #appendWithBatching(body, opts) {
-		return new Promise((resolve, reject) => {
-			this.#buffer.push({
-				data: body,
-				seq: opts?.seq,
-				contentType: opts?.contentType,
-				signal: opts?.signal,
-				resolve,
-				reject
-			});
-			if (this.#queue.idle()) {
-				const batch = this.#buffer.splice(0);
-				this.#queue.push(batch).catch((err) => {
-					for (const msg of batch) msg.reject(err);
-				});
-			}
+	#enqueuePendingBatch() {
+		if (this.#pendingBatch.length === 0) return;
+		const batch = this.#pendingBatch;
+		const seq = this.#nextSeq;
+		this.#pendingBatch = [];
+		this.#batchBytes = 0;
+		this.#nextSeq++;
+		if (this.#autoClaim && !this.#epochClaimed && this.#queue.length() > 0) this.#queue.drained().then(() => {
+			this.#queue.push({
+				batch,
+				seq
+			}).catch(() => {});
 		});
+		else this.#queue.push({
+			batch,
+			seq
+		}).catch(() => {});
 	}
 	/**
-	* Batch worker - processes batches of messages.
+	* Batch worker - processes batches via fastq.
 	*/
-	async #batchWorker(batch) {
+	async #batchWorker(task) {
+		const { batch, seq } = task;
+		const epoch = this.#epoch;
 		try {
-			await this.#sendBatch(batch);
-			for (const msg of batch) msg.resolve();
-			if (this.#buffer.length > 0) {
-				const nextBatch = this.#buffer.splice(0);
-				this.#queue.push(nextBatch).catch((err) => {
-					for (const msg of nextBatch) msg.reject(err);
-				});
-			}
+			await this.#doSendBatch(batch, seq, epoch);
+			if (!this.#epochClaimed) this.#epochClaimed = true;
+			this.#signalSeqComplete(epoch, seq, void 0);
 		} catch (error) {
-			for (const msg of batch) msg.reject(error);
-			for (const msg of this.#buffer) msg.reject(error);
-			this.#buffer = [];
+			this.#signalSeqComplete(epoch, seq, error);
+			if (this.#onError) this.#onError(error);
 			throw error;
 		}
 	}
 	/**
-	* Send a batch of messages as a single POST request.
+	* Signal that a sequence has completed (success or failure).
 	*/
-	async #sendBatch(batch) {
-		if (batch.length === 0) return;
-		const { requestHeaders, fetchUrl } = await this.#buildRequest();
-		const contentType = batch[0]?.contentType ?? this.#options.contentType ?? this.contentType;
-		if (contentType) requestHeaders[`content-type`] = contentType;
-		let highestSeq;
-		for (let i = batch.length - 1; i >= 0; i--) if (batch[i].seq !== void 0) {
-			highestSeq = batch[i].seq;
-			break;
+	#signalSeqComplete(epoch, seq, error) {
+		let epochMap = this.#seqState.get(epoch);
+		if (!epochMap) {
+			epochMap = new Map();
+			this.#seqState.set(epoch, epochMap);
 		}
-		if (highestSeq) requestHeaders[STREAM_SEQ_HEADER] = highestSeq;
+		const state = epochMap.get(seq);
+		if (state) {
+			state.resolved = true;
+			state.error = error;
+			for (const waiter of state.waiters) waiter(error);
+			state.waiters = [];
+		} else epochMap.set(seq, {
+			resolved: true,
+			error,
+			waiters: []
+		});
+		const cleanupThreshold = seq - this.#maxInFlight * 3;
+		if (cleanupThreshold > 0) {
+			for (const oldSeq of epochMap.keys()) if (oldSeq < cleanupThreshold) epochMap.delete(oldSeq);
+		}
+	}
+	/**
+	* Wait for a specific sequence to complete.
+	* Returns immediately if already completed.
+	* Throws if the sequence failed.
+	*/
+	#waitForSeq(epoch, seq) {
+		let epochMap = this.#seqState.get(epoch);
+		if (!epochMap) {
+			epochMap = new Map();
+			this.#seqState.set(epoch, epochMap);
+		}
+		const state = epochMap.get(seq);
+		if (state?.resolved) {
+			if (state.error) return Promise.reject(state.error);
+			return Promise.resolve();
+		}
+		return new Promise((resolve, reject) => {
+			const waiter = (err) => {
+				if (err) reject(err);
+				else resolve();
+			};
+			if (state) state.waiters.push(waiter);
+			else epochMap.set(seq, {
+				resolved: false,
+				waiters: [waiter]
+			});
+		});
+	}
+	/**
+	* Actually send the batch to the server.
+	* Handles auto-claim retry on 403 (stale epoch) if autoClaim is enabled.
+	* Does NOT implement general retry/backoff for network errors or 5xx responses.
+	*/
+	async #doSendBatch(batch, seq, epoch) {
+		const contentType = this.#stream.contentType ?? `application/octet-stream`;
 		const isJson = normalizeContentType$1(contentType) === `application/json`;
 		let batchedBody;
 		if (isJson) {
-			const values = batch.map((m) => m.data);
-			batchedBody = JSON.stringify(values);
+			const jsonStrings = batch.map((e) => new TextDecoder().decode(e.body));
+			batchedBody = `[${jsonStrings.join(`,`)}]`;
 		} else {
-			const totalSize = batch.reduce((sum, m) => {
-				const size = typeof m.data === `string` ? new TextEncoder().encode(m.data).length : m.data.length;
-				return sum + size;
-			}, 0);
+			const totalSize = batch.reduce((sum, e) => sum + e.body.length, 0);
 			const concatenated = new Uint8Array(totalSize);
 			let offset = 0;
-			for (const msg of batch) {
-				const bytes = typeof msg.data === `string` ? new TextEncoder().encode(msg.data) : msg.data;
-				concatenated.set(bytes, offset);
-				offset += bytes.length;
+			for (const entry of batch) {
+				concatenated.set(entry.body, offset);
+				offset += entry.body.length;
 			}
 			batchedBody = concatenated;
 		}
-		const signals = [];
-		if (this.#options.signal) signals.push(this.#options.signal);
-		for (const msg of batch) if (msg.signal) signals.push(msg.signal);
-		const combinedSignal = signals.length > 0 ? AbortSignal.any(signals) : void 0;
-		const response = await this.#fetchClient(fetchUrl.toString(), {
+		const url = this.#stream.url;
+		const headers = {
+			"content-type": contentType,
+			[PRODUCER_ID_HEADER]: this.#producerId,
+			[PRODUCER_EPOCH_HEADER]: epoch.toString(),
+			[PRODUCER_SEQ_HEADER]: seq.toString()
+		};
+		const response = await this.#fetchClient(url, {
 			method: `POST`,
-			headers: requestHeaders,
+			headers,
 			body: batchedBody,
-			signal: combinedSignal
+			signal: this.#signal
 		});
-		if (!response.ok) await handleErrorResponse(response, this.url);
-	}
-	/**
-	* 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!);
-	* ```
-	*/
-	async appendStream(source, opts) {
-		const { requestHeaders, fetchUrl } = await this.#buildRequest();
-		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
-		if (contentType) requestHeaders[`content-type`] = contentType;
-		if (opts?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
-		const body = toReadableStream(source);
-		const response = await this.#fetchClient(fetchUrl.toString(), {
-			method: `POST`,
-			headers: requestHeaders,
-			body,
-			duplex: `half`,
-			signal: opts?.signal ?? this.#options.signal
-		});
-		if (!response.ok) await handleErrorResponse(response, this.url);
-	}
-	/**
-	* 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) {
-		const chunks = [];
-		const stream$1 = this;
-		return new WritableStream({
-			write(chunk) {
-				chunks.push(chunk);
-			},
-			async close() {
-				if (chunks.length > 0) {
-					const readable = new ReadableStream({ start(controller) {
-						for (const chunk of chunks) controller.enqueue(chunk);
-						controller.close();
-					} });
-					await stream$1.appendStream(readable, opts);
-				}
-			},
-			abort(reason) {
-				console.error(`WritableStream aborted:`, reason);
+		if (response.status === 204) return {
+			offset: ``,
+			duplicate: true
+		};
+		if (response.status === 200) {
+			const resultOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+			return {
+				offset: resultOffset,
+				duplicate: false
+			};
+		}
+		if (response.status === 403) {
+			const currentEpochStr = response.headers.get(PRODUCER_EPOCH_HEADER);
+			const currentEpoch = currentEpochStr ? parseInt(currentEpochStr, 10) : epoch;
+			if (this.#autoClaim) {
+				const newEpoch = currentEpoch + 1;
+				this.#epoch = newEpoch;
+				this.#nextSeq = 1;
+				return this.#doSendBatch(batch, 0, newEpoch);
 			}
-		});
-	}
-	/**
-	* 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);
-	*   }
-	* });
-	* ```
-	*/
-	async stream(options) {
-		if (options?.live === `sse` && this.contentType) {
-			const isSSECompatible = SSE_COMPATIBLE_CONTENT_TYPES.some((prefix) => this.contentType.startsWith(prefix));
-			if (!isSSECompatible) throw new DurableStreamError(`SSE is not supported for content-type: ${this.contentType}`, `SSE_NOT_SUPPORTED`, 400);
+			throw new StaleEpochError(currentEpoch);
 		}
-		const mergedHeaders = {
-			...this.#options.headers,
-			...options?.headers
-		};
-		const mergedParams = {
-			...this.#options.params,
-			...options?.params
-		};
-		return stream({
-			url: this.url,
-			headers: mergedHeaders,
-			params: mergedParams,
-			signal: options?.signal ?? this.#options.signal,
-			fetch: this.#options.fetch,
-			backoffOptions: this.#options.backoffOptions,
-			offset: options?.offset,
-			live: options?.live,
-			json: options?.json,
-			onError: options?.onError ?? this.#onError,
-			warnOnHttp: options?.warnOnHttp ?? this.#options.warnOnHttp
-		});
+		if (response.status === 409) {
+			const expectedSeqStr = response.headers.get(PRODUCER_EXPECTED_SEQ_HEADER);
+			const expectedSeq = expectedSeqStr ? parseInt(expectedSeqStr, 10) : 0;
+			if (expectedSeq < seq) {
+				const waitPromises = [];
+				for (let s = expectedSeq; s < seq; s++) waitPromises.push(this.#waitForSeq(epoch, s));
+				await Promise.all(waitPromises);
+				return this.#doSendBatch(batch, seq, epoch);
+			}
+			const receivedSeqStr = response.headers.get(PRODUCER_RECEIVED_SEQ_HEADER);
+			const receivedSeq = receivedSeqStr ? parseInt(receivedSeqStr, 10) : seq;
+			throw new SequenceGapError(expectedSeq, receivedSeq);
+		}
+		if (response.status === 400) {
+			const error$1 = await DurableStreamError.fromResponse(response, url);
+			throw error$1;
+		}
+		const error = await FetchError.fromResponse(response, url);
+		throw error;
 	}
 	/**
-	* Build request headers and URL.
+	* Clear pending batch and report error.
 	*/
-	async #buildRequest() {
-		const requestHeaders = await resolveHeaders(this.#options.headers);
-		const fetchUrl = new URL(this.url);
-		const params = await resolveParams(this.#options.params);
-		for (const [key, value] of Object.entries(params)) fetchUrl.searchParams.set(key, value);
-		return {
-			requestHeaders,
-			fetchUrl
-		};
+	#rejectPendingBatch(error) {
+		if (this.#onError && this.#pendingBatch.length > 0) this.#onError(error);
+		this.#pendingBatch = [];
+		this.#batchBytes = 0;
+		if (this.#lingerTimeout) {
+			clearTimeout(this.#lingerTimeout);
+			this.#lingerTimeout = null;
+		}
 	}
 };
-/**
-* Encode a body value to the appropriate format.
-* Strings are encoded as UTF-8.
-* Objects are JSON-serialized.
-*/
-function encodeBody(body) {
-	if (body === void 0) return void 0;
-	if (typeof body === `string`) return new TextEncoder().encode(body);
-	if (body instanceof Uint8Array) return body;
-	if (body instanceof Blob || body instanceof FormData || body instanceof ReadableStream || body instanceof ArrayBuffer || ArrayBuffer.isView(body)) return body;
-	return new TextEncoder().encode(JSON.stringify(body));
-}
-/**
-* Convert an async iterable to a ReadableStream.
-*/
-function toReadableStream(source) {
-	if (source instanceof ReadableStream) return source.pipeThrough(new TransformStream({ transform(chunk, controller) {
-		if (typeof chunk === `string`) controller.enqueue(new TextEncoder().encode(chunk));
-		else controller.enqueue(chunk);
-	} }));
-	const encoder = new TextEncoder();
-	const iterator = source[Symbol.asyncIterator]();
-	return new ReadableStream({
-		async pull(controller) {
-			try {
-				const { done, value } = await iterator.next();
-				if (done) controller.close();
-				else if (typeof value === `string`) controller.enqueue(encoder.encode(value));
-				else controller.enqueue(value);
-			} catch (e) {
-				controller.error(e);
-			}
-		},
-		cancel() {
-			iterator.return?.();
-		}
-	});
-}
-/**
-* Validate stream options.
-*/
-function validateOptions(options) {
-	if (!options.url) throw new MissingStreamUrlError();
-	if (options.signal && !(options.signal instanceof AbortSignal)) throw new InvalidSignalError();
-	warnIfUsingHttpInBrowser(options.url, options.warnOnHttp);
-}
 
 //#endregion
-//#region src/idempotent-producer.ts
-/**
-* Error thrown when a producer's epoch is stale (zombie fencing).
-*/
-var StaleEpochError = class extends Error {
-	/**
-	* The current epoch on the server.
-	*/
-	currentEpoch;
-	constructor(currentEpoch) {
-		super(`Producer epoch is stale. Current server epoch: ${currentEpoch}. Call restart() or create a new producer with a higher epoch.`);
-		this.name = `StaleEpochError`;
-		this.currentEpoch = currentEpoch;
-	}
-};
-/**
-* Error thrown when an unrecoverable sequence gap is detected.
-*
-* With maxInFlight > 1, HTTP requests can arrive out of order at the server,
-* causing temporary 409 responses. The client automatically handles these
-* by waiting for earlier sequences to complete, then retrying.
-*
-* This error is only thrown when the gap cannot be resolved (e.g., the
-* expected sequence is >= our sequence, indicating a true protocol violation).
-*/
-var SequenceGapError = class extends Error {
-	expectedSeq;
-	receivedSeq;
-	constructor(expectedSeq, receivedSeq) {
-		super(`Producer sequence gap: expected ${expectedSeq}, received ${receivedSeq}`);
-		this.name = `SequenceGapError`;
-		this.expectedSeq = expectedSeq;
-		this.receivedSeq = receivedSeq;
-	}
-};
+//#region src/stream.ts
 /**
 * Normalize content-type by extracting the media type (before any semicolon).
+* Handles cases like "application/json; charset=utf-8".
 */
 function normalizeContentType(contentType) {
 	if (!contentType) return ``;
 	return contentType.split(`;`)[0].trim().toLowerCase();
 }
 /**
-* An idempotent producer for exactly-once writes to a durable stream.
+* Check if a value is a Promise or Promise-like (thenable).
+*/
+function isPromiseLike(value) {
+	return value != null && typeof value.then === `function`;
+}
+/**
+* A handle to a remote durable stream for read/write operations.
 *
-* Features:
-* - Fire-and-forget: append() returns immediately, batches in background
-* - Exactly-once: server deduplicates using (producerId, epoch, seq)
-* - Batching: multiple appends batched into single HTTP request
-* - Pipelining: up to maxInFlight concurrent batches
-* - Zombie fencing: stale producers rejected via epoch validation
+* 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
-* const stream = new DurableStream({ url: "https://..." });
-* const producer = new IdempotentProducer(stream, "order-service-1", {
-*   epoch: 0,
-*   autoClaim: true,
+* // Create a new stream
+* const stream = await DurableStream.create({
+*   url: "https://streams.example.com/my-stream",
+*   headers: { Authorization: "Bearer my-token" },
+*   contentType: "application/json"
 * });
 *
-* // Fire-and-forget writes (synchronous, returns immediately)
-* producer.append("message 1");
-* producer.append("message 2");
+* // Write data
+* await stream.append(JSON.stringify({ message: "hello" }));
 *
-* // Ensure all messages are delivered before shutdown
-* await producer.flush();
-* await producer.close();
+* // 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);
+*   }
+* });
 * ```
 */
-var IdempotentProducer = class {
-	#stream;
-	#producerId;
-	#epoch;
-	#nextSeq = 0;
-	#autoClaim;
-	#maxBatchBytes;
-	#lingerMs;
+var DurableStream = class DurableStream {
+	/**
+	* The URL of the durable stream.
+	*/
+	url;
+	/**
+	* The content type of the stream (populated after connect/head/read).
+	*/
+	contentType;
+	#options;
 	#fetchClient;
-	#signal;
 	#onError;
-	#pendingBatch = [];
-	#batchBytes = 0;
-	#lingerTimeout = null;
+	#batchingEnabled;
 	#queue;
-	#maxInFlight;
-	#closed = false;
-	#epochClaimed;
-	#seqState = new Map();
+	#buffer = [];
 	/**
-	* Create an idempotent producer for a stream.
-	*
-	* @param stream - The DurableStream to write to
-	* @param producerId - Stable identifier for this producer (e.g., "order-service-1")
-	* @param opts - Producer options
+	* Create a cold handle to a stream.
+	* No network IO is performed by the constructor.
 	*/
-	constructor(stream$1, producerId, opts) {
-		this.#stream = stream$1;
-		this.#producerId = producerId;
-		this.#epoch = opts?.epoch ?? 0;
-		this.#autoClaim = opts?.autoClaim ?? false;
-		this.#maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024;
-		this.#lingerMs = opts?.lingerMs ?? 5;
-		this.#signal = opts?.signal;
-		this.#onError = opts?.onError;
-		this.#fetchClient = opts?.fetch ?? ((...args) => fetch(...args));
-		this.#maxInFlight = opts?.maxInFlight ?? 5;
-		this.#epochClaimed = !this.#autoClaim;
-		this.#queue = fastq.default.promise(this.#batchWorker.bind(this), this.#maxInFlight);
-		if (this.#signal) this.#signal.addEventListener(`abort`, () => {
-			this.#rejectPendingBatch(new DurableStreamError(`Producer aborted`, `ALREADY_CLOSED`, void 0, void 0));
-		}, { once: true });
+	constructor(opts) {
+		validateOptions(opts);
+		const urlStr = opts.url instanceof URL ? opts.url.toString() : opts.url;
+		this.url = urlStr;
+		this.#options = {
+			...opts,
+			url: urlStr
+		};
+		this.#onError = opts.onError;
+		if (opts.contentType) this.contentType = opts.contentType;
+		this.#batchingEnabled = opts.batching !== false;
+		if (this.#batchingEnabled) this.#queue = fastq.default.promise(this.#batchWorker.bind(this), 1);
+		const baseFetchClient = opts.fetch ?? ((...args) => fetch(...args));
+		const backOffOpts = { ...opts.backoffOptions ?? BackoffDefaults };
+		const fetchWithBackoffClient = createFetchWithBackoff(baseFetchClient, backOffOpts);
+		this.#fetchClient = createFetchWithConsumedBody(fetchWithBackoffClient);
 	}
 	/**
-	* Append data to the stream.
-	*
-	* This is fire-and-forget: returns immediately after adding to the batch.
-	* The message is batched and sent when:
-	* - maxBatchBytes is reached
-	* - lingerMs elapses
-	* - flush() is called
-	*
-	* Errors are reported via onError callback if configured. Use flush() to
-	* wait for all pending messages to be sent.
-	*
-	* For JSON streams, pass native objects (which will be serialized internally).
-	* For byte streams, pass string or Uint8Array.
-	*
-	* @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
+	* Create a new stream (create-only PUT) and return a handle.
+	* Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
 	*/
-	append(body) {
-		if (this.#closed) throw new DurableStreamError(`Producer is closed`, `ALREADY_CLOSED`, void 0, void 0);
-		const isJson = normalizeContentType(this.#stream.contentType) === `application/json`;
-		let bytes;
-		let data;
-		if (isJson) {
-			const json = JSON.stringify(body);
-			bytes = new TextEncoder().encode(json);
-			data = body;
-		} else {
-			if (typeof body === `string`) bytes = new TextEncoder().encode(body);
-			else if (body instanceof Uint8Array) bytes = body;
-			else throw new DurableStreamError(`Non-JSON streams require string or Uint8Array`, `BAD_REQUEST`, 400, void 0);
-			data = bytes;
-		}
-		this.#pendingBatch.push({
-			data,
-			body: bytes
+	static async create(opts) {
+		const stream$1 = new DurableStream(opts);
+		await stream$1.create({
+			contentType: opts.contentType,
+			ttlSeconds: opts.ttlSeconds,
+			expiresAt: opts.expiresAt,
+			body: opts.body
 		});
-		this.#batchBytes += bytes.length;
-		if (this.#batchBytes >= this.#maxBatchBytes) this.#enqueuePendingBatch();
-		else if (!this.#lingerTimeout) this.#lingerTimeout = setTimeout(() => {
-			this.#lingerTimeout = null;
-			if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
-		}, this.#lingerMs);
+		return stream$1;
 	}
 	/**
-	* Send any pending batch immediately and wait for all in-flight batches.
+	* Validate that a stream exists and fetch metadata via HEAD.
+	* Returns a handle with contentType populated (if sent by server).
 	*
-	* Call this before shutdown to ensure all messages are delivered.
+	* **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
+	* ```
 	*/
-	async flush() {
-		if (this.#lingerTimeout) {
-			clearTimeout(this.#lingerTimeout);
-			this.#lingerTimeout = null;
-		}
-		if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
-		await this.#queue.drained();
+	static async connect(opts) {
+		const stream$1 = new DurableStream(opts);
+		await stream$1.head();
+		return stream$1;
+	}
+	/**
+	* HEAD metadata for a stream without creating a handle.
+	*/
+	static async head(opts) {
+		const stream$1 = new DurableStream(opts);
+		return stream$1.head();
 	}
 	/**
-	* Flush pending messages and close the producer.
-	*
-	* After calling close(), further append() calls will throw.
+	* Delete a stream without creating a handle.
 	*/
-	async close() {
-		if (this.#closed) return;
-		this.#closed = true;
-		try {
-			await this.flush();
-		} catch {}
+	static async delete(opts) {
+		const stream$1 = new DurableStream(opts);
+		return stream$1.delete();
 	}
 	/**
-	* Increment epoch and reset sequence.
-	*
-	* Call this when restarting the producer to establish a new session.
-	* Flushes any pending messages first.
+	* HEAD metadata for this stream.
 	*/
-	async restart() {
-		await this.flush();
-		this.#epoch++;
-		this.#nextSeq = 0;
+	async head(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `HEAD`,
+			headers: requestHeaders,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
+		const contentType = response.headers.get(`content-type`) ?? void 0;
+		const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
+		const etag = response.headers.get(`etag`) ?? void 0;
+		const cacheControl = response.headers.get(`cache-control`) ?? void 0;
+		if (contentType) this.contentType = contentType;
+		return {
+			exists: true,
+			contentType,
+			offset,
+			etag,
+			cacheControl
+		};
 	}
 	/**
-	* Current epoch for this producer.
+	* Create this stream (create-only PUT) using the URL/auth from the handle.
 	*/
-	get epoch() {
-		return this.#epoch;
+	async create(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		if (opts?.ttlSeconds !== void 0) requestHeaders[STREAM_TTL_HEADER] = String(opts.ttlSeconds);
+		if (opts?.expiresAt) requestHeaders[STREAM_EXPIRES_AT_HEADER] = opts.expiresAt;
+		const body = encodeBody(opts?.body);
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `PUT`,
+			headers: requestHeaders,
+			body,
+			signal: this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url, { operation: `create` });
+		const responseContentType = response.headers.get(`content-type`);
+		if (responseContentType) this.contentType = responseContentType;
+		else if (contentType) this.contentType = contentType;
+		return this;
 	}
 	/**
-	* Next sequence number to be assigned.
+	* Delete this stream.
 	*/
-	get nextSeq() {
-		return this.#nextSeq;
+	async delete(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `DELETE`,
+			headers: requestHeaders,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
 	}
 	/**
-	* Number of messages in the current pending batch.
+	* 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` must be string or Uint8Array.
+	* - For JSON streams, pass pre-serialized JSON strings.
+	* - `body` may also be a Promise that resolves to string or Uint8Array.
+	* - Strings are encoded as UTF-8.
+	* - `seq` (if provided) is sent as stream-seq (writer coordination).
+	*
+	* @example
+	* ```typescript
+	* // JSON stream - pass pre-serialized JSON
+	* await stream.append(JSON.stringify({ message: "hello" }));
+	*
+	* // Byte stream
+	* await stream.append("raw text data");
+	* await stream.append(new Uint8Array([1, 2, 3]));
+	*
+	* // Promise value - awaited before buffering
+	* await stream.append(fetchData());
+	* ```
 	*/
-	get pendingCount() {
-		return this.#pendingBatch.length;
+	async append(body, opts) {
+		const resolvedBody = isPromiseLike(body) ? await body : body;
+		if (this.#batchingEnabled && this.#queue) return this.#appendWithBatching(resolvedBody, opts);
+		return this.#appendDirect(resolvedBody, opts);
 	}
 	/**
-	* Number of batches currently in flight.
+	* Direct append without batching (used when batching is disabled).
 	*/
-	get inFlightCount() {
-		return this.#queue.length();
+	async #appendDirect(body, opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		if (opts?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
+		const isJson = normalizeContentType(contentType) === `application/json`;
+		const bodyStr = typeof body === `string` ? body : new TextDecoder().decode(body);
+		const encodedBody = isJson ? `[${bodyStr}]` : bodyStr;
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body: encodedBody,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
 	}
 	/**
-	* Enqueue the current pending batch for processing.
+	* Append with batching - buffers messages and sends them in batches.
 	*/
-	#enqueuePendingBatch() {
-		if (this.#pendingBatch.length === 0) return;
-		const batch = this.#pendingBatch;
-		const seq = this.#nextSeq;
-		this.#pendingBatch = [];
-		this.#batchBytes = 0;
-		this.#nextSeq++;
-		if (this.#autoClaim && !this.#epochClaimed && this.#queue.length() > 0) this.#queue.drained().then(() => {
-			this.#queue.push({
-				batch,
-				seq
-			}).catch(() => {});
+	async #appendWithBatching(body, opts) {
+		return new Promise((resolve, reject) => {
+			this.#buffer.push({
+				data: body,
+				seq: opts?.seq,
+				contentType: opts?.contentType,
+				signal: opts?.signal,
+				resolve,
+				reject
+			});
+			if (this.#queue.idle()) {
+				const batch = this.#buffer.splice(0);
+				this.#queue.push(batch).catch((err) => {
+					for (const msg of batch) msg.reject(err);
+				});
+			}
 		});
-		else this.#queue.push({
-			batch,
-			seq
-		}).catch(() => {});
 	}
 	/**
-	* Batch worker - processes batches via fastq.
+	* Batch worker - processes batches of messages.
 	*/
-	async #batchWorker(task) {
-		const { batch, seq } = task;
-		const epoch = this.#epoch;
+	async #batchWorker(batch) {
 		try {
-			await this.#doSendBatch(batch, seq, epoch);
-			if (!this.#epochClaimed) this.#epochClaimed = true;
-			this.#signalSeqComplete(epoch, seq, void 0);
+			await this.#sendBatch(batch);
+			for (const msg of batch) msg.resolve();
+			if (this.#buffer.length > 0) {
+				const nextBatch = this.#buffer.splice(0);
+				this.#queue.push(nextBatch).catch((err) => {
+					for (const msg of nextBatch) msg.reject(err);
+				});
+			}
 		} catch (error) {
-			this.#signalSeqComplete(epoch, seq, error);
-			if (this.#onError) this.#onError(error);
+			for (const msg of batch) msg.reject(error);
+			for (const msg of this.#buffer) msg.reject(error);
+			this.#buffer = [];
 			throw error;
 		}
 	}
 	/**
-	* Signal that a sequence has completed (success or failure).
+	* Send a batch of messages as a single POST request.
 	*/
-	#signalSeqComplete(epoch, seq, error) {
-		let epochMap = this.#seqState.get(epoch);
-		if (!epochMap) {
-			epochMap = new Map();
-			this.#seqState.set(epoch, epochMap);
+	async #sendBatch(batch) {
+		if (batch.length === 0) return;
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = batch[0]?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		let highestSeq;
+		for (let i = batch.length - 1; i >= 0; i--) if (batch[i].seq !== void 0) {
+			highestSeq = batch[i].seq;
+			break;
 		}
-		const state = epochMap.get(seq);
-		if (state) {
-			state.resolved = true;
-			state.error = error;
-			for (const waiter of state.waiters) waiter(error);
-			state.waiters = [];
-		} else epochMap.set(seq, {
-			resolved: true,
-			error,
-			waiters: []
+		if (highestSeq) requestHeaders[STREAM_SEQ_HEADER] = highestSeq;
+		const isJson = normalizeContentType(contentType) === `application/json`;
+		let batchedBody;
+		if (isJson) {
+			const jsonStrings = batch.map((m) => typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data));
+			batchedBody = `[${jsonStrings.join(`,`)}]`;
+		} else {
+			const strings = batch.map((m) => typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data));
+			batchedBody = strings.join(``);
+		}
+		const signals = [];
+		if (this.#options.signal) signals.push(this.#options.signal);
+		for (const msg of batch) if (msg.signal) signals.push(msg.signal);
+		const combinedSignal = signals.length > 0 ? AbortSignal.any(signals) : void 0;
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body: batchedBody,
+			signal: combinedSignal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
+	}
+	/**
+	* 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!);
+	* ```
+	*/
+	async appendStream(source, opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		if (opts?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
+		const body = toReadableStream(source);
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body,
+			duplex: `half`,
+			signal: opts?.signal ?? this.#options.signal
 		});
-		const cleanupThreshold = seq - this.#maxInFlight * 3;
-		if (cleanupThreshold > 0) {
-			for (const oldSeq of epochMap.keys()) if (oldSeq < cleanupThreshold) epochMap.delete(oldSeq);
-		}
+		if (!response.ok) await handleErrorResponse(response, this.url);
 	}
 	/**
-	* Wait for a specific sequence to complete.
-	* Returns immediately if already completed.
-	* Throws if the sequence failed.
+	* 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.
+	*
+	* Uses IdempotentProducer internally for:
+	* - Automatic batching (controlled by lingerMs, maxBatchBytes)
+	* - Exactly-once delivery semantics
+	* - Streaming writes (doesn't buffer entire content in memory)
+	*
+	* @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());
+	*
+	* // With custom producer options
+	* await source.pipeTo(stream.writable({
+	*   producerId: "my-producer",
+	*   lingerMs: 10,
+	*   maxBatchBytes: 64 * 1024,
+	* }));
+	* ```
 	*/
-	#waitForSeq(epoch, seq) {
-		let epochMap = this.#seqState.get(epoch);
-		if (!epochMap) {
-			epochMap = new Map();
-			this.#seqState.set(epoch, epochMap);
-		}
-		const state = epochMap.get(seq);
-		if (state?.resolved) {
-			if (state.error) return Promise.reject(state.error);
-			return Promise.resolve();
-		}
-		return new Promise((resolve, reject) => {
-			const waiter = (err) => {
-				if (err) reject(err);
-				else resolve();
-			};
-			if (state) state.waiters.push(waiter);
-			else epochMap.set(seq, {
-				resolved: false,
-				waiters: [waiter]
-			});
+	writable(opts) {
+		const producerId = opts?.producerId ?? `writable-${crypto.randomUUID().slice(0, 8)}`;
+		let writeError = null;
+		const producer = new IdempotentProducer(this, producerId, {
+			autoClaim: true,
+			lingerMs: opts?.lingerMs,
+			maxBatchBytes: opts?.maxBatchBytes,
+			onError: (error) => {
+				if (!writeError) writeError = error;
+				opts?.onError?.(error);
+			},
+			signal: opts?.signal ?? this.#options.signal
+		});
+		return new WritableStream({
+			write(chunk) {
+				producer.append(chunk);
+			},
+			async close() {
+				await producer.flush();
+				await producer.close();
+				if (writeError) throw writeError;
+			},
+			abort(_reason) {
+				producer.close().catch((err) => {
+					opts?.onError?.(err);
+				});
+			}
 		});
 	}
 	/**
-	* Actually send the batch to the server.
-	* Handles auto-claim retry on 403 (stale epoch) if autoClaim is enabled.
-	* Does NOT implement general retry/backoff for network errors or 5xx responses.
+	* 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);
+	*   }
+	* });
+	* ```
 	*/
-	async #doSendBatch(batch, seq, epoch) {
-		const contentType = this.#stream.contentType ?? `application/octet-stream`;
-		const isJson = normalizeContentType(contentType) === `application/json`;
-		let batchedBody;
-		if (isJson) {
-			const values = batch.map((e) => e.data);
-			batchedBody = JSON.stringify(values);
-		} else {
-			const totalSize = batch.reduce((sum, e) => sum + e.body.length, 0);
-			const concatenated = new Uint8Array(totalSize);
-			let offset = 0;
-			for (const entry of batch) {
-				concatenated.set(entry.body, offset);
-				offset += entry.body.length;
-			}
-			batchedBody = concatenated;
+	async stream(options) {
+		if (options?.live === `sse` && this.contentType) {
+			const isSSECompatible = SSE_COMPATIBLE_CONTENT_TYPES.some((prefix) => this.contentType.startsWith(prefix));
+			if (!isSSECompatible) throw new DurableStreamError(`SSE is not supported for content-type: ${this.contentType}`, `SSE_NOT_SUPPORTED`, 400);
 		}
-		const url = this.#stream.url;
-		const headers = {
-			"content-type": contentType,
-			[PRODUCER_ID_HEADER]: this.#producerId,
-			[PRODUCER_EPOCH_HEADER]: epoch.toString(),
-			[PRODUCER_SEQ_HEADER]: seq.toString()
+		const mergedHeaders = {
+			...this.#options.headers,
+			...options?.headers
 		};
-		const response = await this.#fetchClient(url, {
-			method: `POST`,
-			headers,
-			body: batchedBody,
-			signal: this.#signal
-		});
-		if (response.status === 204) return {
-			offset: ``,
-			duplicate: true
+		const mergedParams = {
+			...this.#options.params,
+			...options?.params
 		};
-		if (response.status === 200) {
-			const resultOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
-			return {
-				offset: resultOffset,
-				duplicate: false
-			};
-		}
-		if (response.status === 403) {
-			const currentEpochStr = response.headers.get(PRODUCER_EPOCH_HEADER);
-			const currentEpoch = currentEpochStr ? parseInt(currentEpochStr, 10) : epoch;
-			if (this.#autoClaim) {
-				const newEpoch = currentEpoch + 1;
-				this.#epoch = newEpoch;
-				this.#nextSeq = 1;
-				return this.#doSendBatch(batch, 0, newEpoch);
-			}
-			throw new StaleEpochError(currentEpoch);
-		}
-		if (response.status === 409) {
-			const expectedSeqStr = response.headers.get(PRODUCER_EXPECTED_SEQ_HEADER);
-			const expectedSeq = expectedSeqStr ? parseInt(expectedSeqStr, 10) : 0;
-			if (expectedSeq < seq) {
-				const waitPromises = [];
-				for (let s = expectedSeq; s < seq; s++) waitPromises.push(this.#waitForSeq(epoch, s));
-				await Promise.all(waitPromises);
-				return this.#doSendBatch(batch, seq, epoch);
-			}
-			const receivedSeqStr = response.headers.get(PRODUCER_RECEIVED_SEQ_HEADER);
-			const receivedSeq = receivedSeqStr ? parseInt(receivedSeqStr, 10) : seq;
-			throw new SequenceGapError(expectedSeq, receivedSeq);
-		}
-		if (response.status === 400) {
-			const error$1 = await DurableStreamError.fromResponse(response, url);
-			throw error$1;
-		}
-		const error = await FetchError.fromResponse(response, url);
-		throw error;
+		return stream({
+			url: this.url,
+			headers: mergedHeaders,
+			params: mergedParams,
+			signal: options?.signal ?? this.#options.signal,
+			fetch: this.#options.fetch,
+			backoffOptions: this.#options.backoffOptions,
+			offset: options?.offset,
+			live: options?.live,
+			json: options?.json,
+			onError: options?.onError ?? this.#onError,
+			warnOnHttp: options?.warnOnHttp ?? this.#options.warnOnHttp
+		});
 	}
 	/**
-	* Clear pending batch and report error.
+	* Build request headers and URL.
 	*/
-	#rejectPendingBatch(error) {
-		if (this.#onError && this.#pendingBatch.length > 0) this.#onError(error);
-		this.#pendingBatch = [];
-		this.#batchBytes = 0;
-		if (this.#lingerTimeout) {
-			clearTimeout(this.#lingerTimeout);
-			this.#lingerTimeout = null;
-		}
+	async #buildRequest() {
+		const requestHeaders = await resolveHeaders(this.#options.headers);
+		const fetchUrl = new URL(this.url);
+		const params = await resolveParams(this.#options.params);
+		for (const [key, value] of Object.entries(params)) fetchUrl.searchParams.set(key, value);
+		return {
+			requestHeaders,
+			fetchUrl
+		};
 	}
 };
+/**
+* Encode a body value to the appropriate format.
+* Strings are encoded as UTF-8.
+* Objects are JSON-serialized.
+*/
+function encodeBody(body) {
+	if (body === void 0) return void 0;
+	if (typeof body === `string`) return new TextEncoder().encode(body);
+	if (body instanceof Uint8Array) return body;
+	if (body instanceof Blob || body instanceof FormData || body instanceof ReadableStream || body instanceof ArrayBuffer || ArrayBuffer.isView(body)) return body;
+	return new TextEncoder().encode(JSON.stringify(body));
+}
+/**
+* Convert an async iterable to a ReadableStream.
+*/
+function toReadableStream(source) {
+	if (source instanceof ReadableStream) return source.pipeThrough(new TransformStream({ transform(chunk, controller) {
+		if (typeof chunk === `string`) controller.enqueue(new TextEncoder().encode(chunk));
+		else controller.enqueue(chunk);
+	} }));
+	const encoder = new TextEncoder();
+	const iterator = source[Symbol.asyncIterator]();
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const { done, value } = await iterator.next();
+				if (done) controller.close();
+				else if (typeof value === `string`) controller.enqueue(encoder.encode(value));
+				else controller.enqueue(value);
+			} catch (e) {
+				controller.error(e);
+			}
+		},
+		cancel() {
+			iterator.return?.();
+		}
+	});
+}
+/**
+* Validate stream options.
+*/
+function validateOptions(options) {
+	if (!options.url) throw new MissingStreamUrlError();
+	if (options.signal && !(options.signal instanceof AbortSignal)) throw new InvalidSignalError();
+	warnIfUsingHttpInBrowser(options.url, options.warnOnHttp);
+}
 
 //#endregion
 exports.BackoffDefaults = BackoffDefaults