@kyneta/sse-transport 1.1.0

package/dist/chunk-TR4Y3HFB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connection.ts","../src/server-transport.ts"],"sourcesContent":["// connection — SseConnection for server-side peer connections.\n//\n// Wraps a TextReassembler + textCodec to provide send/receive for\n// ChannelMsg over a single SSE connection.\n//\n// Used by SseServerTransport to manage individual client connections.\n// The client adapter handles its own encoding/decoding inline since it\n// manages a single EventSource with reconnection logic.\n//\n// The sendFn receives pre-encoded text frame strings. Framework\n// integrations just wrap them in SSE syntax:\n//   Express: res.write(`data: ${textFrame}\\n\\n`)\n//   Hono:    stream.writeSSE({ data: textFrame })\n\nimport type { Channel, ChannelMsg, PeerId } from \"@kyneta/exchange\"\nimport {\n  encodeTextComplete,\n  fragmentTextPayload,\n  TextReassembler,\n  textCodec,\n} from \"@kyneta/wire\"\n\n/**\n * Default fragment threshold in characters for outbound SSE messages.\n * 60K chars provides a safety margin below typical infrastructure limits.\n */\nexport const DEFAULT_FRAGMENT_THRESHOLD = 60_000\n\n/**\n * Configuration for creating an SseConnection.\n */\nexport interface SseConnectionConfig {\n  /**\n   * Fragment threshold in characters. Messages larger than this are fragmented.\n   * Set to 0 to disable fragmentation.\n   * Default: 60000 (60K chars)\n   */\n  fragmentThreshold?: number\n}\n\n/**\n * Represents a single SSE connection to a peer (server-side).\n *\n * Manages encoding, framing, fragmentation, and reassembly for one\n * connected client. Created by `SseServerTransport.registerConnection()`.\n *\n * The connection uses the text codec for transport — this is the natural\n * choice for SSE's text-only protocol.\n */\nexport class SseConnection {\n  readonly peerId: PeerId\n  readonly channelId: number\n\n  #channel: Channel | null = null\n  #sendFn: ((textFrame: string) => void) | null = null\n  #onDisconnect: (() => void) | null = null\n\n  // Fragmentation support\n  readonly #fragmentThreshold: number\n\n  /**\n   * Text reassembler for handling fragmented POST bodies.\n   * Each connection has its own reassembler to track in-flight fragment batches.\n   */\n  readonly reassembler: TextReassembler\n\n  constructor(peerId: PeerId, channelId: number, config?: SseConnectionConfig) {\n    this.peerId = peerId\n    this.channelId = channelId\n    this.#fragmentThreshold =\n      config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n    this.reassembler = new TextReassembler({\n      timeoutMs: 10_000,\n      onTimeout: (frameId: string) => {\n        console.warn(\n          `[SseConnection] Fragment batch timed out for peer ${peerId}: ${frameId}`,\n        )\n      },\n    })\n  }\n\n  // ==========================================================================\n  // INTERNAL API — for adapter use\n  // ==========================================================================\n\n  /**\n   * Set the channel reference.\n   * Called by the adapter when the channel is created.\n   * @internal\n   */\n  _setChannel(channel: Channel): void {\n    this.#channel = channel\n  }\n\n  // ==========================================================================\n  // PUBLIC API\n  // ==========================================================================\n\n  /**\n   * Set the function to call when sending messages to this peer.\n   *\n   * The function receives a fully encoded text frame string.\n   * The framework integration just wraps it in SSE syntax:\n   * - Express: `res.write(\\`data: \\${textFrame}\\\\n\\\\n\\`)`\n   * - Hono: `stream.writeSSE({ data: textFrame })`\n   *\n   * @param sendFn Function that writes a text frame string to the SSE stream\n   */\n  setSendFunction(sendFn: (textFrame: string) => void): void {\n    this.#sendFn = sendFn\n  }\n\n  /**\n   * Set the function to call when this connection is disconnected.\n   */\n  setDisconnectHandler(handler: () => void): void {\n    this.#onDisconnect = handler\n  }\n\n  /**\n   * Send a ChannelMsg to the peer through the SSE stream.\n   *\n   * Encodes via textCodec → text frame → fragment if needed → sendFn().\n   * Encoding and fragmentation are the connection's concern — the\n   * framework integration only needs to write strings.\n   */\n  send(msg: ChannelMsg): void {\n    if (!this.#sendFn) {\n      throw new Error(\n        `Cannot send message: send function not set for peer ${this.peerId}`,\n      )\n    }\n\n    // Encode to text wire format\n    const textFrame = encodeTextComplete(textCodec, msg)\n\n    // Fragment large payloads\n    if (\n      this.#fragmentThreshold > 0 &&\n      textFrame.length > this.#fragmentThreshold\n    ) {\n      const payload = JSON.stringify(textCodec.encode(msg))\n      const fragments = fragmentTextPayload(payload, this.#fragmentThreshold)\n      for (const fragment of fragments) {\n        this.#sendFn(fragment)\n      }\n    } else {\n      this.#sendFn(textFrame)\n    }\n  }\n\n  /**\n   * Receive a message from the peer and route it to the channel.\n   *\n   * Called by the framework integration after parsing a POST body\n   * through `parseTextPostBody`.\n   */\n  receive(msg: ChannelMsg): void {\n    if (!this.#channel) {\n      throw new Error(\n        `Cannot receive message: channel not set for peer ${this.peerId}`,\n      )\n    }\n    this.#channel.onReceive(msg)\n  }\n\n  /**\n   * Disconnect this connection.\n   */\n  disconnect(): void {\n    this.#onDisconnect?.()\n  }\n\n  /**\n   * Dispose of resources held by this connection.\n   * Must be called when the connection is closed to prevent timer leaks.\n   */\n  dispose(): void {\n    this.reassembler.dispose()\n  }\n}\n","// server-adapter — SSE server adapter for @kyneta/exchange.\n//\n// Manages SSE connections from clients, encoding/decoding via the\n// kyneta text wire format. Framework-agnostic — works with any HTTP\n// framework through the SseConnection's setSendFunction() callback.\n//\n// Usage with Express:\n//   import { SseServerTransport } from \"@kyneta/sse-network-adapter/server\"\n//   import { createSseExpressRouter } from \"@kyneta/sse-network-adapter/express\"\n//\n//   const serverAdapter = new SseServerTransport()\n//   app.use(\"/sse\", createSseExpressRouter(serverAdapter))\n//\n// Usage with Hono:\n//   import { SseServerTransport } from \"@kyneta/sse-network-adapter/server\"\n//   import { parseTextPostBody } from \"@kyneta/sse-network-adapter/express\"\n//\n//   const serverAdapter = new SseServerTransport()\n//   // Wire up GET /events and POST /sync manually using\n//   // serverAdapter.registerConnection() and parseTextPostBody()\n\nimport type { ChannelMsg, GeneratedChannel, PeerId } from \"@kyneta/exchange\"\nimport { Transport } from \"@kyneta/exchange\"\nimport {\n  DEFAULT_FRAGMENT_THRESHOLD,\n  SseConnection,\n  type SseConnectionConfig,\n} from \"./connection.js\"\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the SSE server adapter.\n */\nexport interface SseServerTransportOptions {\n  /**\n   * Fragment threshold in characters. Messages larger than this are fragmented\n   * into multiple SSE events.\n   * Set to 0 to disable fragmentation.\n   * Default: 60000 (60K chars)\n   */\n  fragmentThreshold?: number\n}\n\n// ---------------------------------------------------------------------------\n// Peer ID generation\n// ---------------------------------------------------------------------------\n\n/**\n * Generate a random peer ID for connections that don't provide one.\n */\nfunction generatePeerId(): PeerId {\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\"\n  let result = \"sse-\"\n  for (let i = 0; i < 12; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length))\n  }\n  return result\n}\n\n// ---------------------------------------------------------------------------\n// SseServerTransport\n// ---------------------------------------------------------------------------\n\n/**\n * SSE server network adapter.\n *\n * Framework-agnostic — works with any HTTP framework through the\n * `SseConnection.setSendFunction()` callback. Use `registerConnection()`\n * to integrate with your framework's SSE endpoint handler.\n *\n * Each client connection is tracked as an `SseConnection` keyed by peer ID.\n * The adapter creates a channel per connection and routes outbound messages\n * through the connection's send method (which encodes to text wire format\n * and calls the injected sendFn).\n *\n * The connection handshake:\n * 1. Client opens EventSource (GET /events)\n * 2. Server calls `registerConnection(peerId)` → creates channel\n * 3. Client's EventSource.onopen fires → client sends establish-request (POST)\n * 4. Server receives establish-request → Synchronizer responds with establish-response (SSE)\n *\n * The server does NOT call `establishChannel()` — it waits for the client's\n * establish-request, which arrives via POST after the EventSource is open.\n */\nexport class SseServerTransport extends Transport<PeerId> {\n  #connections = new Map<PeerId, SseConnection>()\n  readonly #fragmentThreshold: number\n\n  constructor(options?: SseServerTransportOptions) {\n    super({ transportType: \"sse-server\" })\n    this.#fragmentThreshold =\n      options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n  }\n\n  // ==========================================================================\n  // Adapter abstract method implementations\n  // ==========================================================================\n\n  protected generate(peerId: PeerId): GeneratedChannel {\n    return {\n      transportType: this.transportType,\n      send: (msg: ChannelMsg) => {\n        const connection = this.#connections.get(peerId)\n        if (connection) {\n          connection.send(msg)\n        }\n      },\n      stop: () => {\n        this.unregisterConnection(peerId)\n      },\n    }\n  }\n\n  async onStart(): Promise<void> {\n    // Server adapter starts passively — connections arrive via registerConnection()\n  }\n\n  async onStop(): Promise<void> {\n    // Disconnect all active connections\n    for (const connection of this.#connections.values()) {\n      connection.disconnect()\n    }\n    this.#connections.clear()\n  }\n\n  // ==========================================================================\n  // Connection management\n  // ==========================================================================\n\n  /**\n   * Register a new peer connection.\n   *\n   * Call this from your framework's SSE endpoint handler when a client\n   * connects via EventSource. Returns an `SseConnection` that you wire\n   * up with `setSendFunction()` and `setDisconnectHandler()`.\n   *\n   * @param peerId The unique identifier for the peer (from query param or header)\n   * @returns An SseConnection object for managing the connection\n   *\n   * @example Express\n   * ```typescript\n   * const connection = serverAdapter.registerConnection(peerId)\n   * connection.setSendFunction((textFrame) => {\n   *   res.write(`data: ${textFrame}\\n\\n`)\n   * })\n   * ```\n   *\n   * @example Hono\n   * ```typescript\n   * const connection = serverAdapter.registerConnection(peerId)\n   * connection.setSendFunction((textFrame) => {\n   *   stream.writeSSE({ data: textFrame })\n   * })\n   * ```\n   */\n  registerConnection(peerId?: PeerId): SseConnection {\n    const resolvedPeerId = peerId ?? generatePeerId()\n\n    // Check for existing connection and clean it up\n    const existingConnection = this.#connections.get(resolvedPeerId)\n    if (existingConnection) {\n      existingConnection.dispose()\n      this.unregisterConnection(resolvedPeerId)\n    }\n\n    // Create channel for this peer\n    const channel = this.addChannel(resolvedPeerId)\n\n    // Create connection object with fragmentation config\n    const connection = new SseConnection(resolvedPeerId, channel.channelId, {\n      fragmentThreshold: this.#fragmentThreshold,\n    })\n    connection._setChannel(channel)\n\n    // Store connection\n    this.#connections.set(resolvedPeerId, connection)\n\n    return connection\n  }\n\n  /**\n   * Unregister a peer connection.\n   *\n   * Removes the channel, disposes the connection's reassembler,\n   * and cleans up tracking state. Called automatically when the\n   * client disconnects (via req.on(\"close\")) or manually.\n   *\n   * @param peerId The unique identifier for the peer\n   */\n  unregisterConnection(peerId: PeerId): void {\n    const connection = this.#connections.get(peerId)\n    if (connection) {\n      connection.dispose()\n      this.removeChannel(connection.channelId)\n      this.#connections.delete(peerId)\n    }\n  }\n\n  /**\n   * Get an active connection by peer ID.\n   */\n  getConnection(peerId: PeerId): SseConnection | undefined {\n    return this.#connections.get(peerId)\n  }\n\n  /**\n   * Get all active connections.\n   */\n  getAllConnections(): SseConnection[] {\n    return Array.from(this.#connections.values())\n  }\n\n  /**\n   * Check if a peer is connected.\n   */\n  isConnected(peerId: PeerId): boolean {\n    return this.#connections.has(peerId)\n  }\n\n  /**\n   * Get the number of connected peers.\n   */\n  get connectionCount(): number {\n    return this.#connections.size\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/client.d.ts

@@ -0,0 +1,144 @@
+import { PeerId, Transport, TransitionListener, GeneratedChannel, TransportFactory, ClientStateMachine } from '@kyneta/exchange';
+export { StateTransition, TransitionListener } from '@kyneta/exchange';
+import { b as SseClientLifecycleEvents, c as SseClientState } from './types-BTgljZGe.js';
+export { D as DisconnectReason } from './types-BTgljZGe.js';
+
+/**
+ * Default fragment threshold in characters.
+ * 60K chars provides a safety margin below typical 100KB body-parser limits,
+ * accounting for JSON overhead and potential base64 expansion.
+ */
+declare const DEFAULT_FRAGMENT_THRESHOLD = 60000;
+/**
+ * Options for the SSE client adapter.
+ */
+interface SseClientOptions {
+    /** URL for POST requests (client→server). String or function of peerId. */
+    postUrl: string | ((peerId: PeerId) => string);
+    /** URL for SSE EventSource (server→client). String or function of peerId. */
+    eventSourceUrl: string | ((peerId: PeerId) => string);
+    /** Reconnection options for EventSource. */
+    reconnect?: {
+        enabled?: boolean;
+        maxAttempts?: number;
+        baseDelay?: number;
+        maxDelay?: number;
+    };
+    /** POST retry options. */
+    postRetry?: {
+        maxAttempts?: number;
+        baseDelay?: number;
+        maxDelay?: number;
+    };
+    /** Fragment threshold in characters. Default: 60000 (60K chars). */
+    fragmentThreshold?: number;
+    /** Lifecycle event callbacks. */
+    lifecycle?: SseClientLifecycleEvents;
+}
+/**
+ * SSE client network adapter for @kyneta/exchange.
+ *
+ * Uses two HTTP channels:
+ * - **EventSource** (GET, long-lived) for server→client messages
+ * - **fetch POST** for client→server messages
+ *
+ * Both directions use the text wire format (`textCodec` + text framing).
+ *
+ * @example
+ * ```typescript
+ * import { createSseClient } from "@kyneta/sse-network-adapter/client"
+ *
+ * const adapter = createSseClient({
+ *   postUrl: "/sync",
+ *   eventSourceUrl: (peerId) => `/events?peerId=${peerId}`,
+ *   reconnect: { enabled: true },
+ * })
+ *
+ * const exchange = new Exchange({
+ *   identity: { peerId: "browser-client" },
+ *   transports: [adapter],
+ * })
+ * ```
+ */
+declare class SseClientTransport extends Transport<void> {
+    #private;
+    constructor(options: SseClientOptions);
+    /**
+     * Get the current state of the connection.
+     */
+    getState(): SseClientState;
+    /**
+     * Subscribe to state transitions.
+     * @returns Unsubscribe function
+     */
+    subscribeToTransitions(listener: TransitionListener<SseClientState>): () => void;
+    /**
+     * Wait for a specific state.
+     */
+    waitForState(predicate: (state: SseClientState) => boolean, options?: {
+        timeoutMs?: number;
+    }): Promise<SseClientState>;
+    /**
+     * Wait for a specific status.
+     */
+    waitForStatus(status: SseClientState["status"], options?: {
+        timeoutMs?: number;
+    }): Promise<SseClientState>;
+    /**
+     * Check if the client is connected (EventSource open, channel established).
+     */
+    get isConnected(): boolean;
+    protected generate(): GeneratedChannel;
+    onStart(): Promise<void>;
+    onStop(): Promise<void>;
+}
+/**
+ * Create an SSE client adapter for browser-to-server connections.
+ *
+ * @example
+ * ```typescript
+ * import { createSseClient } from "@kyneta/sse-network-adapter/client"
+ *
+ * const exchange = new Exchange({
+ *   transports: [createSseClient({
+ *     postUrl: "/sync",
+ *     eventSourceUrl: (peerId) => `/events?peerId=${peerId}`,
+ *     reconnect: { enabled: true },
+ *   })],
+ * })
+ * ```
+ */
+declare function createSseClient(options: SseClientOptions): TransportFactory;
+
+/**
+ * Observable state machine for SSE client connection lifecycle.
+ *
+ * Extends the generic `ClientStateMachine<SseClientState>` with
+ * an SSE-specific convenience helper. Unlike the WebSocket state machine,
+ * SSE has no `"ready"` state — the connection is usable as soon as
+ * `EventSource.onopen` fires.
+ *
+ * Usage:
+ * ```typescript
+ * const sm = new SseClientStateMachine()
+ *
+ * sm.subscribeToTransitions(({ from, to }) => {
+ *   console.log(`${from.status} → ${to.status}`)
+ * })
+ *
+ * sm.transition({ status: "connecting", attempt: 1 })
+ * sm.transition({ status: "connected" })
+ *
+ * // Transitions are delivered asynchronously via microtask
+ * // Listener will see: disconnected → connecting, connecting → connected
+ * ```
+ */
+declare class SseClientStateMachine extends ClientStateMachine<SseClientState> {
+    constructor();
+    /**
+     * Check if the client is connected (EventSource open, channel established).
+     */
+    isConnected(): boolean;
+}
+
+export { DEFAULT_FRAGMENT_THRESHOLD, SseClientLifecycleEvents, type SseClientOptions, SseClientState, SseClientStateMachine, SseClientTransport, createSseClient };

package/dist/client.js

@@ -0,0 +1,460 @@
+import "./chunk-7D4SUZUM.js";
+
+// src/client-transport.ts
+import { Transport } from "@kyneta/exchange";
+import {
+  encodeTextComplete,
+  fragmentTextPayload,
+  TextReassembler,
+  textCodec
+} from "@kyneta/wire";
+
+// src/client-state-machine.ts
+import { ClientStateMachine } from "@kyneta/exchange";
+var SSE_VALID_TRANSITIONS = {
+  disconnected: ["connecting"],
+  connecting: ["connected", "disconnected", "reconnecting"],
+  connected: ["disconnected", "reconnecting"],
+  reconnecting: ["connecting", "disconnected"]
+};
+var SseClientStateMachine = class extends ClientStateMachine {
+  constructor() {
+    super({
+      initialState: { status: "disconnected" },
+      validTransitions: SSE_VALID_TRANSITIONS
+    });
+  }
+  /**
+   * Check if the client is connected (EventSource open, channel established).
+   */
+  isConnected() {
+    return this.getStatus() === "connected";
+  }
+};
+
+// src/client-transport.ts
+var DEFAULT_FRAGMENT_THRESHOLD = 6e4;
+var DEFAULT_RECONNECT = {
+  enabled: true,
+  maxAttempts: 10,
+  baseDelay: 1e3,
+  maxDelay: 3e4
+};
+var DEFAULT_POST_RETRY = {
+  maxAttempts: 3,
+  baseDelay: 1e3,
+  maxDelay: 1e4
+};
+var SseClientTransport = class extends Transport {
+  #peerId;
+  #eventSource;
+  #serverChannel;
+  #reconnectTimer;
+  #options;
+  #shouldReconnect = true;
+  #wasConnectedBefore = false;
+  // State machine
+  #stateMachine = new SseClientStateMachine();
+  // Fragmentation
+  #fragmentThreshold;
+  // Inbound reassembly for fragmented SSE messages from server
+  #reassembler;
+  // POST retry
+  #currentRetryAbortController;
+  constructor(options) {
+    super({ transportType: "sse-client" });
+    this.#options = options;
+    this.#fragmentThreshold = options.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD;
+    this.#reassembler = new TextReassembler({
+      timeoutMs: 1e4
+    });
+    this.#setupLifecycleEvents();
+  }
+  // ==========================================================================
+  // Lifecycle event forwarding
+  // ==========================================================================
+  #setupLifecycleEvents() {
+    this.#stateMachine.subscribeToTransitions((transition) => {
+      this.#options.lifecycle?.onStateChange?.(transition);
+      const { from, to } = transition;
+      if (to.status === "disconnected" && to.reason) {
+        this.#options.lifecycle?.onDisconnect?.(to.reason);
+      }
+      if (to.status === "reconnecting") {
+        this.#options.lifecycle?.onReconnecting?.(to.attempt, to.nextAttemptMs);
+      }
+      if (this.#wasConnectedBefore && (from.status === "reconnecting" || from.status === "connecting") && to.status === "connected") {
+        this.#options.lifecycle?.onReconnected?.();
+      }
+    });
+  }
+  // ==========================================================================
+  // State observation API
+  // ==========================================================================
+  /**
+   * Get the current state of the connection.
+   */
+  getState() {
+    return this.#stateMachine.getState();
+  }
+  /**
+   * Subscribe to state transitions.
+   * @returns Unsubscribe function
+   */
+  subscribeToTransitions(listener) {
+    return this.#stateMachine.subscribeToTransitions(listener);
+  }
+  /**
+   * Wait for a specific state.
+   */
+  waitForState(predicate, options) {
+    return this.#stateMachine.waitForState(predicate, options);
+  }
+  /**
+   * Wait for a specific status.
+   */
+  waitForStatus(status, options) {
+    return this.#stateMachine.waitForStatus(status, options);
+  }
+  /**
+   * Check if the client is connected (EventSource open, channel established).
+   */
+  get isConnected() {
+    return this.#stateMachine.isConnected();
+  }
+  // ==========================================================================
+  // Adapter abstract method implementations
+  // ==========================================================================
+  generate() {
+    return {
+      transportType: this.transportType,
+      send: (msg) => {
+        if (!this.#peerId) {
+          return;
+        }
+        if (!this.#eventSource || this.#eventSource.readyState === 2) {
+          return;
+        }
+        const resolvedPostUrl = typeof this.#options.postUrl === "function" ? this.#options.postUrl(this.#peerId) : this.#options.postUrl;
+        const textFrame = encodeTextComplete(textCodec, msg);
+        if (this.#fragmentThreshold > 0 && textFrame.length > this.#fragmentThreshold) {
+          const payload = JSON.stringify(textCodec.encode(msg));
+          const fragments = fragmentTextPayload(
+            payload,
+            this.#fragmentThreshold
+          );
+          for (const fragment of fragments) {
+            void this.#sendTextWithRetry(resolvedPostUrl, fragment);
+          }
+        } else {
+          void this.#sendTextWithRetry(resolvedPostUrl, textFrame);
+        }
+      },
+      stop: () => {
+      }
+    };
+  }
+  async onStart() {
+    if (!this.identity) {
+      throw new Error(
+        "Adapter not properly initialized \u2014 identity not available"
+      );
+    }
+    this.#peerId = this.identity.peerId;
+    this.#shouldReconnect = true;
+    this.#wasConnectedBefore = false;
+    this.#connect();
+  }
+  async onStop() {
+    this.#shouldReconnect = false;
+    this.#reassembler.dispose();
+    this.#currentRetryAbortController?.abort();
+    this.#currentRetryAbortController = void 0;
+    this.#disconnect({ type: "intentional" });
+  }
+  // ==========================================================================
+  // Connection management
+  // ==========================================================================
+  /**
+   * Connect to the SSE server by creating an EventSource.
+   */
+  #connect() {
+    const currentState = this.#stateMachine.getState();
+    if (currentState.status === "connecting") {
+      return;
+    }
+    if (!this.#peerId) {
+      throw new Error("Cannot connect: peerId not set");
+    }
+    const attempt = currentState.status === "reconnecting" ? currentState.attempt : 1;
+    this.#stateMachine.transition({ status: "connecting", attempt });
+    const url = typeof this.#options.eventSourceUrl === "function" ? this.#options.eventSourceUrl(this.#peerId) : this.#options.eventSourceUrl;
+    try {
+      this.#eventSource = new EventSource(url);
+      this.#eventSource.onopen = () => {
+        this.#handleOpen();
+      };
+      this.#eventSource.onmessage = (event) => {
+        this.#handleMessage(event);
+      };
+      this.#eventSource.onerror = () => {
+        this.#handleError();
+      };
+    } catch (error) {
+      this.#scheduleReconnect({
+        type: "error",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Disconnect from the SSE server.
+   */
+  #disconnect(reason) {
+    this.#clearReconnectTimer();
+    if (this.#eventSource) {
+      this.#eventSource.onopen = null;
+      this.#eventSource.onmessage = null;
+      this.#eventSource.onerror = null;
+      this.#eventSource.close();
+      this.#eventSource = void 0;
+    }
+    if (this.#serverChannel) {
+      this.removeChannel(this.#serverChannel.channelId);
+      this.#serverChannel = void 0;
+    }
+    const currentState = this.#stateMachine.getState();
+    if (currentState.status !== "disconnected") {
+      this.#stateMachine.transition({ status: "disconnected", reason });
+    }
+  }
+  // ==========================================================================
+  // Event handlers
+  // ==========================================================================
+  /**
+   * Handle EventSource open event.
+   *
+   * The SSE connection is usable immediately — no "ready" signal needed.
+   * Create the channel and initiate establishment.
+   */
+  #handleOpen() {
+    const currentState = this.#stateMachine.getState();
+    if (currentState.status !== "connecting" && currentState.status !== "connected") {
+      return;
+    }
+    if (currentState.status === "connecting") {
+      this.#stateMachine.transition({ status: "connected" });
+    }
+    this.#wasConnectedBefore = true;
+    if (this.#currentRetryAbortController) {
+      this.#currentRetryAbortController.abort();
+      this.#currentRetryAbortController = void 0;
+    }
+    if (this.#serverChannel) {
+      this.removeChannel(this.#serverChannel.channelId);
+      this.#serverChannel = void 0;
+    }
+    this.#serverChannel = this.addChannel();
+    this.establishChannel(this.#serverChannel.channelId);
+  }
+  /**
+   * Handle incoming SSE message.
+   *
+   * Each SSE `data:` event contains a text wire frame string.
+   * Feed it through the TextReassembler to handle both complete
+   * and fragmented frames.
+   */
+  #handleMessage(event) {
+    if (!this.#serverChannel) {
+      return;
+    }
+    const data = event.data;
+    if (typeof data !== "string") {
+      return;
+    }
+    const result = this.#reassembler.receive(data);
+    if (result.status === "complete") {
+      try {
+        const parsed = JSON.parse(result.frame.content.payload);
+        const messages = textCodec.decode(parsed);
+        for (const msg of messages) {
+          this.#serverChannel.onReceive(msg);
+        }
+      } catch (error) {
+        console.error("Failed to decode SSE message:", error);
+      }
+    } else if (result.status === "error") {
+      console.error("SSE message reassembly error:", result.error);
+    }
+  }
+  /**
+   * Handle EventSource error.
+   *
+   * Closes the EventSource immediately and takes over reconnection
+   * via the state machine's backoff logic. This prevents the browser's
+   * built-in EventSource reconnection from running.
+   */
+  #handleError() {
+    if (this.#eventSource) {
+      this.#eventSource.onopen = null;
+      this.#eventSource.onmessage = null;
+      this.#eventSource.onerror = null;
+      this.#eventSource.close();
+      this.#eventSource = void 0;
+    }
+    if (this.#serverChannel) {
+      this.removeChannel(this.#serverChannel.channelId);
+      this.#serverChannel = void 0;
+    }
+    this.#scheduleReconnect({
+      type: "error",
+      error: new Error("EventSource connection error")
+    });
+  }
+  // ==========================================================================
+  // POST sending with retry
+  // ==========================================================================
+  /**
+   * Send a text frame via POST with retry logic.
+   */
+  async #sendTextWithRetry(url, textFrame) {
+    let attempt = 0;
+    const postRetryOpts = {
+      ...DEFAULT_POST_RETRY,
+      ...this.#options.postRetry
+    };
+    const { maxAttempts, baseDelay, maxDelay } = postRetryOpts;
+    while (attempt < maxAttempts) {
+      try {
+        if (!this.#currentRetryAbortController) {
+          this.#currentRetryAbortController = new AbortController();
+        }
+        if (!this.#peerId) {
+          throw new Error("PeerId not available for retry");
+        }
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "text/plain",
+            "X-Peer-Id": this.#peerId
+          },
+          body: textFrame,
+          signal: this.#currentRetryAbortController.signal
+        });
+        if (!response.ok) {
+          if (response.status >= 400 && response.status < 500) {
+            throw new Error(`Failed to send message: ${response.statusText}`);
+          }
+          throw new Error(`Server error: ${response.statusText}`);
+        }
+        this.#currentRetryAbortController = void 0;
+        return;
+      } catch (error) {
+        attempt++;
+        const err = error;
+        if (err.name === "AbortError") {
+          throw error;
+        }
+        if (!this.#currentRetryAbortController) {
+          const abortError = new Error("Retry aborted by connection reset");
+          abortError.name = "AbortError";
+          throw abortError;
+        }
+        if (attempt >= maxAttempts) {
+          this.#currentRetryAbortController = void 0;
+          throw error;
+        }
+        const delay = Math.min(
+          baseDelay * 2 ** (attempt - 1) + Math.random() * 100,
+          maxDelay
+        );
+        await new Promise((resolve, reject) => {
+          if (this.#currentRetryAbortController?.signal.aborted) {
+            const error2 = new Error("Retry aborted");
+            error2.name = "AbortError";
+            reject(error2);
+            return;
+          }
+          const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+          }, delay);
+          const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            const error2 = new Error("Retry aborted");
+            error2.name = "AbortError";
+            reject(error2);
+          };
+          const cleanup = () => {
+            this.#currentRetryAbortController?.signal.removeEventListener(
+              "abort",
+              onAbort
+            );
+          };
+          this.#currentRetryAbortController?.signal.addEventListener(
+            "abort",
+            onAbort
+          );
+        });
+      }
+    }
+  }
+  // ==========================================================================
+  // Reconnection
+  // ==========================================================================
+  /**
+   * Schedule a reconnection attempt or transition to disconnected.
+   */
+  #scheduleReconnect(reason) {
+    const currentState = this.#stateMachine.getState();
+    if (currentState.status === "disconnected") {
+      return;
+    }
+    const reconnectOpts = {
+      ...DEFAULT_RECONNECT,
+      ...this.#options.reconnect
+    };
+    if (!this.#shouldReconnect || !reconnectOpts.enabled) {
+      this.#stateMachine.transition({ status: "disconnected", reason });
+      return;
+    }
+    const currentAttempt = currentState.status === "reconnecting" ? currentState.attempt : currentState.status === "connecting" ? currentState.attempt : 0;
+    if (currentAttempt >= reconnectOpts.maxAttempts) {
+      this.#stateMachine.transition({
+        status: "disconnected",
+        reason: { type: "max-retries-exceeded", attempts: currentAttempt }
+      });
+      return;
+    }
+    const nextAttempt = currentAttempt + 1;
+    const delay = Math.min(
+      reconnectOpts.baseDelay * 2 ** (nextAttempt - 1) + Math.random() * 1e3,
+      reconnectOpts.maxDelay
+    );
+    this.#stateMachine.transition({
+      status: "reconnecting",
+      attempt: nextAttempt,
+      nextAttemptMs: delay
+    });
+    this.#reconnectTimer = setTimeout(() => {
+      this.#connect();
+    }, delay);
+  }
+  #clearReconnectTimer() {
+    if (this.#reconnectTimer) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = void 0;
+    }
+  }
+};
+function createSseClient(options) {
+  return () => new SseClientTransport(options);
+}
+export {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  SseClientStateMachine,
+  SseClientTransport,
+  createSseClient
+};
+//# sourceMappingURL=client.js.map