@cstar.help/js 0.15.1 → 0.16.1

package/dist/index.cjs

@@ -33,7 +33,9 @@ __export(src_exports, {
   CStarValidationError: () => CStarValidationError,
   ErrorType: () => ErrorType,
   OfflineQueue: () => OfflineQueue,
-  Subscription: () => Subscription
+  Subscription: () => Subscription,
+  WEBHOOK_EVENT_CATALOG: () => WEBHOOK_EVENT_CATALOG,
+  WEBHOOK_EVENT_SAMPLES: () => WEBHOOK_EVENT_SAMPLES
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -301,7 +303,7 @@ var HttpClient = class {
     }
     if (typeof config.teamId !== "string" || config.teamId.length === 0) {
       throw new Error(
-        "[cStar] CStarClient: teamId is required. Find your team ID in Settings \u2192 General or via `cstar status`."
+        "[cStar] CStarClient: teamId is required. Find your team ID in Settings \u2192 API Keys (Team Identifiers) or via `cstar status`."
       );
     }
     this.config = {
@@ -355,7 +357,8 @@ var HttpClient = class {
     let lastError = null;
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
       if (attempt > 0 && lastError) {
-        const delay = lastError instanceof CStarRateLimitError ? lastError.retryAfter * 1e3 : this.getBackoffDelay(attempt);
+        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);
         await this.sleep(delay);
       }
       let response;
@@ -507,6 +510,15 @@ var CStarRealtime = class {
     this.errorHandlers = /* @__PURE__ */ new Set();
     this.connectionHandlers = /* @__PURE__ */ new Set();
     this.lastEventId = null;
+    /**
+     * Timestamp of the most recently received event, kept as an ISO-8601 string.
+     * Sent as `?since=<iso>` on reconnect so the server can replay events missed
+     * during the gap. The `id:` field on each SSE message is a prefixed entity
+     * ID (`evt_*`), which `new Date(...)` can't parse — passing it as `since`
+     * silently skips the replay branch on the server. Track the timestamp
+     * separately so reconnects actually catch up. R62.
+     */
+    this.lastEventTimestamp = null;
     this.retryCount = 0;
     this.retryTimer = null;
     this._connected = false;
@@ -616,8 +628,8 @@ var CStarRealtime = class {
     if (this.types && this.types.length > 0) {
       params.set("types", this.types.join(","));
     }
-    if (this.lastEventId) {
-      params.set("since", this.lastEventId);
+    if (this.lastEventTimestamp) {
+      params.set("since", this.lastEventTimestamp);
     }
     const qs = params.toString();
     const url = `${baseUrl}/events/stream${qs ? `?${qs}` : ""}`;
@@ -680,6 +692,9 @@ var CStarRealtime = class {
         }
         try {
           const parsed = JSON.parse(msgEvent.data);
+          if (typeof parsed.timestamp === "string" && parsed.timestamp) {
+            this.lastEventTimestamp = parsed.timestamp;
+          }
           const realtimeEvent = {
             type: parsed.type || type,
             id: msgEvent.lastEventId || "",
@@ -710,6 +725,8 @@ var CStarRealtime = class {
     }
     this.sseToken = null;
     this.sseTokenExpiresAt = 0;
+    this.lastEventId = null;
+    this.lastEventTimestamp = null;
     this.setConnected(false);
     this.handlers.clear();
     this.anyHandlers.clear();
@@ -733,6 +750,9 @@ var CStarRealtime = class {
     try {
       const parsed = JSON.parse(event.data);
       if (parsed.type === "connected") return;
+      if (typeof parsed.timestamp === "string" && parsed.timestamp) {
+        this.lastEventTimestamp = parsed.timestamp;
+      }
       const realtimeEvent = {
         type: parsed.type,
         id: event.lastEventId || "",
@@ -1339,10 +1359,31 @@ var InvitesResource = class {
     return this.client.request("DELETE", `/invites/${inviteId}`);
   }
 };
+var MemberPreferencesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get an agent's UX preferences (boring mode, etc.). */
+  async get(memberId) {
+    return this.client.request(
+      "GET",
+      `/members/${memberId}/preferences`
+    );
+  }
+  /** Update an agent's UX preferences. Only provided fields are written. */
+  async update(memberId, params) {
+    return this.client.request(
+      "PATCH",
+      `/members/${memberId}/preferences`,
+      { body: params }
+    );
+  }
+};
 var MembersResource = class {
   constructor(client) {
     this.client = client;
     this.invites = new InvitesResource(client);
+    this.preferences = new MemberPreferencesResource(client);
   }
   /** List all team members. */
   async list(params) {
@@ -1932,7 +1973,7 @@ var AchievementsResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List all achievements with progress. */
+  /** List all achievements with progress. `params.userId` is required. */
   async list(params) {
     return this.client.request("GET", "/game/achievements", {
       query: params
@@ -2305,6 +2346,23 @@ var BillingResource = class {
   }
 };
 
+// src/resources/preferences.ts
+var PreferencesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get team preferences. */
+  async get() {
+    return this.client.request("GET", "/preferences");
+  }
+  /** Update team preferences. Only provided fields are written. */
+  async update(params) {
+    return this.client.request("PATCH", "/preferences", {
+      body: params
+    });
+  }
+};
+
 // src/offline.ts
 var STORAGE_KEY = "cstar_offline_queue";
 var OfflineQueue = class {
@@ -2422,6 +2480,416 @@ var OfflineQueue = class {
   }
 };
 
+// src/types/generated/webhookEvents.ts
+var WEBHOOK_EVENT_SAMPLES = {
+  "agent.preferences_updated": {
+    "team_id": "team_01H8X9YZ7E0J3K4M5N6U",
+    "member_id": "mem_01H8X9YZ7E0J3K4M5N6U",
+    "agent_id": "agt_01H8X9YZ7E0J3K4M5N6U",
+    "changed": [
+      "boringMode"
+    ],
+    "preferences": {
+      "boringMode": true
+    }
+  },
+  "article.created": {
+    "article": {
+      "id": "art_01H8X9YZ7E0J3K4M5N6U",
+      "title": "How to reset your password",
+      "slug": "how-to-reset-your-password",
+      "is_public": false,
+      "created_at": "2026-04-27T18:42:11.000Z"
+    }
+  },
+  "article.deleted": {
+    "id": "art_01H8X9YZ7E0J3K4M5N6U"
+  },
+  "article.published": {
+    "article": {
+      "id": "art_01H8X9YZ7E0J3K4M5N6U",
+      "title": "How to reset your password",
+      "slug": "how-to-reset-your-password",
+      "is_public": true,
+      "published_at": "2026-04-27T19:00:00.000Z"
+    }
+  },
+  "article.updated": {
+    "article": {
+      "id": "art_01H8X9YZ7E0J3K4M5N6U",
+      "title": "How to reset your password (updated)",
+      "slug": "how-to-reset-your-password",
+      "is_public": true
+    }
+  },
+  "boss.damaged": {
+    "boss": {
+      "id": "boss_thunder_drake",
+      "current_hp": 740
+    },
+    "damage": 120,
+    "by": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    }
+  },
+  "boss.defeated": {
+    "boss": {
+      "id": "boss_thunder_drake",
+      "name": "The Thunder Drake"
+    },
+    "final_blow_by": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    },
+    "team_xp_awarded": 1500
+  },
+  "boss.spawned": {
+    "boss": {
+      "id": "boss_thunder_drake",
+      "name": "The Thunder Drake",
+      "level": 4,
+      "max_hp": 1200
+    }
+  },
+  "community_post.commented": {
+    "comment": {
+      "id": "cmt_01H8X9YZ7E0J3K4M5N6X",
+      "post_id": "post_01H8X9YZ7E0J3K4M5N6W",
+      "content": "I would love this \u2014 bumping for visibility.",
+      "author_id": "cus_01H8X9YZ7E0J3K4M5N6Q",
+      "created_at": "2026-04-27T18:55:02.000Z"
+    }
+  },
+  "community_post.created": {
+    "post": {
+      "id": "post_01H8X9YZ7E0J3K4M5N6W",
+      "prefixed_id": "IDEA-42",
+      "title": "Add Slack-style threading to tickets",
+      "status": "open",
+      "visibility": "public",
+      "topic": "feature-requests",
+      "created_at": "2026-04-27T18:42:11.000Z"
+    }
+  },
+  "community_post.deleted": {
+    "post": {
+      "id": "post_01H8X9YZ7E0J3K4M5N6W",
+      "prefixed_id": "IDEA-42",
+      "title": "Add Slack-style threading to tickets"
+    }
+  },
+  "community_post.status_changed": {
+    "post": {
+      "id": "post_01H8X9YZ7E0J3K4M5N6W",
+      "title": "Add Slack-style threading to tickets",
+      "status": "planned",
+      "visibility": "public"
+    }
+  },
+  "community_post.updated": {
+    "post": {
+      "id": "post_01H8X9YZ7E0J3K4M5N6W",
+      "title": "Add Slack-style threading to tickets (revised)",
+      "status": "open",
+      "visibility": "public"
+    }
+  },
+  "community_post.voted": {
+    "post": {
+      "id": "post_01H8X9YZ7E0J3K4M5N6W",
+      "vote_count": 13
+    },
+    "voter": {
+      "id": "cus_01H8X9YZ7E0J3K4M5N6Q"
+    },
+    "direction": "up"
+  },
+  "customer.created": {
+    "customer": {
+      "id": "cus_01H8X9YZ7E0J3K4M5N6Q",
+      "name": "Casey Patel",
+      "email": "casey@example.com",
+      "status": "active",
+      "tags": [
+        "trial"
+      ],
+      "created_at": "2026-04-27T18:42:11.000Z"
+    }
+  },
+  "customer.deleted": {
+    "id": "cus_01H8X9YZ7E0J3K4M5N6Q"
+  },
+  "customer.updated": {
+    "customer": {
+      "id": "cus_01H8X9YZ7E0J3K4M5N6Q",
+      "name": "Casey Patel",
+      "email": "casey@example.com",
+      "status": "active",
+      "tags": [
+        "trial",
+        "paying"
+      ]
+    },
+    "changes": {
+      "tags": {
+        "from": [
+          "trial"
+        ],
+        "to": [
+          "trial",
+          "paying"
+        ]
+      }
+    }
+  },
+  "customer_group.created": {
+    "group": {
+      "id": "grp_01H8X9YZ7E0J3K4M5N6T",
+      "name": "Pro Plan",
+      "color": "indigo",
+      "member_count": 0
+    }
+  },
+  "customer_group.deleted": {
+    "customer_group": {
+      "id": "grp_01H8X9YZ7E0J3K4M5N6T"
+    }
+  },
+  "customer_group.updated": {
+    "group": {
+      "id": "grp_01H8X9YZ7E0J3K4M5N6T",
+      "name": "Pro Plan (Annual)",
+      "color": "indigo",
+      "member_count": 38
+    }
+  },
+  "player.achievement_unlocked": {
+    "player": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    },
+    "achievement": {
+      "id": "first_resolve",
+      "name": "First Resolve",
+      "xp": 50
+    }
+  },
+  "player.level_up": {
+    "player": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    },
+    "level": {
+      "from": 7,
+      "to": 8
+    },
+    "title_unlocked": "Apprentice Healer"
+  },
+  "player.quest_completed": {
+    "player": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    },
+    "quest": {
+      "id": "resolve_5_tickets",
+      "name": "Resolve 5 tickets today",
+      "xp": 100
+    }
+  },
+  "player.streak_milestone": {
+    "player": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    },
+    "streak_days": 5,
+    "milestone": 5
+  },
+  "player.xp_gained": {
+    "player": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    },
+    "amount": 75,
+    "reason": "ticket.resolved",
+    "ticket_id": "tkt_01H8X9YZ7E0J3K4M5N6P"
+  },
+  "social.high_five_sent": {
+    "from_team": {
+      "id": "team_acme",
+      "name": "Acme Support"
+    },
+    "to_team": {
+      "id": "team_globex",
+      "name": "Globex Support"
+    },
+    "message": "Thanks for the assist!"
+  },
+  "social.one_up_sent": {
+    "from": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley"
+    },
+    "to": {
+      "agent_id": "usr_01H8X9YZ7E0J3K4M5N6V",
+      "name": "Sam"
+    },
+    "ticket_id": "tkt_01H8X9YZ7E0J3K4M5N6P",
+    "message": "Great empathy on this one"
+  },
+  "survey.submitted": {
+    "survey": {
+      "id": "svy_01H8X9YZ7E0J3K4M5N6Y",
+      "ticket_id": "tkt_01H8X9YZ7E0J3K4M5N6P",
+      "score": 5,
+      "comment": "Resolved fast, thank you!",
+      "submitted_at": "2026-04-27T19:30:00.000Z"
+    },
+    "customer": {
+      "id": "cus_01H8X9YZ7E0J3K4M5N6Q",
+      "email": "casey@example.com"
+    }
+  },
+  "team.preferences_updated": {
+    "team_id": "team_01H8X9YZ7E0J3K4M5N6U",
+    "changed": [
+      "bossBattlesEnabled"
+    ],
+    "preferences": {
+      "bossBattlesEnabled": false
+    }
+  },
+  "ticket.assigned": {
+    "ticket": {
+      "id": "tkt_01H8X9YZ7E0J3K4M5N6P",
+      "prefixed_id": "CST-1024"
+    },
+    "assignee": {
+      "id": "usr_01H8X9YZ7E0J3K4M5N6S",
+      "name": "Riley",
+      "email": "riley@acme.test"
+    },
+    "previous_assignee": null
+  },
+  "ticket.closed": {
+    "ticket": {
+      "id": "tkt_01H8X9YZ7E0J3K4M5N6P",
+      "prefixed_id": "CST-1024",
+      "title": "Cannot reset password",
+      "status": "resolved",
+      "priority": "normal",
+      "channel": "widget",
+      "resolved_at": "2026-04-27T19:08:43.000Z"
+    },
+    "changes": {
+      "status": {
+        "from": "open",
+        "to": "resolved"
+      }
+    }
+  },
+  "ticket.created": {
+    "ticket": {
+      "id": "tkt_01H8X9YZ7E0J3K4M5N6P",
+      "prefixed_id": "CST-1024",
+      "title": "Cannot reset password",
+      "status": "new",
+      "priority": "normal",
+      "channel": "widget",
+      "customer_id": "cus_01H8X9YZ7E0J3K4M5N6Q",
+      "created_at": "2026-04-27T18:42:11.000Z"
+    },
+    "customer": {
+      "id": "cus_01H8X9YZ7E0J3K4M5N6Q",
+      "name": "Casey Patel",
+      "email": "casey@example.com"
+    }
+  },
+  "ticket.deleted": {
+    "id": "CST-1024"
+  },
+  "ticket.message_added": {
+    "ticket": {
+      "id": "tkt_01H8X9YZ7E0J3K4M5N6P",
+      "dashboard_url": "https://www.cstar.help/team/acme/tickets?selected=tkt_01H8X9YZ7E0J3K4M5N6P"
+    },
+    "message": {
+      "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.",
+      "created_at": "2026-04-27T18:55:02.000Z"
+    },
+    "customer": {
+      "id": "cus_01H8X9YZ7E0J3K4M5N6Q",
+      "name": "Casey Patel",
+      "email": "casey@example.com"
+    }
+  },
+  "ticket.updated": {
+    "ticket": {
+      "id": "tkt_01H8X9YZ7E0J3K4M5N6P",
+      "prefixed_id": "CST-1024",
+      "title": "Cannot reset password",
+      "status": "open",
+      "priority": "high",
+      "channel": "widget"
+    },
+    "changes": {
+      "priority": {
+        "from": "normal",
+        "to": "high"
+      },
+      "tags": {
+        "from": [
+          "bug"
+        ],
+        "to": [
+          "bug",
+          "feature-request"
+        ]
+      }
+    }
+  }
+};
+var WEBHOOK_EVENT_CATALOG = {
+  "agent.preferences_updated": { label: "Agent Preferences Updated", description: "Fired when an agent's per-user UX preferences change (e.g., boringMode toggled)", category: "team" },
+  "article.created": { label: "New Article Created", description: "Fired when a new Library article is created", category: "articles" },
+  "article.deleted": { label: "Article Deleted", description: "Fired when an article is deleted via app or API", category: "articles" },
+  "article.published": { label: "Article Published", description: "Fired when an article is published to the Public Library", category: "articles" },
+  "article.updated": { label: "Article Updated", description: "Fired when an article content or metadata is modified", category: "articles" },
+  "boss.damaged": { label: "Boss Damaged", description: "Fired when a boss takes damage from a ticket close", category: "gamification" },
+  "boss.defeated": { label: "Boss Defeated", description: "Fired when a boss is defeated by the team", category: "gamification" },
+  "boss.spawned": { label: "Boss Battle Started", description: "Fired when a boss appears for the team", category: "gamification" },
+  "community_post.commented": { label: "New Comment on Post", description: "Fired when a new comment is added to a community post", category: "community" },
+  "community_post.created": { label: "New Community Post", description: "Fired when a new community post is created", category: "community" },
+  "community_post.deleted": { label: "Community Post Deleted", description: "Fired when a community post is deleted", category: "community" },
+  "community_post.status_changed": { label: "Post Status Changed", description: "Fired when a community post status is changed (e.g., Planned, Completed)", category: "community" },
+  "community_post.updated": { label: "Community Post Updated", description: "Fired when a community post is updated", category: "community" },
+  "community_post.voted": { label: "Post Voted On", description: "Fired when a community post receives a vote", category: "community" },
+  "customer.created": { label: "New Customer Added", description: "Fired when a new customer is created", category: "customers" },
+  "customer.deleted": { label: "Customer Deleted", description: "Fired when a customer is deleted via app or API", category: "customers" },
+  "customer.updated": { label: "Customer Updated", description: "Fired when customer details are modified", category: "customers" },
+  "customer_group.created": { label: "New Customer Group", description: "Fired when a customer group is created", category: "customers" },
+  "customer_group.deleted": { label: "Customer Group Deleted", description: "Fired when a customer group is deleted", category: "customers" },
+  "customer_group.updated": { label: "Customer Group Updated", description: "Fired when a customer group is modified", category: "customers" },
+  "player.achievement_unlocked": { label: "Achievement Unlocked", description: "Fired when a player unlocks an achievement", category: "gamification" },
+  "player.level_up": { label: "Player Leveled Up", description: "Fired when a player reaches a new level", category: "gamification" },
+  "player.quest_completed": { label: "Quest Completed", description: "Fired when a player completes a daily quest", category: "gamification" },
+  "player.streak_milestone": { label: "Streak Milestone", description: "Fired when a player hits a streak milestone (3, 5, 10, or 25 days)", category: "gamification" },
+  "player.xp_gained": { label: "XP Gained", description: "Fired when a player earns XP from closing a ticket or quest", category: "gamification" },
+  "social.high_five_sent": { label: "High Five Sent", description: "Fired when a team sends a high five to another team", category: "gamification" },
+  "social.one_up_sent": { label: "One-Up Sent", description: "Fired when a teammate sends a one-up recognition", category: "gamification" },
+  "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.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" },
+  "ticket.updated": { label: "Ticket Updated", description: "Fired when a ticket status, priority, or assignment changes", category: "tickets" }
+};
+
 // src/index.ts
 var CStarClient = class {
   constructor(config) {
@@ -2438,6 +2906,7 @@ var CStarClient = class {
     };
     this.members = new MembersResource(this._httpClient);
     this.settings = new SettingsResource(this._httpClient);
+    this.preferences = new PreferencesResource(this._httpClient);
     this.notifications = new NotificationsResource(this._httpClient);
     this.mentions = new MentionsResource(this._httpClient);
     this.attachments = new AttachmentsResource(this._httpClient);
@@ -2521,5 +2990,7 @@ var CStarClient = class {
   CStarValidationError,
   ErrorType,
   OfflineQueue,
-  Subscription
+  Subscription,
+  WEBHOOK_EVENT_CATALOG,
+  WEBHOOK_EVENT_SAMPLES
 });