@cstar.help/js 0.17.5 → 0.18.1

package/dist/index.js

@@ -237,7 +237,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;
@@ -257,7 +257,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) {
@@ -316,10 +316,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;
@@ -359,6 +361,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);
       }
@@ -489,6 +499,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;
@@ -564,7 +576,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();
     }
@@ -624,6 +636,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) {
@@ -633,6 +646,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",
@@ -761,6 +777,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);
   }
@@ -1480,11 +1530,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
@@ -1509,8 +1565,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. */
@@ -1584,15 +1642,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) {
@@ -1608,16 +1673,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", {
@@ -1652,11 +1713,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) {
@@ -1845,25 +1904,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);
   }
 };
 
@@ -2309,7 +2371,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
@@ -2545,7 +2607,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"
     }
@@ -2765,15 +2827,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"
       }
     }
   },
@@ -2806,7 +2867,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": {
@@ -2872,7 +2933,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" },

package/dist/proactive/index.cjs

@@ -23,51 +23,64 @@ __export(proactive_exports, {
   ProactiveClient: () => ProactiveClient
 });
 module.exports = __toCommonJS(proactive_exports);
-var DEFAULT_BASE_URL = "https://www.cstar.help";
-function createRageClickDetector(onSignal) {
+
+// src/proactive/rageClick.ts
+var INTERACTIVE_SELECTOR = 'a[href], button, input, select, textarea, label, summary, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="tab"], [role="menuitem"], [role="option"], [contenteditable="true"], [contenteditable=""]';
+var RAGE_CLICK_THRESHOLD = 3;
+var RAGE_CLICK_WINDOW_MS = 1e3;
+var RAGE_CLICK_RADIUS_PX = 30;
+var RAGE_CLICK_DEBOUNCE_MS = 2e3;
+function describe(el) {
+  let context = el.tagName ? "on " + el.tagName.toLowerCase() : "";
+  if (typeof el.className === "string") {
+    const cls = el.className.split(" ")[0];
+    if (cls) context += "." + cls;
+  }
+  return context;
+}
+function createRageClickDetector(onSignal, doc) {
   let clicks = [];
   let lastFired = 0;
   let handler = null;
+  function onClick(e) {
+    const now = Date.now();
+    const target = e.target;
+    if (!target || typeof target.closest !== "function" || target.closest(INTERACTIVE_SELECTOR)) {
+      clicks = [];
+      return;
+    }
+    clicks = clicks.filter((c) => now - c.t < RAGE_CLICK_WINDOW_MS && c.target === target);
+    clicks.push({ x: e.clientX, y: e.clientY, t: now, target });
+    if (clicks.length < RAGE_CLICK_THRESHOLD || now - lastFired <= RAGE_CLICK_DEBOUNCE_MS) return;
+    const first = clicks[0];
+    const allClose = clicks.every(
+      (c) => Math.hypot(first.x - c.x, first.y - c.y) <= RAGE_CLICK_RADIUS_PX
+    );
+    if (!allClose) return;
+    lastFired = now;
+    onSignal({
+      type: "rage_click",
+      confidence: Math.min(1, clicks.length / 5),
+      context: `Clicked ${clicks.length} times rapidly ${describe(target)}`,
+      timestamp: now
+    });
+    clicks = [];
+  }
   return {
     start() {
-      handler = (e) => {
-        const now = Date.now();
-        clicks = clicks.filter((c) => now - c.t < 500);
-        clicks.push({ x: e.clientX, y: e.clientY, t: now });
-        if (clicks.length >= 3 && now - lastFired > 2e3) {
-          const first = clicks[0];
-          const allClose = clicks.every((c) => {
-            const dx = first.x - c.x;
-            const dy = first.y - c.y;
-            return Math.sqrt(dx * dx + dy * dy) <= 50;
-          });
-          if (allClose) {
-            lastFired = now;
-            const el = e.target;
-            let context = el?.tagName ? "on " + el.tagName.toLowerCase() : "";
-            if (el?.className && typeof el.className === "string") {
-              const cls = el.className.split(" ")[0];
-              if (cls) context += "." + cls;
-            }
-            onSignal({
-              type: "rage_click",
-              confidence: Math.min(1, clicks.length / 5),
-              context: `Clicked ${clicks.length} times rapidly ${context}`,
-              timestamp: now
-            });
-            clicks = [];
-          }
-        }
-      };
-      document.addEventListener("click", handler, true);
+      handler = onClick;
+      (doc ?? document).addEventListener("click", handler, true);
     },
     stop() {
-      if (handler) document.removeEventListener("click", handler, true);
+      if (handler) (doc ?? document).removeEventListener("click", handler, true);
       handler = null;
       clicks = [];
     }
   };
 }
+
+// src/proactive/index.ts
+var DEFAULT_BASE_URL = "https://www.cstar.help";
 function createExitIntentDetector(onSignal) {
   let fired = false;
   let handler = null;

package/dist/proactive/index.js

@@ -1,49 +1,60 @@
-// src/proactive/index.ts
-var DEFAULT_BASE_URL = "https://www.cstar.help";
-function createRageClickDetector(onSignal) {
+// src/proactive/rageClick.ts
+var INTERACTIVE_SELECTOR = 'a[href], button, input, select, textarea, label, summary, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="tab"], [role="menuitem"], [role="option"], [contenteditable="true"], [contenteditable=""]';
+var RAGE_CLICK_THRESHOLD = 3;
+var RAGE_CLICK_WINDOW_MS = 1e3;
+var RAGE_CLICK_RADIUS_PX = 30;
+var RAGE_CLICK_DEBOUNCE_MS = 2e3;
+function describe(el) {
+  let context = el.tagName ? "on " + el.tagName.toLowerCase() : "";
+  if (typeof el.className === "string") {
+    const cls = el.className.split(" ")[0];
+    if (cls) context += "." + cls;
+  }
+  return context;
+}
+function createRageClickDetector(onSignal, doc) {
   let clicks = [];
   let lastFired = 0;
   let handler = null;
+  function onClick(e) {
+    const now = Date.now();
+    const target = e.target;
+    if (!target || typeof target.closest !== "function" || target.closest(INTERACTIVE_SELECTOR)) {
+      clicks = [];
+      return;
+    }
+    clicks = clicks.filter((c) => now - c.t < RAGE_CLICK_WINDOW_MS && c.target === target);
+    clicks.push({ x: e.clientX, y: e.clientY, t: now, target });
+    if (clicks.length < RAGE_CLICK_THRESHOLD || now - lastFired <= RAGE_CLICK_DEBOUNCE_MS) return;
+    const first = clicks[0];
+    const allClose = clicks.every(
+      (c) => Math.hypot(first.x - c.x, first.y - c.y) <= RAGE_CLICK_RADIUS_PX
+    );
+    if (!allClose) return;
+    lastFired = now;
+    onSignal({
+      type: "rage_click",
+      confidence: Math.min(1, clicks.length / 5),
+      context: `Clicked ${clicks.length} times rapidly ${describe(target)}`,
+      timestamp: now
+    });
+    clicks = [];
+  }
   return {
     start() {
-      handler = (e) => {
-        const now = Date.now();
-        clicks = clicks.filter((c) => now - c.t < 500);
-        clicks.push({ x: e.clientX, y: e.clientY, t: now });
-        if (clicks.length >= 3 && now - lastFired > 2e3) {
-          const first = clicks[0];
-          const allClose = clicks.every((c) => {
-            const dx = first.x - c.x;
-            const dy = first.y - c.y;
-            return Math.sqrt(dx * dx + dy * dy) <= 50;
-          });
-          if (allClose) {
-            lastFired = now;
-            const el = e.target;
-            let context = el?.tagName ? "on " + el.tagName.toLowerCase() : "";
-            if (el?.className && typeof el.className === "string") {
-              const cls = el.className.split(" ")[0];
-              if (cls) context += "." + cls;
-            }
-            onSignal({
-              type: "rage_click",
-              confidence: Math.min(1, clicks.length / 5),
-              context: `Clicked ${clicks.length} times rapidly ${context}`,
-              timestamp: now
-            });
-            clicks = [];
-          }
-        }
-      };
-      document.addEventListener("click", handler, true);
+      handler = onClick;
+      (doc ?? document).addEventListener("click", handler, true);
     },
     stop() {
-      if (handler) document.removeEventListener("click", handler, true);
+      if (handler) (doc ?? document).removeEventListener("click", handler, true);
       handler = null;
       clicks = [];
     }
   };
 }
+
+// src/proactive/index.ts
+var DEFAULT_BASE_URL = "https://www.cstar.help";
 function createExitIntentDetector(onSignal) {
   let fired = false;
   let handler = null;

package/dist/webhook/index.d.cts

@@ -1,4 +1,4 @@
-import { d as WebhookEvent } from '../webhookEvents-1N2i2GcQ.cjs';
+import { d as WebhookEvent } from '../webhookEvents-Lqpsj935.cjs';
 
 /** Default replay window for Stripe-style signatures: 5 minutes (300s). */
 declare const DEFAULT_TOLERANCE_SECONDS = 300;

package/dist/webhook/index.d.ts

@@ -1,4 +1,4 @@
-import { d as WebhookEvent } from '../webhookEvents-1N2i2GcQ.js';
+import { d as WebhookEvent } from '../webhookEvents-Lqpsj935.js';
 
 /** Default replay window for Stripe-style signatures: 5 minutes (300s). */
 declare const DEFAULT_TOLERANCE_SECONDS = 300;

package/dist/webhook/node.d.cts

@@ -1,4 +1,4 @@
-import { d as WebhookEvent } from '../webhookEvents-1N2i2GcQ.cjs';
+import { d as WebhookEvent } from '../webhookEvents-Lqpsj935.cjs';
 import { VerifyOptions } from './index.cjs';
 export { DEFAULT_TOLERANCE_SECONDS, WebhookSignatureVerificationError } from './index.cjs';
 

package/dist/webhook/node.d.ts

@@ -1,4 +1,4 @@
-import { d as WebhookEvent } from '../webhookEvents-1N2i2GcQ.js';
+import { d as WebhookEvent } from '../webhookEvents-Lqpsj935.js';
 import { VerifyOptions } from './index.js';
 export { DEFAULT_TOLERANCE_SECONDS, WebhookSignatureVerificationError } from './index.js';
 

package/dist/{webhookEvents-1N2i2GcQ.d.cts → webhookEvents-Lqpsj935.d.cts}

@@ -314,7 +314,6 @@ interface TicketClosedPayload {
         status: string;
         priority: string;
         channel: string;
-        resolved_at: string;
     };
     changes?: Record<string, {
         from: string;

package/dist/{webhookEvents-1N2i2GcQ.d.ts → webhookEvents-Lqpsj935.d.ts}

@@ -314,7 +314,6 @@ interface TicketClosedPayload {
         status: string;
         priority: string;
         channel: string;
-        resolved_at: string;
     };
     changes?: Record<string, {
         from: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/js",
-	"version": "0.17.5",
+	"version": "0.18.1",
 	"description": "Official TypeScript SDK for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",