simple-support-chat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Indigo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,307 @@
+# simple-support-chat
+
+Embeddable chat widget SDK that routes customer messages to Slack threads. Open-source alternative to Crisp, Intercom, and Drift.
+
+- Zero cost, self-hosted
+- Slack-native: messages appear as threads in your workspace
+- Works with any React app (Next.js, Remix, Vite, etc.)
+- Anonymous and authenticated user support
+- No external CSS or Tailwind dependency
+
+## Installation
+
+```bash
+pnpm add simple-support-chat
+```
+
+React 18+ is a peer dependency for the client widget. The server handler works without React.
+
+## Slack App Setup
+
+Follow these steps to create a Slack App for your workspace. Each open-source user creates their own app -- there is no shared OAuth install flow.
+
+### Step 1: Create the App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
+2. Choose **From scratch**
+3. Name it (e.g., "Support Chat") and select your workspace
+4. Click **Create App**
+
+### Step 2: Configure Bot Token Scopes
+
+Navigate to **OAuth & Permissions** in the sidebar and scroll to **Bot Token Scopes**. Add these three scopes:
+
+| Scope | Purpose |
+|-------|---------|
+| `chat:write` | Post messages to channels |
+| `chat:write.customize` | Customize the bot's display name and icon per message |
+| `users:read` | Read basic user profile information |
+
+These are the minimum required scopes. You do not need any User Token Scopes.
+
+### Step 3: Install to Workspace
+
+1. Scroll to the top of **OAuth & Permissions** and click **Install to Workspace**
+2. Review the permissions and click **Allow**
+3. Copy the **Bot User OAuth Token** -- it starts with `xoxb-`
+
+### Step 4: Get Your Channel ID
+
+You need the channel ID (not the channel name) for configuration:
+
+1. Open Slack and navigate to the channel you want to use for support
+2. Click the channel name at the top to open channel details
+3. Scroll to the bottom of the details panel -- the Channel ID is displayed there (e.g., `C0123ABCDEF`)
+
+Alternatively, right-click the channel name, click **Copy link**, and extract the ID from the URL.
+
+### Step 5: Invite the Bot
+
+The bot must be a member of the channel to post messages. In Slack, type:
+
+```
+/invite @YourBotName
+```
+
+### Step 6: Set Environment Variables
+
+Add these to your `.env` file:
+
+```bash
+SLACK_BOT_TOKEN=xoxb-your-token-here
+SLACK_CHANNEL_ID=C0123ABCDEF
+```
+
+### Validate Your Token
+
+Use the built-in `validateSlackToken` utility to verify your token works before going live:
+
+```ts
+import { validateSlackToken } from "simple-support-chat/server";
+
+const result = await validateSlackToken(process.env.SLACK_BOT_TOKEN!);
+if (result.ok) {
+  console.log(`Connected to workspace: ${result.team} as ${result.user}`);
+} else {
+  console.error(`Token validation failed: ${result.error}`);
+}
+```
+
+### Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `not_in_channel` error | Invite the bot to the channel with `/invite @BotName` |
+| `invalid_auth` error | Check that your token starts with `xoxb-` and has not been revoked |
+| `channel_not_found` error | Verify you are using the Channel ID (e.g., `C0123ABCDEF`), not the channel name |
+| Messages not appearing | Confirm the bot has `chat:write` scope and the channel ID is correct |
+| Bot name/icon not customizing | Ensure `chat:write.customize` scope is added |
+
+## Quick Start
+
+### 1. Server: Create API Route
+
+```ts
+// app/api/support/route.ts (Next.js App Router)
+import { createSupportHandler } from "simple-support-chat/server";
+
+export const POST = createSupportHandler({
+  slackBotToken: process.env.SLACK_BOT_TOKEN!,
+  slackChannel: process.env.SLACK_CHANNEL_ID!,
+});
+```
+
+### 2. Client: Add the Chat Widget
+
+```tsx
+import { ChatBubble } from "simple-support-chat";
+
+export default function App() {
+  return (
+    <>
+      {/* Your app content */}
+      <ChatBubble apiUrl="/api/support" />
+    </>
+  );
+}
+```
+
+That's it! Messages from your users will appear as threaded conversations in your Slack channel.
+
+## Configuration
+
+### ChatBubble Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | (required) | URL of your support API endpoint |
+| `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 |
+| `placeholder` | `string` | `'Type a message...'` | Input placeholder text |
+| `show` | `boolean` | `true` | Show/hide the floating bubble |
+| `user` | `ChatUser` | `undefined` | Authenticated user info |
+
+### Server Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `slackBotToken` | `string` | Slack Bot OAuth Token (`xoxb-...`) |
+| `slackChannel` | `string` | Slack channel ID |
+| `botName` | `string` | Custom bot display name |
+| `botIcon` | `string` | Bot icon emoji (e.g., `:speech_balloon:`) |
+| `onMessage` | `(data) => void` | Callback on each message |
+
+## Identity Integration
+
+Pass the logged-in user's identity to the widget so Slack threads show who they are:
+
+```tsx
+import { ChatBubble } from "simple-support-chat";
+import { useAuth } from "./your-auth"; // your auth provider
+
+export function SupportWidget() {
+  const { user } = useAuth();
+
+  return (
+    <ChatBubble
+      apiUrl="/api/support"
+      user={user ? { id: user.id, name: user.name, email: user.email } : undefined}
+    />
+  );
+}
+```
+
+When a user is identified, Slack threads are titled: **Support: John Doe (john@example.com)**
+When anonymous: **Support: Anonymous (session abc12345)**
+
+## Modal Mode
+
+Hide the floating bubble and trigger the chat from a custom "Contact Us" element using the `useSupportChat` hook and `SupportChatModal` component:
+
+```tsx
+import { SupportChatModal, useSupportChat } from "simple-support-chat";
+
+function App() {
+  const { open, close, isOpen } = useSupportChat();
+
+  return (
+    <>
+      <nav>
+        <button onClick={open}>Contact Us</button>
+      </nav>
+
+      <SupportChatModal
+        apiUrl="/api/support"
+        isOpen={isOpen}
+        onClose={close}
+        title="Get Help"
+        color="#10b981"
+        user={currentUser}
+      />
+    </>
+  );
+}
+```
+
+The modal renders centered on desktop (max-width 500px) with a backdrop overlay, and full-screen on mobile. You can place the trigger button anywhere -- nav bar, footer, settings page, error boundaries, etc.
+
+### SupportChatModal Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | (required) | URL of your support API endpoint |
+| `isOpen` | `boolean` | (required) | Whether the modal is open |
+| `onClose` | `() => void` | (required) | Callback to close the modal |
+| `color` | `string` | `'#2563eb'` | Primary color |
+| `title` | `string` | `'Contact Us'` | Modal header title |
+| `placeholder` | `string` | `'Type a message...'` | Input placeholder text |
+| `user` | `ChatUser` | `undefined` | Authenticated user info |
+
+### useSupportChat Hook
+
+```tsx
+import { useSupportChat } from "simple-support-chat";
+
+function ContactButton() {
+  const { open } = useSupportChat();
+  return <button onClick={open}>Contact Us</button>;
+}
+```
+
+## Express / Connect Handler
+
+For Express-style frameworks (Express, Fastify with express compat, etc.), use `createExpressHandler` instead:
+
+```ts
+import express from "express";
+import { createExpressHandler } from "simple-support-chat/server";
+
+const app = express();
+app.use(express.json());
+
+app.post(
+  "/api/support",
+  createExpressHandler({
+    slackBotToken: process.env.SLACK_BOT_TOKEN!,
+    slackChannel: process.env.SLACK_CHANNEL_ID!,
+    botName: "Support Bot",
+    botIcon: ":speech_balloon:",
+    onMessage: (data) => {
+      console.log("New support message:", data.message);
+    },
+  }),
+);
+
+app.listen(3000);
+```
+
+The Express handler uses the same threading logic as the Web API handler. The request body must be parsed before the handler runs (use `express.json()` middleware).
+
+## API Reference
+
+### Server Exports (`simple-support-chat/server`)
+
+| Export | Description |
+|--------|-------------|
+| `createSupportHandler(options)` | Returns a Web API `(Request) => Promise<Response>` handler |
+| `createExpressHandler(options)` | Returns an Express `(req, res) => Promise<void>` handler |
+| `validateSlackToken(token)` | Validates a Slack token via `auth.test` |
+
+### Client Exports (`simple-support-chat`)
+
+| Export | Description |
+|--------|-------------|
+| `ChatBubble` | Floating chat bubble React component |
+| `SupportChatModal` | Modal-based chat React component |
+| `useSupportChat()` | Hook returning `{ open, close, toggle, isOpen }` |
+| `useChatEngine(options)` | Low-level hook for chat message state |
+| `collectAnonymousContext()` | Collects browser context (page URL, user agent, etc.) |
+| `getSessionId()` | Gets or creates a persistent anonymous session ID |
+
+### Types
+
+All TypeScript types are exported from both entry points:
+
+```ts
+// Client types
+import type { ChatBubbleProps, ChatUser, SupportChatModalProps, ChatMessage } from "simple-support-chat";
+
+// Server types
+import type { SupportHandlerOptions, IncomingMessage, HandlerResponse } from "simple-support-chat/server";
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm dev          # Watch mode
+pnpm test         # Run tests
+pnpm typecheck    # TypeScript check
+pnpm lint         # ESLint
+pnpm build        # Production build
+```
+
+## License
+
+MIT