@cstar.help/js 0.12.1 → 0.14.0

package/dist/library/index.js

@@ -1,3 +1,216 @@
+// 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/library/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var LibraryClient = class {
@@ -5,6 +218,13 @@ var LibraryClient = class {
     this.resolvedTeamId = 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] LibraryClient: publishableKey must start with `pk_test_` or `pk_live_`. Secret keys (`sk_*`) cannot be used in browser/anonymous contexts."
+      );
+    }
   }
   /** List all public categories with article counts. */
   async categories() {
@@ -54,13 +274,19 @@ var LibraryClient = class {
    */
   async recordView(slug) {
     const url = `${this.baseUrl}/api/library/${this.teamSlug}/articles/${slug}/view`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.publishableKey) headers["Authorization"] = `Bearer ${this.publishableKey}`;
     const response = await globalThis.fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" }
+      headers
     });
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ error: "Request failed" }));
-      throw new Error(errorBody.error ?? `View tracking failed: ${response.status}`);
+      const errorBody = await response.json().catch(() => null);
+      throw parsePublicError(
+        response.status,
+        errorBody,
+        `View tracking failed: ${response.status}`
+      );
     }
     const body = await response.json();
     return { viewCount: body.viewCount };
@@ -82,14 +308,27 @@ var LibraryClient = class {
    */
   async submitFeedback(slug, params) {
     const url = `${this.baseUrl}/api/library/${this.teamSlug}/articles/${slug}/feedback`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.publishableKey) headers["Authorization"] = `Bearer ${this.publishableKey}`;
     const response = await globalThis.fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers,
       body: JSON.stringify(params)
     });
-    const body = await response.json();
+    const body = await response.json().catch(() => null);
     if (!response.ok) {
-      throw new Error(body.error ?? `Feedback submission failed: ${response.status}`);
+      throw parsePublicError(
+        response.status,
+        body,
+        body?.error ?? `Feedback submission failed: ${response.status}`
+      );
+    }
+    if (body === null) {
+      throw parsePublicError(
+        response.status,
+        null,
+        `Feedback submission returned an invalid JSON response (status ${response.status})`
+      );
     }
     return body;
   }
@@ -120,13 +359,17 @@ var LibraryClient = 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" } }));
-      throw new Error(errorBody.error?.message ?? `Library API error: ${response.status}`);
+      const errorBody = await response.json().catch(() => null);
+      throw parsePublicError(response.status, errorBody, `Library API error: ${response.status}`);
     }
     return response.json();
   }

package/dist/quickhelp/index.cjs

@@ -24,14 +24,215 @@ __export(quickhelp_exports, {
   QuickHelpError: () => QuickHelpError
 });
 module.exports = __toCommonJS(quickhelp_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 ?? "";
+  }
+};
+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
+};
+
+// src/quickhelp/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var QuickHelpClient = class {
   constructor(config) {
-    if (!config?.teamId) {
-      throw new Error("QuickHelpClient: teamId is required");
+    this.resolveTeamIdPromise = null;
+    if (!config?.teamId && !config?.teamSlug) {
+      throw new Error(
+        'QuickHelpClient: either `teamId` or `teamSlug` is required. Pass `teamSlug` (e.g. "acme") for the easiest setup.'
+      );
     }
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.teamId = config.teamId;
+    this.teamId = config.teamId ?? null;
+    this.teamSlug = config.teamSlug ?? null;
+    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] QuickHelpClient: publishableKey must start with `pk_test_` or `pk_live_`. Secret keys (`sk_*`) cannot be used in browser/anonymous contexts."
+      );
+    }
+  }
+  authHeaders() {
+    return this.publishableKey ? { Authorization: `Bearer ${this.publishableKey}` } : {};
+  }
+  /**
+   * Resolve `teamSlug` → `teamId` lazily on the first call that needs it.
+   * Cached for the life of the client. NEW-v2-05.
+   */
+  async resolveTeamId() {
+    if (this.teamId) return this.teamId;
+    if (!this.teamSlug) throw new Error("QuickHelpClient: no teamId or teamSlug set");
+    if (this.resolveTeamIdPromise) return this.resolveTeamIdPromise;
+    this.resolveTeamIdPromise = (async () => {
+      const url = `${this.baseUrl}/api/widget/team-by-slug?teamSlug=${encodeURIComponent(this.teamSlug)}`;
+      const res = await globalThis.fetch(url, { method: "GET", headers: this.authHeaders() });
+      if (!res.ok) {
+        throw new Error(
+          `QuickHelpClient: could not resolve teamSlug "${this.teamSlug}" (HTTP ${res.status}).`
+        );
+      }
+      const body = await res.json();
+      const id = body?.data?.teamId;
+      if (!id) {
+        throw new Error(
+          `QuickHelpClient: lookup for teamSlug "${this.teamSlug}" returned no teamId.`
+        );
+      }
+      this.teamId = id;
+      return id;
+    })();
+    try {
+      return await this.resolveTeamIdPromise;
+    } catch (err) {
+      this.resolveTeamIdPromise = null;
+      throw err;
+    }
   }
   /**
    * Fetch the sanitized public config (title, subtitle, placeholder,
@@ -41,8 +242,9 @@ var QuickHelpClient = class {
    * Returns `null` if Quick Help is disabled on the team (404).
    */
   async config() {
-    const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(this.teamId)}`;
-    const res = await globalThis.fetch(url, { method: "GET" });
+    const teamId = await this.resolveTeamId();
+    const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(teamId)}`;
+    const res = await globalThis.fetch(url, { method: "GET", headers: this.authHeaders() });
     if (res.status === 404) return null;
     if (!res.ok) {
       const body2 = await res.json().catch(() => null);
@@ -58,18 +260,29 @@ var QuickHelpClient = class {
    * property set from the response body.
    */
   async ask(params) {
+    const teamId = await this.resolveTeamId();
     const url = `${this.baseUrl}/api/quickhelp/ask`;
     const res = await globalThis.fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...this.authHeaders() },
       body: JSON.stringify({
-        team_id: this.teamId,
+        team_id: teamId,
         session_id: params.sessionId ?? null,
         question: params.question
       })
     });
     const body = await res.json().catch(() => null);
     if (!res.ok || !body?.success || !body.data) {
+      if (res.status === 503 || body?.error?.code === "feature_not_configured") {
+        throw new CStarFeatureDisabledError(res.status, {
+          type: "feature_not_configured",
+          code: "feature_not_configured",
+          message: body?.error?.message ?? "Quick Help is not available on this team. Enable an AI Agent (Settings \u2192 AI Agents) and configure Quick Help (Settings \u2192 Quick Help) before calling .ask().",
+          doc_url: "https://cstar.help/developers/api/errors#feature-not-configured",
+          feature: "quickHelp",
+          enable_url: `${this.baseUrl}/team/${encodeURIComponent(teamId)}/settings?section=quickHelp`
+        });
+      }
       const message = body?.error?.message ?? `Quick Help ask failed: ${res.status}`;
       const err = new QuickHelpError(message, {
         status: res.status,

package/dist/quickhelp/index.d.cts

@@ -1,7 +1,28 @@
-/** Options for the QuickHelpClient. No auth — Quick Help is anonymous by design. */
+/**
+ * Options for the QuickHelpClient. No auth — Quick Help is anonymous by
+ * design.
+ *
+ * NEW-v2-05: pass either `teamId` (UUID, fastest — no roundtrip) or the
+ * easier-to-discover `teamSlug`. The slug is resolved to a UUID on the
+ * first network call and cached for the life of the client. At least one
+ * is required.
+ */
 interface QuickHelpConfig {
-    /** Your team's UUID. Required. */
-    teamId: string;
+    /** Your team's UUID. Either this or `teamSlug` is required. */
+    teamId?: string;
+    /**
+     * Your team's slug (e.g. `acme`). Resolved to `teamId` lazily via the
+     * public `/api/widget/team-by-slug` endpoint on the first call. Cached
+     * thereafter. Either this or `teamId` is required.
+     */
+    teamSlug?: string;
+    /**
+     * Optional publishable key (`pk_test_*` or `pk_live_*`). Sent as
+     * `Authorization: Bearer` so test-mode dev sessions can be scoped
+     * separately from live customer sessions in your analytics. Backwards-
+     * compatible: omit and the client behaves exactly as before.
+     */
+    publishableKey?: string;
     /** Override the base URL (defaults to https://www.cstar.help). */
     baseUrl?: string;
 }
@@ -60,8 +81,20 @@ interface QuickHelpAskResult {
  */
 declare class QuickHelpClient {
     private readonly baseUrl;
-    private readonly teamId;
+    /** Cached resolved teamId. `null` until the first lookup completes. */
+    private teamId;
+    private readonly teamSlug;
+    private resolveTeamIdPromise;
+    private readonly publishableKey;
+    /** Resolved mode based on the publishable-key prefix. */
+    readonly mode: 'live' | 'test';
     constructor(config: QuickHelpConfig);
+    private authHeaders;
+    /**
+     * Resolve `teamSlug` → `teamId` lazily on the first call that needs it.
+     * Cached for the life of the client. NEW-v2-05.
+     */
+    private resolveTeamId;
     /**
      * Fetch the sanitized public config (title, subtitle, placeholder,
      * theme overrides). Never includes agent id or escalation contact

package/dist/quickhelp/index.d.ts

@@ -1,7 +1,28 @@
-/** Options for the QuickHelpClient. No auth — Quick Help is anonymous by design. */
+/**
+ * Options for the QuickHelpClient. No auth — Quick Help is anonymous by
+ * design.
+ *
+ * NEW-v2-05: pass either `teamId` (UUID, fastest — no roundtrip) or the
+ * easier-to-discover `teamSlug`. The slug is resolved to a UUID on the
+ * first network call and cached for the life of the client. At least one
+ * is required.
+ */
 interface QuickHelpConfig {
-    /** Your team's UUID. Required. */
-    teamId: string;
+    /** Your team's UUID. Either this or `teamSlug` is required. */
+    teamId?: string;
+    /**
+     * Your team's slug (e.g. `acme`). Resolved to `teamId` lazily via the
+     * public `/api/widget/team-by-slug` endpoint on the first call. Cached
+     * thereafter. Either this or `teamId` is required.
+     */
+    teamSlug?: string;
+    /**
+     * Optional publishable key (`pk_test_*` or `pk_live_*`). Sent as
+     * `Authorization: Bearer` so test-mode dev sessions can be scoped
+     * separately from live customer sessions in your analytics. Backwards-
+     * compatible: omit and the client behaves exactly as before.
+     */
+    publishableKey?: string;
     /** Override the base URL (defaults to https://www.cstar.help). */
     baseUrl?: string;
 }
@@ -60,8 +81,20 @@ interface QuickHelpAskResult {
  */
 declare class QuickHelpClient {
     private readonly baseUrl;
-    private readonly teamId;
+    /** Cached resolved teamId. `null` until the first lookup completes. */
+    private teamId;
+    private readonly teamSlug;
+    private resolveTeamIdPromise;
+    private readonly publishableKey;
+    /** Resolved mode based on the publishable-key prefix. */
+    readonly mode: 'live' | 'test';
     constructor(config: QuickHelpConfig);
+    private authHeaders;
+    /**
+     * Resolve `teamSlug` → `teamId` lazily on the first call that needs it.
+     * Cached for the life of the client. NEW-v2-05.
+     */
+    private resolveTeamId;
     /**
      * Fetch the sanitized public config (title, subtitle, placeholder,
      * theme overrides). Never includes agent id or escalation contact