orchestrator-client 5.7.1 → 5.7.3

package/dist/index.d.cts

@@ -511,6 +511,15 @@ interface OrchestratorClientOptions {
     timeoutMs?: number;
     /** Max retry attempts on transient failures (default: 3). */
     maxRetries?: number;
+    /**
+     * Locale tag sent as `X-Locale` on every request (e.g. `"hu-hu"`, `"en-us"`).
+     *
+     * When set the API returns translated content where available.
+     * When not set the API returns its default (English) content.
+     * Per-call locale overrides (on `listTasks`, `getTaskStatus`, etc.)
+     * take precedence over this global setting.
+     */
+    locale?: string;
     /**
      * Custom fetch implementation override.
      *
@@ -538,6 +547,7 @@ declare class OrchestratorAsync {
     protected _getToken: (() => string | Promise<string>) | undefined;
     protected _timeoutMs: number;
     protected _maxRetries: number;
+    protected _locale: string | undefined;
     protected _fetch: typeof globalThis.fetch;
     protected _abortController: AbortController | null;
     constructor(opts?: OrchestratorClientOptions);
@@ -687,7 +697,7 @@ declare class OrchestratorAsync {
         orderDirection?: string;
     }): Promise<ErrorEventListResult>;
     getErrorDetail(errorId: string): Promise<ErrorEventDetail>;
-    getErrorStats(since?: string): Promise<ErrorStatsResult>;
+    getErrorStats(since?: string, topN?: number): Promise<ErrorStatsResult>;
     countErrors(since?: string): Promise<ErrorCountResult>;
     purgeErrors(): Promise<ErrorPurgeResult>;
     health(): Promise<HealthStatus>;
@@ -926,6 +936,19 @@ interface RealtimeClientOptions {
     getToken?: (() => string | Promise<string>) | string;
     /** Whether to auto-connect on construction (default: false). */
     autoConnect?: boolean;
+    /**
+     * Client identifier sent as the `client_id` query parameter at connection
+     * time.  The server uses this for logging/diagnostics.
+     * Defaults to `"orchestrator-client"`.
+     */
+    clientId?: string;
+    /**
+     * Locale tag sent as the `locale` query parameter at connection time
+     * (e.g. `"hu-hu"`, `"en-us"`).  When set the server automatically joins
+     * the client into the matching `locale:<tag>` room so translation-ready
+     * events are delivered without a separate `subscribeLocale()` call.
+     */
+    locale?: string;
 }
 /**
  * Socket.IO-based realtime client for receiving orchestrator events.
@@ -933,20 +956,40 @@ interface RealtimeClientOptions {
  * The server wraps all domain events in a `message` Socket.IO event with an
  * inner `event_type` field. This client unwraps the envelope and dispatches
  * to registered handlers by event_type.
+ *
+ * ## Two subscription APIs — choose one or mix them:
+ *
+ * ### 1. Event-type handlers via `on(event, handler)`
+ * Registers a callback for a specific event type string (e.g.
+ * `"task_status_changed"`). You still need to join the relevant rooms
+ * manually via `subscribeTask()`, `subscribeEvents()`, etc.
+ *
+ * ### 2. Room-scoped subscribers via `subscribe(handler, rooms)`
+ * Mirrors the WebSocketProvider pattern used in the webui. Each call
+ * returns an opaque subscription id. Calling `unsubscribe(id)` removes it.
+ * Room membership is kept in sync automatically: the client joins the union
+ * of all subscribers' rooms and leaves rooms that are no longer needed.
+ * The handler receives the unwrapped event dict for every event from those
+ * rooms, regardless of type.
  */
 declare class RealtimeClient {
     private _baseUrl;
     private _socketOptions;
     private _getToken?;
+    private _clientId;
+    private _locale?;
     private _socket;
     private _handlers;
     private _connected;
+    private _subscriptions;
+    private _currentRooms;
+    private _subIdCounter;
     constructor(baseUrl: string, opts: RealtimeClientOptions);
     get connected(): boolean;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     /**
-     * Dispatch a message envelope to registered handlers.
+     * Dispatch a message envelope to registered handlers and subscribers.
      * The server sends: socket.emit("message", {type: "message", event: {..., event_type: "...", ...}})
      */
     private _dispatch;
@@ -989,6 +1032,41 @@ declare class RealtimeClient {
      * Leave arbitrary rooms by name.
      */
     leaveRooms(rooms: string[]): void;
+    /**
+     * Register a subscriber that receives all events from the given rooms.
+     *
+     * Room membership is managed automatically: the client joins the union
+     * of all active subscribers' rooms and leaves rooms that are no longer
+     * needed when the last subscriber referencing them is removed.
+     *
+     * The `handler` receives the unwrapped event dict (same object that
+     * `on()` handlers receive).
+     *
+     * Returns an opaque subscription id that must be passed to
+     * `unsubscribe()` to remove the subscription.
+     *
+     * Example — mirror the webui's per-component subscription pattern:
+     *
+     *   const id = rt.subscribe((event) => {
+     *     if (event.event_type === "task_status_changed") { ... }
+     *   }, [`task:${taskId}`]);
+     *
+     *   // later, on cleanup:
+     *   rt.unsubscribe(id);
+     */
+    subscribe(handler: EventHandler, rooms: string[]): string;
+    /**
+     * Remove a subscription registered via `subscribe()`.
+     *
+     * Rooms that are no longer referenced by any remaining subscriber are
+     * left automatically.
+     */
+    unsubscribe(id: string): void;
+    /**
+     * Diff the union of all subscribers' rooms against the currently joined
+     * rooms and emit `join`/`leave` for the delta.  No-ops when not connected.
+     */
+    private _syncRooms;
     /**
      * Send a ping to the server.
      */

package/dist/index.d.ts

@@ -511,6 +511,15 @@ interface OrchestratorClientOptions {
     timeoutMs?: number;
     /** Max retry attempts on transient failures (default: 3). */
     maxRetries?: number;
+    /**
+     * Locale tag sent as `X-Locale` on every request (e.g. `"hu-hu"`, `"en-us"`).
+     *
+     * When set the API returns translated content where available.
+     * When not set the API returns its default (English) content.
+     * Per-call locale overrides (on `listTasks`, `getTaskStatus`, etc.)
+     * take precedence over this global setting.
+     */
+    locale?: string;
     /**
      * Custom fetch implementation override.
      *
@@ -538,6 +547,7 @@ declare class OrchestratorAsync {
     protected _getToken: (() => string | Promise<string>) | undefined;
     protected _timeoutMs: number;
     protected _maxRetries: number;
+    protected _locale: string | undefined;
     protected _fetch: typeof globalThis.fetch;
     protected _abortController: AbortController | null;
     constructor(opts?: OrchestratorClientOptions);
@@ -687,7 +697,7 @@ declare class OrchestratorAsync {
         orderDirection?: string;
     }): Promise<ErrorEventListResult>;
     getErrorDetail(errorId: string): Promise<ErrorEventDetail>;
-    getErrorStats(since?: string): Promise<ErrorStatsResult>;
+    getErrorStats(since?: string, topN?: number): Promise<ErrorStatsResult>;
     countErrors(since?: string): Promise<ErrorCountResult>;
     purgeErrors(): Promise<ErrorPurgeResult>;
     health(): Promise<HealthStatus>;
@@ -926,6 +936,19 @@ interface RealtimeClientOptions {
     getToken?: (() => string | Promise<string>) | string;
     /** Whether to auto-connect on construction (default: false). */
     autoConnect?: boolean;
+    /**
+     * Client identifier sent as the `client_id` query parameter at connection
+     * time.  The server uses this for logging/diagnostics.
+     * Defaults to `"orchestrator-client"`.
+     */
+    clientId?: string;
+    /**
+     * Locale tag sent as the `locale` query parameter at connection time
+     * (e.g. `"hu-hu"`, `"en-us"`).  When set the server automatically joins
+     * the client into the matching `locale:<tag>` room so translation-ready
+     * events are delivered without a separate `subscribeLocale()` call.
+     */
+    locale?: string;
 }
 /**
  * Socket.IO-based realtime client for receiving orchestrator events.
@@ -933,20 +956,40 @@ interface RealtimeClientOptions {
  * The server wraps all domain events in a `message` Socket.IO event with an
  * inner `event_type` field. This client unwraps the envelope and dispatches
  * to registered handlers by event_type.
+ *
+ * ## Two subscription APIs — choose one or mix them:
+ *
+ * ### 1. Event-type handlers via `on(event, handler)`
+ * Registers a callback for a specific event type string (e.g.
+ * `"task_status_changed"`). You still need to join the relevant rooms
+ * manually via `subscribeTask()`, `subscribeEvents()`, etc.
+ *
+ * ### 2. Room-scoped subscribers via `subscribe(handler, rooms)`
+ * Mirrors the WebSocketProvider pattern used in the webui. Each call
+ * returns an opaque subscription id. Calling `unsubscribe(id)` removes it.
+ * Room membership is kept in sync automatically: the client joins the union
+ * of all subscribers' rooms and leaves rooms that are no longer needed.
+ * The handler receives the unwrapped event dict for every event from those
+ * rooms, regardless of type.
  */
 declare class RealtimeClient {
     private _baseUrl;
     private _socketOptions;
     private _getToken?;
+    private _clientId;
+    private _locale?;
     private _socket;
     private _handlers;
     private _connected;
+    private _subscriptions;
+    private _currentRooms;
+    private _subIdCounter;
     constructor(baseUrl: string, opts: RealtimeClientOptions);
     get connected(): boolean;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     /**
-     * Dispatch a message envelope to registered handlers.
+     * Dispatch a message envelope to registered handlers and subscribers.
      * The server sends: socket.emit("message", {type: "message", event: {..., event_type: "...", ...}})
      */
     private _dispatch;
@@ -989,6 +1032,41 @@ declare class RealtimeClient {
      * Leave arbitrary rooms by name.
      */
     leaveRooms(rooms: string[]): void;
+    /**
+     * Register a subscriber that receives all events from the given rooms.
+     *
+     * Room membership is managed automatically: the client joins the union
+     * of all active subscribers' rooms and leaves rooms that are no longer
+     * needed when the last subscriber referencing them is removed.
+     *
+     * The `handler` receives the unwrapped event dict (same object that
+     * `on()` handlers receive).
+     *
+     * Returns an opaque subscription id that must be passed to
+     * `unsubscribe()` to remove the subscription.
+     *
+     * Example — mirror the webui's per-component subscription pattern:
+     *
+     *   const id = rt.subscribe((event) => {
+     *     if (event.event_type === "task_status_changed") { ... }
+     *   }, [`task:${taskId}`]);
+     *
+     *   // later, on cleanup:
+     *   rt.unsubscribe(id);
+     */
+    subscribe(handler: EventHandler, rooms: string[]): string;
+    /**
+     * Remove a subscription registered via `subscribe()`.
+     *
+     * Rooms that are no longer referenced by any remaining subscriber are
+     * left automatically.
+     */
+    unsubscribe(id: string): void;
+    /**
+     * Diff the union of all subscribers' rooms against the currently joined
+     * rooms and emit `join`/`leave` for the delta.  No-ops when not connected.
+     */
+    private _syncRooms;
     /**
      * Send a ping to the server.
      */

package/dist/index.js

@@ -90,6 +90,7 @@ var OrchestratorAsync = class {
     this._getToken = opts.getToken;
     this._timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this._maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this._locale = opts.locale;
     this._fetch = opts.fetch ?? globalThis.fetch;
     if (opts.insecure && !opts.fetch && typeof process !== "undefined" && process.versions?.node) {
       this._insecure = true;
@@ -114,6 +115,9 @@ var OrchestratorAsync = class {
         headers.Authorization = `Bearer ${token}`;
       }
     }
+    if (this._locale) {
+      headers["X-Locale"] = this._locale;
+    }
     return headers;
   }
   async _request(method, path, opts) {
@@ -344,10 +348,9 @@ var OrchestratorAsync = class {
     );
   }
   async getTaskCompactions(taskId) {
-    const data = await this._get("/task/compactions", {
+    return this._get("/task/compactions", {
       task_id: taskId
     });
-    return data.compactions ?? [];
   }
   async getTaskJournal(taskId) {
     const data = await this._get("/task/journal", {
@@ -924,8 +927,10 @@ var OrchestratorAsync = class {
   async getErrorDetail(errorId) {
     return this._get(`/errors/${errorId}`);
   }
-  async getErrorStats(since) {
-    const params = {};
+  async getErrorStats(since, topN = 10) {
+    const params = {
+      top_n: topN
+    };
     if (since) params.since = since;
     return this._get("/errors/stats", params);
   }
@@ -1635,9 +1640,15 @@ var RealtimeClient = class {
     this._socket = null;
     this._handlers = /* @__PURE__ */ new Map();
     this._connected = false;
+    // Multi-subscriber room-diffing state (mirrors WebSocketProvider)
+    this._subscriptions = /* @__PURE__ */ new Map();
+    this._currentRooms = /* @__PURE__ */ new Set();
+    this._subIdCounter = 0;
     this._baseUrl = baseUrl.replace(/\/+$/, "");
     this._socketOptions = opts.socketOptions ?? {};
     this._getToken = opts.getToken;
+    this._clientId = opts.clientId ?? "orchestrator-client";
+    this._locale = opts.locale;
     if (opts.autoConnect) {
       this.connect();
     }
@@ -1650,18 +1661,26 @@ var RealtimeClient = class {
     if (this._getToken) {
       auth.token = typeof this._getToken === "function" ? await this._getToken() : this._getToken;
     }
+    const query = { client_id: this._clientId };
+    if (this._locale) {
+      query.locale = this._locale;
+    }
     const { io } = await import("socket.io-client");
     this._socket = io(this._baseUrl, {
       path: "/socket.io",
       auth,
+      query,
       transports: ["websocket", "polling"],
       ...this._socketOptions
     });
     this._socket.on("connect", () => {
       this._connected = true;
+      this._currentRooms = /* @__PURE__ */ new Set();
+      this._syncRooms();
     });
     this._socket.on("disconnect", () => {
       this._connected = false;
+      this._currentRooms = /* @__PURE__ */ new Set();
     });
     this._socket.on("message", (payload) => this._dispatch(payload));
     return new Promise((resolve, reject) => {
@@ -1684,7 +1703,7 @@ var RealtimeClient = class {
     this._connected = false;
   }
   /**
-   * Dispatch a message envelope to registered handlers.
+   * Dispatch a message envelope to registered handlers and subscribers.
    * The server sends: socket.emit("message", {type: "message", event: {..., event_type: "...", ...}})
    */
   _dispatch(payload) {
@@ -1698,6 +1717,9 @@ var RealtimeClient = class {
         h(event);
       }
     }
+    for (const sub of this._subscriptions.values()) {
+      sub.handler(event);
+    }
   }
   /**
    * Subscribe to realtime events for a specific task.
@@ -1767,6 +1789,64 @@ var RealtimeClient = class {
     if (!this._socket) throw new Error("RealtimeClient not connected");
     this._socket.emit("leave", { rooms });
   }
+  // ------------------------------------------------------------------
+  // Multi-subscriber API (mirrors WebSocketProvider room-diffing)
+  // ------------------------------------------------------------------
+  /**
+   * Register a subscriber that receives all events from the given rooms.
+   *
+   * Room membership is managed automatically: the client joins the union
+   * of all active subscribers' rooms and leaves rooms that are no longer
+   * needed when the last subscriber referencing them is removed.
+   *
+   * The `handler` receives the unwrapped event dict (same object that
+   * `on()` handlers receive).
+   *
+   * Returns an opaque subscription id that must be passed to
+   * `unsubscribe()` to remove the subscription.
+   *
+   * Example — mirror the webui's per-component subscription pattern:
+   *
+   *   const id = rt.subscribe((event) => {
+   *     if (event.event_type === "task_status_changed") { ... }
+   *   }, [`task:${taskId}`]);
+   *
+   *   // later, on cleanup:
+   *   rt.unsubscribe(id);
+   */
+  subscribe(handler, rooms) {
+    const id = `sub_${++this._subIdCounter}`;
+    this._subscriptions.set(id, { handler, rooms });
+    this._syncRooms();
+    return id;
+  }
+  /**
+   * Remove a subscription registered via `subscribe()`.
+   *
+   * Rooms that are no longer referenced by any remaining subscriber are
+   * left automatically.
+   */
+  unsubscribe(id) {
+    this._subscriptions.delete(id);
+    this._syncRooms();
+  }
+  /**
+   * Diff the union of all subscribers' rooms against the currently joined
+   * rooms and emit `join`/`leave` for the delta.  No-ops when not connected.
+   */
+  _syncRooms() {
+    const socket = this._socket;
+    if (!socket?.connected) return;
+    const needed = /* @__PURE__ */ new Set();
+    for (const sub of this._subscriptions.values()) {
+      for (const r of sub.rooms) needed.add(r);
+    }
+    const toJoin = [...needed].filter((r) => !this._currentRooms.has(r));
+    const toLeave = [...this._currentRooms].filter((r) => !needed.has(r));
+    if (toJoin.length) socket.emit("join", { rooms: toJoin });
+    if (toLeave.length) socket.emit("leave", { rooms: toLeave });
+    this._currentRooms = needed;
+  }
   /**
    * Send a ping to the server.
    */