@cstar.help/react 0.10.1 → 0.10.3

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
 
@@ -117,6 +117,7 @@ Wrap in `<CStarLibraryProvider>` for public knowledge base access — no auth re
 import { CStarLibraryProvider } from '@cstar.help/react';
 
 function App() {
+	// Seeded with a test key (cstar seed)? Add publishableKey="pk_test_..." to read test articles.
 	return (
 		<CStarLibraryProvider teamSlug="acme">
 			<HelpCenter />
@@ -184,7 +185,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 +221,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 +304,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 +317,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 +337,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 +357,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