@cstar.help/js 0.12.1 → 0.14.0

package/dist/chat/index.js

@@ -248,37 +248,45 @@ var PresenceManager = class {
 };
 
 // src/chat/errors.ts
+function normalizeChatArgs(arg, fallbackCode) {
+  if (typeof arg === "string") {
+    return { message: arg, code: fallbackCode, statusCode: 0, requestId: null };
+  }
+  return { ...arg, code: arg.code ?? fallbackCode };
+}
 var ChatClientError = class extends Error {
-  constructor(message, opts) {
-    super(message);
+  constructor(arg) {
+    const opts = normalizeChatArgs(arg, "UNKNOWN");
+    super(opts.message);
     this.name = "ChatClientError";
     this.code = opts.code ?? "UNKNOWN";
-    this.statusCode = opts.statusCode;
+    this.statusCode = opts.statusCode ?? 0;
     this.requestId = opts.requestId ?? null;
   }
 };
 var ChatClientAuthError = class extends ChatClientError {
-  constructor(opts) {
-    super(opts.message, opts);
+  constructor(arg) {
+    super(normalizeChatArgs(arg, "AUTH_ERROR"));
     this.name = "ChatClientAuthError";
   }
 };
 var ChatClientRateLimitError = class extends ChatClientError {
-  constructor(opts) {
-    super(opts.message, opts);
+  constructor(arg) {
+    const opts = typeof arg === "string" ? { message: arg, code: "RATE_LIMIT", statusCode: 429, requestId: null, retryAfter: null } : { ...arg, code: arg.code ?? "RATE_LIMIT" };
+    super(opts);
     this.name = "ChatClientRateLimitError";
     this.retryAfter = opts.retryAfter ?? null;
   }
 };
 var ChatClientServerError = class extends ChatClientError {
-  constructor(opts) {
-    super(opts.message, opts);
+  constructor(arg) {
+    super(normalizeChatArgs(arg, "SERVER_ERROR"));
     this.name = "ChatClientServerError";
   }
 };
 var ChatClientNetworkError = class extends ChatClientError {
   constructor(opts) {
-    super(opts.message, { code: "NETWORK_ERROR", statusCode: 0, requestId: null });
+    super({ message: opts.message, code: "NETWORK_ERROR", statusCode: 0, requestId: null });
     this.name = "ChatClientNetworkError";
     this.originalError = opts.originalError;
   }
@@ -294,6 +302,7 @@ var ChatClient = class {
     this.customerId = null;
     this.authMode = null;
     this.pollingTimers = /* @__PURE__ */ new Map();
+    this.stateListeners = /* @__PURE__ */ new Set();
     this.realtimeManager = null;
     this.presenceManager = null;
     this.realtimeReady = false;
@@ -333,6 +342,8 @@ var ChatClient = class {
     this.sessionToken = response.data.sessionToken;
     this.teamId = response.data.teamId;
     this.customerId = response.data.customer.id;
+    this.authMode = "hmac";
+    this.notifyStateChanged();
     if (this.realtimeEnabled) {
       this.realtimeInitPromise = this.initRealtime(
         response.data.customer.id,
@@ -392,11 +403,35 @@ var ChatClient = class {
       this.teamId = params.teamId;
     }
     this.authMode = "session";
+    this.notifyStateChanged();
     if (this.realtimeEnabled) {
       const customerName = params.customerName ?? "";
       this.realtimeInitPromise = this.initRealtimeFromSession(customerName);
     }
   }
+  /**
+   * Subscribe to client state changes (auth mode flips, identify, disconnect).
+   * Fires after the mutation, so listeners reading `getAuthMode()` /
+   * `getCustomerId()` see the new value.
+   *
+   * Returns an unsubscribe function. Closes F-041 — used by `useChat` (React)
+   * and `ChatState` (Svelte) to re-render when consumers mutate the client
+   * outside of the framework wrappers.
+   */
+  subscribe(listener) {
+    this.stateListeners.add(listener);
+    return () => {
+      this.stateListeners.delete(listener);
+    };
+  }
+  notifyStateChanged() {
+    for (const listener of this.stateListeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
   /**
    * Returns the auth mode the client is currently using, or `null` before
    * any authenticated call has resolved one. Useful for branching UI
@@ -459,6 +494,7 @@ var ChatClient = class {
     this.teamId = null;
     this.customerId = null;
     this.authMode = null;
+    this.notifyStateChanged();
   }
   /**
    * @internal Make an authenticated request to the widget API.
@@ -496,7 +532,9 @@ var ChatClient = class {
     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") {
+      const previous = this.authMode;
       this.authMode = headerMode;
+      if (previous !== headerMode) this.notifyStateChanged();
     }
     const requestId = responseHeaders?.get("X-Request-Id") ?? null;
     if (!response.ok) {
@@ -530,7 +568,8 @@ var ChatClient = class {
           requestId
         });
       }
-      throw new ChatClientError(message, {
+      throw new ChatClientError({
+        message,
         code,
         statusCode: response.status,
         requestId
@@ -668,7 +707,7 @@ var TicketsApi = class {
   /** 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.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/conversations", {
       method: "GET",
       query: {
@@ -677,16 +716,22 @@ var TicketsApi = class {
         cursor: params?.cursor
       }
     });
+    const data = response.data.tickets ?? response.data.conversations ?? [];
+    const cursor = response.data.cursor;
+    const hasMore = response.data.hasMore;
     return {
-      tickets: response.data.tickets ?? response.data.conversations ?? [],
-      cursor: response.data.cursor,
-      hasMore: response.data.hasMore
+      data,
+      pagination: { cursor, hasMore },
+      hasMore,
+      // Deprecated aliases — same references, no extra allocation.
+      tickets: data,
+      cursor
     };
   }
   /** Create a new ticket. */
   async create(params) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/tickets", {
       method: "POST",
       body: {
@@ -695,15 +740,25 @@ var TicketsApi = class {
         message: params.message
       }
     });
+    const messages = (response.data.messages ?? []).map((m) => ({
+      id: m.id,
+      content: m.content,
+      sender: m.sender,
+      sender_name: m.sender_name,
+      created_at: m.created_at,
+      read_at: m.read_at,
+      attachments: m.attachments ?? []
+    }));
     return {
       id: response.data.id,
-      ticketNumber: "",
+      ticketNumber: null,
       subject: response.data.subject,
       status: response.data.status,
-      messageCount: params.message ? 1 : 0,
+      messageCount: messages.length,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      closedAt: null
+      closedAt: null,
+      messages
     };
   }
 };
@@ -714,7 +769,7 @@ var ChatCommunityApi = class {
   /** Create a new community post as the identified customer. */
   async createPost(params) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -731,7 +786,7 @@ var ChatCommunityApi = class {
   /** Update a post. Only the original author can edit. */
   async updatePost(postId, params) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -748,7 +803,7 @@ var ChatCommunityApi = class {
   /** Delete a post (soft delete). Only the original author can delete. */
   async deletePost(postId) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "deletePost", postId }
@@ -757,7 +812,7 @@ var ChatCommunityApi = class {
   /** Update a comment. Only the original author can edit. */
   async updateComment(postId, commentId, params) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -773,7 +828,7 @@ var ChatCommunityApi = class {
   /** Delete a comment (soft delete). Only the original author can delete. */
   async deleteComment(postId, commentId) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "deleteComment", postId, commentId }
@@ -782,7 +837,7 @@ var ChatCommunityApi = class {
   /** Toggle vote on a post. Returns new vote state and count. */
   async vote(postId) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "vote", postId }
@@ -792,7 +847,7 @@ var ChatCommunityApi = class {
   /** Add a comment to a post. Supports 1-level nesting via parentCommentId. */
   async comment(postId, params) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -808,7 +863,7 @@ var ChatCommunityApi = class {
   /** Toggle follow on a post. */
   async follow(postId) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "follow", postId }
@@ -818,7 +873,7 @@ var ChatCommunityApi = class {
   /** Check if the current user has voted on a post. */
   async getVoteStatus(postId) {
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "GET",
       query: { teamId, postId }
@@ -829,7 +884,7 @@ var ChatCommunityApi = class {
   async bulkVoteStatus(postIds) {
     if (postIds.length === 0) return {};
     const teamId = this.chat.getTeamId();
-    if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
+    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     const response = await this.chat.fetch("/api/widget/community", {
       method: "GET",
       query: { teamId, postIds: postIds.join(",") }

package/dist/community/index.cjs

@@ -23,6 +23,221 @@ __export(community_exports, {
   CommunityClient: () => CommunityClient
 });
 module.exports = __toCommonJS(community_exports);
+
+// src/errors.ts
+var ErrorType = {
+  AUTHENTICATION_ERROR: "authentication_error",
+  PERMISSION_ERROR: "permission_error",
+  INVALID_REQUEST_ERROR: "invalid_request_error",
+  NOT_FOUND_ERROR: "not_found_error",
+  CONFLICT_ERROR: "conflict_error",
+  RATE_LIMIT_ERROR: "rate_limit_error",
+  FEATURE_NOT_CONFIGURED: "feature_not_configured",
+  API_ERROR: "api_error",
+  SERVER_ERROR: "server_error"
+};
+var DEFAULT_DOC_URL = "https://cstar.help/developers/api/errors";
+function normalizeArgs(messageOrStatus, maybeBody, defaults) {
+  if (typeof messageOrStatus === "string") {
+    return {
+      statusCode: defaults?.code === "rate_limit_error" ? 429 : 0,
+      body: {
+        type: defaults?.type ?? ErrorType.API_ERROR,
+        code: defaults?.code ?? "sdk_error",
+        message: messageOrStatus,
+        doc_url: defaults?.doc_url ?? DEFAULT_DOC_URL,
+        ...defaults?.feature ? { feature: defaults.feature } : {},
+        ...defaults?.enable_url ? { enable_url: defaults.enable_url } : {}
+      }
+    };
+  }
+  return {
+    statusCode: messageOrStatus,
+    body: maybeBody ?? {
+      type: defaults?.type ?? ErrorType.API_ERROR,
+      code: defaults?.code ?? "unknown_error",
+      message: defaults?.message ?? `Request failed with status ${messageOrStatus}`,
+      doc_url: defaults?.doc_url ?? DEFAULT_DOC_URL
+    }
+  };
+}
+var CStarError = class extends Error {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body);
+    super(resolved.message);
+    this.name = "CStarError";
+    this.type = resolved.type;
+    this.code = resolved.code;
+    this.param = resolved.param;
+    this.docUrl = resolved.doc_url;
+    this.requestId = resolved.request_id;
+    this.statusCode = statusCode;
+  }
+};
+var CStarAuthenticationError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.AUTHENTICATION_ERROR,
+      code: "authentication_failed",
+      doc_url: `${DEFAULT_DOC_URL}#authentication-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarAuthenticationError";
+  }
+};
+var CStarRateLimitError = class extends CStarError {
+  constructor(messageOrStatus, body, retryAfter) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.RATE_LIMIT_ERROR,
+      code: "rate_limit_exceeded",
+      doc_url: `${DEFAULT_DOC_URL}#rate-limit-error`
+    });
+    super(statusCode === 0 ? 429 : statusCode, resolved);
+    this.name = "CStarRateLimitError";
+    this.retryAfter = retryAfter ?? 60;
+  }
+};
+var CStarNotFoundError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.NOT_FOUND_ERROR,
+      code: "resource_not_found",
+      doc_url: `${DEFAULT_DOC_URL}#not-found-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarNotFoundError";
+  }
+};
+var CStarValidationError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.INVALID_REQUEST_ERROR,
+      code: "validation_error",
+      doc_url: `${DEFAULT_DOC_URL}#validation-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarValidationError";
+  }
+};
+var CStarPermissionError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.PERMISSION_ERROR,
+      code: "permission_denied",
+      doc_url: `${DEFAULT_DOC_URL}#permission-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarPermissionError";
+  }
+};
+var CStarConflictError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.CONFLICT_ERROR,
+      code: "conflict",
+      doc_url: `${DEFAULT_DOC_URL}#conflict-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarConflictError";
+  }
+};
+var CStarServerError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.SERVER_ERROR,
+      code: "server_error",
+      doc_url: `${DEFAULT_DOC_URL}#server-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarServerError";
+  }
+};
+var CStarFeatureDisabledError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.FEATURE_NOT_CONFIGURED,
+      code: "feature_not_configured",
+      doc_url: `${DEFAULT_DOC_URL}#feature-not-configured`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarFeatureDisabledError";
+    this.feature = resolved.feature ?? "unknown";
+    this.enableUrl = resolved.enable_url ?? "";
+  }
+};
+function parsePublicError(status, body, fallbackMessage) {
+  const obj = body && typeof body === "object" ? body : null;
+  const errVal = obj?.error;
+  let message = fallbackMessage;
+  let structured = null;
+  if (typeof errVal === "string") {
+    message = errVal;
+  } else if (errVal && typeof errVal === "object") {
+    const e = errVal;
+    if (typeof e.message === "string") message = e.message;
+    structured = {
+      type: typeof e.type === "string" ? e.type : ErrorType.API_ERROR,
+      code: typeof e.code === "string" ? e.code : "api_error",
+      message,
+      param: typeof e.param === "string" ? e.param : void 0,
+      doc_url: typeof e.doc_url === "string" ? e.doc_url : DEFAULT_DOC_URL,
+      request_id: typeof e.request_id === "string" ? e.request_id : void 0,
+      feature: typeof e.feature === "string" ? e.feature : void 0,
+      enable_url: typeof e.enable_url === "string" ? e.enable_url : void 0
+    };
+  } else if (typeof obj?.message === "string") {
+    message = obj.message;
+  }
+  const errorBody = structured ?? {
+    type: ErrorType.API_ERROR,
+    code: status >= 500 ? "server_error" : "request_failed",
+    message,
+    doc_url: DEFAULT_DOC_URL
+  };
+  return parseError(status, { error: errorBody });
+}
+var STATUS_TO_CLASS = {
+  400: CStarValidationError,
+  401: CStarAuthenticationError,
+  403: CStarPermissionError,
+  404: CStarNotFoundError,
+  409: CStarConflictError,
+  422: CStarValidationError,
+  429: CStarRateLimitError
+};
+var TYPE_TO_CLASS = {
+  [ErrorType.AUTHENTICATION_ERROR]: CStarAuthenticationError,
+  [ErrorType.PERMISSION_ERROR]: CStarPermissionError,
+  [ErrorType.RATE_LIMIT_ERROR]: CStarRateLimitError,
+  [ErrorType.NOT_FOUND_ERROR]: CStarNotFoundError,
+  [ErrorType.INVALID_REQUEST_ERROR]: CStarValidationError,
+  [ErrorType.CONFLICT_ERROR]: CStarConflictError,
+  [ErrorType.SERVER_ERROR]: CStarServerError,
+  [ErrorType.FEATURE_NOT_CONFIGURED]: CStarFeatureDisabledError
+};
+function parseError(statusCode, body, retryAfter) {
+  const errorBody = body?.error ?? {
+    type: ErrorType.API_ERROR,
+    code: "unknown_error",
+    message: `Request failed with status ${statusCode}`,
+    doc_url: DEFAULT_DOC_URL
+  };
+  if (statusCode === 429) {
+    return new CStarRateLimitError(statusCode, errorBody, retryAfter ?? 60);
+  }
+  const StatusCls = STATUS_TO_CLASS[statusCode];
+  if (StatusCls) {
+    return new StatusCls(statusCode, errorBody);
+  }
+  const TypeCls = TYPE_TO_CLASS[errorBody.type];
+  if (TypeCls) {
+    return new TypeCls(statusCode, errorBody);
+  }
+  if (statusCode >= 500) return new CStarServerError(statusCode, errorBody);
+  return new CStarError(statusCode, errorBody);
+}
+
+// src/community/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var CommunityClient = class {
   constructor(config) {
@@ -30,6 +245,13 @@ var CommunityClient = class {
     this.teamId = null;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.teamSlug = config.teamSlug;
+    this.publishableKey = config.publishableKey ?? null;
+    this.mode = this.publishableKey?.startsWith("pk_test_") ? "test" : "live";
+    if (this.publishableKey && !/^pk_(test|live)_/.test(this.publishableKey)) {
+      throw new Error(
+        "[cStar] CommunityClient: publishableKey must start with `pk_test_` or `pk_live_`. Secret keys (`sk_*`) cannot be used in browser/anonymous contexts."
+      );
+    }
   }
   /**
    * Set a session token from identity verification.
@@ -246,13 +468,13 @@ var CommunityClient = class {
    */
   resolveTeamId() {
     if (this.teamId) return this.teamId;
-    throw new Error(
+    throw new CStarValidationError(
       "Team ID is required for authenticated operations. Pass it via setSessionToken(token, teamId) or use ChatClient.identify() which provides it automatically."
     );
   }
   async authenticatedFetch(path, options) {
     if (!this.sessionToken) {
-      throw new Error(
+      throw new CStarValidationError(
         "Session token required. Call setSessionToken() or use ChatClient.identify() first."
       );
     }
@@ -275,9 +497,8 @@ var CommunityClient = class {
       body: options.body ? JSON.stringify(options.body) : void 0
     });
     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);
+      const errorBody = await response.json().catch(() => null);
+      throw parsePublicError(response.status, errorBody, `Community API error: ${response.status}`);
     }
     return response.json();
   }
@@ -291,14 +512,17 @@ var CommunityClient = class {
       const qs = params.toString();
       if (qs) url += `?${qs}`;
     }
+    const headers = { "Content-Type": "application/json" };
+    if (this.publishableKey) {
+      headers["Authorization"] = `Bearer ${this.publishableKey}`;
+    }
     const response = await globalThis.fetch(url, {
       method: "GET",
-      headers: { "Content-Type": "application/json" }
+      headers
     });
     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);
+      const errorBody = await response.json().catch(() => null);
+      throw parsePublicError(response.status, errorBody, `Community API error: ${response.status}`);
     }
     return response.json();
   }

package/dist/community/index.d.cts

@@ -9,6 +9,14 @@ interface CommunityAttachment {
 interface CommunityConfig {
     /** Team slug (e.g., 'acme'). Identifies the community to query. */
     teamSlug: string;
+    /**
+     * Optional publishable key (`pk_test_*` or `pk_live_*`). When provided,
+     * the client switches data scope to match the key's mode (test vs live).
+     * Without a key, defaults to live — backwards-compatible with existing
+     * widget integrations. See `LibraryConfig.publishableKey` for the full
+     * test/live story.
+     */
+    publishableKey?: string;
     /** Override the base URL (defaults to https://www.cstar.help). */
     baseUrl?: string;
 }
@@ -193,6 +201,9 @@ interface CommunityPostDetail {
 declare class CommunityClient {
     private readonly baseUrl;
     private readonly teamSlug;
+    private readonly publishableKey;
+    /** Resolved mode based on the publishable-key prefix (`pk_test_*` => `test`). */
+    readonly mode: 'live' | 'test';
     private sessionToken;
     private teamId;
     constructor(config: CommunityConfig);

package/dist/community/index.d.ts

@@ -9,6 +9,14 @@ interface CommunityAttachment {
 interface CommunityConfig {
     /** Team slug (e.g., 'acme'). Identifies the community to query. */
     teamSlug: string;
+    /**
+     * Optional publishable key (`pk_test_*` or `pk_live_*`). When provided,
+     * the client switches data scope to match the key's mode (test vs live).
+     * Without a key, defaults to live — backwards-compatible with existing
+     * widget integrations. See `LibraryConfig.publishableKey` for the full
+     * test/live story.
+     */
+    publishableKey?: string;
     /** Override the base URL (defaults to https://www.cstar.help). */
     baseUrl?: string;
 }
@@ -193,6 +201,9 @@ interface CommunityPostDetail {
 declare class CommunityClient {
     private readonly baseUrl;
     private readonly teamSlug;
+    private readonly publishableKey;
+    /** Resolved mode based on the publishable-key prefix (`pk_test_*` => `test`). */
+    readonly mode: 'live' | 'test';
     private sessionToken;
     private teamId;
     constructor(config: CommunityConfig);