@cstar.help/react 0.9.0 → 0.10.1

package/README.md

@@ -300,11 +300,74 @@ function CommunitySearch() {
 | `useLibraryClient()`   | `LibraryClient`   | Raw client from nearest `CStarLibraryProvider`   |
 | `useCommunityClient()` | `CommunityClient` | Raw client from nearest `CStarCommunityProvider` |
 
+## 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
+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
+disposes) the client inside the `'use client'` boundary, so nothing
+class-shaped crosses the RSC boundary:
+
+```tsx
+// app/providers.tsx
+'use client';
+import { CStarDashboardProvider } from '@cstar.help/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+	return (
+		<CStarDashboardProvider
+			config={{
+				apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!,
+				teamId: process.env.NEXT_PUBLIC_CSTAR_TEAM_ID!
+			}}
+		>
+			{children}
+		</CStarDashboardProvider>
+	);
+}
+```
+
+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.
+
+**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:
+
+```tsx
+'use client';
+import { useMemo } from 'react';
+import { CStarClient } from '@cstar.help/js';
+import { CStarDashboardProvider } from '@cstar.help/react';
+
+export function Providers({ children }) {
+	const client = useMemo(
+		() =>
+			new CStarClient({
+				apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!,
+				teamId: process.env.NEXT_PUBLIC_CSTAR_TEAM_ID!
+			}),
+		[]
+	);
+	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
+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

@@ -107,9 +107,14 @@ function useChat() {
   const [isRealtimeReady, setIsRealtimeReady] = (0, import_react3.useState)(false);
   const [error, setError] = (0, import_react3.useState)(null);
   (0, import_react3.useEffect)(() => {
-    const current = client.getAuthMode();
-    if (current !== authMode) setAuthMode(current);
-  }, [client, authMode]);
+    const subscribe = client.subscribe?.bind(client);
+    if (!subscribe) return;
+    return subscribe(() => {
+      const mode = client.getAuthMode();
+      setAuthMode(mode);
+      setIsAuthenticated(mode !== null);
+    });
+  }, [client]);
   const wireRealtime = (0, import_react3.useCallback)(() => {
     client.waitForRealtime().then(() => setIsRealtimeReady(true)).catch(() => {
     });
@@ -199,7 +204,7 @@ function useTickets() {
     try {
       const result = await client.tickets.list();
       if (mountedRef.current) {
-        setTickets(result.tickets);
+        setTickets(result.data);
         setHasMore(result.hasMore);
       }
     } catch (err) {
@@ -241,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(
@@ -287,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: "",
@@ -305,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;
       }
     },
@@ -727,20 +750,38 @@ function useCommunitySearch() {
 
 // src/dashboard/CStarDashboardProvider.tsx
 var import_react17 = require("react");
+var import_js = require("@cstar.help/js");
 var import_jsx_runtime4 = require("react/jsx-runtime");
 var CStarDashboardContext = (0, import_react17.createContext)(null);
-function CStarDashboardProvider({ client, children }) {
-  if (!client) {
+function CStarDashboardProvider({
+  config,
+  client: providedClient,
+  children
+}) {
+  if (!config && !providedClient) {
     throw new Error(
-      "CStarDashboardProvider requires a `client` prop. Build it server-side with `new CStarClient({ apiKey: process.env.CSTAR_API_KEY, teamId })` and pass via SSR. See https://cstar.help/developers/sdk/react#dashboard"
+      "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"
     );
   }
-  const contextValue = (0, import_react17.useRef)({ client }).current;
+  const client = (0, import_react17.useMemo)(() => {
+    if (providedClient) return providedClient;
+    return new import_js.CStarClient(config);
+  }, [
+    providedClient,
+    config?.apiKey,
+    config?.teamId,
+    config?.baseUrl,
+    config?.version,
+    config?.maxRetries,
+    config?.timeout
+  ]);
+  const contextValue = (0, import_react17.useMemo)(() => ({ client }), [client]);
   (0, import_react17.useEffect)(() => {
+    if (providedClient) return;
     return () => {
       client?.realtime?.disconnect?.();
     };
-  }, [client]);
+  }, [client, providedClient]);
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(CStarDashboardContext.Provider, { value: contextValue, children });
 }
 function useDashboardClient() {
@@ -753,6 +794,7 @@ function useDashboardClient() {
 
 // src/dashboard/useCStarQuery.ts
 var import_react18 = require("react");
+var import_js2 = require("@cstar.help/js");
 function resolveResource(client, path) {
   const parts = path.split(".");
   if (parts.length < 2 || parts[1] !== "list") return null;
@@ -764,6 +806,11 @@ function resolveResource(client, path) {
   return { resource, basePath: `/${resourceName}` };
 }
 function useCStarQuery(resource, params) {
+  if (typeof resource !== "string") {
+    throw new import_js2.CStarValidationError(
+      `useCStarQuery: \`resource\` must be a string (e.g. 'tickets.list'). Received ${resource === null ? "null" : typeof resource}. The signature is useCStarQuery(resource: string, params?: object).`
+    );
+  }
   const client = useDashboardClient();
   const [data, setData] = (0, import_react18.useState)(null);
   const [loading, setLoading] = (0, import_react18.useState)(true);

package/dist/index.d.cts

@@ -6,8 +6,7 @@ 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 { CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
+import { CStarClientConfig, CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
 declare const CStarLibraryContext: react.Context<LibraryClient | 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. */
@@ -355,28 +354,48 @@ interface UseCommunitySearchReturn {
 declare function useCommunitySearch(): UseCommunitySearchReturn;
 
 interface CStarDashboardProviderProps {
-    /** A pre-configured CStarClient instance (server-side, secret key). */
-    client: CStarClient;
+    /**
+     * Serializable client config — `{ apiKey, teamId, baseUrl?, ... }`. The
+     * 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.
+     * Config is visible to the browser: use only a publishable key here.
+     *
+     * Either `config` or `client` is required.
+     */
+    config?: CStarClientConfig;
+    /**
+     * A pre-built `CStarClient` instance.
+     *
+     * @deprecated since 0.9.0 — pass `config` instead. Class instances cannot
+     *   cross the RSC boundary, which makes this prop unsafe to use from a
+     *   Next.js App Router server component. Kept as an escape hatch for
+     *   integrators who already wired it; will be removed in 1.0.
+     */
+    client?: CStarClient;
     children: react__default.ReactNode;
 }
 /**
- * Provides a CStarClient to dashboard hooks.
+ * 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.
+ * Provider props and bundled clients are visible to the browser. Pass only
+ * a publishable key; supported operations are limited by that key's permissions.
+ * Run privileged dashboard reads and mutations through your authenticated
+ * backend, where a secret-key `CStarClient` stays on the server.
  *
  * ```tsx
- * const client = new CStarClient({ apiKey: 'sk_test_...', teamId: '...' });
- *
- * <CStarDashboardProvider client={client}>
+ * // app/providers.tsx
+ * 'use client';
+ * <CStarDashboardProvider
+ *   config={{ apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!, teamId }}
+ * >
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```
  */
-declare function CStarDashboardProvider({ client, 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.
+ * Access the `CStarClient` from the nearest `CStarDashboardProvider`.
  * Throws if used outside a provider.
  */
 declare function useDashboardClient(): CStarClient;

package/dist/index.d.ts

@@ -6,8 +6,7 @@ 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 { CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
+import { CStarClientConfig, CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
 declare const CStarLibraryContext: react.Context<LibraryClient | 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. */
@@ -355,28 +354,48 @@ interface UseCommunitySearchReturn {
 declare function useCommunitySearch(): UseCommunitySearchReturn;
 
 interface CStarDashboardProviderProps {
-    /** A pre-configured CStarClient instance (server-side, secret key). */
-    client: CStarClient;
+    /**
+     * Serializable client config — `{ apiKey, teamId, baseUrl?, ... }`. The
+     * 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.
+     * Config is visible to the browser: use only a publishable key here.
+     *
+     * Either `config` or `client` is required.
+     */
+    config?: CStarClientConfig;
+    /**
+     * A pre-built `CStarClient` instance.
+     *
+     * @deprecated since 0.9.0 — pass `config` instead. Class instances cannot
+     *   cross the RSC boundary, which makes this prop unsafe to use from a
+     *   Next.js App Router server component. Kept as an escape hatch for
+     *   integrators who already wired it; will be removed in 1.0.
+     */
+    client?: CStarClient;
     children: react__default.ReactNode;
 }
 /**
- * Provides a CStarClient to dashboard hooks.
+ * 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.
+ * Provider props and bundled clients are visible to the browser. Pass only
+ * a publishable key; supported operations are limited by that key's permissions.
+ * Run privileged dashboard reads and mutations through your authenticated
+ * backend, where a secret-key `CStarClient` stays on the server.
  *
  * ```tsx
- * const client = new CStarClient({ apiKey: 'sk_test_...', teamId: '...' });
- *
- * <CStarDashboardProvider client={client}>
+ * // app/providers.tsx
+ * 'use client';
+ * <CStarDashboardProvider
+ *   config={{ apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!, teamId }}
+ * >
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```
  */
-declare function CStarDashboardProvider({ client, 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.
+ * Access the `CStarClient` from the nearest `CStarDashboardProvider`.
  * Throws if used outside a provider.
  */
 declare function useDashboardClient(): CStarClient;

package/dist/index.js

@@ -52,9 +52,14 @@ function useChat() {
   const [isRealtimeReady, setIsRealtimeReady] = useState(false);
   const [error, setError] = useState(null);
   useEffect2(() => {
-    const current = client.getAuthMode();
-    if (current !== authMode) setAuthMode(current);
-  }, [client, authMode]);
+    const subscribe = client.subscribe?.bind(client);
+    if (!subscribe) return;
+    return subscribe(() => {
+      const mode = client.getAuthMode();
+      setAuthMode(mode);
+      setIsAuthenticated(mode !== null);
+    });
+  }, [client]);
   const wireRealtime = useCallback(() => {
     client.waitForRealtime().then(() => setIsRealtimeReady(true)).catch(() => {
     });
@@ -144,7 +149,7 @@ function useTickets() {
     try {
       const result = await client.tickets.list();
       if (mountedRef.current) {
-        setTickets(result.tickets);
+        setTickets(result.data);
         setHasMore(result.hasMore);
       }
     } catch (err) {
@@ -186,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(
@@ -232,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: "",
@@ -250,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;
       }
     },
@@ -671,21 +694,39 @@ function useCommunitySearch() {
 }
 
 // src/dashboard/CStarDashboardProvider.tsx
-import { createContext as createContext2, useContext as useContext2, useEffect as useEffect14, useRef as useRef15 } from "react";
+import { createContext as createContext2, useContext as useContext2, useEffect as useEffect14, useMemo } from "react";
+import { CStarClient } from "@cstar.help/js";
 import { jsx as jsx4 } from "react/jsx-runtime";
 var CStarDashboardContext = createContext2(null);
-function CStarDashboardProvider({ client, children }) {
-  if (!client) {
+function CStarDashboardProvider({
+  config,
+  client: providedClient,
+  children
+}) {
+  if (!config && !providedClient) {
     throw new Error(
-      "CStarDashboardProvider requires a `client` prop. Build it server-side with `new CStarClient({ apiKey: process.env.CSTAR_API_KEY, teamId })` and pass via SSR. See https://cstar.help/developers/sdk/react#dashboard"
+      "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"
     );
   }
-  const contextValue = useRef15({ client }).current;
+  const client = useMemo(() => {
+    if (providedClient) return providedClient;
+    return new CStarClient(config);
+  }, [
+    providedClient,
+    config?.apiKey,
+    config?.teamId,
+    config?.baseUrl,
+    config?.version,
+    config?.maxRetries,
+    config?.timeout
+  ]);
+  const contextValue = useMemo(() => ({ client }), [client]);
   useEffect14(() => {
+    if (providedClient) return;
     return () => {
       client?.realtime?.disconnect?.();
     };
-  }, [client]);
+  }, [client, providedClient]);
   return /* @__PURE__ */ jsx4(CStarDashboardContext.Provider, { value: contextValue, children });
 }
 function useDashboardClient() {
@@ -697,7 +738,8 @@ function useDashboardClient() {
 }
 
 // src/dashboard/useCStarQuery.ts
-import { useState as useState13, useEffect as useEffect15, useRef as useRef16, useCallback as useCallback12 } from "react";
+import { useState as useState13, useEffect as useEffect15, useRef as useRef15, useCallback as useCallback12 } from "react";
+import { CStarValidationError } from "@cstar.help/js";
 function resolveResource(client, path) {
   const parts = path.split(".");
   if (parts.length < 2 || parts[1] !== "list") return null;
@@ -709,11 +751,16 @@ function resolveResource(client, path) {
   return { resource, basePath: `/${resourceName}` };
 }
 function useCStarQuery(resource, params) {
+  if (typeof resource !== "string") {
+    throw new CStarValidationError(
+      `useCStarQuery: \`resource\` must be a string (e.g. 'tickets.list'). Received ${resource === null ? "null" : typeof resource}. The signature is useCStarQuery(resource: string, params?: object).`
+    );
+  }
   const client = useDashboardClient();
   const [data, setData] = useState13(null);
   const [loading, setLoading] = useState13(true);
   const [error, setError] = useState13(null);
-  const subscriptionRef = useRef16(null);
+  const subscriptionRef = useRef15(null);
   const paramsKey = params ? JSON.stringify(params) : "";
   useEffect15(() => {
     const resolved = resolveResource(client, resource);
@@ -841,13 +888,13 @@ function useCStarEvents(types) {
 }
 
 // src/dashboard/useBossBattle.ts
-import { useState as useState16, useEffect as useEffect17, useRef as useRef17, useCallback as useCallback14 } from "react";
+import { useState as useState16, useEffect as useEffect17, useRef as useRef16, useCallback as useCallback14 } from "react";
 function useBossBattle() {
   const client = useDashboardClient();
   const [boss, setBoss] = useState16(null);
   const [loading, setLoading] = useState16(true);
   const [error, setError] = useState16(null);
-  const subRef = useRef17(null);
+  const subRef = useRef16(null);
   useEffect17(() => {
     const sub = client.game.subscribeBoss(client.realtime);
     subRef.current = sub;
@@ -872,13 +919,13 @@ function useBossBattle() {
 }
 
 // src/dashboard/usePlayerStats.ts
-import { useState as useState17, useEffect as useEffect18, useRef as useRef18, useCallback as useCallback15 } from "react";
+import { useState as useState17, useEffect as useEffect18, useRef as useRef17, useCallback as useCallback15 } from "react";
 function usePlayerStats(memberId) {
   const client = useDashboardClient();
   const [player, setPlayer] = useState17(null);
   const [loading, setLoading] = useState17(true);
   const [error, setError] = useState17(null);
-  const subRef = useRef18(null);
+  const subRef = useRef17(null);
   useEffect18(() => {
     const sub = client.game.subscribePlayer(client.realtime, memberId);
     subRef.current = sub;
@@ -903,13 +950,13 @@ function usePlayerStats(memberId) {
 }
 
 // src/dashboard/useLeaderboard.ts
-import { useState as useState18, useEffect as useEffect19, useRef as useRef19, useCallback as useCallback16 } from "react";
+import { useState as useState18, useEffect as useEffect19, useRef as useRef18, useCallback as useCallback16 } from "react";
 function useLeaderboard(period) {
   const client = useDashboardClient();
   const [entries, setEntries] = useState18([]);
   const [loading, setLoading] = useState18(true);
   const [error, setError] = useState18(null);
-  const subRef = useRef19(null);
+  const subRef = useRef18(null);
   useEffect19(() => {
     const sub = client.game.subscribeLeaderboard(client.realtime, period ? { period } : void 0);
     subRef.current = sub;
@@ -934,13 +981,13 @@ function useLeaderboard(period) {
 }
 
 // src/dashboard/useGameActivity.ts
-import { useState as useState19, useEffect as useEffect20, useRef as useRef20, useCallback as useCallback17 } from "react";
+import { useState as useState19, useEffect as useEffect20, useRef as useRef19, useCallback as useCallback17 } from "react";
 function useGameActivity() {
   const client = useDashboardClient();
   const [events, setEvents] = useState19([]);
   const [loading, setLoading] = useState19(true);
   const [error, setError] = useState19(null);
-  const subRef = useRef20(null);
+  const subRef = useRef19(null);
   useEffect20(() => {
     const sub = client.game.subscribeActivity(client.realtime);
     subRef.current = sub;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/react",
-	"version": "0.9.0",
+	"version": "0.10.1",
 	"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.14.0"
+		"@cstar.help/js": ">=0.15.0"
 	},
 	"devDependencies": {
 		"react": "^18.3.1",
 		"react-dom": "^18.3.1",
-		"@cstar.help/js": "file:../js",
+		"@cstar.help/js": "^0.17.0",
 		"@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",