@cstar.help/react 0.8.0 → 0.10.0

package/README.md

@@ -300,6 +300,69 @@ 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+

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) {
@@ -727,20 +732,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 +776,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 +788,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

@@ -7,7 +7,7 @@ export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, Libr
 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>;
@@ -355,28 +355,44 @@ 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.
+     *
+     * 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.
  *
  * ```tsx
- * const client = new CStarClient({ apiKey: 'sk_test_...', teamId: '...' });
- *
- * <CStarDashboardProvider client={client}>
+ * // 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 }}>
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```
  */
-declare function CStarDashboardProvider({ client, children }: CStarDashboardProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarDashboardProvider({ config, client: providedClient, children }: CStarDashboardProviderProps): react_jsx_runtime.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

@@ -7,7 +7,7 @@ export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, Libr
 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>;
@@ -355,28 +355,44 @@ 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.
+     *
+     * 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.
  *
  * ```tsx
- * const client = new CStarClient({ apiKey: 'sk_test_...', teamId: '...' });
- *
- * <CStarDashboardProvider client={client}>
+ * // 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 }}>
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```
  */
-declare function CStarDashboardProvider({ client, children }: CStarDashboardProviderProps): react_jsx_runtime.JSX.Element;
+declare function CStarDashboardProvider({ config, client: providedClient, children }: CStarDashboardProviderProps): react_jsx_runtime.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) {
@@ -671,21 +676,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 +720,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 +733,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 +870,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 +901,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 +932,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 +963,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.8.0",
+	"version": "0.10.0",
 	"description": "React hooks for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -30,7 +30,7 @@
 	},
 	"peerDependencies": {
 		"react": ">=18.0.0",
-		"@cstar.help/js": ">=0.11.0"
+		"@cstar.help/js": ">=0.15.0"
 	},
 	"devDependencies": {
 		"react": "^18.3.1",