@cstar.help/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ChatClient, ChatConfig, IdentifyParams, IdentifyResult, Conversation, ConversationCreateParams, WidgetMessage } from '@cstar.help/js/chat';
+export { ChatConfig, Conversation, ConversationCreateParams, ConversationListResponse, IdentifyParams, IdentifyResult, TypingPayload, WidgetMessage } from '@cstar.help/js/chat';
+import { LibraryClient, LibraryConfig, Category, LibraryArticle, LibraryArticleListParams } from '@cstar.help/js/library';
+export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, LibrarySearchParams, LibrarySearchResult } from '@cstar.help/js/library';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+declare const CStarChatContext: react.Context<ChatClient | null>;
+declare const CStarLibraryContext: react.Context<LibraryClient | null>;
+/**
+ * Access the ChatClient from the nearest CStarChatProvider.
+ * Throws if used outside a provider.
+ */
+declare function useChatClient(): ChatClient;
+/**
+ * Access the LibraryClient from the nearest CStarLibraryProvider.
+ * Throws if used outside a provider.
+ */
+declare function useLibraryClient(): LibraryClient;
+
+interface CStarChatProviderProps extends ChatConfig {
+    children: ReactNode;
+}
+/**
+ * Provides a ChatClient instance to all child components.
+ * Creates the client on mount and disconnects on unmount.
+ *
+ * ```tsx
+ * <CStarChatProvider teamSlug="acme" supabaseUrl="..." supabaseAnonKey="...">
+ *   <ChatWidget />
+ * </CStarChatProvider>
+ * ```
+ */
+declare function CStarChatProvider({ children, ...config }: CStarChatProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseChatReturn {
+    /** Identify a customer with HMAC signature. */
+    identify: (customer: IdentifyParams, signature: string) => Promise<IdentifyResult>;
+    /** Disconnect the client and clean up all subscriptions. */
+    disconnect: () => void;
+    /** Whether a customer has been successfully identified. */
+    isIdentified: boolean;
+    /** Whether the Supabase Realtime connection is ready. */
+    isRealtimeReady: boolean;
+    /** The last error from identify, or null. */
+    error: Error | null;
+}
+/**
+ * Core chat hook — manages identity verification and realtime readiness.
+ *
+ * ```tsx
+ * const { identify, disconnect, isIdentified, isRealtimeReady, error } = useChat();
+ *
+ * await identify(
+ *   { externalId: 'usr_123', email: 'jane@co.com', timestamp: Date.now() / 1000 },
+ *   hmacSignature
+ * );
+ * ```
+ */
+declare function useChat(): UseChatReturn;
+
+interface UseConversationsReturn {
+    /** List of conversations for the identified customer. */
+    conversations: Conversation[];
+    /** Whether the initial fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Whether there are more conversations to load. */
+    hasMore: boolean;
+    /** Re-fetch the conversation list. */
+    refresh: () => Promise<void>;
+    /** Create a new conversation. */
+    create: (params: ConversationCreateParams) => Promise<Conversation>;
+}
+/**
+ * Manage the customer's conversation list.
+ *
+ * ```tsx
+ * const { conversations, isLoading, create, refresh } = useConversations();
+ * ```
+ */
+declare function useConversations(): UseConversationsReturn;
+
+interface UseMessagesReturn {
+    /** Messages in the conversation, oldest first. */
+    messages: WidgetMessage[];
+    /** Whether the initial fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Send a message. Optimistically appended, replaced with server response. */
+    send: (content: string) => Promise<WidgetMessage>;
+    /** Re-fetch messages from the API. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Manage messages for a single conversation with automatic real-time updates.
+ *
+ * ```tsx
+ * const { messages, isLoading, send } = useMessages(ticketId);
+ * await send('Hello!');
+ * ```
+ */
+declare function useMessages(ticketId: string | null): UseMessagesReturn;
+
+interface TypingAgent {
+    agentId: string;
+    agentName: string;
+}
+interface UseTypingReturn {
+    /** Agents currently typing. Auto-cleared after 4s of no activity. */
+    typingAgents: TypingAgent[];
+    /** Send a customer typing indicator. */
+    sendTyping: (isTyping: boolean) => Promise<void>;
+}
+/**
+ * Track agent typing indicators for a conversation.
+ *
+ * ```tsx
+ * const { typingAgents, sendTyping } = useTyping(ticketId);
+ * ```
+ */
+declare function useTyping(ticketId: string | null): UseTypingReturn;
+
+interface CStarLibraryProviderProps extends LibraryConfig {
+    children: ReactNode;
+}
+/**
+ * Provides a LibraryClient instance to all child components.
+ *
+ * ```tsx
+ * <CStarLibraryProvider teamSlug="acme">
+ *   <KnowledgeBase />
+ * </CStarLibraryProvider>
+ * ```
+ */
+declare function CStarLibraryProvider({ children, ...config }: CStarLibraryProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseCategoriesReturn {
+    /** All public categories. */
+    categories: Category[];
+    /** Whether the initial fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch categories. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch public knowledge base categories.
+ *
+ * ```tsx
+ * const { categories, isLoading, error } = useCategories();
+ * ```
+ */
+declare function useCategories(): UseCategoriesReturn;
+
+interface UseArticlesReturn {
+    /** Published articles. */
+    articles: LibraryArticle[];
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch articles with the current params. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch published articles, optionally filtered by category.
+ *
+ * ```tsx
+ * const { articles, isLoading } = useArticles({ categorySlug: 'getting-started' });
+ * ```
+ */
+declare function useArticles(params?: LibraryArticleListParams): UseArticlesReturn;
+
+interface UseArticleReturn {
+    /** The article, or null if not yet loaded. */
+    article: LibraryArticle | null;
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch the article. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch a single article by slug.
+ *
+ * ```tsx
+ * const { article, isLoading, error } = useArticle('getting-started');
+ * ```
+ */
+declare function useArticle(slug: string | null): UseArticleReturn;
+
+interface UseArticleSearchReturn {
+    /** Search results. */
+    results: LibraryArticle[];
+    /** Total number of matching articles. */
+    totalCount: number;
+    /** Whether a search is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+}
+/**
+ * Search articles with automatic debouncing (300ms).
+ * Clears results when query is empty.
+ *
+ * ```tsx
+ * const { results, totalCount, isLoading } = useArticleSearch(searchTerm);
+ * ```
+ */
+declare function useArticleSearch(query: string): UseArticleSearchReturn;
+
+export { CStarChatContext, CStarChatProvider, type CStarChatProviderProps, CStarLibraryContext, CStarLibraryProvider, type CStarLibraryProviderProps, type TypingAgent, type UseArticleReturn, type UseArticleSearchReturn, type UseArticlesReturn, type UseCategoriesReturn, type UseChatReturn, type UseConversationsReturn, type UseMessagesReturn, type UseTypingReturn, useArticle, useArticleSearch, useArticles, useCategories, useChat, useChatClient, useConversations, useLibraryClient, useMessages, useTyping };

package/dist/index.js

@@ -0,0 +1,454 @@
+// src/context.tsx
+import { createContext, useContext } from "react";
+var CStarChatContext = createContext(null);
+var CStarLibraryContext = createContext(null);
+function useChatClient() {
+  const client = useContext(CStarChatContext);
+  if (!client) {
+    throw new Error("useChatClient must be used within a <CStarChatProvider>");
+  }
+  return client;
+}
+function useLibraryClient() {
+  const client = useContext(CStarLibraryContext);
+  if (!client) {
+    throw new Error("useLibraryClient must be used within a <CStarLibraryProvider>");
+  }
+  return client;
+}
+
+// src/chat/CStarChatProvider.tsx
+import { useEffect, useRef } from "react";
+import { ChatClient } from "@cstar.help/js/chat";
+import { jsx } from "react/jsx-runtime";
+function CStarChatProvider({ children, ...config }) {
+  const clientRef = useRef(null);
+  if (!clientRef.current) {
+    clientRef.current = new ChatClient(config);
+  }
+  useEffect(() => {
+    return () => {
+      clientRef.current?.disconnect();
+      clientRef.current = null;
+    };
+  }, []);
+  return /* @__PURE__ */ jsx(CStarChatContext.Provider, { value: clientRef.current, children });
+}
+
+// src/chat/useChat.ts
+import { useState, useCallback } from "react";
+function useChat() {
+  const client = useChatClient();
+  const [isIdentified, setIsIdentified] = useState(false);
+  const [isRealtimeReady, setIsRealtimeReady] = useState(false);
+  const [error, setError] = useState(null);
+  const identify = useCallback(
+    async (customer, signature) => {
+      setError(null);
+      try {
+        const result = await client.identify(customer, signature);
+        setIsIdentified(true);
+        client.waitForRealtime().then(() => {
+          setIsRealtimeReady(true);
+        }).catch(() => {
+        });
+        return result;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      }
+    },
+    [client]
+  );
+  const disconnect = useCallback(() => {
+    client.disconnect();
+    setIsIdentified(false);
+    setIsRealtimeReady(false);
+    setError(null);
+  }, [client]);
+  return { identify, disconnect, isIdentified, isRealtimeReady, error };
+}
+
+// src/chat/useConversations.ts
+import { useState as useState2, useEffect as useEffect2, useCallback as useCallback2, useRef as useRef2 } from "react";
+function useConversations() {
+  const client = useChatClient();
+  const [conversations, setConversations] = useState2([]);
+  const [isLoading, setIsLoading] = useState2(true);
+  const [error, setError] = useState2(null);
+  const [hasMore, setHasMore] = useState2(false);
+  const mountedRef = useRef2(true);
+  const refresh = useCallback2(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await client.conversations.list();
+      if (mountedRef.current) {
+        setConversations(result.conversations);
+        setHasMore(result.hasMore);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client]);
+  useEffect2(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  const create = useCallback2(
+    async (params) => {
+      const conversation = await client.conversations.create(params);
+      if (mountedRef.current) {
+        setConversations((prev) => [conversation, ...prev]);
+      }
+      return conversation;
+    },
+    [client]
+  );
+  return { conversations, isLoading, error, hasMore, refresh, create };
+}
+
+// src/chat/useMessages.ts
+import { useState as useState3, useEffect as useEffect3, useCallback as useCallback3, useRef as useRef3 } from "react";
+function useMessages(ticketId) {
+  const client = useChatClient();
+  const [messages, setMessages] = useState3([]);
+  const [isLoading, setIsLoading] = useState3(true);
+  const [error, setError] = useState3(null);
+  const mountedRef = useRef3(true);
+  const seenIdsRef = useRef3(/* @__PURE__ */ new Set());
+  const refresh = useCallback3(async () => {
+    if (!ticketId) return;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const msgs = await client.messages.list(ticketId);
+      if (mountedRef.current) {
+        seenIdsRef.current = new Set(msgs.map((m) => m.id));
+        setMessages(msgs);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client, ticketId]);
+  useEffect3(() => {
+    mountedRef.current = true;
+    if (!ticketId) {
+      setMessages([]);
+      setIsLoading(false);
+      return;
+    }
+    refresh();
+    const unsubscribe = client.onMessage(ticketId, (msg) => {
+      if (mountedRef.current && !seenIdsRef.current.has(msg.id)) {
+        seenIdsRef.current.add(msg.id);
+        setMessages((prev) => {
+          const optimisticIdx = prev.findIndex(
+            (m) => m.id.startsWith("optimistic-") && m.content === msg.content
+          );
+          if (optimisticIdx >= 0) {
+            const next = [...prev];
+            next[optimisticIdx] = msg;
+            return next;
+          }
+          return [...prev, msg];
+        });
+      }
+    });
+    return () => {
+      mountedRef.current = false;
+      unsubscribe();
+    };
+  }, [client, ticketId, refresh]);
+  const send = useCallback3(
+    async (content) => {
+      if (!ticketId) throw new Error("No conversation selected");
+      const optimistic = {
+        id: `optimistic-${Date.now()}`,
+        content,
+        sender: "customer",
+        sender_name: "",
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        read_at: null,
+        attachments: []
+      };
+      setMessages((prev) => [...prev, optimistic]);
+      try {
+        const msg = await client.messages.send(ticketId, content);
+        seenIdsRef.current.add(msg.id);
+        setMessages(
+          (prev) => prev.map((m) => m.id === optimistic.id ? msg : m)
+        );
+        return msg;
+      } catch (err) {
+        setMessages((prev) => prev.filter((m) => m.id !== optimistic.id));
+        throw err;
+      }
+    },
+    [client, ticketId]
+  );
+  return { messages, isLoading, error, send, refresh };
+}
+
+// src/chat/useTyping.ts
+import { useState as useState4, useEffect as useEffect4, useCallback as useCallback4, useRef as useRef4 } from "react";
+var TYPING_TIMEOUT = 4e3;
+function useTyping(ticketId) {
+  const client = useChatClient();
+  const [typingAgents, setTypingAgents] = useState4([]);
+  const timersRef = useRef4(/* @__PURE__ */ new Map());
+  const mountedRef = useRef4(true);
+  useEffect4(() => {
+    mountedRef.current = true;
+    if (!ticketId) {
+      setTypingAgents([]);
+      return;
+    }
+    const unsubscribe = client.onTyping(ticketId, (payload) => {
+      if (!mountedRef.current) return;
+      const { agent_id, agent_name, is_typing } = payload;
+      const existing = timersRef.current.get(agent_id);
+      if (existing) clearTimeout(existing);
+      if (is_typing) {
+        setTypingAgents((prev) => {
+          if (prev.some((a) => a.agentId === agent_id)) return prev;
+          return [...prev, { agentId: agent_id, agentName: agent_name }];
+        });
+        const timer = setTimeout(() => {
+          if (mountedRef.current) {
+            setTypingAgents((prev) => prev.filter((a) => a.agentId !== agent_id));
+            timersRef.current.delete(agent_id);
+          }
+        }, TYPING_TIMEOUT);
+        timersRef.current.set(agent_id, timer);
+      } else {
+        setTypingAgents((prev) => prev.filter((a) => a.agentId !== agent_id));
+        timersRef.current.delete(agent_id);
+      }
+    });
+    return () => {
+      mountedRef.current = false;
+      unsubscribe();
+      for (const timer of timersRef.current.values()) {
+        clearTimeout(timer);
+      }
+      timersRef.current.clear();
+    };
+  }, [client, ticketId]);
+  const sendTyping = useCallback4(
+    async (isTyping) => {
+      if (!ticketId) return;
+      await client.sendTyping(ticketId, isTyping);
+    },
+    [client, ticketId]
+  );
+  return { typingAgents, sendTyping };
+}
+
+// src/library/CStarLibraryProvider.tsx
+import { useRef as useRef5 } from "react";
+import { LibraryClient } from "@cstar.help/js/library";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function CStarLibraryProvider({ children, ...config }) {
+  const clientRef = useRef5(null);
+  if (!clientRef.current) {
+    clientRef.current = new LibraryClient(config);
+  }
+  return /* @__PURE__ */ jsx2(CStarLibraryContext.Provider, { value: clientRef.current, children });
+}
+
+// src/library/useCategories.ts
+import { useState as useState5, useEffect as useEffect5, useCallback as useCallback5, useRef as useRef6 } from "react";
+function useCategories() {
+  const client = useLibraryClient();
+  const [categories, setCategories] = useState5([]);
+  const [isLoading, setIsLoading] = useState5(true);
+  const [error, setError] = useState5(null);
+  const mountedRef = useRef6(true);
+  const refresh = useCallback5(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await client.categories();
+      if (mountedRef.current) {
+        setCategories(data);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client]);
+  useEffect5(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { categories, isLoading, error, refresh };
+}
+
+// src/library/useArticles.ts
+import { useState as useState6, useEffect as useEffect6, useCallback as useCallback6, useRef as useRef7 } from "react";
+function useArticles(params) {
+  const client = useLibraryClient();
+  const [articles, setArticles] = useState6([]);
+  const [isLoading, setIsLoading] = useState6(true);
+  const [error, setError] = useState6(null);
+  const mountedRef = useRef7(true);
+  const categorySlug = params?.categorySlug;
+  const limit = params?.limit;
+  const offset = params?.offset;
+  const refresh = useCallback6(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await client.articles({ categorySlug, limit, offset });
+      if (mountedRef.current) {
+        setArticles(data);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client, categorySlug, limit, offset]);
+  useEffect6(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { articles, isLoading, error, refresh };
+}
+
+// src/library/useArticle.ts
+import { useState as useState7, useEffect as useEffect7, useCallback as useCallback7, useRef as useRef8 } from "react";
+function useArticle(slug) {
+  const client = useLibraryClient();
+  const [article, setArticle] = useState7(null);
+  const [isLoading, setIsLoading] = useState7(true);
+  const [error, setError] = useState7(null);
+  const mountedRef = useRef8(true);
+  const refresh = useCallback7(async () => {
+    if (!slug) return;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await client.article(slug);
+      if (mountedRef.current) {
+        setArticle(data);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client, slug]);
+  useEffect7(() => {
+    mountedRef.current = true;
+    if (!slug) {
+      setArticle(null);
+      setIsLoading(false);
+      return;
+    }
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [slug, refresh]);
+  return { article, isLoading, error, refresh };
+}
+
+// src/library/useArticleSearch.ts
+import { useState as useState8, useEffect as useEffect8, useRef as useRef9 } from "react";
+var DEBOUNCE_MS = 300;
+function useArticleSearch(query) {
+  const client = useLibraryClient();
+  const [results, setResults] = useState8([]);
+  const [totalCount, setTotalCount] = useState8(0);
+  const [isLoading, setIsLoading] = useState8(false);
+  const [error, setError] = useState8(null);
+  const mountedRef = useRef9(true);
+  useEffect8(() => {
+    mountedRef.current = true;
+    const trimmed = query.trim();
+    if (!trimmed) {
+      setResults([]);
+      setTotalCount(0);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+    setIsLoading(true);
+    const timer = setTimeout(async () => {
+      try {
+        const result = await client.search(trimmed);
+        if (mountedRef.current) {
+          setResults(result.data);
+          setTotalCount(result.count);
+          setError(null);
+        }
+      } catch (err) {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+      } finally {
+        if (mountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    }, DEBOUNCE_MS);
+    return () => {
+      mountedRef.current = false;
+      clearTimeout(timer);
+    };
+  }, [client, query]);
+  return { results, totalCount, isLoading, error };
+}
+export {
+  CStarChatContext,
+  CStarChatProvider,
+  CStarLibraryContext,
+  CStarLibraryProvider,
+  useArticle,
+  useArticleSearch,
+  useArticles,
+  useCategories,
+  useChat,
+  useChatClient,
+  useConversations,
+  useLibraryClient,
+  useMessages,
+  useTyping
+};