@cstar.help/js 0.17.2 → 0.17.4

package/README.md

@@ -49,16 +49,16 @@ Manage tickets, customers, articles, team members, settings, game system, and ev
 ```typescript
 import { CStarClient } from '@cstar.help/js';
 
-const cstar = new CStarClient({
-	apiKey: process.env.CSTAR_SECRET_KEY, // sk_live_... or sk_test_...
-	teamId: process.env.CSTAR_TEAM_ID
-});
+const apiKey = process.env.CSTAR_SECRET_KEY; // sk_live_... or sk_test_...
+const teamId = process.env.CSTAR_TEAM_ID;
+if (!apiKey || !teamId) throw new Error('Set CSTAR_SECRET_KEY and CSTAR_TEAM_ID.');
+const cstar = new CStarClient({ apiKey, teamId });
 
 // List open tickets
 const { data: tickets } = await cstar.tickets.list({ status: 'open' });
 
 // Create a ticket
-const { data: ticket } = await cstar.tickets.create({
+const ticket = await cstar.tickets.create({
 	title: 'Help with billing',
 	customerId: 'cus_abc123'
 });
@@ -69,6 +69,8 @@ for await (const ticket of cstar.tickets.listAutoPaginating({ status: 'open' }))
 }
 ```
 
+Created, retrieved and updated resources are returned directly. List methods return `{ data, pagination, hasMore }`. Search returns `{ results, total, query }`. Read `cstar.lastMeta.requestId` immediately after a call when you need its request ID.
+
 ### Full Resource Reference
 
 **Core Resources** — Tickets, customers, and knowledge base.
@@ -116,13 +118,17 @@ for await (const ticket of cstar.tickets.listAutoPaginating({ status: 'open' }))
 | `cstar.game.boss`         | `.current()` `.isActive()` `.spawn(params?)` `.damage(params)` `.defeats(params?)` `.getDefeat(id)` |
 | `cstar.game.achievements` | `.list(params?)` `.unlocked(params)` `.get(id, params?)`                                            |
 | `cstar.game.quests`       | `.today(params?)` `.history(params?)`                                                               |
-| `cstar.game.puzzles`      | `.today(params?)` `.complete(params)` `.streak(params)` `.leaderboard(params?)`                     |
+| `cstar.game.puzzles`      | `.today(params?)` `.complete(params)` `.streak(params)` `.leaderboard(params)`                      |
 | `cstar.game.oneUps`       | `.list(params?)` `.send(params)` `.remaining(params)`                                               |
 | `cstar.game.highFives`    | `.list(params?)` `.send(params)` `.canSend(teamId, params)`                                         |
-| `cstar.game.cosmetics`    | `.list(params?)` `.getPreferences(params)` `.updatePreferences(params)`                             |
-| `cstar.game.seasons`      | `.list()` `.current()` `.stats(seasonId, params)`                                                   |
+| `cstar.game.cosmetics`    | `.list(params)` `.getPreferences(params)` `.updatePreferences(params)`                              |
+| `cstar.game.seasons`      | `.list(params?)` `.current()` `.stats(seasonId, params)`                                            |
 | `cstar.game.skills`       | `.get(params)` `.allocate(params)` `.reset(params)`                                                 |
 
+Game writes belong on your server with a secret API key. Use user and team UUIDs from cStar. One-ups and high fives default their sender to the key creator. Puzzle scoreboards require a `puzzleId`; streak boards use `{ type: 'streaks' }`. Cosmetic lists require a `userId`.
+
+Cosmetic and season lists return `{ data, pagination, hasMore }`. One-up and high-five lists return `{ object: 'list', data }`. Today's quests return `{ quests, completedToday, totalQuests, allComplete, completionBonus, resetsAt }`. Single resources return bare objects.
+
 **Advanced** — AI, automations, views, billing, webhooks.
 
 | Resource                 | Methods                                                                                                                                                                            |
@@ -140,20 +146,21 @@ for await (const ticket of cstar.tickets.listAutoPaginating({ status: 'open' }))
 
 ```typescript
 // Team analytics
-const { data: overview } = await cstar.analytics.overview({ period: 'week' });
-console.log(`${overview.tickets.open} open tickets this week`);
+const overview = await cstar.analytics.overview({ period: 'week' });
+console.log(`${overview.tickets?.open ?? 0} open tickets this week`);
 
 // SLA rules
 const { data: rules } = await cstar.sla.list();
 
-// Boss battle
-const { data: boss } = await cstar.game.boss.current();
-if (boss.active) {
-	console.log(`${boss.name} — ${boss.health}/${boss.maxHealth} HP`);
-}
+// Cheer on another team. The sender defaults to your API key's creator.
+const highFive = await cstar.game.highFives.send({
+	recipientTeamId: '550e8400-e29b-41d4-a716-446655440003',
+	message: 'Amazing work!'
+});
+console.log(`A high five from ${highFive.senderTeam.name}`);
 
 // AI-powered reply suggestion
-const { data: suggestion } = await cstar.ai.suggestReply('tkt_abc123');
+const suggestion = await cstar.ai.suggestReply('tkt_abc123');
 
 // Bulk close resolved tickets
 await cstar.bulk.update({
@@ -162,14 +169,19 @@ await cstar.bulk.update({
 	data: { status: 'closed' }
 });
 
-// Export data
-const { data: exportResult } = await cstar.export.create({
-	resources: [{ type: 'tickets', filters: { status: 'closed' } }],
-	format: 'csv'
+// Export closed tickets as JSON with raw rows and per-resource counts
+const exported = await cstar.export.create({
+	resources: ['tickets'],
+	filters: { status: 'closed' },
+	format: 'json'
 });
+console.log(exported.summary.tickets);
+
+// CSV is text and supports one resource at a time
+const csv = await cstar.export.create({ resources: ['tickets'], format: 'csv' });
 
 // Saved views
-const { data: view } = await cstar.views.create({
+const view = await cstar.views.create({
 	name: 'Urgent Unresolved',
 	entityType: 'tickets',
 	filters: { priority: 'urgent', status: 'open' }
@@ -177,7 +189,7 @@ const { data: view } = await cstar.views.create({
 const { data: results } = await cstar.views.execute(view.id);
 
 // Search across everything
-const { data: searchResults } = await cstar.search.query({
+const { results: searchResults } = await cstar.search.query({
 	query: 'billing issue',
 	types: ['tickets', 'customers']
 });
@@ -443,7 +455,7 @@ try {
 Safely retry create/update operations:
 
 ```typescript
-const { data: ticket } = await cstar.tickets.create(
+const ticket = await cstar.tickets.create(
 	{ title: 'Billing issue', customerId: 'cus_abc' },
 	{ idempotencyKey: 'create-billing-issue-usr123' }
 );

package/dist/index.cjs

@@ -278,7 +278,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.17.2";
+var SDK_VERSION = "0.17.4";
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;
@@ -384,8 +384,13 @@ var HttpClient = class {
       }
       if (response.ok) {
         if (response.status === 204) return void 0;
-        const json = await response.json();
         const headerRequestId = response.headers.get("x-request-id") ?? response.headers.get("x-cstar-request-id");
+        if (options?.responseType === "text") {
+          const text = await response.text();
+          this.captureMeta(null, headerRequestId);
+          return text;
+        }
+        const json = await response.json();
         this.captureMeta(json, headerRequestId);
         return this.unwrapEnvelope(json);
       }
@@ -1495,11 +1500,9 @@ var QuickRepliesResource = class {
   }
   /** Reorder quick replies. */
   async reorder(orderedIds) {
-    return this.client.request(
-      "PUT",
-      "/settings/quick-replies/reorder",
-      { body: { orderedIds } }
-    );
+    return this.client.request("PUT", "/settings/quick-replies/reorder", {
+      body: { orderedIds }
+    });
   }
 };
 var SettingsResource = class {
@@ -1673,9 +1676,13 @@ var CustomFieldsResource = class {
   }
   /** Reorder custom fields within a content type. */
   async reorder(contentType, orderedIds) {
-    return this.client.request("PUT", "/custom-fields/reorder", {
-      body: { contentType, orderedIds }
-    });
+    return this.client.request(
+      "PUT",
+      "/custom-fields/reorder",
+      {
+        body: { contentType, orderedIds }
+      }
+    );
   }
 };
 
@@ -1810,11 +1817,11 @@ var ExportResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** Create an export. Returns exported data synchronously. */
   async create(params, options) {
     return this.client.request("POST", "/export", {
       body: params,
-      idempotencyKey: options?.idempotencyKey
+      idempotencyKey: options?.idempotencyKey,
+      responseType: params.format === "csv" ? "text" : "json"
     });
   }
 };
@@ -1979,7 +1986,7 @@ var BossResource = class {
   /** List boss defeat history. */
   async defeats(params) {
     return this.client.request("GET", "/game/boss/defeats", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get a single defeat record. */
@@ -1994,25 +2001,25 @@ var AchievementsResource = class {
   /** List all achievements with progress. `params.userId` is required. */
   async list(params) {
     return this.client.request("GET", "/game/achievements", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** List unlocked achievements only. */
   async unlocked(params) {
     return this.client.request("GET", "/game/achievements/unlocked", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get a single achievement. */
   async get(achievementId, params) {
     return this.client.request("GET", `/game/achievements/${achievementId}`, {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get recently unlocked achievements across the team. */
   async recent(params) {
     return this.client.request("GET", "/game/achievements/recent", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
 };
@@ -2023,13 +2030,13 @@ var GameActivityResource = class {
   /** Get the team activity feed. */
   async list(params) {
     return this.client.request("GET", "/game/activity", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get activity for a specific member. */
   async forMember(memberId, params) {
     return this.client.request("GET", `/game/activity/member/${memberId}`, {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
 };
@@ -2040,13 +2047,13 @@ var QuestsResource = class {
   /** Get today's quests. */
   async today(params) {
     return this.client.request("GET", "/game/quests/today", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get quest history. */
   async history(params) {
     return this.client.request("GET", "/game/quests/history", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
 };
@@ -2057,10 +2064,10 @@ var PuzzlesResource = class {
   /** Get today's puzzle. */
   async today(params) {
     return this.client.request("GET", "/game/puzzles/today", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
-  /** Submit a puzzle answer. */
+  /** Record a completed puzzle, its timing and result. */
   async complete(params, options) {
     return this.client.request("POST", "/game/puzzles/complete", {
       body: params,
@@ -2070,13 +2077,13 @@ var PuzzlesResource = class {
   /** Get puzzle streak for a user. */
   async streak(params) {
     return this.client.request("GET", "/game/puzzles/streak", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get puzzle leaderboard. */
   async leaderboard(params) {
     return this.client.request("GET", "/game/puzzles/leaderboard", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
 };
@@ -2087,7 +2094,7 @@ var OneUpsResource = class {
   /** List one-ups. */
   async list(params) {
     return this.client.request("GET", "/game/one-ups", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Send a one-up. */
@@ -2100,7 +2107,7 @@ var OneUpsResource = class {
   /** Check remaining free one-ups today. */
   async remaining(params) {
     return this.client.request("GET", "/game/one-ups/remaining", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
 };
@@ -2111,7 +2118,7 @@ var HighFivesResource = class {
   /** List high fives. */
   async list(params) {
     return this.client.request("GET", "/game/high-fives", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Send a high five. */
@@ -2124,7 +2131,7 @@ var HighFivesResource = class {
   /** Check if you can send a high five to a team. */
   async canSend(recipientTeamId, params) {
     return this.client.request("GET", `/game/high-fives/can-send/${recipientTeamId}`, {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
 };
@@ -2135,13 +2142,13 @@ var CosmeticsResource = class {
   /** List unlocked cosmetics. */
   async list(params) {
     return this.client.request("GET", "/game/cosmetics", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get cosmetic preferences. */
   async getPreferences(params) {
     return this.client.request("GET", "/game/cosmetics/preferences", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Update cosmetic preferences. */
@@ -2154,8 +2161,10 @@ var SeasonsResource = class {
     this.client = client;
   }
   /** List all seasons. */
-  async list() {
-    return this.client.request("GET", "/game/seasons");
+  async list(params) {
+    return this.client.request("GET", "/game/seasons", {
+      query: params ? { ...params } : void 0
+    });
   }
   /** Get the current active season. */
   async current() {
@@ -2164,7 +2173,7 @@ var SeasonsResource = class {
   /** Get user stats for a season. */
   async stats(seasonId, params) {
     return this.client.request("GET", `/game/seasons/${seasonId}/stats`, {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
 };
@@ -2175,7 +2184,7 @@ var SkillsResource = class {
   /** Get the skill tree with current allocations. */
   async get(params) {
     return this.client.request("GET", "/game/skills", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Allocate a skill point. */
@@ -2210,7 +2219,7 @@ var GameResource = class {
   /** Get current player stats. */
   async player(params) {
     return this.client.request("GET", "/game/player", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get a specific player's stats by membership ID. */
@@ -2225,13 +2234,13 @@ var GameResource = class {
    */
   async leaderboard(params) {
     return this.client.request("GET", "/game/leaderboard", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get the current user's leaderboard position. */
   async myRank(params) {
     return this.client.request("GET", "/game/leaderboard/me", {
-      query: params
+      query: params ? { ...params } : void 0
     });
   }
   /** Get game balance configuration (read-only constants). */