simple-support-chat 0.1.0 → 0.2.0

package/dist/server/index.d.cts

@@ -13,6 +13,8 @@ interface SlackConfig {
 interface SupportHandlerOptions extends SlackConfig {
     /** Optional callback fired on each message */
     onMessage?: (data: IncomingMessage) => void | Promise<void>;
+    /** Optional pluggable storage backend. Defaults to InMemoryStore. */
+    store?: SupportChatStore;
 }
 /** User info sent from the client */
 interface MessageUser {
@@ -63,6 +65,46 @@ interface ExpressResponse {
     status(code: number): ExpressResponse;
     json(data: unknown): void;
 }
+/** A reply from a team member in Slack, stored for client polling. */
+interface Reply {
+    /** Unique reply ID */
+    id: string;
+    /** Reply text content */
+    text: string;
+    /** Display name of the sender */
+    sender: string;
+    /** ISO 8601 timestamp of the reply */
+    timestamp: string;
+    /** Slack thread_ts the reply belongs to */
+    threadTs: string;
+}
+/** Metadata stored alongside a thread mapping. */
+interface ThreadRecord {
+    /** Client session identifier */
+    sessionId: string;
+    /** Slack thread timestamp */
+    threadTs: string;
+    /** Optional metadata (user info, context, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pluggable storage interface for thread mappings and replies.
+ *
+ * Implement this interface to persist data to any database.
+ * The package ships with `InMemoryStore` as the default for local development.
+ */
+interface SupportChatStore {
+    /** Save a thread mapping (session -> Slack thread). */
+    saveThread(sessionId: string, threadTs: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Look up a thread by client session ID. Returns null if not found. */
+    getThreadBySession(sessionId: string): Promise<ThreadRecord | null>;
+    /** Look up a thread by Slack thread timestamp. Returns null if not found. */
+    getThreadByTs(threadTs: string): Promise<ThreadRecord | null>;
+    /** Save a reply from a team member. */
+    saveReply(sessionId: string, reply: Reply): Promise<void>;
+    /** Get replies for a session. If `since` (ISO 8601) is provided, only return newer replies. */
+    getReplies(sessionId: string, since?: string): Promise<Reply[]>;
+}
 
 /**
  * Creates a support chat POST handler that routes messages to Slack threads.
@@ -114,4 +156,150 @@ declare function validateSlackToken(token: string): Promise<{
     error?: string;
 }>;
 
-export { type ErrorResponse, type ExpressRequest, type ExpressResponse, type HandlerResponse, type IncomingMessage, type MessageContext, type MessageUser, type SlackConfig, type SuccessResponse, type SupportHandlerOptions, createExpressHandler, createSupportHandler, validateSlackToken };
+/** Options for createWebhookHandler */
+interface WebhookHandlerOptions {
+    /** Pluggable storage backend (must be the same instance used by createSupportHandler) */
+    store: SupportChatStore;
+    /** Slack signing secret for request verification */
+    signingSecret: string;
+}
+/**
+ * Verify Slack request signature.
+ *
+ * @see https://api.slack.com/authentication/verifying-requests-from-slack
+ */
+declare function verifySlackSignature(signingSecret: string, signature: string, timestamp: string, rawBody: string): boolean;
+/**
+ * Creates a Slack webhook handler using the Web API Request/Response standard.
+ *
+ * Handles:
+ * - URL verification challenge (Slack app setup)
+ * - Event subscription messages (thread replies from team members)
+ *
+ * Compatible with Next.js App Router, Remix, Hono, Deno, Bun, etc.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/support/webhook/route.ts
+ * import { createWebhookHandler } from 'simple-support-chat/server';
+ * import { store } from '../store';
+ *
+ * export const POST = createWebhookHandler({
+ *   store,
+ *   signingSecret: process.env.SLACK_SIGNING_SECRET!,
+ * });
+ * ```
+ */
+declare function createWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Creates a Slack webhook handler for Express/Connect frameworks.
+ *
+ * IMPORTANT: You must use a raw body parser for the webhook route so that
+ * signature verification works correctly. Example:
+ *
+ * ```ts
+ * import express from 'express';
+ * import { createExpressWebhookHandler } from 'simple-support-chat/server';
+ *
+ * const app = express();
+ *
+ * // Use raw body parser for the webhook route
+ * app.post('/api/support/webhook',
+ *   express.raw({ type: 'application/json' }),
+ *   createExpressWebhookHandler({
+ *     store,
+ *     signingSecret: process.env.SLACK_SIGNING_SECRET!,
+ *   })
+ * );
+ * ```
+ */
+declare function createExpressWebhookHandler(options: WebhookHandlerOptions): (req: ExpressWebhookRequest, res: ExpressResponse) => Promise<void>;
+/** Express request with headers for webhook signature verification */
+interface ExpressWebhookRequest extends ExpressRequest {
+    headers?: Record<string, string | string[] | undefined>;
+}
+
+/** Options for createRepliesHandler */
+interface RepliesHandlerOptions {
+    /** Pluggable storage backend (must be the same instance used by createSupportHandler) */
+    store: SupportChatStore;
+}
+/** Response shape returned by the replies endpoint */
+interface RepliesResponse {
+    replies: Reply[];
+    lastChecked: string;
+}
+/** Error response from the replies endpoint */
+interface RepliesErrorResponse {
+    error: string;
+}
+/** Express-compatible request with query params */
+interface ExpressRepliesRequest {
+    query?: Record<string, string | string[] | undefined>;
+    method?: string;
+}
+/**
+ * Creates a replies polling handler using the Web API Request/Response standard.
+ *
+ * Accepts GET requests with query parameters:
+ * - `sessionId` (required): The client session ID to fetch replies for
+ * - `since` (optional): ISO 8601 timestamp to fetch only newer replies
+ *
+ * Returns JSON: `{ replies: Reply[], lastChecked: string }`
+ *
+ * Compatible with Next.js App Router, Remix, Hono, Deno, Bun, etc.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/support/replies/route.ts
+ * import { createRepliesHandler } from 'simple-support-chat/server';
+ * import { store } from '../store';
+ *
+ * export const GET = createRepliesHandler({ store });
+ * ```
+ */
+declare function createRepliesHandler(options: RepliesHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Creates a replies polling handler for Express/Connect frameworks.
+ *
+ * @example Express
+ * ```ts
+ * import express from 'express';
+ * import { createExpressRepliesHandler } from 'simple-support-chat/server';
+ *
+ * const app = express();
+ * app.get('/api/support/replies', createExpressRepliesHandler({ store }));
+ * ```
+ */
+declare function createExpressRepliesHandler(options: RepliesHandlerOptions): (req: ExpressRepliesRequest, res: ExpressResponse) => Promise<void>;
+
+/**
+ * In-memory implementation of SupportChatStore.
+ *
+ * Suitable for local development and testing. Data is lost when the process
+ * restarts. For production, implement SupportChatStore with your database
+ * of choice (Supabase, Prisma, MongoDB, etc.).
+ */
+declare class InMemoryStore implements SupportChatStore {
+    /** sessionId -> ThreadRecord */
+    private threads;
+    /** threadTs -> sessionId (reverse lookup) */
+    private threadTsIndex;
+    /** sessionId -> Reply[] */
+    private replies;
+    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[]>;
+}
+
+/**
+ * Convert Slack-style emoji shortcodes (e.g. `:slightly_smiling_face:`) to
+ * their Unicode emoji equivalents (e.g. 🙂).
+ *
+ * Unknown shortcodes are left as-is so nothing is lost in translation.
+ */
+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 };

package/dist/server/index.d.ts

@@ -13,6 +13,8 @@ interface SlackConfig {
 interface SupportHandlerOptions extends SlackConfig {
     /** Optional callback fired on each message */
     onMessage?: (data: IncomingMessage) => void | Promise<void>;
+    /** Optional pluggable storage backend. Defaults to InMemoryStore. */
+    store?: SupportChatStore;
 }
 /** User info sent from the client */
 interface MessageUser {
@@ -63,6 +65,46 @@ interface ExpressResponse {
     status(code: number): ExpressResponse;
     json(data: unknown): void;
 }
+/** A reply from a team member in Slack, stored for client polling. */
+interface Reply {
+    /** Unique reply ID */
+    id: string;
+    /** Reply text content */
+    text: string;
+    /** Display name of the sender */
+    sender: string;
+    /** ISO 8601 timestamp of the reply */
+    timestamp: string;
+    /** Slack thread_ts the reply belongs to */
+    threadTs: string;
+}
+/** Metadata stored alongside a thread mapping. */
+interface ThreadRecord {
+    /** Client session identifier */
+    sessionId: string;
+    /** Slack thread timestamp */
+    threadTs: string;
+    /** Optional metadata (user info, context, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pluggable storage interface for thread mappings and replies.
+ *
+ * Implement this interface to persist data to any database.
+ * The package ships with `InMemoryStore` as the default for local development.
+ */
+interface SupportChatStore {
+    /** Save a thread mapping (session -> Slack thread). */
+    saveThread(sessionId: string, threadTs: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Look up a thread by client session ID. Returns null if not found. */
+    getThreadBySession(sessionId: string): Promise<ThreadRecord | null>;
+    /** Look up a thread by Slack thread timestamp. Returns null if not found. */
+    getThreadByTs(threadTs: string): Promise<ThreadRecord | null>;
+    /** Save a reply from a team member. */
+    saveReply(sessionId: string, reply: Reply): Promise<void>;
+    /** Get replies for a session. If `since` (ISO 8601) is provided, only return newer replies. */
+    getReplies(sessionId: string, since?: string): Promise<Reply[]>;
+}
 
 /**
  * Creates a support chat POST handler that routes messages to Slack threads.
@@ -114,4 +156,150 @@ declare function validateSlackToken(token: string): Promise<{
     error?: string;
 }>;
 
-export { type ErrorResponse, type ExpressRequest, type ExpressResponse, type HandlerResponse, type IncomingMessage, type MessageContext, type MessageUser, type SlackConfig, type SuccessResponse, type SupportHandlerOptions, createExpressHandler, createSupportHandler, validateSlackToken };
+/** Options for createWebhookHandler */
+interface WebhookHandlerOptions {
+    /** Pluggable storage backend (must be the same instance used by createSupportHandler) */
+    store: SupportChatStore;
+    /** Slack signing secret for request verification */
+    signingSecret: string;
+}
+/**
+ * Verify Slack request signature.
+ *
+ * @see https://api.slack.com/authentication/verifying-requests-from-slack
+ */
+declare function verifySlackSignature(signingSecret: string, signature: string, timestamp: string, rawBody: string): boolean;
+/**
+ * Creates a Slack webhook handler using the Web API Request/Response standard.
+ *
+ * Handles:
+ * - URL verification challenge (Slack app setup)
+ * - Event subscription messages (thread replies from team members)
+ *
+ * Compatible with Next.js App Router, Remix, Hono, Deno, Bun, etc.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/support/webhook/route.ts
+ * import { createWebhookHandler } from 'simple-support-chat/server';
+ * import { store } from '../store';
+ *
+ * export const POST = createWebhookHandler({
+ *   store,
+ *   signingSecret: process.env.SLACK_SIGNING_SECRET!,
+ * });
+ * ```
+ */
+declare function createWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Creates a Slack webhook handler for Express/Connect frameworks.
+ *
+ * IMPORTANT: You must use a raw body parser for the webhook route so that
+ * signature verification works correctly. Example:
+ *
+ * ```ts
+ * import express from 'express';
+ * import { createExpressWebhookHandler } from 'simple-support-chat/server';
+ *
+ * const app = express();
+ *
+ * // Use raw body parser for the webhook route
+ * app.post('/api/support/webhook',
+ *   express.raw({ type: 'application/json' }),
+ *   createExpressWebhookHandler({
+ *     store,
+ *     signingSecret: process.env.SLACK_SIGNING_SECRET!,
+ *   })
+ * );
+ * ```
+ */
+declare function createExpressWebhookHandler(options: WebhookHandlerOptions): (req: ExpressWebhookRequest, res: ExpressResponse) => Promise<void>;
+/** Express request with headers for webhook signature verification */
+interface ExpressWebhookRequest extends ExpressRequest {
+    headers?: Record<string, string | string[] | undefined>;
+}
+
+/** Options for createRepliesHandler */
+interface RepliesHandlerOptions {
+    /** Pluggable storage backend (must be the same instance used by createSupportHandler) */
+    store: SupportChatStore;
+}
+/** Response shape returned by the replies endpoint */
+interface RepliesResponse {
+    replies: Reply[];
+    lastChecked: string;
+}
+/** Error response from the replies endpoint */
+interface RepliesErrorResponse {
+    error: string;
+}
+/** Express-compatible request with query params */
+interface ExpressRepliesRequest {
+    query?: Record<string, string | string[] | undefined>;
+    method?: string;
+}
+/**
+ * Creates a replies polling handler using the Web API Request/Response standard.
+ *
+ * Accepts GET requests with query parameters:
+ * - `sessionId` (required): The client session ID to fetch replies for
+ * - `since` (optional): ISO 8601 timestamp to fetch only newer replies
+ *
+ * Returns JSON: `{ replies: Reply[], lastChecked: string }`
+ *
+ * Compatible with Next.js App Router, Remix, Hono, Deno, Bun, etc.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/support/replies/route.ts
+ * import { createRepliesHandler } from 'simple-support-chat/server';
+ * import { store } from '../store';
+ *
+ * export const GET = createRepliesHandler({ store });
+ * ```
+ */
+declare function createRepliesHandler(options: RepliesHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Creates a replies polling handler for Express/Connect frameworks.
+ *
+ * @example Express
+ * ```ts
+ * import express from 'express';
+ * import { createExpressRepliesHandler } from 'simple-support-chat/server';
+ *
+ * const app = express();
+ * app.get('/api/support/replies', createExpressRepliesHandler({ store }));
+ * ```
+ */
+declare function createExpressRepliesHandler(options: RepliesHandlerOptions): (req: ExpressRepliesRequest, res: ExpressResponse) => Promise<void>;
+
+/**
+ * In-memory implementation of SupportChatStore.
+ *
+ * Suitable for local development and testing. Data is lost when the process
+ * restarts. For production, implement SupportChatStore with your database
+ * of choice (Supabase, Prisma, MongoDB, etc.).
+ */
+declare class InMemoryStore implements SupportChatStore {
+    /** sessionId -> ThreadRecord */
+    private threads;
+    /** threadTs -> sessionId (reverse lookup) */
+    private threadTsIndex;
+    /** sessionId -> Reply[] */
+    private replies;
+    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[]>;
+}
+
+/**
+ * Convert Slack-style emoji shortcodes (e.g. `:slightly_smiling_face:`) to
+ * their Unicode emoji equivalents (e.g. 🙂).
+ *
+ * Unknown shortcodes are left as-is so nothing is lost in translation.
+ */
+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 };