@durable-streams/client 0.1.5 → 0.2.1

package/dist/index.js

@@ -22,6 +22,11 @@ const STREAM_CURSOR_HEADER = `Stream-Cursor`;
 */
 const STREAM_UP_TO_DATE_HEADER = `Stream-Up-To-Date`;
 /**
+* Response/request header indicating stream is closed (EOF).
+* When present with value "true", the stream is permanently closed.
+*/
+const STREAM_CLOSED_HEADER = `Stream-Closed`;
+/**
 * Request header for writer coordination sequence.
 * Monotonic, lexicographic. If lower than last appended seq -> 409 Conflict.
 */
@@ -70,8 +75,17 @@ const LIVE_QUERY_PARAM = `live`;
 */
 const CURSOR_QUERY_PARAM = `cursor`;
 /**
-* Content types that support SSE mode.
-* SSE is only valid for text/* or application/json streams.
+* Response header indicating SSE data encoding (e.g., base64 for binary streams).
+*/
+const STREAM_SSE_DATA_ENCODING_HEADER = `stream-sse-data-encoding`;
+/**
+* SSE control event field for stream closed state.
+* Note: Different from HTTP header name (camelCase vs Header-Case).
+*/
+const SSE_CLOSED_FIELD = `streamClosed`;
+/**
+* Content types that are natively compatible with SSE (UTF-8 text).
+* Binary content types are also supported via automatic base64 encoding.
 */
 const SSE_COMPATIBLE_CONTENT_TYPES = [`text/`, `application/json`];
 /**
@@ -201,6 +215,23 @@ var MissingStreamUrlError = class extends Error {
 	}
 };
 /**
+* Error thrown when attempting to append to a closed stream.
+*/
+var StreamClosedError = class extends DurableStreamError {
+	code = `STREAM_CLOSED`;
+	status = 409;
+	streamClosed = true;
+	/**
+	* The final offset of the stream, if available from the response.
+	*/
+	finalOffset;
+	constructor(url, finalOffset) {
+		super(`Cannot append to closed stream`, `STREAM_CLOSED`, 409, url);
+		this.name = `StreamClosedError`;
+		this.finalOffset = finalOffset;
+	}
+};
+/**
 * Error thrown when signal option is invalid.
 */
 var InvalidSignalError = class extends Error {
@@ -480,13 +511,19 @@ async function* parseSSEStream(stream$1, signal) {
 							type: `control`,
 							streamNextOffset: control.streamNextOffset,
 							streamCursor: control.streamCursor,
-							upToDate: control.upToDate
+							upToDate: control.upToDate,
+							streamClosed: control.streamClosed
 						};
-					} 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();
-			else if (line.startsWith(`data:`)) {
+			} else if (line.startsWith(`event:`)) {
+				const eventType = line.slice(6);
+				currentEvent.type = eventType.startsWith(` `) ? eventType.slice(1) : eventType;
+			} else if (line.startsWith(`data:`)) {
 				const content = line.slice(5);
 				currentEvent.data.push(content.startsWith(` `) ? content.slice(1) : content);
 			}
@@ -505,9 +542,13 @@ async function* parseSSEStream(stream$1, signal) {
 					type: `control`,
 					streamNextOffset: control.streamNextOffset,
 					streamCursor: control.streamCursor,
-					upToDate: control.upToDate
+					upToDate: control.upToDate,
+					streamClosed: control.streamClosed
 				};
-			} 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();
@@ -533,9 +574,10 @@ var StreamResponseImpl = class {
 	#statusText;
 	#ok;
 	#isLoading;
-	offset;
-	cursor;
-	upToDate;
+	#offset;
+	#cursor;
+	#upToDate;
+	#streamClosed;
 	#isJsonMode;
 	#abortController;
 	#fetchNext;
@@ -555,15 +597,17 @@ var StreamResponseImpl = class {
 	#lastSSEConnectionStartTime;
 	#consecutiveShortSSEConnections = 0;
 	#sseFallbackToLongPoll = false;
+	#encoding;
 	#responseStream;
 	constructor(config) {
 		this.url = config.url;
 		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.#streamClosed = config.initialStreamClosed;
 		this.#headers = config.firstResponse.headers;
 		this.#status = config.firstResponse.status;
 		this.#statusText = config.firstResponse.statusText;
@@ -580,6 +624,7 @@ var StreamResponseImpl = class {
 			backoffMaxDelay: config.sseResilience?.backoffMaxDelay ?? 5e3,
 			logWarnings: config.sseResilience?.logWarnings ?? true
 		};
+		this.#encoding = config.encoding;
 		this.#closed = new Promise((resolve, reject) => {
 			this.#closedResolve = resolve;
 			this.#closedReject = reject;
@@ -654,6 +699,18 @@ var StreamResponseImpl = class {
 	get isLoading() {
 		return this.#isLoading;
 	}
+	get offset() {
+		return this.#offset;
+	}
+	get cursor() {
+		return this.#cursor;
+	}
+	get upToDate() {
+		return this.#upToDate;
+	}
+	get streamClosed() {
+		return this.#streamClosed;
+	}
 	#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`);
 	}
@@ -675,11 +732,12 @@ var StreamResponseImpl = class {
 	}
 	/**
 	* Determine if we should continue with live updates based on live mode
-	* and whether we've received upToDate.
+	* and whether we've received upToDate or streamClosed.
 	*/
 	#shouldContinueLive() {
 		if (this.#stopAfterUpToDate && this.upToDate) return false;
 		if (this.live === false) return false;
+		if (this.#streamClosed) return false;
 		return true;
 	}
 	/**
@@ -687,10 +745,12 @@ 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);
+		const streamClosedHeader = response.headers.get(STREAM_CLOSED_HEADER);
+		if (streamClosedHeader?.toLowerCase() === `true`) this.#streamClosed = true;
 		this.#headers = response.headers;
 		this.#status = response.status;
 		this.#statusText = response.statusText;
@@ -698,7 +758,7 @@ var StreamResponseImpl = class {
 	}
 	/**
 	* Extract stream metadata from Response headers.
-	* Used by subscriber APIs to get the correct offset/cursor/upToDate for each
+	* Used by subscriber APIs to get the correct offset/cursor/upToDate/streamClosed for each
 	* specific Response, rather than reading from `this` which may be stale due to
 	* ReadableStream prefetching or timing issues.
 	*/
@@ -706,24 +766,74 @@ var StreamResponseImpl = class {
 		const offset = response.headers.get(STREAM_OFFSET_HEADER);
 		const cursor = response.headers.get(STREAM_CURSOR_HEADER);
 		const upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER);
+		const streamClosed = response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
 		return {
 			offset: offset ?? this.offset,
 			cursor: cursor ?? this.cursor,
-			upToDate
+			upToDate,
+			streamClosed: streamClosed || this.streamClosed
 		};
 	}
 	/**
+	* Decode base64 string to Uint8Array.
+	* Per protocol: concatenate data lines, remove \n and \r, then decode.
+	*/
+	#decodeBase64(base64Str) {
+		const cleaned = base64Str.replace(/[\n\r]/g, ``);
+		if (cleaned.length === 0) return new Uint8Array(0);
+		if (cleaned.length % 4 !== 0) throw new DurableStreamError(`Invalid base64 data: length ${cleaned.length} is not a multiple of 4`, `PARSE_ERROR`);
+		try {
+			if (typeof Buffer !== `undefined`) return new Uint8Array(Buffer.from(cleaned, `base64`));
+			else {
+				const binaryStr = atob(cleaned);
+				const bytes = new Uint8Array(binaryStr.length);
+				for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i);
+				return bytes;
+			}
+		} catch (err) {
+			throw new DurableStreamError(`Failed to decode base64 data: ${err instanceof Error ? err.message : String(err)}`, `PARSE_ERROR`);
+		}
+	}
+	/**
 	* Create a synthetic Response from SSE data with proper headers.
-	* Includes offset/cursor/upToDate in headers so subscribers can read them.
+	* Includes offset/cursor/upToDate/streamClosed in headers so subscribers can read them.
 	*/
-	#createSSESyntheticResponse(data, offset, cursor, upToDate) {
+	#createSSESyntheticResponse(data, offset, cursor, upToDate, streamClosed) {
+		return this.#createSSESyntheticResponseFromParts([data], offset, cursor, upToDate, streamClosed);
+	}
+	/**
+	* Create a synthetic Response from multiple SSE data parts.
+	* For base64 mode, each part is independently encoded, so we decode each
+	* separately and concatenate the binary results.
+	* For text mode, parts are simply concatenated as strings.
+	*/
+	#createSSESyntheticResponseFromParts(dataParts, offset, cursor, upToDate, streamClosed) {
 		const headers = {
 			"content-type": this.contentType ?? `application/json`,
 			[STREAM_OFFSET_HEADER]: String(offset)
 		};
 		if (cursor) headers[STREAM_CURSOR_HEADER] = cursor;
 		if (upToDate) headers[STREAM_UP_TO_DATE_HEADER] = `true`;
-		return new Response(data, {
+		if (streamClosed) headers[STREAM_CLOSED_HEADER] = `true`;
+		let body;
+		if (this.#encoding === `base64`) {
+			const decodedParts = dataParts.filter((part) => part.length > 0).map((part) => this.#decodeBase64(part));
+			if (decodedParts.length === 0) body = new ArrayBuffer(0);
+			else if (decodedParts.length === 1) {
+				const decoded = decodedParts[0];
+				body = decoded.buffer.slice(decoded.byteOffset, decoded.byteOffset + decoded.byteLength);
+			} else {
+				const totalLength = decodedParts.reduce((sum, part) => sum + part.length, 0);
+				const combined = new Uint8Array(totalLength);
+				let offset$1 = 0;
+				for (const part of decodedParts) {
+					combined.set(part, offset$1);
+					offset$1 += part.length;
+				}
+				body = combined.buffer;
+			}
+		} else body = dataParts.join(``);
+		return new Response(body, {
 			status: 200,
 			headers
 		});
@@ -732,9 +842,13 @@ 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;
+		if (controlEvent.streamClosed) {
+			this.#streamClosed = true;
+			this.#upToDate = true;
+		}
 	}
 	/**
 	* Mark the start of an SSE connection for duration tracking.
@@ -807,19 +921,29 @@ var StreamResponseImpl = class {
 		}
 		if (event.type === `data`) return this.#processSSEDataEvent(event.data, sseEventIterator);
 		this.#updateStateFromSSEControl(event);
+		if (event.upToDate) {
+			const response = this.#createSSESyntheticResponse(``, event.streamNextOffset, event.streamCursor, true, event.streamClosed ?? false);
+			return {
+				type: `response`,
+				response
+			};
+		}
 		return { type: `continue` };
 	}
 	/**
 	* Process an SSE data event by waiting for its corresponding control event.
 	* In SSE protocol, control events come AFTER data events.
 	* Multiple data events may arrive before a single control event - we buffer them.
+	*
+	* For base64 mode, each data event is independently base64 encoded, so we
+	* collect them as an array and decode each separately.
 	*/
 	async #processSSEDataEvent(pendingData, sseEventIterator) {
-		let bufferedData = pendingData;
+		const bufferedDataParts = [pendingData];
 		while (true) {
 			const { done: controlDone, value: controlEvent } = await sseEventIterator.next();
 			if (controlDone) {
-				const response = this.#createSSESyntheticResponse(bufferedData, this.offset, this.cursor, this.upToDate);
+				const response = this.#createSSESyntheticResponseFromParts(bufferedDataParts, this.offset, this.cursor, this.upToDate, this.streamClosed);
 				try {
 					const newIterator = await this.#trySSEReconnect();
 					return {
@@ -836,13 +960,13 @@ var StreamResponseImpl = class {
 			}
 			if (controlEvent.type === `control`) {
 				this.#updateStateFromSSEControl(controlEvent);
-				const response = this.#createSSESyntheticResponse(bufferedData, controlEvent.streamNextOffset, controlEvent.streamCursor, controlEvent.upToDate ?? false);
+				const response = this.#createSSESyntheticResponseFromParts(bufferedDataParts, controlEvent.streamNextOffset, controlEvent.streamCursor, controlEvent.upToDate ?? false, controlEvent.streamClosed ?? false);
 				return {
 					type: `response`,
 					response
 				};
 			}
-			bufferedData += controlEvent.data;
+			bufferedDataParts.push(controlEvent.data);
 		}
 	}
 	/**
@@ -1000,7 +1124,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;
@@ -1097,7 +1227,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());
 			},
@@ -1133,16 +1269,23 @@ var StreamResponseImpl = class {
 				while (!result.done) {
 					if (abortController.signal.aborted) break;
 					const response = result.value;
-					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const { offset, cursor, upToDate, streamClosed } = 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,
 						offset,
 						cursor,
-						upToDate
+						upToDate,
+						streamClosed
 					});
 					result = await reader.read();
 				}
@@ -1172,13 +1315,14 @@ var StreamResponseImpl = class {
 				while (!result.done) {
 					if (abortController.signal.aborted) break;
 					const response = result.value;
-					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const { offset, cursor, upToDate, streamClosed } = this.#getMetadataFromResponse(response);
 					const buffer = await response.arrayBuffer();
 					await subscriber({
 						data: new Uint8Array(buffer),
 						offset,
 						cursor,
-						upToDate
+						upToDate,
+						streamClosed
 					});
 					result = await reader.read();
 				}
@@ -1208,13 +1352,14 @@ var StreamResponseImpl = class {
 				while (!result.done) {
 					if (abortController.signal.aborted) break;
 					const response = result.value;
-					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const { offset, cursor, upToDate, streamClosed } = this.#getMetadataFromResponse(response);
 					const text = await response.text();
 					await subscriber({
 						text,
 						offset,
 						cursor,
-						upToDate
+						upToDate,
+						streamClosed
 					});
 					result = await reader.read();
 				}
@@ -1265,6 +1410,11 @@ async function handleErrorResponse(response, url, context) {
 	const status = response.status;
 	if (status === 404) throw new DurableStreamError(`Stream not found: ${url}`, `NOT_FOUND`, 404);
 	if (status === 409) {
+		const streamClosedHeader = response.headers.get(STREAM_CLOSED_HEADER);
+		if (streamClosedHeader?.toLowerCase() === `true`) {
+			const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
+			throw new StreamClosedError(url, finalOffset);
+		}
 		const message = context?.operation === `create` ? `Stream already exists: ${url}` : `Sequence conflict: seq is lower than last appended`;
 		const code = context?.operation === `create` ? `CONFLICT_EXISTS` : `CONFLICT_SEQ`;
 		throw new DurableStreamError(message, code, 409);
@@ -1381,7 +1531,7 @@ function _resetHttpWarningForTesting() {
 *   url,
 *   auth,
 *   offset: savedOffset,
-*   live: "auto",
+*   live: true,
 * })
 * live.subscribeJson(async (batch) => {
 *   for (const item of batch.items) {
@@ -1422,10 +1572,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);
@@ -1450,13 +1601,16 @@ async function streamInternal(options) {
 	const initialOffset = firstResponse.headers.get(STREAM_OFFSET_HEADER) ?? startOffset;
 	const initialCursor = firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? void 0;
 	const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER);
+	const initialStreamClosed = firstResponse.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
 	const isJsonMode = options.json === true || (contentType?.includes(`application/json`) ?? false);
+	const sseDataEncoding = firstResponse.headers.get(STREAM_SSE_DATA_ENCODING_HEADER);
+	const encoding = sseDataEncoding === `base64` ? `base64` : void 0;
 	const fetchNext = async (offset, cursor, signal, resumingFromPause) => {
 		const nextUrl = new URL(url);
 		nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
 		if (!resumingFromPause) {
-			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 (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);
@@ -1495,936 +1649,1126 @@ async function streamInternal(options) {
 		initialOffset,
 		initialCursor,
 		initialUpToDate,
+		initialStreamClosed,
 		firstResponse,
 		abortController,
 		fetchNext,
 		startSSE,
-		sseResilience: options.sseResilience
+		sseResilience: options.sseResilience,
+		encoding
 	});
 }
 
 //#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.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;
+	#closeResult = null;
+	#pendingFinalMessage;
+	#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.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.
+	* Stop the producer without closing the underlying stream.
+	*
+	* Use this when you want to:
+	* - Hand off writing to another producer
+	* - Keep the stream open for future writes
+	* - Stop this producer but not signal EOF to readers
+	*
+	* Flushes any pending messages before detaching.
+	* After calling detach(), further append() calls will throw.
 	*/
-	static async delete(opts) {
-		const stream$1 = new DurableStream(opts);
-		return stream$1.delete();
-	}
-	/**
-	* HEAD metadata for this stream.
+	async detach() {
+		if (this.#closed) return;
+		this.#closed = true;
+		try {
+			await this.flush();
+		} catch {}
+	}
+	/**
+	* Flush pending messages and close the underlying stream (EOF).
+	*
+	* This is the typical way to end a producer session. It:
+	* 1. Flushes all pending messages
+	* 2. Optionally appends a final message
+	* 3. Closes the stream (no further appends permitted)
+	*
+	* **Idempotent**: Unlike `DurableStream.close({ body })`, this method is
+	* idempotent even with a final message because it uses producer headers
+	* for deduplication. Safe to retry on network failures.
+	*
+	* @param finalMessage - Optional final message to append atomically with close
+	* @returns CloseResult with the final offset
 	*/
-	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 close(finalMessage) {
+		if (this.#closed) {
+			if (this.#closeResult) return this.#closeResult;
+			await this.flush();
+			const result$1 = await this.#doClose(this.#pendingFinalMessage);
+			this.#closeResult = result$1;
+			return result$1;
+		}
+		this.#closed = true;
+		this.#pendingFinalMessage = finalMessage;
+		await this.flush();
+		const result = await this.#doClose(finalMessage);
+		this.#closeResult = result;
+		return result;
 	}
 	/**
-	* Create this stream (create-only PUT) using the URL/auth from the handle.
+	* Actually close the stream with optional final message.
+	* Uses producer headers for idempotency.
 	*/
-	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,
+	async #doClose(finalMessage) {
+		const contentType = this.#stream.contentType ?? `application/octet-stream`;
+		const isJson = normalizeContentType$1(contentType) === `application/json`;
+		let body;
+		if (finalMessage !== void 0) {
+			const bodyBytes = typeof finalMessage === `string` ? new TextEncoder().encode(finalMessage) : finalMessage;
+			if (isJson) {
+				const jsonStr = new TextDecoder().decode(bodyBytes);
+				body = `[${jsonStr}]`;
+			} else body = bodyBytes;
+		}
+		const seqForThisRequest = this.#nextSeq;
+		const headers = {
+			"content-type": contentType,
+			[PRODUCER_ID_HEADER]: this.#producerId,
+			[PRODUCER_EPOCH_HEADER]: this.#epoch.toString(),
+			[PRODUCER_SEQ_HEADER]: seqForThisRequest.toString(),
+			[STREAM_CLOSED_HEADER]: `true`
+		};
+		const response = await this.#fetchClient(this.#stream.url, {
+			method: `POST`,
+			headers,
 			body,
-			signal: this.#options.signal
+			signal: this.#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;
+		if (response.status === 204) {
+			this.#nextSeq = seqForThisRequest + 1;
+			const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+			return { finalOffset };
+		}
+		if (response.status === 200) {
+			this.#nextSeq = seqForThisRequest + 1;
+			const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+			return { finalOffset };
+		}
+		if (response.status === 403) {
+			const currentEpochStr = response.headers.get(PRODUCER_EPOCH_HEADER);
+			const currentEpoch = currentEpochStr ? parseInt(currentEpochStr, 10) : this.#epoch;
+			if (this.#autoClaim) {
+				const newEpoch = currentEpoch + 1;
+				this.#epoch = newEpoch;
+				this.#nextSeq = 0;
+				return this.#doClose(finalMessage);
+			}
+			throw new StaleEpochError(currentEpoch);
+		}
+		const error = await FetchError.fromResponse(response, this.#stream.url);
+		throw error;
 	}
 	/**
-	* Delete this stream.
+	* Increment epoch and reset sequence.
+	*
+	* Call this when restarting the producer to establish a new session.
+	* Flushes any pending messages first.
 	*/
-	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);
+	async restart() {
+		await this.flush();
+		this.#epoch++;
+		this.#nextSeq = 0;
 	}
 	/**
-	* 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]));
-	* ```
+	* Current epoch for this producer.
 	*/
-	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 epoch() {
+		return this.#epoch;
 	}
 	/**
-	* Direct append without batching (used when batching is disabled).
+	* Next sequence number to be assigned.
 	*/
-	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 nextSeq() {
+		return this.#nextSeq;
 	}
 	/**
-	* Append with batching - buffers messages and sends them in batches.
+	* Number of messages in the current pending batch.
 	*/
-	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);
-				});
-			}
+	get pendingCount() {
+		return this.#pendingBatch.length;
+	}
+	/**
+	* Number of batches currently in flight.
+	*/
+	get inFlightCount() {
+		return this.#queue.length();
+	}
+	/**
+	* Enqueue the current pending batch for processing.
+	*/
+	#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;
-		}
-		if (highestSeq) requestHeaders[STREAM_SEQ_HEADER] = highestSeq;
-		const isJson = normalizeContentType$1(contentType) === `application/json`;
-		let batchedBody;
-		if (isJson) {
-			const values = batch.map((m) => m.data);
-			batchedBody = JSON.stringify(values);
-		} 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 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;
-			}
-			batchedBody = concatenated;
+	#signalSeqComplete(epoch, seq, error) {
+		let epochMap = this.#seqState.get(epoch);
+		if (!epochMap) {
+			epochMap = new Map();
+			this.#seqState.set(epoch, epochMap);
 		}
-		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
+		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 (!response.ok) await handleErrorResponse(response, this.url);
+		const cleanupThreshold = seq - this.#maxInFlight * 3;
+		if (cleanupThreshold > 0) {
+			for (const oldSeq of epochMap.keys()) if (oldSeq < cleanupThreshold) epochMap.delete(oldSeq);
+		}
 	}
 	/**
-	* 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!);
-	* ```
+	* Wait for a specific sequence to complete.
+	* Returns immediately if already completed.
+	* Throws if the sequence failed.
 	*/
-	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
+	#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]
+			});
 		});
-		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());
-	* ```
+	* 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.
 	*/
-	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);
+	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 jsonStrings = batch.map((e) => new TextDecoder().decode(e.body));
+			batchedBody = `[${jsonStrings.join(`,`)}]`;
+		} 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;
 			}
-		});
-	}
-	/**
-	* 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);
+			batchedBody = concatenated;
 		}
-		const mergedHeaders = {
-			...this.#options.headers,
-			...options?.headers
-		};
-		const mergedParams = {
-			...this.#options.params,
-			...options?.params
+		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()
 		};
-		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
+		const response = await this.#fetchClient(url, {
+			method: `POST`,
+			headers,
+			body: batchedBody,
+			signal: this.#signal
 		});
+		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);
+			}
+			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;
 	}
 	/**
-	* 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;
+		}
 	}
 };
+
+//#endregion
+//#region src/stream.ts
 /**
-* Encode a body value to the appropriate format.
-* Strings are encoded as UTF-8.
-* Objects are JSON-serialized.
+* Normalize content-type by extracting the media type (before any semicolon).
+* Handles cases like "application/json; charset=utf-8".
 */
-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));
+function normalizeContentType(contentType) {
+	if (!contentType) return ``;
+	return contentType.split(`;`)[0].trim().toLowerCase();
 }
 /**
-* Convert an async iterable to a ReadableStream.
+* Check if a value is a Promise or Promise-like (thenable).
 */
-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;
-	}
-};
-/**
-* Normalize content-type by extracting the media type (before any semicolon).
-*/
-function normalizeContentType(contentType) {
-	if (!contentType) return ``;
-	return contentType.split(`;`)[0].trim().toLowerCase();
+function isPromiseLike(value) {
+	return value != null && typeof value.then === `function`;
 }
 /**
-* An idempotent producer for exactly-once writes to a durable stream.
+* 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.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.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,
+			closed: opts.closed
 		});
-		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);
-	}
-	/**
-	* Send any pending batch immediately and wait for all in-flight batches.
-	*
-	* Call this before shutdown to ensure all messages are delivered.
-	*/
-	async flush() {
-		if (this.#lingerTimeout) {
-			clearTimeout(this.#lingerTimeout);
-			this.#lingerTimeout = null;
-		}
-		if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
-		await this.#queue.drained();
+		return stream$1;
 	}
 	/**
-	* Flush pending messages and close the producer.
+	* Validate that a stream exists and fetch metadata via HEAD.
+	* Returns a handle with contentType populated (if sent by server).
 	*
-	* After calling close(), further append() calls will throw.
-	*/
-	async close() {
-		if (this.#closed) return;
-		this.#closed = true;
-		try {
-			await this.flush();
-		} catch {}
-	}
-	/**
-	* Increment epoch and reset sequence.
+	* **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.
 	*
-	* Call this when restarting the producer to establish a new session.
-	* Flushes any pending messages first.
+	* @example
+	* ```typescript
+	* // Validate stream exists before reading
+	* const handle = await DurableStream.connect({ url })
+	* const res = await handle.stream() // Now actually read
+	* ```
 	*/
-	async restart() {
-		await this.flush();
-		this.#epoch++;
-		this.#nextSeq = 0;
+	static async connect(opts) {
+		const stream$1 = new DurableStream(opts);
+		await stream$1.head();
+		return stream$1;
 	}
 	/**
-	* Current epoch for this producer.
+	* HEAD metadata for a stream without creating a handle.
 	*/
-	get epoch() {
-		return this.#epoch;
+	static async head(opts) {
+		const stream$1 = new DurableStream(opts);
+		return stream$1.head();
 	}
 	/**
-	* Next sequence number to be assigned.
+	* Delete a stream without creating a handle.
 	*/
-	get nextSeq() {
-		return this.#nextSeq;
+	static async delete(opts) {
+		const stream$1 = new DurableStream(opts);
+		return stream$1.delete();
 	}
 	/**
-	* Number of messages in the current pending batch.
+	* HEAD metadata for this stream.
 	*/
-	get pendingCount() {
-		return this.#pendingBatch.length;
-	}
+	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;
+		const streamClosed = response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
+		if (contentType) this.contentType = contentType;
+		return {
+			exists: true,
+			contentType,
+			offset,
+			etag,
+			cacheControl,
+			streamClosed
+		};
+	}
 	/**
-	* Number of batches currently in flight.
+	* Create this stream (create-only PUT) using the URL/auth from the handle.
 	*/
-	get inFlightCount() {
-		return this.#queue.length();
+	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;
+		if (opts?.closed) requestHeaders[STREAM_CLOSED_HEADER] = `true`;
+		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;
 	}
 	/**
-	* Enqueue the current pending batch for processing.
+	* Delete this stream.
 	*/
-	#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 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
 		});
-		else this.#queue.push({
-			batch,
-			seq
-		}).catch(() => {});
+		if (!response.ok) await handleErrorResponse(response, this.url);
 	}
 	/**
-	* Batch worker - processes batches via fastq.
+	* Close the stream, optionally with a final message.
+	*
+	* After closing:
+	* - No further appends are permitted (server returns 409)
+	* - Readers can observe the closed state and treat it as EOF
+	* - The stream's data remains fully readable
+	*
+	* Closing is:
+	* - **Durable**: The closed state is persisted
+	* - **Monotonic**: Once closed, a stream cannot be reopened
+	*
+	* **Idempotency:**
+	* - `close()` without body: Idempotent — safe to call multiple times
+	* - `close({ body })` with body: NOT idempotent — throws `StreamClosedError`
+	*   if stream is already closed (use `IdempotentProducer.close()` for
+	*   idempotent close-with-body semantics)
+	*
+	* @returns CloseResult with the final offset
+	* @throws StreamClosedError if called with body on an already-closed stream
 	*/
-	async #batchWorker(task) {
-		const { batch, seq } = task;
-		const epoch = this.#epoch;
-		try {
-			await this.#doSendBatch(batch, seq, epoch);
-			if (!this.#epochClaimed) this.#epochClaimed = true;
-			this.#signalSeqComplete(epoch, seq, void 0);
-		} catch (error) {
-			this.#signalSeqComplete(epoch, seq, error);
-			if (this.#onError) this.#onError(error);
-			throw error;
+	async close(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		requestHeaders[STREAM_CLOSED_HEADER] = `true`;
+		let body;
+		if (opts?.body !== void 0) {
+			const isJson = normalizeContentType(contentType) === `application/json`;
+			if (isJson) {
+				const bodyStr = typeof opts.body === `string` ? opts.body : new TextDecoder().decode(opts.body);
+				body = `[${bodyStr}]`;
+			} else body = typeof opts.body === `string` ? opts.body : opts.body;
+		}
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (response.status === 409) {
+			const isClosed = response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
+			if (isClosed) {
+				const finalOffset$1 = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
+				throw new StreamClosedError(this.url, finalOffset$1);
+			}
 		}
+		if (!response.ok) await handleErrorResponse(response, this.url);
+		const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+		return { finalOffset };
 	}
 	/**
-	* Signal that a sequence has completed (success or failure).
+	* 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());
+	* ```
 	*/
-	#signalSeqComplete(epoch, seq, error) {
-		let epochMap = this.#seqState.get(epoch);
-		if (!epochMap) {
-			epochMap = new Map();
-			this.#seqState.set(epoch, epochMap);
-		}
-		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: []
+	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);
+	}
+	/**
+	* Direct append without batching (used when batching is disabled).
+	*/
+	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`;
+		let encodedBody;
+		if (isJson) {
+			const bodyStr = typeof body === `string` ? body : new TextDecoder().decode(body);
+			encodedBody = `[${bodyStr}]`;
+		} else if (typeof body === `string`) encodedBody = body;
+		else encodedBody = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body: encodedBody,
+			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.
+	* Append with batching - buffers messages and sends them in batches.
 	*/
-	#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();
-		}
+	async #appendWithBatching(body, opts) {
 		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]
+			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);
+				});
+			}
 		});
 	}
 	/**
-	* 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.
+	* Batch worker - processes batches of messages.
 	*/
-	async #doSendBatch(batch, seq, epoch) {
-		const contentType = this.#stream.contentType ?? `application/octet-stream`;
+	async #batchWorker(batch) {
+		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);
+				});
+			}
+		} catch (error) {
+			for (const msg of batch) msg.reject(error);
+			for (const msg of this.#buffer) msg.reject(error);
+			this.#buffer = [];
+			throw error;
+		}
+	}
+	/**
+	* Send a batch of messages as a single POST request.
+	*/
+	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;
+		}
+		if (highestSeq) requestHeaders[STREAM_SEQ_HEADER] = highestSeq;
 		const isJson = normalizeContentType(contentType) === `application/json`;
 		let batchedBody;
 		if (isJson) {
-			const values = batch.map((e) => e.data);
-			batchedBody = JSON.stringify(values);
+			const jsonStrings = batch.map((m) => typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data));
+			batchedBody = `[${jsonStrings.join(`,`)}]`;
 		} 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;
+			const hasUint8Array = batch.some((m) => m.data instanceof Uint8Array);
+			const hasString = batch.some((m) => typeof m.data === `string`);
+			if (hasUint8Array && !hasString) {
+				const chunks = batch.map((m) => m.data);
+				const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+				const combined = new Uint8Array(totalLength);
+				let offset = 0;
+				for (const chunk of chunks) {
+					combined.set(chunk, offset);
+					offset += chunk.length;
+				}
+				batchedBody = combined;
+			} else if (hasString && !hasUint8Array) batchedBody = batch.map((m) => m.data).join(``);
+			else {
+				const encoder = new TextEncoder();
+				const chunks = batch.map((m) => typeof m.data === `string` ? encoder.encode(m.data) : m.data);
+				const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+				const combined = new Uint8Array(totalLength);
+				let offset = 0;
+				for (const chunk of chunks) {
+					combined.set(chunk, offset);
+					offset += chunk.length;
+				}
+				batchedBody = combined;
 			}
-			batchedBody = concatenated;
 		}
-		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, {
+		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,
+			headers: requestHeaders,
 			body: batchedBody,
-			signal: this.#signal
+			signal: combinedSignal
 		});
-		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);
-			}
-			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);
+		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.
+	*
+	* 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,
+	* }));
+	* ```
+	*/
+	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.close();
+				if (writeError) throw writeError;
+			},
+			abort(_reason) {
+				producer.detach().catch((err) => {
+					opts?.onError?.(err);
+				});
 			}
-			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;
+		});
 	}
 	/**
-	* Clear pending batch and report error.
+	* 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);
+	*   }
+	* });
+	* ```
 	*/
-	#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 stream(options) {
+		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
+		});
+	}
+	/**
+	* Build request headers and URL.
+	*/
+	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
-export { BackoffDefaults, CURSOR_QUERY_PARAM, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, FetchBackoffAbortError, FetchError, IdempotentProducer, InvalidSignalError, LIVE_QUERY_PARAM, MissingStreamUrlError, OFFSET_QUERY_PARAM, PRODUCER_EPOCH_HEADER, PRODUCER_EXPECTED_SEQ_HEADER, PRODUCER_ID_HEADER, PRODUCER_RECEIVED_SEQ_HEADER, PRODUCER_SEQ_HEADER, 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, SequenceGapError, StaleEpochError, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };
+export { BackoffDefaults, CURSOR_QUERY_PARAM, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, FetchBackoffAbortError, FetchError, IdempotentProducer, InvalidSignalError, LIVE_QUERY_PARAM, MissingStreamUrlError, OFFSET_QUERY_PARAM, PRODUCER_EPOCH_HEADER, PRODUCER_EXPECTED_SEQ_HEADER, PRODUCER_ID_HEADER, PRODUCER_RECEIVED_SEQ_HEADER, PRODUCER_SEQ_HEADER, SSE_CLOSED_FIELD, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CLOSED_HEADER, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, SequenceGapError, StaleEpochError, StreamClosedError, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };