@cstar.help/js 0.10.3 → 0.12.0

package/dist/chat/index.js

@@ -9,8 +9,8 @@ var RealtimeManager = class {
     this.options = options;
   }
   /**
-   * Initialize the Supabase client and authenticate with a realtime token.
-   * Returns true if successful, false if @supabase/supabase-js is unavailable.
+   * Initialize the realtime client and authenticate with a token.
+   * Returns true if successful, false if the realtime runtime is unavailable.
    */
   init() {
     if (this.initPromise) return this.initPromise;
@@ -19,15 +19,15 @@ var RealtimeManager = class {
   }
   async doInit() {
     try {
+      const tokenData = await this.options.fetchToken();
       const { createClient } = await import(
         /* webpackIgnore: true */
         "@supabase/supabase-js"
       );
-      this.client = createClient(this.options.supabaseUrl, this.options.supabaseAnonKey, {
+      this.client = createClient(tokenData.realtimeUrl, tokenData.realtimeKey, {
         auth: { persistSession: false, autoRefreshToken: false },
         realtime: { params: { eventsPerSecond: 10 } }
       });
-      const tokenData = await this.options.fetchToken();
       this.setToken(tokenData);
       return true;
     } catch {
@@ -85,7 +85,8 @@ var RealtimeManager = class {
           sender_name: row.sender_name ?? "",
           created_at: row.created_at,
           read_at: row.read_at ?? null,
-          attachments: row.attachments ?? []
+          attachments: row.attachments ?? [],
+          payload: row.payload ?? null
         };
         callback(message);
       }
@@ -93,10 +94,18 @@ var RealtimeManager = class {
     this.channels.set(channelName, channel);
     return () => this.removeChannel(channelName);
   }
-  /** Get the underlying Supabase client (for sharing with PresenceManager). */
+  /** Get the underlying realtime client (for sharing with PresenceManager). */
   getClient() {
     return this.client;
   }
+  /**
+   * The current Supabase JWT (set by init/refresh). Returned so callers can
+   * decode the `sub` claim to learn the customerId — required after a
+   * session-mode login where the SDK doesn't have customerId at hand.
+   */
+  getCurrentToken() {
+    return this.currentToken;
+  }
   /** Whether the realtime manager is initialized and has a token. */
   get isReady() {
     return this.client !== null && this.currentToken !== null;
@@ -135,7 +144,7 @@ var PresenceManager = class {
     this.typingClearTimers = /* @__PURE__ */ new Map();
     this.options = options;
   }
-  /** Set the Supabase client (shared from RealtimeManager). */
+  /** Set the realtime client (shared from RealtimeManager). */
   setClient(client) {
     this.client = client;
   }
@@ -238,6 +247,43 @@ var PresenceManager = class {
   }
 };
 
+// src/chat/errors.ts
+var ChatClientError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    this.name = "ChatClientError";
+    this.code = opts.code ?? "UNKNOWN";
+    this.statusCode = opts.statusCode;
+    this.requestId = opts.requestId ?? null;
+  }
+};
+var ChatClientAuthError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, opts);
+    this.name = "ChatClientAuthError";
+  }
+};
+var ChatClientRateLimitError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, opts);
+    this.name = "ChatClientRateLimitError";
+    this.retryAfter = opts.retryAfter ?? null;
+  }
+};
+var ChatClientServerError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, opts);
+    this.name = "ChatClientServerError";
+  }
+};
+var ChatClientNetworkError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, { code: "NETWORK_ERROR", statusCode: 0, requestId: null });
+    this.name = "ChatClientNetworkError";
+    this.originalError = opts.originalError;
+  }
+};
+
 // src/chat/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_POLLING_INTERVAL = 3e3;
@@ -246,6 +292,7 @@ var ChatClient = class {
     this.sessionToken = null;
     this.teamId = null;
     this.customerId = null;
+    this.authMode = null;
     this.pollingTimers = /* @__PURE__ */ new Map();
     this.realtimeManager = null;
     this.presenceManager = null;
@@ -254,18 +301,17 @@ var ChatClient = class {
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.teamSlug = config.teamSlug;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
-    this.supabaseUrl = config.supabaseUrl;
-    this.supabaseAnonKey = config.supabaseAnonKey;
-    this.conversations = new ConversationsApi(this);
+    this.realtimeEnabled = config.realtime !== false;
+    this.tickets = new TicketsApi(this);
     this.messages = new MessagesApi(this);
     this.community = new ChatCommunityApi(this);
   }
   /**
    * Identify a customer using HMAC signature verification.
-   * Must be called before accessing conversations or messages.
+   * Must be called before accessing tickets or messages.
    *
-   * If `supabaseUrl` and `supabaseAnonKey` were provided in the config,
-   * this will also initialize real-time subscriptions (non-blocking).
+   * Real-time subscriptions are initialized automatically (non-blocking)
+   * unless `realtime: false` was passed in config.
    *
    * @param customer - Customer identity fields
    * @param signature - HMAC-SHA256 hex signature of the signed fields
@@ -287,7 +333,7 @@ var ChatClient = class {
     this.sessionToken = response.data.sessionToken;
     this.teamId = response.data.teamId;
     this.customerId = response.data.customer.id;
-    if (this.supabaseUrl && this.supabaseAnonKey) {
+    if (this.realtimeEnabled) {
       this.realtimeInitPromise = this.initRealtime(
         response.data.customer.id,
         response.data.customer.name || customer.name || customer.email
@@ -296,8 +342,72 @@ var ChatClient = class {
     return response.data;
   }
   /**
-   * Subscribe to new messages on a conversation.
-   * Uses Supabase Realtime (Postgres Changes) when available, falls back to polling.
+   * Sign in with cStar's hosted password auth. The SDK keeps the resulting
+   * Supabase access token and uses it as Bearer for every subsequent call.
+   * Real-time bootstraps automatically (same flow as `identify()`).
+   *
+   * Use this when your customers don't have a session in your app and you
+   * want cStar to handle login. For the case where your app already has a
+   * Supabase session, use `loginWithSession({ accessToken })` instead.
+   */
+  async loginWithCredentials(params) {
+    const teamId = await this.resolveTeamIdFromSlug();
+    const response = await this.fetch("/api/widget/auth/login", {
+      method: "POST",
+      body: { email: params.email, password: params.password, teamId }
+    });
+    if (!response.accessToken) {
+      throw new ChatClientAuthError({
+        message: "Login succeeded but no session was issued",
+        code: "NO_SESSION",
+        statusCode: 200,
+        requestId: null
+      });
+    }
+    await this.loginWithSession({
+      accessToken: response.accessToken,
+      teamId,
+      customerName: response.customer.name ?? response.customer.email
+    });
+    return {
+      customer: {
+        id: this.customerId ?? response.customer.id,
+        email: response.customer.email,
+        name: response.customer.name
+      },
+      teamId
+    };
+  }
+  /**
+   * Use an existing Supabase access token for widget calls. Skip the cStar
+   * login flow entirely; the SDK uses the supplied token as Bearer and
+   * bootstraps real-time the same way `identify()` does.
+   *
+   * The widget API verifies the token via the `widget-session` strategy on
+   * every request — there is no client-side validation here.
+   */
+  async loginWithSession(params) {
+    this.sessionToken = params.accessToken;
+    if (params.teamId) {
+      this.teamId = params.teamId;
+    }
+    this.authMode = "session";
+    if (this.realtimeEnabled) {
+      const customerName = params.customerName ?? "";
+      this.realtimeInitPromise = this.initRealtimeFromSession(customerName);
+    }
+  }
+  /**
+   * Returns the auth mode the client is currently using, or `null` before
+   * any authenticated call has resolved one. Useful for branching UI
+   * (e.g. to show a "Sign out" button only in session mode).
+   */
+  getAuthMode() {
+    return this.authMode;
+  }
+  /**
+   * Subscribe to new messages on a ticket.
+   * Uses real-time delivery when available, falls back to polling.
    *
    * @returns Unsubscribe function
    */
@@ -309,7 +419,7 @@ var ChatClient = class {
   }
   /**
    * Subscribe to typing indicator events.
-   * Requires Supabase Realtime — returns a no-op if unavailable.
+   * Requires real-time — returns a no-op when unavailable.
    *
    * @returns Unsubscribe function
    */
@@ -321,8 +431,8 @@ var ChatClient = class {
     };
   }
   /**
-   * Send a customer typing indicator (requires realtime).
-   * No-op if realtime is not available.
+   * Send a customer typing indicator (requires real-time).
+   * No-op when real-time is unavailable.
    */
   async sendTyping(ticketId, isTyping) {
     if (this.presenceManager) {
@@ -348,8 +458,20 @@ var ChatClient = class {
     this.sessionToken = null;
     this.teamId = null;
     this.customerId = null;
+    this.authMode = null;
   }
-  /** @internal Make an authenticated request to the widget API. */
+  /**
+   * @internal Make an authenticated request to the widget API.
+   *
+   * On any non-2xx response, throws a typed subclass of `ChatClientError`
+   * (`ChatClientAuthError`, `ChatClientRateLimitError`, etc.) so consumers
+   * can branch on error class instead of parsing message strings.
+   *
+   * On the way out, reads the `X-Cstar-Auth-Mode` response header (set by
+   * widgetHandler on every response) and caches it on the client. After
+   * the first authenticated round-trip, `getAuthMode()` returns the
+   * server-confirmed mode.
+   */
   async fetch(path, options) {
     const url = this.buildUrl(path, options.query);
     const headers = {
@@ -358,17 +480,104 @@ var ChatClient = class {
     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
-    });
+    let response;
+    try {
+      response = await globalThis.fetch(url, {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : void 0
+      });
+    } catch (networkErr) {
+      throw new ChatClientNetworkError({
+        message: networkErr instanceof Error ? networkErr.message : "Network request failed",
+        originalError: networkErr
+      });
+    }
+    const responseHeaders = response.headers && typeof response.headers.get === "function" ? response.headers : null;
+    const headerMode = responseHeaders?.get("X-Cstar-Auth-Mode") ?? null;
+    if (headerMode === "hmac" || headerMode === "session") {
+      this.authMode = headerMode;
+    }
+    const requestId = responseHeaders?.get("X-Request-Id") ?? null;
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ error: { message: "Request failed" } }));
-      throw new Error(errorBody.error?.message ?? `Widget API error: ${response.status}`);
+      const errorBody = await response.json().catch(() => ({ error: { code: "UNKNOWN", message: "Request failed" } }));
+      const code = errorBody.error?.code ?? "UNKNOWN";
+      const message = errorBody.error?.message ?? `Widget API error: ${response.status}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new ChatClientAuthError({
+          message,
+          code,
+          statusCode: response.status,
+          requestId
+        });
+      }
+      if (response.status === 429) {
+        const retryAfterHeader = responseHeaders?.get("Retry-After") ?? null;
+        const retryAfter = retryAfterHeader ? parseInt(retryAfterHeader, 10) : null;
+        throw new ChatClientRateLimitError({
+          message,
+          code,
+          statusCode: response.status,
+          requestId,
+          retryAfter: Number.isFinite(retryAfter ?? NaN) ? retryAfter : null
+        });
+      }
+      if (response.status >= 500) {
+        throw new ChatClientServerError({
+          message,
+          code,
+          statusCode: response.status,
+          requestId
+        });
+      }
+      throw new ChatClientError(message, {
+        code,
+        statusCode: response.status,
+        requestId
+      });
     }
     return response.json();
   }
+  /**
+   * Look up the team UUID from the configured `teamSlug`. Used by
+   * `loginWithCredentials`. HMAC integrators (`identify()`) never hit
+   * this path — verify-identity accepts the slug directly.
+   *
+   * @internal
+   */
+  async resolveTeamIdFromSlug() {
+    const response = await this.fetch(
+      "/api/widget/team-by-slug",
+      {
+        method: "GET",
+        query: { teamSlug: this.teamSlug }
+      }
+    );
+    return response.data.teamId;
+  }
+  /** @internal Bootstrap realtime from a session login (no precomputed customerId). */
+  async initRealtimeFromSession(customerName) {
+    try {
+      this.realtimeManager = new RealtimeManager({
+        fetchToken: () => this.fetchRealtimeToken()
+      });
+      const ready = await this.realtimeManager.init();
+      if (!ready) return;
+      this.realtimeReady = true;
+      const token = this.realtimeManager.getCurrentToken();
+      const customerId = token ? decodeJwtSub(token) : null;
+      if (customerId) {
+        this.customerId = customerId;
+        this.presenceManager = new PresenceManager({ customerId, customerName });
+        const client = this.realtimeManager.getClient();
+        if (client) {
+          this.presenceManager.setClient(client);
+        }
+      }
+    } catch {
+      this.realtimeReady = false;
+    }
+  }
   /** @internal Get the stored team ID for requests that need it. */
   getTeamId() {
     return this.teamId;
@@ -386,8 +595,6 @@ var ChatClient = class {
   async initRealtime(customerId, customerName) {
     try {
       this.realtimeManager = new RealtimeManager({
-        supabaseUrl: this.supabaseUrl,
-        supabaseAnonKey: this.supabaseAnonKey,
         fetchToken: () => this.fetchRealtimeToken()
       });
       const ready = await this.realtimeManager.init();
@@ -454,28 +661,29 @@ var ChatClient = class {
     return qs ? `${base}?${qs}` : base;
   }
 };
-var ConversationsApi = class {
+var TicketsApi = class {
   constructor(chat) {
     this.chat = chat;
   }
-  /** List conversations for the identified customer. */
+  /** List tickets for the identified customer. */
   async list(params) {
     const teamId = this.chat.getTeamId();
     if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
-    const response = await this.chat.fetch(
-      "/api/widget/conversations",
-      {
-        method: "GET",
-        query: {
-          teamId,
-          limit: params?.limit?.toString(),
-          cursor: params?.cursor
-        }
+    const response = await this.chat.fetch("/api/widget/conversations", {
+      method: "GET",
+      query: {
+        teamId,
+        limit: params?.limit?.toString(),
+        cursor: params?.cursor
       }
-    );
-    return response.data;
+    });
+    return {
+      tickets: response.data.tickets ?? response.data.conversations ?? [],
+      cursor: response.data.cursor,
+      hasMore: response.data.hasMore
+    };
   }
-  /** Create a new conversation (ticket). */
+  /** Create a new ticket. */
   async create(params) {
     const teamId = this.chat.getTeamId();
     if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
@@ -633,7 +841,7 @@ var MessagesApi = class {
   constructor(chat) {
     this.chat = chat;
   }
-  /** List messages for a conversation. */
+  /** List messages for a ticket. */
   async list(ticketId) {
     const teamId = this.chat.getTeamId();
     const response = await this.chat.fetch(
@@ -648,7 +856,7 @@ var MessagesApi = class {
     );
     return response.data.messages;
   }
-  /** Send a message to a conversation. */
+  /** Send a message to a ticket. */
   async send(ticketId, content) {
     const teamId = this.chat.getTeamId();
     const response = await this.chat.fetch(
@@ -665,6 +873,25 @@ var MessagesApi = class {
     return response.data.message;
   }
 };
+function decodeJwtSub(jwt) {
+  try {
+    const parts = jwt.split(".");
+    if (parts.length !== 3) return null;
+    const payloadB64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = payloadB64 + "=".repeat((4 - payloadB64.length % 4) % 4);
+    const payload = JSON.parse(
+      typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("utf-8")
+    );
+    return typeof payload.sub === "string" ? payload.sub : null;
+  } catch {
+    return null;
+  }
+}
 export {
-  ChatClient
+  ChatClient,
+  ChatClientAuthError,
+  ChatClientError,
+  ChatClientNetworkError,
+  ChatClientRateLimitError,
+  ChatClientServerError
 };

package/dist/index.cjs

@@ -140,6 +140,16 @@ var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_TIMEOUT = 3e4;
 var HttpClient = class {
   constructor(config) {
+    if (!config || typeof config.apiKey !== "string" || config.apiKey.length === 0) {
+      throw new Error(
+        "[cStar] CStarClient: apiKey is required. Pass a secret key (sk_live_... / sk_test_...) or a publishable key (pk_live_... / pk_test_...). See https://cstar.help/developers/quickstart"
+      );
+    }
+    if (typeof config.teamId !== "string" || config.teamId.length === 0) {
+      throw new Error(
+        "[cStar] CStarClient: teamId is required. Find your team ID in Settings \u2192 General or via `cstar status`."
+      );
+    }
     this.config = {
       apiKey: config.apiKey,
       teamId: config.teamId,
@@ -1956,10 +1966,12 @@ var GameResource = class {
   subscribeLeaderboard(realtime, params) {
     const fetchFn = async () => {
       const res = await this.leaderboard(params);
+      const envelope = res.data;
+      const entries = Array.isArray(envelope) ? envelope : envelope?.entries ?? [];
       return {
         success: true,
-        data: res.data,
-        pagination: { total: res.data.length, page: 1, pageSize: 100, hasMore: false },
+        data: entries,
+        pagination: { total: entries.length, page: 1, pageSize: 100, hasMore: false },
         meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
       };
     };