@inf-minds/streams-protocol 0.0.1

package/dist/headers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Header name for the next offset to read from.
+ */
+export declare const HEADER_NEXT_OFFSET = "Stream-Next-Offset";
+/**
+ * Header name indicating stream is caught up to current tail.
+ */
+export declare const HEADER_UP_TO_DATE = "Stream-Up-To-Date";
+/**
+ * Header name indicating stream is permanently closed.
+ */
+export declare const HEADER_CLOSED = "Stream-Closed";
+/**
+ * Header name for opaque cursor (CDN collapsing support).
+ */
+export declare const HEADER_CURSOR = "Stream-Cursor";
+/**
+ * Default polling interval in milliseconds for catch-up mode.
+ */
+export declare const DEFAULT_POLL_INTERVAL = 500;
+/**
+ * Parsed stream response headers.
+ */
+export interface StreamResponseHeaders {
+    /** Next offset to read from */
+    nextOffset: string;
+    /** True when caught up to stream tail */
+    upToDate?: boolean;
+    /** True when stream is permanently closed */
+    closed?: boolean;
+    /** Opaque cursor for CDN request collapsing */
+    cursor?: string;
+    /** ETag for caching */
+    etag?: string;
+}
+/**
+ * Parses stream headers from an HTTP response.
+ *
+ * @example
+ * const headers = response.headers;
+ * const stream = parseStreamHeaders(headers);
+ * console.log(stream.nextOffset); // '210'
+ */
+export declare function parseStreamHeaders(headers: Headers): StreamResponseHeaders;
+/**
+ * Formats stream headers for an HTTP response.
+ *
+ * @example
+ * const headers = formatStreamHeaders({ nextOffset: '210', upToDate: true });
+ * response.headers = headers;
+ */
+export declare function formatStreamHeaders(stream: StreamResponseHeaders): Headers;
+//# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,qBAAqB,CA4B1E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAsB1E"}

package/dist/headers.js

@@ -0,0 +1,78 @@
+// ABOUTME: HTTP header parsing and formatting utilities for Durable Streams
+// ABOUTME: Handles Stream-* headers per protocol specification
+/**
+ * Header name for the next offset to read from.
+ */
+export const HEADER_NEXT_OFFSET = 'Stream-Next-Offset';
+/**
+ * Header name indicating stream is caught up to current tail.
+ */
+export const HEADER_UP_TO_DATE = 'Stream-Up-To-Date';
+/**
+ * Header name indicating stream is permanently closed.
+ */
+export const HEADER_CLOSED = 'Stream-Closed';
+/**
+ * Header name for opaque cursor (CDN collapsing support).
+ */
+export const HEADER_CURSOR = 'Stream-Cursor';
+/**
+ * Default polling interval in milliseconds for catch-up mode.
+ */
+export const DEFAULT_POLL_INTERVAL = 500;
+/**
+ * Parses stream headers from an HTTP response.
+ *
+ * @example
+ * const headers = response.headers;
+ * const stream = parseStreamHeaders(headers);
+ * console.log(stream.nextOffset); // '210'
+ */
+export function parseStreamHeaders(headers) {
+    const nextOffset = headers.get(HEADER_NEXT_OFFSET) ?? '';
+    const upToDateStr = headers.get(HEADER_UP_TO_DATE);
+    const closedStr = headers.get(HEADER_CLOSED);
+    const cursor = headers.get(HEADER_CURSOR) ?? undefined;
+    const etag = headers.get('ETag') ?? undefined;
+    const result = {
+        nextOffset,
+    };
+    if (upToDateStr !== null) {
+        result.upToDate = upToDateStr === 'true';
+    }
+    if (closedStr !== null) {
+        result.closed = closedStr === 'true';
+    }
+    if (cursor) {
+        result.cursor = cursor;
+    }
+    if (etag) {
+        result.etag = etag;
+    }
+    return result;
+}
+/**
+ * Formats stream headers for an HTTP response.
+ *
+ * @example
+ * const headers = formatStreamHeaders({ nextOffset: '210', upToDate: true });
+ * response.headers = headers;
+ */
+export function formatStreamHeaders(stream) {
+    const headers = new Headers();
+    headers.set(HEADER_NEXT_OFFSET, stream.nextOffset);
+    if (stream.upToDate !== undefined) {
+        headers.set(HEADER_UP_TO_DATE, String(stream.upToDate));
+    }
+    if (stream.closed !== undefined) {
+        headers.set(HEADER_CLOSED, String(stream.closed));
+    }
+    if (stream.cursor !== undefined) {
+        headers.set(HEADER_CURSOR, stream.cursor);
+    }
+    if (stream.etag !== undefined) {
+        headers.set('ETag', stream.etag);
+    }
+    return headers;
+}
+//# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,+DAA+D;AAE/D;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAErD;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAkBzC;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS,CAAC;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC;IAE9C,MAAM,MAAM,GAA0B;QACpC,UAAU;KACX,CAAC;IAEF,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;QACzB,MAAM,CAAC,QAAQ,GAAG,WAAW,KAAK,MAAM,CAAC;IAC3C,CAAC;IAED,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,CAAC,MAAM,GAAG,SAAS,KAAK,MAAM,CAAC;IACvC,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA6B;IAC/D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAEnD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { encodeOffset, decodeOffset, OFFSET_BEGINNING, OFFSET_NOW, } from './offset.js';
+export { formatSSEDataEvent, formatSSEControlEvent, parseSSEEvent, SSE_RETRY_MS, type SSEDataEvent, type SSEControlEvent, type SSEEvent, type SSEControlPayload, } from './sse.js';
+export { parseStreamHeaders, formatStreamHeaders, HEADER_NEXT_OFFSET, HEADER_UP_TO_DATE, HEADER_CLOSED, HEADER_CURSOR, DEFAULT_POLL_INTERVAL, type StreamResponseHeaders, } from './headers.js';
+export { isWSClientMessage, isWSServerMessage, parseWSClientMessage, parseWSServerMessage, serializeWSMessage, type WSClientMessage, type WSServerMessage, type WSConnectedMessage, type WSSubscribeMessage, type WSUnsubscribeMessage, type WSPingMessage, type WSSubscribedMessage, type WSUnsubscribedMessage, type WSEventMessage, type WSStatusMessage, type WSErrorMessage, type WSPongMessage, } from './websocket.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// ABOUTME: Durable Streams protocol types and utilities
+// ABOUTME: Zero-dependency package for protocol compliance across clients and servers
+// Offset encoding/decoding
+export { encodeOffset, decodeOffset, OFFSET_BEGINNING, OFFSET_NOW, } from './offset.js';
+// SSE formatting and parsing
+export { formatSSEDataEvent, formatSSEControlEvent, parseSSEEvent, SSE_RETRY_MS, } from './sse.js';
+// HTTP header utilities
+export { parseStreamHeaders, formatStreamHeaders, HEADER_NEXT_OFFSET, HEADER_UP_TO_DATE, HEADER_CLOSED, HEADER_CURSOR, DEFAULT_POLL_INTERVAL, } from './headers.js';
+// WebSocket protocol types
+export { isWSClientMessage, isWSServerMessage, parseWSClientMessage, parseWSServerMessage, serializeWSMessage, } from './websocket.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,sFAAsF;AAEtF,2BAA2B;AAC3B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,6BAA6B;AAC7B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACb,YAAY,GAKb,MAAM,UAAU,CAAC;AAElB,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,qBAAqB,GAEtB,MAAM,cAAc,CAAC;AAEtB,2BAA2B;AAC3B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GAanB,MAAM,gBAAgB,CAAC"}

package/dist/offset.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Special offset value indicating "from beginning" of stream.
+ */
+export declare const OFFSET_BEGINNING = "-1";
+/**
+ * Special offset value indicating "from current tail" (live mode).
+ */
+export declare const OFFSET_NOW = "now";
+/**
+ * Encodes a bigint event ID to a lexicographically sortable offset string.
+ *
+ * Uses length-prefixed base-36 encoding:
+ * - First character indicates the length of the base-36 representation
+ * - Remaining characters are the base-36 encoded value
+ *
+ * This ensures that smaller numeric values always sort before larger ones
+ * when using string comparison.
+ *
+ * @example
+ * encodeOffset(0n)   // '10'   (length 1, value '0')
+ * encodeOffset(35n)  // '1z'   (length 1, value 'z')
+ * encodeOffset(36n)  // '210'  (length 2, value '10')
+ * encodeOffset(1295n) // '2zz' (length 2, value 'zz')
+ */
+export declare function encodeOffset(id: bigint): string;
+/**
+ * Decodes a lexicographically sortable offset string back to a bigint.
+ *
+ * Inverse of encodeOffset.
+ *
+ * @example
+ * decodeOffset('10')  // 0n
+ * decodeOffset('1z')  // 35n
+ * decodeOffset('210') // 36n
+ */
+export declare function decodeOffset(offset: string): bigint;
+//# sourceMappingURL=offset.d.ts.map

package/dist/offset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offset.d.ts","sourceRoot":"","sources":["../src/offset.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,UAAU,QAAQ,CAAC;AAEhC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAgB/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAsBnD"}

package/dist/offset.js

@@ -0,0 +1,69 @@
+// ABOUTME: Offset encoding/decoding utilities for Durable Streams protocol
+// ABOUTME: Uses length-prefixed base-36 encoding for lexicographic ordering
+/**
+ * Special offset value indicating "from beginning" of stream.
+ */
+export const OFFSET_BEGINNING = '-1';
+/**
+ * Special offset value indicating "from current tail" (live mode).
+ */
+export const OFFSET_NOW = 'now';
+/**
+ * Encodes a bigint event ID to a lexicographically sortable offset string.
+ *
+ * Uses length-prefixed base-36 encoding:
+ * - First character indicates the length of the base-36 representation
+ * - Remaining characters are the base-36 encoded value
+ *
+ * This ensures that smaller numeric values always sort before larger ones
+ * when using string comparison.
+ *
+ * @example
+ * encodeOffset(0n)   // '10'   (length 1, value '0')
+ * encodeOffset(35n)  // '1z'   (length 1, value 'z')
+ * encodeOffset(36n)  // '210'  (length 2, value '10')
+ * encodeOffset(1295n) // '2zz' (length 2, value 'zz')
+ */
+export function encodeOffset(id) {
+    if (id < 0n) {
+        throw new Error('Offset ID must be non-negative');
+    }
+    const base36 = id.toString(36);
+    const length = base36.length;
+    // Use base-36 character for length prefix (supports up to 35 digits)
+    // 35 base-36 digits can represent numbers up to 36^35 - 1, which is enormous
+    if (length > 35) {
+        throw new Error('Offset ID too large');
+    }
+    const lengthPrefix = length.toString(36);
+    return lengthPrefix + base36;
+}
+/**
+ * Decodes a lexicographically sortable offset string back to a bigint.
+ *
+ * Inverse of encodeOffset.
+ *
+ * @example
+ * decodeOffset('10')  // 0n
+ * decodeOffset('1z')  // 35n
+ * decodeOffset('210') // 36n
+ */
+export function decodeOffset(offset) {
+    if (offset.length < 2) {
+        throw new Error('Invalid offset format');
+    }
+    const lengthPrefix = offset[0];
+    const expectedLength = parseInt(lengthPrefix, 36);
+    const base36Value = offset.slice(1);
+    if (base36Value.length !== expectedLength) {
+        throw new Error(`Invalid offset format: expected ${expectedLength} digits, got ${base36Value.length}`);
+    }
+    // Parse base-36 string to bigint
+    // BigInt doesn't have native base-36 parsing, so we do it manually
+    let result = 0n;
+    for (const char of base36Value) {
+        result = result * 36n + BigInt(parseInt(char, 36));
+    }
+    return result;
+}
+//# sourceMappingURL=offset.js.map

package/dist/offset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offset.js","sourceRoot":"","sources":["../src/offset.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAE5E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,CAAC;AAEhC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,MAAM,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAE7B,qEAAqE;IACrE,6EAA6E;IAC7E,IAAI,MAAM,GAAG,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACzC,OAAO,YAAY,GAAG,MAAM,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IAChC,MAAM,cAAc,GAAG,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEpC,IAAI,WAAW,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,mCAAmC,cAAc,gBAAgB,WAAW,CAAC,MAAM,EAAE,CACtF,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,mEAAmE;IACnE,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,GAAG,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/sse.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Default retry interval in milliseconds for SSE connections.
+ */
+export declare const SSE_RETRY_MS = 3000;
+/**
+ * SSE data event containing actual stream payload.
+ */
+export interface SSEDataEvent<T = unknown> {
+    event: 'data';
+    data: T;
+}
+/**
+ * SSE control event containing stream metadata.
+ */
+export interface SSEControlEvent {
+    event: 'control';
+    streamNextOffset: string;
+    streamCursor?: string;
+    upToDate?: boolean;
+    streamClosed?: boolean;
+}
+/**
+ * Union type for all SSE events in the Durable Streams protocol.
+ */
+export type SSEEvent<T = unknown> = SSEDataEvent<T> | SSEControlEvent;
+/**
+ * Control event payload (without the 'event' discriminator).
+ */
+export interface SSEControlPayload {
+    streamNextOffset: string;
+    streamCursor?: string;
+    upToDate?: boolean;
+    streamClosed?: boolean;
+}
+/**
+ * Formats a data payload as an SSE data event string.
+ *
+ * @example
+ * formatSSEDataEvent({ type: 'message' })
+ * // Returns: 'event: data\ndata: {"type":"message"}\n\n'
+ */
+export declare function formatSSEDataEvent(data: unknown): string;
+/**
+ * Formats control metadata as an SSE control event string.
+ *
+ * @example
+ * formatSSEControlEvent({ streamNextOffset: '210', upToDate: true })
+ * // Returns: 'event: control\ndata: {"streamNextOffset":"210","upToDate":true}\n\n'
+ */
+export declare function formatSSEControlEvent(control: SSEControlPayload): string;
+/**
+ * Parses an SSE event block (lines between double newlines).
+ *
+ * Returns null for empty input, comments, or non-data/control events.
+ *
+ * @example
+ * parseSSEEvent('event: data\ndata: {"type":"message"}')
+ * // Returns: { event: 'data', data: { type: 'message' } }
+ */
+export declare function parseSSEEvent(block: string): SSEEvent | null;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,SAAS,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAGxD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAkBxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAyE5D"}

package/dist/sse.js

@@ -0,0 +1,114 @@
+// ABOUTME: SSE (Server-Sent Events) formatting and parsing utilities
+// ABOUTME: Implements two-event model (data + control) per Durable Streams spec
+/**
+ * Default retry interval in milliseconds for SSE connections.
+ */
+export const SSE_RETRY_MS = 3000;
+/**
+ * Formats a data payload as an SSE data event string.
+ *
+ * @example
+ * formatSSEDataEvent({ type: 'message' })
+ * // Returns: 'event: data\ndata: {"type":"message"}\n\n'
+ */
+export function formatSSEDataEvent(data) {
+    const json = JSON.stringify(data);
+    return `event: data\ndata: ${json}\n\n`;
+}
+/**
+ * Formats control metadata as an SSE control event string.
+ *
+ * @example
+ * formatSSEControlEvent({ streamNextOffset: '210', upToDate: true })
+ * // Returns: 'event: control\ndata: {"streamNextOffset":"210","upToDate":true}\n\n'
+ */
+export function formatSSEControlEvent(control) {
+    // Only include defined fields
+    const payload = {
+        streamNextOffset: control.streamNextOffset,
+    };
+    if (control.streamCursor !== undefined) {
+        payload.streamCursor = control.streamCursor;
+    }
+    if (control.upToDate !== undefined) {
+        payload.upToDate = control.upToDate;
+    }
+    if (control.streamClosed !== undefined) {
+        payload.streamClosed = control.streamClosed;
+    }
+    const json = JSON.stringify(payload);
+    return `event: control\ndata: ${json}\n\n`;
+}
+/**
+ * Parses an SSE event block (lines between double newlines).
+ *
+ * Returns null for empty input, comments, or non-data/control events.
+ *
+ * @example
+ * parseSSEEvent('event: data\ndata: {"type":"message"}')
+ * // Returns: { event: 'data', data: { type: 'message' } }
+ */
+export function parseSSEEvent(block) {
+    if (!block || block.trim() === '') {
+        return null;
+    }
+    const lines = block.split('\n');
+    let eventType = null;
+    const dataLines = [];
+    for (const line of lines) {
+        // Skip comments
+        if (line.startsWith(':')) {
+            continue;
+        }
+        // Parse event type
+        if (line.startsWith('event:')) {
+            eventType = line.slice(6).trim();
+            continue;
+        }
+        // Parse data lines
+        if (line.startsWith('data:')) {
+            dataLines.push(line.slice(5).trim());
+            continue;
+        }
+        // Handle "data:" without space (per SSE spec)
+        if (line.startsWith('data')) {
+            const colonIndex = line.indexOf(':');
+            if (colonIndex !== -1) {
+                dataLines.push(line.slice(colonIndex + 1).trim());
+            }
+        }
+    }
+    // Only process data and control events
+    if (eventType !== 'data' && eventType !== 'control') {
+        return null;
+    }
+    if (dataLines.length === 0) {
+        return null;
+    }
+    // Concatenate data lines (per SSE spec, they should be joined with newlines)
+    const dataString = dataLines.join('\n');
+    try {
+        const parsed = JSON.parse(dataString);
+        if (eventType === 'data') {
+            return {
+                event: 'data',
+                data: parsed,
+            };
+        }
+        if (eventType === 'control') {
+            return {
+                event: 'control',
+                streamNextOffset: parsed.streamNextOffset,
+                streamCursor: parsed.streamCursor,
+                upToDate: parsed.upToDate,
+                streamClosed: parsed.streamClosed,
+            };
+        }
+    }
+    catch {
+        // Invalid JSON - return null
+        return null;
+    }
+    return null;
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAoCjC;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,sBAAsB,IAAI,MAAM,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA0B;IAC9D,8BAA8B;IAC9B,MAAM,OAAO,GAA4B;QACvC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;KAC3C,CAAC;IAEF,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,yBAAyB,IAAI,MAAM,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,gBAAgB;QAChB,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,SAAS;QACX,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACjC,SAAS;QACX,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACrC,SAAS;QACX,CAAC;QAED,8CAA8C;QAC9C,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACrC,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;gBACtB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;IACH,CAAC;IAED,uCAAuC;IACvC,IAAI,SAAS,KAAK,MAAM,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAExC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAEtC,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;YACzB,OAAO;gBACL,KAAK,EAAE,MAAM;gBACb,IAAI,EAAE,MAAM;aACb,CAAC;QACJ,CAAC;QAED,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO;gBACL,KAAK,EAAE,SAAS;gBAChB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,YAAY,EAAE,MAAM,CAAC,YAAY;aAClC,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/websocket.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Messages sent from client to server over WebSocket.
+ */
+export type WSClientMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSPingMessage;
+/**
+ * Subscribe to a stream from a given offset.
+ */
+export interface WSSubscribeMessage {
+    type: 'subscribe';
+    /** Stream ID to subscribe to */
+    streamId: string;
+    /** Starting offset, defaults to '-1' (beginning) */
+    offset?: string;
+}
+/**
+ * Unsubscribe from a stream.
+ */
+export interface WSUnsubscribeMessage {
+    type: 'unsubscribe';
+    /** Stream ID to unsubscribe from */
+    streamId: string;
+}
+/**
+ * Ping message for keepalive.
+ */
+export interface WSPingMessage {
+    type: 'ping';
+}
+/**
+ * Messages sent from server to client over WebSocket.
+ */
+export type WSServerMessage = WSConnectedMessage | WSSubscribedMessage | WSUnsubscribedMessage | WSEventMessage | WSStatusMessage | WSErrorMessage | WSPongMessage;
+/**
+ * Connection acknowledgment with assigned client ID.
+ */
+export interface WSConnectedMessage {
+    type: 'connected';
+    /** Client ID for this connection */
+    clientId: string;
+}
+/**
+ * Confirmation of successful subscription.
+ */
+export interface WSSubscribedMessage {
+    type: 'subscribed';
+    /** Stream ID subscribed to */
+    streamId: string;
+    /** Current offset position */
+    offset: string;
+}
+/**
+ * Confirmation of unsubscription.
+ */
+export interface WSUnsubscribedMessage {
+    type: 'unsubscribed';
+    /** Stream ID unsubscribed from */
+    streamId: string;
+}
+/**
+ * Stream event delivery.
+ */
+export interface WSEventMessage {
+    type: 'event';
+    /** Stream ID this event belongs to */
+    streamId: string;
+    /** Event payload */
+    event: unknown;
+    /** Offset after this event */
+    nextOffset: string;
+}
+/**
+ * Stream status update.
+ */
+export interface WSStatusMessage {
+    type: 'status';
+    /** Stream ID */
+    streamId: string;
+    /** True when caught up to tail */
+    upToDate: boolean;
+    /** True when stream is permanently closed */
+    closed?: boolean;
+}
+/**
+ * Error message.
+ */
+export interface WSErrorMessage {
+    type: 'error';
+    /** Human-readable error message */
+    message: string;
+    /** Machine-readable error code */
+    code?: string;
+    /** Stream ID if error is stream-specific */
+    streamId?: string;
+}
+/**
+ * Pong response to ping.
+ */
+export interface WSPongMessage {
+    type: 'pong';
+}
+/**
+ * Type guard for client messages.
+ */
+export declare function isWSClientMessage(msg: unknown): msg is WSClientMessage;
+/**
+ * Type guard for server messages.
+ */
+export declare function isWSServerMessage(msg: unknown): msg is WSServerMessage;
+/**
+ * Parse a JSON string as a client message.
+ */
+export declare function parseWSClientMessage(json: string): WSClientMessage | null;
+/**
+ * Parse a JSON string as a server message.
+ */
+export declare function parseWSServerMessage(json: string): WSServerMessage | null;
+/**
+ * Serialize a message to JSON string.
+ */
+export declare function serializeWSMessage(msg: WSClientMessage | WSServerMessage): string;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,oBAAoB,GACpB,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,WAAW,CAAC;IAClB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,mBAAmB,GACnB,qBAAqB,GACrB,cAAc,GACd,eAAe,GACf,cAAc,GACd,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,WAAW,CAAC;IAClB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,YAAY,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,cAAc,CAAC;IACrB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAItE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAYtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAUzE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAUzE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,GAAG,MAAM,CAEjF"}

package/dist/websocket.js

@@ -0,0 +1,63 @@
+// ABOUTME: WebSocket protocol types for Durable Streams
+// ABOUTME: Defines client-to-server and server-to-client message formats
+/**
+ * Type guard for client messages.
+ */
+export function isWSClientMessage(msg) {
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const { type } = msg;
+    return type === 'subscribe' || type === 'unsubscribe' || type === 'ping';
+}
+/**
+ * Type guard for server messages.
+ */
+export function isWSServerMessage(msg) {
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const { type } = msg;
+    return (type === 'connected' ||
+        type === 'subscribed' ||
+        type === 'unsubscribed' ||
+        type === 'event' ||
+        type === 'status' ||
+        type === 'error' ||
+        type === 'pong');
+}
+/**
+ * Parse a JSON string as a client message.
+ */
+export function parseWSClientMessage(json) {
+    try {
+        const parsed = JSON.parse(json);
+        if (isWSClientMessage(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse a JSON string as a server message.
+ */
+export function parseWSServerMessage(json) {
+    try {
+        const parsed = JSON.parse(json);
+        if (isWSServerMessage(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Serialize a message to JSON string.
+ */
+export function serializeWSMessage(msg) {
+    return JSON.stringify(msg);
+}
+//# sourceMappingURL=websocket.js.map

package/dist/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AA4HzE;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,EAAE,IAAI,EAAE,GAAG,GAAyB,CAAC;IAC3C,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,MAAM,CAAC;AAC3E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,EAAE,IAAI,EAAE,GAAG,GAAyB,CAAC;IAC3C,OAAO,CACL,IAAI,KAAK,WAAW;QACpB,IAAI,KAAK,YAAY;QACrB,IAAI,KAAK,cAAc;QACvB,IAAI,KAAK,OAAO;QAChB,IAAI,KAAK,QAAQ;QACjB,IAAI,KAAK,OAAO;QAChB,IAAI,KAAK,MAAM,CAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsC;IACvE,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@inf-minds/streams-protocol",
+  "version": "0.0.1",
+  "description": "Durable Streams protocol types and utilities",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'No linter configured yet'"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/headers.ts

@@ -0,0 +1,112 @@
+// ABOUTME: HTTP header parsing and formatting utilities for Durable Streams
+// ABOUTME: Handles Stream-* headers per protocol specification
+
+/**
+ * Header name for the next offset to read from.
+ */
+export const HEADER_NEXT_OFFSET = 'Stream-Next-Offset';
+
+/**
+ * Header name indicating stream is caught up to current tail.
+ */
+export const HEADER_UP_TO_DATE = 'Stream-Up-To-Date';
+
+/**
+ * Header name indicating stream is permanently closed.
+ */
+export const HEADER_CLOSED = 'Stream-Closed';
+
+/**
+ * Header name for opaque cursor (CDN collapsing support).
+ */
+export const HEADER_CURSOR = 'Stream-Cursor';
+
+/**
+ * Default polling interval in milliseconds for catch-up mode.
+ */
+export const DEFAULT_POLL_INTERVAL = 500;
+
+/**
+ * Parsed stream response headers.
+ */
+export interface StreamResponseHeaders {
+  /** Next offset to read from */
+  nextOffset: string;
+  /** True when caught up to stream tail */
+  upToDate?: boolean;
+  /** True when stream is permanently closed */
+  closed?: boolean;
+  /** Opaque cursor for CDN request collapsing */
+  cursor?: string;
+  /** ETag for caching */
+  etag?: string;
+}
+
+/**
+ * Parses stream headers from an HTTP response.
+ *
+ * @example
+ * const headers = response.headers;
+ * const stream = parseStreamHeaders(headers);
+ * console.log(stream.nextOffset); // '210'
+ */
+export function parseStreamHeaders(headers: Headers): StreamResponseHeaders {
+  const nextOffset = headers.get(HEADER_NEXT_OFFSET) ?? '';
+  const upToDateStr = headers.get(HEADER_UP_TO_DATE);
+  const closedStr = headers.get(HEADER_CLOSED);
+  const cursor = headers.get(HEADER_CURSOR) ?? undefined;
+  const etag = headers.get('ETag') ?? undefined;
+
+  const result: StreamResponseHeaders = {
+    nextOffset,
+  };
+
+  if (upToDateStr !== null) {
+    result.upToDate = upToDateStr === 'true';
+  }
+
+  if (closedStr !== null) {
+    result.closed = closedStr === 'true';
+  }
+
+  if (cursor) {
+    result.cursor = cursor;
+  }
+
+  if (etag) {
+    result.etag = etag;
+  }
+
+  return result;
+}
+
+/**
+ * Formats stream headers for an HTTP response.
+ *
+ * @example
+ * const headers = formatStreamHeaders({ nextOffset: '210', upToDate: true });
+ * response.headers = headers;
+ */
+export function formatStreamHeaders(stream: StreamResponseHeaders): Headers {
+  const headers = new Headers();
+
+  headers.set(HEADER_NEXT_OFFSET, stream.nextOffset);
+
+  if (stream.upToDate !== undefined) {
+    headers.set(HEADER_UP_TO_DATE, String(stream.upToDate));
+  }
+
+  if (stream.closed !== undefined) {
+    headers.set(HEADER_CLOSED, String(stream.closed));
+  }
+
+  if (stream.cursor !== undefined) {
+    headers.set(HEADER_CURSOR, stream.cursor);
+  }
+
+  if (stream.etag !== undefined) {
+    headers.set('ETag', stream.etag);
+  }
+
+  return headers;
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+// ABOUTME: Durable Streams protocol types and utilities
+// ABOUTME: Zero-dependency package for protocol compliance across clients and servers
+
+// Offset encoding/decoding
+export {
+  encodeOffset,
+  decodeOffset,
+  OFFSET_BEGINNING,
+  OFFSET_NOW,
+} from './offset.js';
+
+// SSE formatting and parsing
+export {
+  formatSSEDataEvent,
+  formatSSEControlEvent,
+  parseSSEEvent,
+  SSE_RETRY_MS,
+  type SSEDataEvent,
+  type SSEControlEvent,
+  type SSEEvent,
+  type SSEControlPayload,
+} from './sse.js';
+
+// HTTP header utilities
+export {
+  parseStreamHeaders,
+  formatStreamHeaders,
+  HEADER_NEXT_OFFSET,
+  HEADER_UP_TO_DATE,
+  HEADER_CLOSED,
+  HEADER_CURSOR,
+  DEFAULT_POLL_INTERVAL,
+  type StreamResponseHeaders,
+} from './headers.js';
+
+// WebSocket protocol types
+export {
+  isWSClientMessage,
+  isWSServerMessage,
+  parseWSClientMessage,
+  parseWSServerMessage,
+  serializeWSMessage,
+  type WSClientMessage,
+  type WSServerMessage,
+  type WSConnectedMessage,
+  type WSSubscribeMessage,
+  type WSUnsubscribeMessage,
+  type WSPingMessage,
+  type WSSubscribedMessage,
+  type WSUnsubscribedMessage,
+  type WSEventMessage,
+  type WSStatusMessage,
+  type WSErrorMessage,
+  type WSPongMessage,
+} from './websocket.js';

package/src/offset.ts

@@ -0,0 +1,80 @@
+// ABOUTME: Offset encoding/decoding utilities for Durable Streams protocol
+// ABOUTME: Uses length-prefixed base-36 encoding for lexicographic ordering
+
+/**
+ * Special offset value indicating "from beginning" of stream.
+ */
+export const OFFSET_BEGINNING = '-1';
+
+/**
+ * Special offset value indicating "from current tail" (live mode).
+ */
+export const OFFSET_NOW = 'now';
+
+/**
+ * Encodes a bigint event ID to a lexicographically sortable offset string.
+ *
+ * Uses length-prefixed base-36 encoding:
+ * - First character indicates the length of the base-36 representation
+ * - Remaining characters are the base-36 encoded value
+ *
+ * This ensures that smaller numeric values always sort before larger ones
+ * when using string comparison.
+ *
+ * @example
+ * encodeOffset(0n)   // '10'   (length 1, value '0')
+ * encodeOffset(35n)  // '1z'   (length 1, value 'z')
+ * encodeOffset(36n)  // '210'  (length 2, value '10')
+ * encodeOffset(1295n) // '2zz' (length 2, value 'zz')
+ */
+export function encodeOffset(id: bigint): string {
+  if (id < 0n) {
+    throw new Error('Offset ID must be non-negative');
+  }
+
+  const base36 = id.toString(36);
+  const length = base36.length;
+
+  // Use base-36 character for length prefix (supports up to 35 digits)
+  // 35 base-36 digits can represent numbers up to 36^35 - 1, which is enormous
+  if (length > 35) {
+    throw new Error('Offset ID too large');
+  }
+
+  const lengthPrefix = length.toString(36);
+  return lengthPrefix + base36;
+}
+
+/**
+ * Decodes a lexicographically sortable offset string back to a bigint.
+ *
+ * Inverse of encodeOffset.
+ *
+ * @example
+ * decodeOffset('10')  // 0n
+ * decodeOffset('1z')  // 35n
+ * decodeOffset('210') // 36n
+ */
+export function decodeOffset(offset: string): bigint {
+  if (offset.length < 2) {
+    throw new Error('Invalid offset format');
+  }
+
+  const lengthPrefix = offset[0]!;
+  const expectedLength = parseInt(lengthPrefix, 36);
+  const base36Value = offset.slice(1);
+
+  if (base36Value.length !== expectedLength) {
+    throw new Error(
+      `Invalid offset format: expected ${expectedLength} digits, got ${base36Value.length}`
+    );
+  }
+
+  // Parse base-36 string to bigint
+  // BigInt doesn't have native base-36 parsing, so we do it manually
+  let result = 0n;
+  for (const char of base36Value) {
+    result = result * 36n + BigInt(parseInt(char, 36));
+  }
+  return result;
+}

package/src/sse.ts

@@ -0,0 +1,164 @@
+// ABOUTME: SSE (Server-Sent Events) formatting and parsing utilities
+// ABOUTME: Implements two-event model (data + control) per Durable Streams spec
+
+/**
+ * Default retry interval in milliseconds for SSE connections.
+ */
+export const SSE_RETRY_MS = 3000;
+
+/**
+ * SSE data event containing actual stream payload.
+ */
+export interface SSEDataEvent<T = unknown> {
+  event: 'data';
+  data: T;
+}
+
+/**
+ * SSE control event containing stream metadata.
+ */
+export interface SSEControlEvent {
+  event: 'control';
+  streamNextOffset: string;
+  streamCursor?: string;
+  upToDate?: boolean;
+  streamClosed?: boolean;
+}
+
+/**
+ * Union type for all SSE events in the Durable Streams protocol.
+ */
+export type SSEEvent<T = unknown> = SSEDataEvent<T> | SSEControlEvent;
+
+/**
+ * Control event payload (without the 'event' discriminator).
+ */
+export interface SSEControlPayload {
+  streamNextOffset: string;
+  streamCursor?: string;
+  upToDate?: boolean;
+  streamClosed?: boolean;
+}
+
+/**
+ * Formats a data payload as an SSE data event string.
+ *
+ * @example
+ * formatSSEDataEvent({ type: 'message' })
+ * // Returns: 'event: data\ndata: {"type":"message"}\n\n'
+ */
+export function formatSSEDataEvent(data: unknown): string {
+  const json = JSON.stringify(data);
+  return `event: data\ndata: ${json}\n\n`;
+}
+
+/**
+ * Formats control metadata as an SSE control event string.
+ *
+ * @example
+ * formatSSEControlEvent({ streamNextOffset: '210', upToDate: true })
+ * // Returns: 'event: control\ndata: {"streamNextOffset":"210","upToDate":true}\n\n'
+ */
+export function formatSSEControlEvent(control: SSEControlPayload): string {
+  // Only include defined fields
+  const payload: Record<string, unknown> = {
+    streamNextOffset: control.streamNextOffset,
+  };
+
+  if (control.streamCursor !== undefined) {
+    payload.streamCursor = control.streamCursor;
+  }
+  if (control.upToDate !== undefined) {
+    payload.upToDate = control.upToDate;
+  }
+  if (control.streamClosed !== undefined) {
+    payload.streamClosed = control.streamClosed;
+  }
+
+  const json = JSON.stringify(payload);
+  return `event: control\ndata: ${json}\n\n`;
+}
+
+/**
+ * Parses an SSE event block (lines between double newlines).
+ *
+ * Returns null for empty input, comments, or non-data/control events.
+ *
+ * @example
+ * parseSSEEvent('event: data\ndata: {"type":"message"}')
+ * // Returns: { event: 'data', data: { type: 'message' } }
+ */
+export function parseSSEEvent(block: string): SSEEvent | null {
+  if (!block || block.trim() === '') {
+    return null;
+  }
+
+  const lines = block.split('\n');
+  let eventType: string | null = null;
+  const dataLines: string[] = [];
+
+  for (const line of lines) {
+    // Skip comments
+    if (line.startsWith(':')) {
+      continue;
+    }
+
+    // Parse event type
+    if (line.startsWith('event:')) {
+      eventType = line.slice(6).trim();
+      continue;
+    }
+
+    // Parse data lines
+    if (line.startsWith('data:')) {
+      dataLines.push(line.slice(5).trim());
+      continue;
+    }
+
+    // Handle "data:" without space (per SSE spec)
+    if (line.startsWith('data')) {
+      const colonIndex = line.indexOf(':');
+      if (colonIndex !== -1) {
+        dataLines.push(line.slice(colonIndex + 1).trim());
+      }
+    }
+  }
+
+  // Only process data and control events
+  if (eventType !== 'data' && eventType !== 'control') {
+    return null;
+  }
+
+  if (dataLines.length === 0) {
+    return null;
+  }
+
+  // Concatenate data lines (per SSE spec, they should be joined with newlines)
+  const dataString = dataLines.join('\n');
+
+  try {
+    const parsed = JSON.parse(dataString);
+
+    if (eventType === 'data') {
+      return {
+        event: 'data',
+        data: parsed,
+      };
+    }
+
+    if (eventType === 'control') {
+      return {
+        event: 'control',
+        streamNextOffset: parsed.streamNextOffset,
+        streamCursor: parsed.streamCursor,
+        upToDate: parsed.upToDate,
+        streamClosed: parsed.streamClosed,
+      };
+    }
+  } catch {
+    // Invalid JSON - return null
+    return null;
+  }
+
+  return null;
+}

package/src/websocket.ts

@@ -0,0 +1,187 @@
+// ABOUTME: WebSocket protocol types for Durable Streams
+// ABOUTME: Defines client-to-server and server-to-client message formats
+
+/**
+ * Messages sent from client to server over WebSocket.
+ */
+export type WSClientMessage =
+  | WSSubscribeMessage
+  | WSUnsubscribeMessage
+  | WSPingMessage;
+
+/**
+ * Subscribe to a stream from a given offset.
+ */
+export interface WSSubscribeMessage {
+  type: 'subscribe';
+  /** Stream ID to subscribe to */
+  streamId: string;
+  /** Starting offset, defaults to '-1' (beginning) */
+  offset?: string;
+}
+
+/**
+ * Unsubscribe from a stream.
+ */
+export interface WSUnsubscribeMessage {
+  type: 'unsubscribe';
+  /** Stream ID to unsubscribe from */
+  streamId: string;
+}
+
+/**
+ * Ping message for keepalive.
+ */
+export interface WSPingMessage {
+  type: 'ping';
+}
+
+/**
+ * Messages sent from server to client over WebSocket.
+ */
+export type WSServerMessage =
+  | WSConnectedMessage
+  | WSSubscribedMessage
+  | WSUnsubscribedMessage
+  | WSEventMessage
+  | WSStatusMessage
+  | WSErrorMessage
+  | WSPongMessage;
+
+/**
+ * Connection acknowledgment with assigned client ID.
+ */
+export interface WSConnectedMessage {
+  type: 'connected';
+  /** Client ID for this connection */
+  clientId: string;
+}
+
+/**
+ * Confirmation of successful subscription.
+ */
+export interface WSSubscribedMessage {
+  type: 'subscribed';
+  /** Stream ID subscribed to */
+  streamId: string;
+  /** Current offset position */
+  offset: string;
+}
+
+/**
+ * Confirmation of unsubscription.
+ */
+export interface WSUnsubscribedMessage {
+  type: 'unsubscribed';
+  /** Stream ID unsubscribed from */
+  streamId: string;
+}
+
+/**
+ * Stream event delivery.
+ */
+export interface WSEventMessage {
+  type: 'event';
+  /** Stream ID this event belongs to */
+  streamId: string;
+  /** Event payload */
+  event: unknown;
+  /** Offset after this event */
+  nextOffset: string;
+}
+
+/**
+ * Stream status update.
+ */
+export interface WSStatusMessage {
+  type: 'status';
+  /** Stream ID */
+  streamId: string;
+  /** True when caught up to tail */
+  upToDate: boolean;
+  /** True when stream is permanently closed */
+  closed?: boolean;
+}
+
+/**
+ * Error message.
+ */
+export interface WSErrorMessage {
+  type: 'error';
+  /** Human-readable error message */
+  message: string;
+  /** Machine-readable error code */
+  code?: string;
+  /** Stream ID if error is stream-specific */
+  streamId?: string;
+}
+
+/**
+ * Pong response to ping.
+ */
+export interface WSPongMessage {
+  type: 'pong';
+}
+
+/**
+ * Type guard for client messages.
+ */
+export function isWSClientMessage(msg: unknown): msg is WSClientMessage {
+  if (typeof msg !== 'object' || msg === null) return false;
+  const { type } = msg as { type?: unknown };
+  return type === 'subscribe' || type === 'unsubscribe' || type === 'ping';
+}
+
+/**
+ * Type guard for server messages.
+ */
+export function isWSServerMessage(msg: unknown): msg is WSServerMessage {
+  if (typeof msg !== 'object' || msg === null) return false;
+  const { type } = msg as { type?: unknown };
+  return (
+    type === 'connected' ||
+    type === 'subscribed' ||
+    type === 'unsubscribed' ||
+    type === 'event' ||
+    type === 'status' ||
+    type === 'error' ||
+    type === 'pong'
+  );
+}
+
+/**
+ * Parse a JSON string as a client message.
+ */
+export function parseWSClientMessage(json: string): WSClientMessage | null {
+  try {
+    const parsed = JSON.parse(json);
+    if (isWSClientMessage(parsed)) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a JSON string as a server message.
+ */
+export function parseWSServerMessage(json: string): WSServerMessage | null {
+  try {
+    const parsed = JSON.parse(json);
+    if (isWSServerMessage(parsed)) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Serialize a message to JSON string.
+ */
+export function serializeWSMessage(msg: WSClientMessage | WSServerMessage): string {
+  return JSON.stringify(msg);
+}