simple-support-chat 0.1.1 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@ Embeddable chat widget SDK that routes customer messages to Slack threads. Open-
 
 - Zero cost, self-hosted
 - Slack-native: messages appear as threads in your workspace
+- Bidirectional: team replies in Slack threads show in the chat widget
+- Slack emoji shortcodes (`:heart:`) auto-converted to Unicode (❤️)
 - Works with any React app (Next.js, Remix, Vite, etc.)
 - Anonymous and authenticated user support
 - No external CSS or Tailwind dependency
@@ -70,8 +72,11 @@ Add these to your `.env` file:
 ```bash
 SLACK_BOT_TOKEN=xoxb-your-token-here
 SLACK_CHANNEL_ID=C0123ABCDEF
+SLACK_SIGNING_SECRET=your-signing-secret-here  # Required for receiving replies (see "Receiving Replies" section)
 ```
 
+The signing secret is found under **Basic Information** > **App Credentials** in your Slack app settings. It is only needed if you want bidirectional messaging (team replies appearing in the widget).
+
 ### Validate Your Token
 
 Use the built-in `validateSlackToken` utility to verify your token works before going live:
@@ -128,6 +133,280 @@ export default function App() {
 
 That's it! Messages from your users will appear as threaded conversations in your Slack channel.
 
+## Receiving Replies
+
+By default, simple-support-chat is one-way: users send messages that appear in Slack. To make it bidirectional -- so team replies in Slack appear in the user's chat widget -- you need three additional pieces:
+
+1. A **webhook route** that receives events from Slack when someone replies in a thread
+2. A **replies endpoint** that the client polls for new replies
+3. The `repliesUrl` prop on the client widget
+
+### Prerequisites
+
+- Completed the [Slack App Setup](#slack-app-setup) above
+- Your Slack app's **Signing Secret** (found under **Basic Information** > **App Credentials** in [api.slack.com/apps](https://api.slack.com/apps))
+
+Add the signing secret to your environment variables:
+
+```bash
+SLACK_SIGNING_SECRET=your-signing-secret-here
+```
+
+### Step 1: Enable Event Subscriptions
+
+1. Go to your app at [api.slack.com/apps](https://api.slack.com/apps)
+2. Navigate to **Event Subscriptions** in the sidebar
+3. Toggle **Enable Events** to On
+4. Set the **Request URL** to `https://your-domain.com/api/support/webhook`
+   - Slack will send a verification challenge -- your webhook handler responds automatically
+5. Under **Subscribe to bot events**, add `message.channels`
+6. Click **Save Changes**
+
+A pre-built manifest is included at [`slack-app-manifest.json`](./slack-app-manifest.json). Replace `YOUR_DOMAIN` with your actual domain and use it when creating or reconfiguring your Slack app.
+
+> **Local development:** Slack cannot reach `localhost`. Use a tunnel like [ngrok](https://ngrok.com/) (`ngrok http 3000`) and set the tunnel URL as the Request URL. You can skip webhook setup entirely for local dev -- one-way messaging works without it.
+
+### Step 2: Create a Shared Store
+
+The webhook handler, replies handler, and message handler must share the same store instance so that thread mappings and replies are consistent.
+
+```ts
+// lib/support-store.ts (or wherever you keep shared singletons)
+import { InMemoryStore } from "simple-support-chat/server";
+
+export const store = new InMemoryStore();
+```
+
+`InMemoryStore` works for local development. For production, implement the `SupportChatStore` interface with your database (see [Custom Storage](#custom-storage-supportchatstore) below).
+
+### Step 3: Set Up Routes
+
+#### Next.js App Router
+
+```ts
+// app/api/support/route.ts
+import { createSupportHandler } from "simple-support-chat/server";
+import { store } from "@/lib/support-store";
+
+export const POST = createSupportHandler({
+  slackBotToken: process.env.SLACK_BOT_TOKEN!,
+  slackChannel: process.env.SLACK_CHANNEL_ID!,
+  store,
+});
+```
+
+```ts
+// app/api/support/webhook/route.ts
+import { createWebhookHandler } from "simple-support-chat/server";
+import { store } from "@/lib/support-store";
+
+export const POST = createWebhookHandler({
+  store,
+  signingSecret: process.env.SLACK_SIGNING_SECRET!,
+});
+```
+
+```ts
+// app/api/support/replies/route.ts
+import { createRepliesHandler } from "simple-support-chat/server";
+import { store } from "@/lib/support-store";
+
+export const GET = createRepliesHandler({ store });
+```
+
+#### Express
+
+```ts
+import express from "express";
+import {
+  createExpressHandler,
+  createExpressWebhookHandler,
+  createExpressRepliesHandler,
+  InMemoryStore,
+} from "simple-support-chat/server";
+
+const app = express();
+const store = new InMemoryStore();
+
+// Message handler (uses JSON body parser)
+app.post(
+  "/api/support",
+  express.json(),
+  createExpressHandler({
+    slackBotToken: process.env.SLACK_BOT_TOKEN!,
+    slackChannel: process.env.SLACK_CHANNEL_ID!,
+    store,
+  }),
+);
+
+// Webhook handler (uses raw body parser for signature verification)
+app.post(
+  "/api/support/webhook",
+  express.raw({ type: "application/json" }),
+  createExpressWebhookHandler({
+    store,
+    signingSecret: process.env.SLACK_SIGNING_SECRET!,
+  }),
+);
+
+// Replies handler (GET endpoint for client polling)
+app.get(
+  "/api/support/replies",
+  createExpressRepliesHandler({ store }),
+);
+
+app.listen(3000);
+```
+
+> **Important:** The webhook route must use `express.raw()` (not `express.json()`) so that the raw request body is available for Slack signature verification.
+
+### Step 4: Add repliesUrl to the Client
+
+Pass the `repliesUrl` prop to enable reply polling:
+
+```tsx
+<ChatBubble
+  apiUrl="/api/support"
+  repliesUrl="/api/support/replies"
+/>
+```
+
+Or with the modal:
+
+```tsx
+<SupportChatModal
+  apiUrl="/api/support"
+  repliesUrl="/api/support/replies"
+  isOpen={isOpen}
+  onClose={close}
+/>
+```
+
+When `repliesUrl` is set, the widget polls every 4 seconds while the chat panel is open. Replies appear as left-aligned gray bubbles. Polling stops when the chat is closed.
+
+### Custom Storage (SupportChatStore)
+
+For production, implement the `SupportChatStore` interface to persist thread mappings and replies to your database. Here is the interface:
+
+```ts
+interface SupportChatStore {
+  saveThread(sessionId: string, threadTs: string, metadata?: Record<string, unknown>): Promise<void>;
+  getThreadBySession(sessionId: string): Promise<ThreadRecord | null>;
+  getThreadByTs(threadTs: string): Promise<ThreadRecord | null>;
+  saveReply(sessionId: string, reply: Reply): Promise<void>;
+  getReplies(sessionId: string, since?: string): Promise<Reply[]>;
+}
+```
+
+#### Example: Supabase Implementation
+
+First, create the tables:
+
+```sql
+-- Supabase migration
+create table support_chat_threads (
+  session_id text primary key,
+  thread_ts text not null unique,
+  metadata jsonb default '{}',
+  created_at timestamptz default now()
+);
+
+create table support_chat_replies (
+  id text primary key,
+  session_id text not null references support_chat_threads(session_id),
+  text text not null,
+  sender text not null,
+  timestamp timestamptz not null,
+  thread_ts text not null
+);
+
+create index idx_replies_session_timestamp
+  on support_chat_replies(session_id, timestamp);
+```
+
+Then implement the store:
+
+```ts
+import type { SupportChatStore, ThreadRecord, Reply } from "simple-support-chat/server";
+import { createClient } from "@supabase/supabase-js";
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+);
+
+export class SupabaseChatStore implements SupportChatStore {
+  async saveThread(sessionId: string, threadTs: string, metadata?: Record<string, unknown>) {
+    await supabase.from("support_chat_threads").upsert({
+      session_id: sessionId,
+      thread_ts: threadTs,
+      metadata: metadata ?? {},
+    });
+  }
+
+  async getThreadBySession(sessionId: string): Promise<ThreadRecord | null> {
+    const { data } = await supabase
+      .from("support_chat_threads")
+      .select("*")
+      .eq("session_id", sessionId)
+      .single();
+    if (!data) return null;
+    return { sessionId: data.session_id, threadTs: data.thread_ts, metadata: data.metadata };
+  }
+
+  async getThreadByTs(threadTs: string): Promise<ThreadRecord | null> {
+    const { data } = await supabase
+      .from("support_chat_threads")
+      .select("*")
+      .eq("thread_ts", threadTs)
+      .single();
+    if (!data) return null;
+    return { sessionId: data.session_id, threadTs: data.thread_ts, metadata: data.metadata };
+  }
+
+  async saveReply(sessionId: string, reply: Reply) {
+    await supabase.from("support_chat_replies").insert({
+      id: reply.id,
+      session_id: sessionId,
+      text: reply.text,
+      sender: reply.sender,
+      timestamp: reply.timestamp,
+      thread_ts: reply.threadTs,
+    });
+  }
+
+  async getReplies(sessionId: string, since?: string): Promise<Reply[]> {
+    let query = supabase
+      .from("support_chat_replies")
+      .select("*")
+      .eq("session_id", sessionId)
+      .order("timestamp", { ascending: true });
+
+    if (since) {
+      query = query.gt("timestamp", since);
+    }
+
+    const { data } = await query;
+    return (data ?? []).map((r) => ({
+      id: r.id,
+      text: r.text,
+      sender: r.sender,
+      timestamp: r.timestamp,
+      threadTs: r.thread_ts,
+    }));
+  }
+}
+```
+
+Then pass the store to all handlers:
+
+```ts
+import { SupabaseChatStore } from "@/lib/supabase-chat-store";
+
+const store = new SupabaseChatStore();
+// Use this store instance in createSupportHandler, createWebhookHandler, and createRepliesHandler
+```
+
 ## Configuration
 
 ### ChatBubble Props
@@ -135,6 +414,7 @@ That's it! Messages from your users will appear as threaded conversations in you
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `apiUrl` | `string` | (required) | URL of your support API endpoint |
+| `repliesUrl` | `string` | `undefined` | URL of the replies endpoint. Enables bidirectional chat. |
 | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Bubble position |
 | `color` | `string` | `'#2563eb'` | Primary color (bubble, header, sent messages) |
 | `title` | `string` | `'Support'` | Chat panel header title |
@@ -151,6 +431,7 @@ That's it! Messages from your users will appear as threaded conversations in you
 | `botName` | `string` | Custom bot display name |
 | `botIcon` | `string` | Bot icon emoji (e.g., `:speech_balloon:`) |
 | `onMessage` | `(data) => void` | Callback on each message |
+| `store` | `SupportChatStore` | Pluggable storage backend (defaults to `InMemoryStore`) |
 
 ## Identity Integration
 
@@ -211,6 +492,7 @@ The modal renders centered on desktop (max-width 500px) with a backdrop overlay,
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `apiUrl` | `string` | (required) | URL of your support API endpoint |
+| `repliesUrl` | `string` | `undefined` | URL of the replies endpoint. Enables bidirectional chat. |
 | `isOpen` | `boolean` | (required) | Whether the modal is open |
 | `onClose` | `() => void` | (required) | Callback to close the modal |
 | `color` | `string` | `'#2563eb'` | Primary color |
@@ -264,9 +546,16 @@ The Express handler uses the same threading logic as the Web API handler. The re
 
 | Export | Description |
 |--------|-------------|
-| `createSupportHandler(options)` | Returns a Web API `(Request) => Promise<Response>` handler |
-| `createExpressHandler(options)` | Returns an Express `(req, res) => Promise<void>` handler |
+| `createSupportHandler(options)` | Returns a Web API `(Request) => Promise<Response>` handler for messages |
+| `createExpressHandler(options)` | Returns an Express `(req, res) => Promise<void>` handler for messages |
+| `createWebhookHandler(options)` | Returns a Web API handler for Slack event webhooks |
+| `createExpressWebhookHandler(options)` | Returns an Express handler for Slack event webhooks |
+| `createRepliesHandler(options)` | Returns a Web API handler for the replies polling endpoint |
+| `createExpressRepliesHandler(options)` | Returns an Express handler for the replies polling endpoint |
+| `verifySlackSignature(secret, sig, ts, body)` | Verifies a Slack request signature |
+| `InMemoryStore` | Default in-memory implementation of `SupportChatStore` |
 | `validateSlackToken(token)` | Validates a Slack token via `auth.test` |
+| `emojify(text)` | Converts Slack emoji shortcodes (`:heart:`) to Unicode (❤️) |
 
 ### Client Exports (`simple-support-chat`)
 
@@ -288,7 +577,17 @@ All TypeScript types are exported from both entry points:
 import type { ChatBubbleProps, ChatUser, SupportChatModalProps, ChatMessage } from "simple-support-chat";
 
 // Server types
-import type { SupportHandlerOptions, IncomingMessage, HandlerResponse } from "simple-support-chat/server";
+import type {
+  SupportHandlerOptions,
+  IncomingMessage,
+  HandlerResponse,
+  SupportChatStore,
+  Reply,
+  ThreadRecord,
+  WebhookHandlerOptions,
+  RepliesHandlerOptions,
+  RepliesResponse,
+} from "simple-support-chat/server";
 ```
 
 ## Development

package/dist/client/index.cjs

@@ -50,13 +50,18 @@ function collectAnonymousContext() {
 }
 
 // src/client/useChatEngine.ts
+var POLL_INTERVAL = 4e3;
 function useChatEngine({
   apiUrl,
-  user
+  user,
+  repliesUrl,
+  isOpen = true
 }) {
   const [messages, setMessages] = react.useState([]);
   const [input, setInput] = react.useState("");
   const [sending, setSending] = react.useState(false);
+  const lastReplyTimestampRef = react.useRef(null);
+  const knownReplyIdsRef = react.useRef(/* @__PURE__ */ new Set());
   const sendMessage = react.useCallback(async () => {
     const text = input.trim();
     if (!text || sending) return;
@@ -115,6 +120,44 @@ function useChatEngine({
     },
     [sendMessage]
   );
+  react.useEffect(() => {
+    if (!repliesUrl || !isOpen) return;
+    const sessionId = user?.id ?? getSessionId();
+    const fetchReplies = async () => {
+      try {
+        const params = new URLSearchParams({ sessionId });
+        if (lastReplyTimestampRef.current) {
+          params.set("since", lastReplyTimestampRef.current);
+        }
+        const response = await fetch(`${repliesUrl}?${params.toString()}`);
+        if (!response.ok) return;
+        const data = await response.json();
+        if (data.replies.length === 0) return;
+        const newReplies = data.replies.filter(
+          (r) => !knownReplyIdsRef.current.has(r.id)
+        );
+        if (newReplies.length === 0) return;
+        for (const r of newReplies) {
+          knownReplyIdsRef.current.add(r.id);
+        }
+        const latestTimestamp = newReplies.reduce((latest, r) => {
+          return r.timestamp > latest ? r.timestamp : latest;
+        }, lastReplyTimestampRef.current ?? "");
+        lastReplyTimestampRef.current = latestTimestamp;
+        const replyMessages = newReplies.map((r) => ({
+          id: r.id,
+          text: r.text,
+          sender: "received",
+          timestamp: new Date(r.timestamp).getTime()
+        }));
+        setMessages((prev) => [...prev, ...replyMessages]);
+      } catch {
+      }
+    };
+    void fetchReplies();
+    const intervalId = setInterval(() => void fetchReplies(), POLL_INTERVAL);
+    return () => clearInterval(intervalId);
+  }, [repliesUrl, isOpen, user]);
   return { messages, input, setInput, sending, sendMessage, handleKeyDown };
 }
 function useColorScheme() {
@@ -184,12 +227,13 @@ function ChatBubble({
   title = "Support",
   placeholder = "Type a message...",
   show = true,
-  user
+  user,
+  repliesUrl
 }) {
   const [isOpen, setIsOpen] = react.useState(false);
   const colorScheme = useColorScheme();
   const theme = react.useMemo(() => getThemeTokens(colorScheme), [colorScheme]);
-  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user });
+  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user, repliesUrl, isOpen });
   const [panelState, setPanelState] = react.useState(
     "closed"
   );
@@ -414,6 +458,7 @@ function ChatBubble({
                 messages.map((msg) => /* @__PURE__ */ jsxRuntime.jsx(
                   "div",
                   {
+                    "data-sender": msg.sender,
                     style: {
                       alignSelf: msg.sender === "user" ? "flex-end" : "flex-start",
                       maxWidth: "80%",
@@ -527,9 +572,10 @@ function SupportChatModal({
   color = "#2563eb",
   title = "Contact Us",
   placeholder = "Type a message...",
-  user
+  user,
+  repliesUrl
 }) {
-  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user });
+  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user, repliesUrl, isOpen });
   const colorScheme = useColorScheme();
   const theme = react.useMemo(() => getThemeTokens(colorScheme), [colorScheme]);
   const modalRef = react.useRef(null);
@@ -721,6 +767,7 @@ function SupportChatModal({
                     messages.map((msg) => /* @__PURE__ */ jsxRuntime.jsx(
                       "div",
                       {
+                        "data-sender": msg.sender,
                         style: {
                           alignSelf: msg.sender === "user" ? "flex-end" : "flex-start",
                           maxWidth: "80%",