@cstar.help/react 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cStar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# @cstar.help/react
+
+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
+- **Two modules** — Chat (real-time messaging) and Library (knowledge base)
+- **TypeScript-first** — full type definitions included
+- **Tiny** — ~18 KB, tree-shakeable, only peer deps
+
+## Install
+
+```bash
+npm install @cstar.help/react @cstar.help/js
+```
+
+## Chat
+
+Wrap your app in `<CStarChatProvider>` and use hooks anywhere inside.
+
+### Setup
+
+```tsx
+import { CStarChatProvider } from '@cstar.help/react';
+
+function App() {
+	return (
+		<CStarChatProvider teamSlug="acme" supabaseUrl="..." supabaseAnonKey="...">
+			<ChatWidget />
+		</CStarChatProvider>
+	);
+}
+```
+
+### Identify the Customer
+
+```tsx
+import { useChat } from '@cstar.help/react';
+
+function ChatWidget() {
+	const { identify, isIdentified, isRealtimeReady, error } = useChat();
+
+	useEffect(() => {
+		identify(
+			{ externalId: 'usr_123', email: 'jane@acme.com', timestamp: Math.floor(Date.now() / 1000) },
+			hmacSignature // computed server-side
+		);
+	}, []);
+
+	if (!isIdentified) return <p>Connecting...</p>;
+	return <ConversationList />;
+}
+```
+
+### Conversations
+
+```tsx
+import { useConversations } from '@cstar.help/react';
+
+function ConversationList() {
+	const { conversations, isLoading, create, refresh, hasMore } = useConversations();
+
+	if (isLoading) return <Spinner />;
+
+	return (
+		<ul>
+			{conversations.map((c) => (
+				<li key={c.id}>{c.subject}</li>
+			))}
+		</ul>
+	);
+}
+```
+
+### Messages + Typing Indicators
+
+```tsx
+import { useMessages, useTyping } from '@cstar.help/react';
+
+function ChatWindow({ ticketId }) {
+	const { messages, isLoading, send } = useMessages(ticketId);
+	const { typingAgents, sendTyping } = useTyping(ticketId);
+	const [text, setText] = useState('');
+
+	const handleSend = async () => {
+		await send(text); // optimistic — appears instantly
+		setText('');
+	};
+
+	return (
+		<>
+			{messages.map((msg) => (
+				<div key={msg.id}>{msg.content}</div>
+			))}
+			{typingAgents.map((a) => (
+				<p key={a.agentId}>{a.agentName} is typing...</p>
+			))}
+			<input
+				value={text}
+				onChange={(e) => {
+					setText(e.target.value);
+					sendTyping(e.target.value.length > 0);
+				}}
+				onKeyDown={(e) => e.key === 'Enter' && handleSend()}
+			/>
+		</>
+	);
+}
+```
+
+## Knowledge Base
+
+Wrap in `<CStarLibraryProvider>` for public knowledge base access — no auth required.
+
+### Setup
+
+```tsx
+import { CStarLibraryProvider } from '@cstar.help/react';
+
+function App() {
+	return (
+		<CStarLibraryProvider teamSlug="acme">
+			<HelpCenter />
+		</CStarLibraryProvider>
+	);
+}
+```
+
+### Categories + Articles
+
+```tsx
+import { useCategories, useArticles, useArticle } from '@cstar.help/react';
+
+function HelpCenter() {
+	const { categories, isLoading: catsLoading } = useCategories();
+	const { articles, isLoading: artsLoading } = useArticles({ categorySlug: 'getting-started' });
+
+	return (
+		<>
+			<nav>
+				{categories.map((cat) => (
+					<a key={cat.id}>{cat.name}</a>
+				))}
+			</nav>
+			<ul>
+				{articles.map((a) => (
+					<li key={a.id}>{a.title}</li>
+				))}
+			</ul>
+		</>
+	);
+}
+
+// Single article by slug
+function ArticlePage({ slug }) {
+	const { article, isLoading, error } = useArticle(slug);
+	if (isLoading) return <Spinner />;
+	if (!article) return <NotFound />;
+	return <h1>{article.title}</h1>;
+}
+```
+
+### Search with Debouncing
+
+```tsx
+import { useArticleSearch } from '@cstar.help/react';
+
+function SearchBar() {
+	const [query, setQuery] = useState('');
+	const { results, totalCount, isLoading } = useArticleSearch(query); // 300ms debounce built-in
+
+	return (
+		<>
+			<input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search..." />
+			{isLoading && <Spinner />}
+			{results.map((a) => (
+				<a key={a.id} href={`/articles/${a.slug}`}>
+					{a.title}
+				</a>
+			))}
+		</>
+	);
+}
+```
+
+## API Reference
+
+### Chat Hooks
+
+| Hook                    | Returns                                                          | Description                                          |
+| ----------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
+| `useChat()`             | `{ identify, disconnect, isIdentified, isRealtimeReady, error }` | Identity verification and connection state           |
+| `useConversations()`    | `{ conversations, isLoading, error, hasMore, refresh, create }`  | List and create conversations                        |
+| `useMessages(ticketId)` | `{ messages, isLoading, error, send, refresh }`                  | Messages with real-time updates and optimistic send  |
+| `useTyping(ticketId)`   | `{ typingAgents, sendTyping }`                                   | Agent typing indicators with auto-clear (4s timeout) |
+
+### Library Hooks
+
+| Hook                      | Returns                                     | Description                               |
+| ------------------------- | ------------------------------------------- | ----------------------------------------- |
+| `useCategories()`         | `{ categories, isLoading, error, refresh }` | Knowledge base categories                 |
+| `useArticles(params?)`    | `{ articles, isLoading, error, refresh }`   | Articles, optionally filtered by category |
+| `useArticle(slug)`        | `{ article, isLoading, error, refresh }`    | Single article by slug                    |
+| `useArticleSearch(query)` | `{ results, totalCount, isLoading, error }` | Search with 300ms debounce                |
+
+### Context Accessors
+
+| Function             | Returns         | Description                                    |
+| -------------------- | --------------- | ---------------------------------------------- |
+| `useChatClient()`    | `ChatClient`    | Raw client from nearest `CStarChatProvider`    |
+| `useLibraryClient()` | `LibraryClient` | Raw client from nearest `CStarLibraryProvider` |
+
+## Requirements
+
+- React 18+
+- @cstar.help/js 0.1.0+
+- Node.js 18+ (for SSR)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/react",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "React hooks for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -48,9 +48,14 @@
 	"engines": {
 		"node": ">=18.0.0"
 	},
+	"homepage": "https://cstar.help/developers/sdk/react",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/cstar-help/cstar"
+		"url": "https://github.com/cstar-help/cstar",
+		"directory": "packages/react"
+	},
+	"bugs": {
+		"url": "https://github.com/cstar-help/cstar/issues"
 	},
 	"keywords": [
 		"cstar",