@cstar.help/js 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+# @cstar.help/js
+
+Official TypeScript SDK for the [cStar](https://cstar.help) customer support platform.
+
+- **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
+- **ESM + CJS** — works everywhere
+
+## Install
+
+```bash
+npm install @cstar.help/js
+```
+
+## Quick Start
+
+### Server-side API Client
+
+Manage tickets, customers, articles, and webhooks with your secret API key.
+
+```typescript
+import { CStarClient } from '@cstar.help/js';
+
+const cstar = new CStarClient({
+  apiKey: 'sk_live_abc123...',
+  teamId: 'tm_your_team_id',
+});
+
+// List open tickets
+const { data: tickets } = await cstar.tickets.list({ status: 'open' });
+
+// Create a ticket
+const { data: ticket } = await cstar.tickets.create({
+  title: 'Help with billing',
+  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)
+
+Build custom chat experiences with identity verification.
+
+```typescript
+import { ChatClient } from '@cstar.help/js/chat';
+
+const chat = new ChatClient({ teamSlug: 'acme' });
+
+// Identify the customer (HMAC signature from your server)
+await chat.identify(
+  { externalId: 'usr_123', email: 'jane@example.com', name: 'Jane', timestamp: Date.now() / 1000 },
+  hmacSignature
+);
+
+// List conversations
+const { conversations } = await chat.conversations.list();
+
+// Send a message
+await chat.messages.send('tkt_abc123', 'Thanks for the help!');
+
+// Subscribe to new messages (polling)
+const unsubscribe = chat.onMessage('tkt_abc123', (message) => {
+  console.log(`${message.sender_name}: ${message.content}`);
+});
+
+// Clean up
+chat.disconnect();
+```
+
+### 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
+
+Verify incoming webhook signatures on your server.
+
+```typescript
+import { constructEvent } from '@cstar.help/js/webhook';
+
+// In your webhook handler (Express, Hono, etc.)
+const event = constructEvent(rawBody, signature, 'whsec_your_secret');
+
+switch (event.type) {
+  case 'ticket.created':
+    console.log('New ticket:', event.data.title);
+    break;
+  case 'customer.created':
+    console.log('New customer:', event.data.email);
+    break;
+}
+```
+
+For edge environments (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
+
+```typescript
+const cstar = new CStarClient({
+  apiKey: 'sk_live_...',    // Required — secret or publishable key
+  teamId: 'tm_...',         // Required — your team ID
+  baseUrl: 'https://...',   // Optional — defaults to https://app.cstar.help
+  version: '2026-03-01',    // Optional — API version header
+  maxRetries: 3,            // Optional — retry attempts for 5xx/429
+  timeout: 30000,           // Optional — request timeout in ms
+});
+```
+
+### 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
+```
+
+### Error Handling
+
+All API errors throw typed exceptions:
+
+```typescript
+import { CStarError, CStarNotFoundError, CStarValidationError } from '@cstar.help/js';
+
+try {
+  await cstar.tickets.get('tkt_nonexistent');
+} catch (err) {
+  if (err instanceof CStarNotFoundError) {
+    console.log('Ticket not found:', err.message);
+  } else if (err instanceof CStarValidationError) {
+    console.log('Invalid param:', err.param);
+  } else if (err instanceof CStarError) {
+    console.log('API error:', err.code, err.statusCode);
+  }
+}
+```
+
+### Idempotency
+
+Safely retry create operations:
+
+```typescript
+const { data: ticket } = await cstar.tickets.create(
+  { title: 'Billing issue', customerId: 'cus_abc' },
+  { idempotencyKey: 'create-billing-issue-usr123' }
+);
+```
+
+## Requirements
+
+- Node.js 18+ (for native `fetch` and `AbortSignal.timeout`)
+- TypeScript 5.0+ (for type definitions)
+
+## License
+
+MIT

package/dist/chat/index.cjs

@@ -0,0 +1,238 @@
+"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/chat/index.ts
+var chat_exports = {};
+__export(chat_exports, {
+  ChatClient: () => ChatClient
+});
+module.exports = __toCommonJS(chat_exports);
+var DEFAULT_BASE_URL = "https://app.cstar.help";
+var DEFAULT_POLLING_INTERVAL = 3e3;
+var ChatClient = class {
+  constructor(config) {
+    this.sessionToken = null;
+    this.teamId = null;
+    this.pollingTimers = /* @__PURE__ */ new Map();
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamSlug = config.teamSlug;
+    this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+    this.conversations = new ConversationsApi(this);
+    this.messages = new MessagesApi(this);
+  }
+  /**
+   * Identify a customer using HMAC signature verification.
+   * Must be called before accessing conversations or messages.
+   *
+   * @param customer - Customer identity fields
+   * @param signature - HMAC-SHA256 hex signature of the signed fields
+   * @param testMode - Whether to use test mode (relaxed timestamp validation)
+   */
+  async identify(customer, signature, testMode = false) {
+    const response = await this.fetch(
+      "/api/widget/verify-identity",
+      {
+        method: "POST",
+        body: {
+          teamSlug: this.teamSlug,
+          testMode,
+          customer,
+          signature
+        }
+      }
+    );
+    this.sessionToken = response.data.sessionToken;
+    return response.data;
+  }
+  /**
+   * Subscribe to new messages on a conversation.
+   * Falls back to polling when Supabase Realtime is not available.
+   *
+   * @returns Unsubscribe function
+   */
+  onMessage(ticketId, callback) {
+    let lastMessageId = null;
+    const poll = async () => {
+      try {
+        const messages = await this.messages.list(ticketId);
+        if (messages.length > 0) {
+          const latest = messages[messages.length - 1];
+          if (lastMessageId && latest.id !== lastMessageId) {
+            const lastIdx = messages.findIndex((m) => m.id === lastMessageId);
+            const newMessages = lastIdx >= 0 ? messages.slice(lastIdx + 1) : [latest];
+            for (const msg of newMessages) {
+              callback(msg);
+            }
+          }
+          lastMessageId = latest.id;
+        }
+      } catch {
+      }
+    };
+    poll();
+    const timer = setInterval(poll, this.pollingInterval);
+    this.pollingTimers.set(ticketId, timer);
+    return () => {
+      clearInterval(timer);
+      this.pollingTimers.delete(ticketId);
+    };
+  }
+  /**
+   * Subscribe to typing indicator events.
+   * Requires Supabase Realtime — returns a no-op if unavailable.
+   *
+   * @returns Unsubscribe function
+   */
+  onTyping(_ticketId, _callback) {
+    return () => {
+    };
+  }
+  /** Disconnect all subscriptions and clean up. */
+  disconnect() {
+    for (const timer of this.pollingTimers.values()) {
+      clearInterval(timer);
+    }
+    this.pollingTimers.clear();
+    this.sessionToken = null;
+  }
+  /** @internal Make an authenticated request to the widget API. */
+  async fetch(path, options) {
+    const url = this.buildUrl(path, options.query);
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.sessionToken) {
+      headers["Authorization"] = `Bearer ${this.sessionToken}`;
+    }
+    const response = await globalThis.fetch(url, {
+      method: options.method,
+      headers,
+      body: options.body ? JSON.stringify(options.body) : void 0
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ error: { message: "Request failed" } }));
+      throw new Error(errorBody.error?.message ?? `Widget API error: ${response.status}`);
+    }
+    return response.json();
+  }
+  /** @internal Get the stored team ID for requests that need it. */
+  getTeamId() {
+    return this.teamId;
+  }
+  /** @internal Set team ID from identify response or other source. */
+  setTeamId(teamId) {
+    this.teamId = teamId;
+  }
+  buildUrl(path, query) {
+    const base = `${this.baseUrl}${path}`;
+    if (!query) return base;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) params.set(key, value);
+    }
+    const qs = params.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+};
+var ConversationsApi = class {
+  constructor(chat) {
+    this.chat = chat;
+  }
+  /** List conversations for the identified customer. */
+  async list(params) {
+    const teamId = this.chat.getTeamId();
+    const response = await this.chat.fetch(
+      "/api/widget/conversations",
+      {
+        method: "GET",
+        query: {
+          teamId: teamId ?? void 0,
+          limit: params?.limit?.toString(),
+          cursor: params?.cursor
+        }
+      }
+    );
+    return response.data;
+  }
+  /** Create a new conversation (ticket). */
+  async create(params) {
+    const teamId = this.chat.getTeamId();
+    const response = await this.chat.fetch(
+      "/api/widget/tickets",
+      {
+        method: "POST",
+        body: {
+          teamId,
+          subject: params.subject,
+          message: params.message
+        }
+      }
+    );
+    return {
+      id: response.data.id,
+      ticketNumber: "",
+      subject: response.data.subject,
+      status: response.data.status,
+      messageCount: params.message ? 1 : 0,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      closedAt: null
+    };
+  }
+};
+var MessagesApi = class {
+  constructor(chat) {
+    this.chat = chat;
+  }
+  /** List messages for a conversation. */
+  async list(ticketId) {
+    const teamId = this.chat.getTeamId();
+    const response = await this.chat.fetch(
+      "/api/widget/messages",
+      {
+        method: "GET",
+        query: {
+          teamId: teamId ?? void 0,
+          ticketId
+        }
+      }
+    );
+    return response.data.messages;
+  }
+  /** Send a message to a conversation. */
+  async send(ticketId, content) {
+    const teamId = this.chat.getTeamId();
+    const response = await this.chat.fetch(
+      "/api/widget/messages",
+      {
+        method: "POST",
+        body: {
+          teamId,
+          ticketId,
+          content
+        }
+      }
+    );
+    return response.data.message;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ChatClient
+});

package/dist/chat/index.d.cts

@@ -0,0 +1,172 @@
+/** Configuration for the ChatClient. */
+interface ChatConfig {
+    /** Team slug (e.g., 'acme'). Used to identify the team. */
+    teamSlug: string;
+    /** Override the base URL (defaults to https://app.cstar.help). */
+    baseUrl?: string;
+    /** Supabase project URL for realtime subscriptions (optional). */
+    supabaseUrl?: string;
+    /** Supabase anon key for realtime subscriptions (optional). */
+    supabaseAnonKey?: string;
+    /** Polling interval in ms when Supabase Realtime is not available (defaults to 3000). */
+    pollingInterval?: number;
+}
+/** Parameters for identifying a customer via HMAC signature verification. */
+interface IdentifyParams {
+    /** Customer ID from your system. */
+    externalId: string;
+    /** Customer email address. */
+    email: string;
+    /** Customer display name. */
+    name?: string;
+    /** Avatar URL (not included in signature). */
+    avatarUrl?: string;
+    /** Custom metadata (not included in signature). */
+    metadata?: Record<string, {
+        value: string;
+        agentVisible: boolean;
+    }>;
+    /** Unix timestamp (seconds). Used for replay protection. */
+    timestamp: number;
+}
+/** Identity verification response. */
+interface IdentifyResult {
+    verified: true;
+    customer: {
+        id: string;
+        externalId: string;
+        email: string;
+        name: string;
+    };
+    sessionToken: string;
+    expiresAt: string;
+}
+/** A customer conversation (maps to a ticket). */
+interface Conversation {
+    id: string;
+    ticketNumber: string;
+    subject: string;
+    status: string;
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+    closedAt: string | null;
+}
+/** Paginated conversation list response. */
+interface ConversationListResponse {
+    conversations: Conversation[];
+    cursor: string | null;
+    hasMore: boolean;
+}
+/** A message in a conversation. */
+interface WidgetMessage {
+    id: string;
+    content: string;
+    sender: 'customer' | 'agent';
+    sender_name: string;
+    created_at: string;
+    read_at: string | null;
+    attachments: unknown[];
+}
+/** Parameters for listing conversations. */
+interface ConversationListParams {
+    limit?: number;
+    cursor?: string;
+}
+/** Parameters for creating a new conversation. */
+interface ConversationCreateParams {
+    subject: string;
+    message?: string;
+}
+/** Typing indicator payload from realtime subscription. */
+interface TypingPayload {
+    agent_id: string;
+    agent_name: string;
+    is_typing: boolean;
+}
+/** Callback for message events. */
+type MessageCallback = (message: WidgetMessage) => void;
+/** Callback for typing indicator events. */
+type TypingCallback = (payload: TypingPayload) => void;
+
+/**
+ * Customer-facing chat client for the cStar widget API.
+ *
+ * ```typescript
+ * const chat = new ChatClient({ teamSlug: 'acme' });
+ * await chat.identify(
+ *   { externalId: 'usr_123', email: 'jane@co.com', name: 'Jane', timestamp: Date.now() / 1000 },
+ *   'hmac_signature_hex'
+ * );
+ * const { conversations } = await chat.conversations.list();
+ * ```
+ */
+declare class ChatClient {
+    private readonly baseUrl;
+    private readonly teamSlug;
+    private readonly pollingInterval;
+    private sessionToken;
+    private teamId;
+    private pollingTimers;
+    /** Sub-resource for managing conversations. */
+    readonly conversations: ConversationsApi;
+    /** Sub-resource for managing messages. */
+    readonly messages: MessagesApi;
+    constructor(config: ChatConfig);
+    /**
+     * Identify a customer using HMAC signature verification.
+     * Must be called before accessing conversations or messages.
+     *
+     * @param customer - Customer identity fields
+     * @param signature - HMAC-SHA256 hex signature of the signed fields
+     * @param testMode - Whether to use test mode (relaxed timestamp validation)
+     */
+    identify(customer: IdentifyParams, signature: string, testMode?: boolean): Promise<IdentifyResult>;
+    /**
+     * Subscribe to new messages on a conversation.
+     * Falls back to polling when Supabase Realtime is not available.
+     *
+     * @returns Unsubscribe function
+     */
+    onMessage(ticketId: string, callback: MessageCallback): () => void;
+    /**
+     * Subscribe to typing indicator events.
+     * Requires Supabase Realtime — returns a no-op if unavailable.
+     *
+     * @returns Unsubscribe function
+     */
+    onTyping(_ticketId: string, _callback: TypingCallback): () => void;
+    /** Disconnect all subscriptions and clean up. */
+    disconnect(): void;
+    /** @internal Make an authenticated request to the widget API. */
+    fetch<T>(path: string, options: {
+        method: string;
+        body?: unknown;
+        query?: Record<string, string | undefined>;
+    }): Promise<T>;
+    /** @internal Get the stored team ID for requests that need it. */
+    getTeamId(): string | null;
+    /** @internal Set team ID from identify response or other source. */
+    setTeamId(teamId: string): void;
+    private buildUrl;
+}
+/** Conversations sub-resource on ChatClient. */
+declare class ConversationsApi {
+    private readonly chat;
+    constructor(chat: ChatClient);
+    /** List conversations for the identified customer. */
+    list(params?: ConversationListParams): Promise<ConversationListResponse>;
+    /** Create a new conversation (ticket). */
+    create(params: ConversationCreateParams): Promise<Conversation>;
+}
+/** Messages sub-resource on ChatClient. */
+declare class MessagesApi {
+    private readonly chat;
+    constructor(chat: ChatClient);
+    /** List messages for a conversation. */
+    list(ticketId: string): Promise<WidgetMessage[]>;
+    /** Send a message to a conversation. */
+    send(ticketId: string, content: string): Promise<WidgetMessage>;
+}
+
+export { ChatClient, type ChatConfig, type Conversation, type ConversationCreateParams, type ConversationListParams, type ConversationListResponse, type IdentifyParams, type IdentifyResult, type MessageCallback, type TypingCallback, type WidgetMessage };