@cstar.help/js 0.13.0 → 0.15.0

package/dist/quickhelp/index.cjs

@@ -20,8 +20,21 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/quickhelp/index.ts
 var quickhelp_exports = {};
 __export(quickhelp_exports, {
+  CStarAuthenticationError: () => CStarAuthenticationError,
+  CStarConflictError: () => CStarConflictError,
+  CStarError: () => CStarError,
+  CStarFeatureDisabledError: () => CStarFeatureDisabledError,
+  CStarNotFoundError: () => CStarNotFoundError,
+  CStarPermissionError: () => CStarPermissionError,
+  CStarRateLimitError: () => CStarRateLimitError,
+  CStarRealtimeUnavailableError: () => CStarRealtimeUnavailableError,
+  CStarServerError: () => CStarServerError,
+  CStarValidationError: () => CStarValidationError,
+  ErrorType: () => ErrorType,
   QuickHelpClient: () => QuickHelpClient,
-  QuickHelpError: () => QuickHelpError
+  QuickHelpError: () => QuickHelpError,
+  parseError: () => parseError,
+  parsePublicError: () => parsePublicError
 });
 module.exports = __toCommonJS(quickhelp_exports);
 
@@ -62,7 +75,7 @@ function normalizeArgs(messageOrStatus, maybeBody, defaults) {
     }
   };
 }
-var CStarError = class extends Error {
+var CStarErrorImpl = class extends Error {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body);
     super(resolved.message);
@@ -75,7 +88,7 @@ var CStarError = class extends Error {
     this.statusCode = statusCode;
   }
 };
-var CStarAuthenticationError = class extends CStarError {
+var CStarAuthenticationErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.AUTHENTICATION_ERROR,
@@ -86,7 +99,7 @@ var CStarAuthenticationError = class extends CStarError {
     this.name = "CStarAuthenticationError";
   }
 };
-var CStarRateLimitError = class extends CStarError {
+var CStarRateLimitErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body, retryAfter) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.RATE_LIMIT_ERROR,
@@ -98,7 +111,7 @@ var CStarRateLimitError = class extends CStarError {
     this.retryAfter = retryAfter ?? 60;
   }
 };
-var CStarNotFoundError = class extends CStarError {
+var CStarNotFoundErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.NOT_FOUND_ERROR,
@@ -109,7 +122,7 @@ var CStarNotFoundError = class extends CStarError {
     this.name = "CStarNotFoundError";
   }
 };
-var CStarValidationError = class extends CStarError {
+var CStarValidationErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.INVALID_REQUEST_ERROR,
@@ -120,7 +133,7 @@ var CStarValidationError = class extends CStarError {
     this.name = "CStarValidationError";
   }
 };
-var CStarPermissionError = class extends CStarError {
+var CStarPermissionErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.PERMISSION_ERROR,
@@ -131,7 +144,7 @@ var CStarPermissionError = class extends CStarError {
     this.name = "CStarPermissionError";
   }
 };
-var CStarConflictError = class extends CStarError {
+var CStarConflictErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.CONFLICT_ERROR,
@@ -142,7 +155,7 @@ var CStarConflictError = class extends CStarError {
     this.name = "CStarConflictError";
   }
 };
-var CStarServerError = class extends CStarError {
+var CStarServerErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.SERVER_ERROR,
@@ -153,7 +166,7 @@ var CStarServerError = class extends CStarError {
     this.name = "CStarServerError";
   }
 };
-var CStarFeatureDisabledError = class extends CStarError {
+var CStarFeatureDisabledErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.FEATURE_NOT_CONFIGURED,
@@ -166,6 +179,82 @@ var CStarFeatureDisabledError = class extends CStarError {
     this.enableUrl = resolved.enable_url ?? "";
   }
 };
+var CStarRealtimeUnavailableErrorImpl = class extends CStarErrorImpl {
+  constructor(message) {
+    const resolved = message ?? "EventSource is not available in this environment. Real-time subscriptions only work in the browser. Move the call to a client-only path (`useEffect` / `onMount`), or pass an `eventSource` polyfill via the realtime options. See https://cstar.help/developers/sdk/realtime#ssr";
+    super(0, {
+      type: ErrorType.API_ERROR,
+      code: "realtime_unavailable",
+      message: resolved,
+      doc_url: "https://cstar.help/developers/sdk/realtime#ssr"
+    });
+    this.name = "CStarRealtimeUnavailableError";
+  }
+};
+var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("@cstar.help/js/errors/v1");
+var globalSlot = globalThis;
+var registry = globalSlot[REGISTRY_KEY] ?? (globalSlot[REGISTRY_KEY] = {
+  CStarError: CStarErrorImpl,
+  CStarAuthenticationError: CStarAuthenticationErrorImpl,
+  CStarRateLimitError: CStarRateLimitErrorImpl,
+  CStarNotFoundError: CStarNotFoundErrorImpl,
+  CStarValidationError: CStarValidationErrorImpl,
+  CStarPermissionError: CStarPermissionErrorImpl,
+  CStarConflictError: CStarConflictErrorImpl,
+  CStarServerError: CStarServerErrorImpl,
+  CStarFeatureDisabledError: CStarFeatureDisabledErrorImpl,
+  CStarRealtimeUnavailableError: CStarRealtimeUnavailableErrorImpl
+});
+var CStarError = registry.CStarError;
+var CStarAuthenticationError = registry.CStarAuthenticationError;
+var CStarRateLimitError = registry.CStarRateLimitError;
+var CStarNotFoundError = registry.CStarNotFoundError;
+var CStarValidationError = registry.CStarValidationError;
+var CStarPermissionError = registry.CStarPermissionError;
+var CStarConflictError = registry.CStarConflictError;
+var CStarServerError = registry.CStarServerError;
+var CStarFeatureDisabledError = registry.CStarFeatureDisabledError;
+var CStarRealtimeUnavailableError = registry.CStarRealtimeUnavailableError;
+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,
@@ -176,16 +265,41 @@ var TYPE_TO_CLASS = {
   [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/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)) {
@@ -197,6 +311,39 @@ var QuickHelpClient = class {
   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,
    * theme overrides). Never includes agent id or escalation contact
@@ -205,7 +352,8 @@ 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 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) {
@@ -222,12 +370,13 @@ 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", ...this.authHeaders() },
       body: JSON.stringify({
-        team_id: this.teamId,
+        team_id: teamId,
         session_id: params.sessionId ?? null,
         question: params.question
       })
@@ -241,7 +390,7 @@ var QuickHelpClient = class {
           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(this.teamId)}/settings?section=quickHelp`
+          enable_url: `${this.baseUrl}/team/${encodeURIComponent(teamId)}/settings?section=quickHelp`
         });
       }
       const message = body?.error?.message ?? `Quick Help ask failed: ${res.status}`;
@@ -271,6 +420,19 @@ function parseRetryAfter(header) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CStarAuthenticationError,
+  CStarConflictError,
+  CStarError,
+  CStarFeatureDisabledError,
+  CStarNotFoundError,
+  CStarPermissionError,
+  CStarRateLimitError,
+  CStarRealtimeUnavailableError,
+  CStarServerError,
+  CStarValidationError,
+  ErrorType,
   QuickHelpClient,
-  QuickHelpError
+  QuickHelpError,
+  parseError,
+  parsePublicError
 });

package/dist/quickhelp/index.d.cts

@@ -1,7 +1,21 @@
-/** 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
@@ -41,6 +55,126 @@ interface QuickHelpAskResult {
     turnNumber: number;
 }
 
+/**
+ * Error classes for the cStar SDK.
+ *
+ * NEW-v3-01 — Cross-subpath instanceof identity.
+ *
+ * Each public subpath (`/library`, `/auth`, `/community`, `/quickhelp`, ...)
+ * is bundled as a separate tsup entry with `splitting: false`, so each one
+ * carries its own copy of this module. Without deduplication, errors thrown
+ * by `LibraryClient` carry the LibraryClient-bundled `CStarError` class —
+ * not the one a consumer imports from `@cstar.help/js`. That makes
+ * `instanceof CStarError` checks fail silently, invalidating every "did the
+ * SDK throw a typed cStar error?" branch in user code.
+ *
+ * Fix: register each class on a `Symbol.for(...)` slot of `globalThis`. The
+ * symbol is realm-shared, so every bundled copy of this module resolves to
+ * the SAME class identity at runtime — the first copy to load wins, and all
+ * subsequent copies surface the canonical class via the same slot. The
+ * inline `Impl` definitions are only used as the seed for the very first
+ * copy to register. Internal `parseError` / `parsePublicError` reference the
+ * EXPORTED canonical names so instances they construct also land on the
+ * canonical class.
+ */
+/** Error type constants matching the cStar API. */
+declare const ErrorType: {
+    readonly AUTHENTICATION_ERROR: "authentication_error";
+    readonly PERMISSION_ERROR: "permission_error";
+    readonly INVALID_REQUEST_ERROR: "invalid_request_error";
+    readonly NOT_FOUND_ERROR: "not_found_error";
+    readonly CONFLICT_ERROR: "conflict_error";
+    readonly RATE_LIMIT_ERROR: "rate_limit_error";
+    readonly FEATURE_NOT_CONFIGURED: "feature_not_configured";
+    readonly API_ERROR: "api_error";
+    readonly SERVER_ERROR: "server_error";
+};
+/** Shape of the error object returned by the cStar API. */
+interface ApiErrorBody {
+    type: string;
+    code: string;
+    message: string;
+    param?: string;
+    doc_url: string;
+    request_id?: string;
+    feature?: string;
+    enable_url?: string;
+}
+/** Base error class for all cStar API errors. */
+declare class CStarErrorImpl extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly param?: string;
+    readonly docUrl: string;
+    readonly requestId?: string;
+    readonly statusCode: number;
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarAuthenticationErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarRateLimitErrorImpl extends CStarErrorImpl {
+    readonly retryAfter: number;
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody, retryAfter?: number);
+}
+declare class CStarNotFoundErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarValidationErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarPermissionErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarConflictErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarServerErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarFeatureDisabledErrorImpl extends CStarErrorImpl {
+    readonly feature: string;
+    readonly enableUrl: string;
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarRealtimeUnavailableErrorImpl extends CStarErrorImpl {
+    constructor(message?: string);
+}
+declare const CStarError: typeof CStarErrorImpl;
+type CStarError = InstanceType<typeof CStarErrorImpl>;
+declare const CStarAuthenticationError: typeof CStarAuthenticationErrorImpl;
+type CStarAuthenticationError = InstanceType<typeof CStarAuthenticationErrorImpl>;
+declare const CStarRateLimitError: typeof CStarRateLimitErrorImpl;
+type CStarRateLimitError = InstanceType<typeof CStarRateLimitErrorImpl>;
+declare const CStarNotFoundError: typeof CStarNotFoundErrorImpl;
+type CStarNotFoundError = InstanceType<typeof CStarNotFoundErrorImpl>;
+declare const CStarValidationError: typeof CStarValidationErrorImpl;
+type CStarValidationError = InstanceType<typeof CStarValidationErrorImpl>;
+declare const CStarPermissionError: typeof CStarPermissionErrorImpl;
+type CStarPermissionError = InstanceType<typeof CStarPermissionErrorImpl>;
+declare const CStarConflictError: typeof CStarConflictErrorImpl;
+type CStarConflictError = InstanceType<typeof CStarConflictErrorImpl>;
+declare const CStarServerError: typeof CStarServerErrorImpl;
+type CStarServerError = InstanceType<typeof CStarServerErrorImpl>;
+declare const CStarFeatureDisabledError: typeof CStarFeatureDisabledErrorImpl;
+type CStarFeatureDisabledError = InstanceType<typeof CStarFeatureDisabledErrorImpl>;
+declare const CStarRealtimeUnavailableError: typeof CStarRealtimeUnavailableErrorImpl;
+type CStarRealtimeUnavailableError = InstanceType<typeof CStarRealtimeUnavailableErrorImpl>;
+/**
+ * Parse a public-route response (anonymous LibraryClient, CommunityClient,
+ * QuickHelpClient, AuthClient) into a typed `CStarError`.
+ *
+ * Public routes don't always emit the structured `{error: {type, code,
+ * doc_url, ...}}` envelope — many emit `{error: 'message string'}` or
+ * `{message: '...'}`. This helper normalizes both shapes and dispatches
+ * on HTTP status (closes F-026 and F-034 — Library/Auth used to throw
+ * plain `Error`).
+ */
+declare function parsePublicError(status: number, body: unknown, fallbackMessage: string): CStarError;
+declare function parseError(statusCode: number, body: {
+    error?: ApiErrorBody;
+} | null, retryAfter?: number): CStarError;
+
 /**
  * Quick Help — anonymous AI Q&A client.
  *
@@ -67,12 +201,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
@@ -105,4 +247,4 @@ declare class QuickHelpError extends Error {
     });
 }
 
-export { type QuickHelpAskParams, type QuickHelpAskResult, QuickHelpClient, type QuickHelpConfig, QuickHelpError, type QuickHelpPublicConfig, type QuickHelpTurnOutcome };
+export { type ApiErrorBody, CStarAuthenticationError, CStarConflictError, CStarError, CStarFeatureDisabledError, CStarNotFoundError, CStarPermissionError, CStarRateLimitError, CStarRealtimeUnavailableError, CStarServerError, CStarValidationError, ErrorType, type QuickHelpAskParams, type QuickHelpAskResult, QuickHelpClient, type QuickHelpConfig, QuickHelpError, type QuickHelpPublicConfig, type QuickHelpTurnOutcome, parseError, parsePublicError };

package/dist/quickhelp/index.d.ts

@@ -1,7 +1,21 @@
-/** 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
@@ -41,6 +55,126 @@ interface QuickHelpAskResult {
     turnNumber: number;
 }
 
+/**
+ * Error classes for the cStar SDK.
+ *
+ * NEW-v3-01 — Cross-subpath instanceof identity.
+ *
+ * Each public subpath (`/library`, `/auth`, `/community`, `/quickhelp`, ...)
+ * is bundled as a separate tsup entry with `splitting: false`, so each one
+ * carries its own copy of this module. Without deduplication, errors thrown
+ * by `LibraryClient` carry the LibraryClient-bundled `CStarError` class —
+ * not the one a consumer imports from `@cstar.help/js`. That makes
+ * `instanceof CStarError` checks fail silently, invalidating every "did the
+ * SDK throw a typed cStar error?" branch in user code.
+ *
+ * Fix: register each class on a `Symbol.for(...)` slot of `globalThis`. The
+ * symbol is realm-shared, so every bundled copy of this module resolves to
+ * the SAME class identity at runtime — the first copy to load wins, and all
+ * subsequent copies surface the canonical class via the same slot. The
+ * inline `Impl` definitions are only used as the seed for the very first
+ * copy to register. Internal `parseError` / `parsePublicError` reference the
+ * EXPORTED canonical names so instances they construct also land on the
+ * canonical class.
+ */
+/** Error type constants matching the cStar API. */
+declare const ErrorType: {
+    readonly AUTHENTICATION_ERROR: "authentication_error";
+    readonly PERMISSION_ERROR: "permission_error";
+    readonly INVALID_REQUEST_ERROR: "invalid_request_error";
+    readonly NOT_FOUND_ERROR: "not_found_error";
+    readonly CONFLICT_ERROR: "conflict_error";
+    readonly RATE_LIMIT_ERROR: "rate_limit_error";
+    readonly FEATURE_NOT_CONFIGURED: "feature_not_configured";
+    readonly API_ERROR: "api_error";
+    readonly SERVER_ERROR: "server_error";
+};
+/** Shape of the error object returned by the cStar API. */
+interface ApiErrorBody {
+    type: string;
+    code: string;
+    message: string;
+    param?: string;
+    doc_url: string;
+    request_id?: string;
+    feature?: string;
+    enable_url?: string;
+}
+/** Base error class for all cStar API errors. */
+declare class CStarErrorImpl extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly param?: string;
+    readonly docUrl: string;
+    readonly requestId?: string;
+    readonly statusCode: number;
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarAuthenticationErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarRateLimitErrorImpl extends CStarErrorImpl {
+    readonly retryAfter: number;
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody, retryAfter?: number);
+}
+declare class CStarNotFoundErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarValidationErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarPermissionErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarConflictErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarServerErrorImpl extends CStarErrorImpl {
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarFeatureDisabledErrorImpl extends CStarErrorImpl {
+    readonly feature: string;
+    readonly enableUrl: string;
+    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
+}
+declare class CStarRealtimeUnavailableErrorImpl extends CStarErrorImpl {
+    constructor(message?: string);
+}
+declare const CStarError: typeof CStarErrorImpl;
+type CStarError = InstanceType<typeof CStarErrorImpl>;
+declare const CStarAuthenticationError: typeof CStarAuthenticationErrorImpl;
+type CStarAuthenticationError = InstanceType<typeof CStarAuthenticationErrorImpl>;
+declare const CStarRateLimitError: typeof CStarRateLimitErrorImpl;
+type CStarRateLimitError = InstanceType<typeof CStarRateLimitErrorImpl>;
+declare const CStarNotFoundError: typeof CStarNotFoundErrorImpl;
+type CStarNotFoundError = InstanceType<typeof CStarNotFoundErrorImpl>;
+declare const CStarValidationError: typeof CStarValidationErrorImpl;
+type CStarValidationError = InstanceType<typeof CStarValidationErrorImpl>;
+declare const CStarPermissionError: typeof CStarPermissionErrorImpl;
+type CStarPermissionError = InstanceType<typeof CStarPermissionErrorImpl>;
+declare const CStarConflictError: typeof CStarConflictErrorImpl;
+type CStarConflictError = InstanceType<typeof CStarConflictErrorImpl>;
+declare const CStarServerError: typeof CStarServerErrorImpl;
+type CStarServerError = InstanceType<typeof CStarServerErrorImpl>;
+declare const CStarFeatureDisabledError: typeof CStarFeatureDisabledErrorImpl;
+type CStarFeatureDisabledError = InstanceType<typeof CStarFeatureDisabledErrorImpl>;
+declare const CStarRealtimeUnavailableError: typeof CStarRealtimeUnavailableErrorImpl;
+type CStarRealtimeUnavailableError = InstanceType<typeof CStarRealtimeUnavailableErrorImpl>;
+/**
+ * Parse a public-route response (anonymous LibraryClient, CommunityClient,
+ * QuickHelpClient, AuthClient) into a typed `CStarError`.
+ *
+ * Public routes don't always emit the structured `{error: {type, code,
+ * doc_url, ...}}` envelope — many emit `{error: 'message string'}` or
+ * `{message: '...'}`. This helper normalizes both shapes and dispatches
+ * on HTTP status (closes F-026 and F-034 — Library/Auth used to throw
+ * plain `Error`).
+ */
+declare function parsePublicError(status: number, body: unknown, fallbackMessage: string): CStarError;
+declare function parseError(statusCode: number, body: {
+    error?: ApiErrorBody;
+} | null, retryAfter?: number): CStarError;
+
 /**
  * Quick Help — anonymous AI Q&A client.
  *
@@ -67,12 +201,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
@@ -105,4 +247,4 @@ declare class QuickHelpError extends Error {
     });
 }
 
-export { type QuickHelpAskParams, type QuickHelpAskResult, QuickHelpClient, type QuickHelpConfig, QuickHelpError, type QuickHelpPublicConfig, type QuickHelpTurnOutcome };
+export { type ApiErrorBody, CStarAuthenticationError, CStarConflictError, CStarError, CStarFeatureDisabledError, CStarNotFoundError, CStarPermissionError, CStarRateLimitError, CStarRealtimeUnavailableError, CStarServerError, CStarValidationError, ErrorType, type QuickHelpAskParams, type QuickHelpAskResult, QuickHelpClient, type QuickHelpConfig, QuickHelpError, type QuickHelpPublicConfig, type QuickHelpTurnOutcome, parseError, parsePublicError };