@cstar.help/js 0.16.1 → 0.17.0

package/dist/errors-b5A4wfAg.d.ts

@@ -0,0 +1,398 @@
+/**
+ * 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;
+
+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/index.cjs

@@ -323,7 +323,8 @@ var HttpClient = class {
   }
   /**
    * Make an authenticated request to the cStar API.
-   * Automatically retries on 5xx errors and rate limits.
+   * Automatically retries rate limits and retry-safe failures. POST/PATCH
+   * network and 5xx failures require an idempotency key to avoid duplicate writes.
    */
   async request(method, path, options) {
     return this._sendRequest(method, this.buildUrl(path, options?.query), options);
@@ -354,6 +355,7 @@ var HttpClient = class {
   async _sendRequest(method, url, options) {
     const headers = this.buildHeaders(options?.idempotencyKey);
     const body = options?.body ? JSON.stringify(options.body) : void 0;
+    const canRetryAmbiguousFailure = !["POST", "PATCH"].includes(method.toUpperCase()) || !!options?.idempotencyKey;
     let lastError = null;
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
       if (attempt > 0 && lastError) {
@@ -377,7 +379,7 @@ var HttpClient = class {
           message: `Network request failed: ${networkErr.message}`,
           doc_url: "https://www.cstar.help/developers/errors#connection-errors"
         });
-        if (attempt < this.config.maxRetries) continue;
+        if (canRetryAmbiguousFailure && attempt < this.config.maxRetries) continue;
         throw lastError;
       }
       if (response.ok) {
@@ -402,7 +404,7 @@ var HttpClient = class {
         throw lastError;
       }
       lastError = parseError(response.status, errorBody);
-      if (attempt < this.config.maxRetries) continue;
+      if (canRetryAmbiguousFailure && attempt < this.config.maxRetries) continue;
       throw lastError;
     }
     throw lastError ?? new Error("Request failed after retries");
@@ -609,9 +611,13 @@ var CStarRealtime = class {
       this.exchangeToken().then(() => {
         this.connecting = false;
         this.connect();
-      }).catch(() => {
+      }).catch((err) => {
         this.connecting = false;
-        this.connectWithToken(rawKey);
+        if (this.destroyed) return;
+        this.emitError(err instanceof Error ? err : new Error(String(err)));
+        if (this.autoReconnect && this.retryCount < this.maxRetries) {
+          this.scheduleReconnect();
+        }
       });
       return;
     }
@@ -620,9 +626,10 @@ var CStarRealtime = class {
   }
   /**
    * Open the EventSource with the given auth token.
-   * Extracted so both the happy path and the fallback path share logic.
+   * Secret keys reach this method only after exchanging for an SSE token.
    */
   connectWithToken(authToken) {
+    if (this.destroyed) return;
     const baseUrl = this.httpClient.getBaseUrl();
     const params = new URLSearchParams();
     if (this.types && this.types.length > 0) {
@@ -633,11 +640,6 @@ var CStarRealtime = class {
     }
     const qs = params.toString();
     const url = `${baseUrl}/events/stream${qs ? `?${qs}` : ""}`;
-    if (authToken.startsWith("sk_") && typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined") {
-      console.warn(
-        "[cStar] Secret API key is being passed via SSE query parameter. Query strings may be logged by proxies and CDNs. For production, use a server-side proxy to add the Authorization header."
-      );
-    }
     const separator = qs ? "&" : "?";
     const authenticatedUrl = authToken ? `${url}${separator}token=${authToken}` : url;
     const Ctor = this.resolveEventSource();
@@ -809,9 +811,14 @@ var CStarRealtime = class {
    */
   async exchangeToken() {
     const response = await this.httpClient.request("POST", "/events/token");
-    const { token, expiresAt, expiresIn } = response.data;
+    if (this.destroyed) return;
+    const { token, expiresAt, expiresIn } = response;
+    const expiry = new Date(expiresAt).getTime();
+    if (typeof token !== "string" || !token || token.startsWith("sk_") || !Number.isFinite(expiry) || expiry <= Date.now() || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+      throw new Error("SSE token exchange returned an invalid token or expiry");
+    }
     this.sseToken = token;
-    this.sseTokenExpiresAt = new Date(expiresAt).getTime();
+    this.sseTokenExpiresAt = expiry;
     const refreshIn = Math.max((expiresIn - 30) * 1e3, expiresIn / 2 * 1e3);
     this.scheduleTokenRefresh(refreshIn);
   }
@@ -875,6 +882,8 @@ var Subscription = class {
     this.destroyed = false;
     /** Generation counter to prevent stale refresh() from overwriting SSE updates. */
     this.generation = 0;
+    /** Replay events against the initial snapshot instead of discarding that snapshot. */
+    this.initialEvents = [];
     this.init();
   }
   /** Current data array (updated in real-time). */
@@ -902,12 +911,12 @@ var Subscription = class {
     const gen = ++this.generation;
     try {
       const response = await this.fetchFn();
-      if (gen !== this.generation) return;
+      if (this.destroyed || gen !== this.generation) return;
       this._data = response.data;
       this._error = null;
       this.emitChange();
     } catch (err) {
-      if (gen !== this.generation) return;
+      if (this.destroyed || gen !== this.generation) return;
       this._error = err instanceof Error ? err : new Error(String(err));
       this.emitError(this._error);
     }
@@ -934,6 +943,7 @@ var Subscription = class {
   /** Stop the subscription and clean up all listeners. */
   unsubscribe() {
     this.destroyed = true;
+    this.initialEvents = [];
     if (this.boundEventHandler) {
       this.realtime.offAny(this.boundEventHandler);
       this.boundEventHandler = null;
@@ -948,14 +958,18 @@ var Subscription = class {
     const gen = ++this.generation;
     try {
       const response = await this.fetchFn();
-      if (gen !== this.generation) return;
+      if (this.destroyed || gen !== this.generation) return;
       this._data = response.data;
       this._loading = false;
       this._error = null;
+      const events = this.initialEvents;
+      this.initialEvents = [];
+      for (const event of events) this.handleEvent(event);
       this.emitChange();
     } catch (err) {
-      if (gen !== this.generation) return;
+      if (this.destroyed || gen !== this.generation) return;
       this._loading = false;
+      this.initialEvents = [];
       this._error = err instanceof Error ? err : new Error(String(err));
       this.emitError(this._error);
     }
@@ -977,6 +991,10 @@ var Subscription = class {
     }
     const entityData = this.extractEntity(event);
     if (!entityData || !getEntityId(entityData)) return;
+    if (this._loading) {
+      this.initialEvents.push(event);
+      return;
+    }
     this.generation++;
     if (event.type.endsWith(".created")) {
       this.handleCreated(entityData);
@@ -2364,13 +2382,13 @@ var PreferencesResource = class {
 };
 
 // src/offline.ts
-var STORAGE_KEY = "cstar_offline_queue";
 var OfflineQueue = class {
   constructor(httpClient, options) {
     this.httpClient = httpClient;
     this.items = [];
     this.autoFlushEnabled = false;
     this.onlineHandler = null;
+    this.storageKey = `cstar_offline_queue:${httpClient.getBaseUrl()}:${httpClient.environment}`;
     this.useLocalStorage = options?.storage === "localStorage" && typeof globalThis !== "undefined" && typeof globalThis.localStorage !== "undefined";
     if (this.useLocalStorage) {
       this.loadFromStorage();
@@ -2411,7 +2429,7 @@ var OfflineQueue = class {
         const message = err instanceof Error ? err.message : String(err);
         results.push({ id: item.id, success: false, error: message });
         const statusCode = err.statusCode;
-        const isRetryable = !statusCode || statusCode >= 500;
+        const isRetryable = !statusCode || statusCode === 429 || statusCode >= 500;
         if (isRetryable) {
           failedItems.push(item);
         }
@@ -2464,15 +2482,16 @@ var OfflineQueue = class {
   saveToStorage() {
     if (!this.useLocalStorage) return;
     try {
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(this.items));
+      localStorage.setItem(this.storageKey, JSON.stringify(this.items));
     } catch {
     }
   }
   loadFromStorage() {
     try {
-      const raw = localStorage.getItem(STORAGE_KEY);
+      const raw = localStorage.getItem(this.storageKey);
       if (raw) {
-        this.items = JSON.parse(raw);
+        const stored = JSON.parse(raw);
+        this.items = Array.isArray(stored) ? stored : [];
       }
     } catch {
       this.items = [];