feat: add connection lifecycle callbacks

Author: tilyupo

packages/sdk/src/client-types.ts

@@ -182,6 +182,21 @@ export interface ReplaneClientOptions<T extends object> {
    * Defaults to SDK identifier (e.g., "replane-js/x.y.z").
    */
   agent?: string;
+
+  /**
+   * Callback invoked when a connection error occurs during SSE streaming.
+   * This is called on each retry attempt, useful for tracking connection health.
+   * The SDK will automatically retry connections, so this is informational.
+   * @param error - The error that caused the connection failure
+   */
+  onConnectionError?: (error: unknown) => void;
+
+  /**
+   * Callback invoked when the SSE connection is successfully established.
+   * This is called on initial connection and on every successful reconnection.
+   * Useful for tracking connection health and reconnection metrics.
+   */
+  onConnected?: () => void;
 }
 
 /**
@@ -234,6 +249,19 @@ export interface RestoreReplaneClientOptions<T extends object> {
      * Defaults to SDK identifier (e.g., "replane-js/x.y.z").
      */
     agent?: string;
+    /**
+     * Callback invoked when a connection error occurs during SSE streaming.
+     * This is called on each retry attempt, useful for tracking connection health.
+     * The SDK will automatically retry connections, so this is informational.
+     * @param error - The error that caused the connection failure
+     */
+    onConnectionError?: (error: unknown) => void;
+    /**
+     * Callback invoked when the SSE connection is successfully established.
+     * This is called on initial connection and on every successful reconnection.
+     * Useful for tracking connection health and reconnection metrics.
+     */
+    onConnected?: () => void;
   };
   /**
    * Override the context from the snapshot.
@@ -257,4 +285,6 @@ export interface ReplaneFinalOptions {
   requiredConfigs: string[];
   fallbacks: ConfigDto[];
   agent: string;
+  onConnectionError?: (error: unknown) => void;
+  onConnected?: () => void;
 }

packages/sdk/src/client.ts

@@ -383,35 +383,37 @@ async function createReplaneClientInternal<T extends object = Record<string, unk
 /**
  * Convert user options to final options with defaults
  */
-function toFinalOptions<T extends object>(defaults: ReplaneClientOptions<T>): ReplaneFinalOptions {
+function toFinalOptions<T extends object>(options: ReplaneClientOptions<T>): ReplaneFinalOptions {
   return {
-    sdkKey: defaults.sdkKey ?? "",
-    baseUrl: (defaults.baseUrl ?? "").replace(/\/+$/, ""),
+    sdkKey: options.sdkKey ?? "",
+    baseUrl: (options.baseUrl ?? "").replace(/\/+$/, ""),
     fetchFn:
-      defaults.fetchFn ??
+      options.fetchFn ??
       // some browsers require binding the fetch function to window
       globalThis.fetch.bind(globalThis),
-    requestTimeoutMs: defaults.requestTimeoutMs ?? 2000,
-    initializationTimeoutMs: defaults.initializationTimeoutMs ?? 5000,
-    inactivityTimeoutMs: defaults.inactivityTimeoutMs ?? 30_000,
-    logger: defaults.logger ?? console,
-    retryDelayMs: defaults.retryDelayMs ?? 200,
+    requestTimeoutMs: options.requestTimeoutMs ?? 2000,
+    initializationTimeoutMs: options.initializationTimeoutMs ?? 5000,
+    inactivityTimeoutMs: options.inactivityTimeoutMs ?? 30_000,
+    logger: options.logger ?? console,
+    retryDelayMs: options.retryDelayMs ?? 200,
     context: {
-      ...(defaults.context ?? {}),
+      ...(options.context ?? {}),
     },
-    requiredConfigs: Array.isArray(defaults.required)
-      ? defaults.required.map((name) => String(name))
-      : Object.entries(defaults.required ?? {})
+    requiredConfigs: Array.isArray(options.required)
+      ? options.required.map((name) => String(name))
+      : Object.entries(options.required ?? {})
           .filter(([_, value]) => value !== undefined)
           .map(([name]) => name),
-    fallbacks: Object.entries(defaults.fallbacks ?? {})
+    fallbacks: Object.entries(options.fallbacks ?? {})
       .filter(([_, value]) => value !== undefined)
       .map(([name, value]) => ({
         name,
         overrides: [],
         version: -1,
         value,
       })),
-    agent: defaults.agent ?? DEFAULT_AGENT,
+    agent: options.agent ?? DEFAULT_AGENT,
+    onConnectionError: options.onConnectionError,
+    onConnected: options.onConnected,
   };
 }

packages/sdk/src/storage.ts

@@ -17,6 +17,8 @@ export interface StartReplicationStreamOptions extends ReplaneFinalOptions {
   getBody: () => StartReplicationStreamBody;
   signal?: AbortSignal;
   onConnect?: () => void;
+  onConnectionError?: (error: unknown) => void;
+  onConnected?: () => void;
 }
 
 /**
@@ -69,6 +71,9 @@ export class ReplaneRemoteStorage implements ReplaneStorage {
               error
             );
 
+            // Call the connection error callback if provided
+            options.onConnectionError?.(error);
+
             await retryDelay(retryDelayMs);
           }
         }
@@ -112,6 +117,8 @@ export class ReplaneRemoteStorage implements ReplaneStorage {
         onConnect: () => {
           resetInactivityTimer();
           options.onConnect?.();
+          // Call the user's onConnected callback
+          options.onConnected?.();
         },
       });
 

packages/sdk/src/version.ts

@@ -1,3 +1,3 @@
 // Auto-generated - do not edit manually
-export const VERSION = "0.8.10";
+export const VERSION = "0.8.11";
 export const DEFAULT_AGENT = `replane-js-sdk/${VERSION}`;