@cstar.help/js 0.12.1 → 0.14.0

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(src_exports, {
   CStarClient: () => CStarClient,
   CStarConflictError: () => CStarConflictError,
   CStarError: () => CStarError,
+  CStarFeatureDisabledError: () => CStarFeatureDisabledError,
   CStarNotFoundError: () => CStarNotFoundError,
   CStarPermissionError: () => CStarPermissionError,
   CStarRateLimitError: () => CStarRateLimitError,
@@ -44,102 +45,211 @@ var ErrorType = {
   NOT_FOUND_ERROR: "not_found_error",
   CONFLICT_ERROR: "conflict_error",
   RATE_LIMIT_ERROR: "rate_limit_error",
+  FEATURE_NOT_CONFIGURED: "feature_not_configured",
   API_ERROR: "api_error",
   SERVER_ERROR: "server_error"
 };
+var DEFAULT_DOC_URL = "https://cstar.help/developers/api/errors";
+function normalizeArgs(messageOrStatus, maybeBody, defaults) {
+  if (typeof messageOrStatus === "string") {
+    return {
+      statusCode: defaults?.code === "rate_limit_error" ? 429 : 0,
+      body: {
+        type: defaults?.type ?? ErrorType.API_ERROR,
+        code: defaults?.code ?? "sdk_error",
+        message: messageOrStatus,
+        doc_url: defaults?.doc_url ?? DEFAULT_DOC_URL,
+        ...defaults?.feature ? { feature: defaults.feature } : {},
+        ...defaults?.enable_url ? { enable_url: defaults.enable_url } : {}
+      }
+    };
+  }
+  return {
+    statusCode: messageOrStatus,
+    body: maybeBody ?? {
+      type: defaults?.type ?? ErrorType.API_ERROR,
+      code: defaults?.code ?? "unknown_error",
+      message: defaults?.message ?? `Request failed with status ${messageOrStatus}`,
+      doc_url: defaults?.doc_url ?? DEFAULT_DOC_URL
+    }
+  };
+}
 var CStarError = class extends Error {
-  constructor(statusCode, body) {
-    super(body.message);
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body);
+    super(resolved.message);
     this.name = "CStarError";
-    this.type = body.type;
-    this.code = body.code;
-    this.param = body.param;
-    this.docUrl = body.doc_url;
-    this.requestId = body.request_id;
+    this.type = resolved.type;
+    this.code = resolved.code;
+    this.param = resolved.param;
+    this.docUrl = resolved.doc_url;
+    this.requestId = resolved.request_id;
     this.statusCode = statusCode;
   }
 };
 var CStarAuthenticationError = class extends CStarError {
-  constructor(statusCode, body) {
-    super(statusCode, body);
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.AUTHENTICATION_ERROR,
+      code: "authentication_failed",
+      doc_url: `${DEFAULT_DOC_URL}#authentication-error`
+    });
+    super(statusCode, resolved);
     this.name = "CStarAuthenticationError";
   }
 };
 var CStarRateLimitError = class extends CStarError {
-  constructor(statusCode, body, retryAfter) {
-    super(statusCode, body);
+  constructor(messageOrStatus, body, retryAfter) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.RATE_LIMIT_ERROR,
+      code: "rate_limit_exceeded",
+      doc_url: `${DEFAULT_DOC_URL}#rate-limit-error`
+    });
+    super(statusCode === 0 ? 429 : statusCode, resolved);
     this.name = "CStarRateLimitError";
-    this.retryAfter = retryAfter;
+    this.retryAfter = retryAfter ?? 60;
   }
 };
 var CStarNotFoundError = class extends CStarError {
-  constructor(statusCode, body) {
-    super(statusCode, body);
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.NOT_FOUND_ERROR,
+      code: "resource_not_found",
+      doc_url: `${DEFAULT_DOC_URL}#not-found-error`
+    });
+    super(statusCode, resolved);
     this.name = "CStarNotFoundError";
   }
 };
 var CStarValidationError = class extends CStarError {
-  constructor(statusCode, body) {
-    super(statusCode, body);
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.INVALID_REQUEST_ERROR,
+      code: "validation_error",
+      doc_url: `${DEFAULT_DOC_URL}#validation-error`
+    });
+    super(statusCode, resolved);
     this.name = "CStarValidationError";
   }
 };
 var CStarPermissionError = class extends CStarError {
-  constructor(statusCode, body) {
-    super(statusCode, body);
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.PERMISSION_ERROR,
+      code: "permission_denied",
+      doc_url: `${DEFAULT_DOC_URL}#permission-error`
+    });
+    super(statusCode, resolved);
     this.name = "CStarPermissionError";
   }
 };
 var CStarConflictError = class extends CStarError {
-  constructor(statusCode, body) {
-    super(statusCode, body);
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.CONFLICT_ERROR,
+      code: "conflict",
+      doc_url: `${DEFAULT_DOC_URL}#conflict-error`
+    });
+    super(statusCode, resolved);
     this.name = "CStarConflictError";
   }
 };
 var CStarServerError = class extends CStarError {
-  constructor(statusCode, body) {
-    super(statusCode, body);
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.SERVER_ERROR,
+      code: "server_error",
+      doc_url: `${DEFAULT_DOC_URL}#server-error`
+    });
+    super(statusCode, resolved);
     this.name = "CStarServerError";
   }
 };
+var CStarFeatureDisabledError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.FEATURE_NOT_CONFIGURED,
+      code: "feature_not_configured",
+      doc_url: `${DEFAULT_DOC_URL}#feature-not-configured`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarFeatureDisabledError";
+    this.feature = resolved.feature ?? "unknown";
+    this.enableUrl = resolved.enable_url ?? "";
+  }
+};
+var CStarRealtimeUnavailableError = class extends CStarError {
+  constructor(message) {
+    const resolved = message ?? "EventSource is not available in this environment. Real-time subscriptions only work in the browser. Move the call to a client-only path (`useEffect` / `onMount`), or pass an `eventSource` polyfill via the realtime options. See https://cstar.help/developers/sdk/realtime#ssr";
+    super(0, {
+      type: ErrorType.API_ERROR,
+      code: "realtime_unavailable",
+      message: resolved,
+      doc_url: "https://cstar.help/developers/sdk/realtime#ssr"
+    });
+    this.name = "CStarRealtimeUnavailableError";
+  }
+};
+var STATUS_TO_CLASS = {
+  400: CStarValidationError,
+  401: CStarAuthenticationError,
+  403: CStarPermissionError,
+  404: CStarNotFoundError,
+  409: CStarConflictError,
+  422: CStarValidationError,
+  429: CStarRateLimitError
+};
+var TYPE_TO_CLASS = {
+  [ErrorType.AUTHENTICATION_ERROR]: CStarAuthenticationError,
+  [ErrorType.PERMISSION_ERROR]: CStarPermissionError,
+  [ErrorType.RATE_LIMIT_ERROR]: CStarRateLimitError,
+  [ErrorType.NOT_FOUND_ERROR]: CStarNotFoundError,
+  [ErrorType.INVALID_REQUEST_ERROR]: CStarValidationError,
+  [ErrorType.CONFLICT_ERROR]: CStarConflictError,
+  [ErrorType.SERVER_ERROR]: CStarServerError,
+  [ErrorType.FEATURE_NOT_CONFIGURED]: CStarFeatureDisabledError
+};
 function parseError(statusCode, body, retryAfter) {
   const errorBody = body?.error ?? {
     type: ErrorType.API_ERROR,
     code: "unknown_error",
     message: `Request failed with status ${statusCode}`,
-    doc_url: "https://cstar.help/developers/api/errors"
+    doc_url: DEFAULT_DOC_URL
   };
-  switch (errorBody.type) {
-    case ErrorType.AUTHENTICATION_ERROR:
-      return new CStarAuthenticationError(statusCode, errorBody);
-    case ErrorType.PERMISSION_ERROR:
-      return new CStarPermissionError(statusCode, errorBody);
-    case ErrorType.RATE_LIMIT_ERROR:
-      return new CStarRateLimitError(statusCode, errorBody, retryAfter ?? 60);
-    case ErrorType.NOT_FOUND_ERROR:
-      return new CStarNotFoundError(statusCode, errorBody);
-    case ErrorType.INVALID_REQUEST_ERROR:
-      return new CStarValidationError(statusCode, errorBody);
-    case ErrorType.CONFLICT_ERROR:
-      return new CStarConflictError(statusCode, errorBody);
-    case ErrorType.SERVER_ERROR:
-      return new CStarServerError(statusCode, errorBody);
-    default:
-      if (statusCode === 403) return new CStarPermissionError(statusCode, errorBody);
-      if (statusCode === 409) return new CStarConflictError(statusCode, errorBody);
-      if (statusCode >= 500) return new CStarServerError(statusCode, errorBody);
-      return new CStarError(statusCode, errorBody);
+  if (statusCode === 429) {
+    return new CStarRateLimitError(statusCode, errorBody, retryAfter ?? 60);
+  }
+  const StatusCls = STATUS_TO_CLASS[statusCode];
+  if (StatusCls) {
+    return new StatusCls(statusCode, errorBody);
   }
+  const TypeCls = TYPE_TO_CLASS[errorBody.type];
+  if (TypeCls) {
+    return new TypeCls(statusCode, errorBody);
+  }
+  if (statusCode >= 500) return new CStarServerError(statusCode, errorBody);
+  return new CStarError(statusCode, errorBody);
 }
 
 // src/client.ts
-var SDK_VERSION = "0.5.2";
+var SDK_VERSION = "0.14.0";
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_TIMEOUT = 3e4;
 var HttpClient = class {
   constructor(config) {
+    /**
+     * Side-channel metadata from the most recent response. Holds the server
+     * `requestId`, `timestamp`, and (for list endpoints) `pagination`. Mutable
+     * per-call — read it immediately after awaiting the call.
+     *
+     * ```ts
+     * const ticket = await cstar.tickets.create({...});
+     * console.error('Created ticket', ticket.id, 'request:', cstar.lastMeta.requestId);
+     * ```
+     */
+    this.lastMeta = { requestId: null, timestamp: null, pagination: null };
     if (!config || typeof config.apiKey !== "string" || config.apiKey.length === 0) {
       throw new Error(
         "[cStar] CStarClient: apiKey is required. Pass a secret key (sk_live_... / sk_test_...) or a publishable key (pk_live_... / pk_test_...). See https://cstar.help/developers/quickstart"
@@ -170,7 +280,32 @@ var HttpClient = class {
    * Automatically retries on 5xx errors and rate limits.
    */
   async request(method, path, options) {
-    const url = this.buildUrl(path, options?.query);
+    return this._sendRequest(method, this.buildUrl(path, options?.query), options);
+  }
+  /**
+   * Like `request()` but skips the `/api/v1/teams/{teamId}` prefix. Used for
+   * the small set of non-team-scoped endpoints (`/auth/whoami`, etc).
+   *
+   * @internal — exposed to CStarClient for `whoami()` and similar; not part
+   * of the documented public surface.
+   */
+  async requestUnscoped(method, path, options) {
+    const baseUrl = this.config.baseUrl + "/api/v1" + path;
+    const finalUrl = this.appendQuery(baseUrl, options?.query);
+    return this._sendRequest(method, finalUrl, options);
+  }
+  appendQuery(url, query) {
+    if (!query) return url;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) for (const v of value) params.append(`${key}[]`, v);
+      else params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `${url}?${qs}` : url;
+  }
+  async _sendRequest(method, url, options) {
     const headers = this.buildHeaders(options?.idempotencyKey);
     const body = options?.body ? JSON.stringify(options.body) : void 0;
     let lastError = null;
@@ -201,13 +336,9 @@ var HttpClient = class {
       if (response.ok) {
         if (response.status === 204) return void 0;
         const json = await response.json();
-        const requestId2 = response.headers.get("x-request-id") ?? response.headers.get("x-cstar-request-id");
-        if (requestId2 && json && typeof json === "object" && "meta" in json) {
-          const existing = json.meta;
-          const metaBase = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {};
-          json.meta = { ...metaBase, requestId: requestId2 };
-        }
-        return json;
+        const headerRequestId = response.headers.get("x-request-id") ?? response.headers.get("x-cstar-request-id");
+        this.captureMeta(json, headerRequestId);
+        return this.unwrapEnvelope(json);
       }
       const errorBody = await response.json().catch(() => null);
       const retryAfter = parseInt(response.headers.get("Retry-After") ?? "", 10) || void 0;
@@ -229,6 +360,51 @@ var HttpClient = class {
     }
     throw lastError ?? new Error("Request failed after retries");
   }
+  /**
+   * Capture `meta`, `requestId`, and `pagination` from the raw response
+   * into `this.lastMeta` before unwrapping the envelope.
+   */
+  captureMeta(body, headerRequestId) {
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+      const obj = body;
+      const meta = obj.meta && typeof obj.meta === "object" ? obj.meta : null;
+      const pagination = obj.pagination && typeof obj.pagination === "object" ? obj.pagination : null;
+      this.lastMeta = {
+        requestId: headerRequestId ?? (typeof meta?.requestId === "string" ? meta.requestId : null),
+        timestamp: typeof meta?.timestamp === "string" ? meta.timestamp : null,
+        pagination
+      };
+      return;
+    }
+    this.lastMeta = { requestId: headerRequestId, timestamp: null, pagination: null };
+  }
+  /**
+   * Unwrap the legacy `{success, data, meta, pagination?}` envelope.
+   * - `{success:true, data: array, pagination}` → `{data, pagination, hasMore}`
+   * - `{success:true, data: object}` → `data` (bare resource)
+   * - other shapes pass through unchanged so subpath SDKs (chat, library) keep
+   *   their bespoke shapes for now.
+   */
+  unwrapEnvelope(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) return body;
+    const obj = body;
+    if (obj.success !== true || !("data" in obj)) return body;
+    const data = obj.data;
+    if (Array.isArray(data)) {
+      const pagination = obj.pagination ?? null;
+      return {
+        data,
+        pagination: pagination ?? {
+          total: data.length,
+          page: 1,
+          pageSize: data.length,
+          hasMore: false
+        },
+        hasMore: pagination?.hasMore ?? false
+      };
+    }
+    return data;
+  }
   buildUrl(path, query) {
     const base = `${this.config.baseUrl}/api/v1/teams/${this.config.teamId}${path}`;
     if (!query) return base;
@@ -301,6 +477,18 @@ var CStarRealtime = class {
     this.autoReconnect = options?.autoReconnect ?? true;
     this.maxRetries = options?.maxRetries ?? 10;
     this.types = options?.types;
+    this.eventSourceCtor = options?.eventSource;
+  }
+  /**
+   * Resolve the EventSource constructor to use for this connection.
+   * Returns the explicit polyfill when one was injected, otherwise the
+   * global. Returns `undefined` when neither is available — callers must
+   * convert to `CStarRealtimeUnavailableError` before touching it.
+   */
+  resolveEventSource() {
+    if (this.eventSourceCtor) return this.eventSourceCtor;
+    const fromGlobal = globalThis.EventSource;
+    return typeof fromGlobal === "function" ? fromGlobal : void 0;
   }
   /** Subscribe to a specific event type. Supports wildcards (e.g., 'ticket.*'). Returns an unsubscribe function. */
   on(eventType, handler) {
@@ -355,6 +543,9 @@ var CStarRealtime = class {
   /** Start the SSE connection. Called automatically on first handler registration. */
   connect() {
     if (this.eventSource || this.destroyed || this.connecting) return;
+    if (!this.resolveEventSource()) {
+      throw new CStarRealtimeUnavailableError();
+    }
     this.connecting = true;
     const headers = this.httpClient.getAuthHeaders();
     const rawKey = headers.Authorization?.replace("Bearer ", "") ?? "";
@@ -393,7 +584,12 @@ var CStarRealtime = class {
     }
     const separator = qs ? "&" : "?";
     const authenticatedUrl = authToken ? `${url}${separator}token=${authToken}` : url;
-    this.eventSource = new EventSource(authenticatedUrl);
+    const Ctor = this.resolveEventSource();
+    if (!Ctor) {
+      this.connecting = false;
+      throw new CStarRealtimeUnavailableError();
+    }
+    this.eventSource = new Ctor(authenticatedUrl);
     this.eventSource.onopen = () => {
       this.connecting = false;
       this.retryCount = 0;
@@ -812,6 +1008,14 @@ var BaseResource = class {
   async del(id) {
     return this.client.request("DELETE", `${this.basePath}/${id}`);
   }
+  /**
+   * Delete a resource by ID. Alias for `del()` — kept because IDE
+   * auto-complete and documentation both surface `delete` first. Closes
+   * NEW-v2-06.
+   */
+  async delete(id) {
+    return this.del(id);
+  }
   /**
    * Auto-paginating async iterator that yields every item across all pages.
    *
@@ -1910,7 +2114,12 @@ var GameResource = class {
   async getPlayer(memberId) {
     return this.client.request("GET", `/game/player/${memberId}`);
   }
-  /** Get the team leaderboard. */
+  /**
+   * Get the team leaderboard. Returns the unwrapped envelope from the
+   * `/game/leaderboard` endpoint (`{entries, totalParticipants, period, ...}`)
+   * — wider than a flat array because the server includes the period and
+   * a participant count alongside the entries.
+   */
   async leaderboard(params) {
     return this.client.request("GET", "/game/leaderboard", {
       query: params
@@ -1933,12 +2142,12 @@ var GameResource = class {
    */
   subscribeBoss(realtime) {
     const fetchFn = async () => {
-      const res = await this.boss.current();
+      const boss = await this.boss.current();
+      const list = boss.active ? [boss] : [];
       return {
-        success: true,
-        data: res.data.active ? [res.data] : [],
-        pagination: { total: res.data.active ? 1 : 0, page: 1, pageSize: 1, hasMore: false },
-        meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+        data: list,
+        pagination: { total: list.length, page: 1, pageSize: 1, hasMore: false },
+        hasMore: false
       };
     };
     return new Subscription(realtime, fetchFn, "/game/boss");
@@ -1949,12 +2158,11 @@ var GameResource = class {
    */
   subscribePlayer(realtime, userId) {
     const fetchFn = async () => {
-      const res = await this.player({ userId });
+      const player = await this.player({ userId });
       return {
-        success: true,
-        data: [res.data],
+        data: [player],
         pagination: { total: 1, page: 1, pageSize: 1, hasMore: false },
-        meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+        hasMore: false
       };
     };
     return new Subscription(realtime, fetchFn, "/game/player");
@@ -1965,14 +2173,12 @@ var GameResource = class {
    */
   subscribeLeaderboard(realtime, params) {
     const fetchFn = async () => {
-      const res = await this.leaderboard(params);
-      const envelope = res.data;
-      const entries = Array.isArray(envelope) ? envelope : envelope?.entries ?? [];
+      const board = await this.leaderboard(params);
+      const entries = board.entries ?? [];
       return {
-        success: true,
         data: entries,
         pagination: { total: entries.length, page: 1, pageSize: 100, hasMore: false },
-        meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+        hasMore: false
       };
     };
     return new Subscription(realtime, fetchFn, "/game/leaderboard");
@@ -1983,13 +2189,12 @@ var GameResource = class {
    */
   subscribeActivity(realtime) {
     const fetchFn = async () => {
-      const res = await this.activity.list({ limit: 50 });
-      const data = res.data.data || [];
+      const feed = await this.activity.list({ limit: 50 });
+      const items = feed.data ?? [];
       return {
-        success: true,
-        data,
-        pagination: { total: data.length, page: 1, pageSize: 50, hasMore: false },
-        meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+        data: items,
+        pagination: { total: items.length, page: 1, pageSize: 50, hasMore: false },
+        hasMore: false
       };
     };
     return new Subscription(realtime, fetchFn, "/game/activity");
@@ -2227,6 +2432,35 @@ var CStarClient = class {
   get isTestMode() {
     return this._httpClient.environment === "test";
   }
+  /**
+   * Validate the configured API key and return the team + key metadata it
+   * resolves to. Useful for confirming the key is wired up correctly during
+   * onboarding (and for AI assistants that want a one-call sanity check).
+   *
+   * Closes F-018.
+   *
+   * ```ts
+   * const me = await cstar.whoami();
+   * console.log(me.teamSlug, me.environment); // 'acme', 'test'
+   * ```
+   */
+  async whoami() {
+    return this._httpClient.requestUnscoped("GET", "/auth/whoami");
+  }
+  /**
+   * Side-channel metadata from the most recent HTTP response. Holds the
+   * server `requestId` (for support escalations), `timestamp`, and the
+   * `pagination` info from list endpoints. Reset on every call — read it
+   * immediately after awaiting the call you care about.
+   *
+   * ```ts
+   * const ticket = await cstar.tickets.create({...});
+   * console.error('Created', ticket.id, 'request:', cstar.lastMeta.requestId);
+   * ```
+   */
+  get lastMeta() {
+    return this._httpClient.lastMeta;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -2234,6 +2468,7 @@ var CStarClient = class {
   CStarClient,
   CStarConflictError,
   CStarError,
+  CStarFeatureDisabledError,
   CStarNotFoundError,
   CStarPermissionError,
   CStarRateLimitError,