@cstar.help/js 0.3.4 → 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
-- **Four 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.
 
-Build custom chat experiences with identity verification.
+| 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 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,33 +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');
 ```
 
-### Webhook Verification
+---
+
+## 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' });
+
+const topics = await community.topics();
+const { posts } = await community.posts({ topicSlug: 'feature-requests', sort: 'votes' });
+const { post, comments } = await community.post('dark-mode-support');
+```
+
+---
+
+## 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) {
@@ -114,31 +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)`             |
+---
 
-### 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
@@ -147,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');
@@ -175,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(

package/dist/community/index.cjs

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/community/index.ts
+var community_exports = {};
+__export(community_exports, {
+  CommunityClient: () => CommunityClient
+});
+module.exports = __toCommonJS(community_exports);
+var DEFAULT_BASE_URL = "https://www.cstar.help";
+var CommunityClient = class {
+  constructor(config) {
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamSlug = config.teamSlug;
+  }
+  /** List all public community topics. */
+  async topics() {
+    const response = await this.fetch(
+      `/api/community/${this.teamSlug}/topics`
+    );
+    return response.data;
+  }
+  /** List public posts, optionally filtered by topic, status, or sort order. */
+  async posts(params) {
+    const query = {};
+    if (params?.topicSlug) query.topicSlug = params.topicSlug;
+    if (params?.status) query.status = params.status;
+    if (params?.sort) query.sort = params.sort;
+    if (params?.limit) query.limit = String(params.limit);
+    if (params?.offset) query.offset = String(params.offset);
+    const response = await this.fetch(
+      `/api/community/${this.teamSlug}/posts`,
+      query
+    );
+    return { posts: response.data, count: response.count };
+  }
+  /** Get a single post by slug, including all comments. */
+  async post(slug) {
+    const response = await this.fetch(
+      `/api/community/${this.teamSlug}/posts/${slug}`
+    );
+    return response.data;
+  }
+  /**
+   * Full-text search across post titles and bodies.
+   * Returns matching posts with relevance ranking.
+   */
+  async search(query) {
+    return this.fetch(`/api/community/${this.teamSlug}/search`, {
+      q: query
+    });
+  }
+  async fetch(path, query) {
+    let url = `${this.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) params.set(key, value);
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const response = await globalThis.fetch(url, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" }
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ error: { message: "Request failed" } }));
+      const message = typeof errorBody.error === "string" ? errorBody.error : errorBody.error?.message ?? `Community API error: ${response.status}`;
+      throw new Error(message);
+    }
+    return response.json();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CommunityClient
+});

package/dist/community/index.d.cts

@@ -0,0 +1,115 @@
+/** Configuration for the CommunityClient. */
+interface CommunityConfig {
+    /** Team slug (e.g., 'acme'). Identifies the community to query. */
+    teamSlug: string;
+    /** Override the base URL (defaults to https://www.cstar.help). */
+    baseUrl?: string;
+}
+/** A discussion topic/category in the community. */
+interface CommunityTopic {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    icon: string;
+    visibility: 'public' | 'members_only';
+    sort_order: number;
+}
+/** A public community post. */
+interface CommunityPost {
+    id: string;
+    title: string;
+    slug: string;
+    body: string;
+    status: 'open' | 'answered' | 'officially_answered' | 'planned' | 'not_planned' | 'completed' | 'under_review';
+    visibility: 'public' | 'members_only';
+    voteCount: number;
+    commentCount: number;
+    isPinned: boolean;
+    isFeatured: boolean;
+    isLocked: boolean;
+    commentsEnabled: boolean;
+    topicName: string;
+    topicSlug: string;
+    authorName: string;
+    authorAvatar: string;
+    authorBio: string;
+    authorPostCount: number;
+    authorCommentCount: number;
+    isTeamMember: boolean;
+    lastActivityAt: string;
+    createdAt: string;
+}
+/** A comment on a community post. */
+interface CommunityComment {
+    id: string;
+    body: string;
+    isOfficial: boolean;
+    voteScore: number;
+    parentCommentId: string | null;
+    authorName: string;
+    authorAvatar: string;
+    authorBio: string;
+    authorPostCount: number;
+    authorCommentCount: number;
+    isTeamMember: boolean;
+    createdAt: string;
+}
+/** Parameters for listing posts. */
+interface CommunityPostListParams {
+    /** Filter by topic slug. */
+    topicSlug?: string;
+    /** Filter by status. */
+    status?: string;
+    /** Sort order (default: 'recent'). */
+    sort?: 'recent' | 'votes' | 'comments';
+    /** Max results per page. */
+    limit?: number;
+    /** Pagination offset. */
+    offset?: number;
+}
+/** Search results. */
+interface CommunitySearchResult {
+    data: CommunityPost[];
+    count: number;
+    query: string;
+}
+/** A single post with its comments. */
+interface CommunityPostDetail {
+    post: CommunityPost;
+    comments: CommunityComment[];
+}
+
+/**
+ * Public community client. No authentication required.
+ *
+ * ```typescript
+ * const community = new CommunityClient({ teamSlug: 'acme' });
+ * const topics = await community.topics();
+ * const posts = await community.posts({ topicSlug: 'feedback', sort: 'votes' });
+ * const post = await community.post('my-feature-request');
+ * const results = await community.search('dark mode');
+ * ```
+ */
+declare class CommunityClient {
+    private readonly baseUrl;
+    private readonly teamSlug;
+    constructor(config: CommunityConfig);
+    /** List all public community topics. */
+    topics(): Promise<CommunityTopic[]>;
+    /** List public posts, optionally filtered by topic, status, or sort order. */
+    posts(params?: CommunityPostListParams): Promise<{
+        posts: CommunityPost[];
+        count: number;
+    }>;
+    /** Get a single post by slug, including all comments. */
+    post(slug: string): Promise<CommunityPostDetail>;
+    /**
+     * Full-text search across post titles and bodies.
+     * Returns matching posts with relevance ranking.
+     */
+    search(query: string): Promise<CommunitySearchResult>;
+    private fetch;
+}
+
+export { CommunityClient, type CommunityComment, type CommunityConfig, type CommunityPost, type CommunityPostDetail, type CommunityPostListParams, type CommunitySearchResult, type CommunityTopic };