@cstar.help/js 0.13.0 → 0.14.0

package/dist/chat/index.cjs

@@ -343,6 +343,7 @@ var ChatClient = class {
     this.customerId = null;
     this.authMode = null;
     this.pollingTimers = /* @__PURE__ */ new Map();
+    this.stateListeners = /* @__PURE__ */ new Set();
     this.realtimeManager = null;
     this.presenceManager = null;
     this.realtimeReady = false;
@@ -383,6 +384,7 @@ var ChatClient = class {
     this.teamId = response.data.teamId;
     this.customerId = response.data.customer.id;
     this.authMode = "hmac";
+    this.notifyStateChanged();
     if (this.realtimeEnabled) {
       this.realtimeInitPromise = this.initRealtime(
         response.data.customer.id,
@@ -442,11 +444,35 @@ var ChatClient = class {
       this.teamId = params.teamId;
     }
     this.authMode = "session";
+    this.notifyStateChanged();
     if (this.realtimeEnabled) {
       const customerName = params.customerName ?? "";
       this.realtimeInitPromise = this.initRealtimeFromSession(customerName);
     }
   }
+  /**
+   * Subscribe to client state changes (auth mode flips, identify, disconnect).
+   * Fires after the mutation, so listeners reading `getAuthMode()` /
+   * `getCustomerId()` see the new value.
+   *
+   * Returns an unsubscribe function. Closes F-041 — used by `useChat` (React)
+   * and `ChatState` (Svelte) to re-render when consumers mutate the client
+   * outside of the framework wrappers.
+   */
+  subscribe(listener) {
+    this.stateListeners.add(listener);
+    return () => {
+      this.stateListeners.delete(listener);
+    };
+  }
+  notifyStateChanged() {
+    for (const listener of this.stateListeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
   /**
    * Returns the auth mode the client is currently using, or `null` before
    * any authenticated call has resolved one. Useful for branching UI
@@ -509,6 +535,7 @@ var ChatClient = class {
     this.teamId = null;
     this.customerId = null;
     this.authMode = null;
+    this.notifyStateChanged();
   }
   /**
    * @internal Make an authenticated request to the widget API.
@@ -546,7 +573,9 @@ var ChatClient = class {
     const responseHeaders = response.headers && typeof response.headers.get === "function" ? response.headers : null;
     const headerMode = responseHeaders?.get("X-Cstar-Auth-Mode") ?? null;
     if (headerMode === "hmac" || headerMode === "session") {
+      const previous = this.authMode;
       this.authMode = headerMode;
+      if (previous !== headerMode) this.notifyStateChanged();
     }
     const requestId = responseHeaders?.get("X-Request-Id") ?? null;
     if (!response.ok) {
@@ -728,10 +757,16 @@ var TicketsApi = class {
         cursor: params?.cursor
       }
     });
+    const data = response.data.tickets ?? response.data.conversations ?? [];
+    const cursor = response.data.cursor;
+    const hasMore = response.data.hasMore;
     return {
-      tickets: response.data.tickets ?? response.data.conversations ?? [],
-      cursor: response.data.cursor,
-      hasMore: response.data.hasMore
+      data,
+      pagination: { cursor, hasMore },
+      hasMore,
+      // Deprecated aliases — same references, no extra allocation.
+      tickets: data,
+      cursor
     };
   }
   /** Create a new ticket. */

package/dist/chat/index.d.cts

@@ -107,11 +107,34 @@ interface Ticket {
      */
     messages?: Message[];
 }
-/** Paginated ticket list response. */
+/**
+ * Paginated ticket list response.
+ *
+ * As of `@cstar.help/js@0.14.0` the canonical fields match the admin SDK and
+ * library SDK envelopes (`{ data, pagination, hasMore }`). The legacy
+ * `tickets` and `cursor` fields are kept as aliases — they reference the
+ * same data — and will be removed in the next major. Closes F-037.
+ */
 interface TicketListResponse {
+    /** Tickets on this page (canonical). */
+    data: Ticket[];
+    /** Pagination cursor + a flag for whether more pages exist (canonical). */
+    pagination: {
+        cursor: string | null;
+        hasMore: boolean;
+    };
+    /** Convenience copy of `pagination.hasMore`. */
+    hasMore: boolean;
+    /**
+     * @deprecated since 0.14.0 — use `data`. Same array reference for now.
+     *   Will be removed in the next major.
+     */
     tickets: Ticket[];
+    /**
+     * @deprecated since 0.14.0 — use `pagination.cursor`. Same value.
+     *   Will be removed in the next major.
+     */
     cursor: string | null;
-    hasMore: boolean;
 }
 /** A message on a ticket. */
 interface Message {
@@ -345,6 +368,12 @@ declare class ChatClientNetworkError extends ChatClientError {
  * `ChatClientServerError`, `ChatClientNetworkError`. Each carries
  * `requestId` for correlating with server-side logs.
  */
+/**
+ * Listener for client-state changes (auth-mode flips, identity assignment,
+ * disconnects). Fires once after the underlying state mutates so a UI layer
+ * can re-read `getAuthMode()` / `getCustomerId()` and re-render. Closes F-041.
+ */
+type ChatStateListener = () => void;
 declare class ChatClient {
     private readonly baseUrl;
     private readonly teamSlug;
@@ -355,6 +384,7 @@ declare class ChatClient {
     private customerId;
     private authMode;
     private pollingTimers;
+    private stateListeners;
     private realtimeManager;
     private presenceManager;
     private realtimeReady;
@@ -397,6 +427,17 @@ declare class ChatClient {
      * every request — there is no client-side validation here.
      */
     loginWithSession(params: LoginWithSessionParams): Promise<void>;
+    /**
+     * Subscribe to client state changes (auth mode flips, identify, disconnect).
+     * Fires after the mutation, so listeners reading `getAuthMode()` /
+     * `getCustomerId()` see the new value.
+     *
+     * Returns an unsubscribe function. Closes F-041 — used by `useChat` (React)
+     * and `ChatState` (Svelte) to re-render when consumers mutate the client
+     * outside of the framework wrappers.
+     */
+    subscribe(listener: ChatStateListener): () => void;
+    private notifyStateChanged;
     /**
      * Returns the auth mode the client is currently using, or `null` before
      * any authenticated call has resolved one. Useful for branching UI
@@ -509,4 +550,4 @@ declare class MessagesApi {
     send(ticketId: string, content: string): Promise<Message>;
 }
 
-export { type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };
+export { type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type ChatStateListener, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };

package/dist/chat/index.d.ts

@@ -107,11 +107,34 @@ interface Ticket {
      */
     messages?: Message[];
 }
-/** Paginated ticket list response. */
+/**
+ * Paginated ticket list response.
+ *
+ * As of `@cstar.help/js@0.14.0` the canonical fields match the admin SDK and
+ * library SDK envelopes (`{ data, pagination, hasMore }`). The legacy
+ * `tickets` and `cursor` fields are kept as aliases — they reference the
+ * same data — and will be removed in the next major. Closes F-037.
+ */
 interface TicketListResponse {
+    /** Tickets on this page (canonical). */
+    data: Ticket[];
+    /** Pagination cursor + a flag for whether more pages exist (canonical). */
+    pagination: {
+        cursor: string | null;
+        hasMore: boolean;
+    };
+    /** Convenience copy of `pagination.hasMore`. */
+    hasMore: boolean;
+    /**
+     * @deprecated since 0.14.0 — use `data`. Same array reference for now.
+     *   Will be removed in the next major.
+     */
     tickets: Ticket[];
+    /**
+     * @deprecated since 0.14.0 — use `pagination.cursor`. Same value.
+     *   Will be removed in the next major.
+     */
     cursor: string | null;
-    hasMore: boolean;
 }
 /** A message on a ticket. */
 interface Message {
@@ -345,6 +368,12 @@ declare class ChatClientNetworkError extends ChatClientError {
  * `ChatClientServerError`, `ChatClientNetworkError`. Each carries
  * `requestId` for correlating with server-side logs.
  */
+/**
+ * Listener for client-state changes (auth-mode flips, identity assignment,
+ * disconnects). Fires once after the underlying state mutates so a UI layer
+ * can re-read `getAuthMode()` / `getCustomerId()` and re-render. Closes F-041.
+ */
+type ChatStateListener = () => void;
 declare class ChatClient {
     private readonly baseUrl;
     private readonly teamSlug;
@@ -355,6 +384,7 @@ declare class ChatClient {
     private customerId;
     private authMode;
     private pollingTimers;
+    private stateListeners;
     private realtimeManager;
     private presenceManager;
     private realtimeReady;
@@ -397,6 +427,17 @@ declare class ChatClient {
      * every request — there is no client-side validation here.
      */
     loginWithSession(params: LoginWithSessionParams): Promise<void>;
+    /**
+     * Subscribe to client state changes (auth mode flips, identify, disconnect).
+     * Fires after the mutation, so listeners reading `getAuthMode()` /
+     * `getCustomerId()` see the new value.
+     *
+     * Returns an unsubscribe function. Closes F-041 — used by `useChat` (React)
+     * and `ChatState` (Svelte) to re-render when consumers mutate the client
+     * outside of the framework wrappers.
+     */
+    subscribe(listener: ChatStateListener): () => void;
+    private notifyStateChanged;
     /**
      * Returns the auth mode the client is currently using, or `null` before
      * any authenticated call has resolved one. Useful for branching UI
@@ -509,4 +550,4 @@ declare class MessagesApi {
     send(ticketId: string, content: string): Promise<Message>;
 }
 
-export { type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };
+export { type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type ChatStateListener, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };

package/dist/chat/index.js

@@ -302,6 +302,7 @@ var ChatClient = class {
     this.customerId = null;
     this.authMode = null;
     this.pollingTimers = /* @__PURE__ */ new Map();
+    this.stateListeners = /* @__PURE__ */ new Set();
     this.realtimeManager = null;
     this.presenceManager = null;
     this.realtimeReady = false;
@@ -342,6 +343,7 @@ var ChatClient = class {
     this.teamId = response.data.teamId;
     this.customerId = response.data.customer.id;
     this.authMode = "hmac";
+    this.notifyStateChanged();
     if (this.realtimeEnabled) {
       this.realtimeInitPromise = this.initRealtime(
         response.data.customer.id,
@@ -401,11 +403,35 @@ var ChatClient = class {
       this.teamId = params.teamId;
     }
     this.authMode = "session";
+    this.notifyStateChanged();
     if (this.realtimeEnabled) {
       const customerName = params.customerName ?? "";
       this.realtimeInitPromise = this.initRealtimeFromSession(customerName);
     }
   }
+  /**
+   * Subscribe to client state changes (auth mode flips, identify, disconnect).
+   * Fires after the mutation, so listeners reading `getAuthMode()` /
+   * `getCustomerId()` see the new value.
+   *
+   * Returns an unsubscribe function. Closes F-041 — used by `useChat` (React)
+   * and `ChatState` (Svelte) to re-render when consumers mutate the client
+   * outside of the framework wrappers.
+   */
+  subscribe(listener) {
+    this.stateListeners.add(listener);
+    return () => {
+      this.stateListeners.delete(listener);
+    };
+  }
+  notifyStateChanged() {
+    for (const listener of this.stateListeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
   /**
    * Returns the auth mode the client is currently using, or `null` before
    * any authenticated call has resolved one. Useful for branching UI
@@ -468,6 +494,7 @@ var ChatClient = class {
     this.teamId = null;
     this.customerId = null;
     this.authMode = null;
+    this.notifyStateChanged();
   }
   /**
    * @internal Make an authenticated request to the widget API.
@@ -505,7 +532,9 @@ var ChatClient = class {
     const responseHeaders = response.headers && typeof response.headers.get === "function" ? response.headers : null;
     const headerMode = responseHeaders?.get("X-Cstar-Auth-Mode") ?? null;
     if (headerMode === "hmac" || headerMode === "session") {
+      const previous = this.authMode;
       this.authMode = headerMode;
+      if (previous !== headerMode) this.notifyStateChanged();
     }
     const requestId = responseHeaders?.get("X-Request-Id") ?? null;
     if (!response.ok) {
@@ -687,10 +716,16 @@ var TicketsApi = class {
         cursor: params?.cursor
       }
     });
+    const data = response.data.tickets ?? response.data.conversations ?? [];
+    const cursor = response.data.cursor;
+    const hasMore = response.data.hasMore;
     return {
-      tickets: response.data.tickets ?? response.data.conversations ?? [],
-      cursor: response.data.cursor,
-      hasMore: response.data.hasMore
+      data,
+      pagination: { cursor, hasMore },
+      hasMore,
+      // Deprecated aliases — same references, no extra allocation.
+      tickets: data,
+      cursor
     };
   }
   /** Create a new ticket. */

package/dist/index.cjs

@@ -178,6 +178,18 @@ var CStarFeatureDisabledError = class extends CStarError {
     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,
@@ -220,7 +232,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.13.0";
+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;
@@ -465,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) {
@@ -519,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 ", "") ?? "";
@@ -557,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;
@@ -976,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.
    *

package/dist/index.d.cts

@@ -134,6 +134,13 @@ declare class HttpClient {
     private sleep;
 }
 
+/**
+ * The subset of the global `EventSource` constructor surface that the
+ * realtime client uses. Allows polyfill injection (e.g. the `eventsource`
+ * npm package on Node) without forcing the polyfill to satisfy the full
+ * lib.dom.d.ts shape.
+ */
+type EventSourceConstructor = new (url: string) => EventSource;
 /** Options for configuring the realtime connection. */
 interface RealtimeOptions {
     /** Event types to subscribe to (e.g., ['ticket.*', 'boss.*']). Omit for all. */
@@ -142,6 +149,13 @@ interface RealtimeOptions {
     autoReconnect?: boolean;
     /** Max reconnection attempts before giving up (default: 10). */
     maxRetries?: number;
+    /**
+     * EventSource constructor to use. Defaults to `globalThis.EventSource`
+     * (browsers and Node 22+). Pass an explicit polyfill (e.g. the
+     * `eventsource` npm package) to subscribe from a Node environment that
+     * lacks the global. Closes NEW-v2-02.
+     */
+    eventSource?: EventSourceConstructor;
 }
 /** A parsed realtime event from the SSE stream. */
 interface RealtimeEvent<T = unknown> {
@@ -189,7 +203,15 @@ declare class CStarRealtime {
     private readonly autoReconnect;
     private readonly maxRetries;
     private readonly types;
+    private readonly eventSourceCtor;
     constructor(httpClient: HttpClient, options?: RealtimeOptions);
+    /**
+     * 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.
+     */
+    private resolveEventSource;
     /** Subscribe to a specific event type. Supports wildcards (e.g., 'ticket.*'). Returns an unsubscribe function. */
     on<T = unknown>(eventType: string, handler: EventHandler<T>): () => void;
     /** Subscribe to all events. Returns an unsubscribe function. */
@@ -393,6 +415,12 @@ declare abstract class BaseResource<TEntity, TListParams extends PaginationParam
     update(id: string, params: TUpdateParams, options?: RequestOptions): Promise<TEntity>;
     /** Delete a resource by ID. */
     del(id: string): Promise<DeleteResponse>;
+    /**
+     * Delete a resource by ID. Alias for `del()` — kept because IDE
+     * auto-complete and documentation both surface `delete` first. Closes
+     * NEW-v2-06.
+     */
+    delete(id: string): Promise<DeleteResponse>;
     /**
      * Auto-paginating async iterator that yields every item across all pages.
      *

package/dist/index.d.ts

@@ -134,6 +134,13 @@ declare class HttpClient {
     private sleep;
 }
 
+/**
+ * The subset of the global `EventSource` constructor surface that the
+ * realtime client uses. Allows polyfill injection (e.g. the `eventsource`
+ * npm package on Node) without forcing the polyfill to satisfy the full
+ * lib.dom.d.ts shape.
+ */
+type EventSourceConstructor = new (url: string) => EventSource;
 /** Options for configuring the realtime connection. */
 interface RealtimeOptions {
     /** Event types to subscribe to (e.g., ['ticket.*', 'boss.*']). Omit for all. */
@@ -142,6 +149,13 @@ interface RealtimeOptions {
     autoReconnect?: boolean;
     /** Max reconnection attempts before giving up (default: 10). */
     maxRetries?: number;
+    /**
+     * EventSource constructor to use. Defaults to `globalThis.EventSource`
+     * (browsers and Node 22+). Pass an explicit polyfill (e.g. the
+     * `eventsource` npm package) to subscribe from a Node environment that
+     * lacks the global. Closes NEW-v2-02.
+     */
+    eventSource?: EventSourceConstructor;
 }
 /** A parsed realtime event from the SSE stream. */
 interface RealtimeEvent<T = unknown> {
@@ -189,7 +203,15 @@ declare class CStarRealtime {
     private readonly autoReconnect;
     private readonly maxRetries;
     private readonly types;
+    private readonly eventSourceCtor;
     constructor(httpClient: HttpClient, options?: RealtimeOptions);
+    /**
+     * 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.
+     */
+    private resolveEventSource;
     /** Subscribe to a specific event type. Supports wildcards (e.g., 'ticket.*'). Returns an unsubscribe function. */
     on<T = unknown>(eventType: string, handler: EventHandler<T>): () => void;
     /** Subscribe to all events. Returns an unsubscribe function. */
@@ -393,6 +415,12 @@ declare abstract class BaseResource<TEntity, TListParams extends PaginationParam
     update(id: string, params: TUpdateParams, options?: RequestOptions): Promise<TEntity>;
     /** Delete a resource by ID. */
     del(id: string): Promise<DeleteResponse>;
+    /**
+     * Delete a resource by ID. Alias for `del()` — kept because IDE
+     * auto-complete and documentation both surface `delete` first. Closes
+     * NEW-v2-06.
+     */
+    delete(id: string): Promise<DeleteResponse>;
     /**
      * Auto-paginating async iterator that yields every item across all pages.
      *

package/dist/index.js

@@ -139,6 +139,18 @@ var CStarFeatureDisabledError = class extends CStarError {
     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,
@@ -181,7 +193,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.13.0";
+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;
@@ -426,6 +438,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) {
@@ -480,6 +504,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 ", "") ?? "";
@@ -518,7 +545,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;
@@ -937,6 +969,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.
    *

package/dist/quickhelp/index.cjs

@@ -181,11 +181,15 @@ var TYPE_TO_CLASS = {
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var QuickHelpClient = class {
   constructor(config) {
-    if (!config?.teamId) {
-      throw new Error("QuickHelpClient: teamId is required");
+    this.resolveTeamIdPromise = null;
+    if (!config?.teamId && !config?.teamSlug) {
+      throw new Error(
+        'QuickHelpClient: either `teamId` or `teamSlug` is required. Pass `teamSlug` (e.g. "acme") for the easiest setup.'
+      );
     }
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.teamId = config.teamId;
+    this.teamId = config.teamId ?? null;
+    this.teamSlug = config.teamSlug ?? null;
     this.publishableKey = config.publishableKey ?? null;
     this.mode = this.publishableKey?.startsWith("pk_test_") ? "test" : "live";
     if (this.publishableKey && !/^pk_(test|live)_/.test(this.publishableKey)) {
@@ -197,6 +201,39 @@ var QuickHelpClient = class {
   authHeaders() {
     return this.publishableKey ? { Authorization: `Bearer ${this.publishableKey}` } : {};
   }
+  /**
+   * Resolve `teamSlug` → `teamId` lazily on the first call that needs it.
+   * Cached for the life of the client. NEW-v2-05.
+   */
+  async resolveTeamId() {
+    if (this.teamId) return this.teamId;
+    if (!this.teamSlug) throw new Error("QuickHelpClient: no teamId or teamSlug set");
+    if (this.resolveTeamIdPromise) return this.resolveTeamIdPromise;
+    this.resolveTeamIdPromise = (async () => {
+      const url = `${this.baseUrl}/api/widget/team-by-slug?teamSlug=${encodeURIComponent(this.teamSlug)}`;
+      const res = await globalThis.fetch(url, { method: "GET", headers: this.authHeaders() });
+      if (!res.ok) {
+        throw new Error(
+          `QuickHelpClient: could not resolve teamSlug "${this.teamSlug}" (HTTP ${res.status}).`
+        );
+      }
+      const body = await res.json();
+      const id = body?.data?.teamId;
+      if (!id) {
+        throw new Error(
+          `QuickHelpClient: lookup for teamSlug "${this.teamSlug}" returned no teamId.`
+        );
+      }
+      this.teamId = id;
+      return id;
+    })();
+    try {
+      return await this.resolveTeamIdPromise;
+    } catch (err) {
+      this.resolveTeamIdPromise = null;
+      throw err;
+    }
+  }
   /**
    * Fetch the sanitized public config (title, subtitle, placeholder,
    * theme overrides). Never includes agent id or escalation contact
@@ -205,7 +242,8 @@ var QuickHelpClient = class {
    * Returns `null` if Quick Help is disabled on the team (404).
    */
   async config() {
-    const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(this.teamId)}`;
+    const teamId = await this.resolveTeamId();
+    const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(teamId)}`;
     const res = await globalThis.fetch(url, { method: "GET", headers: this.authHeaders() });
     if (res.status === 404) return null;
     if (!res.ok) {
@@ -222,12 +260,13 @@ var QuickHelpClient = class {
    * property set from the response body.
    */
   async ask(params) {
+    const teamId = await this.resolveTeamId();
     const url = `${this.baseUrl}/api/quickhelp/ask`;
     const res = await globalThis.fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json", ...this.authHeaders() },
       body: JSON.stringify({
-        team_id: this.teamId,
+        team_id: teamId,
         session_id: params.sessionId ?? null,
         question: params.question
       })
@@ -241,7 +280,7 @@ var QuickHelpClient = class {
           message: body?.error?.message ?? "Quick Help is not available on this team. Enable an AI Agent (Settings \u2192 AI Agents) and configure Quick Help (Settings \u2192 Quick Help) before calling .ask().",
           doc_url: "https://cstar.help/developers/api/errors#feature-not-configured",
           feature: "quickHelp",
-          enable_url: `${this.baseUrl}/team/${encodeURIComponent(this.teamId)}/settings?section=quickHelp`
+          enable_url: `${this.baseUrl}/team/${encodeURIComponent(teamId)}/settings?section=quickHelp`
         });
       }
       const message = body?.error?.message ?? `Quick Help ask failed: ${res.status}`;

package/dist/quickhelp/index.d.cts

@@ -1,7 +1,21 @@
-/** Options for the QuickHelpClient. No auth — Quick Help is anonymous by design. */
+/**
+ * Options for the QuickHelpClient. No auth — Quick Help is anonymous by
+ * design.
+ *
+ * NEW-v2-05: pass either `teamId` (UUID, fastest — no roundtrip) or the
+ * easier-to-discover `teamSlug`. The slug is resolved to a UUID on the
+ * first network call and cached for the life of the client. At least one
+ * is required.
+ */
 interface QuickHelpConfig {
-    /** Your team's UUID. Required. */
-    teamId: string;
+    /** Your team's UUID. Either this or `teamSlug` is required. */
+    teamId?: string;
+    /**
+     * Your team's slug (e.g. `acme`). Resolved to `teamId` lazily via the
+     * public `/api/widget/team-by-slug` endpoint on the first call. Cached
+     * thereafter. Either this or `teamId` is required.
+     */
+    teamSlug?: string;
     /**
      * Optional publishable key (`pk_test_*` or `pk_live_*`). Sent as
      * `Authorization: Bearer` so test-mode dev sessions can be scoped
@@ -67,12 +81,20 @@ interface QuickHelpAskResult {
  */
 declare class QuickHelpClient {
     private readonly baseUrl;
-    private readonly teamId;
+    /** Cached resolved teamId. `null` until the first lookup completes. */
+    private teamId;
+    private readonly teamSlug;
+    private resolveTeamIdPromise;
     private readonly publishableKey;
     /** Resolved mode based on the publishable-key prefix. */
     readonly mode: 'live' | 'test';
     constructor(config: QuickHelpConfig);
     private authHeaders;
+    /**
+     * Resolve `teamSlug` → `teamId` lazily on the first call that needs it.
+     * Cached for the life of the client. NEW-v2-05.
+     */
+    private resolveTeamId;
     /**
      * Fetch the sanitized public config (title, subtitle, placeholder,
      * theme overrides). Never includes agent id or escalation contact

package/dist/quickhelp/index.d.ts

@@ -1,7 +1,21 @@
-/** Options for the QuickHelpClient. No auth — Quick Help is anonymous by design. */
+/**
+ * Options for the QuickHelpClient. No auth — Quick Help is anonymous by
+ * design.
+ *
+ * NEW-v2-05: pass either `teamId` (UUID, fastest — no roundtrip) or the
+ * easier-to-discover `teamSlug`. The slug is resolved to a UUID on the
+ * first network call and cached for the life of the client. At least one
+ * is required.
+ */
 interface QuickHelpConfig {
-    /** Your team's UUID. Required. */
-    teamId: string;
+    /** Your team's UUID. Either this or `teamSlug` is required. */
+    teamId?: string;
+    /**
+     * Your team's slug (e.g. `acme`). Resolved to `teamId` lazily via the
+     * public `/api/widget/team-by-slug` endpoint on the first call. Cached
+     * thereafter. Either this or `teamId` is required.
+     */
+    teamSlug?: string;
     /**
      * Optional publishable key (`pk_test_*` or `pk_live_*`). Sent as
      * `Authorization: Bearer` so test-mode dev sessions can be scoped
@@ -67,12 +81,20 @@ interface QuickHelpAskResult {
  */
 declare class QuickHelpClient {
     private readonly baseUrl;
-    private readonly teamId;
+    /** Cached resolved teamId. `null` until the first lookup completes. */
+    private teamId;
+    private readonly teamSlug;
+    private resolveTeamIdPromise;
     private readonly publishableKey;
     /** Resolved mode based on the publishable-key prefix. */
     readonly mode: 'live' | 'test';
     constructor(config: QuickHelpConfig);
     private authHeaders;
+    /**
+     * Resolve `teamSlug` → `teamId` lazily on the first call that needs it.
+     * Cached for the life of the client. NEW-v2-05.
+     */
+    private resolveTeamId;
     /**
      * Fetch the sanitized public config (title, subtitle, placeholder,
      * theme overrides). Never includes agent id or escalation contact

package/dist/quickhelp/index.js

@@ -154,11 +154,15 @@ var TYPE_TO_CLASS = {
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var QuickHelpClient = class {
   constructor(config) {
-    if (!config?.teamId) {
-      throw new Error("QuickHelpClient: teamId is required");
+    this.resolveTeamIdPromise = null;
+    if (!config?.teamId && !config?.teamSlug) {
+      throw new Error(
+        'QuickHelpClient: either `teamId` or `teamSlug` is required. Pass `teamSlug` (e.g. "acme") for the easiest setup.'
+      );
     }
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.teamId = config.teamId;
+    this.teamId = config.teamId ?? null;
+    this.teamSlug = config.teamSlug ?? null;
     this.publishableKey = config.publishableKey ?? null;
     this.mode = this.publishableKey?.startsWith("pk_test_") ? "test" : "live";
     if (this.publishableKey && !/^pk_(test|live)_/.test(this.publishableKey)) {
@@ -170,6 +174,39 @@ var QuickHelpClient = class {
   authHeaders() {
     return this.publishableKey ? { Authorization: `Bearer ${this.publishableKey}` } : {};
   }
+  /**
+   * Resolve `teamSlug` → `teamId` lazily on the first call that needs it.
+   * Cached for the life of the client. NEW-v2-05.
+   */
+  async resolveTeamId() {
+    if (this.teamId) return this.teamId;
+    if (!this.teamSlug) throw new Error("QuickHelpClient: no teamId or teamSlug set");
+    if (this.resolveTeamIdPromise) return this.resolveTeamIdPromise;
+    this.resolveTeamIdPromise = (async () => {
+      const url = `${this.baseUrl}/api/widget/team-by-slug?teamSlug=${encodeURIComponent(this.teamSlug)}`;
+      const res = await globalThis.fetch(url, { method: "GET", headers: this.authHeaders() });
+      if (!res.ok) {
+        throw new Error(
+          `QuickHelpClient: could not resolve teamSlug "${this.teamSlug}" (HTTP ${res.status}).`
+        );
+      }
+      const body = await res.json();
+      const id = body?.data?.teamId;
+      if (!id) {
+        throw new Error(
+          `QuickHelpClient: lookup for teamSlug "${this.teamSlug}" returned no teamId.`
+        );
+      }
+      this.teamId = id;
+      return id;
+    })();
+    try {
+      return await this.resolveTeamIdPromise;
+    } catch (err) {
+      this.resolveTeamIdPromise = null;
+      throw err;
+    }
+  }
   /**
    * Fetch the sanitized public config (title, subtitle, placeholder,
    * theme overrides). Never includes agent id or escalation contact
@@ -178,7 +215,8 @@ var QuickHelpClient = class {
    * Returns `null` if Quick Help is disabled on the team (404).
    */
   async config() {
-    const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(this.teamId)}`;
+    const teamId = await this.resolveTeamId();
+    const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(teamId)}`;
     const res = await globalThis.fetch(url, { method: "GET", headers: this.authHeaders() });
     if (res.status === 404) return null;
     if (!res.ok) {
@@ -195,12 +233,13 @@ var QuickHelpClient = class {
    * property set from the response body.
    */
   async ask(params) {
+    const teamId = await this.resolveTeamId();
     const url = `${this.baseUrl}/api/quickhelp/ask`;
     const res = await globalThis.fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json", ...this.authHeaders() },
       body: JSON.stringify({
-        team_id: this.teamId,
+        team_id: teamId,
         session_id: params.sessionId ?? null,
         question: params.question
       })
@@ -214,7 +253,7 @@ var QuickHelpClient = class {
           message: body?.error?.message ?? "Quick Help is not available on this team. Enable an AI Agent (Settings \u2192 AI Agents) and configure Quick Help (Settings \u2192 Quick Help) before calling .ask().",
           doc_url: "https://cstar.help/developers/api/errors#feature-not-configured",
           feature: "quickHelp",
-          enable_url: `${this.baseUrl}/team/${encodeURIComponent(this.teamId)}/settings?section=quickHelp`
+          enable_url: `${this.baseUrl}/team/${encodeURIComponent(teamId)}/settings?section=quickHelp`
         });
       }
       const message = body?.error?.message ?? `Quick Help ask failed: ${res.status}`;

package/package.json

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