@cstar.help/js 0.14.0 → 0.15.1

package/dist/index.d.ts

@@ -1017,7 +1017,15 @@ interface Webhook {
     metadata: Metadata;
     createdAt: string;
     updatedAt: string;
-    /** Only returned on creation (POST). */
+    /**
+     * Signing secret for HMAC verification (`whsec_*`). Only returned on
+     * creation (POST `/webhooks`). Save it immediately — subsequent reads
+     * will not include it. Use it as the `secret` argument to
+     * `constructEvent` / `verifySignature` from `@cstar.help/js/webhook`.
+     */
+    signingSecret?: string;
+    /** @deprecated since 0.15.0 — use {@link signingSecret} instead. Kept
+     * during the deprecation window so 0.14.x consumers keep working. */
     secret?: string;
 }
 /** Parameters for listing webhooks. */
@@ -3056,6 +3064,28 @@ declare class OfflineQueue {
     private loadFromStorage;
 }
 
+/**
+ * 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";
@@ -3080,58 +3110,309 @@ interface ApiErrorBody {
     enable_url?: string;
 }
 /** Base error class for all cStar API errors. */
-declare class CStarError 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);
-}
-/** Thrown when authentication fails (401). */
-declare class CStarAuthenticationError extends CStarError {
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
-}
-/** Thrown when rate limited (429). Includes retry timing. */
-declare class CStarRateLimitError extends CStarError {
-    readonly retryAfter: number;
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody, retryAfter?: number);
-}
-/** Thrown when a resource is not found (404). */
-declare class CStarNotFoundError extends CStarError {
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
-}
-/** Thrown on invalid request parameters (400/422). */
-declare class CStarValidationError extends CStarError {
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
-}
-/** Thrown when authenticated but lacking permission (403). */
-declare class CStarPermissionError extends CStarError {
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
-}
-/** Thrown on resource conflicts (409). */
-declare class CStarConflictError extends CStarError {
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
-}
-/** Thrown on internal server errors (500+). */
-declare class CStarServerError extends CStarError {
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
-}
-/**
- * Thrown when the call landed on a feature that the team has not enabled
- * or configured (e.g. Quick Help on a team without an AI agent). Carries
- * `feature` and `enableUrl` so the caller can route the user to the
- * dashboard setting that fixes it.
- *
- * Closes F-031 — anonymous QuickHelp `.ask()` previously surfaced as an
- * unactionable 503.
- */
-declare class CStarFeatureDisabledError extends CStarError {
-    readonly feature: string;
-    readonly enableUrl: string;
-    constructor(messageOrStatus: string | number, body?: ApiErrorBody);
-}
+declare const CStarErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarAuthenticationErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarRateLimitErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody, retryAfter?: number): {
+        readonly retryAfter: number;
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarNotFoundErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarValidationErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarPermissionErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarConflictErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarServerErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarFeatureDisabledErrorImpl: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly feature: string;
+        readonly enableUrl: string;
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare const CStarError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarError = InstanceType<typeof CStarErrorImpl>;
+declare const CStarAuthenticationError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarAuthenticationError = InstanceType<typeof CStarAuthenticationErrorImpl>;
+declare const CStarRateLimitError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody, retryAfter?: number): {
+        readonly retryAfter: number;
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarRateLimitError = InstanceType<typeof CStarRateLimitErrorImpl>;
+declare const CStarNotFoundError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarNotFoundError = InstanceType<typeof CStarNotFoundErrorImpl>;
+declare const CStarValidationError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarValidationError = InstanceType<typeof CStarValidationErrorImpl>;
+declare const CStarPermissionError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarPermissionError = InstanceType<typeof CStarPermissionErrorImpl>;
+declare const CStarConflictError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarConflictError = InstanceType<typeof CStarConflictErrorImpl>;
+declare const CStarServerError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarServerError = InstanceType<typeof CStarServerErrorImpl>;
+declare const CStarFeatureDisabledError: {
+    new (messageOrStatus: string | number, body?: ApiErrorBody): {
+        readonly feature: string;
+        readonly enableUrl: string;
+        readonly type: string;
+        readonly code: string;
+        readonly param?: string;
+        readonly docUrl: string;
+        readonly requestId?: string;
+        readonly statusCode: number;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+type CStarFeatureDisabledError = InstanceType<typeof CStarFeatureDisabledErrorImpl>;
 
 /** Configuration for the CStarClient. */
 interface CStarClientConfig {

package/dist/index.js

@@ -35,7 +35,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);
@@ -48,7 +48,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,
@@ -59,7 +59,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,
@@ -71,7 +71,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,
@@ -82,7 +82,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,
@@ -93,7 +93,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,
@@ -104,7 +104,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,
@@ -115,7 +115,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,
@@ -126,7 +126,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,
@@ -139,7 +139,7 @@ var CStarFeatureDisabledError = class extends CStarError {
     this.enableUrl = resolved.enable_url ?? "";
   }
 };
-var CStarRealtimeUnavailableError = class extends CStarError {
+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, {
@@ -151,6 +151,50 @@ var CStarRealtimeUnavailableError = class extends CStarError {
     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 NAME_FIXES = [
+  "CStarError",
+  "CStarAuthenticationError",
+  "CStarRateLimitError",
+  "CStarNotFoundError",
+  "CStarValidationError",
+  "CStarPermissionError",
+  "CStarConflictError",
+  "CStarServerError",
+  "CStarFeatureDisabledError",
+  "CStarRealtimeUnavailableError"
+];
+for (const key of NAME_FIXES) {
+  if (registry[key].name !== key) {
+    Object.defineProperty(registry[key], "name", {
+      value: key,
+      configurable: true
+    });
+  }
+}
+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;
 var STATUS_TO_CLASS = {
   400: CStarValidationError,
   401: CStarAuthenticationError,
@@ -193,7 +237,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.14.0";
+var SDK_VERSION = "0.15.1";
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;