@cstar.help/js 0.5.2 → 0.6.1

package/dist/index.js

@@ -1,10 +1,13 @@
 // src/errors.ts
 var ErrorType = {
   AUTHENTICATION_ERROR: "authentication_error",
+  PERMISSION_ERROR: "permission_error",
   INVALID_REQUEST_ERROR: "invalid_request_error",
   NOT_FOUND_ERROR: "not_found_error",
+  CONFLICT_ERROR: "conflict_error",
   RATE_LIMIT_ERROR: "rate_limit_error",
-  API_ERROR: "api_error"
+  API_ERROR: "api_error",
+  SERVER_ERROR: "server_error"
 };
 var CStarError = class extends Error {
   constructor(statusCode, body) {
@@ -43,6 +46,24 @@ var CStarValidationError = class extends CStarError {
     this.name = "CStarValidationError";
   }
 };
+var CStarPermissionError = class extends CStarError {
+  constructor(statusCode, body) {
+    super(statusCode, body);
+    this.name = "CStarPermissionError";
+  }
+};
+var CStarConflictError = class extends CStarError {
+  constructor(statusCode, body) {
+    super(statusCode, body);
+    this.name = "CStarConflictError";
+  }
+};
+var CStarServerError = class extends CStarError {
+  constructor(statusCode, body) {
+    super(statusCode, body);
+    this.name = "CStarServerError";
+  }
+};
 function parseError(statusCode, body, retryAfter) {
   const errorBody = body?.error ?? {
     type: ErrorType.API_ERROR,
@@ -53,19 +74,28 @@ function parseError(statusCode, body, retryAfter) {
   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);
   }
 }
 
 // src/client.ts
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.2";
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;
@@ -122,10 +152,21 @@ var HttpClient = class {
       }
       if (response.ok) {
         if (response.status === 204) return void 0;
-        return await response.json();
+        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 errorBody = await response.json().catch(() => null);
       const retryAfter = parseInt(response.headers.get("Retry-After") ?? "", 10) || void 0;
+      const requestId = response.headers.get("x-request-id") ?? response.headers.get("x-cstar-request-id");
+      if (requestId && errorBody?.error) {
+        errorBody.error.request_id = requestId;
+      }
       if (response.status < 500 && response.status !== 429) {
         throw parseError(response.status, errorBody, retryAfter);
       }
@@ -169,6 +210,14 @@ var HttpClient = class {
     }
     return headers;
   }
+  /** Get the base URL for building SSE or other endpoints. */
+  getBaseUrl() {
+    return `${this.config.baseUrl}/api/v1/teams/${this.config.teamId}`;
+  }
+  /** Get authorization headers for non-fetch requests (e.g., SSE). */
+  getAuthHeaders() {
+    return this.buildHeaders();
+  }
   /** Exponential backoff: 500ms, 1s, 2s, 4s... capped at 8s, plus jitter. */
   getBackoffDelay(attempt) {
     const base = Math.min(500 * Math.pow(2, attempt - 1), 8e3);
@@ -180,6 +229,504 @@ var HttpClient = class {
   }
 };
 
+// src/realtime.ts
+var CStarRealtime = class {
+  constructor(httpClient, options) {
+    this.httpClient = httpClient;
+    this.eventSource = null;
+    this.handlers = /* @__PURE__ */ new Map();
+    this.anyHandlers = /* @__PURE__ */ new Set();
+    this.errorHandlers = /* @__PURE__ */ new Set();
+    this.connectionHandlers = /* @__PURE__ */ new Set();
+    this.lastEventId = null;
+    this.retryCount = 0;
+    this.retryTimer = null;
+    this._connected = false;
+    this.destroyed = false;
+    this.connecting = false;
+    /** Short-lived SSE token (exchanged from secret key). */
+    this.sseToken = null;
+    /** When the current SSE token expires (epoch ms). */
+    this.sseTokenExpiresAt = 0;
+    /** Timer that refreshes the SSE token before it expires. */
+    this.tokenRefreshTimer = null;
+    this.autoReconnect = options?.autoReconnect ?? true;
+    this.maxRetries = options?.maxRetries ?? 10;
+    this.types = options?.types;
+  }
+  /** Subscribe to a specific event type. Supports wildcards (e.g., 'ticket.*'). Returns an unsubscribe function. */
+  on(eventType, handler) {
+    let set = this.handlers.get(eventType);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(eventType, set);
+    }
+    set.add(handler);
+    this.ensureConnected();
+    return () => {
+      set.delete(handler);
+    };
+  }
+  /** Subscribe to all events. Returns an unsubscribe function. */
+  onAny(handler) {
+    this.anyHandlers.add(handler);
+    this.ensureConnected();
+    return () => {
+      this.anyHandlers.delete(handler);
+    };
+  }
+  /** Handle connection errors. */
+  onError(handler) {
+    this.errorHandlers.add(handler);
+    return this;
+  }
+  /** Handle connection state changes. */
+  onConnectionChange(handler) {
+    this.connectionHandlers.add(handler);
+    return this;
+  }
+  /** Remove a connection state handler. */
+  offConnectionChange(handler) {
+    this.connectionHandlers.delete(handler);
+    return this;
+  }
+  /** Remove a handler for a specific event type. */
+  off(eventType, handler) {
+    const set = this.handlers.get(eventType);
+    if (set) {
+      set.delete(handler);
+      if (set.size === 0) this.handlers.delete(eventType);
+    }
+    return this;
+  }
+  /** Remove a handler from the "any" subscription. */
+  offAny(handler) {
+    this.anyHandlers.delete(handler);
+    return this;
+  }
+  /** Start the SSE connection. Called automatically on first handler registration. */
+  connect() {
+    if (this.eventSource || this.destroyed || this.connecting) return;
+    this.connecting = true;
+    const headers = this.httpClient.getAuthHeaders();
+    const rawKey = headers.Authorization?.replace("Bearer ", "") ?? "";
+    if (rawKey.startsWith("sk_") && !this.hasFreshSseToken()) {
+      this.exchangeToken().then(() => {
+        this.connecting = false;
+        this.connect();
+      }).catch(() => {
+        this.connecting = false;
+        this.connectWithToken(rawKey);
+      });
+      return;
+    }
+    const token = this.sseToken ?? rawKey;
+    this.connectWithToken(token);
+  }
+  /**
+   * Open the EventSource with the given auth token.
+   * Extracted so both the happy path and the fallback path share logic.
+   */
+  connectWithToken(authToken) {
+    const baseUrl = this.httpClient.getBaseUrl();
+    const params = new URLSearchParams();
+    if (this.types && this.types.length > 0) {
+      params.set("types", this.types.join(","));
+    }
+    if (this.lastEventId) {
+      params.set("since", this.lastEventId);
+    }
+    const qs = params.toString();
+    const url = `${baseUrl}/events/stream${qs ? `?${qs}` : ""}`;
+    if (authToken.startsWith("sk_") && typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined") {
+      console.warn(
+        "[cStar] Secret API key is being passed via SSE query parameter. Query strings may be logged by proxies and CDNs. For production, use a server-side proxy to add the Authorization header."
+      );
+    }
+    const separator = qs ? "&" : "?";
+    const authenticatedUrl = authToken ? `${url}${separator}token=${authToken}` : url;
+    this.eventSource = new EventSource(authenticatedUrl);
+    this.eventSource.onopen = () => {
+      this.connecting = false;
+      this.retryCount = 0;
+      this.setConnected(true);
+    };
+    this.eventSource.onerror = () => {
+      this.connecting = false;
+      this.setConnected(false);
+      if (this.eventSource) {
+        this.eventSource.close();
+        this.eventSource = null;
+      }
+      if (this.autoReconnect && !this.destroyed && this.retryCount < this.maxRetries) {
+        this.scheduleReconnect();
+      } else if (this.retryCount >= this.maxRetries) {
+        this.emitError(new Error(`Realtime connection failed after ${this.maxRetries} retries`));
+      }
+    };
+    this.eventSource.onmessage = (event) => {
+      this.handleMessage(event);
+    };
+    const knownTypes = [
+      "ticket.created",
+      "ticket.updated",
+      "ticket.closed",
+      "ticket.assigned",
+      "message.created",
+      "message.updated",
+      "notification.created",
+      "mention.created",
+      // Gamification events (future)
+      "boss.spawned",
+      "boss.damaged",
+      "boss.defeated",
+      "achievement.unlocked",
+      "quest.completed",
+      "level.up"
+    ];
+    for (const type of knownTypes) {
+      this.eventSource.addEventListener(type, (event) => {
+        const msgEvent = event;
+        if (msgEvent.lastEventId) {
+          this.lastEventId = msgEvent.lastEventId;
+        }
+        try {
+          const parsed = JSON.parse(msgEvent.data);
+          const realtimeEvent = {
+            type: parsed.type || type,
+            id: msgEvent.lastEventId || "",
+            data: parsed.data || parsed,
+            timestamp: parsed.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+            teamId: parsed.teamId || ""
+          };
+          this.dispatch(realtimeEvent);
+        } catch {
+        }
+      });
+    }
+  }
+  /** Stop listening and clean up all resources. */
+  disconnect() {
+    this.destroyed = true;
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    if (this.tokenRefreshTimer) {
+      clearTimeout(this.tokenRefreshTimer);
+      this.tokenRefreshTimer = null;
+    }
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.sseToken = null;
+    this.sseTokenExpiresAt = 0;
+    this.setConnected(false);
+    this.handlers.clear();
+    this.anyHandlers.clear();
+    this.errorHandlers.clear();
+    this.connectionHandlers.clear();
+  }
+  /** Whether the SSE connection is currently open. */
+  get connected() {
+    return this._connected;
+  }
+  // ── Internal ──
+  ensureConnected() {
+    if (!this.eventSource && !this.destroyed) {
+      this.connect();
+    }
+  }
+  handleMessage(event) {
+    if (event.lastEventId) {
+      this.lastEventId = event.lastEventId;
+    }
+    try {
+      const parsed = JSON.parse(event.data);
+      if (parsed.type === "connected") return;
+      const realtimeEvent = {
+        type: parsed.type,
+        id: event.lastEventId || "",
+        data: parsed.data || parsed,
+        timestamp: parsed.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+        teamId: parsed.teamId || ""
+      };
+      this.dispatch(realtimeEvent);
+    } catch {
+    }
+  }
+  dispatch(event) {
+    const exactSet = this.handlers.get(event.type);
+    if (exactSet) {
+      for (const handler of exactSet) handler(event);
+    }
+    for (const [pattern, handlerSet] of this.handlers) {
+      if (pattern.endsWith(".*")) {
+        const prefix = pattern.slice(0, -2);
+        if (event.type.startsWith(prefix + ".") && pattern !== event.type) {
+          for (const handler of handlerSet) handler(event);
+        }
+      }
+    }
+    for (const handler of this.anyHandlers) handler(event);
+  }
+  scheduleReconnect() {
+    this.retryCount++;
+    const delay = Math.min(500 * Math.pow(2, this.retryCount - 1), 8e3) + Math.random() * 200;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      if (!this.destroyed) {
+        this.connect();
+      }
+    }, delay);
+  }
+  setConnected(value) {
+    if (this._connected !== value) {
+      this._connected = value;
+      for (const handler of this.connectionHandlers) handler(value);
+    }
+  }
+  emitError(error) {
+    for (const handler of this.errorHandlers) handler(error);
+  }
+  // ── SSE Token Exchange ──
+  /** Whether we hold a token that won't expire for at least 30 seconds. */
+  hasFreshSseToken() {
+    return !!this.sseToken && this.sseTokenExpiresAt - Date.now() > 3e4;
+  }
+  /**
+   * Exchange the secret API key for a short-lived SSE token via
+   * POST /events/token. Schedules automatic refresh before expiry.
+   */
+  async exchangeToken() {
+    const response = await this.httpClient.request("POST", "/events/token");
+    const { token, expiresAt, expiresIn } = response.data;
+    this.sseToken = token;
+    this.sseTokenExpiresAt = new Date(expiresAt).getTime();
+    const refreshIn = Math.max((expiresIn - 30) * 1e3, expiresIn / 2 * 1e3);
+    this.scheduleTokenRefresh(refreshIn);
+  }
+  /**
+   * Schedule a background token refresh. On success the existing connection
+   * keeps working (tokens are validated at connect time). On the next
+   * reconnect the fresh token will be used automatically.
+   */
+  scheduleTokenRefresh(delayMs) {
+    if (this.tokenRefreshTimer) clearTimeout(this.tokenRefreshTimer);
+    this.tokenRefreshTimer = setTimeout(() => {
+      this.tokenRefreshTimer = null;
+      if (this.destroyed) return;
+      this.exchangeToken().catch(() => {
+      });
+    }, delayMs);
+  }
+};
+
+// src/subscription.ts
+var RESOURCE_EVENT_MAP = {
+  "/tickets": ["ticket.created", "ticket.updated", "ticket.closed", "ticket.assigned"],
+  "/customers": ["customer.created", "customer.updated"],
+  "/articles": ["article.created", "article.updated", "article.published"],
+  "/messages": ["message.created", "message.updated"],
+  "/notifications": ["notification.created"],
+  "/mentions": ["mention.created"],
+  "/game/boss": ["boss.spawned", "boss.damaged", "boss.defeated"],
+  "/game/player": ["achievement.unlocked", "quest.completed", "level.up", "player.updated"],
+  "/game/leaderboard": [
+    "leaderboard.updated",
+    "achievement.unlocked",
+    "quest.completed",
+    "level.up"
+  ],
+  "/game/activity": [
+    "boss.spawned",
+    "boss.defeated",
+    "achievement.unlocked",
+    "level.up",
+    "quest.completed"
+  ]
+};
+function getEntityId(item) {
+  if (!item || typeof item !== "object") return void 0;
+  const obj = item;
+  return obj.id ?? obj.userId ?? void 0;
+}
+var Subscription = class {
+  constructor(realtime, fetchFn, resourcePath, filterFn) {
+    this.realtime = realtime;
+    this.fetchFn = fetchFn;
+    this.resourcePath = resourcePath;
+    this.filterFn = filterFn;
+    this._data = [];
+    this._loading = true;
+    this._error = null;
+    this.changeHandlers = /* @__PURE__ */ new Set();
+    this.errorEventHandlers = /* @__PURE__ */ new Set();
+    this.boundEventHandler = null;
+    this.destroyed = false;
+    /** Generation counter to prevent stale refresh() from overwriting SSE updates. */
+    this.generation = 0;
+    this.init();
+  }
+  /** Current data array (updated in real-time). */
+  get data() {
+    return this._data;
+  }
+  /** True during initial data fetch. */
+  get loading() {
+    return this._loading;
+  }
+  /** Last error, if any. */
+  get error() {
+    return this._error;
+  }
+  on(event, handler) {
+    if (event === "change") {
+      this.changeHandlers.add(handler);
+    } else if (event === "error") {
+      this.errorEventHandlers.add(handler);
+    }
+    return this;
+  }
+  /** Manually refresh data from the server. */
+  async refresh() {
+    const gen = ++this.generation;
+    try {
+      const response = await this.fetchFn();
+      if (gen !== this.generation) return;
+      this._data = response.data;
+      this._error = null;
+      this.emitChange();
+    } catch (err) {
+      if (gen !== this.generation) return;
+      this._error = err instanceof Error ? err : new Error(String(err));
+      this.emitError(this._error);
+    }
+  }
+  /**
+   * Apply an optimistic update to the local data.
+   * Returns a rollback function that reverts the change.
+   */
+  optimisticUpdate(id, changes) {
+    const snapshot = [...this._data];
+    const index = this._data.findIndex((item) => getEntityId(item) === id);
+    if (index !== -1) {
+      this._data[index] = { ...this._data[index], ...changes };
+      if (this.filterFn && !this.filterFn(this._data[index])) {
+        this._data.splice(index, 1);
+      }
+      this.emitChange();
+    }
+    return () => {
+      this._data = snapshot;
+      this.emitChange();
+    };
+  }
+  /** Stop the subscription and clean up all listeners. */
+  unsubscribe() {
+    this.destroyed = true;
+    if (this.boundEventHandler) {
+      this.realtime.offAny(this.boundEventHandler);
+      this.boundEventHandler = null;
+    }
+    this.changeHandlers.clear();
+    this.errorEventHandlers.clear();
+  }
+  // ── Internal ──
+  async init() {
+    this.boundEventHandler = (event) => this.handleEvent(event);
+    this.realtime.onAny(this.boundEventHandler);
+    const gen = ++this.generation;
+    try {
+      const response = await this.fetchFn();
+      if (gen !== this.generation) return;
+      this._data = response.data;
+      this._loading = false;
+      this._error = null;
+      this.emitChange();
+    } catch (err) {
+      if (gen !== this.generation) return;
+      this._loading = false;
+      this._error = err instanceof Error ? err : new Error(String(err));
+      this.emitError(this._error);
+    }
+  }
+  handleEvent(event) {
+    if (this.destroyed) return;
+    const eventTypes = RESOURCE_EVENT_MAP[this.resourcePath];
+    if (eventTypes) {
+      const isRelevant = eventTypes.some((t) => {
+        const prefix = t.split(".")[0];
+        return event.type.startsWith(prefix + ".");
+      });
+      if (!isRelevant) return;
+    } else {
+      const eventPrefix = event.type.split(".")[0];
+      const segments = this.resourcePath.replace(/^\//, "").split("/");
+      const resourceName = segments[segments.length - 1];
+      if (resourceName !== eventPrefix && resourceName !== eventPrefix + "s") return;
+    }
+    const entityData = this.extractEntity(event);
+    if (!entityData || !getEntityId(entityData)) return;
+    this.generation++;
+    if (event.type.endsWith(".created")) {
+      this.handleCreated(entityData);
+    } else if (event.type.endsWith(".deleted")) {
+      this.handleDeleted(entityData);
+    } else if (event.type.endsWith(".updated") || event.type.endsWith(".assigned") || event.type.endsWith(".closed")) {
+      this.handleUpdated(entityData);
+    }
+  }
+  handleCreated(entity) {
+    if (this.filterFn && !this.filterFn(entity)) return;
+    const entityId = getEntityId(entity);
+    if (entityId && this._data.some((item) => getEntityId(item) === entityId)) return;
+    this._data = [entity, ...this._data];
+    this.emitChange();
+  }
+  handleDeleted(entity) {
+    const entityId = getEntityId(entity);
+    if (!entityId) return;
+    const index = this._data.findIndex((item) => getEntityId(item) === entityId);
+    if (index !== -1) {
+      this._data = [...this._data.slice(0, index), ...this._data.slice(index + 1)];
+      this.emitChange();
+    }
+  }
+  handleUpdated(entity) {
+    const entityId = getEntityId(entity);
+    const index = entityId ? this._data.findIndex((item) => getEntityId(item) === entityId) : -1;
+    if (index !== -1) {
+      const updated = { ...this._data[index], ...entity };
+      if (this.filterFn && !this.filterFn(updated)) {
+        this._data = [...this._data.slice(0, index), ...this._data.slice(index + 1)];
+      } else {
+        this._data = [...this._data.slice(0, index), updated, ...this._data.slice(index + 1)];
+      }
+      this.emitChange();
+    } else if (this.filterFn && this.filterFn(entity)) {
+      this._data = [entity, ...this._data];
+      this.emitChange();
+    }
+  }
+  extractEntity(event) {
+    const data = event.data;
+    const resourceKey = this.resourcePath.replace(/^\//, "").replace(/s$/, "");
+    if (data[resourceKey] && typeof data[resourceKey] === "object") {
+      return data[resourceKey];
+    }
+    if (data.id) return data;
+    return null;
+  }
+  emitChange() {
+    for (const handler of this.changeHandlers) handler(this._data);
+  }
+  emitError(error) {
+    for (const handler of this.errorEventHandlers) handler(error);
+  }
+};
+
 // src/resources/base.ts
 var BaseResource = class {
   constructor(client, basePath) {
@@ -238,6 +785,22 @@ var BaseResource = class {
       page++;
     }
   }
+  /**
+   * Subscribe to real-time changes for this resource type.
+   *
+   * Fetches initial data, then auto-updates via SSE events.
+   * Requires a `CStarRealtime` instance (available from `CStarClient.realtime`).
+   *
+   * ```typescript
+   * const sub = cstar.tickets.subscribe(cstar.realtime, { status: 'open' });
+   * sub.on('change', (tickets) => console.log(tickets));
+   * // Later: sub.unsubscribe();
+   * ```
+   */
+  subscribe(realtime, params, filterFn) {
+    const fetchFn = () => this.list(params);
+    return new Subscription(realtime, fetchFn, this.basePath, filterFn);
+  }
   /** Convert params to string values for query string serialization. */
   serializeQuery(params) {
     const result = {};
@@ -322,7 +885,7 @@ var WebhooksResource = class extends BaseResource {
     );
   }
   /** Subscribe to an event (REST Hooks / Zapier protocol). */
-  async subscribe(params, options) {
+  async restSubscribe(params, options) {
     return this.client.request("POST", "/webhooks/subscribe", {
       body: params,
       idempotencyKey: options?.idempotencyKey
@@ -1315,6 +1878,72 @@ var GameResource = class {
   async config() {
     return this.client.request("GET", "/game/config");
   }
+  // ── Real-time Subscriptions ──
+  /**
+   * Subscribe to live boss battle state.
+   * Updates on boss.spawned, boss.damaged, boss.defeated events.
+   */
+  subscribeBoss(realtime) {
+    const fetchFn = async () => {
+      const res = await this.boss.current();
+      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() }
+      };
+    };
+    return new Subscription(realtime, fetchFn, "/game/boss");
+  }
+  /**
+   * Subscribe to player stats (XP, gold, level, streaks).
+   * Updates on achievement.unlocked, quest.completed, level.up events.
+   */
+  subscribePlayer(realtime, userId) {
+    const fetchFn = async () => {
+      const res = await this.player({ userId });
+      return {
+        success: true,
+        data: [res.data],
+        pagination: { total: 1, page: 1, pageSize: 1, hasMore: false },
+        meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+      };
+    };
+    return new Subscription(realtime, fetchFn, "/game/player");
+  }
+  /**
+   * Subscribe to the team leaderboard.
+   * Updates when scores change.
+   */
+  subscribeLeaderboard(realtime, params) {
+    const fetchFn = async () => {
+      const res = await this.leaderboard(params);
+      return {
+        success: true,
+        data: res.data,
+        pagination: { total: res.data.length, page: 1, pageSize: 100, hasMore: false },
+        meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+      };
+    };
+    return new Subscription(realtime, fetchFn, "/game/leaderboard");
+  }
+  /**
+   * Subscribe to team activity feed (achievements, boss defeats, level ups).
+   * Rolling feed of recent game events.
+   */
+  subscribeActivity(realtime) {
+    const fetchFn = async () => {
+      const res = await this.activity.list({ limit: 50 });
+      const data = res.data.data || [];
+      return {
+        success: true,
+        data,
+        pagination: { total: data.length, page: 1, pageSize: 50, hasMore: false },
+        meta: { requestId: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+      };
+    };
+    return new Subscription(realtime, fetchFn, "/game/activity");
+  }
 };
 
 // src/resources/ai.ts
@@ -1377,52 +2006,190 @@ var BillingResource = class {
   }
 };
 
+// src/offline.ts
+var STORAGE_KEY = "cstar_offline_queue";
+var OfflineQueue = class {
+  constructor(httpClient, options) {
+    this.httpClient = httpClient;
+    this.items = [];
+    this.autoFlushEnabled = false;
+    this.onlineHandler = null;
+    this.useLocalStorage = options?.storage === "localStorage" && typeof globalThis !== "undefined" && typeof globalThis.localStorage !== "undefined";
+    if (this.useLocalStorage) {
+      this.loadFromStorage();
+    }
+  }
+  /** Queue a mutation for later execution. Returns a queue item ID. */
+  enqueue(method, path, body) {
+    const id = `q_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const item = {
+      id,
+      method,
+      path,
+      body,
+      queuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.items.push(item);
+    this.saveToStorage();
+    return id;
+  }
+  /**
+   * Process all queued mutations in order. Returns results for each item.
+   * Failed items are re-queued at the front to preserve ordering.
+   * Items enqueued during flush are appended after re-queued failures.
+   */
+  async flush() {
+    const results = [];
+    const itemsToProcess = [...this.items];
+    this.items = [];
+    this.saveToStorage();
+    const failedItems = [];
+    for (const item of itemsToProcess) {
+      try {
+        const data = await this.httpClient.request(item.method, item.path, {
+          body: item.body
+        });
+        results.push({ id: item.id, success: true, data });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        results.push({ id: item.id, success: false, error: message });
+        const statusCode = err.statusCode;
+        const isRetryable = !statusCode || statusCode >= 500;
+        if (isRetryable) {
+          failedItems.push(item);
+        }
+      }
+    }
+    this.items = [...failedItems, ...this.items];
+    this.saveToStorage();
+    return results;
+  }
+  /** Get pending queue items. */
+  get pending() {
+    return [...this.items];
+  }
+  /** Number of items in the queue. */
+  get size() {
+    return this.items.length;
+  }
+  /** Clear all pending items. */
+  clear() {
+    this.items = [];
+    this.saveToStorage();
+  }
+  /**
+   * Enable auto-flush when the browser goes online.
+   * Only works in browser environments with the `online` event.
+   */
+  enableAutoFlush() {
+    if (this.autoFlushEnabled) return;
+    if (typeof globalThis === "undefined" || typeof globalThis.addEventListener !== "function") {
+      return;
+    }
+    this.autoFlushEnabled = true;
+    this.onlineHandler = () => {
+      if (this.items.length > 0) {
+        this.flush().catch(() => {
+        });
+      }
+    };
+    globalThis.addEventListener("online", this.onlineHandler);
+  }
+  /** Disable auto-flush and clean up event listeners. */
+  disableAutoFlush() {
+    if (!this.autoFlushEnabled || !this.onlineHandler) return;
+    if (typeof globalThis !== "undefined" && typeof globalThis.removeEventListener === "function") {
+      globalThis.removeEventListener("online", this.onlineHandler);
+    }
+    this.onlineHandler = null;
+    this.autoFlushEnabled = false;
+  }
+  saveToStorage() {
+    if (!this.useLocalStorage) return;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(this.items));
+    } catch {
+    }
+  }
+  loadFromStorage() {
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY);
+      if (raw) {
+        this.items = JSON.parse(raw);
+      }
+    } catch {
+      this.items = [];
+    }
+  }
+};
+
 // src/index.ts
 var CStarClient = class {
   constructor(config) {
-    this.client = new HttpClient(config);
-    this.tickets = new TicketsResource(this.client);
-    this.customers = new CustomersResource(this.client);
-    this.articles = new ArticlesResource(this.client);
-    this.webhooks = new WebhooksResource(this.client);
-    this.automations = new AutomationsResource(this.client);
-    this.categories = new CategoriesResource(this.client);
+    this._httpClient = new HttpClient(config);
+    this.tickets = new TicketsResource(this._httpClient);
+    this.customers = new CustomersResource(this._httpClient);
+    this.articles = new ArticlesResource(this._httpClient);
+    this.webhooks = new WebhooksResource(this._httpClient);
+    this.automations = new AutomationsResource(this._httpClient);
+    this.categories = new CategoriesResource(this._httpClient);
     this.community = {
-      posts: new CommunityPostsResource(this.client),
-      topics: new CommunityTopicsResource(this.client)
+      posts: new CommunityPostsResource(this._httpClient),
+      topics: new CommunityTopicsResource(this._httpClient)
     };
-    this.members = new MembersResource(this.client);
-    this.settings = new SettingsResource(this.client);
-    this.notifications = new NotificationsResource(this.client);
-    this.mentions = new MentionsResource(this.client);
-    this.attachments = new AttachmentsResource(this.client);
-    this.customFields = new CustomFieldsResource(this.client);
-    this.sla = new SlaResource(this.client);
-    this.analytics = new AnalyticsResource(this.client);
-    this.bulk = new BulkResource(this.client);
-    this.export = new ExportResource(this.client);
-    this.import = new ImportResource(this.client);
-    this.auditLog = new AuditLogResource(this.client);
-    this.search = new SearchResource(this.client);
-    this.tags = new TagsResource(this.client);
-    this.activity = new ActivityResource(this.client);
-    this.customerGroups = new CustomerGroupsResource(this.client);
-    this.game = new GameResource(this.client);
-    this.ai = new AiResource(this.client);
-    this.views = new ViewsResource(this.client);
-    this.billing = new BillingResource(this.client);
+    this.members = new MembersResource(this._httpClient);
+    this.settings = new SettingsResource(this._httpClient);
+    this.notifications = new NotificationsResource(this._httpClient);
+    this.mentions = new MentionsResource(this._httpClient);
+    this.attachments = new AttachmentsResource(this._httpClient);
+    this.customFields = new CustomFieldsResource(this._httpClient);
+    this.sla = new SlaResource(this._httpClient);
+    this.analytics = new AnalyticsResource(this._httpClient);
+    this.bulk = new BulkResource(this._httpClient);
+    this.export = new ExportResource(this._httpClient);
+    this.import = new ImportResource(this._httpClient);
+    this.auditLog = new AuditLogResource(this._httpClient);
+    this.search = new SearchResource(this._httpClient);
+    this.tags = new TagsResource(this._httpClient);
+    this.activity = new ActivityResource(this._httpClient);
+    this.customerGroups = new CustomerGroupsResource(this._httpClient);
+    this.game = new GameResource(this._httpClient);
+    this.ai = new AiResource(this._httpClient);
+    this.views = new ViewsResource(this._httpClient);
+    this.billing = new BillingResource(this._httpClient);
+    this.realtime = new CStarRealtime(this._httpClient);
+    if (config.offline) {
+      const queueOpts = typeof config.offline === "object" ? config.offline : void 0;
+      this.offlineQueue = new OfflineQueue(this._httpClient, queueOpts);
+      this.offlineQueue.enableAutoFlush();
+    } else {
+      this.offlineQueue = null;
+    }
+  }
+  /** Disconnect the realtime stream and clean up. */
+  destroy() {
+    this.realtime.disconnect();
+    if (this.offlineQueue) {
+      this.offlineQueue.disableAutoFlush();
+    }
   }
   /** Whether this client is using test mode keys (sk_test_* or pk_test_*). */
   get isTestMode() {
-    return this.client.environment === "test";
+    return this._httpClient.environment === "test";
   }
 };
 export {
   CStarAuthenticationError,
   CStarClient,
+  CStarConflictError,
   CStarError,
   CStarNotFoundError,
+  CStarPermissionError,
   CStarRateLimitError,
+  CStarRealtime,
+  CStarServerError,
   CStarValidationError,
-  ErrorType
+  ErrorType,
+  OfflineQueue,
+  Subscription
 };