@cstar.help/js 0.16.0 → 0.16.1

package/dist/index.cjs

@@ -303,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 = {
@@ -510,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;
@@ -619,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}` : ""}`;
@@ -683,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 || "",
@@ -713,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();
@@ -736,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 || "",
@@ -1956,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

package/dist/index.d.cts

@@ -189,6 +189,15 @@ declare class CStarRealtime {
     private errorHandlers;
     private connectionHandlers;
     private lastEventId;
+    /**
+     * 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.
+     */
+    private lastEventTimestamp;
     private retryCount;
     private retryTimer;
     private _connected;
@@ -2194,21 +2203,37 @@ interface ExportResult {
 /** Import request parameters. */
 interface ImportCreateParams {
     resource: 'tickets' | 'customers' | 'articles';
+    /**
+     * Records to import. Flat objects with the per-entity fields you want
+     * to set — e.g. `[{ name: 'Jane', email: 'jane@example.com' }]` for
+     * `resource: 'customers'`. Each record is treated as a create. Server
+     * also accepts the wrapped internal shape `{ data, action, existingId? }`
+     * if you need to drive updates from the SDK.
+     */
     records: Record<string, unknown>[];
+    /** How to handle duplicates. Defaults to `'overwrite'`. */
     mergeStrategy?: 'skip' | 'overwrite' | 'merge';
 }
 /** Import result. */
 interface ImportResult {
     object: 'import_result';
-    resource: string;
+    /** ID of the persisted import-log row (null if the log row could not be written). */
+    logId: string | null;
+    /** Entity type imported — `ticket`, `customer`, or `article`. */
+    entityType: string;
+    /** True when every record imported without error. */
+    success: boolean;
     total: number;
     created: number;
     updated: number;
     skipped: number;
-    errors: Array<{
+    failed: number;
+    errors?: Array<{
         index: number;
         error: string;
     }>;
+    /** IDs of the rows created by this import. */
+    createdIds: string[];
 }
 /** Import log entry. */
 interface ImportLog {
@@ -2545,6 +2570,8 @@ interface Achievement {
 }
 /** Parameters for listing achievements. */
 interface AchievementListParams extends PaginationParams {
+    /** Whose achievement progress to load. Required — the endpoint 400s without it. */
+    userId: string;
     category?: string;
 }
 /** A daily quest. */
@@ -2741,8 +2768,8 @@ declare class BossResource {
 declare class AchievementsResource {
     private readonly client;
     constructor(client: HttpClient);
-    /** List all achievements with progress. */
-    list(params?: AchievementListParams): Promise<ApiResponse<{
+    /** List all achievements with progress. `params.userId` is required. */
+    list(params: AchievementListParams): Promise<ApiResponse<{
         object: 'achievement_list';
         data: Achievement[];
         summary: {

package/dist/index.d.ts

@@ -189,6 +189,15 @@ declare class CStarRealtime {
     private errorHandlers;
     private connectionHandlers;
     private lastEventId;
+    /**
+     * 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.
+     */
+    private lastEventTimestamp;
     private retryCount;
     private retryTimer;
     private _connected;
@@ -2194,21 +2203,37 @@ interface ExportResult {
 /** Import request parameters. */
 interface ImportCreateParams {
     resource: 'tickets' | 'customers' | 'articles';
+    /**
+     * Records to import. Flat objects with the per-entity fields you want
+     * to set — e.g. `[{ name: 'Jane', email: 'jane@example.com' }]` for
+     * `resource: 'customers'`. Each record is treated as a create. Server
+     * also accepts the wrapped internal shape `{ data, action, existingId? }`
+     * if you need to drive updates from the SDK.
+     */
     records: Record<string, unknown>[];
+    /** How to handle duplicates. Defaults to `'overwrite'`. */
     mergeStrategy?: 'skip' | 'overwrite' | 'merge';
 }
 /** Import result. */
 interface ImportResult {
     object: 'import_result';
-    resource: string;
+    /** ID of the persisted import-log row (null if the log row could not be written). */
+    logId: string | null;
+    /** Entity type imported — `ticket`, `customer`, or `article`. */
+    entityType: string;
+    /** True when every record imported without error. */
+    success: boolean;
     total: number;
     created: number;
     updated: number;
     skipped: number;
-    errors: Array<{
+    failed: number;
+    errors?: Array<{
         index: number;
         error: string;
     }>;
+    /** IDs of the rows created by this import. */
+    createdIds: string[];
 }
 /** Import log entry. */
 interface ImportLog {
@@ -2545,6 +2570,8 @@ interface Achievement {
 }
 /** Parameters for listing achievements. */
 interface AchievementListParams extends PaginationParams {
+    /** Whose achievement progress to load. Required — the endpoint 400s without it. */
+    userId: string;
     category?: string;
 }
 /** A daily quest. */
@@ -2741,8 +2768,8 @@ declare class BossResource {
 declare class AchievementsResource {
     private readonly client;
     constructor(client: HttpClient);
-    /** List all achievements with progress. */
-    list(params?: AchievementListParams): Promise<ApiResponse<{
+    /** List all achievements with progress. `params.userId` is required. */
+    list(params: AchievementListParams): Promise<ApiResponse<{
         object: 'achievement_list';
         data: Achievement[];
         summary: {

package/dist/index.js

@@ -262,7 +262,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 = {
@@ -469,6 +469,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;
@@ -578,8 +587,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}` : ""}`;
@@ -642,6 +651,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 || "",
@@ -672,6 +684,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();
@@ -695,6 +709,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 || "",
@@ -1915,7 +1932,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

package/package.json

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