notif-agent 1.0.0

package/dist/index.mjs

@@ -0,0 +1,729 @@
+// src/client/EventEmitter.ts
+var EventEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  globalListeners = /* @__PURE__ */ new Set();
+  /**
+   * Bind a callback to a specific event name.
+   */
+  bind(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return this;
+  }
+  /**
+   * Unbind a callback from a specific event name, or all callbacks if callback is omitted.
+   * If both event and callback are omitted, all listeners are removed.
+   */
+  unbind(event, callback) {
+    if (!event) {
+      this.listeners.clear();
+      return this;
+    }
+    if (!callback) {
+      this.listeners.delete(event);
+      return this;
+    }
+    const set = this.listeners.get(event);
+    if (set) {
+      set.delete(callback);
+      if (set.size === 0) {
+        this.listeners.delete(event);
+      }
+    }
+    return this;
+  }
+  /**
+   * Bind a callback to ALL incoming events on this emitter.
+   */
+  bind_global(callback) {
+    this.globalListeners.add(callback);
+    return this;
+  }
+  /**
+   * Unbind a global callback, or all global callbacks if callback is omitted.
+   */
+  unbind_global(callback) {
+    if (!callback) {
+      this.globalListeners.clear();
+      return this;
+    }
+    this.globalListeners.delete(callback);
+    return this;
+  }
+  /**
+   * Emit an event to registered listeners and global listeners.
+   */
+  emit(event, data, metadata) {
+    const set = this.listeners.get(event);
+    if (set) {
+      for (const cb of Array.from(set)) {
+        try {
+          cb(data, metadata);
+        } catch (err) {
+          console.error(`[notif-agent] Error in listener for event "${event}":`, err);
+        }
+      }
+    }
+    for (const globalCb of Array.from(this.globalListeners)) {
+      try {
+        globalCb(event, data, metadata);
+      } catch (err) {
+        console.error(`[notif-agent] Error in global listener for event "${event}":`, err);
+      }
+    }
+  }
+  /**
+   * Clear all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+    this.globalListeners.clear();
+  }
+};
+
+// src/client/Channel.ts
+var Channel = class {
+  name;
+  state = "subscribing";
+  emitter = new EventEmitter();
+  constructor(name) {
+    this.name = name;
+  }
+  /**
+   * Whether the channel is currently successfully subscribed.
+   */
+  get subscribed() {
+    return this.state === "subscribed";
+  }
+  /**
+   * Bind an event listener to this channel.
+   *
+   * Example:
+   * ```ts
+   * channel.bind('new-comment', (data) => {
+   *   console.log(data);
+   * });
+   * ```
+   */
+  bind(event, callback) {
+    this.emitter.bind(event, callback);
+    return this;
+  }
+  /**
+   * Unbind an event listener from this channel.
+   */
+  unbind(event, callback) {
+    this.emitter.unbind(event, callback);
+    return this;
+  }
+  /**
+   * Bind a global listener to all events received on this channel.
+   *
+   * Example:
+   * ```ts
+   * channel.bind_global((eventName, data) => {
+   *   console.log(`Event ${eventName}:`, data);
+   * });
+   * ```
+   */
+  bind_global(callback) {
+    this.emitter.bind_global(callback);
+    return this;
+  }
+  /**
+   * Unbind a global listener from this channel.
+   */
+  unbind_global(callback) {
+    this.emitter.unbind_global(callback);
+    return this;
+  }
+  /**
+   * Internal method to dispatch an event onto this channel.
+   */
+  handleEvent(event, data, metadata) {
+    this.emitter.emit(event, data, {
+      ...metadata,
+      event,
+      channel: this.name
+    });
+  }
+  /**
+   * Internal method to update subscription status and fire Pusher-compatible subscription events.
+   */
+  setSubscribed(data) {
+    this.state = "subscribed";
+    this.handleEvent("subscription_succeeded", data ?? {});
+    this.handleEvent("pusher:subscription_succeeded", data ?? {});
+  }
+  /**
+   * Internal method to set subscription error.
+   */
+  setSubscriptionError(error) {
+    this.state = "error";
+    this.handleEvent("subscription_error", error);
+    this.handleEvent("pusher:subscription_error", error);
+  }
+  /**
+   * Internal method called when channel is unsubscribed.
+   */
+  setUnsubscribed() {
+    this.state = "unsubscribed";
+    this.emitter.clear();
+  }
+};
+
+// src/client/ConnectionManager.ts
+var ConnectionManager = class {
+  state = "initialized";
+  clientId = null;
+  /**
+   * Pusher-compatible alias for clientId.
+   */
+  get socket_id() {
+    return this.clientId;
+  }
+  emitter = new EventEmitter();
+  options;
+  eventSource = null;
+  abortController = null;
+  reconnectAttempts = 0;
+  reconnectTimer = null;
+  heartbeatTimer = null;
+  isManuallyClosed = false;
+  constructor(url, options = {}) {
+    this.options = {
+      url,
+      headers: options.headers,
+      queryParams: options.queryParams,
+      withCredentials: options.withCredentials ?? false,
+      transport: options.transport ?? "auto",
+      reconnectBaseDelay: options.reconnectBaseDelay ?? 1e3,
+      reconnectMaxDelay: options.reconnectMaxDelay ?? 3e4,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? Infinity,
+      heartbeatTimeout: options.heartbeatTimeout ?? 45e3,
+      autoConnect: options.autoConnect ?? true,
+      debug: options.debug ?? false
+    };
+    if (this.options.autoConnect) {
+      setTimeout(() => {
+        if (!this.isManuallyClosed && this.state === "initialized") {
+          this.connect();
+        }
+      }, 0);
+    }
+  }
+  bind(event, callback) {
+    this.emitter.bind(event, callback);
+    return this;
+  }
+  unbind(event, callback) {
+    this.emitter.unbind(event, callback);
+    return this;
+  }
+  connect() {
+    this.isManuallyClosed = false;
+    this.clearTimers();
+    if (this.state === "connected" || this.state === "connecting") {
+      return;
+    }
+    this.transition("connecting");
+    this.establishConnection();
+  }
+  disconnect() {
+    this.isManuallyClosed = true;
+    this.clientId = null;
+    this.clearTimers();
+    this.closeActiveTransport();
+    this.transition("disconnected");
+  }
+  transition(nextState) {
+    if (this.state === nextState) return;
+    const previous = this.state;
+    this.state = nextState;
+    this.log(`State transition: ${previous} -> ${nextState}`);
+    const payload = { previous, current: nextState };
+    this.emitter.emit("state_change", payload);
+    this.emitter.emit(nextState, payload);
+  }
+  async establishConnection() {
+    try {
+      const headers = await this.resolveHeaders();
+      const hasCustomHeaders = headers && Object.keys(headers).length > 0;
+      const shouldUseFetch = this.options.transport === "fetch" || this.options.transport === "auto" && (hasCustomHeaders || typeof EventSource === "undefined");
+      const fullUrl = this.buildUrl();
+      if (shouldUseFetch) {
+        this.log(`Connecting via Fetch SSE stream: ${fullUrl}`);
+        this.connectViaFetch(fullUrl, headers);
+      } else {
+        this.log(`Connecting via native EventSource: ${fullUrl}`);
+        this.connectViaEventSource(fullUrl);
+      }
+    } catch (err) {
+      this.handleConnectionFailure(err);
+    }
+  }
+  connectViaEventSource(url) {
+    this.closeActiveTransport();
+    try {
+      const es = new EventSource(url, {
+        withCredentials: this.options.withCredentials
+      });
+      this.eventSource = es;
+      es.onopen = () => {
+        this.handleConnectionSuccess();
+      };
+      es.onmessage = (e) => {
+        this.resetHeartbeat();
+        this.parseAndDispatchMessage("message", e.data, e.lastEventId);
+      };
+      es.onerror = (err) => {
+        this.log("EventSource error occurred", err);
+        if (es.readyState === EventSource.CLOSED) {
+          this.handleConnectionFailure(err);
+        } else {
+          this.transition("unavailable");
+        }
+      };
+    } catch (err) {
+      this.handleConnectionFailure(err);
+    }
+  }
+  async connectViaFetch(url, headers) {
+    this.closeActiveTransport();
+    this.abortController = new AbortController();
+    try {
+      const requestHeaders = {
+        Accept: "text/event-stream",
+        "Cache-Control": "no-cache",
+        ...headers
+      };
+      const response = await fetch(url, {
+        method: "GET",
+        headers: requestHeaders,
+        credentials: this.options.withCredentials ? "include" : "same-origin",
+        signal: this.abortController.signal
+      });
+      if (!response.ok) {
+        throw new Error(`SSE connection failed with HTTP status ${response.status}: ${response.statusText}`);
+      }
+      if (!response.body) {
+        throw new Error("Response body is null or stream reading is not supported");
+      }
+      this.handleConnectionSuccess();
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder("utf-8");
+      let buffer = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        this.resetHeartbeat();
+        buffer += decoder.decode(value, { stream: true });
+        const parts = buffer.split(/\r\n\r\n|\n\n/);
+        buffer = parts.pop() ?? "";
+        for (const part of parts) {
+          if (part.trim().length > 0) {
+            this.processSSEFrame(part);
+          }
+        }
+      }
+      if (!this.isManuallyClosed) {
+        this.handleConnectionFailure(new Error("SSE stream ended by server"));
+      }
+    } catch (err) {
+      if (err.name === "AbortError" || this.isManuallyClosed) {
+        return;
+      }
+      this.handleConnectionFailure(err);
+    }
+  }
+  processSSEFrame(frame) {
+    const lines = frame.split(/\r\n|\r|\n/);
+    let event = "message";
+    let data = "";
+    let id;
+    for (const line of lines) {
+      if (line.startsWith(":")) {
+        this.resetHeartbeat();
+        continue;
+      }
+      if (line.startsWith("event:")) {
+        event = line.slice(6).trim();
+      } else if (line.startsWith("data:")) {
+        const value = line.slice(5).trim();
+        data += (data ? "\n" : "") + value;
+      } else if (line.startsWith("id:")) {
+        id = line.slice(3).trim();
+      } else if (line.startsWith("retry:")) {
+        const retryMs = parseInt(line.slice(6).trim(), 10);
+        if (!isNaN(retryMs)) {
+          this.options.reconnectBaseDelay = retryMs;
+        }
+      }
+    }
+    if (data || event !== "message") {
+      this.parseAndDispatchMessage(event, data, id);
+    }
+  }
+  parseAndDispatchMessage(sseEvent, rawData, id) {
+    let parsedData = rawData;
+    let channel;
+    let eventName = sseEvent;
+    if (rawData) {
+      try {
+        const json = JSON.parse(rawData);
+        if (typeof json === "object" && json !== null) {
+          if (json.channel && typeof json.channel === "string") {
+            channel = json.channel;
+          }
+          if (json.event && typeof json.event === "string") {
+            eventName = json.event;
+          }
+          if ("data" in json) {
+            parsedData = json.data;
+          } else {
+            parsedData = json;
+          }
+        } else {
+          parsedData = json;
+        }
+      } catch {
+        parsedData = rawData;
+      }
+    }
+    if (eventName === "connected" && parsedData && typeof parsedData === "object" && parsedData.clientId) {
+      this.clientId = parsedData.clientId;
+      this.emitter.emit("handshake", parsedData);
+    }
+    if (eventName === "ping" || eventName === "heartbeat" || eventName === ":ping") {
+      this.resetHeartbeat();
+      return;
+    }
+    const payload = {
+      channel,
+      event: eventName,
+      data: parsedData,
+      id,
+      timestamp: Date.now()
+    };
+    this.emitter.emit("message", payload);
+  }
+  handleConnectionSuccess() {
+    this.reconnectAttempts = 0;
+    this.transition("connected");
+    this.resetHeartbeat();
+  }
+  handleConnectionFailure(error) {
+    this.log("Connection failed or dropped", error);
+    this.closeActiveTransport();
+    this.clearHeartbeat();
+    if (this.isManuallyClosed) {
+      return;
+    }
+    this.emitter.emit("error", error);
+    this.reconnectAttempts++;
+    if (this.reconnectAttempts > this.options.maxReconnectAttempts) {
+      this.log(`Max reconnect attempts (${this.options.maxReconnectAttempts}) exceeded. State -> failed`);
+      this.transition("failed");
+      return;
+    }
+    this.transition("unavailable");
+    this.scheduleReconnect();
+  }
+  scheduleReconnect() {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    const delay = Math.min(
+      this.options.reconnectBaseDelay * Math.pow(1.5, this.reconnectAttempts - 1),
+      this.options.reconnectMaxDelay
+    );
+    const jitter = delay * 0.2 * (Math.random() - 0.5);
+    const totalDelay = Math.max(100, Math.round(delay + jitter));
+    this.log(`Scheduling reconnect in ${totalDelay}ms (attempt #${this.reconnectAttempts})`);
+    this.reconnectTimer = setTimeout(() => {
+      if (!this.isManuallyClosed && this.state !== "connected") {
+        this.transition("connecting");
+        this.establishConnection();
+      }
+    }, totalDelay);
+  }
+  resetHeartbeat() {
+    this.clearHeartbeat();
+    if (this.options.heartbeatTimeout <= 0) return;
+    this.heartbeatTimer = setTimeout(() => {
+      this.log(`Heartbeat timeout (${this.options.heartbeatTimeout}ms) exceeded. Connection dropped.`);
+      this.handleConnectionFailure(new Error("Heartbeat timeout"));
+    }, this.options.heartbeatTimeout);
+  }
+  clearHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearTimeout(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  clearTimers() {
+    this.clearHeartbeat();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+  closeActiveTransport() {
+    if (this.eventSource) {
+      try {
+        this.eventSource.close();
+      } catch {
+      }
+      this.eventSource = null;
+    }
+    if (this.abortController) {
+      try {
+        this.abortController.abort();
+      } catch {
+      }
+      this.abortController = null;
+    }
+  }
+  buildUrl() {
+    const url = new URL(this.options.url, typeof window !== "undefined" ? window.location.href : "http://localhost");
+    if (this.options.queryParams) {
+      for (const [key, value] of Object.entries(this.options.queryParams)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async resolveHeaders() {
+    if (!this.options.headers) return void 0;
+    if (typeof this.options.headers === "function") {
+      return await this.options.headers();
+    }
+    return this.options.headers;
+  }
+  log(...args) {
+    if (this.options.debug) {
+      console.log("[notif-agent:connection]", ...args);
+    }
+  }
+};
+
+// src/client/NotifAgent.ts
+var NotifAgent = class {
+  connection;
+  options;
+  channels = /* @__PURE__ */ new Map();
+  globalEmitter = new EventEmitter();
+  /**
+   * Unique client connection ID provided by NotifServer handshake.
+   */
+  get clientId() {
+    return this.connection.clientId;
+  }
+  /**
+   * Pusher-compatible alias for clientId.
+   */
+  get socket_id() {
+    return this.connection.clientId;
+  }
+  constructor(urlOrOptions, maybeOptions) {
+    let options;
+    if (typeof urlOrOptions === "string") {
+      options = { ...maybeOptions ?? {}, url: urlOrOptions };
+    } else {
+      options = urlOrOptions;
+    }
+    if (!options.url) {
+      throw new Error("[notif-agent] SSE URL must be specified");
+    }
+    this.options = options;
+    this.connection = new ConnectionManager(options.url, options);
+    this.connection.bind("message", (payload) => {
+      this.routeMessage(payload);
+    });
+    const triggerChannelSubscriptions = () => {
+      for (const channel of this.channels.values()) {
+        const isPrivate = channel.name.startsWith("private-") || channel.name.startsWith("presence-");
+        if (isPrivate && this.options.authEndpoint) {
+          this.authorizeChannel(channel);
+        } else {
+          channel.setSubscribed();
+        }
+      }
+    };
+    this.connection.bind("handshake", () => {
+      triggerChannelSubscriptions();
+    });
+    this.connection.bind("connected", () => {
+      if (this.connection.clientId || !this.options.authEndpoint) {
+        triggerChannelSubscriptions();
+      }
+    });
+  }
+  /**
+   * Subscribe to a channel.
+   *
+   * Example:
+   * ```ts
+   * const channel = agent.subscribe('orders');
+   * channel.bind('created', (order) => { ... });
+   * ```
+   */
+  subscribe(channelName) {
+    if (!channelName) {
+      throw new Error("[notif-agent] Channel name cannot be empty");
+    }
+    let channel = this.channels.get(channelName);
+    if (!channel) {
+      channel = new Channel(channelName);
+      this.channels.set(channelName, channel);
+      if (this.connection.state === "connected") {
+        setTimeout(() => {
+          const isPrivate = channelName.startsWith("private-") || channelName.startsWith("presence-");
+          if (isPrivate && this.options.authEndpoint) {
+            this.authorizeChannel(channel);
+          } else {
+            channel?.setSubscribed();
+          }
+        }, 0);
+      }
+    }
+    return channel;
+  }
+  /**
+   * Internal authorization helper for private/presence channels.
+   */
+  async authorizeChannel(channel) {
+    if (!this.options.authEndpoint) {
+      channel.setSubscribed();
+      return;
+    }
+    try {
+      let customHeaders = {};
+      if (typeof this.options.auth?.headers === "function") {
+        customHeaders = await this.options.auth.headers();
+      } else if (this.options.auth?.headers) {
+        customHeaders = this.options.auth.headers;
+      }
+      const body = {
+        clientId: this.connection.clientId,
+        socket_id: this.connection.clientId,
+        channel: channel.name,
+        ...this.options.auth?.params ?? {}
+      };
+      const response = await fetch(this.options.authEndpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...customHeaders
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`[notif-agent] Authorization failed (${response.status}): ${errorText}`);
+      }
+      const authData = await response.json().catch(() => ({}));
+      channel.setSubscribed(authData);
+    } catch (err) {
+      channel.setSubscriptionError(err);
+    }
+  }
+  /**
+   * Unsubscribe from a channel.
+   */
+  unsubscribe(channelName) {
+    const channel = this.channels.get(channelName);
+    if (channel) {
+      channel.setUnsubscribed();
+      this.channels.delete(channelName);
+    }
+  }
+  /**
+   * Get an existing subscribed channel by name, if any.
+   */
+  channel(channelName) {
+    return this.channels.get(channelName);
+  }
+  /**
+   * Return all currently subscribed channels.
+   */
+  allChannels() {
+    return Array.from(this.channels.values());
+  }
+  /**
+   * Bind to an event across all channels or global events.
+   *
+   * Example:
+   * ```ts
+   * agent.bind('system-alert', (data) => console.log(data));
+   * ```
+   */
+  bind(event, callback) {
+    this.globalEmitter.bind(event, callback);
+    return this;
+  }
+  /**
+   * Unbind an event listener.
+   */
+  unbind(event, callback) {
+    this.globalEmitter.unbind(event, callback);
+    return this;
+  }
+  /**
+   * Bind to all events regardless of name.
+   */
+  bind_global(callback) {
+    this.globalEmitter.bind_global(callback);
+    return this;
+  }
+  /**
+   * Unbind a global event listener.
+   */
+  unbind_global(callback) {
+    this.globalEmitter.unbind_global(callback);
+    return this;
+  }
+  /**
+   * Connect to the SSE endpoint.
+   */
+  connect() {
+    this.connection.connect();
+  }
+  /**
+   * Disconnect from the SSE endpoint.
+   */
+  disconnect() {
+    this.connection.disconnect();
+  }
+  /**
+   * Route incoming SSE message to global emitters and specific channels.
+   */
+  routeMessage(payload) {
+    const metadata = {
+      channel: payload.channel,
+      event: payload.event,
+      id: payload.id,
+      timestamp: payload.timestamp
+    };
+    this.globalEmitter.emit(payload.event, payload.data, metadata);
+    if (payload.channel) {
+      const targetChannel = this.channels.get(payload.channel);
+      if (targetChannel) {
+        targetChannel.handleEvent(payload.event, payload.data, metadata);
+      }
+    } else {
+      for (const ch of this.channels.values()) {
+        ch.handleEvent(payload.event, payload.data, metadata);
+      }
+    }
+  }
+};
+
+// src/index.ts
+var src_default = NotifAgent;
+
+export { Channel, ConnectionManager, EventEmitter, NotifAgent, src_default as default };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map