@cstar.help/react 0.10.0 → 0.10.2

package/README.md

@@ -2,10 +2,10 @@
 
 React hooks for the [cStar](https://cstar.help) customer support platform. Build custom chat widgets and knowledge base UIs with type-safe, SSR-compatible hooks.
 
-- **React 18+** — hooks with automatic loading states and error handling
-- **Three modules** — Chat (real-time messaging), Library (knowledge base), and Community (forum)
-- **TypeScript-first** — full type definitions included
-- **Tiny** — ~18 KB, tree-shakeable, only peer deps
+- **React 18+**: hooks with automatic loading states and error handling
+- **Three modules**: Chat (real-time messaging), Library (knowledge base), and Community (forum)
+- **TypeScript-first**: full type definitions included
+- **Tiny**: ~18 KB, tree-shakeable, only peer deps
 
 ## Install
 
@@ -82,7 +82,7 @@ function ChatWindow({ ticketId }) {
 	const [text, setText] = useState('');
 
 	const handleSend = async () => {
-		await send(text); // optimistic — appears instantly
+		await send(text); // optimistic: appears instantly
 		setText('');
 	};
 
@@ -109,7 +109,7 @@ function ChatWindow({ ticketId }) {
 
 ## Knowledge Base
 
-Wrap in `<CStarLibraryProvider>` for public knowledge base access — no auth required.
+Wrap in `<CStarLibraryProvider>` for public knowledge base access. No auth required.
 
 ### Setup
 
@@ -184,7 +184,7 @@ function SearchBar() {
 
 ## Community
 
-Wrap in `<CStarCommunityProvider>` for public community forum access — no auth required.
+Wrap in `<CStarCommunityProvider>` for public community forum access. No auth required.
 
 ### Setup
 
@@ -220,7 +220,7 @@ function CommunityForum() {
 			<ul>
 				{posts.map((post) => (
 					<li key={post.id}>
-						{post.title} — {post.voteCount} votes
+						{post.title} ({post.voteCount} votes)
 					</li>
 				))}
 			</ul>
@@ -303,11 +303,11 @@ function CommunitySearch() {
 ## Using with Next.js App Router (RSC)
 
 The dashboard provider (`CStarDashboardProvider`) wraps a `CStarClient`,
-which is a class instance — and React Server Components can't serialize
+which is a class instance, and React Server Components can't serialize
 class instances across the server/client boundary. The provider therefore
 takes one of two prop shapes:
 
-**Recommended — pass a plain config object.** The provider builds (and
+**Recommended: pass a plain config object.** The provider builds (and
 disposes) the client inside the `'use client'` boundary, so nothing
 class-shaped crosses the RSC boundary:
 
@@ -316,11 +316,17 @@ class-shaped crosses the RSC boundary:
 'use client';
 import { CStarDashboardProvider } from '@cstar.help/react';
 
-export function Providers({ children }: { children: React.ReactNode }) {
+export function Providers({
+	children,
+	secretKey
+}: {
+	children: React.ReactNode;
+	secretKey: string;
+}) {
 	return (
 		<CStarDashboardProvider
 			config={{
-				apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!,
+				apiKey: secretKey, // passed down from your server, see below
 				teamId: process.env.NEXT_PUBLIC_CSTAR_TEAM_ID!
 			}}
 		>
@@ -330,12 +336,16 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
-Use the `apiKey` field for a publishable key (`pk_live_*` / `pk_test_*`),
-NOT a secret key — the bundle ships to the browser. For server-only flows
-(an admin route handler, a server action), construct `CStarClient` with the
-secret key inline; never thread it into a provider.
+Every dashboard hook calls team endpoints, and those need a secret key
+(`sk_live_*` / `sk_test_*`): a publishable key gets 403
+`publishable_key_forbidden` on reads and `publishable_key_write` on writes.
+Whatever you pass to the provider reaches the browser, so use it only in a
+trusted environment, such as an internal tool behind your own login where
+everyone who can open the page may hold that key. Use a key scoped to what
+the dashboard needs. For a public site, have the app call your own backend
+(a route handler or server action) that holds a secret-key `CStarClient`.
 
-**Legacy — pass a pre-built client (deprecated).** If you already have a
+**Legacy: pass a pre-built client (deprecated).** If you already have a
 client instance you want to share, the `client` prop still works, but you
 have to construct it inside `'use client'` and you take on responsibility
 for tearing down the realtime subscription:
@@ -346,28 +356,28 @@ import { useMemo } from 'react';
 import { CStarClient } from '@cstar.help/js';
 import { CStarDashboardProvider } from '@cstar.help/react';
 
-export function Providers({ children }) {
+export function Providers({ children, secretKey }) {
 	const client = useMemo(
 		() =>
 			new CStarClient({
-				apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!,
+				apiKey: secretKey, // trusted environments only, as above
 				teamId: process.env.NEXT_PUBLIC_CSTAR_TEAM_ID!
 			}),
-		[]
+		[secretKey]
 	);
 	return <CStarDashboardProvider client={client}>{children}</CStarDashboardProvider>;
 }
 ```
 
 Either way, mark the file `'use client'`. Server components can sit above
-the provider in the tree — only the provider boundary needs to be a client
+the provider in the tree. Only the provider boundary needs to be a client
 component.
 
 ## Requirements
 
 - React 18+
 - @cstar.help/js 0.1.0+
-- Node.js 18+ (for SSR)
+- Node.js 22+ for SSR with `@cstar.help/js` 0.17
 
 ## License
 

package/dist/index.cjs

@@ -246,36 +246,48 @@ function useMessages(ticketId) {
   const [error, setError] = (0, import_react5.useState)(null);
   const mountedRef = (0, import_react5.useRef)(true);
   const seenIdsRef = (0, import_react5.useRef)(/* @__PURE__ */ new Set());
+  const requestRef = (0, import_react5.useRef)(0);
+  const scopeRef = (0, import_react5.useRef)(0);
+  const optimisticRef = (0, import_react5.useRef)(0);
   const refresh = (0, import_react5.useCallback)(async () => {
     if (!ticketId) return;
+    const request = ++requestRef.current;
     setIsLoading(true);
     setError(null);
     try {
       const msgs = await client.messages.list(ticketId);
-      if (mountedRef.current) {
+      if (mountedRef.current && request === requestRef.current) {
         seenIdsRef.current = new Set(msgs.map((m) => m.id));
         setMessages(msgs);
       }
     } catch (err) {
-      if (mountedRef.current) {
+      if (mountedRef.current && request === requestRef.current) {
         setError(err instanceof Error ? err : new Error(String(err)));
       }
     } finally {
-      if (mountedRef.current) {
+      if (mountedRef.current && request === requestRef.current) {
         setIsLoading(false);
       }
     }
   }, [client, ticketId]);
   (0, import_react5.useEffect)(() => {
     mountedRef.current = true;
+    const scope = ++scopeRef.current;
+    seenIdsRef.current = /* @__PURE__ */ new Set();
+    setMessages([]);
+    setError(null);
     if (!ticketId) {
       setMessages([]);
       setIsLoading(false);
-      return;
+      return () => {
+        mountedRef.current = false;
+        requestRef.current++;
+        scopeRef.current++;
+      };
     }
     refresh();
     const unsubscribe = client.onMessage(ticketId, (msg) => {
-      if (mountedRef.current && !seenIdsRef.current.has(msg.id)) {
+      if (mountedRef.current && scope === scopeRef.current && !seenIdsRef.current.has(msg.id)) {
         seenIdsRef.current.add(msg.id);
         setMessages((prev) => {
           const optimisticIdx = prev.findIndex(
@@ -292,14 +304,17 @@ function useMessages(ticketId) {
     });
     return () => {
       mountedRef.current = false;
+      requestRef.current++;
+      scopeRef.current++;
       unsubscribe();
     };
   }, [client, ticketId, refresh]);
   const send = (0, import_react5.useCallback)(
     async (content) => {
       if (!ticketId) throw new Error("No ticket selected");
+      const scope = scopeRef.current;
       const optimistic = {
-        id: `optimistic-${Date.now()}`,
+        id: `optimistic-${++optimisticRef.current}`,
         content,
         sender: "customer",
         sender_name: "",
@@ -310,11 +325,14 @@ function useMessages(ticketId) {
       setMessages((prev) => [...prev, optimistic]);
       try {
         const msg = await client.messages.send(ticketId, content);
+        if (!mountedRef.current || scope !== scopeRef.current) return msg;
         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));
+        if (mountedRef.current && scope === scopeRef.current) {
+          setMessages((prev) => prev.filter((m) => m.id !== optimistic.id));
+        }
         throw err;
       }
     },
@@ -742,7 +760,7 @@ function CStarDashboardProvider({
 }) {
   if (!config && !providedClient) {
     throw new Error(
-      "CStarDashboardProvider requires either a `config` prop (`{ apiKey, teamId }` \u2014 recommended) or a `client` prop (a pre-built CStarClient instance, deprecated). See https://cstar.help/developers/sdk/react#dashboard"
+      "CStarDashboardProvider requires either a `config` prop (`{ apiKey, teamId }`, recommended) or a `client` prop (a pre-built CStarClient instance, deprecated). See https://cstar.help/developers/sdk/react#dashboard"
     );
   }
   const client = (0, import_react17.useMemo)(() => {

package/dist/index.d.cts

@@ -6,7 +6,6 @@ import { LibraryClient, LibraryConfig, Category, LibraryArticle, LibraryArticleL
 export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, LibrarySearchParams, LibrarySearchResult } from '@cstar.help/js/library';
 import { CommunityClient, CommunityConfig, CommunityTopic, CommunityPost, CommunityPostListParams, CommunityPostDetail, CommunitySearchResult } from '@cstar.help/js/community';
 export { CommunityComment, CommunityConfig, CommunityPost, CommunityPostDetail, CommunityPostListParams, CommunitySearchResult, CommunityTopic } from '@cstar.help/js/community';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import { CStarClientConfig, CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
@@ -41,7 +40,7 @@ interface CStarChatProviderProps extends ChatConfig {
  * </CStarChatProvider>
  * ```
  */
-declare function CStarChatProvider({ children, ...config }: CStarChatProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarChatProvider({ children, ...config }: CStarChatProviderProps): react.JSX.Element;
 
 interface UseChatReturn {
     /** Identify a customer with HMAC signature. */
@@ -178,7 +177,7 @@ interface CStarLibraryProviderProps extends LibraryConfig {
  * </CStarLibraryProvider>
  * ```
  */
-declare function CStarLibraryProvider({ children, ...config }: CStarLibraryProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarLibraryProvider({ children, ...config }: CStarLibraryProviderProps): react.JSX.Element;
 
 interface UseCategoriesReturn {
     /** All public categories. */
@@ -271,7 +270,7 @@ interface CStarCommunityProviderProps extends CommunityConfig {
  * </CStarCommunityProvider>
  * ```
  */
-declare function CStarCommunityProvider({ children, ...config }: CStarCommunityProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarCommunityProvider({ children, ...config }: CStarCommunityProviderProps): react.JSX.Element;
 
 interface UseTopicsReturn {
     /** Community discussion topics. */
@@ -360,6 +359,11 @@ interface CStarDashboardProviderProps {
      * provider builds the `CStarClient` internally so this prop can be passed
      * across the React Server Components boundary without tripping the
      * "Classes or null prototypes are not supported" runtime error.
+     * Every dashboard hook calls team endpoints, which need a secret key
+     * (a publishable key gets 403 publishable_key_forbidden). Config reaches
+     * the browser, so use the provider only where everyone who loads the page
+     * may hold that key (an internal tool behind your own login, a desktop
+     * app). On a public site, call your own backend instead.
      *
      * Either `config` or `client` is required.
      */
@@ -378,19 +382,23 @@ interface CStarDashboardProviderProps {
 /**
  * Provides a `CStarClient` to dashboard hooks.
  *
- * Unlike `CStarChatProvider` (which uses a publishable key for customer-facing
- * chat), this provider wraps a full admin client with a secret key for building
- * custom dashboards.
+ * Every hook calls team endpoints, which need a secret key: publishable keys
+ * get 403 publishable_key_forbidden on reads and publishable_key_write on
+ * writes. Provider props and bundled clients are visible to the browser, so
+ * use the provider only in a trusted environment (an internal tool behind
+ * your own login, a desktop app), with a secret key scoped to what the
+ * dashboard needs. For anything public, have the app call your own backend,
+ * where a secret-key `CStarClient` stays on the server.
  *
  * ```tsx
- * // Recommended: pass serializable config — works in any React tree, including
- * // App Router server components that hand the props to a client component.
- * <CStarDashboardProvider config={{ apiKey: process.env.CSTAR_API_KEY!, teamId }}>
+ * // app/providers.tsx (an internal tool behind your own login)
+ * 'use client';
+ * <CStarDashboardProvider config={{ apiKey: secretKeyFromYourServer, teamId }}>
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```
  */
-declare function CStarDashboardProvider({ config, client: providedClient, children }: CStarDashboardProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarDashboardProvider({ config, client: providedClient, children }: CStarDashboardProviderProps): react__default.JSX.Element;
 /**
  * Access the `CStarClient` from the nearest `CStarDashboardProvider`.
  * Throws if used outside a provider.

package/dist/index.d.ts

@@ -6,7 +6,6 @@ import { LibraryClient, LibraryConfig, Category, LibraryArticle, LibraryArticleL
 export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, LibrarySearchParams, LibrarySearchResult } from '@cstar.help/js/library';
 import { CommunityClient, CommunityConfig, CommunityTopic, CommunityPost, CommunityPostListParams, CommunityPostDetail, CommunitySearchResult } from '@cstar.help/js/community';
 export { CommunityComment, CommunityConfig, CommunityPost, CommunityPostDetail, CommunityPostListParams, CommunitySearchResult, CommunityTopic } from '@cstar.help/js/community';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import { CStarClientConfig, CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
@@ -41,7 +40,7 @@ interface CStarChatProviderProps extends ChatConfig {
  * </CStarChatProvider>
  * ```
  */
-declare function CStarChatProvider({ children, ...config }: CStarChatProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarChatProvider({ children, ...config }: CStarChatProviderProps): react.JSX.Element;
 
 interface UseChatReturn {
     /** Identify a customer with HMAC signature. */
@@ -178,7 +177,7 @@ interface CStarLibraryProviderProps extends LibraryConfig {
  * </CStarLibraryProvider>
  * ```
  */
-declare function CStarLibraryProvider({ children, ...config }: CStarLibraryProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarLibraryProvider({ children, ...config }: CStarLibraryProviderProps): react.JSX.Element;
 
 interface UseCategoriesReturn {
     /** All public categories. */
@@ -271,7 +270,7 @@ interface CStarCommunityProviderProps extends CommunityConfig {
  * </CStarCommunityProvider>
  * ```
  */
-declare function CStarCommunityProvider({ children, ...config }: CStarCommunityProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarCommunityProvider({ children, ...config }: CStarCommunityProviderProps): react.JSX.Element;
 
 interface UseTopicsReturn {
     /** Community discussion topics. */
@@ -360,6 +359,11 @@ interface CStarDashboardProviderProps {
      * provider builds the `CStarClient` internally so this prop can be passed
      * across the React Server Components boundary without tripping the
      * "Classes or null prototypes are not supported" runtime error.
+     * Every dashboard hook calls team endpoints, which need a secret key
+     * (a publishable key gets 403 publishable_key_forbidden). Config reaches
+     * the browser, so use the provider only where everyone who loads the page
+     * may hold that key (an internal tool behind your own login, a desktop
+     * app). On a public site, call your own backend instead.
      *
      * Either `config` or `client` is required.
      */
@@ -378,19 +382,23 @@ interface CStarDashboardProviderProps {
 /**
  * Provides a `CStarClient` to dashboard hooks.
  *
- * Unlike `CStarChatProvider` (which uses a publishable key for customer-facing
- * chat), this provider wraps a full admin client with a secret key for building
- * custom dashboards.
+ * Every hook calls team endpoints, which need a secret key: publishable keys
+ * get 403 publishable_key_forbidden on reads and publishable_key_write on
+ * writes. Provider props and bundled clients are visible to the browser, so
+ * use the provider only in a trusted environment (an internal tool behind
+ * your own login, a desktop app), with a secret key scoped to what the
+ * dashboard needs. For anything public, have the app call your own backend,
+ * where a secret-key `CStarClient` stays on the server.
  *
  * ```tsx
- * // Recommended: pass serializable config — works in any React tree, including
- * // App Router server components that hand the props to a client component.
- * <CStarDashboardProvider config={{ apiKey: process.env.CSTAR_API_KEY!, teamId }}>
+ * // app/providers.tsx (an internal tool behind your own login)
+ * 'use client';
+ * <CStarDashboardProvider config={{ apiKey: secretKeyFromYourServer, teamId }}>
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```
  */
-declare function CStarDashboardProvider({ config, client: providedClient, children }: CStarDashboardProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarDashboardProvider({ config, client: providedClient, children }: CStarDashboardProviderProps): react__default.JSX.Element;
 /**
  * Access the `CStarClient` from the nearest `CStarDashboardProvider`.
  * Throws if used outside a provider.

package/dist/index.js

@@ -191,36 +191,48 @@ function useMessages(ticketId) {
   const [error, setError] = useState3(null);
   const mountedRef = useRef3(true);
   const seenIdsRef = useRef3(/* @__PURE__ */ new Set());
+  const requestRef = useRef3(0);
+  const scopeRef = useRef3(0);
+  const optimisticRef = useRef3(0);
   const refresh = useCallback3(async () => {
     if (!ticketId) return;
+    const request = ++requestRef.current;
     setIsLoading(true);
     setError(null);
     try {
       const msgs = await client.messages.list(ticketId);
-      if (mountedRef.current) {
+      if (mountedRef.current && request === requestRef.current) {
         seenIdsRef.current = new Set(msgs.map((m) => m.id));
         setMessages(msgs);
       }
     } catch (err) {
-      if (mountedRef.current) {
+      if (mountedRef.current && request === requestRef.current) {
         setError(err instanceof Error ? err : new Error(String(err)));
       }
     } finally {
-      if (mountedRef.current) {
+      if (mountedRef.current && request === requestRef.current) {
         setIsLoading(false);
       }
     }
   }, [client, ticketId]);
   useEffect4(() => {
     mountedRef.current = true;
+    const scope = ++scopeRef.current;
+    seenIdsRef.current = /* @__PURE__ */ new Set();
+    setMessages([]);
+    setError(null);
     if (!ticketId) {
       setMessages([]);
       setIsLoading(false);
-      return;
+      return () => {
+        mountedRef.current = false;
+        requestRef.current++;
+        scopeRef.current++;
+      };
     }
     refresh();
     const unsubscribe = client.onMessage(ticketId, (msg) => {
-      if (mountedRef.current && !seenIdsRef.current.has(msg.id)) {
+      if (mountedRef.current && scope === scopeRef.current && !seenIdsRef.current.has(msg.id)) {
         seenIdsRef.current.add(msg.id);
         setMessages((prev) => {
           const optimisticIdx = prev.findIndex(
@@ -237,14 +249,17 @@ function useMessages(ticketId) {
     });
     return () => {
       mountedRef.current = false;
+      requestRef.current++;
+      scopeRef.current++;
       unsubscribe();
     };
   }, [client, ticketId, refresh]);
   const send = useCallback3(
     async (content) => {
       if (!ticketId) throw new Error("No ticket selected");
+      const scope = scopeRef.current;
       const optimistic = {
-        id: `optimistic-${Date.now()}`,
+        id: `optimistic-${++optimisticRef.current}`,
         content,
         sender: "customer",
         sender_name: "",
@@ -255,11 +270,14 @@ function useMessages(ticketId) {
       setMessages((prev) => [...prev, optimistic]);
       try {
         const msg = await client.messages.send(ticketId, content);
+        if (!mountedRef.current || scope !== scopeRef.current) return msg;
         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));
+        if (mountedRef.current && scope === scopeRef.current) {
+          setMessages((prev) => prev.filter((m) => m.id !== optimistic.id));
+        }
         throw err;
       }
     },
@@ -687,7 +705,7 @@ function CStarDashboardProvider({
 }) {
   if (!config && !providedClient) {
     throw new Error(
-      "CStarDashboardProvider requires either a `config` prop (`{ apiKey, teamId }` \u2014 recommended) or a `client` prop (a pre-built CStarClient instance, deprecated). See https://cstar.help/developers/sdk/react#dashboard"
+      "CStarDashboardProvider requires either a `config` prop (`{ apiKey, teamId }`, recommended) or a `client` prop (a pre-built CStarClient instance, deprecated). See https://cstar.help/developers/sdk/react#dashboard"
     );
   }
   const client = useMemo(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/react",
-	"version": "0.10.0",
+	"version": "0.10.2",
 	"description": "React hooks for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -30,19 +30,20 @@
 	},
 	"peerDependencies": {
 		"react": ">=18.0.0",
-		"@cstar.help/js": ">=0.15.0"
+		"@cstar.help/js": "^0.18.2"
 	},
 	"devDependencies": {
 		"react": "^18.3.1",
 		"react-dom": "^18.3.1",
-		"@cstar.help/js": "file:../js",
+		"@cstar.help/js": "^0.18.2",
 		"@testing-library/react": "^16.1.0",
 		"@types/react": "^18.3.0",
 		"@types/react-dom": "^18.3.0",
 		"tsup": "^8.5.0",
 		"typescript": "^5.7.0",
 		"vitest": "^3.2.0",
-		"jsdom": "^25.0.0"
+		"jsdom": "^25.0.0",
+		"@testing-library/dom": "^10.4.1"
 	},
 	"license": "MIT",
 	"engines": {
@@ -51,11 +52,11 @@
 	"homepage": "https://cstar.help/developers/sdk/react",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/cstar-help/cstar",
+		"url": "https://github.com/msjoshlopez/cstar",
 		"directory": "packages/react"
 	},
 	"bugs": {
-		"url": "https://github.com/cstar-help/cstar/issues"
+		"url": "https://www.cstar.help/support"
 	},
 	"keywords": [
 		"cstar",