@cstar.help/js 0.17.4 → 0.18.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { W as WebhookEventType, a as WebhookEventDataMap } from './webhookEvents-1N2i2GcQ.cjs';
-export { b as WEBHOOK_EVENT_CATALOG, c as WEBHOOK_EVENT_SAMPLES, d as WebhookEvent } from './webhookEvents-1N2i2GcQ.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, h as CStarServerError, i as CStarValidationError, E as ErrorType } from './errors-b5A4wfAg.cjs';
+import { W as WebhookEventType, a as WebhookEventDataMap } from './webhookEvents-Lqpsj935.cjs';
+export { b as WEBHOOK_EVENT_CATALOG, c as WEBHOOK_EVENT_SAMPLES, d as WebhookEvent } from './webhookEvents-Lqpsj935.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, h as CStarServerError, i as CStarValidationError, E as ErrorType } from './errors-bW8CwTn4.cjs';
 
 /** Metadata: string key-value pairs. Max 50 keys, 40-char keys, 500-char values. */
 type Metadata = Record<string, string>;
@@ -210,6 +210,8 @@ declare class CStarRealtime {
     private retryTimer;
     private _connected;
     private destroyed;
+    /** The server closed the stream because the API key was revoked or expired. */
+    private revoked;
     private connecting;
     /** Short-lived SSE token (exchanged from secret key). */
     private sseToken;
@@ -259,6 +261,7 @@ declare class CStarRealtime {
     private dispatch;
     private scheduleReconnect;
     private setConnected;
+    private handleRevoked;
     private emitError;
     /** Whether we hold a token that won't expire for at least 30 seconds. */
     private hasFreshSseToken;
@@ -279,6 +282,9 @@ declare class CStarRealtime {
 interface Message {
     id: string;
     object: 'message';
+    ticketId: string;
+    /** True for a note visible only to the support team. */
+    isInternal: boolean;
     sender: 'customer' | 'agent' | 'system';
     content: string;
     senderId: string | null;
@@ -293,15 +299,41 @@ interface MessageCreateParams {
     sender?: 'customer' | 'agent' | 'system';
     senderId?: string;
     senderName?: string;
+    messageType?: 'public' | 'internal';
+    /** Boolean alias for messageType. If both are supplied, they must agree. */
+    isInternal?: boolean;
 }
+/** Pagination options for a ticket message history. */
+type MessageListParams = PaginationParams;
 
+/**
+ * One of the team's priority keys, highest first in GET /settings
+ * (`priorities[].key`), for example `critical`, `high`, `normal`, `low`.
+ * Teams can rename and add priorities, so this is not a fixed list. A key
+ * the team doesn't have fails with a 400 `parameter_invalid` that lists
+ * the allowed keys.
+ */
+type TicketPriorityKey = string;
+/**
+ * One of the team's ticket status keys from GET /settings
+ * (`ticketStatuses[].key`), for example `new`, `open`, `pending`,
+ * `waiting_on_customer`, `resolved`, `closed`. `merged` is set only by
+ * merging tickets. Other values fail with a 400 `parameter_invalid`.
+ */
+type TicketStatusKey = string;
+/**
+ * Ticket custom field values as sent: numbers and booleans are stored as
+ * strings, and null clears a value.
+ */
+type TicketCustomFieldValues = Record<string, string | number | boolean | null>;
 /** A cStar support ticket. */
 interface Ticket {
     id: string;
     object: 'ticket';
+    /** Ticket subject. New subjects are at most 255 characters; tickets created earlier may be longer. */
     title: string;
-    priority: 'low' | 'normal' | 'high' | 'urgent';
-    status: string;
+    priority: TicketPriorityKey;
+    status: TicketStatusKey;
     customerId: string | null;
     customerName: string | null;
     assignedTo: string | null;
@@ -315,6 +347,8 @@ interface Ticket {
     resolutionTier: string | null;
     slaPaused: boolean;
     metadata: Metadata;
+    /** Custom field values keyed by field ID, stored as strings ('42', 'true', an option value). */
+    customFields: Record<string, string>;
     createdAt: string;
     closedAt: string | null;
     updatedAt: string;
@@ -334,34 +368,62 @@ interface TicketCustomerSummary {
 }
 /** Parameters for listing tickets. */
 interface TicketListParams extends PaginationParams {
-    status?: string;
-    priority?: 'low' | 'normal' | 'high' | 'urgent';
+    status?: TicketStatusKey;
+    priority?: TicketPriorityKey;
     customerId?: string;
     assignedTo?: string;
     search?: string;
     expand?: string[];
 }
+/**
+ * An opening message sent with a new ticket. Same rules as adding a message
+ * later: unknown fields, another sender, or `messageType` and `isInternal`
+ * that disagree fail with a 400 whose `param` names the item, e.g.
+ * `messages[1].sender`.
+ */
+interface TicketSeedMessage {
+    sender: 'customer' | 'agent' | 'system';
+    content: string;
+    /** `true` saves a private team note the customer never sees. */
+    isInternal?: boolean;
+    /** Defaults to `public`. */
+    messageType?: 'public' | 'internal';
+}
 /** Parameters for creating a ticket. */
 interface TicketCreateParams {
+    /** Ticket subject, 1 to 255 characters. Longer values fail with a 400 whose `param` is `title`. */
     title: string;
-    priority?: 'low' | 'normal' | 'high' | 'urgent';
-    status?: string;
+    priority?: TicketPriorityKey;
+    status?: TicketStatusKey;
     customerId?: string;
+    /** Email of an existing customer on the team, used when `customerId` is not set. */
+    customerEmail?: string;
     customerName?: string;
+    /** Opening messages, oldest first. */
+    messages?: TicketSeedMessage[];
     tags?: string[];
     notes?: string;
+    /** Values keyed by ticket custom field ID; each must fit its field's type (400 otherwise). */
+    customFields?: TicketCustomFieldValues;
     metadata?: Metadata;
 }
-/** Parameters for updating a ticket. */
+/**
+ * Parameters for updating a ticket. The customer cannot be changed after
+ * creation; the API rejects unknown fields.
+ */
 interface TicketUpdateParams {
+    /**
+     * New subject, at most 255 characters (400 with `param: 'title'` otherwise).
+     * Re-sending an older ticket's unchanged, longer subject is accepted.
+     */
     title?: string;
-    priority?: 'low' | 'normal' | 'high' | 'urgent';
-    status?: string;
-    customerId?: string | null;
-    customerName?: string;
+    priority?: TicketPriorityKey;
+    status?: TicketStatusKey;
     assignedTo?: string | null;
     tags?: string[];
     notes?: string;
+    /** Replaces all values, keyed by custom field ID. null or '' clears one. */
+    customFields?: TicketCustomFieldValues;
     metadata?: Record<string, string | null>;
 }
 
@@ -471,8 +533,8 @@ declare abstract class BaseResource<TEntity, TListParams extends PaginationParam
 declare class TicketMessagesResource {
     private readonly client;
     constructor(client: HttpClient);
-    /** List all messages on a ticket. */
-    list(ticketId: string): Promise<ListResponse<Message>>;
+    /** List one page of a ticket history. Use pagination.hasMore to request the next page. */
+    list(ticketId: string, params?: MessageListParams): Promise<ListResponse<Message>>;
     /** Add a message to a ticket. */
     create(ticketId: string, params: MessageCreateParams, options?: RequestOptions): Promise<Message>;
 }
@@ -535,6 +597,11 @@ declare class CustomersResource extends BaseResource<Customer, CustomerListParam
     constructor(client: HttpClient);
 }
 
+/**
+ * One of the team's article statuses (GET /settings `articleStatuses`).
+ * Every team has draft and published; a team may add its own (archived, ...).
+ */
+type ArticleStatus = 'draft' | 'published' | (string & {});
 /** A cStar knowledge base article. */
 interface Article {
     id: string;
@@ -544,7 +611,7 @@ interface Article {
     excerpt: string | null;
     content: string | null;
     categoryId: string | null;
-    status: 'draft' | 'published';
+    status: ArticleStatus;
     tags: string[];
     notes: string | null;
     viewCount: number;
@@ -559,8 +626,9 @@ interface Article {
 }
 /** Parameters for listing articles. */
 interface ArticleListParams extends PaginationParams {
+    /** Category UUID. The API rejects names and slugs. */
     category?: string;
-    status?: 'draft' | 'published';
+    status?: ArticleStatus;
     isPublic?: boolean;
     search?: string;
     tag?: string;
@@ -572,7 +640,7 @@ interface ArticleCreateParams {
     content?: string;
     excerpt?: string;
     categoryId?: string;
-    status?: 'draft' | 'published';
+    status?: ArticleStatus;
     tags?: string[];
     notes?: string;
     isPublic?: boolean;
@@ -585,8 +653,9 @@ interface ArticleUpdateParams {
     title?: string;
     content?: string;
     excerpt?: string;
-    categoryId?: string;
-    status?: 'draft' | 'published';
+    /** Category UUID, or null to clear it. */
+    categoryId?: string | null;
+    status?: ArticleStatus;
     tags?: string[];
     notes?: string;
     isPublic?: boolean;
@@ -1228,27 +1297,26 @@ interface StatusUpdateParams {
 /** A quick reply template. */
 interface QuickReply {
     id: string;
-    object: 'quick_reply';
     title: string;
+    /** Reply text. Mirrors `text` for older rows. */
     body: string;
-    category: string | null;
-    position: number;
-    createdAt: string;
-    updatedAt: string;
+    text: string;
 }
-/** Parameters for creating a quick reply. */
+/** Parameters for creating a quick reply. The API rejects any other field. */
 interface QuickReplyCreateParams {
     title: string;
     body: string;
-    category?: string;
 }
-/** Parameters for updating a quick reply. */
+/** Parameters for updating a quick reply. The API rejects any other field. */
 interface QuickReplyUpdateParams {
     title?: string;
     body?: string;
-    category?: string;
 }
-/** Business hours configuration. */
+/**
+ * The chat widget's online hours. When `enabled`, the widget shows its
+ * offline message outside them. Not the SLA working hours in the
+ * dashboard's Settings > Business Hours, which SLA deadlines use.
+ */
 interface BusinessHours {
     object: 'business_hours';
     enabled: boolean;
@@ -1259,7 +1327,7 @@ interface BusinessHours {
         end: string;
     }>;
 }
-/** Parameters for updating business hours. */
+/** Parameters for updating the chat widget's online hours. */
 interface BusinessHoursUpdateParams {
     enabled?: boolean;
     timezone?: string;
@@ -1269,14 +1337,126 @@ interface BusinessHoursUpdateParams {
         end: string;
     }>;
 }
+/** A chat widget entrance effect: a preset, `custom` (your own) or `none`. */
+type WidgetEntranceEffect = 'none' | 'puff' | 'confetti' | 'sparkle' | 'pop' | 'slide' | 'custom';
+/**
+ * One frame of a custom entrance. Missing values are neutral; the element
+ * always ends in its own styles.
+ */
+interface WidgetEntranceKeyframe {
+    /** 0 to 1. */
+    opacity?: number;
+    /** 0 to 3. */
+    scale?: number;
+    /** -168 to 168 px. */
+    translateX?: number;
+    /** -168 to 168 px. */
+    translateY?: number;
+    /** -360 to 360 degrees. */
+    rotate?: number;
+}
+/** Particles thrown from the launcher by a custom entrance. */
+interface WidgetEntranceParticles {
+    /** 1 to 34. Default 13. */
+    count?: number;
+    shape?: 'circle' | 'square' | 'star';
+    /** 1 to 5 hex colours. Default: a confetti mix plus your widget colour. */
+    colors?: string[] | null;
+    /** Degrees of the cone, 0 to 360. Default 360. */
+    spread?: number;
+    /** Degrees, 0 is straight up, -180 to 180. Default 0. */
+    direction?: number;
+    /** Pixels, 0 to 168. Default 84. */
+    distance?: number;
+    /** Pixels, 2 to 21. Default 8. */
+    size?: number;
+    /** A multiple of 42, up to 840. Default 630. */
+    durationMs?: number;
+    /** A multiple of 42; with durationMs at most 840. Default 0. */
+    delayMs?: number;
+}
+/** Your own entrance, played by a moment set to `custom`. */
+interface WidgetEntranceCustom {
+    /** 2 to 5 evenly spaced frames. */
+    keyframes?: WidgetEntranceKeyframe[] | null;
+    /** A multiple of 42, up to 840. Default 420. */
+    durationMs?: number;
+    /** A multiple of 42; with durationMs at most 840. Default 0. */
+    delayMs?: number;
+    easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'bounce';
+    particles?: WidgetEntranceParticles | null;
+}
+/**
+ * Chat widget entrance effects: `launcher` plays when the chat button first
+ * appears on a page, `open` when someone opens the chat. Visitors who ask
+ * for reduced motion see none.
+ */
+interface WidgetEntrance {
+    launcher?: WidgetEntranceEffect;
+    open?: WidgetEntranceEffect;
+    custom?: WidgetEntranceCustom | null;
+}
 /** Widget configuration. */
 interface WidgetSettings {
-    object: 'widget_settings';
+    object: 'widget_config';
+    /** Always complete in responses (`none` when unset). */
+    entrance: Required<Pick<WidgetEntrance, 'launcher' | 'open'>> & {
+        custom: WidgetEntranceCustom | null;
+    };
     [key: string]: unknown;
 }
-/** Parameters for updating widget settings. */
+/**
+ * Parameters for updating widget settings. Only the fields you send change.
+ * Text over its limit is rejected with a 413. Strings, primaryColor, the URLs,
+ * theme, position, mode and entrance are checked (400); the booleans and
+ * libraryBorderRadius are saved as sent.
+ */
 interface WidgetSettingsUpdateParams {
-    [key: string]: unknown;
+    /** Hex only: `#rgb` or `#rrggbb`. */
+    primaryColor?: string;
+    theme?: 'light' | 'dark';
+    position?: 'bottom-right' | 'bottom-left';
+    /** Text on the chat button, up to 30 characters. */
+    launcherText?: string;
+    /** Up to 500 characters. */
+    welcomeMessage?: string;
+    /** Shown outside business hours, up to 500 characters. */
+    offlineMessage?: string;
+    /** Up to 200 characters. */
+    companyName?: string;
+    /** An http or https URL, up to 2,000 characters. An empty string clears it. */
+    termsUrl?: string;
+    /** An http or https URL, up to 2,000 characters. An empty string clears it. */
+    privacyUrl?: string;
+    /** `script` runs the embed snippet; `sdk` leaves it off for your own UI. */
+    mode?: 'script' | 'sdk';
+    isEnabled?: boolean;
+    showOnLibraryPages?: boolean;
+    /** Saved for older setups only: widget sign-ups always confirm their email. */
+    requireCustomerEmailConfirmation?: boolean;
+    businessHoursEnabled?: boolean;
+    /** Help center colours: any CSS colour, up to 50 characters. */
+    libraryBgColor?: string;
+    libraryCardColor?: string;
+    libraryTextColor?: string;
+    libraryTextSecondaryColor?: string;
+    libraryBorderColor?: string;
+    libraryAccentColor?: string;
+    /** Font names, up to 100 characters. */
+    libraryFontHeading?: string;
+    libraryFontBody?: string;
+    /** A CSS length such as `12px`. */
+    libraryBorderRadius?: string;
+    /**
+     * Entrance effects, merged per key over the saved ones: `launcher`,
+     * `open` and `custom` change only when sent, and `null` resets that key
+     * (`none`, or no custom effect). `entrance: null` turns them all off.
+     */
+    entrance?: {
+        launcher?: WidgetEntranceEffect | null;
+        open?: WidgetEntranceEffect | null;
+        custom?: WidgetEntranceCustom | null;
+    } | null;
 }
 
 /** Manage ticket status configurations. */
@@ -1321,9 +1501,15 @@ declare class SettingsResource {
     get(): Promise<ApiResponse<TeamSettings>>;
     /** Update team settings (bulk). */
     update(params: TeamSettingsUpdateParams): Promise<ApiResponse<TeamSettings>>;
-    /** 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.
+     */
     getBusinessHours(): Promise<ApiResponse<BusinessHours>>;
-    /** 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.
+     */
     updateBusinessHours(params: BusinessHoursUpdateParams): Promise<ApiResponse<BusinessHours>>;
     /** Get widget settings. */
     getWidget(): Promise<ApiResponse<WidgetSettings>>;
@@ -1331,29 +1517,38 @@ declare class SettingsResource {
     updateWidget(params: WidgetSettingsUpdateParams): Promise<ApiResponse<WidgetSettings>>;
 }
 
-/** A notification. */
+/** A notification (mirrors `mapNotificationToApi` on the server). */
 interface Notification {
     id: string;
     object: 'notification';
     type: string;
     title: string;
     body: string | null;
-    resourceType: string | null;
-    resourceId: string | null;
+    ticketId: string | null;
     actorId: string | null;
     actorName: string | null;
-    read: boolean;
+    priority: string;
+    /** Whether the user in `userId` has read it. */
+    isRead: boolean;
     readAt: string | null;
+    isAdminNotification: boolean;
+    expiresAt: string | null;
     createdAt: string;
 }
 /** Parameters for listing notifications. */
 interface NotificationListParams extends PaginationParams {
+    /** Filter by notification type (for example `assigned`). */
+    type?: string;
+    /** `false` for unread only, `true` for read only. */
+    isRead?: boolean;
+    /** @deprecated Use `isRead: false`. Sent as `isRead=false`. */
     unreadOnly?: boolean;
 }
 /** Unread count response. */
 interface UnreadCount {
-    object: 'unread_count';
-    count: number;
+    unreadCount: number;
+    /** True when the count hit the server's scan cap and may be higher. */
+    truncated: boolean;
 }
 
 /** Manage notifications. */
@@ -1421,80 +1616,115 @@ declare class MentionsResource {
     }>>;
 }
 
-/** A file attachment. */
+/** Storage bucket a message file lives in. `attachments` holds chat widget uploads. */
+type AttachmentBucket = 'email-attachments' | 'ticket-attachments' | 'avatars' | 'attachments';
+/**
+ * A message file from `attachments.list()`. Storage is private: `url` is a
+ * signed link that works for `expiresIn` seconds (300). Do not store it; list
+ * again or call `attachments.get(storagePath, { bucket })` for a fresh one.
+ * `url`, `storagePath`, `bucket` and `expiresIn` are null when the file
+ * cannot be signed.
+ */
 interface Attachment {
     id: string;
     object: 'attachment';
-    filename: string;
-    contentType: string;
-    size: number;
-    url: string;
-    ticketId: string | null;
-    uploadedBy: string | null;
+    messageId: string;
+    ticketId: string;
+    filename: string | null;
+    contentType: string | null;
+    sizeBytes: number | null;
     createdAt: string;
+    url: string | null;
+    storagePath: string | null;
+    bucket: AttachmentBucket | null;
+    expiresIn: number | null;
 }
 /** Parameters for listing attachments. */
 interface AttachmentListParams extends PaginationParams {
     ticketId?: string;
 }
+/** Parameters for a signed download URL. */
+interface AttachmentGetParams {
+    /** Defaults to `email-attachments` on the server. */
+    bucket?: AttachmentBucket;
+}
+/** A signed download URL from `attachments.get()`. A bearer link until it expires. */
+interface AttachmentDownloadUrl {
+    url: string;
+    /** Seconds until `url` stops working (300). */
+    expiresIn: number;
+}
 
 /** Manage file attachments. */
 declare class AttachmentsResource {
     private readonly client;
     constructor(client: HttpClient);
-    /** List attachments. */
+    /** List message files, each with a short-lived signed `url`. */
     list(params?: AttachmentListParams): Promise<ListResponse<Attachment>>;
-    /** Get a single attachment. */
-    get(attachmentId: string): Promise<ApiResponse<Attachment>>;
+    /**
+     * Get a signed download URL, valid for `expiresIn` seconds, for a stored
+     * file. Pass `storagePath` and `bucket` from `list()`.
+     */
+    get(storagePath: string, params?: AttachmentGetParams): Promise<AttachmentDownloadUrl>;
     /** Delete an attachment. */
     del(attachmentId: string): Promise<ApiResponse<DeleteResponse>>;
 }
 
-/** A custom field definition. */
+/** Record type a custom field belongs to. */
+type CustomFieldContentType = 'ticket' | 'customer' | 'article';
+/** Input type of a custom field. */
+type CustomFieldType = 'text' | 'number' | 'date' | 'select' | 'checkbox';
+/** A custom field definition (mirrors `mapFieldToApi` on the server). */
 interface CustomField {
     id: string;
     object: 'custom_field';
-    name: string;
-    key: string;
-    type: 'text' | 'number' | 'select' | 'multiselect' | 'date' | 'boolean';
-    entityType: 'tickets' | 'customers';
-    description: string | null;
-    required: boolean;
+    contentType: CustomFieldContentType;
+    label: string;
+    fieldType: CustomFieldType;
+    defaultValue: string | null;
+    /** Choices for `select` fields. */
     options: string[] | null;
-    position: number;
+    minValue: number | null;
+    maxValue: number | null;
+    required: boolean;
+    sortOrder: number;
     createdAt: string;
-    updatedAt: string;
 }
 /** Parameters for listing custom fields. */
-interface CustomFieldListParams extends PaginationParams {
-    entityType?: 'tickets' | 'customers';
+interface CustomFieldListParams {
+    /** Only fields for this record type. */
+    entity?: CustomFieldContentType;
 }
 /** Parameters for creating a custom field. */
 interface CustomFieldCreateParams {
-    name: string;
-    key: string;
-    type: 'text' | 'number' | 'select' | 'multiselect' | 'date' | 'boolean';
-    entityType: 'tickets' | 'customers';
-    description?: string;
-    required?: boolean;
+    contentType: CustomFieldContentType;
+    label: string;
+    /** Defaults to `text`. */
+    fieldType?: CustomFieldType;
+    defaultValue?: string;
     options?: string[];
+    minValue?: number;
+    maxValue?: number;
+    required?: boolean;
 }
-/** Parameters for updating a custom field. */
+/** Parameters for updating a custom field. `contentType` cannot change. */
 interface CustomFieldUpdateParams {
-    name?: string;
-    description?: string;
-    required?: boolean;
+    label?: string;
+    fieldType?: CustomFieldType;
+    defaultValue?: string | null;
     options?: string[];
+    minValue?: number | null;
+    maxValue?: number | null;
+    required?: boolean;
+    sortOrder?: number;
 }
 
 /** Manage custom field definitions. */
 declare class CustomFieldsResource {
     private readonly client;
     constructor(client: HttpClient);
-    /** List custom fields. */
+    /** List custom field definitions, optionally for one record type. There is no single-field GET. */
     list(params?: CustomFieldListParams): Promise<ListResponse<CustomField>>;
-    /** Get a single custom field. */
-    get(fieldId: string): Promise<ApiResponse<CustomField>>;
     /** Create a custom field. */
     create(params: CustomFieldCreateParams, options?: RequestOptions): Promise<ApiResponse<CustomField>>;
     /** Update a custom field. */
@@ -1502,51 +1732,42 @@ declare class CustomFieldsResource {
     /** Delete a custom field. */
     del(fieldId: string): Promise<ApiResponse<DeleteResponse>>;
     /** Reorder custom fields within a content type. */
-    reorder(contentType: 'ticket' | 'customer' | 'article', orderedIds: string[]): Promise<{
+    reorder(contentType: CustomFieldContentType, orderedIds: string[]): Promise<{
         success: true;
         reordered: number;
     }>;
 }
 
-/** An SLA rule. */
+/**
+ * An SLA rule. Rules are stored in order on the team's SLA settings, so
+ * there is no per-rule timestamp.
+ */
 interface SlaRule {
     id: string;
-    object: 'sla_rule';
     name: string;
-    description: string | null;
-    priority: string;
-    responseTarget: number;
-    resolutionTarget: number;
-    businessHoursOnly: boolean;
+    /** Ticket priority key this rule applies to (for example `critical`). */
+    priorityKey: string;
+    /** First-response target in minutes. */
+    responseTimeMinutes: number;
+    /** Resolution target in minutes. */
+    resolutionTimeMinutes: number;
+    /** Count every hour instead of only business hours. */
+    use24x7: boolean;
     enabled: boolean;
-    position: number;
-    createdAt: string;
-    updatedAt: string;
-}
-/** Parameters for listing SLA rules. */
-interface SlaRuleListParams extends PaginationParams {
-    enabled?: boolean;
 }
 /** Parameters for creating an SLA rule. */
 interface SlaRuleCreateParams {
     name: string;
-    description?: string;
-    priority: string;
-    responseTarget: number;
-    resolutionTarget: number;
-    businessHoursOnly?: boolean;
+    priorityKey: string;
+    responseTimeMinutes: number;
+    resolutionTimeMinutes: number;
+    /** Defaults to false (business hours only). */
+    use24x7?: boolean;
+    /** Defaults to true. */
     enabled?: boolean;
 }
 /** Parameters for updating an SLA rule. */
-interface SlaRuleUpdateParams {
-    name?: string;
-    description?: string;
-    priority?: string;
-    responseTarget?: number;
-    resolutionTarget?: number;
-    businessHoursOnly?: boolean;
-    enabled?: boolean;
-}
+type SlaRuleUpdateParams = Partial<SlaRuleCreateParams>;
 /** Parameters for SLA metrics query. */
 interface SlaMetricsParams {
     period?: 'day' | 'week' | 'month' | 'quarter';
@@ -1565,8 +1786,8 @@ interface SlaMetrics {
 declare class SlaResource {
     private readonly client;
     constructor(client: HttpClient);
-    /** List SLA rules. */
-    list(params?: SlaRuleListParams): Promise<ListResponse<SlaRule>>;
+    /** List SLA rules in evaluation order. */
+    list(): Promise<ListResponse<SlaRule>>;
     /** Create an SLA rule. */
     create(params: SlaRuleCreateParams, options?: RequestOptions): Promise<ApiResponse<SlaRule>>;
     /** Update an SLA rule. */
@@ -1784,6 +2005,12 @@ interface ExportResult {
     /** Included when the selected tickets have messages. */
     messages?: Record<string, unknown>[];
     summary: Partial<Record<ExportResourceType | 'messages', number>>;
+    /**
+     * Resources cut off at the limit: 10,000 rows per resource, 50,000
+     * messages. Empty when the export is complete. Narrow with `filters`
+     * (for example `createdAfter`) to export the rest.
+     */
+    truncated: Array<ExportResourceType | 'messages'>;
 }
 
 /** Import request parameters. */
@@ -1825,12 +2052,15 @@ interface ImportResult {
     updated: number;
     skipped: number;
     failed: number;
-    errors?: Array<{
-        index: number;
-        error: string;
+    /** Rows that failed, as "Row N: ..." lines (a status or sentiment outside the team's keys lists the allowed ones). */
+    errors?: string[];
+    /** Rows saved with something missing (e.g. no customer link) or skipped as duplicates, as "Row N: ..." lines. */
+    warnings?: string[];
+    /** The rows created by this import: the 1-based row number and the prefixed id (tkt_, cus_, art_). */
+    createdIds: Array<{
+        rowIndex: number;
+        id: string;
     }>;
-    /** IDs of the rows created by this import. */
-    createdIds: string[];
 }
 /** Import log entry. */
 interface ImportLog {
@@ -1938,27 +2168,65 @@ declare class SearchResource {
     query(params: SearchParams): Promise<SearchResponse>;
 }
 
-/** A tag with usage count. */
+/** Entity types that carry tags. */
+type TagEntity = 'tickets' | 'customers' | 'articles';
+/** One tag on one entity type, with how many records carry it. */
 interface Tag {
-    object: 'tag';
-    name: string;
+    tag: string;
+    entity: TagEntity;
     count: number;
 }
 /** Parameters for listing tags. */
-interface TagListParams extends PaginationParams {
+interface TagListParams {
+    /** Only tags on this entity type. Omit for all three. */
+    entity?: TagEntity;
+    /** Case-insensitive substring filter on the tag name. */
     search?: string;
 }
+/** Parameters for merging one tag into another. */
+interface TagMergeParams {
+    /** Tag to replace. */
+    fromTag: string;
+    /** Tag that replaces it. */
+    toTag: string;
+    /** Only merge on this entity type. Omit for all three. */
+    entity?: TagEntity;
+}
+/** Result of a tag merge. */
+interface TagMergeResult {
+    /** Number of records whose tags changed. */
+    merged: number;
+    fromTag: string;
+    toTag: string;
+}
+/** Result of removing a tag. */
+interface TagRemoveResult {
+    deleted: true;
+    tag: string;
+    /** Number of records the tag was removed from. */
+    removedFrom: number;
+}
 
-/** Manage tags. */
+/**
+ * Manage tags across tickets, customers and articles. Tags exist only on the
+ * records that carry them, so there is no create call: add a tag by updating
+ * a record's `tags`.
+ */
 declare class TagsResource {
     private readonly client;
     constructor(client: HttpClient);
-    /** List all tags with usage counts. */
+    /** List tags with usage counts, one row per tag and entity type. */
     list(params?: TagListParams): Promise<ListResponse<Tag>>;
-    /** Create a tag. */
-    create(name: string, options?: RequestOptions): Promise<ApiResponse<Tag>>;
-    /** Delete a tag. */
-    del(name: string): Promise<ApiResponse<DeleteResponse>>;
+    /** Replace `fromTag` with `toTag` on every record that carries it. */
+    merge(params: TagMergeParams, options?: RequestOptions): Promise<TagMergeResult>;
+    /** Remove a tag from every record that carries it. */
+    remove(tag: string, params?: {
+        entity?: TagEntity;
+    }): Promise<TagRemoveResult>;
+    /** @deprecated Use `remove()`. */
+    del(tag: string, params?: {
+        entity?: TagEntity;
+    }): Promise<TagRemoveResult>;
 }
 
 /** An activity/timeline event. */
@@ -2142,16 +2410,21 @@ interface BossDefeat {
 /** Parameters for listing boss defeats. */
 interface BossDefeatListParams extends PaginationParams {
 }
-/** Parameters for spawning a boss. */
+/**
+ * Parameters for summoning a boss. A boss comes from a rush of customer
+ * tickets; the server counts them and picks the difficulty.
+ */
 interface BossSpawnParams {
+    /** @deprecated Ignored: difficulty follows the customer-ticket count. */
     difficulty?: 'easy' | 'medium' | 'hard';
 }
 /** Parameters for dealing boss damage. */
 interface BossDamageParams {
+    /** A closed customer ticket (widget, email or API). Each ticket hits once. */
+    ticketId: string;
     /** Defaults to the API key's creator. */
     userId?: string;
     userName?: string;
-    priority?: 'low' | 'normal' | 'high' | 'urgent';
 }
 /** Leaderboard entry. */
 interface LeaderboardEntry {
@@ -2192,13 +2465,15 @@ interface AchievementListParams extends PaginationParams {
 /** A daily quest. */
 interface Quest {
     questId: string;
+    /** Display title, for example `Ticket Tackler`. */
     name: string;
     description: string | null;
-    difficulty: string;
+    /** `easy`, `medium` or `hard`; null for a quest cStar no longer offers. */
+    difficulty: string | null;
     progress: number;
     target: number;
     completed: boolean;
-    completedAt: string | null;
+    /** XP and gold that completing the quest pays. */
     xpReward: number;
     goldReward: number;
 }
@@ -2209,20 +2484,15 @@ interface QuestList {
     completedToday: number;
     totalQuests: number;
     allComplete: boolean;
-    completionBonus: {
-        xp: number;
-        gold: number;
-    } | null;
     resetsAt: string;
 }
-/** Completed quests grouped by day. */
+/** Completed quests grouped by game day (UTC), newest first. */
 interface QuestHistory {
     object: 'quest_history';
     history: Array<{
+        /** Game day the quests were completed, `YYYY-MM-DD` (UTC). */
         date: string;
-        quests: Array<Pick<Quest, 'questId' | 'name' | 'difficulty' | 'xpReward' | 'goldReward'> & {
-            completedAt: string;
-        }>;
+        quests: Array<Pick<Quest, 'questId' | 'name' | 'difficulty' | 'xpReward' | 'goldReward'>>;
         completedCount: number;
     }>;
     totalCompleted: number;
@@ -2244,7 +2514,8 @@ interface Puzzle {
 }
 /** Puzzle completion parameters. */
 interface PuzzleCompleteParams {
-    userId: string;
+    /** Defaults to the API key's user; if sent, it must be that user. */
+    userId?: string;
     puzzleId: string;
     timeSeconds: number;
     mistakes?: number;
@@ -2323,7 +2594,11 @@ interface OneUp {
     wasFree: boolean;
     createdAt: string;
 }
-/** Sending a one-up also returns the remaining allowance and rewards. */
+/**
+ * Sending a one-up also returns the remaining allowance and rewards. The base
+ * reward (10 XP and 5 gold) is paid once per sender and recipient each UTC
+ * day, so repeat sends report 0 XP. Gifted gold is always paid.
+ */
 interface OneUpSendResult extends OneUp {
     freeRemaining: number;
     recipientXpAwarded: number;
@@ -2334,21 +2609,28 @@ interface OneUpListParams {
     userId?: string;
     limit?: number;
 }
-/** Parameters for sending a one-up. */
+/** Parameters for sending a one-up. The sender is always the API key's creator. */
 interface OneUpCreateParams {
-    /** Defaults to the API key's creator. */
+    /** @deprecated The sender is always the API key's creator. A different value is rejected. */
     senderId?: string;
+    /** @deprecated Ignored. The server reads names from the team. */
     senderName?: string;
+    /** A member of the same team. */
     recipientId: string;
+    /** @deprecated Ignored. The server reads names from the team. */
     recipientName?: string;
+    /** Up to 140 characters. Longer messages are cut. */
     message?: string;
+    /** Gold to gift, from 0 to 100, taken from the sender. Live keys only. */
     goldAmount?: number;
 }
-/** Remaining one-ups info. */
+/** Remaining free one-ups today. The limit includes the Social Butterfly skill bonus. */
 interface OneUpRemaining {
     object: 'one_up_remaining';
     remaining: number;
     limit: number;
+    sentToday: number;
+    /** The next UTC midnight. */
     resetsAt: string;
 }
 /** A high five (kudos between teams). */
@@ -2377,11 +2659,8 @@ interface HighFiveListParams {
 /** Parameters for sending a high five. */
 interface HighFiveCreateParams {
     recipientTeamId: string;
-    recipientTeamName?: string;
-    /** Defaults to the API key's creator. */
+    /** Defaults to the API key's user; if sent, it must be that user. Names come from cStar. */
     senderUserId?: string;
-    senderUserName?: string;
-    senderTeamName?: string;
     message?: string;
 }
 /** Can-send check result. */
@@ -2801,20 +3080,33 @@ interface ViewExecuteParams extends PaginationParams {
 /** Manage saved views (saved filters). */
 declare class ViewsResource extends BaseResource<SavedView, ViewListParams, ViewCreateParams, ViewUpdateParams> {
     constructor(client: HttpClient);
-    /** 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. */
     execute(viewId: string, params?: ViewExecuteParams): Promise<ListResponse<unknown>>;
 }
 
 /** Subscription status. */
 interface Subscription {
     object: 'subscription';
+    teamId: string;
+    teamName: string;
+    /** The team's subscription status, for example `trialing` or `active`; `inactive` when it has none. */
     status: string;
-    plan: string | null;
-    currentPeriodStart: string | null;
-    currentPeriodEnd: string | null;
-    cancelAtPeriodEnd: boolean;
+    isTrialing: boolean;
+    /** When the trial ends; null when there is none, including a team that never had one. */
+    trialEndsAt: string | null;
+    /** True while the team has no active subscription: reads work, writes return 402 `team_paused`. */
+    paused: boolean;
+    /** Why the team is paused; null when it isn't. */
+    pausedReason: 'trial_ended' | 'no_trial' | 'payment_failed' | 'canceled' | 'payment_required' | null;
+    /** When the team and its data are deleted (the whole named UTC day is safe), or null. */
+    scheduledDeletionAt: string | null;
+    /** Paid seats: every member, with up to 3 spectators free (minimum 1). */
+    seatCount: number;
+    /** Human members on the team (AI agents are free and not counted). */
     memberCount: number;
-    [key: string]: unknown;
+    hasStripeCustomer: boolean;
+    hasActiveSubscription: boolean;
+    createdAt: string;
 }
 /** Billing portal result. */
 interface BillingPortal {
@@ -2922,7 +3214,11 @@ declare class OfflineQueue {
 
 /** Configuration for the CStarClient. */
 interface CStarClientConfig {
-    /** Your API key (sk_live_*, sk_test_*, pk_live_*, or pk_test_*). */
+    /**
+     * Your secret API key (sk_live_* or sk_test_*). Team endpoints refuse
+     * publishable keys (pk_*) with 403: publishable_key_forbidden on reads,
+     * publishable_key_write on writes.
+     */
     apiKey: string;
     /** Your team ID. */
     teamId: string;
@@ -3057,7 +3353,12 @@ declare class CStarClient {
         keyType: 'secret' | 'publishable';
         environment: 'live' | 'test';
         createdAt: string;
-        subscriptionStatus: string;
+        /** Secret keys only, like GET /billing/subscription. */
+        subscriptionStatus?: string;
+        /** Secret keys only: true while the team has no active subscription (writes return 402 `team_paused`). */
+        paused?: boolean;
+        /** Secret keys only: why the team is paused; null when it isn't. */
+        pausedReason?: 'trial_ended' | 'no_trial' | 'payment_failed' | 'canceled' | 'payment_required' | null;
     }>;
     /**
      * Side-channel metadata from the most recent HTTP response. Holds the
@@ -3073,4 +3374,4 @@ declare class CStarClient {
     get lastMeta(): LastMeta;
 }
 
-export { type Achievement, type AchievementListParams, type ActivityEvent, type ActivityListParams, type AiAction, type AiActionParams, type AiActionResult, type AnalyticsOverview, type AnalyticsParams, type ApiResponse, type Article, type ArticleCreateParams, type ArticleListParams, type ArticleUpdateParams, type Attachment, type AttachmentListParams, type AuditLogEntry, type AuditLogListParams, type AutomationAction, type AutomationCondition, type AutomationConditions, type AutomationCreateParams, type AutomationExecution, type AutomationExecutionListParams, type AutomationListParams, type AutomationRule, type AutomationTestResult, type AutomationUpdateParams, type BillingPortal, type BillingPortalParams, type Boss, type BossDamageParams, type BossDamageResult, type BossDefeat, type BossDefeatListParams, type BossSpawnParams, type BulkDeleteParams, type BulkResult, type BulkUpdateParams, type BusinessHours, type BusinessHoursUpdateParams, CStarClient, type CStarClientConfig, CStarRealtime, type Category, type CategoryCreateParams, type CategoryListParams, type CategoryUpdateParams, type CommunityComment, type CommunityCommentCreateParams, type CommunityPost, type CommunityPostCreateParams, type CommunityPostListParams, type CommunityPostUpdateParams, type CommunityTopic, type ConnectionHandler, type Cosmetic, type CosmeticListParams, type CosmeticPreferences, type CsatSettings, type CsatSettingsUpdateParams, type CsatStats, type CsatSurvey, type CsatSurveyCreateParams, type CsatSurveyListParams, type CurrentSeason, type CustomField, type CustomFieldCreateParams, type CustomFieldListParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerGroup, type CustomerGroupAddMembersParams, type CustomerGroupAddResult, type CustomerGroupCreateParams, type CustomerGroupListParams, type CustomerGroupMemberListParams, type CustomerGroupMembersResult, type CustomerGroupRemoveResult, type CustomerGroupUpdateParams, type CustomerListParams, type CustomerUpdateParams, type DeleteResponse, type ErrorHandler, type EventHandler, type ExportCreateParams, type ExportCsvParams, type ExportFilters, type ExportJsonParams, type ExportResourceType, type ExportResult, type GameConfig, type HighFive, type HighFiveCanSend, type HighFiveCreateParams, type HighFiveListParams, type ImportCreateParams, type ImportLog, type ImportLogListParams, type ImportResult, type Invite, type InviteCreateParams, type InviteListParams, type LeaderboardEntry, type LeaderboardParams, type ListResponse, type Member, type MemberListParams, type MemberUpdateParams, type Mention, type MentionListParams, type MentionUnreadCount, type Message, type MessageCreateParams, type Metadata, type Notification, type NotificationListParams, OfflineQueue, type OfflineQueueOptions, type OneUp, type OneUpCreateParams, type OneUpListParams, type OneUpRemaining, type OneUpSendResult, type PaginationInfo, type PaginationParams, type Player, type Puzzle, type PuzzleCompleteParams, type PuzzleCompleteResult, type PuzzleLeaderboardParams, type PuzzleLeaderboardResult, type PuzzleStreak, type Quest, type QuestHistory, type QuestHistoryParams, type QuestList, type QueueItem, type QueueResult, type QuickReply, type QuickReplyCreateParams, type QuickReplyUpdateParams, type RealtimeEvent, type RealtimeOptions, type RequestOptions, type SavedView, type SearchParams, type SearchResponse, type SearchResult, type Season, type SeasonStats, type SkillAllocateParams, type SkillAllocateResult, type SkillTree, type SlaMetrics, type SlaMetricsParams, type SlaRule, type SlaRuleCreateParams, type SlaRuleListParams, type SlaRuleUpdateParams, type StatusCreateParams, type StatusUpdateParams, Subscription$1 as Subscription, type Tag, type TagListParams, type TeamSettings, type TeamSettingsUpdateParams, type Ticket, type TicketCreateParams, type TicketCustomerSummary, type TicketListParams, type TicketStatus, type TicketUpdateParams, type TopicCustomField, type UnreadCount, type ViewCreateParams, type ViewExecuteParams, type ViewListParams, type ViewUpdateParams, type Webhook, type WebhookCreateParams, type WebhookEventData, WebhookEventType, type WebhookListParams, type WebhookListener, type WebhookListenerParams, type WebhookSubscribeParams, type WebhookSubscription, type WebhookTestResult, type WebhookTriggerTestParams, type WebhookTriggerTestResult, type WebhookUpdateParams, type WidgetSettings, type WidgetSettingsUpdateParams };
+export { type Achievement, type AchievementListParams, type ActivityEvent, type ActivityListParams, type AiAction, type AiActionParams, type AiActionResult, type AnalyticsOverview, type AnalyticsParams, type ApiResponse, type Article, type ArticleCreateParams, type ArticleListParams, type ArticleUpdateParams, type Attachment, type AttachmentBucket, type AttachmentDownloadUrl, type AttachmentGetParams, type AttachmentListParams, type AuditLogEntry, type AuditLogListParams, type AutomationAction, type AutomationCondition, type AutomationConditions, type AutomationCreateParams, type AutomationExecution, type AutomationExecutionListParams, type AutomationListParams, type AutomationRule, type AutomationTestResult, type AutomationUpdateParams, type BillingPortal, type BillingPortalParams, type Boss, type BossDamageParams, type BossDamageResult, type BossDefeat, type BossDefeatListParams, type BossSpawnParams, type BulkDeleteParams, type BulkResult, type BulkUpdateParams, type BusinessHours, type BusinessHoursUpdateParams, CStarClient, type CStarClientConfig, CStarRealtime, type Category, type CategoryCreateParams, type CategoryListParams, type CategoryUpdateParams, type CommunityComment, type CommunityCommentCreateParams, type CommunityPost, type CommunityPostCreateParams, type CommunityPostListParams, type CommunityPostUpdateParams, type CommunityTopic, type ConnectionHandler, type Cosmetic, type CosmeticListParams, type CosmeticPreferences, type CsatSettings, type CsatSettingsUpdateParams, type CsatStats, type CsatSurvey, type CsatSurveyCreateParams, type CsatSurveyListParams, type CurrentSeason, type CustomField, type CustomFieldContentType, type CustomFieldCreateParams, type CustomFieldListParams, type CustomFieldType, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerGroup, type CustomerGroupAddMembersParams, type CustomerGroupAddResult, type CustomerGroupCreateParams, type CustomerGroupListParams, type CustomerGroupMemberListParams, type CustomerGroupMembersResult, type CustomerGroupRemoveResult, type CustomerGroupUpdateParams, type CustomerListParams, type CustomerUpdateParams, type DeleteResponse, type ErrorHandler, type EventHandler, type ExportCreateParams, type ExportCsvParams, type ExportFilters, type ExportJsonParams, type ExportResourceType, type ExportResult, type GameConfig, type HighFive, type HighFiveCanSend, type HighFiveCreateParams, type HighFiveListParams, type ImportCreateParams, type ImportLog, type ImportLogListParams, type ImportResult, type Invite, type InviteCreateParams, type InviteListParams, type LeaderboardEntry, type LeaderboardParams, type ListResponse, type Member, type MemberListParams, type MemberUpdateParams, type Mention, type MentionListParams, type MentionUnreadCount, type Message, type MessageCreateParams, type MessageListParams, type Metadata, type Notification, type NotificationListParams, OfflineQueue, type OfflineQueueOptions, type OneUp, type OneUpCreateParams, type OneUpListParams, type OneUpRemaining, type OneUpSendResult, type PaginationInfo, type PaginationParams, type Player, type Puzzle, type PuzzleCompleteParams, type PuzzleCompleteResult, type PuzzleLeaderboardParams, type PuzzleLeaderboardResult, type PuzzleStreak, type Quest, type QuestHistory, type QuestHistoryParams, type QuestList, type QueueItem, type QueueResult, type QuickReply, type QuickReplyCreateParams, type QuickReplyUpdateParams, type RealtimeEvent, type RealtimeOptions, type RequestOptions, type SavedView, type SearchParams, type SearchResponse, type SearchResult, type Season, type SeasonStats, type SkillAllocateParams, type SkillAllocateResult, type SkillTree, type SlaMetrics, type SlaMetricsParams, type SlaRule, type SlaRuleCreateParams, type SlaRuleUpdateParams, type StatusCreateParams, type StatusUpdateParams, Subscription$1 as Subscription, type Tag, type TagEntity, type TagListParams, type TagMergeParams, type TagMergeResult, type TagRemoveResult, type TeamSettings, type TeamSettingsUpdateParams, type Ticket, type TicketCreateParams, type TicketCustomFieldValues, type TicketCustomerSummary, type TicketListParams, type TicketPriorityKey, type TicketSeedMessage, type TicketStatus, type TicketStatusKey, type TicketUpdateParams, type TopicCustomField, type UnreadCount, type ViewCreateParams, type ViewExecuteParams, type ViewListParams, type ViewUpdateParams, type Webhook, type WebhookCreateParams, type WebhookEventData, WebhookEventType, type WebhookListParams, type WebhookListener, type WebhookListenerParams, type WebhookSubscribeParams, type WebhookSubscription, type WebhookTestResult, type WebhookTriggerTestParams, type WebhookTriggerTestResult, type WebhookUpdateParams, type WidgetEntrance, type WidgetEntranceCustom, type WidgetEntranceEffect, type WidgetEntranceKeyframe, type WidgetEntranceParticles, type WidgetSettings, type WidgetSettingsUpdateParams };