@cstar.help/js 0.1.0

package/dist/chat/index.d.ts

@@ -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 };

package/dist/chat/index.js

@@ -0,0 +1,213 @@
+// src/chat/index.ts
+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;
+  }
+};
+export {
+  ChatClient
+};