simple-support-chat 0.3.3 → 0.4.1

package/dist/server/index.d.cts

@@ -1,3 +1,59 @@
+/** Event types that the reply emitter can broadcast */
+type ReplyEventType = "reply" | "thread_created";
+/** Payload for a reply event */
+interface ReplyEvent {
+    type: "reply";
+    sessionId: string;
+    reply: Reply;
+}
+/** Payload for a thread_created event */
+interface ThreadCreatedEvent {
+    type: "thread_created";
+    sessionId: string;
+    threadTs: string;
+}
+/** Union of all emitter event payloads */
+type EmitterEvent = ReplyEvent | ThreadCreatedEvent;
+/** Callback function signature for emitter subscribers */
+type EmitterCallback = (event: EmitterEvent) => void;
+/** The reply emitter interface */
+interface ReplyEmitter {
+    /** Emit a reply event to all subscribers for a given sessionId */
+    emit(sessionId: string, reply: Reply): void;
+    /** Emit a thread_created event to all subscribers for a given sessionId */
+    emitThreadCreated(sessionId: string, threadTs: string): void;
+    /** Subscribe to events for a given sessionId */
+    subscribe(sessionId: string, callback: EmitterCallback): void;
+    /** Unsubscribe a callback from a given sessionId */
+    unsubscribe(sessionId: string, callback: EmitterCallback): void;
+}
+/**
+ * Creates an in-process event emitter for broadcasting reply events to
+ * connected SSE clients.
+ *
+ * This is intentionally simple — it's an in-process pub/sub mechanism,
+ * not a distributed message broker. It works within a single server process,
+ * which is the expected use case for this SDK.
+ *
+ * @example
+ * ```ts
+ * import { createReplyEmitter } from 'simple-support-chat/server';
+ *
+ * const emitter = createReplyEmitter();
+ *
+ * // Subscribe to replies for a session
+ * emitter.subscribe('session-123', (event) => {
+ *   if (event.type === 'reply') {
+ *     console.log('New reply:', event.reply);
+ *   }
+ * });
+ *
+ * // Emit a reply (typically called by the webhook handler)
+ * emitter.emit('session-123', reply);
+ * ```
+ */
+declare function createReplyEmitter(): ReplyEmitter;
+
 /** Slack configuration for the support handler */
 interface SlackConfig {
     /** Slack Bot User OAuth Token (xoxb-...) */
@@ -15,6 +71,8 @@ interface SupportHandlerOptions extends SlackConfig {
     onMessage?: (data: IncomingMessage) => void | Promise<void>;
     /** Optional pluggable storage backend. Defaults to InMemoryStore. */
     store?: SupportChatStore;
+    /** Optional reply emitter for broadcasting events to SSE clients */
+    emitter?: ReplyEmitter;
 }
 /** User info sent from the client */
 interface MessageUser {
@@ -162,6 +220,8 @@ interface WebhookHandlerOptions {
     store: SupportChatStore;
     /** Slack signing secret for request verification */
     signingSecret: string;
+    /** Optional reply emitter for broadcasting replies to SSE clients */
+    emitter?: ReplyEmitter;
 }
 /**
  * Verify Slack request signature.
@@ -273,6 +333,65 @@ declare function createRepliesHandler(options: RepliesHandlerOptions): (request:
  */
 declare function createExpressRepliesHandler(options: RepliesHandlerOptions): (req: ExpressRepliesRequest, res: ExpressResponse) => Promise<void>;
 
+/** Options for createSSEHandler / createExpressSSEHandler */
+interface SSEHandlerOptions {
+    /** Reply emitter instance (shared with webhook handler) */
+    emitter: ReplyEmitter;
+    /** Heartbeat interval in milliseconds. Defaults to 30000 (30 seconds). */
+    heartbeatInterval?: number;
+}
+/** Minimal Express-compatible response for SSE streaming */
+interface ExpressSSEResponse {
+    writeHead(statusCode: number, headers: Record<string, string>): void;
+    write(chunk: string): boolean;
+    end(): void;
+    on(event: string, listener: () => void): void;
+}
+/** Minimal Express-compatible request for SSE */
+interface ExpressSSERequest {
+    query?: Record<string, string | string[] | undefined>;
+    method?: string;
+    on?(event: string, listener: () => void): void;
+}
+/**
+ * Creates an SSE stream handler using the Web API Request/Response standard.
+ *
+ * Clients connect via GET with `?sessionId={id}`. The handler subscribes to
+ * the emitter for that session and streams events as they arrive.
+ *
+ * Event types streamed:
+ * - `reply` — a new reply from the support team: `data: { reply: Reply }`
+ * - `thread_created` — a Slack thread was created: `data: { threadTs: string }`
+ * - `heartbeat` — keep-alive ping every 30s: `data: {}`
+ *
+ * Compatible with Next.js App Router, Remix, Hono, Deno, Bun, etc.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/support/sse/route.ts
+ * import { createSSEHandler, createReplyEmitter } from 'simple-support-chat/server';
+ *
+ * const emitter = createReplyEmitter();
+ * export const GET = createSSEHandler({ emitter });
+ * ```
+ */
+declare function createSSEHandler(options: SSEHandlerOptions): (request: Request) => Response;
+/**
+ * Creates an SSE stream handler for Express/Connect frameworks.
+ *
+ * @example Express
+ * ```ts
+ * import express from 'express';
+ * import { createExpressSSEHandler, createReplyEmitter } from 'simple-support-chat/server';
+ *
+ * const app = express();
+ * const emitter = createReplyEmitter();
+ *
+ * app.get('/api/support/sse', createExpressSSEHandler({ emitter }));
+ * ```
+ */
+declare function createExpressSSEHandler(options: SSEHandlerOptions): (req: ExpressSSERequest, res: ExpressSSEResponse) => void;
+
 /**
  * In-memory implementation of SupportChatStore.
  *
@@ -302,4 +421,4 @@ declare class InMemoryStore implements SupportChatStore {
  */
 declare function emojify(text: string): string;
 
-export { type ErrorResponse, type ExpressRepliesRequest, type ExpressRequest, type ExpressResponse, type ExpressWebhookRequest, type HandlerResponse, InMemoryStore, type IncomingMessage, type MessageContext, type MessageUser, type RepliesErrorResponse, type RepliesHandlerOptions, type RepliesResponse, type Reply, type SlackConfig, type SuccessResponse, type SupportChatStore, type SupportHandlerOptions, type ThreadRecord, type WebhookHandlerOptions, createExpressHandler, createExpressRepliesHandler, createExpressWebhookHandler, createRepliesHandler, createSupportHandler, createWebhookHandler, emojify, validateSlackToken, verifySlackSignature };
+export { type EmitterCallback, type EmitterEvent, type ErrorResponse, type ExpressRepliesRequest, type ExpressRequest, type ExpressResponse, type ExpressSSERequest, type ExpressSSEResponse, type ExpressWebhookRequest, type HandlerResponse, InMemoryStore, type IncomingMessage, type MessageContext, type MessageUser, type RepliesErrorResponse, type RepliesHandlerOptions, type RepliesResponse, type Reply, type ReplyEmitter, type ReplyEvent, type ReplyEventType, type SSEHandlerOptions, type SlackConfig, type SuccessResponse, type SupportChatStore, type SupportHandlerOptions, type ThreadCreatedEvent, type ThreadRecord, type WebhookHandlerOptions, createExpressHandler, createExpressRepliesHandler, createExpressSSEHandler, createExpressWebhookHandler, createRepliesHandler, createReplyEmitter, createSSEHandler, createSupportHandler, createWebhookHandler, emojify, validateSlackToken, verifySlackSignature };

package/dist/server/index.d.ts

@@ -1,3 +1,59 @@
+/** Event types that the reply emitter can broadcast */
+type ReplyEventType = "reply" | "thread_created";
+/** Payload for a reply event */
+interface ReplyEvent {
+    type: "reply";
+    sessionId: string;
+    reply: Reply;
+}
+/** Payload for a thread_created event */
+interface ThreadCreatedEvent {
+    type: "thread_created";
+    sessionId: string;
+    threadTs: string;
+}
+/** Union of all emitter event payloads */
+type EmitterEvent = ReplyEvent | ThreadCreatedEvent;
+/** Callback function signature for emitter subscribers */
+type EmitterCallback = (event: EmitterEvent) => void;
+/** The reply emitter interface */
+interface ReplyEmitter {
+    /** Emit a reply event to all subscribers for a given sessionId */
+    emit(sessionId: string, reply: Reply): void;
+    /** Emit a thread_created event to all subscribers for a given sessionId */
+    emitThreadCreated(sessionId: string, threadTs: string): void;
+    /** Subscribe to events for a given sessionId */
+    subscribe(sessionId: string, callback: EmitterCallback): void;
+    /** Unsubscribe a callback from a given sessionId */
+    unsubscribe(sessionId: string, callback: EmitterCallback): void;
+}
+/**
+ * Creates an in-process event emitter for broadcasting reply events to
+ * connected SSE clients.
+ *
+ * This is intentionally simple — it's an in-process pub/sub mechanism,
+ * not a distributed message broker. It works within a single server process,
+ * which is the expected use case for this SDK.
+ *
+ * @example
+ * ```ts
+ * import { createReplyEmitter } from 'simple-support-chat/server';
+ *
+ * const emitter = createReplyEmitter();
+ *
+ * // Subscribe to replies for a session
+ * emitter.subscribe('session-123', (event) => {
+ *   if (event.type === 'reply') {
+ *     console.log('New reply:', event.reply);
+ *   }
+ * });
+ *
+ * // Emit a reply (typically called by the webhook handler)
+ * emitter.emit('session-123', reply);
+ * ```
+ */
+declare function createReplyEmitter(): ReplyEmitter;
+
 /** Slack configuration for the support handler */
 interface SlackConfig {
     /** Slack Bot User OAuth Token (xoxb-...) */
@@ -15,6 +71,8 @@ interface SupportHandlerOptions extends SlackConfig {
     onMessage?: (data: IncomingMessage) => void | Promise<void>;
     /** Optional pluggable storage backend. Defaults to InMemoryStore. */
     store?: SupportChatStore;
+    /** Optional reply emitter for broadcasting events to SSE clients */
+    emitter?: ReplyEmitter;
 }
 /** User info sent from the client */
 interface MessageUser {
@@ -162,6 +220,8 @@ interface WebhookHandlerOptions {
     store: SupportChatStore;
     /** Slack signing secret for request verification */
     signingSecret: string;
+    /** Optional reply emitter for broadcasting replies to SSE clients */
+    emitter?: ReplyEmitter;
 }
 /**
  * Verify Slack request signature.
@@ -273,6 +333,65 @@ declare function createRepliesHandler(options: RepliesHandlerOptions): (request:
  */
 declare function createExpressRepliesHandler(options: RepliesHandlerOptions): (req: ExpressRepliesRequest, res: ExpressResponse) => Promise<void>;
 
+/** Options for createSSEHandler / createExpressSSEHandler */
+interface SSEHandlerOptions {
+    /** Reply emitter instance (shared with webhook handler) */
+    emitter: ReplyEmitter;
+    /** Heartbeat interval in milliseconds. Defaults to 30000 (30 seconds). */
+    heartbeatInterval?: number;
+}
+/** Minimal Express-compatible response for SSE streaming */
+interface ExpressSSEResponse {
+    writeHead(statusCode: number, headers: Record<string, string>): void;
+    write(chunk: string): boolean;
+    end(): void;
+    on(event: string, listener: () => void): void;
+}
+/** Minimal Express-compatible request for SSE */
+interface ExpressSSERequest {
+    query?: Record<string, string | string[] | undefined>;
+    method?: string;
+    on?(event: string, listener: () => void): void;
+}
+/**
+ * Creates an SSE stream handler using the Web API Request/Response standard.
+ *
+ * Clients connect via GET with `?sessionId={id}`. The handler subscribes to
+ * the emitter for that session and streams events as they arrive.
+ *
+ * Event types streamed:
+ * - `reply` — a new reply from the support team: `data: { reply: Reply }`
+ * - `thread_created` — a Slack thread was created: `data: { threadTs: string }`
+ * - `heartbeat` — keep-alive ping every 30s: `data: {}`
+ *
+ * Compatible with Next.js App Router, Remix, Hono, Deno, Bun, etc.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/support/sse/route.ts
+ * import { createSSEHandler, createReplyEmitter } from 'simple-support-chat/server';
+ *
+ * const emitter = createReplyEmitter();
+ * export const GET = createSSEHandler({ emitter });
+ * ```
+ */
+declare function createSSEHandler(options: SSEHandlerOptions): (request: Request) => Response;
+/**
+ * Creates an SSE stream handler for Express/Connect frameworks.
+ *
+ * @example Express
+ * ```ts
+ * import express from 'express';
+ * import { createExpressSSEHandler, createReplyEmitter } from 'simple-support-chat/server';
+ *
+ * const app = express();
+ * const emitter = createReplyEmitter();
+ *
+ * app.get('/api/support/sse', createExpressSSEHandler({ emitter }));
+ * ```
+ */
+declare function createExpressSSEHandler(options: SSEHandlerOptions): (req: ExpressSSERequest, res: ExpressSSEResponse) => void;
+
 /**
  * In-memory implementation of SupportChatStore.
  *
@@ -302,4 +421,4 @@ declare class InMemoryStore implements SupportChatStore {
  */
 declare function emojify(text: string): string;
 
-export { type ErrorResponse, type ExpressRepliesRequest, type ExpressRequest, type ExpressResponse, type ExpressWebhookRequest, type HandlerResponse, InMemoryStore, type IncomingMessage, type MessageContext, type MessageUser, type RepliesErrorResponse, type RepliesHandlerOptions, type RepliesResponse, type Reply, type SlackConfig, type SuccessResponse, type SupportChatStore, type SupportHandlerOptions, type ThreadRecord, type WebhookHandlerOptions, createExpressHandler, createExpressRepliesHandler, createExpressWebhookHandler, createRepliesHandler, createSupportHandler, createWebhookHandler, emojify, validateSlackToken, verifySlackSignature };
+export { type EmitterCallback, type EmitterEvent, type ErrorResponse, type ExpressRepliesRequest, type ExpressRequest, type ExpressResponse, type ExpressSSERequest, type ExpressSSEResponse, type ExpressWebhookRequest, type HandlerResponse, InMemoryStore, type IncomingMessage, type MessageContext, type MessageUser, type RepliesErrorResponse, type RepliesHandlerOptions, type RepliesResponse, type Reply, type ReplyEmitter, type ReplyEvent, type ReplyEventType, type SSEHandlerOptions, type SlackConfig, type SuccessResponse, type SupportChatStore, type SupportHandlerOptions, type ThreadCreatedEvent, type ThreadRecord, type WebhookHandlerOptions, createExpressHandler, createExpressRepliesHandler, createExpressSSEHandler, createExpressWebhookHandler, createRepliesHandler, createReplyEmitter, createSSEHandler, createSupportHandler, createWebhookHandler, emojify, validateSlackToken, verifySlackSignature };

package/dist/server/index.js

@@ -39,7 +39,7 @@ var InMemoryStore = class {
 
 // src/server/handler.ts
 async function handleMessage(body, options) {
-  const { slack, slackChannel, botName, botIcon, onMessage, store } = options;
+  const { slack, slackChannel, botName, botIcon, onMessage, store, emitter } = options;
   if (!body.message || typeof body.message !== "string") {
     return {
       data: { success: false, error: "Missing required field: message" },
@@ -102,6 +102,9 @@ ${body.message}`,
         user: body.user,
         context: body.context
       });
+      if (emitter) {
+        emitter.emitThreadCreated(body.sessionId, threadTs);
+      }
       return {
         data: { success: true, threadId: threadTs },
         status: 200
@@ -116,7 +119,7 @@ ${body.message}`,
   }
 }
 function createSupportHandler(options) {
-  const { slackBotToken, slackChannel, botName, botIcon, onMessage, store } = options;
+  const { slackBotToken, slackChannel, botName, botIcon, onMessage, store, emitter } = options;
   const slack = new WebClient(slackBotToken);
   const resolvedStore = store ?? new InMemoryStore();
   return async (request) => {
@@ -141,13 +144,14 @@ function createSupportHandler(options) {
       botName,
       botIcon,
       onMessage,
-      store: resolvedStore
+      store: resolvedStore,
+      emitter
     });
     return jsonResponse(result.data, result.status);
   };
 }
 function createExpressHandler(options) {
-  const { slackBotToken, slackChannel, botName, botIcon, onMessage, store } = options;
+  const { slackBotToken, slackChannel, botName, botIcon, onMessage, store, emitter } = options;
   const slack = new WebClient(slackBotToken);
   const resolvedStore = store ?? new InMemoryStore();
   return async (req, res) => {
@@ -158,7 +162,8 @@ function createExpressHandler(options) {
       botName,
       botIcon,
       onMessage,
-      store: resolvedStore
+      store: resolvedStore,
+      emitter
     });
     res.status(result.status).json(result.data);
   };
@@ -2130,7 +2135,7 @@ function verifySlackSignature(signingSecret, signature, timestamp, rawBody) {
   }
 }
 function createWebhookHandler(options) {
-  const { store, signingSecret } = options;
+  const { store, signingSecret, emitter } = options;
   return async (request) => {
     let rawBody;
     try {
@@ -2181,13 +2186,16 @@ function createWebhookHandler(options) {
         threadTs: event.thread_ts
       };
       await store.saveReply(threadRecord.sessionId, reply);
+      if (emitter) {
+        emitter.emit(threadRecord.sessionId, reply);
+      }
       return jsonResponse2({ ok: true }, 200);
     }
     return jsonResponse2({ ok: true }, 200);
   };
 }
 function createExpressWebhookHandler(options) {
-  const { store, signingSecret } = options;
+  const { store, signingSecret, emitter } = options;
   return async (req, res) => {
     const rawBody = typeof req.body === "string" ? req.body : Buffer.isBuffer(req.body) ? req.body.toString("utf-8") : JSON.stringify(req.body);
     const signature = req.headers?.["x-slack-signature"] ?? "";
@@ -2238,6 +2246,9 @@ function createExpressWebhookHandler(options) {
         threadTs: event.thread_ts
       };
       await store.saveReply(threadRecord.sessionId, reply);
+      if (emitter) {
+        emitter.emit(threadRecord.sessionId, reply);
+      }
       res.status(200).json({ ok: true });
       return;
     }
@@ -2300,6 +2311,188 @@ function jsonResponse3(data, status = 200) {
   });
 }
 
-export { InMemoryStore, createExpressHandler, createExpressRepliesHandler, createExpressWebhookHandler, createRepliesHandler, createSupportHandler, createWebhookHandler, emojify, validateSlackToken, verifySlackSignature };
+// src/server/emitter.ts
+function createReplyEmitter() {
+  const subscribers = /* @__PURE__ */ new Map();
+  return {
+    emit(sessionId, reply) {
+      const callbacks = subscribers.get(sessionId);
+      if (!callbacks) return;
+      const event = { type: "reply", sessionId, reply };
+      for (const cb of callbacks) {
+        try {
+          cb(event);
+        } catch {
+        }
+      }
+    },
+    emitThreadCreated(sessionId, threadTs) {
+      const callbacks = subscribers.get(sessionId);
+      if (!callbacks) return;
+      const event = {
+        type: "thread_created",
+        sessionId,
+        threadTs
+      };
+      for (const cb of callbacks) {
+        try {
+          cb(event);
+        } catch {
+        }
+      }
+    },
+    subscribe(sessionId, callback) {
+      let callbacks = subscribers.get(sessionId);
+      if (!callbacks) {
+        callbacks = /* @__PURE__ */ new Set();
+        subscribers.set(sessionId, callbacks);
+      }
+      callbacks.add(callback);
+    },
+    unsubscribe(sessionId, callback) {
+      const callbacks = subscribers.get(sessionId);
+      if (!callbacks) return;
+      callbacks.delete(callback);
+      if (callbacks.size === 0) {
+        subscribers.delete(sessionId);
+      }
+    }
+  };
+}
+
+// src/server/sse.ts
+function createSSEHandler(options) {
+  const { emitter, heartbeatInterval = 3e4 } = options;
+  return (request) => {
+    const url = new URL(request.url);
+    const sessionId = url.searchParams.get("sessionId");
+    if (!sessionId) {
+      return new Response(
+        JSON.stringify({ error: "Missing required query parameter: sessionId" }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+    const sid = sessionId;
+    let heartbeatTimer = null;
+    let unsubscribed = false;
+    const stream = new ReadableStream({
+      start(controller) {
+        const callback = (event) => {
+          if (unsubscribed) return;
+          try {
+            if (event.type === "reply") {
+              const data = JSON.stringify({ reply: event.reply });
+              controller.enqueue(formatSSE("reply", data));
+            } else if (event.type === "thread_created") {
+              const data = JSON.stringify({ threadTs: event.threadTs });
+              controller.enqueue(formatSSE("thread_created", data));
+            }
+          } catch {
+            cleanup();
+          }
+        };
+        emitter.subscribe(sid, callback);
+        heartbeatTimer = setInterval(() => {
+          try {
+            controller.enqueue(formatSSE("heartbeat", "{}"));
+          } catch {
+            cleanup();
+          }
+        }, heartbeatInterval);
+        function cleanup() {
+          if (unsubscribed) return;
+          unsubscribed = true;
+          emitter.unsubscribe(sid, callback);
+          if (heartbeatTimer !== null) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+          }
+        }
+        if (request.signal) {
+          request.signal.addEventListener("abort", () => {
+            cleanup();
+            try {
+              controller.close();
+            } catch {
+            }
+          });
+        }
+      },
+      cancel() {
+        unsubscribed = true;
+        if (heartbeatTimer !== null) {
+          clearInterval(heartbeatTimer);
+          heartbeatTimer = null;
+        }
+      }
+    });
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive"
+      }
+    });
+  };
+}
+function createExpressSSEHandler(options) {
+  const { emitter, heartbeatInterval = 3e4 } = options;
+  return (req, res) => {
+    const sessionId = req.query?.sessionId;
+    if (!sessionId || typeof sessionId !== "string") {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.write(JSON.stringify({ error: "Missing required query parameter: sessionId" }));
+      res.end();
+      return;
+    }
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive"
+    });
+    let cleaned = false;
+    const callback = (event) => {
+      if (cleaned) return;
+      if (event.type === "reply") {
+        const data = JSON.stringify({ reply: event.reply });
+        res.write(formatSSEString("reply", data));
+      } else if (event.type === "thread_created") {
+        const data = JSON.stringify({ threadTs: event.threadTs });
+        res.write(formatSSEString("thread_created", data));
+      }
+    };
+    emitter.subscribe(sessionId, callback);
+    const heartbeatTimer = setInterval(() => {
+      if (cleaned) return;
+      res.write(formatSSEString("heartbeat", "{}"));
+    }, heartbeatInterval);
+    function cleanup() {
+      if (cleaned) return;
+      cleaned = true;
+      emitter.unsubscribe(sessionId, callback);
+      clearInterval(heartbeatTimer);
+    }
+    res.on("close", cleanup);
+  };
+}
+function formatSSE(event, data) {
+  const text = `event: ${event}
+data: ${data}
+
+`;
+  return new TextEncoder().encode(text);
+}
+function formatSSEString(event, data) {
+  return `event: ${event}
+data: ${data}
+
+`;
+}
+
+export { InMemoryStore, createExpressHandler, createExpressRepliesHandler, createExpressSSEHandler, createExpressWebhookHandler, createRepliesHandler, createReplyEmitter, createSSEHandler, createSupportHandler, createWebhookHandler, emojify, validateSlackToken, verifySlackSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map