@cstar.help/react 0.10.1 → 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,21 +356,21 @@ 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

package/dist/index.cjs

@@ -760,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

@@ -359,7 +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.
-     * Config is visible to the browser: use only a publishable key here.
+     * 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,17 +382,18 @@ interface CStarDashboardProviderProps {
 /**
  * Provides a `CStarClient` to dashboard hooks.
  *
- * 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.
+ * 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
- * // app/providers.tsx
+ * // app/providers.tsx (an internal tool behind your own login)
  * 'use client';
- * <CStarDashboardProvider
- *   config={{ apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!, teamId }}
- * >
+ * <CStarDashboardProvider config={{ apiKey: secretKeyFromYourServer, teamId }}>
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```

package/dist/index.d.ts

@@ -359,7 +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.
-     * Config is visible to the browser: use only a publishable key here.
+     * 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,17 +382,18 @@ interface CStarDashboardProviderProps {
 /**
  * Provides a `CStarClient` to dashboard hooks.
  *
- * 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.
+ * 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
- * // app/providers.tsx
+ * // app/providers.tsx (an internal tool behind your own login)
  * 'use client';
- * <CStarDashboardProvider
- *   config={{ apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!, teamId }}
- * >
+ * <CStarDashboardProvider config={{ apiKey: secretKeyFromYourServer, teamId }}>
  *   <TicketList />
  * </CStarDashboardProvider>
  * ```

package/dist/index.js

@@ -705,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.1",
+	"version": "0.10.2",
 	"description": "React hooks for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -30,12 +30,12 @@
 	},
 	"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": "^0.17.0",
+		"@cstar.help/js": "^0.18.2",
 		"@testing-library/react": "^16.1.0",
 		"@types/react": "^18.3.0",
 		"@types/react-dom": "^18.3.0",