@aptly-sdk/hq 0.0.5 → 0.0.6

package/dist/index.js

@@ -1,7 +1,5 @@
 import './global.css';
-import require$$0, { useState, useEffect, createContext, useRef, useContext, useCallback, useMemo, Activity } from 'react';
-import Brook from '@aptly-sdk/brook';
-import { BrookProvider as BrookProvider$1, useStream } from '@aptly-sdk/brook/react';
+import React, { useEffect, createContext, useRef, useState, useContext, useCallback, useMemo, Activity } from 'react';
 
 function getProject(apiKey) {
   return new Promise(resolve => {
@@ -44,6 +42,1683 @@ var client = {
   }
 };
 
+/**
+ * Exponential backoff implementation with 1.5x multiplier and jitter.
+ * Prevents thundering herd problem during reconnection scenarios.
+ */
+
+/**
+ * Manages exponential backoff timing for reconnection attempts.
+ */
+class ExponentialBackoff {
+  /**
+   * Creates a new ExponentialBackoff instance.
+   *
+   * @param {Object} options - Configuration options.
+   * @param {number} [options.initialDelay=3000] - Initial delay in milliseconds.
+   * @param {number} [options.multiplier=1.5] - Backoff multiplier factor.
+   * @param {number} [options.maxDelay=30000] - Maximum delay cap in milliseconds.
+   * @param {number} [options.jitter=0.1] - Jitter factor (0-1) to add randomness.
+   * @param {number} [options.maxAttempts=Infinity] - Maximum number of attempts.
+   * @param {Log} log - Log instance.
+   */
+  constructor(options = {}) {
+    this.initialDelay = options.initialDelay || 3000; // 3 seconds
+    this.multiplier = options.multiplier || 1.5; // 1.5x multiplier as per PRP
+    this.maxDelay = options.maxDelay || 30000; // 30 seconds max
+    this.jitter = options.jitter || 0.1; // 10% jitter
+    this.maxAttempts = options.maxAttempts || Infinity;
+    this.attempts = 0;
+    this.currentDelay = this.initialDelay;
+    this.log = options.log;
+  }
+
+  /**
+   * Gets the next delay value with exponential backoff and jitter.
+   *
+   * @returns {number} Delay in milliseconds for the next attempt.
+   */
+  getDelay() {
+    if (this.attempts >= this.maxAttempts) {
+      throw new Error('Maximum reconnection attempts exceeded');
+    }
+    this.attempts += 1;
+
+    // Calculate base delay with exponential backoff
+    let delay = this.currentDelay;
+
+    // Apply jitter to prevent thundering herd
+    // Jitter adds randomness between -jitter% and +jitter%
+    const jitterAmount = delay * this.jitter;
+    const jitterOffset = (Math.random() * 2 - 1) * jitterAmount;
+    delay += jitterOffset;
+
+    // Ensure delay is positive and within bounds
+    delay = Math.max(100, Math.min(delay, this.maxDelay));
+
+    // Update current delay for next attempt
+    this.currentDelay = Math.min(this.currentDelay * this.multiplier, this.maxDelay);
+    return Math.floor(delay);
+  }
+
+  /**
+   * Resets the backoff state after a successful connection.
+   *
+   * @returns {void}
+   */
+  reset() {
+    this.attempts = 0;
+    this.currentDelay = this.initialDelay;
+  }
+
+  /**
+   * Gets the current number of attempts made.
+   *
+   * @returns {number} Number of connection attempts.
+   */
+  getAttempts() {
+    return this.attempts;
+  }
+
+  /**
+   * Checks if maximum attempts have been reached.
+   *
+   * @returns {boolean} True if max attempts exceeded.
+   */
+  isMaxAttemptsReached() {
+    return this.attempts >= this.maxAttempts;
+  }
+
+  /**
+   * Gets the next delay without incrementing the attempt counter.
+   * Useful for previewing the next delay value.
+   *
+   * @returns {number} Next delay in milliseconds.
+   */
+  peekNextDelay() {
+    let delay = this.currentDelay * this.multiplier;
+    delay = Math.min(delay, this.maxDelay);
+
+    // Apply jitter
+    const jitterAmount = delay * this.jitter;
+    const jitterOffset = (Math.random() * 2 - 1) * jitterAmount;
+    delay += jitterOffset;
+    return Math.max(100, Math.floor(delay));
+  }
+
+  /**
+   * Creates a promise that resolves after the backoff delay.
+   * Convenient for async/await usage patterns.
+   *
+   * @returns {Promise<number>} Promise resolving to the delay used.
+   */
+  async wait() {
+    const delay = this.getDelay();
+    return new Promise(resolve => {
+      setTimeout(() => {
+        resolve(delay);
+      }, delay);
+    });
+  }
+
+  /**
+   * Gets configuration summary for debugging.
+   *
+   * @returns {Object} Configuration and state information.
+   */
+  getStatus() {
+    return {
+      attempts: this.attempts,
+      currentDelay: this.currentDelay,
+      nextDelay: this.attempts < this.maxAttempts ? this.peekNextDelay() : null,
+      maxAttempts: this.maxAttempts,
+      config: {
+        initialDelay: this.initialDelay,
+        multiplier: this.multiplier,
+        maxDelay: this.maxDelay,
+        jitter: this.jitter
+      }
+    };
+  }
+}
+
+/**
+ * WebSocket connection manager with automatic reconnection and fault tolerance.
+ * Provides reliable real-time connectivity with exponential backoff strategy.
+ */
+
+
+/**
+ * Connection states for status tracking.
+ */
+const CONNECTION_STATES = {
+  DISCONNECTED: 'disconnected',
+  CONNECTING: 'connecting',
+  AUTHENTICATING: 'authenticating',
+  CONNECTED: 'connected',
+  RECONNECTING: 'reconnecting',
+  FAILED: 'failed',
+  UNAUTHORIZED: 'unauthorized'
+};
+
+/**
+ * Manages WebSocket connections with automatic reconnection and state management.
+ */
+class Connection {
+  /**
+   * Creates a new Connection instance.
+   *
+   * @param {Object} config - Connection configuration.
+   * @param {string} config.endpoint - WebSocket server endpoint.
+   * @param {string} config.apiKey - API key for authentication.
+   * @param {number} [config.reconnectTimeout=3000] - Initial reconnection delay.
+   * @param {EventTarget} connectivity - Event target for connectivity events.
+   */
+  constructor(config, connectivity, log) {
+    this.config = config;
+    this.connectivity = connectivity;
+    this.ws = null;
+    this.state = CONNECTION_STATES.DISCONNECTED;
+    this.clientId = this.generateClientId();
+    this.log = log;
+
+    // Reconnection management
+    this.backoff = new ExponentialBackoff({
+      initialDelay: config.reconnectTimeout || 3000,
+      multiplier: 1.5,
+      maxDelay: 30000,
+      maxAttempts: 20,
+      log: this.log
+    });
+    this.reconnectTimeoutId = null;
+    this.shouldReconnect = false;
+    this.messageHandlers = new Set();
+    this.connectionPromise = null;
+
+    // Message queue for offline messages
+    this.messageQueue = [];
+    this.maxQueueSize = 10000;
+
+    // Heartbeat management
+    this.heartbeatInterval = null;
+    this.lastPongTime = null;
+    this.lastPingTime = null;
+    this.heartbeatIntervalMs = 30000; // 30 seconds
+
+    // Authentication management
+    this.isAuthenticated = false;
+    this.authTimeout = 30000; // 30 seconds to authenticate
+    this.authTimeoutId = null;
+    this.authPromise = null;
+  }
+
+  /**
+   * Establishes WebSocket connection with retry logic.
+   *
+   * @returns {Promise<boolean>} Promise resolving to connection success status.
+   */
+  async connect() {
+    // If already connecting, return the existing promise
+    if (this.connectionPromise) {
+      return this.connectionPromise;
+    }
+    this.shouldReconnect = true;
+    this.connectionPromise = this.attemptConnection();
+    try {
+      const result = await this.connectionPromise;
+      this.connectionPromise = null;
+      return result;
+    } catch (error) {
+      this.connectionPromise = null;
+      throw error;
+    }
+  }
+
+  /**
+   * Attempts to establish WebSocket connection.
+   *
+   * @returns {Promise<boolean>} Promise resolving to connection success.
+   * @private
+   */
+  attemptConnection() {
+    return new Promise((resolve, reject) => {
+      try {
+        this.setState(CONNECTION_STATES.CONNECTING);
+
+        // Create WebSocket connection
+        this.ws = new WebSocket(this.config.endpoint);
+
+        // Connection timeout
+        const connectionTimeout = setTimeout(() => {
+          if (this.ws && this.ws.readyState === WebSocket.CONNECTING) {
+            this.ws.close();
+            reject(new Error('Connection timeout'));
+          }
+        }, 10000);
+
+        // Connection opened successfully
+        this.ws.onopen = () => {
+          clearTimeout(connectionTimeout);
+          this.setState(CONNECTION_STATES.AUTHENTICATING);
+          this.backoff.reset();
+
+          // Start authentication process
+          this.startAuthentication().then(() => {
+            this.setState(CONNECTION_STATES.CONNECTED);
+            // this.startHeartbeat(); -- This is removed due to heartbeat is managed in server.
+            this.flushMessageQueue();
+            resolve(true);
+          }).catch(authError => {
+            this.log.error('Authentication failed:', authError);
+            this.ws.close(1000, 'Authentication failed');
+            this.setState(CONNECTION_STATES.UNAUTHORIZED);
+            reject(authError);
+          });
+        };
+
+        // Handle incoming messages
+        this.ws.onmessage = event => {
+          this.handleMessage(event);
+        };
+
+        // Handle connection close
+        this.ws.onclose = event => {
+          clearTimeout(connectionTimeout);
+          this.stopHeartbeat();
+          this.handleDisconnection(event);
+
+          // If this was during initial connection, reject the promise
+          if (this.state === CONNECTION_STATES.CONNECTING) {
+            reject(new Error(`Connection failed: ${event.code} ${event.reason}`));
+          }
+        };
+
+        // Handle connection errors
+        this.ws.onerror = error => {
+          clearTimeout(connectionTimeout);
+
+          // If this was during initial connection, reject the promise
+          if (this.state === CONNECTION_STATES.CONNECTING) {
+            reject(new Error('WebSocket connection error'));
+          }
+        };
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Closes the WebSocket connection and stops reconnection attempts.
+   *
+   * @returns {void}
+   */
+  disconnect() {
+    this.shouldReconnect = false;
+    if (this.reconnectTimeoutId) {
+      clearTimeout(this.reconnectTimeoutId);
+      this.reconnectTimeoutId = null;
+    }
+
+    // Clear auth timeout
+    if (this.authTimeoutId) {
+      clearTimeout(this.authTimeoutId);
+      this.authTimeoutId = null;
+    }
+
+    // Reset authentication state
+    this.isAuthenticated = false;
+    this.authPromise = null;
+    this.stopHeartbeat();
+    if (this.ws) {
+      try {
+        // Detach handlers to avoid side effects during shutdown
+        this.ws.onopen = null;
+        this.ws.onmessage = null;
+        this.ws.onclose = null;
+        this.ws.onerror = null;
+
+        // Prefer terminate when available to avoid lingering close timers
+        if (typeof this.ws.terminate === 'function') {
+          this.ws.terminate();
+        } else {
+          this.ws.close();
+        }
+      } catch (e) {
+        // Ignore errors during shutdown
+      }
+      this.ws = null;
+    }
+    this.setState(CONNECTION_STATES.DISCONNECTED);
+  }
+
+  /**
+   * Sends a message through the WebSocket connection.
+   *
+   * @param {Object} message - Message object to send.
+   * @returns {void}
+   */
+  send(message) {
+    const messageStr = JSON.stringify(message);
+    if (this.isConnected()) {
+      try {
+        this.ws.send(messageStr);
+      } catch (error) {
+        this.log.error('Failed to send message:', error);
+        // Queue the message for retry
+        this.queueMessage(message);
+      }
+    } else {
+      // Queue message if not connected
+      this.queueMessage(message);
+    }
+  }
+
+  /**
+   * Adds a message handler for incoming WebSocket messages.
+   *
+   * @param {Function} handler - Message handler function.
+   * @returns {void}
+   */
+  addMessageHandler(handler) {
+    this.messageHandlers.add(handler);
+  }
+
+  /**
+   * Removes a message handler.
+   *
+   * @param {Function} handler - Message handler function to remove.
+   * @returns {void}
+   */
+  removeMessageHandler(handler) {
+    this.messageHandlers.delete(handler);
+  }
+
+  /**
+   * Gets the current connection state.
+   *
+   * @returns {string} Current connection state.
+   */
+  getState() {
+    return this.state;
+  }
+
+  /**
+   * Checks if the connection is currently established and authenticated.
+   *
+   * @returns {boolean} True if connected and authenticated.
+   */
+  isConnected() {
+    return this.state === CONNECTION_STATES.CONNECTED && this.isAuthenticated && this.ws && this.ws.readyState === WebSocket.OPEN;
+  }
+
+  /**
+   * Gets the client ID for this connection.
+   *
+   * @returns {string} Unique client identifier.
+   */
+  getClientId() {
+    return this.clientId;
+  }
+
+  /**
+   * Handles incoming WebSocket messages.
+   *
+   * @param {MessageEvent} event - WebSocket message event.
+   * @returns {void}
+   * @private
+   */
+  handleMessage(event) {
+    try {
+      const message = JSON.parse(event.data);
+
+      // Handle authentication messages during auth flow
+      if (!this.isAuthenticated) {
+        this.handleAuthMessage(message);
+        return;
+      }
+
+      // Handle heartbeat responses
+      if (message.type === 'heartbeat') {
+        this.handleReceiveHeartbeat();
+        return;
+      }
+
+      // Forward message to registered handlers
+      this.messageHandlers.forEach(handler => {
+        try {
+          handler(message);
+        } catch (error) {
+          this.log.error('Message handler error:', error);
+        }
+      });
+    } catch (error) {
+      this.log.error('Failed to parse WebSocket message:', error);
+    }
+  }
+
+  /**
+   * Starts the post-connection authentication process.
+   *
+   * @returns {Promise<void>} Promise resolving when authentication completes.
+   * @private
+   */
+  startAuthentication() {
+    return new Promise((resolve, reject) => {
+      this.authPromise = {
+        resolve,
+        reject
+      };
+
+      // Set authentication timeout
+      this.authTimeoutId = setTimeout(() => {
+        const error = new Error('Authentication timeout');
+        this.authPromise = null;
+        reject(error);
+      }, this.authTimeout);
+
+      // Send authentication credentials immediately after connection
+      // The server expects immediate authentication, not a request-response flow
+      this.sendAuthCredentials();
+    });
+  }
+
+  /**
+   * Handles authentication-related messages from the server.
+   *
+   * @param {Object} message - Parsed WebSocket message.
+   * @returns {void}
+   * @private
+   */
+  handleAuthMessage(message) {
+    if (!this.authPromise) {
+      return; // No active authentication process
+    }
+    switch (message.type) {
+      case 'auth_required':
+        this.sendAuthCredentials();
+        break;
+      case 'auth_success':
+        this.handleAuthSuccess(message);
+        break;
+      case 'connected':
+        this.handleConnected(message);
+        break;
+      case 'auth_timeout':
+      case 'error':
+        this.handleAuthError(message);
+        break;
+      case 'heartbeat':
+        // Allow heartbeat during auth
+        this.lastPongTime = Date.now();
+        this.handleReceiveHeartbeat();
+        break;
+      default:
+        this.log.warn('Unexpected message during authentication:', message.type);
+        if (message.error === 'Invalid API key') {
+          this.setState(CONNECTION_STATES.UNAUTHORIZED);
+        }
+        break;
+    }
+  }
+
+  /**
+   * Sends authentication credentials to the server.
+   *
+   * @returns {void}
+   * @private
+   */
+  sendAuthCredentials() {
+    const authMessage = {
+      type: 'auth',
+      apiKey: this.config.apiKey,
+      timestamp: Date.now()
+    };
+    try {
+      this.ws.send(JSON.stringify(authMessage));
+    } catch (error) {
+      this.log.error('Failed to send auth credentials:', error);
+      if (this.authPromise) {
+        this.authPromise.reject(error);
+        this.authPromise = null;
+      }
+    }
+  }
+
+  /**
+   * Handles successful authentication response.
+   *
+   * @param {Object} message - Auth success message.
+   * @returns {void}
+   * @private
+   */
+  handleAuthSuccess(message) {
+    // Wait for connected message to complete authentication
+  }
+
+  /**
+   * Handles connected message after successful authentication.
+   *
+   * @param {Object} message - Connected message.
+   * @returns {void}
+   * @private
+   */
+  handleConnected(message) {
+    // Clear auth timeout
+    if (this.authTimeoutId) {
+      clearTimeout(this.authTimeoutId);
+      this.authTimeoutId = null;
+    }
+
+    // Mark as authenticated
+    this.isAuthenticated = true;
+
+    // Resolve authentication promise
+    if (this.authPromise) {
+      this.authPromise.resolve();
+      this.authPromise = null;
+    }
+  }
+
+  /**
+   * Handles authentication errors.
+   *
+   * @param {Object} message - Error message.
+   * @returns {void}
+   * @private
+   */
+  handleAuthError(message) {
+    this.log.error('Authentication error:', message);
+
+    // Clear auth timeout
+    if (this.authTimeoutId) {
+      clearTimeout(this.authTimeoutId);
+      this.authTimeoutId = null;
+    }
+
+    // Reject authentication promise
+    if (this.authPromise) {
+      const error = new Error(message.error || message.message || 'Authentication failed');
+      this.authPromise.reject(error);
+      this.authPromise = null;
+    }
+  }
+
+  /**
+   * Handles WebSocket disconnection and manages reconnection.
+   *
+   * @param {CloseEvent} event - WebSocket close event.
+   * @returns {void}
+   * @private
+   */
+  handleDisconnection(event) {
+    this.log.info('WebSocket disconnected:', event.code, event.reason);
+
+    // Reset authentication state on disconnection
+    this.isAuthenticated = false;
+    this.authPromise = null;
+    if (this.authTimeoutId) {
+      clearTimeout(this.authTimeoutId);
+      this.authTimeoutId = null;
+    }
+
+    // Don't reconnect if it was a deliberate disconnection
+    if (!this.shouldReconnect || event.code === 1000) {
+      this.setState(CONNECTION_STATES.DISCONNECTED);
+      return;
+    }
+
+    // Check if we've exceeded max attempts
+    if (this.backoff.isMaxAttemptsReached()) {
+      this.setState(CONNECTION_STATES.FAILED);
+      return;
+    }
+
+    // Start reconnection process
+    this.setState(CONNECTION_STATES.RECONNECTING);
+    this.scheduleReconnection();
+  }
+
+  /**
+   * Schedules the next reconnection attempt with exponential backoff.
+   *
+   * @returns {void}
+   * @private
+   */
+  scheduleReconnection() {
+    if (this.reconnectTimeoutId) {
+      clearTimeout(this.reconnectTimeoutId);
+    }
+    const delay = this.backoff.getDelay();
+    this.reconnectTimeoutId = setTimeout(async () => {
+      if (this.shouldReconnect && this.state === CONNECTION_STATES.RECONNECTING) {
+        try {
+          await this.attemptConnection();
+        } catch (error) {
+          this.log.error('Reconnection attempt failed:', error);
+          // Schedule next attempt if we haven't exceeded max attempts
+          if (!this.backoff.isMaxAttemptsReached()) {
+            this.scheduleReconnection();
+          } else {
+            this.setState(CONNECTION_STATES.FAILED);
+          }
+        }
+      }
+    }, delay);
+  }
+
+  /**
+   * Sets the connection state and emits connectivity events.
+   *
+   * @param {string} newState - New connection state.
+   * @returns {void}
+   * @private
+   */
+  setState(newState) {
+    if (this.state !== newState) {
+      this.state = newState;
+
+      // Emit connectivity event
+      const event = new CustomEvent('connectivity', {
+        detail: {
+          status: newState,
+          timestamp: Date.now(),
+          clientId: this.clientId
+        }
+      });
+      this.connectivity.dispatchEvent(event);
+    }
+  }
+
+  /**
+   * Queues a message for sending when connection is re-established.
+   *
+   * @param {Object} message - Message to queue.
+   * @returns {void}
+   * @private
+   */
+  queueMessage(message) {
+    if (this.messageQueue.length >= this.maxQueueSize) {
+      this.messageQueue.shift(); // Remove oldest message
+    }
+    this.messageQueue.push({
+      message,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Sends all queued messages after reconnection.
+   *
+   * @returns {void}
+   * @private
+   */
+  flushMessageQueue() {
+    if (this.messageQueue.length === 0) {
+      return;
+    }
+    const messages = [...this.messageQueue];
+    this.messageQueue = [];
+    messages.forEach(({
+      message
+    }) => {
+      this.send(message);
+    });
+  }
+
+  /**
+   * Starts heartbeat monitoring to detect connection health.
+   *
+   * @deprecated
+   * @returns {void}
+   * @private
+   */
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.lastPongTime = Date.now();
+    this.heartbeatInterval = setInterval(() => {
+      if (this.isConnected()) {
+        // Check if we've received a recent pong
+        const timeSinceLastPong = Date.now() - this.lastPongTime;
+        if (timeSinceLastPong > this.heartbeatIntervalMs * 2) {
+          this.log.warn('Heartbeat timeout detected, closing connection');
+          this.ws.close();
+          return;
+        }
+
+        // Send heartbeat
+        this.send({
+          type: 'heartbeat',
+          timestamp: Date.now()
+        });
+      }
+    }, this.heartbeatIntervalMs);
+  }
+
+  /**
+   * Stops heartbeat monitoring.
+   *
+   * @returns {void}
+   * @private
+   */
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+
+  /**
+   * Generates a unique client ID.
+   *
+   * @returns {string} Unique client identifier.
+   * @private
+   */
+  generateClientId() {
+    return `client_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+  }
+
+  /**
+   * Gets connection statistics for debugging.
+   *
+   * @returns {Object} Connection statistics.
+   */
+  getStats() {
+    return {
+      state: this.state,
+      clientId: this.clientId,
+      isAuthenticated: this.isAuthenticated,
+      reconnectAttempts: this.backoff.getAttempts(),
+      queuedMessages: this.messageQueue.length,
+      lastPongTime: this.lastPongTime,
+      backoffStatus: this.backoff.getStatus()
+    };
+  }
+  handleReceiveHeartbeat() {
+    this.lastPingTime = Date.now();
+    this.ws.send(JSON.stringify({
+      type: 'heartbeat',
+      payload: {
+        type: 'response'
+      }
+    }));
+  }
+}
+
+// import * as log from './utils/logx.js';
+
+class Stream {
+  constructor({
+    channelName,
+    connection,
+    offset,
+    log
+  }) {
+    this.offset = offset;
+    this.state = '';
+    this.channelName = channelName;
+    this.connection = connection;
+    this.handler;
+    this.log = log;
+  }
+  start(handler) {
+    if (typeof handler !== 'function') {
+      throw new Error('Stream callback must be a function');
+    }
+    this.handler = handler;
+    const subscribeMessage = {
+      type: 'subscribe',
+      channel: this.channelName,
+      fromOffset: this.offset
+    };
+    this.connection.send(subscribeMessage);
+    this.state = 'streaming';
+    this.log.info('Streaming started');
+  }
+  stop() {
+    this.state = 'stopped';
+  }
+  getStatus() {
+    const wsConnectionState = this.connection.getState();
+    if (wsConnectionState !== 'connected') return wsConnectionState;
+    if (this.state) return this.state || wsConnectionState;
+  }
+}
+
+/**
+ * Channel class for pub/sub messaging with offset tracking and message replay.
+ * Provides stream subscription, publishing, and message history functionality.
+ */
+
+/**
+ * Represents a pub/sub channel with real-time messaging capabilities.
+ */
+class Channel {
+  /**
+   * Creates a new Channel instance.
+   *
+   * @param {string} name - Channel name/topic.
+   * @param {Connection} connection - WebSocket connection manager.
+   */
+  constructor(name, connection, log) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Channel name is required and must be a string');
+    }
+    this.name = name;
+    this.connection = connection;
+    this.log = log;
+
+    // Stream management
+    this.streamHandlers = new Set();
+    this.messageHandler = this.handleMessage.bind(this);
+    this.streams = new Map();
+
+    // Subscribe to connection messages
+    this.connection.addMessageHandler(this.messageHandler);
+    this.offset = 0;
+    this.localStorage;
+    if (globalThis.window && window.localStorage) {
+      this.localStorage = window.localStorage;
+      const storedOffset = this.localStorage.getItem(`${this.name}_offset`);
+      if (storedOffset) {
+        this.offset = Number(storedOffset);
+      }
+    }
+  }
+  stream(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('Stream callback must be a function');
+    }
+    const previousSize = this.streams.size;
+    const stream = new Stream({
+      channelName: this.name,
+      connection: this.connection,
+      offset: this.offset,
+      log: this.log
+    });
+    this.streams.set(callback, stream);
+    if (this.streams.size > previousSize) {
+      this.log.info('Streaming next success!', this.streams.size, this.offset);
+    }
+    stream.start(callback);
+    return () => {
+      this.unstream(callback);
+    };
+  }
+  unstream(callback) {
+    const stream = this.streams.get(callback);
+    if (stream) {
+      const previousSize = this.streams.size;
+      stream.stop();
+      this.streams.delete(callback);
+      if (previousSize > this.streams.size) {
+        this.log.info('Unstreaming next success!', this.streams.size);
+      }
+    }
+    if (this.streams.size === 0) {
+      this.log.info('No streams left, closing the channel.');
+
+      // sends unsubscribe message to the ws connection but this will not close the ws connection.
+      // the ws will just stop receiving message for this channel/topic.
+      // channel will be automatically reopened when new stream is created.
+      this.close();
+    }
+  }
+
+  /**
+   * Publishes a message to the channel via WebSocket.
+   *
+   * @param {*} message - Message payload to publish.
+   * @returns {Promise<void>} Promise resolving when message is published.
+   */
+  async publish(message) {
+    if (!this.connection.isConnected()) {
+      throw new Error('Connection is not established');
+    }
+    return new Promise((resolve, reject) => {
+      const publishMessage = {
+        type: 'publish',
+        channel: this.name,
+        message,
+        timestamp: Date.now()
+      };
+      try {
+        this.connection.send(publishMessage);
+
+        // Note: We don't wait for confirmation in this implementation
+        // In production, you might want to wait for a 'published' response
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Alias for publish() method for backward compatibility.
+   *
+   * @param {*} message - Message payload to publish.
+   * @returns {Promise<void>} Promise resolving when message is published.
+   */
+  async send(message) {
+    return this.publish(message);
+  }
+
+  /**
+   * Unsubscribes from the channel and stops receiving messages.
+   *
+   * @returns {void}
+   */
+  close() {
+    // unsubscribe to the ws connection
+    const unsubscribeMessage = {
+      type: 'unsubscribe',
+      channel: this.name,
+      timestamp: Date.now()
+    };
+    this.connection.send(unsubscribeMessage);
+  }
+
+  /**
+   * Handles incoming WebSocket messages for this channel.
+   *
+   * @param {Object} message - WebSocket message object.
+   * @returns {void}
+   * @private
+   */
+  handleMessage(message) {
+    // if no streams are active, do not process the message
+    if (this.streams.size === 0) {
+      this.log.info('No streams active, skipping message:', message);
+      return;
+    }
+
+    // Handle subscription confirmation
+    if (message.type === 'subscribed' && message.channel === this.name) {
+      this.log.info(`Subscribed to channel: ${this.name}`);
+      return;
+    }
+
+    // Handle unsubscription confirmation
+    if (message.type === 'unsubscribed' && message.channel === this.name) {
+      this.log.info(`Unsubscribed from channel: ${this.name}`);
+      return;
+    }
+
+    // Handle incoming messages - check if message has channel field or assume it's for this channel
+    if (message.type === 'message') {
+      if (!message.channel || message.channel === this.name) {
+        // Add channel to message if missing
+        if (!message.channel) {
+          message.channel = this.name;
+        }
+        this.processIncomingMessage(message);
+        return;
+      }
+    }
+
+    // Handle publish confirmation
+    if (message.type === 'published' && message.channel === this.name) {
+      this.log.info('Message published to channel');
+    }
+  }
+
+  /**
+   * Processes an incoming message and forwards it to stream handlers.
+   *
+   * @param {Object} message - Incoming message object.
+   * @returns {void}
+   * @private
+   */
+  processIncomingMessage(message) {
+    // Create metadata object for the callback
+    const metadata = {
+      offset: message.offset,
+      timestamp: message.timestamp,
+      replay: message.replay || false,
+      channel: message.channel
+    };
+    if (message.offset) {
+      if (message.offset > this.offset) {
+        this.setOffset(message.offset);
+      }
+    }
+
+    // Forward to all stream handlers (process all messages)
+    this.streams.forEach(stream => {
+      try {
+        stream.handler(message.data, metadata);
+      } catch (error) {
+        this.log.error('Stream handler error:', error);
+      }
+    });
+  }
+
+  /**
+   * Re-subscribes to the channel after reconnection.
+   * Called automatically when connection is re-established.
+   *
+   * @returns {void}
+   */
+  resubscribe() {
+    if (this.streams.size > 0) ;
+  }
+
+  /**
+   * Gets channel statistics for debugging.
+   *
+   * @returns {Object} Channel statistics and state information.
+   */
+  getStats() {
+    return {
+      name: this.name,
+      streamHandlers: this.streamHandlers.size,
+      connectionState: this.connection.getState()
+    };
+  }
+  setOffset(offset) {
+    this.offset = offset;
+    if (this.localStorage) {
+      this.localStorage.setItem(`${this.name}_offset`, this.offset);
+    }
+  }
+}
+
+class Log {
+  constructor(config) {
+    this.verbose = config.verbose;
+  }
+  info(...args) {
+    if (this.verbose) {
+      console.log(...args);
+    }
+  }
+  error(...args) {
+    if (this.verbose) {
+      console.error(...args);
+    }
+  }
+  warn(...args) {
+    if (this.verbose) {
+      console.warn(...args);
+    }
+  }
+  debug(...args) {
+    if (this.verbose) {
+      console.debug(...args);
+    }
+  }
+}
+
+/**
+ * Main Package class for the realtime pub/sub SDK.
+ * Provides WebSocket connectivity, channel management, and real-time messaging.
+ */
+
+
+/**
+ * Main SDK class that provides pub/sub functionality with automatic reconnection.
+ */
+class Package {
+  /**
+   * @param {Object} config - Client configuration.
+   * @param {string} config.apiKey - API key for authentication.
+   */
+  constructor(config = {}) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.config = config;
+    this.config.endpoint = config.host || 'wss://connect.aptly.cloud';
+    this.config.verbose = config.verbose || false;
+    this.log = new Log(config);
+
+    // Create connectivity event target for status monitoring (internal)
+    this._connectivity = new EventTarget();
+
+    // Initialize connection manager
+    this.connection = new Connection(config, this._connectivity, this.log);
+    this._connectivityHandlers = new Set();
+
+    // Channel management
+    this.channels = new Map();
+
+    // Set up connection event handlers
+    this.setupConnectionHandlers();
+
+    // Create realtime interface
+    this.realtime = {
+      channel: this.createChannel.bind(this)
+    };
+    this.log.info('Package initialized');
+  }
+
+  /**
+   * Establishes connection to the WebSocket server.
+   *
+   * @returns {Promise<boolean>} Promise resolving to connection success status.
+   */
+  async connect() {
+    try {
+      this.log.info('Connecting to server');
+      const connected = await this.connection.connect();
+      this.log.info('Connected to server', connected);
+      if (connected) {
+        // Re-subscribe to existing channels after reconnection
+        this.resubscribeChannels();
+      }
+      return connected;
+    } catch (error) {
+      this.log.error('Failed to connect:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Disconnects from the WebSocket server and cleans up resources.
+   *
+   * @returns {void}
+   */
+  disconnect() {
+    // Close all channels
+    this.channels.forEach(channel => {
+      channel.close();
+    });
+    this.channels.clear();
+
+    // Disconnect the connection
+    this.connection.disconnect();
+  }
+
+  /**
+   * Creates or retrieves a channel instance for the given channel name.
+   *
+   * @param {string} name - Channel name/topic.
+   * @returns {Channel} Channel instance for the specified name.
+   */
+  createChannel(name) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Channel name is required and must be a string');
+    }
+
+    // Return existing channel if already created
+    if (this.channels.has(name)) {
+      return this.channels.get(name);
+    }
+
+    // Create new channel instance
+    const channel = new Channel(name, this.connection, this.log);
+    this.channels.set(name, channel);
+    return channel;
+  }
+
+  /**
+   * Gets the current connection status.
+   *
+   * @returns {string} Current connection status.
+   */
+  getConnectionStatus() {
+    return this.connection.getState();
+  }
+
+  /**
+   * Checks if the connection is authenticated.
+   *
+   * @returns {boolean} True if authenticated.
+   */
+  isAuthenticated() {
+    return this.connection.isAuthenticated;
+  }
+
+  /**
+   * Gets the client ID for this connection.
+   *
+   * @returns {string} Unique client identifier.
+   */
+  getClientId() {
+    return this.connection.getClientId();
+  }
+
+  /**
+   * Gets all active channel names.
+   *
+   * @returns {Array<string>} Array of active channel names.
+   */
+  getActiveChannels() {
+    return Array.from(this.channels.keys());
+  }
+
+  /**
+   * Gets statistics for all channels and the connection.
+   *
+   * @returns {Object} Statistics object with connection and channel information.
+   */
+  getStats() {
+    const channelStats = {};
+    this.channels.forEach((channel, name) => {
+      channelStats[name] = channel.getStats();
+    });
+    return {
+      connection: this.connection.getStats(),
+      channels: channelStats,
+      activeChannels: this.getActiveChannels().length
+    };
+  }
+
+  /**
+   * Publishes a message to a channel via HTTP API (fallback method).
+   *
+   * @param {string} channel - Channel name to publish to.
+   * @param {*} message - Message payload to publish.
+   * @returns {Promise<Object>} Promise resolving to publish response.
+   */
+  async publishHttp(channel, message) {
+    if (!channel || !message) {
+      throw new Error('Channel and message are required');
+    }
+    const httpEndpoint = this.config.endpoint.replace('ws://', 'http://').replace('wss://', 'https://');
+    const url = new URL('/realtime', httpEndpoint);
+    const response = await fetch(url.toString(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': this.config.apiKey
+      },
+      body: JSON.stringify({
+        channel,
+        message
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP publish failed: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  /**
+   * Checks if the client is currently connected to the server.
+   *
+   * @returns {boolean} True if connected.
+   */
+  isConnected() {
+    return this.connection.isConnected();
+  }
+
+  /**
+   * Sets up connection event handlers for automatic channel management.
+   *
+   * @returns {void}
+   * @private
+   */
+  setupConnectionHandlers() {
+    // Listen for connection state changes
+    const handler = event => {
+      const {
+        status
+      } = event.detail;
+
+      // Re-subscribe channels when connection is re-established
+      // todo add conidtion only when previously connected
+      if (status === 'connected') {
+        this.resubscribeChannels();
+      }
+    };
+    this._connectivity.addEventListener('connectivity', handler);
+    this._connectivityHandlers.add(handler);
+  }
+
+  /**
+   * Re-subscribes all active channels after reconnection.
+   *
+   * @returns {void}
+   * @private
+   */
+  resubscribeChannels() {
+    this.channels.forEach(channel => {
+      if (channel.streams && channel.streams.size > 0) {
+        channel.resubscribe();
+      }
+    });
+  }
+  onConnectivityChange(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('Connectivity callback must be a function');
+    }
+    function handler(event) {
+      callback(event.detail.status);
+    }
+    this._connectivity.addEventListener('connectivity', handler);
+    this.log.info('connectivity listener added');
+    this._connectivityHandlers.add(handler);
+    return () => {
+      this._connectivity.removeEventListener('connectivity', handler);
+      this.log.info('connectivity listener removed');
+      this._connectivityHandlers.delete(handler);
+    };
+  }
+
+  /**
+   * Removes all event listeners and cleans up resources.
+   * Should be called when the Package instance is no longer needed.
+   *
+   * @returns {void}
+   */
+  cleanup() {
+    this.disconnect();
+    this._connectivityHandlers.forEach(handler => {
+      this._connectivity.removeEventListener('connectivity', handler);
+    });
+    this._connectivityHandlers.clear();
+
+    // Remove all connectivity listeners
+    // Note: EventTarget doesn't have a removeAllListeners method,
+    // so we rely on garbage collection when the instance is destroyed
+  }
+}
+
+// Attach the connectivity subscription method to match the API pattern
+Object.defineProperty(Package.prototype, 'connectivity', {
+  get() {
+    return {
+      subscribe: this.subscribeToConnectivity.bind(this)
+    };
+  }
+});
+
+/**
+ * BrookProvider component that provides Brook client context to React components.
+ * Manages the client instance and connection state across the component tree.
+ */
+
+const BrookContext = /*#__PURE__*/createContext(null);
+
+/**
+ * BrookProvider component that wraps the application with Brook client context.
+ *
+ * @param {Object} props - Component props.
+ * @param {Object} props.config - Brook client instance.
+ * @param {React.ReactNode} props.children - Child components to wrap.
+ * @returns {React.ReactElement} Provider component.
+ */
+function BrookProvider$1({
+  config,
+  children
+}) {
+  if (!config) {
+    throw new Error('BrookProvider requires a config prop with Brook client instance');
+  }
+  useEffect(() => {
+    config.connect();
+  }, [config]);
+  const contextValue = {
+    client: config
+  };
+  return /*#__PURE__*/React.createElement(BrookContext.Provider, {
+    value: contextValue
+  }, children);
+}
+
+/**
+ * Hook to access the Brook context.
+ *
+ * @returns {Object} Brook context containing client and connection state.
+ * @throws {Error} If used outside of BrookProvider.
+ */
+const useBrookContext = () => {
+  const context = useContext(BrookContext);
+  if (!context) {
+    throw new Error('Hook must be used within a BrookProvider');
+  }
+  return context;
+};
+
+function useConnection() {
+  const ctx = useBrookContext();
+  const [status, setStatus] = useState('disconnected');
+  useEffect(() => {
+    const client = ctx.client;
+    if (client) {
+      setStatus(client.getConnectionStatus());
+    }
+    if (client?.onConnectivityChange) {
+      const unsubscribe = client.onConnectivityChange(status => {
+        setStatus(status);
+      });
+      return () => unsubscribe?.();
+    }
+  }, [ctx]);
+  return {
+    status
+  };
+}
+
+/**
+ * Timer node for linked list implementation.
+ * Represents a single timeout operation in the queue.
+ */
+class TimerNode {
+  /**
+   * Creates a new timer node.
+   *
+   * @param {Function} callback - Function to execute when timer fires.
+   * @param {number} delay - Delay in milliseconds before execution.
+   */
+  constructor(callback, delay) {
+    this.callback = callback;
+    this.delay = delay;
+    this.next = null;
+    this.timeoutId = null;
+  }
+
+  /**
+   * Sets the next node in the queue.
+   *
+   * @param {TimerNode} next - The next timer node.
+   */
+  setNext(next) {
+    this.next = next;
+  }
+
+  /**
+   * Executes this timer node and schedules the next one.
+   *
+   * @param {Function} onComplete - Callback when this node completes.
+   */
+  execute(onComplete) {
+    this.timeoutId = setTimeout(() => {
+      try {
+        this.callback?.();
+      } catch (error) {
+        console.error('Timer callback error:', error);
+      }
+      onComplete(this.next);
+    }, this.delay);
+  }
+
+  /**
+   * Cancels the timeout if it hasn't executed yet.
+   */
+  cancel() {
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+  }
+}
+
+/**
+ * Sequential timer implementation using a linked list.
+ * Executes timeouts one after another in the order they were added.
+ */
+class Timer {
+  /**
+   * Creates a new Timer instance.
+   */
+  constructor() {
+    this.head = null;
+    this.tail = null;
+    this.isExecuting = false;
+  }
+
+  /**
+   * Adds a timeout to the execution queue.
+   *
+   * @param {Function} callback - Function to execute when timer fires.
+   * @param {number} delay - Delay in milliseconds before execution.
+   * @returns {TimerNode} The created timer node for potential cancellation.
+   */
+  setTimeout(callback, delay) {
+    const node = new TimerNode(callback, delay);
+
+    // Add to queue
+    if (!this.head) {
+      this.head = node;
+      this.tail = node;
+      this._startExecution();
+    } else {
+      this.tail.setNext(node);
+      this.tail = node;
+    }
+    return node;
+  }
+
+  /**
+   * Starts executing the timer queue.
+   *
+   * @private
+   */
+  _startExecution() {
+    if (this.isExecuting || !this.head) return;
+    this.isExecuting = true;
+    this._executeNext(this.head);
+  }
+
+  /**
+   * Executes the next timer in the queue.
+   *
+   * @param {TimerNode} currentNode - The current node to execute.
+   * @private
+   */
+  _executeNext(currentNode) {
+    if (!currentNode) {
+      this._onQueueComplete();
+      return;
+    }
+    currentNode.execute(nextNode => {
+      this.head = nextNode;
+      if (!nextNode) {
+        this.tail = null;
+      }
+      this._executeNext(nextNode);
+    });
+  }
+
+  /**
+   * Called when the timer queue is complete.
+   *
+   * @private
+   */
+  _onQueueComplete() {
+    this.isExecuting = false;
+  }
+
+  /**
+   * Clears all pending timers in the queue.
+   */
+  clear() {
+    let current = this.head;
+    while (current) {
+      current.cancel();
+      current = current.next;
+    }
+    this.head = null;
+    this.tail = null;
+    this.isExecuting = false;
+  }
+
+  /**
+   * Checks if the timer queue is currently executing.
+   *
+   * @returns {boolean} True if executing, false otherwise.
+   */
+  isRunning() {
+    return this.isExecuting;
+  }
+
+  /**
+   * Gets the number of pending timers in the queue.
+   *
+   * @returns {number} Number of pending timers.
+   */
+  getPendingCount() {
+    let count = 0;
+    let current = this.head;
+    while (current) {
+      count++;
+      current = current.next;
+    }
+    return count;
+  }
+}
+
+function useStream(topic, callback) {
+  const ctx = useBrookContext();
+  const unsubscribeRef = useRef(null);
+  const topicRef = useRef(topic);
+  const {
+    status
+  } = useConnection();
+  const [streaming, setStreaming] = useState(false);
+  function subscribe() {
+    ctx?.client?.log?.info('Subscribing to topic:', topic);
+    if (topicRef.current !== topic) {
+      // unsubscribe from the previous topic
+      unsubscribe();
+    }
+    if (unsubscribeRef.current) {
+      ctx?.client?.log?.info('Already subscribed to channel. Aborting action.');
+      return;
+    }
+    if (!topic) {
+      ctx?.client?.log?.warn('No topic to subscribe to.');
+      return;
+    }
+    const channel = ctx.client.realtime.channel(topic);
+    ctx?.client?.log?.info(`Subscribing to channel: ${topic} from useStream hook`);
+    const timer = new Timer();
+    unsubscribeRef.current = channel.stream((message, metadata) => {
+      timer.setTimeout(() => {
+        callback(message, metadata);
+      }, 50);
+    });
+    setStreaming(true);
+  }
+  function unsubscribe() {
+    if (unsubscribeRef.current) {
+      ctx?.client?.log?.info('Unsubscribing.');
+      unsubscribeRef.current();
+      unsubscribeRef.current = null;
+      ctx?.client?.log?.info('Unsubscribed.');
+      setStreaming(false);
+    }
+  }
+  useEffect(() => {
+    // do nothing
+    if (!topic) return;
+
+    // otherwise, automatically subscribe
+    if (status === 'connected') {
+      subscribe();
+    }
+  }, [topic, status]);
+  useEffect(() => unsubscribe, []);
+  return {
+    streaming,
+    unsubscribe,
+    subscribe
+  };
+}
+
 var jsxRuntime = {exports: {}};
 
 var reactJsxRuntime_production = {};
@@ -380,7 +2055,7 @@ function requireReactJsxRuntime_development () {
 	        object.$$typeof === REACT_ELEMENT_TYPE
 	      );
 	    }
-	    var React = require$$0,
+	    var React$1 = React,
 	      REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element"),
 	      REACT_PORTAL_TYPE = Symbol.for("react.portal"),
 	      REACT_FRAGMENT_TYPE = Symbol.for("react.fragment"),
@@ -396,7 +2071,7 @@ function requireReactJsxRuntime_development () {
 	      REACT_ACTIVITY_TYPE = Symbol.for("react.activity"),
 	      REACT_CLIENT_REFERENCE = Symbol.for("react.client.reference"),
 	      ReactSharedInternals =
-	        React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+	        React$1.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
 	      hasOwnProperty = Object.prototype.hasOwnProperty,
 	      isArrayImpl = Array.isArray,
 	      createTask = console.createTask
@@ -404,15 +2079,15 @@ function requireReactJsxRuntime_development () {
 	        : function () {
 	            return null;
 	          };
-	    React = {
+	    React$1 = {
 	      react_stack_bottom_frame: function (callStackForError) {
 	        return callStackForError();
 	      }
 	    };
 	    var specialPropKeyWarningShown;
 	    var didWarnAboutElementRef = {};
-	    var unknownOwnerDebugStack = React.react_stack_bottom_frame.bind(
-	      React,
+	    var unknownOwnerDebugStack = React$1.react_stack_bottom_frame.bind(
+	      React$1,
 	      UnknownOwner
 	    )();
 	    var unknownOwnerDebugTask = createTask(getTaskName(UnknownOwner));
@@ -473,11 +2148,11 @@ const BrookProvider = ({
   const config = {
     apiKey: apiKey || "apiKey"
   };
-  const [client, setClient] = useState(new Brook(config));
+  const [client, setClient] = useState(new Package(config));
   useEffect(() => {
     client.cleanup();
     if (apiKey) {
-      const brook = new Brook(config);
+      const brook = new Package(config);
       setClient(brook);
       return () => {
         brook.cleanup();