@cilow/sdk 0.2.0 → 0.2.1

package/dist/websocket.d.mts

@@ -0,0 +1,160 @@
+import { CilowConfig, WebSocketConfig, CilowEvent, MemoryCreatedEvent, MemoryUpdatedEvent, MemoryDeletedEvent, MemoryTierChangedEvent, GraphNodeCreatedEvent, GraphEdgeCreatedEvent, ConnectionStatusEvent } from './types.mjs';
+
+/**
+ * Cilow WebSocket Client
+ *
+ * Real-time connection for memory updates, graph changes, and event streaming.
+ */
+
+/**
+ * WebSocket connection states
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Event listener type
+ */
+type EventListener<T extends CilowEvent = CilowEvent> = (event: T) => void;
+/**
+ * Subscription filter options
+ */
+interface SubscriptionFilter {
+    /** Filter by user ID */
+    userId?: string;
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Filter by tags */
+    tags?: string[];
+    /** Filter by event types */
+    eventTypes?: string[];
+}
+/**
+ * CilowWebSocket - Real-time WebSocket client for Cilow
+ *
+ * @example
+ * ```typescript
+ * const ws = new CilowWebSocket({
+ *   apiUrl: 'https://api.cilow.ai',
+ *   apiKey: 'your-key'
+ * });
+ *
+ * // Subscribe to memory events
+ * ws.on('memory.created', (event) => {
+ *   console.log('New memory:', event.memory);
+ * });
+ *
+ * // Connect
+ * await ws.connect();
+ *
+ * // Subscribe to specific user's events
+ * ws.subscribe({ userId: 'user-123' });
+ * ```
+ */
+declare class CilowWebSocket {
+    private ws;
+    private readonly wsUrl;
+    private readonly apiKey;
+    private readonly reconnectAttempts;
+    private readonly reconnectDelay;
+    private readonly heartbeatInterval;
+    private readonly messageQueueSize;
+    private state;
+    private reconnectCount;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private messageQueue;
+    private subscriptions;
+    private listeners;
+    private allListeners;
+    constructor(config: CilowConfig & WebSocketConfig);
+    /**
+     * Get current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to events with optional filter
+     */
+    subscribe(filter?: SubscriptionFilter): void;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(filter?: SubscriptionFilter): void;
+    /**
+     * Add event listener for specific event type
+     */
+    on<T extends CilowEvent>(eventType: T['type'], listener: EventListener<T>): () => void;
+    /**
+     * Add listener for all events
+     */
+    onAny(listener: EventListener): () => void;
+    /**
+     * Remove event listener
+     */
+    off<T extends CilowEvent>(eventType: T['type'], listener: EventListener<T>): void;
+    /**
+     * Remove all listeners for an event type
+     */
+    offAll(eventType?: string): void;
+    /**
+     * Listen for memory created events
+     */
+    onMemoryCreated(listener: EventListener<MemoryCreatedEvent>): () => void;
+    /**
+     * Listen for memory updated events
+     */
+    onMemoryUpdated(listener: EventListener<MemoryUpdatedEvent>): () => void;
+    /**
+     * Listen for memory deleted events
+     */
+    onMemoryDeleted(listener: EventListener<MemoryDeletedEvent>): () => void;
+    /**
+     * Listen for memory tier changed events
+     */
+    onMemoryTierChanged(listener: EventListener<MemoryTierChangedEvent>): () => void;
+    /**
+     * Listen for graph node created events
+     */
+    onGraphNodeCreated(listener: EventListener<GraphNodeCreatedEvent>): () => void;
+    /**
+     * Listen for graph edge created events
+     */
+    onGraphEdgeCreated(listener: EventListener<GraphEdgeCreatedEvent>): () => void;
+    /**
+     * Listen for connection status changes
+     */
+    onConnectionStatus(listener: EventListener<ConnectionStatusEvent>): () => void;
+    /**
+     * Wait for specific event (one-time)
+     */
+    once<T extends CilowEvent>(eventType: T['type'], timeout?: number): Promise<T>;
+    private send;
+    private sendSubscription;
+    private resubscribe;
+    private flushMessageQueue;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private emit;
+    private emitStatusEvent;
+}
+/**
+ * Create a WebSocket client instance (convenience function)
+ */
+declare function createWebSocket(config: CilowConfig & WebSocketConfig): CilowWebSocket;
+
+export { CilowWebSocket, type ConnectionState, type EventListener, type SubscriptionFilter, createWebSocket };

package/dist/websocket.d.ts

@@ -0,0 +1,160 @@
+import { CilowConfig, WebSocketConfig, CilowEvent, MemoryCreatedEvent, MemoryUpdatedEvent, MemoryDeletedEvent, MemoryTierChangedEvent, GraphNodeCreatedEvent, GraphEdgeCreatedEvent, ConnectionStatusEvent } from './types.js';
+
+/**
+ * Cilow WebSocket Client
+ *
+ * Real-time connection for memory updates, graph changes, and event streaming.
+ */
+
+/**
+ * WebSocket connection states
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Event listener type
+ */
+type EventListener<T extends CilowEvent = CilowEvent> = (event: T) => void;
+/**
+ * Subscription filter options
+ */
+interface SubscriptionFilter {
+    /** Filter by user ID */
+    userId?: string;
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Filter by tags */
+    tags?: string[];
+    /** Filter by event types */
+    eventTypes?: string[];
+}
+/**
+ * CilowWebSocket - Real-time WebSocket client for Cilow
+ *
+ * @example
+ * ```typescript
+ * const ws = new CilowWebSocket({
+ *   apiUrl: 'https://api.cilow.ai',
+ *   apiKey: 'your-key'
+ * });
+ *
+ * // Subscribe to memory events
+ * ws.on('memory.created', (event) => {
+ *   console.log('New memory:', event.memory);
+ * });
+ *
+ * // Connect
+ * await ws.connect();
+ *
+ * // Subscribe to specific user's events
+ * ws.subscribe({ userId: 'user-123' });
+ * ```
+ */
+declare class CilowWebSocket {
+    private ws;
+    private readonly wsUrl;
+    private readonly apiKey;
+    private readonly reconnectAttempts;
+    private readonly reconnectDelay;
+    private readonly heartbeatInterval;
+    private readonly messageQueueSize;
+    private state;
+    private reconnectCount;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private messageQueue;
+    private subscriptions;
+    private listeners;
+    private allListeners;
+    constructor(config: CilowConfig & WebSocketConfig);
+    /**
+     * Get current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to events with optional filter
+     */
+    subscribe(filter?: SubscriptionFilter): void;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(filter?: SubscriptionFilter): void;
+    /**
+     * Add event listener for specific event type
+     */
+    on<T extends CilowEvent>(eventType: T['type'], listener: EventListener<T>): () => void;
+    /**
+     * Add listener for all events
+     */
+    onAny(listener: EventListener): () => void;
+    /**
+     * Remove event listener
+     */
+    off<T extends CilowEvent>(eventType: T['type'], listener: EventListener<T>): void;
+    /**
+     * Remove all listeners for an event type
+     */
+    offAll(eventType?: string): void;
+    /**
+     * Listen for memory created events
+     */
+    onMemoryCreated(listener: EventListener<MemoryCreatedEvent>): () => void;
+    /**
+     * Listen for memory updated events
+     */
+    onMemoryUpdated(listener: EventListener<MemoryUpdatedEvent>): () => void;
+    /**
+     * Listen for memory deleted events
+     */
+    onMemoryDeleted(listener: EventListener<MemoryDeletedEvent>): () => void;
+    /**
+     * Listen for memory tier changed events
+     */
+    onMemoryTierChanged(listener: EventListener<MemoryTierChangedEvent>): () => void;
+    /**
+     * Listen for graph node created events
+     */
+    onGraphNodeCreated(listener: EventListener<GraphNodeCreatedEvent>): () => void;
+    /**
+     * Listen for graph edge created events
+     */
+    onGraphEdgeCreated(listener: EventListener<GraphEdgeCreatedEvent>): () => void;
+    /**
+     * Listen for connection status changes
+     */
+    onConnectionStatus(listener: EventListener<ConnectionStatusEvent>): () => void;
+    /**
+     * Wait for specific event (one-time)
+     */
+    once<T extends CilowEvent>(eventType: T['type'], timeout?: number): Promise<T>;
+    private send;
+    private sendSubscription;
+    private resubscribe;
+    private flushMessageQueue;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private emit;
+    private emitStatusEvent;
+}
+/**
+ * Create a WebSocket client instance (convenience function)
+ */
+declare function createWebSocket(config: CilowConfig & WebSocketConfig): CilowWebSocket;
+
+export { CilowWebSocket, type ConnectionState, type EventListener, type SubscriptionFilter, createWebSocket };

package/dist/websocket.js

@@ -0,0 +1,342 @@
+'use strict';
+
+// src/websocket.ts
+var CilowWebSocket = class {
+  constructor(config) {
+    this.ws = null;
+    this.state = "disconnected";
+    this.reconnectCount = 0;
+    this.heartbeatTimer = null;
+    this.reconnectTimer = null;
+    this.messageQueue = [];
+    this.subscriptions = [];
+    this.listeners = /* @__PURE__ */ new Map();
+    this.allListeners = /* @__PURE__ */ new Set();
+    const httpUrl = config.apiUrl.replace(/\/$/, "");
+    this.wsUrl = config.wsUrl ?? httpUrl.replace(/^http/, "ws") + "/ws";
+    this.apiKey = config.apiKey;
+    this.reconnectAttempts = config.reconnectAttempts ?? 5;
+    this.reconnectDelay = config.reconnectDelay ?? 1e3;
+    this.heartbeatInterval = config.heartbeatInterval ?? 3e4;
+    this.messageQueueSize = config.messageQueueSize ?? 100;
+  }
+  /**
+   * Get current connection state
+   */
+  get connectionState() {
+    return this.state;
+  }
+  /**
+   * Check if connected
+   */
+  get isConnected() {
+    return this.state === "connected";
+  }
+  /**
+   * Connect to the WebSocket server
+   */
+  async connect() {
+    if (this.state === "connected" || this.state === "connecting") {
+      return;
+    }
+    this.state = "connecting";
+    this.emitStatusEvent("connecting");
+    return new Promise((resolve, reject) => {
+      try {
+        const url = new URL(this.wsUrl);
+        url.searchParams.set("token", this.apiKey);
+        this.ws = new WebSocket(url.toString());
+        this.ws.onopen = () => {
+          this.state = "connected";
+          this.reconnectCount = 0;
+          this.emitStatusEvent("connected");
+          this.startHeartbeat();
+          this.flushMessageQueue();
+          this.resubscribe();
+          resolve();
+        };
+        this.ws.onclose = (event) => {
+          this.handleClose(event);
+        };
+        this.ws.onerror = (error) => {
+          if (this.state === "connecting") {
+            reject(new Error("WebSocket connection failed"));
+          }
+          this.handleError(error);
+        };
+        this.ws.onmessage = (event) => {
+          this.handleMessage(event);
+        };
+      } catch (error) {
+        this.state = "disconnected";
+        reject(error);
+      }
+    });
+  }
+  /**
+   * Disconnect from the WebSocket server
+   */
+  disconnect() {
+    this.stopHeartbeat();
+    this.clearReconnectTimer();
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.close(1e3, "Client disconnect");
+      this.ws = null;
+    }
+    this.state = "disconnected";
+    this.emitStatusEvent("disconnected", "Client initiated disconnect");
+  }
+  /**
+   * Subscribe to events with optional filter
+   */
+  subscribe(filter) {
+    if (filter) {
+      this.subscriptions.push(filter);
+    }
+    if (this.isConnected) {
+      this.sendSubscription(filter);
+    }
+  }
+  /**
+   * Unsubscribe from events
+   */
+  unsubscribe(filter) {
+    if (filter) {
+      this.subscriptions = this.subscriptions.filter(
+        (s) => s.userId !== filter.userId || s.sessionId !== filter.sessionId || JSON.stringify(s.tags) !== JSON.stringify(filter.tags)
+      );
+    } else {
+      this.subscriptions = [];
+    }
+    if (this.isConnected) {
+      this.send({
+        type: "unsubscribe",
+        filter
+      });
+    }
+  }
+  /**
+   * Add event listener for specific event type
+   */
+  on(eventType, listener) {
+    if (!this.listeners.has(eventType)) {
+      this.listeners.set(eventType, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(eventType).add(listener);
+    return () => {
+      this.listeners.get(eventType)?.delete(listener);
+    };
+  }
+  /**
+   * Add listener for all events
+   */
+  onAny(listener) {
+    this.allListeners.add(listener);
+    return () => {
+      this.allListeners.delete(listener);
+    };
+  }
+  /**
+   * Remove event listener
+   */
+  off(eventType, listener) {
+    this.listeners.get(eventType)?.delete(listener);
+  }
+  /**
+   * Remove all listeners for an event type
+   */
+  offAll(eventType) {
+    if (eventType) {
+      this.listeners.delete(eventType);
+    } else {
+      this.listeners.clear();
+      this.allListeners.clear();
+    }
+  }
+  /**
+   * Listen for memory created events
+   */
+  onMemoryCreated(listener) {
+    return this.on("memory.created", listener);
+  }
+  /**
+   * Listen for memory updated events
+   */
+  onMemoryUpdated(listener) {
+    return this.on("memory.updated", listener);
+  }
+  /**
+   * Listen for memory deleted events
+   */
+  onMemoryDeleted(listener) {
+    return this.on("memory.deleted", listener);
+  }
+  /**
+   * Listen for memory tier changed events
+   */
+  onMemoryTierChanged(listener) {
+    return this.on("memory.tier_changed", listener);
+  }
+  /**
+   * Listen for graph node created events
+   */
+  onGraphNodeCreated(listener) {
+    return this.on("graph.node_created", listener);
+  }
+  /**
+   * Listen for graph edge created events
+   */
+  onGraphEdgeCreated(listener) {
+    return this.on("graph.edge_created", listener);
+  }
+  /**
+   * Listen for connection status changes
+   */
+  onConnectionStatus(listener) {
+    return this.on("connection.status", listener);
+  }
+  /**
+   * Wait for specific event (one-time)
+   */
+  once(eventType, timeout) {
+    return new Promise((resolve, reject) => {
+      const timeoutId = timeout ? setTimeout(() => {
+        unsubscribe();
+        reject(new Error(`Timeout waiting for event: ${eventType}`));
+      }, timeout) : null;
+      const unsubscribe = this.on(eventType, (event) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        unsubscribe();
+        resolve(event);
+      });
+    });
+  }
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+  send(message) {
+    const data = JSON.stringify(message);
+    if (this.isConnected && this.ws) {
+      this.ws.send(data);
+    } else {
+      if (this.messageQueue.length >= this.messageQueueSize) {
+        this.messageQueue.shift();
+      }
+      this.messageQueue.push(data);
+    }
+  }
+  sendSubscription(filter) {
+    this.send({
+      type: "subscribe",
+      filter: filter ?? {}
+    });
+  }
+  resubscribe() {
+    for (const filter of this.subscriptions) {
+      this.sendSubscription(filter);
+    }
+  }
+  flushMessageQueue() {
+    while (this.messageQueue.length > 0 && this.isConnected && this.ws) {
+      const message = this.messageQueue.shift();
+      if (message) {
+        this.ws.send(message);
+      }
+    }
+  }
+  handleMessage(event) {
+    try {
+      const data = JSON.parse(event.data);
+      this.emit(data);
+    } catch (error) {
+      console.error("Failed to parse WebSocket message:", error);
+    }
+  }
+  handleClose(event) {
+    this.stopHeartbeat();
+    if (event.code === 1e3) {
+      this.state = "disconnected";
+      this.emitStatusEvent("disconnected", "Connection closed normally");
+      return;
+    }
+    if (this.reconnectCount < this.reconnectAttempts) {
+      this.state = "reconnecting";
+      this.emitStatusEvent("reconnecting", `Reconnecting (attempt ${this.reconnectCount + 1}/${this.reconnectAttempts})`);
+      this.scheduleReconnect();
+    } else {
+      this.state = "disconnected";
+      this.emitStatusEvent("disconnected", "Max reconnection attempts reached");
+    }
+  }
+  handleError(_error) {
+    console.error("WebSocket error occurred");
+  }
+  scheduleReconnect() {
+    this.clearReconnectTimer();
+    const delay = this.reconnectDelay * Math.pow(2, this.reconnectCount);
+    this.reconnectCount++;
+    this.reconnectTimer = setTimeout(async () => {
+      try {
+        await this.connect();
+      } catch {
+      }
+    }, delay);
+  }
+  clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (this.isConnected) {
+        this.send({ type: "ping" });
+      }
+    }, this.heartbeatInterval);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  emit(event) {
+    const typeListeners = this.listeners.get(event.type);
+    if (typeListeners) {
+      for (const listener of typeListeners) {
+        try {
+          listener(event);
+        } catch (error) {
+          console.error("Error in event listener:", error);
+        }
+      }
+    }
+    for (const listener of this.allListeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("Error in event listener:", error);
+      }
+    }
+  }
+  emitStatusEvent(status, reason) {
+    const event = {
+      type: "connection.status",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      status: status === "connecting" ? "reconnecting" : status,
+      reason
+    };
+    this.emit(event);
+  }
+};
+function createWebSocket(config) {
+  return new CilowWebSocket(config);
+}
+
+exports.CilowWebSocket = CilowWebSocket;
+exports.createWebSocket = createWebSocket;
+//# sourceMappingURL=websocket.js.map
+//# sourceMappingURL=websocket.js.map