@cstar.help/js 0.14.0 → 0.15.1

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,102 @@ 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 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;
+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,6 +285,27 @@ 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";
@@ -310,6 +440,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

@@ -55,6 +55,403 @@ 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 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 CStarRealtimeUnavailableErrorImpl: {
+    new (message?: 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>;
+declare const CStarRealtimeUnavailableError: {
+    new (message?: 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 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.
  *
@@ -127,4 +524,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 };