@cstar.help/js 0.18.0 → 0.18.1

package/README.md

@@ -480,6 +480,22 @@ const ticket = await cstar.tickets.create(
 );
 ```
 
+For 24 hours, the same request with the same key returns the first successful
+response. The same key with a different body throws `CStarValidationError`
+(`idempotency_key_reused`, 422). While the first request is still running, the
+API answers `409 idempotency_key_in_use` with `Retry-After`. From 0.18.1
+(unreleased), the client waits and retries within `maxRetries`; 0.18.0 throws
+`CStarConflictError`.
+
+The API ignores the key on `webhooks.create`, `webhooks.listen` and
+`export.create`, so a key does not make their retries safe: the client still
+retries a network error or 5xx. Leave the key off those calls (without one the
+client does not retry them), or use a client with `maxRetries: 0`. Check
+`webhooks.list()` before you retry `webhooks.create`. A repeated `export.create`
+only reads your data again (nothing is stored). A repeated `webhooks.listen` is a
+second CLI listener: remove it with `webhooks.unlisten(id)`, or it is swept after
+5 minutes without a heartbeat.
+
 ## Requirements
 
 - Node.js 22+ (matching the supported Supabase dependency)

package/dist/chat/index.cjs

@@ -222,6 +222,7 @@ var RealtimeManager = class {
 // src/chat/presence.ts
 var TYPING_THROTTLE_MS = 2e3;
 var TYPING_CLEAR_DELAY_MS = 3e3;
+var PRIVATE_TOPIC = { config: { private: true } };
 var PresenceManager = class {
   constructor(options) {
     this.client = null;
@@ -245,7 +246,7 @@ var PresenceManager = class {
     };
     const channelName = `typing:${ticketId}`;
     this.removeChannel(channelName);
-    const channel = this.client.channel(`ticket:${ticketId}`);
+    const channel = this.client.channel(`ticket:${ticketId}`, PRIVATE_TOPIC);
     this.channels.set(channelName, channel);
     channel.on("broadcast", { event: "typing" }, (data) => {
       if (this.channels.get(channelName) !== channel) return;
@@ -297,7 +298,7 @@ var PresenceManager = class {
       const sendChannelName = `typing-send:${ticketId}`;
       let channel = this.channels.get(sendChannelName);
       if (!channel) {
-        channel = this.client.channel(`ticket:${ticketId}`);
+        channel = this.client.channel(`ticket:${ticketId}`, PRIVATE_TOPIC);
         channel.subscribe();
         this.channels.set(sendChannelName, channel);
       }

package/dist/chat/index.js

@@ -181,6 +181,7 @@ var RealtimeManager = class {
 // src/chat/presence.ts
 var TYPING_THROTTLE_MS = 2e3;
 var TYPING_CLEAR_DELAY_MS = 3e3;
+var PRIVATE_TOPIC = { config: { private: true } };
 var PresenceManager = class {
   constructor(options) {
     this.client = null;
@@ -204,7 +205,7 @@ var PresenceManager = class {
     };
     const channelName = `typing:${ticketId}`;
     this.removeChannel(channelName);
-    const channel = this.client.channel(`ticket:${ticketId}`);
+    const channel = this.client.channel(`ticket:${ticketId}`, PRIVATE_TOPIC);
     this.channels.set(channelName, channel);
     channel.on("broadcast", { event: "typing" }, (data) => {
       if (this.channels.get(channelName) !== channel) return;
@@ -256,7 +257,7 @@ var PresenceManager = class {
       const sendChannelName = `typing-send:${ticketId}`;
       let channel = this.channels.get(sendChannelName);
       if (!channel) {
-        channel = this.client.channel(`ticket:${ticketId}`);
+        channel = this.client.channel(`ticket:${ticketId}`, PRIVATE_TOPIC);
         channel.subscribe();
         this.channels.set(sendChannelName, channel);
       }

package/dist/index.cjs

@@ -278,7 +278,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.18.0";
+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;
@@ -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);
       }

package/dist/index.d.cts

@@ -1581,6 +1581,7 @@ interface Mention {
     senderName: string | null;
     recipientId: string;
     recipientName: string | null;
+    /** The ticket's prefixed id (`tkt_*`), or null for a mention with no ticket. */
     ticketId: string | null;
     ticketTitle: string | null;
     isRead: boolean;
@@ -1674,6 +1675,11 @@ declare class AttachmentsResource {
 type CustomFieldContentType = 'ticket' | 'customer' | 'article';
 /** Input type of a custom field. */
 type CustomFieldType = 'text' | 'number' | 'date' | 'select' | 'checkbox';
+/** One choice of a `select` field. A record stores its `value`. */
+interface CustomFieldOption {
+    value: string;
+    label: string;
+}
 /** A custom field definition (mirrors `mapFieldToApi` on the server). */
 interface CustomField {
     id: string;
@@ -1683,7 +1689,7 @@ interface CustomField {
     fieldType: CustomFieldType;
     defaultValue: string | null;
     /** Choices for `select` fields. */
-    options: string[] | null;
+    options: CustomFieldOption[] | null;
     minValue: number | null;
     maxValue: number | null;
     required: boolean;
@@ -1702,7 +1708,11 @@ interface CustomFieldCreateParams {
     /** Defaults to `text`. */
     fieldType?: CustomFieldType;
     defaultValue?: string;
-    options?: string[];
+    /** Choices for `select` fields. A string is its own label. */
+    options?: Array<string | {
+        value: string;
+        label?: string;
+    }>;
     minValue?: number;
     maxValue?: number;
     required?: boolean;
@@ -1712,7 +1722,11 @@ interface CustomFieldUpdateParams {
     label?: string;
     fieldType?: CustomFieldType;
     defaultValue?: string | null;
-    options?: string[];
+    /** Replaces the choices. A string is its own label. */
+    options?: Array<string | {
+        value: string;
+        label?: string;
+    }>;
     minValue?: number | null;
     maxValue?: number | null;
     required?: boolean;
@@ -2032,7 +2046,10 @@ interface ImportCreateParams {
      * A truthy `source.body` paired with an array at `conversation_parts` or
      * `conversation_parts.conversation_parts` is also rejected, even if that
      * array is empty. Empty history without this initial-message shape,
-     * customFields/metadata and wrapped records with `action: 'skip'` are allowed.
+     * customFields and wrapped records with `action: 'skip'` are allowed (empty
+     * history and `metadata` are ignored with a row warning). camelCase field
+     * names (`customerEmail`, `externalId`) work; any field the import doesn't
+     * read is named in `warnings`.
      */
     records: Record<string, unknown>[];
     /** How to handle duplicates. Defaults to `'overwrite'`. */
@@ -2041,8 +2058,8 @@ interface ImportCreateParams {
 /** Import result. */
 interface ImportResult {
     object: 'import_result';
-    /** ID of the persisted import-log row (null if the log row could not be written). */
-    logId: string | null;
+    /** ID of the import's log row (GET /import/logs/{logId}, `import.getLog()`). */
+    logId: string;
     /** Entity type imported — `ticket`, `customer`, or `article`. */
     entityType: string;
     /** True when every record imported without error. */
@@ -2066,18 +2083,28 @@ interface ImportResult {
 interface ImportLog {
     id: string;
     object: 'import_log';
-    resource: string;
-    status: string;
+    /** `ticket`, `customer` or `article`. */
+    entityType: string;
+    /** `api` for REST imports, or the platform the dashboard importer read. */
+    sourcePlatform: string | null;
+    sourceFilename: string | null;
     totalRecords: number;
     created: number;
     updated: number;
     skipped: number;
-    errors: number;
+    failed: number;
+    /** The failed rows, as "Row N: ..." lines, or null. */
+    errors: string[] | null;
+    matchKey: string | null;
+    mergeStrategy: Record<string, string> | null;
+    /** When the import finished; null while it runs. */
+    completedAt: string | null;
     createdAt: string;
 }
 /** Parameters for listing import logs. */
 interface ImportLogListParams extends PaginationParams {
-    resource?: string;
+    /** Only imports of this kind. */
+    resource?: 'tickets' | 'customers' | 'articles';
 }
 
 /** Export data from your team. */

package/dist/index.d.ts

@@ -1581,6 +1581,7 @@ interface Mention {
     senderName: string | null;
     recipientId: string;
     recipientName: string | null;
+    /** The ticket's prefixed id (`tkt_*`), or null for a mention with no ticket. */
     ticketId: string | null;
     ticketTitle: string | null;
     isRead: boolean;
@@ -1674,6 +1675,11 @@ declare class AttachmentsResource {
 type CustomFieldContentType = 'ticket' | 'customer' | 'article';
 /** Input type of a custom field. */
 type CustomFieldType = 'text' | 'number' | 'date' | 'select' | 'checkbox';
+/** One choice of a `select` field. A record stores its `value`. */
+interface CustomFieldOption {
+    value: string;
+    label: string;
+}
 /** A custom field definition (mirrors `mapFieldToApi` on the server). */
 interface CustomField {
     id: string;
@@ -1683,7 +1689,7 @@ interface CustomField {
     fieldType: CustomFieldType;
     defaultValue: string | null;
     /** Choices for `select` fields. */
-    options: string[] | null;
+    options: CustomFieldOption[] | null;
     minValue: number | null;
     maxValue: number | null;
     required: boolean;
@@ -1702,7 +1708,11 @@ interface CustomFieldCreateParams {
     /** Defaults to `text`. */
     fieldType?: CustomFieldType;
     defaultValue?: string;
-    options?: string[];
+    /** Choices for `select` fields. A string is its own label. */
+    options?: Array<string | {
+        value: string;
+        label?: string;
+    }>;
     minValue?: number;
     maxValue?: number;
     required?: boolean;
@@ -1712,7 +1722,11 @@ interface CustomFieldUpdateParams {
     label?: string;
     fieldType?: CustomFieldType;
     defaultValue?: string | null;
-    options?: string[];
+    /** Replaces the choices. A string is its own label. */
+    options?: Array<string | {
+        value: string;
+        label?: string;
+    }>;
     minValue?: number | null;
     maxValue?: number | null;
     required?: boolean;
@@ -2032,7 +2046,10 @@ interface ImportCreateParams {
      * A truthy `source.body` paired with an array at `conversation_parts` or
      * `conversation_parts.conversation_parts` is also rejected, even if that
      * array is empty. Empty history without this initial-message shape,
-     * customFields/metadata and wrapped records with `action: 'skip'` are allowed.
+     * customFields and wrapped records with `action: 'skip'` are allowed (empty
+     * history and `metadata` are ignored with a row warning). camelCase field
+     * names (`customerEmail`, `externalId`) work; any field the import doesn't
+     * read is named in `warnings`.
      */
     records: Record<string, unknown>[];
     /** How to handle duplicates. Defaults to `'overwrite'`. */
@@ -2041,8 +2058,8 @@ interface ImportCreateParams {
 /** Import result. */
 interface ImportResult {
     object: 'import_result';
-    /** ID of the persisted import-log row (null if the log row could not be written). */
-    logId: string | null;
+    /** ID of the import's log row (GET /import/logs/{logId}, `import.getLog()`). */
+    logId: string;
     /** Entity type imported — `ticket`, `customer`, or `article`. */
     entityType: string;
     /** True when every record imported without error. */
@@ -2066,18 +2083,28 @@ interface ImportResult {
 interface ImportLog {
     id: string;
     object: 'import_log';
-    resource: string;
-    status: string;
+    /** `ticket`, `customer` or `article`. */
+    entityType: string;
+    /** `api` for REST imports, or the platform the dashboard importer read. */
+    sourcePlatform: string | null;
+    sourceFilename: string | null;
     totalRecords: number;
     created: number;
     updated: number;
     skipped: number;
-    errors: number;
+    failed: number;
+    /** The failed rows, as "Row N: ..." lines, or null. */
+    errors: string[] | null;
+    matchKey: string | null;
+    mergeStrategy: Record<string, string> | null;
+    /** When the import finished; null while it runs. */
+    completedAt: string | null;
     createdAt: string;
 }
 /** Parameters for listing import logs. */
 interface ImportLogListParams extends PaginationParams {
-    resource?: string;
+    /** Only imports of this kind. */
+    resource?: 'tickets' | 'customers' | 'articles';
 }
 
 /** Export data from your team. */

package/dist/index.js

@@ -237,7 +237,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.18.0";
+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;
@@ -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);
       }

package/package.json

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