@cstar.help/js 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ Official TypeScript SDK for the [cStar](https://cstar.help) customer support pla
 
 - **Zero dependencies** — works with Node.js 18+ native `fetch`
 - **TypeScript-first** — full type definitions included
-- **Five entry points** — tree-shake what you don't need
+- **Six entry points** — tree-shake what you don't need
 - **ESM + CJS** — works everywhere
 
 ## Install
@@ -13,18 +13,56 @@ Official TypeScript SDK for the [cStar](https://cstar.help) customer support pla
 npm install @cstar.help/js
 ```
 
-## Quick Start
+---
 
-### Server-side API Client
+## Which SDK Do I Need?
 
-Manage tickets, customers, articles, and webhooks with your secret API key.
+cStar has one package with **six entry points**, each designed for a different context:
+
+| Import                     | Use Case                                  | Runs On           | Auth Required | Key Type             |
+| -------------------------- | ----------------------------------------- | ----------------- | ------------- | -------------------- |
+| `@cstar.help/js`           | **Admin dashboard / backend integration** | Server only       | Yes           | Secret (`sk_*`)      |
+| `@cstar.help/js/chat`      | Customer chat widget                      | Browser           | Yes           | Publishable (`pk_*`) |
+| `@cstar.help/js/library`   | Public knowledge base                     | Browser or server | No            | None                 |
+| `@cstar.help/js/community` | Public community forum                    | Browser or server | No            | None                 |
+| `@cstar.help/js/webhook`   | Webhook signature verification            | Server only       | No            | Signing secret       |
+| `@cstar.help/js/auth`      | Authentication utilities                  | Server only       | Yes           | Secret (`sk_*`)      |
+
+### The Security Model
+
+cStar uses **two key types** to control access — the same pattern as Stripe and Supabase:
+
+```
+Secret keys (sk_live_*, sk_test_*)
+├── Full CRUD on all resources
+├── Settings, billing, analytics, game system
+├── Team member management, audit log
+├── AI actions, automations, SLA rules
+└── NEVER expose in client-side code
+
+Publishable keys (pk_live_*, pk_test_*)
+├── Read-only on public data (tickets, customers, articles)
+├── Used by the chat widget for customer-facing features
+├── Safe to include in browser bundles
+└── Cannot write, delete, or access sensitive endpoints
+```
+
+> **Rule of thumb**: If you're building a custom support dashboard for your team, use `CStarClient` with a secret key on your backend. If you're adding chat to your website, use `ChatClient` with a publishable key in the browser.
+
+---
+
+## Server-Side: Admin API Client
+
+> **⚠️ Server-side only.** `CStarClient` requires a secret key (`sk_*`) and must never be used in browser code. The SDK will warn you if it detects a browser environment.
+
+Manage tickets, customers, articles, team members, settings, game system, and everything else.
 
 ```typescript
 import { CStarClient } from '@cstar.help/js';
 
 const cstar = new CStarClient({
-	apiKey: 'sk_live_abc123...',
-	teamId: 'tm_your_team_id'
+	apiKey: process.env.CSTAR_SECRET_KEY, // sk_live_... or sk_test_...
+	teamId: process.env.CSTAR_TEAM_ID
 });
 
 // List open tickets
@@ -36,18 +74,131 @@ const { data: ticket } = await cstar.tickets.create({
 	customerId: 'cus_abc123'
 });
 
-// Get a customer with expanded fields
-const { data: customer } = await cstar.customers.get('cus_abc123');
-
 // Auto-paginate through all tickets
 for await (const ticket of cstar.tickets.listAutoPaginating({ status: 'open' })) {
 	console.log(ticket.title);
 }
 ```
 
-### Customer Chat (Widget SDK)
+### Full Resource Reference
+
+**Core Resources** — Tickets, customers, and knowledge base.
+
+| Resource                 | Methods                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------- |
+| `cstar.tickets`          | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.tickets.messages` | `.list(ticketId)` `.create(ticketId, params)`                                                   |
+| `cstar.customers`        | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.articles`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.categories`       | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)`                         |
+
+**Team & Configuration** — Members, settings, and customization.
+
+| Resource                      | Methods                                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `cstar.members`               | `.list()` `.get(id)` `.update(id, params)` `.del(id)`                                                                  |
+| `cstar.members.invites`       | `.list()` `.create(params)` `.del(id)`                                                                                 |
+| `cstar.settings`              | `.get()` `.update(params)` `.getBusinessHours()` `.updateBusinessHours(params)` `.getWidget()` `.updateWidget(params)` |
+| `cstar.settings.statuses`     | `.list()` `.create(params)` `.update(key, params)` `.del(key)` `.reorder(keys)`                                        |
+| `cstar.settings.quickReplies` | `.list()` `.create(params)` `.update(id, params)` `.del(id)` `.reorder(ids)`                                           |
+| `cstar.customFields`          | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.reorder(ids)`                                |
+| `cstar.notifications`         | `.list()` `.unreadCount()` `.markRead(id)` `.markAllRead()`                                                            |
+
+**Operations** — Analytics, bulk actions, and data management.
+
+| Resource               | Methods                                                                                 |
+| ---------------------- | --------------------------------------------------------------------------------------- |
+| `cstar.analytics`      | `.overview(params?)` `.agents(params?)` `.csatStats(params?)` `.csatResponses(params?)` |
+| `cstar.sla`            | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)`                 |
+| `cstar.bulk`           | `.update(params)` `.del(params)`                                                        |
+| `cstar.export`         | `.create(params)`                                                                       |
+| `cstar.import`         | `.create(params)` `.logs(params?)` `.getLog(id)`                                        |
+| `cstar.search`         | `.query(params)`                                                                        |
+| `cstar.tags`           | `.list()` `.create(name)` `.del(name)`                                                  |
+| `cstar.activity`       | `.list(params?)`                                                                        |
+| `cstar.auditLog`       | `.list(params?)`                                                                        |
+| `cstar.customerGroups` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)`                 |
+
+**Gamification** — The full game system.
+
+| Resource                  | Methods                                                                                             |
+| ------------------------- | --------------------------------------------------------------------------------------------------- |
+| `cstar.game`              | `.player(params?)` `.getPlayer(memberId)` `.leaderboard(params?)` `.myRank(params?)`                |
+| `cstar.game.boss`         | `.current()` `.isActive()` `.spawn(params?)` `.damage(params)` `.defeats(params?)` `.getDefeat(id)` |
+| `cstar.game.achievements` | `.list(params?)` `.unlocked(params)` `.get(id, params?)`                                            |
+| `cstar.game.quests`       | `.today(params?)` `.history(params?)`                                                               |
+| `cstar.game.puzzles`      | `.today(params?)` `.complete(params)` `.streak(params)` `.leaderboard(params?)`                     |
+| `cstar.game.oneUps`       | `.list(params?)` `.send(params)` `.remaining(params)`                                               |
+| `cstar.game.highFives`    | `.list(params?)` `.send(params)` `.canSend(teamId, params)`                                         |
+| `cstar.game.cosmetics`    | `.list(params?)` `.getPreferences(params)` `.updatePreferences(params)`                             |
+| `cstar.game.seasons`      | `.list()` `.current()` `.stats(seasonId, params)`                                                   |
+| `cstar.game.skills`       | `.get(params)` `.allocate(params)` `.reset(params)`                                                 |
+
+**Advanced** — AI, automations, views, billing, webhooks.
+
+| Resource                 | Methods                                                                                                                                                                            |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cstar.ai`               | `.run(params)` `.autoTag(ticketId)` `.suggestReply(ticketId)` `.summarize(ticketId)` `.improve(text)`                                                                              |
+| `cstar.automations`      | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.toggle(id)` `.reorder(ids)` `.test(id, params)` `.executions(id)` `.allExecutions()` `.evaluate(params)` |
+| `cstar.views`            | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.execute(id, params?)`                                                                                    |
+| `cstar.billing`          | `.subscription()` `.portal(params?)`                                                                                                                                               |
+| `cstar.webhooks`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.test(id)`                                                                                                |
+| `cstar.community.posts`  | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)`                                                                                                            |
+| `cstar.community.topics` | `.list()` `.get(id)`                                                                                                                                                               |
+| `cstar.attachments`      | `.list(params?)` `.get(id)` `.del(id)`                                                                                                                                             |
+
+### Usage Examples
+
+```typescript
+// Team analytics
+const { data: overview } = await cstar.analytics.overview({ period: 'week' });
+console.log(`${overview.tickets.open} open tickets this week`);
+
+// SLA rules
+const { data: rules } = await cstar.sla.list();
+
+// Boss battle
+const { data: boss } = await cstar.game.boss.current();
+if (boss.active) {
+	console.log(`${boss.name} — ${boss.health}/${boss.maxHealth} HP`);
+}
+
+// AI-powered reply suggestion
+const { data: suggestion } = await cstar.ai.suggestReply('tkt_abc123');
+
+// Bulk close resolved tickets
+await cstar.bulk.update({
+	resource: 'tickets',
+	ids: ['tkt_1', 'tkt_2', 'tkt_3'],
+	data: { status: 'closed' }
+});
+
+// Export data
+const { data: exportResult } = await cstar.export.create({
+	resources: [{ type: 'tickets', filters: { status: 'closed' } }],
+	format: 'csv'
+});
+
+// Saved views
+const { data: view } = await cstar.views.create({
+	name: 'Urgent Unresolved',
+	entityType: 'tickets',
+	filters: { priority: 'urgent', status: 'open' }
+});
+const { data: results } = await cstar.views.execute(view.id);
+
+// Search across everything
+const { data: searchResults } = await cstar.search.query({
+	query: 'billing issue',
+	types: ['tickets', 'customers']
+});
+```
+
+---
+
+## Client-Side: Chat Widget SDK
 
-Build custom chat experiences with identity verification.
+Build custom chat experiences in the browser. Uses a publishable key — safe for frontend code.
 
 ```typescript
 import { ChatClient } from '@cstar.help/js/chat';
@@ -66,7 +217,7 @@ const { conversations } = await chat.conversations.list();
 // Send a message
 await chat.messages.send('tkt_abc123', 'Thanks for the help!');
 
-// Subscribe to new messages (polling)
+// Subscribe to new messages
 const unsubscribe = chat.onMessage('tkt_abc123', (message) => {
 	console.log(`${message.sender_name}: ${message.content}`);
 });
@@ -75,88 +226,48 @@ const unsubscribe = chat.onMessage('tkt_abc123', (message) => {
 chat.disconnect();
 ```
 
-### Public Knowledge Base
+---
 
-Search and browse your public help center — no authentication required.
+## Client-Side: Public Knowledge Base
+
+Search and browse your public help center — **no authentication required**.
 
 ```typescript
 import { LibraryClient } from '@cstar.help/js/library';
 
 const library = new LibraryClient({ teamSlug: 'acme' });
 
-// List categories
 const categories = await library.categories();
-
-// Search articles
 const results = await library.search('reset password');
-
-// Get a specific article
 const article = await library.article('how-to-reset-password');
 ```
 
-### Public Community
+---
 
-Browse and search your public community forum — no authentication required.
+## Client-Side: Public Community
+
+Browse your public community forum — **no authentication required**.
 
 ```typescript
 import { CommunityClient } from '@cstar.help/js/community';
 
 const community = new CommunityClient({ teamSlug: 'acme' });
 
-// List discussion topics
 const topics = await community.topics();
-
-// List posts (with filters)
-const { posts, count } = await community.posts({
-	topicSlug: 'feature-requests',
-	sort: 'votes'
-});
-
-// Get a single post with all comments
+const { posts } = await community.posts({ topicSlug: 'feature-requests', sort: 'votes' });
 const { post, comments } = await community.post('dark-mode-support');
-
-// Search posts
-const results = await community.search('billing');
 ```
 
-### Server-side Community (Admin)
-
-Manage community posts with your secret API key via `CStarClient`:
+---
 
-```typescript
-const cstar = new CStarClient({ apiKey: 'sk_live_...', teamId: 'tm_...' });
-
-// List all posts (including hidden/unapproved)
-const { data: posts } = await cstar.community.posts.list({ status: 'open' });
-
-// Create a post
-const { data: post } = await cstar.community.posts.create({
-	title: 'New Feature: Dark Mode',
-	body: 'We just shipped dark mode!',
-	topicId: 'topic_abc123'
-});
-
-// Toggle vote on a post
-const { voted, voteCount } = await cstar.community.posts.vote('post_id');
-
-// Add a comment
-const comment = await cstar.community.posts.createComment('post_id', {
-	body: 'Great idea!',
-	isOfficial: true
-});
-
-// List topics
-const { data: topics } = await cstar.community.topics.list();
-```
-
-### Webhook Verification
+## Server-Side: Webhook Verification
 
 Verify incoming webhook signatures on your server.
 
 ```typescript
 import { constructEvent } from '@cstar.help/js/webhook';
 
-// In your webhook handler (Express, Hono, etc.)
+// In your webhook handler
 const event = constructEvent(rawBody, signature, 'whsec_your_secret');
 
 switch (event.type) {
@@ -169,33 +280,20 @@ switch (event.type) {
 }
 ```
 
-For edge environments (Cloudflare Workers, Deno), use the async variant:
+For edge runtimes (Cloudflare Workers, Deno), use the async variant:
 
 ```typescript
 import { constructEventAsync } from '@cstar.help/js/webhook';
-
 const event = await constructEventAsync(rawBody, signature, secret);
 ```
 
-## API Reference
-
-### CStarClient
-
-| Resource                 | Methods                                                                                                                                            |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cstar.tickets`          | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()`                                                    |
-| `cstar.tickets.messages` | `.list(ticketId)` `.create(ticketId, params)`                                                                                                      |
-| `cstar.customers`        | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()`                                                    |
-| `cstar.articles`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()`                                                    |
-| `cstar.webhooks`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.test(id)`                                                                |
-| `cstar.community.posts`  | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.vote(id)` `.follow(id)` `.listComments(id)` `.createComment(id, params)` |
-| `cstar.community.topics` | `.list()` `.get(id)`                                                                                                                               |
+---
 
-### Configuration
+## Configuration
 
 ```typescript
 const cstar = new CStarClient({
-	apiKey: 'sk_live_...', // Required — secret or publishable key
+	apiKey: 'sk_live_...', // Required — must be a secret key (sk_*)
 	teamId: 'tm_...', // Required — your team ID
 	baseUrl: 'https://...', // Optional — defaults to https://www.cstar.help
 	version: '2026-03-01', // Optional — API version header
@@ -204,26 +302,32 @@ const cstar = new CStarClient({
 });
 ```
 
-### Test Mode
+## Test Mode
 
 Test mode is auto-detected from your API key prefix:
 
 ```typescript
-// Uses test data — no real customers affected
 const cstar = new CStarClient({
 	apiKey: 'sk_test_abc123...',
 	teamId: 'tm_your_team_id'
 });
 
 console.log(cstar.isTestMode); // true
+// All operations use test data — no real customers affected
 ```
 
-### Error Handling
+## Error Handling
 
 All API errors throw typed exceptions:
 
 ```typescript
-import { CStarError, CStarNotFoundError, CStarValidationError } from '@cstar.help/js';
+import {
+	CStarError,
+	CStarAuthenticationError,
+	CStarRateLimitError,
+	CStarNotFoundError,
+	CStarValidationError
+} from '@cstar.help/js';
 
 try {
 	await cstar.tickets.get('tkt_nonexistent');
@@ -232,15 +336,19 @@ try {
 		console.log('Ticket not found:', err.message);
 	} else if (err instanceof CStarValidationError) {
 		console.log('Invalid param:', err.param);
+	} else if (err instanceof CStarRateLimitError) {
+		console.log('Rate limited, retry after:', err.retryAfter, 'seconds');
+	} else if (err instanceof CStarAuthenticationError) {
+		console.log('Bad API key');
 	} else if (err instanceof CStarError) {
 		console.log('API error:', err.code, err.statusCode);
 	}
 }
 ```
 
-### Idempotency
+## Idempotency
 
-Safely retry create operations:
+Safely retry create/update operations:
 
 ```typescript
 const { data: ticket } = await cstar.tickets.create(