@cstar.help/js 0.17.4 → 0.18.0

package/dist/chat/index.d.cts

@@ -28,6 +28,11 @@ type ChatAuthMode = 'hmac' | 'session';
 interface LoginWithSessionParams {
     /** Supabase access token (JWT). Used as Bearer for every subsequent call. */
     accessToken: string;
+    /**
+     * Optional: the matching refresh token. When supplied, the client renews
+     * an expired access token through `/api/widget/auth/refresh` on a 401.
+     */
+    refreshToken?: string;
     /** Optional: the team UUID. If omitted, derived server-side from the token. */
     teamId?: string;
     /** Optional: a hint for the customer name (UI only — server stays authoritative). */
@@ -132,6 +137,8 @@ interface TicketListResponse {
 /** A message on a ticket. */
 interface Message {
     id: string;
+    /** Opaque send identity, used to reconcile a reply after an uncertain response. */
+    client_request_key?: string | null;
     content: string;
     sender: 'customer' | 'agent';
     sender_name: string;
@@ -144,6 +151,12 @@ interface Message {
     /** Whether this message was sent by an AI agent. */
     is_bot?: boolean;
 }
+/** Options for one logical customer reply, including any retries. */
+interface MessageSendOptions {
+    /** Retain for a manual retry of the same ticket, content and attachments. Use a new key for each intentional send. Receipts last 24 hours. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
 /** A confirmed customer's message attachment. Never a Storage path or URL. */
 interface CustomerAttachmentReference {
     readonly ticketId: string;
@@ -170,6 +183,7 @@ interface TicketListParams {
 }
 /** Parameters for creating a new ticket. */
 interface TicketCreateParams {
+    /** Conversation subject. Subjects over 255 characters are shortened with an ellipsis, never rejected. */
     subject: string;
     message?: string;
 }
@@ -231,6 +245,8 @@ declare class ChatClientError extends Error {
     readonly code: string;
     readonly statusCode: number;
     readonly requestId: string | null;
+    /** Customer message send key retained for a manual retry after an uncertain outcome. */
+    idempotencyKey?: string;
     constructor(arg: ChatErrorOpts | string);
 }
 /** 401 / 403 — auth failed (bad/expired token, wrong team, etc.). */
@@ -316,6 +332,8 @@ declare class ChatClient {
     private readonly pollingInterval;
     private readonly realtimeEnabled;
     private sessionToken;
+    private refreshToken;
+    private refreshPromise;
     private teamId;
     private customerId;
     private authMode;
@@ -429,7 +447,14 @@ declare class ChatClient {
         signal?: AbortSignal;
         cache?: RequestCache;
         readBody?: (response: Response) => Promise<T>;
-    }): Promise<T>;
+        idempotencyKey?: string;
+    }, retriedAfterRefresh?: boolean): Promise<T>;
+    /**
+     * Renew the access token with the stored refresh token. Concurrent 401s
+     * share one refresh. Resolves true when a newer token is in place.
+     */
+    private refreshSession;
+    private requestRefresh;
     /**
      * Look up the team UUID from the configured `teamSlug`. Used by
      * `loginWithCredentials`. HMAC integrators (`identify()`) never hit
@@ -501,8 +526,11 @@ declare class MessagesApi {
     constructor(chat: ChatClient);
     /** List messages for a ticket. */
     list(ticketId: string): Promise<Message[]>;
-    /** Send a message to a ticket. */
-    send(ticketId: string, content: string): Promise<Message>;
+    /**
+     * Send one logical reply. Network and server failures retry twice with the
+     * same key. A separate send call is a new intent unless a retained key is supplied.
+     */
+    send(ticketId: string, content: string, options?: MessageSendOptions): Promise<Message>;
 }
 
-export { type AttachmentDownloadOptions, type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type ChatStateListener, type CustomerAttachmentReference, type DownloadedAttachment, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };
+export { type AttachmentDownloadOptions, type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type ChatStateListener, type CustomerAttachmentReference, type DownloadedAttachment, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type MessageSendOptions, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };

package/dist/chat/index.d.ts

@@ -28,6 +28,11 @@ type ChatAuthMode = 'hmac' | 'session';
 interface LoginWithSessionParams {
     /** Supabase access token (JWT). Used as Bearer for every subsequent call. */
     accessToken: string;
+    /**
+     * Optional: the matching refresh token. When supplied, the client renews
+     * an expired access token through `/api/widget/auth/refresh` on a 401.
+     */
+    refreshToken?: string;
     /** Optional: the team UUID. If omitted, derived server-side from the token. */
     teamId?: string;
     /** Optional: a hint for the customer name (UI only — server stays authoritative). */
@@ -132,6 +137,8 @@ interface TicketListResponse {
 /** A message on a ticket. */
 interface Message {
     id: string;
+    /** Opaque send identity, used to reconcile a reply after an uncertain response. */
+    client_request_key?: string | null;
     content: string;
     sender: 'customer' | 'agent';
     sender_name: string;
@@ -144,6 +151,12 @@ interface Message {
     /** Whether this message was sent by an AI agent. */
     is_bot?: boolean;
 }
+/** Options for one logical customer reply, including any retries. */
+interface MessageSendOptions {
+    /** Retain for a manual retry of the same ticket, content and attachments. Use a new key for each intentional send. Receipts last 24 hours. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
 /** A confirmed customer's message attachment. Never a Storage path or URL. */
 interface CustomerAttachmentReference {
     readonly ticketId: string;
@@ -170,6 +183,7 @@ interface TicketListParams {
 }
 /** Parameters for creating a new ticket. */
 interface TicketCreateParams {
+    /** Conversation subject. Subjects over 255 characters are shortened with an ellipsis, never rejected. */
     subject: string;
     message?: string;
 }
@@ -231,6 +245,8 @@ declare class ChatClientError extends Error {
     readonly code: string;
     readonly statusCode: number;
     readonly requestId: string | null;
+    /** Customer message send key retained for a manual retry after an uncertain outcome. */
+    idempotencyKey?: string;
     constructor(arg: ChatErrorOpts | string);
 }
 /** 401 / 403 — auth failed (bad/expired token, wrong team, etc.). */
@@ -316,6 +332,8 @@ declare class ChatClient {
     private readonly pollingInterval;
     private readonly realtimeEnabled;
     private sessionToken;
+    private refreshToken;
+    private refreshPromise;
     private teamId;
     private customerId;
     private authMode;
@@ -429,7 +447,14 @@ declare class ChatClient {
         signal?: AbortSignal;
         cache?: RequestCache;
         readBody?: (response: Response) => Promise<T>;
-    }): Promise<T>;
+        idempotencyKey?: string;
+    }, retriedAfterRefresh?: boolean): Promise<T>;
+    /**
+     * Renew the access token with the stored refresh token. Concurrent 401s
+     * share one refresh. Resolves true when a newer token is in place.
+     */
+    private refreshSession;
+    private requestRefresh;
     /**
      * Look up the team UUID from the configured `teamSlug`. Used by
      * `loginWithCredentials`. HMAC integrators (`identify()`) never hit
@@ -501,8 +526,11 @@ declare class MessagesApi {
     constructor(chat: ChatClient);
     /** List messages for a ticket. */
     list(ticketId: string): Promise<Message[]>;
-    /** Send a message to a ticket. */
-    send(ticketId: string, content: string): Promise<Message>;
+    /**
+     * Send one logical reply. Network and server failures retry twice with the
+     * same key. A separate send call is a new intent unless a retained key is supplied.
+     */
+    send(ticketId: string, content: string, options?: MessageSendOptions): Promise<Message>;
 }
 
-export { type AttachmentDownloadOptions, type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type ChatStateListener, type CustomerAttachmentReference, type DownloadedAttachment, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };
+export { type AttachmentDownloadOptions, type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type ChatStateListener, type CustomerAttachmentReference, type DownloadedAttachment, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type MessageSendOptions, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };

package/dist/chat/index.js

@@ -434,6 +434,8 @@ var DEFAULT_POLLING_INTERVAL = 3e3;
 var ChatClient = class {
   constructor(config) {
     this.sessionToken = null;
+    this.refreshToken = null;
+    this.refreshPromise = null;
     this.teamId = null;
     this.customerId = null;
     this.authMode = null;
@@ -526,6 +528,7 @@ var ChatClient = class {
     this.applySession(
       {
         accessToken: response.accessToken,
+        refreshToken: response.refreshToken ?? void 0,
         teamId,
         customerName: response.customer.name ?? response.customer.email
       },
@@ -556,6 +559,7 @@ var ChatClient = class {
   applySession(params, generation) {
     this.assertSession(generation);
     this.sessionToken = params.accessToken;
+    this.refreshToken = params.refreshToken ?? null;
     if (params.teamId) {
       this.teamId = params.teamId;
     }
@@ -665,6 +669,8 @@ var ChatClient = class {
     this.pollingSubscriptions.clear();
     this.realtimeMessageSubscriptions.clear();
     this.sessionToken = null;
+    this.refreshToken = null;
+    this.refreshPromise = null;
     this.teamId = null;
     this.customerId = null;
     this.authMode = null;
@@ -696,7 +702,7 @@ var ChatClient = class {
    * the first authenticated round-trip, `getAuthMode()` returns the
    * server-confirmed mode.
    */
-  async fetch(path, options) {
+  async fetch(path, options, retriedAfterRefresh = false) {
     const generation = this.sessionGeneration;
     const assertRequest = () => {
       this.assertSession(generation);
@@ -707,8 +713,10 @@ var ChatClient = class {
     const headers = {
       "Content-Type": "application/json"
     };
-    if (this.sessionToken) {
-      headers["Authorization"] = `Bearer ${this.sessionToken}`;
+    if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+    const sentToken = this.sessionToken;
+    if (sentToken) {
+      headers["Authorization"] = `Bearer ${sentToken}`;
     }
     let response;
     try {
@@ -736,11 +744,17 @@ var ChatClient = class {
     }
     assertRequest();
     const requestId = responseHeaders?.get("X-Request-Id") ?? null;
+    if (response.status === 401 && sentToken && this.refreshToken && !retriedAfterRefresh) {
+      const refreshed = await this.refreshSession(sentToken);
+      assertRequest();
+      if (refreshed) return this.fetch(path, options, true);
+    }
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ error: { code: "UNKNOWN", message: "Request failed" } }));
+      const errorBody = await response.json().catch(() => null);
       assertRequest();
-      const code = errorBody.error?.code ?? "UNKNOWN";
-      const message = errorBody.error?.message ?? `Widget API error: ${response.status}`;
+      const structured = errorBody?.error && typeof errorBody.error === "object" ? errorBody.error : null;
+      const code = structured?.code ?? "UNKNOWN";
+      const message = structured?.message ?? (typeof errorBody?.error === "string" ? errorBody.error : null) ?? (typeof errorBody?.message === "string" ? errorBody.message : null) ?? `Widget API error: ${response.status}`;
       if (response.status === 401 || response.status === 403) {
         throw new ChatClientAuthError({
           message,
@@ -781,9 +795,52 @@ var ChatClient = class {
       return body;
     } catch (error) {
       assertRequest();
+      if (options.idempotencyKey)
+        throw new ChatClientNetworkError({
+          message: "Could not read the message acknowledgment",
+          originalError: error
+        });
       throw error;
     }
   }
+  /**
+   * Renew the access token with the stored refresh token. Concurrent 401s
+   * share one refresh. Resolves true when a newer token is in place.
+   */
+  refreshSession(rejectedToken) {
+    if (this.sessionToken && this.sessionToken !== rejectedToken) return Promise.resolve(true);
+    if (!this.refreshPromise) {
+      const pending = this.requestRefresh().finally(() => {
+        if (this.refreshPromise === pending) this.refreshPromise = null;
+      });
+      this.refreshPromise = pending;
+    }
+    return this.refreshPromise;
+  }
+  async requestRefresh() {
+    const generation = this.sessionGeneration;
+    const refreshToken = this.refreshToken;
+    if (!refreshToken) return false;
+    try {
+      const response = await globalThis.fetch(`${this.baseUrl}/api/widget/auth/refresh`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refreshToken })
+      });
+      if (generation !== this.sessionGeneration) return false;
+      if (!response.ok) {
+        if (response.status === 401) this.refreshToken = null;
+        return false;
+      }
+      const body = await response.json();
+      if (generation !== this.sessionGeneration || !body.accessToken) return false;
+      this.sessionToken = body.accessToken;
+      this.refreshToken = body.refreshToken ?? refreshToken;
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * Look up the team UUID from the configured `teamSlug`. Used by
    * `loginWithCredentials`. HMAC integrators (`identify()`) never hit
@@ -1256,26 +1313,80 @@ var MessagesApi = class {
     assertCurrent();
     return response.data.messages;
   }
-  /** Send a message to a ticket. */
-  async send(ticketId, content) {
+  /**
+   * Send one logical reply. Network and server failures retry twice with the
+   * same key. A separate send call is a new intent unless a retained key is supplied.
+   */
+  async send(ticketId, content, options = {}) {
     const assertCurrent = this.chat.captureSession();
+    options.signal?.throwIfAborted();
+    const key = options.idempotencyKey ?? createMessageRequestKey();
+    if (!key || key.length > 250 || key.trim() !== key || /[^\x20-\x7e]/.test(key))
+      throw new ChatClientError({
+        code: "INVALID_IDEMPOTENCY_KEY",
+        message: "Idempotency-Key must contain 1 to 250 printable characters, without surrounding whitespace."
+      });
     const teamId = await this.chat.ensureTeamId();
     assertCurrent();
-    const response = await this.chat.fetch(
-      "/api/widget/messages",
-      {
-        method: "POST",
-        body: {
-          teamId,
-          ticketId,
-          content
-        }
+    for (let attempt = 0; ; attempt++) {
+      assertCurrent();
+      options.signal?.throwIfAborted();
+      try {
+        const response = await this.chat.fetch(
+          "/api/widget/messages",
+          {
+            method: "POST",
+            body: { teamId, ticketId, content },
+            idempotencyKey: key,
+            signal: options.signal
+          }
+        );
+        assertCurrent();
+        if (typeof response?.data?.message?.id !== "string" || !response.data.message.id)
+          throw new ChatClientNetworkError({
+            message: "Message acknowledgment was incomplete",
+            originalError: new Error(
+              "The reply may already be saved. Retry with the same send identity."
+            )
+          });
+        return response.data.message;
+      } catch (error) {
+        assertCurrent();
+        options.signal?.throwIfAborted();
+        if (error instanceof ChatClientError) error.idempotencyKey = key;
+        if (attempt >= 2 || !(error instanceof ChatClientNetworkError || error instanceof ChatClientServerError))
+          throw error;
+        await waitForMessageRetry(250 * 2 ** attempt, options.signal);
       }
-    );
-    assertCurrent();
-    return response.data.message;
+    }
   }
 };
+function createMessageRequestKey() {
+  if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+  if (typeof globalThis.crypto?.getRandomValues !== "function")
+    throw new ChatClientError({
+      code: "RANDOM_UNAVAILABLE",
+      message: "Secure random values are required to send a message safely."
+    });
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function waitForMessageRetry(delay, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const finish = () => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    };
+    const timer = setTimeout(finish, delay);
+    const abort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
 function decodeJwtSub(jwt) {
   try {
     const parts = jwt.split(".");

package/dist/community/index.d.cts

@@ -1,6 +1,6 @@
 import { h as CommunityConfig, i as CommunityTopic, j as CommunityPostListParams, k as CommunityPost, l as CommunityPostDetail, m as CommunitySearchResult, C as CommunityCreatePostParams, a as CommunityCreatedPost, b as CommunityUpdatePostParams, c as CommunityUpdateCommentParams, d as CommunityCreatedComment, e as CommunityVoteResult, f as CommunityCreateCommentParams, g as CommunityFollowResult } from '../types-DF7GprCV.cjs';
 export { n as CommunityComment } from '../types-DF7GprCV.cjs';
-export { A as ApiErrorBody, C as CStarAuthenticationError, a as CStarConflictError, b as CStarError, c as CStarFeatureDisabledError, d as CStarNotFoundError, e as CStarPermissionError, f as CStarRateLimitError, g as CStarRealtimeUnavailableError, h as CStarServerError, i as CStarValidationError, E as ErrorType, p as parseError, j as parsePublicError } from '../errors-b5A4wfAg.cjs';
+export { A as ApiErrorBody, C as CStarAuthenticationError, a as CStarConflictError, b as CStarError, c as CStarFeatureDisabledError, d as CStarNotFoundError, e as CStarPermissionError, f as CStarRateLimitError, g as CStarRealtimeUnavailableError, h as CStarServerError, i as CStarValidationError, E as ErrorType, p as parseError, j as parsePublicError } from '../errors-bW8CwTn4.cjs';
 
 /**
  * Public community client. No authentication required.

package/dist/community/index.d.ts

@@ -1,6 +1,6 @@
 import { h as CommunityConfig, i as CommunityTopic, j as CommunityPostListParams, k as CommunityPost, l as CommunityPostDetail, m as CommunitySearchResult, C as CommunityCreatePostParams, a as CommunityCreatedPost, b as CommunityUpdatePostParams, c as CommunityUpdateCommentParams, d as CommunityCreatedComment, e as CommunityVoteResult, f as CommunityCreateCommentParams, g as CommunityFollowResult } from '../types-DF7GprCV.js';
 export { n as CommunityComment } from '../types-DF7GprCV.js';
-export { A as ApiErrorBody, C as CStarAuthenticationError, a as CStarConflictError, b as CStarError, c as CStarFeatureDisabledError, d as CStarNotFoundError, e as CStarPermissionError, f as CStarRateLimitError, g as CStarRealtimeUnavailableError, h as CStarServerError, i as CStarValidationError, E as ErrorType, p as parseError, j as parsePublicError } from '../errors-b5A4wfAg.js';
+export { A as ApiErrorBody, C as CStarAuthenticationError, a as CStarConflictError, b as CStarError, c as CStarFeatureDisabledError, d as CStarNotFoundError, e as CStarPermissionError, f as CStarRateLimitError, g as CStarRealtimeUnavailableError, h as CStarServerError, i as CStarValidationError, E as ErrorType, p as parseError, j as parsePublicError } from '../errors-bW8CwTn4.js';
 
 /**
  * Public community client. No authentication required.

package/dist/errors-bW8CwTn4.d.cts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+
+export { type ApiErrorBody as A, CStarAuthenticationError as C, ErrorType as E, CStarConflictError as a, CStarError as b, CStarFeatureDisabledError as c, CStarNotFoundError as d, CStarPermissionError as e, CStarRateLimitError as f, CStarRealtimeUnavailableError as g, CStarServerError as h, CStarValidationError as i, parsePublicError as j, parseError as p };

package/dist/errors-bW8CwTn4.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+
+export { type ApiErrorBody as A, CStarAuthenticationError as C, ErrorType as E, CStarConflictError as a, CStarError as b, CStarFeatureDisabledError as c, CStarNotFoundError as d, CStarPermissionError as e, CStarRateLimitError as f, CStarRealtimeUnavailableError as g, CStarServerError as h, CStarValidationError as i, parsePublicError as j, parseError as p };