@cstar.help/js 0.17.5 → 0.18.1

package/dist/index.cjs

@@ -278,7 +278,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.17.5";
+var SDK_VERSION = "0.18.1";
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;
@@ -298,7 +298,7 @@ var HttpClient = class {
     this.lastMeta = { requestId: null, timestamp: null, pagination: null };
     if (!config || typeof config.apiKey !== "string" || config.apiKey.length === 0) {
       throw new Error(
-        "[cStar] CStarClient: apiKey is required. Pass a secret key (sk_live_... / sk_test_...) or a publishable key (pk_live_... / pk_test_...). See https://cstar.help/developers/quickstart"
+        "[cStar] CStarClient: apiKey is required. Pass a secret key (sk_live_... / sk_test_...). Publishable keys (pk_...) cannot read team endpoints; use them with LibraryClient or CommunityClient. See https://cstar.help/developers/quickstart"
       );
     }
     if (typeof config.teamId !== "string" || config.teamId.length === 0) {
@@ -357,10 +357,12 @@ var HttpClient = class {
     const body = options?.body ? JSON.stringify(options.body) : void 0;
     const canRetryAmbiguousFailure = !["POST", "PATCH"].includes(method.toUpperCase()) || !!options?.idempotencyKey;
     let lastError = null;
+    const RATE_LIMIT_RETRY_CAP_MS = 6e4;
+    let inProgressWaitMs = null;
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
       if (attempt > 0 && lastError) {
-        const RATE_LIMIT_RETRY_CAP_MS = 6e4;
-        const delay = lastError instanceof CStarRateLimitError ? Math.min(lastError.retryAfter * 1e3, RATE_LIMIT_RETRY_CAP_MS) : this.getBackoffDelay(attempt);
+        const delay = inProgressWaitMs ?? (lastError instanceof CStarRateLimitError ? Math.min(lastError.retryAfter * 1e3, RATE_LIMIT_RETRY_CAP_MS) : this.getBackoffDelay(attempt));
+        inProgressWaitMs = null;
         await this.sleep(delay);
       }
       let response;
@@ -400,6 +402,14 @@ var HttpClient = class {
       if (requestId && errorBody?.error) {
         errorBody.error.request_id = requestId;
       }
+      if (response.status === 409 && options?.idempotencyKey && errorBody?.error?.code === "idempotency_key_in_use" && retryAfter !== void 0) {
+        lastError = parseError(409, errorBody, retryAfter);
+        if (attempt < this.config.maxRetries) {
+          inProgressWaitMs = Math.min(retryAfter * 1e3, RATE_LIMIT_RETRY_CAP_MS);
+          continue;
+        }
+        throw lastError;
+      }
       if (response.status < 500 && response.status !== 429) {
         throw parseError(response.status, errorBody, retryAfter);
       }
@@ -530,6 +540,8 @@ var CStarRealtime = class {
     this.retryTimer = null;
     this._connected = false;
     this.destroyed = false;
+    /** The server closed the stream because the API key was revoked or expired. */
+    this.revoked = false;
     this.connecting = false;
     /** Short-lived SSE token (exchanged from secret key). */
     this.sseToken = null;
@@ -605,7 +617,7 @@ var CStarRealtime = class {
   }
   /** Start the SSE connection. Called automatically on first handler registration. */
   connect() {
-    if (this.eventSource || this.destroyed || this.connecting) return;
+    if (this.eventSource || this.destroyed || this.revoked || this.connecting) return;
     if (!this.resolveEventSource()) {
       throw new CStarRealtimeUnavailableError();
     }
@@ -665,6 +677,7 @@ var CStarRealtime = class {
         this.eventSource.close();
         this.eventSource = null;
       }
+      if (this.revoked) return;
       if (this.autoReconnect && !this.destroyed && this.retryCount < this.maxRetries) {
         this.scheduleReconnect();
       } else if (this.retryCount >= this.maxRetries) {
@@ -674,6 +687,9 @@ var CStarRealtime = class {
     this.eventSource.onmessage = (event) => {
       this.handleMessage(event);
     };
+    this.eventSource.addEventListener("revoked", (event) => {
+      this.handleRevoked(event);
+    });
     const knownTypes = [
       "ticket.created",
       "ticket.updated",
@@ -802,6 +818,40 @@ var CStarRealtime = class {
       for (const handler of this.connectionHandlers) handler(value);
     }
   }
+  handleRevoked(event) {
+    if (this.revoked || this.destroyed) return;
+    this.revoked = true;
+    let body = {};
+    try {
+      body = JSON.parse(event.data).error ?? {};
+    } catch {
+    }
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    if (this.tokenRefreshTimer) {
+      clearTimeout(this.tokenRefreshTimer);
+      this.tokenRefreshTimer = null;
+    }
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.sseToken = null;
+    this.sseTokenExpiresAt = 0;
+    this.connecting = false;
+    this.setConnected(false);
+    this.emitError(
+      new CStarAuthenticationError(401, {
+        type: body.type ?? "authentication_error",
+        code: body.code ?? "invalid_api_key",
+        message: body.message ?? "This API key was revoked or has expired, so the stream is closed.",
+        doc_url: body.doc_url ?? "https://www.cstar.help/developers/errors#invalid_api_key",
+        ...body.request_id ? { request_id: body.request_id } : {}
+      })
+    );
+  }
   emitError(error) {
     for (const handler of this.errorHandlers) handler(error);
   }
@@ -1521,11 +1571,17 @@ var SettingsResource = class {
   async update(params) {
     return this.client.request("PATCH", "/settings", { body: params });
   }
-  /** Get business hours configuration. */
+  /**
+   * Get the chat widget's online hours (outside them the widget shows its
+   * offline message). Not the SLA working hours that SLA deadlines use.
+   */
   async getBusinessHours() {
     return this.client.request("GET", "/settings/business-hours");
   }
-  /** Update business hours configuration. */
+  /**
+   * Update the chat widget's online hours. SLA deadlines don't change:
+   * they follow the SLA working hours in Settings > Business Hours.
+   */
   async updateBusinessHours(params) {
     return this.client.request("PATCH", "/settings/business-hours", {
       body: params
@@ -1550,8 +1606,10 @@ var NotificationsResource = class {
   }
   /** List notifications for a user. */
   async list(params) {
+    const { unreadOnly, ...query } = params;
+    if (unreadOnly && query.isRead === void 0) query.isRead = false;
     return this.client.request("GET", "/notifications", {
-      query: params
+      query
     });
   }
   /** Get unread notification count for a user. */
@@ -1625,15 +1683,22 @@ var AttachmentsResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List attachments. */
+  /** List message files, each with a short-lived signed `url`. */
   async list(params) {
     return this.client.request("GET", "/attachments", {
       query: params
     });
   }
-  /** Get a single attachment. */
-  async get(attachmentId) {
-    return this.client.request("GET", `/attachments/${attachmentId}`);
+  /**
+   * Get a signed download URL, valid for `expiresIn` seconds, for a stored
+   * file. Pass `storagePath` and `bucket` from `list()`.
+   */
+  async get(storagePath, params) {
+    return this.client.request(
+      "GET",
+      `/attachments/${storagePath}`,
+      params?.bucket ? { query: { bucket: params.bucket } } : void 0
+    );
   }
   /** Delete an attachment. */
   async del(attachmentId) {
@@ -1649,16 +1714,12 @@ var CustomFieldsResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List custom fields. */
+  /** List custom field definitions, optionally for one record type. There is no single-field GET. */
   async list(params) {
     return this.client.request("GET", "/custom-fields", {
       query: params
     });
   }
-  /** Get a single custom field. */
-  async get(fieldId) {
-    return this.client.request("GET", `/custom-fields/${fieldId}`);
-  }
   /** Create a custom field. */
   async create(params, options) {
     return this.client.request("POST", "/custom-fields", {
@@ -1693,11 +1754,9 @@ var SlaResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List SLA rules. */
-  async list(params) {
-    return this.client.request("GET", "/sla/rules", {
-      query: params
-    });
+  /** List SLA rules in evaluation order. */
+  async list() {
+    return this.client.request("GET", "/sla/rules");
   }
   /** Create an SLA rule. */
   async create(params, options) {
@@ -1886,25 +1945,28 @@ var TagsResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List all tags with usage counts. */
+  /** List tags with usage counts, one row per tag and entity type. */
   async list(params) {
     return this.client.request("GET", "/tags", {
       query: params
     });
   }
-  /** Create a tag. */
-  async create(name, options) {
+  /** Replace `fromTag` with `toTag` on every record that carries it. */
+  async merge(params, options) {
     return this.client.request("POST", "/tags", {
-      body: { name },
+      body: { action: "merge", ...params },
       idempotencyKey: options?.idempotencyKey
     });
   }
-  /** Delete a tag. */
-  async del(name) {
-    return this.client.request(
-      "DELETE",
-      `/tags/${encodeURIComponent(name)}`
-    );
+  /** Remove a tag from every record that carries it. */
+  async remove(tag, params) {
+    return this.client.request("DELETE", "/tags", {
+      body: { tag, ...params }
+    });
+  }
+  /** @deprecated Use `remove()`. */
+  async del(tag, params) {
+    return this.remove(tag, params);
   }
 };
 
@@ -2350,7 +2412,7 @@ var ViewsResource = class extends BaseResource {
   constructor(client) {
     super(client, "/views");
   }
-  /** Execute a view — returns the filtered results. The server uses the view's entity_type to determine which table to query. */
+  /** Execute a view and return the filtered results. The server uses the view's entity_type to determine which table to query. */
   async execute(viewId, params) {
     return this.client.request("GET", `/views/${viewId}/execute`, {
       query: params
@@ -2586,7 +2648,7 @@ var WEBHOOK_EVENT_SAMPLES = {
     "comment": {
       "id": "cmt_01H8X9YZ7E0J3K4M5N6X",
       "post_id": "post_01H8X9YZ7E0J3K4M5N6W",
-      "content": "I would love this \u2014 bumping for visibility.",
+      "content": "I would love this. Bumping for visibility.",
       "author_id": "cus_01H8X9YZ7E0J3K4M5N6Q",
       "created_at": "2026-04-27T18:55:02.000Z"
     }
@@ -2806,15 +2868,14 @@ var WEBHOOK_EVENT_SAMPLES = {
       "id": "tkt_01H8X9YZ7E0J3K4M5N6P",
       "prefixed_id": "CST-1024",
       "title": "Cannot reset password",
-      "status": "resolved",
+      "status": "closed",
       "priority": "normal",
-      "channel": "widget",
-      "resolved_at": "2026-04-27T19:08:43.000Z"
+      "channel": "widget"
     },
     "changes": {
       "status": {
         "from": "open",
-        "to": "resolved"
+        "to": "closed"
       }
     }
   },
@@ -2847,7 +2908,7 @@ var WEBHOOK_EVENT_SAMPLES = {
       "id": "msg_01H8X9YZ7E0J3K4M5N6R",
       "sender": "agent",
       "sender_name": "Riley",
-      "content": "I just sent a reset link to your inbox \u2014 let me know if it lands.",
+      "content": "I just sent a reset link to your inbox. Let me know if it lands.",
       "created_at": "2026-04-27T18:55:02.000Z"
     },
     "customer": {
@@ -2913,7 +2974,7 @@ var WEBHOOK_EVENT_CATALOG = {
   "survey.submitted": { label: "Customer Feedback Received", description: "Fired when a customer submits a CSAT survey response", category: "csat" },
   "team.preferences_updated": { label: "Team Preferences Updated", description: "Fired when team-wide UX preferences change (e.g., bossBattlesEnabled toggled)", category: "team" },
   "ticket.assigned": { label: "Ticket Assigned", description: "Fired when a ticket is assigned to an agent", category: "tickets" },
-  "ticket.closed": { label: "Ticket Closed/Resolved", description: "Fired when a ticket is resolved or closed", category: "tickets" },
+  "ticket.closed": { label: "Ticket Closed", description: "Fired when a ticket's status changes to Closed. Moving a ticket to Resolved sends ticket.updated instead.", category: "tickets" },
   "ticket.created": { label: "New Ticket Created", description: "Fired when a new ticket is created via app, widget, API, or email", category: "tickets" },
   "ticket.deleted": { label: "Ticket Deleted", description: "Fired when a ticket is deleted via app or API", category: "tickets" },
   "ticket.message_added": { label: "New Message on Ticket", description: "Fired when a new message is added to a ticket", category: "tickets" },