connectbase-client 3.6.0 → 3.7.0

package/dist/index.d.mts

@@ -7010,6 +7010,36 @@ declare class EndpointAPI {
      * )
      * ```
      */
+    /**
+     * Open a native browser `WebSocket` to a user model server (e.g. ComfyUI's
+     * `/ws` event channel) through the ConnectBase proxy.
+     *
+     * Background: native browser `WebSocket` cannot send custom headers, so
+     * `X-Public-Key` cannot be supplied on the Upgrade request. This helper
+     * solves that by:
+     *   1. POSTing to `/v1/proxy/<label>/ws-ticket` (with `X-Public-Key`)
+     *      to obtain a single-use 30s token,
+     *   2. Opening `wss://<base>/v1/proxy/<label><path>?ticket=<token>&...`,
+     *   3. Returning the established `WebSocket` to the caller.
+     *
+     * Both the client→upstream and upstream→client byte streams flow
+     * transparently — the proxy server adds no framing of its own.
+     *
+     * @example ComfyUI native event channel
+     * ```ts
+     * const ws = await cb.endpoint.connectWebSocket("comfyui-main", {
+     *     path: "/ws",
+     *     query: { clientId: crypto.randomUUID() },
+     * })
+     * ws.onmessage = (e) => {
+     *     const msg = JSON.parse(typeof e.data === "string" ? e.data : "")
+     *     if (msg.type === "progress") {
+     *         // progress.value / progress.max — exact node-level progress
+     *     }
+     * }
+     * ```
+     */
+    connectWebSocket(label: string, opts?: ConnectWebSocketOptions): Promise<WebSocket>;
     pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: any, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
 }
 /**
@@ -7032,6 +7062,22 @@ interface EndpointCallInit {
     /** 취소 신호. */
     signal?: AbortSignal;
 }
+/**
+ * EndpointAPI.connectWebSocket 옵션.
+ */
+interface ConnectWebSocketOptions {
+    /**
+     * 사용자 모델 서버의 WebSocket 엔드포인트 경로. `/` 로 시작 (기본 `/`).
+     * 예: `/ws`, `/socket`.
+     */
+    path?: string;
+    /** 추가 query 파라미터 (ticket 은 자동 주입). */
+    query?: Record<string, string>;
+    /** WebSocket subprotocols (Sec-WebSocket-Protocol 헤더). */
+    protocols?: string | string[];
+    /** Abort 시 ws.close(1000) 호출. */
+    signal?: AbortSignal;
+}
 /**
  * EndpointAPI.pollUntil 옵션.
  */

package/dist/index.d.ts

@@ -7010,6 +7010,36 @@ declare class EndpointAPI {
      * )
      * ```
      */
+    /**
+     * Open a native browser `WebSocket` to a user model server (e.g. ComfyUI's
+     * `/ws` event channel) through the ConnectBase proxy.
+     *
+     * Background: native browser `WebSocket` cannot send custom headers, so
+     * `X-Public-Key` cannot be supplied on the Upgrade request. This helper
+     * solves that by:
+     *   1. POSTing to `/v1/proxy/<label>/ws-ticket` (with `X-Public-Key`)
+     *      to obtain a single-use 30s token,
+     *   2. Opening `wss://<base>/v1/proxy/<label><path>?ticket=<token>&...`,
+     *   3. Returning the established `WebSocket` to the caller.
+     *
+     * Both the client→upstream and upstream→client byte streams flow
+     * transparently — the proxy server adds no framing of its own.
+     *
+     * @example ComfyUI native event channel
+     * ```ts
+     * const ws = await cb.endpoint.connectWebSocket("comfyui-main", {
+     *     path: "/ws",
+     *     query: { clientId: crypto.randomUUID() },
+     * })
+     * ws.onmessage = (e) => {
+     *     const msg = JSON.parse(typeof e.data === "string" ? e.data : "")
+     *     if (msg.type === "progress") {
+     *         // progress.value / progress.max — exact node-level progress
+     *     }
+     * }
+     * ```
+     */
+    connectWebSocket(label: string, opts?: ConnectWebSocketOptions): Promise<WebSocket>;
     pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: any, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
 }
 /**
@@ -7032,6 +7062,22 @@ interface EndpointCallInit {
     /** 취소 신호. */
     signal?: AbortSignal;
 }
+/**
+ * EndpointAPI.connectWebSocket 옵션.
+ */
+interface ConnectWebSocketOptions {
+    /**
+     * 사용자 모델 서버의 WebSocket 엔드포인트 경로. `/` 로 시작 (기본 `/`).
+     * 예: `/ws`, `/socket`.
+     */
+    path?: string;
+    /** 추가 query 파라미터 (ticket 은 자동 주입). */
+    query?: Record<string, string>;
+    /** WebSocket subprotocols (Sec-WebSocket-Protocol 헤더). */
+    protocols?: string | string[];
+    /** Abort 시 ws.close(1000) 호출. */
+    signal?: AbortSignal;
+}
 /**
  * EndpointAPI.pollUntil 옵션.
  */

package/dist/index.js

@@ -7849,6 +7849,91 @@ var EndpointAPI = class {
    * )
    * ```
    */
+  /**
+   * Open a native browser `WebSocket` to a user model server (e.g. ComfyUI's
+   * `/ws` event channel) through the ConnectBase proxy.
+   *
+   * Background: native browser `WebSocket` cannot send custom headers, so
+   * `X-Public-Key` cannot be supplied on the Upgrade request. This helper
+   * solves that by:
+   *   1. POSTing to `/v1/proxy/<label>/ws-ticket` (with `X-Public-Key`)
+   *      to obtain a single-use 30s token,
+   *   2. Opening `wss://<base>/v1/proxy/<label><path>?ticket=<token>&...`,
+   *   3. Returning the established `WebSocket` to the caller.
+   *
+   * Both the client→upstream and upstream→client byte streams flow
+   * transparently — the proxy server adds no framing of its own.
+   *
+   * @example ComfyUI native event channel
+   * ```ts
+   * const ws = await cb.endpoint.connectWebSocket("comfyui-main", {
+   *     path: "/ws",
+   *     query: { clientId: crypto.randomUUID() },
+   * })
+   * ws.onmessage = (e) => {
+   *     const msg = JSON.parse(typeof e.data === "string" ? e.data : "")
+   *     if (msg.type === "progress") {
+   *         // progress.value / progress.max — exact node-level progress
+   *     }
+   * }
+   * ```
+   */
+  async connectWebSocket(label, opts = {}) {
+    if (!label) {
+      throw new Error("EndpointAPI.connectWebSocket: label required");
+    }
+    const path = opts.path ?? "/";
+    if (!path.startsWith("/")) {
+      throw new Error(
+        `EndpointAPI.connectWebSocket: path must start with '/', got ${JSON.stringify(path)}`
+      );
+    }
+    const baseUrl = this.http.getBaseUrl().replace(/\/+$/, "");
+    const ticketUrl = `${baseUrl}/v1/proxy/${encodeURIComponent(label)}/ws-ticket`;
+    const ticketHeaders = new Headers();
+    const pk = this.http.getPublicKey();
+    if (!pk) {
+      throw new Error(
+        "EndpointAPI.connectWebSocket: publicKey not configured. Pass `publicKey` to ConnectBase constructor."
+      );
+    }
+    ticketHeaders.set("X-Public-Key", pk);
+    const ticketRes = await fetch(ticketUrl, {
+      method: "POST",
+      headers: ticketHeaders,
+      signal: opts.signal
+    });
+    if (!ticketRes.ok) {
+      const text = await ticketRes.text().catch(() => "");
+      throw new Error(
+        `EndpointAPI.connectWebSocket: ticket issuance failed (${ticketRes.status}) ${text.slice(0, 200)}`
+      );
+    }
+    const { ticket } = await ticketRes.json();
+    if (!ticket) {
+      throw new Error("EndpointAPI.connectWebSocket: server returned empty ticket");
+    }
+    const wsUrl = new URL(`${baseUrl}/v1/proxy/${encodeURIComponent(label)}${path}`);
+    wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        wsUrl.searchParams.set(k, v);
+      }
+    }
+    wsUrl.searchParams.set("ticket", ticket);
+    const ws = opts.protocols ? new WebSocket(wsUrl.toString(), opts.protocols) : new WebSocket(wsUrl.toString());
+    if (opts.signal) {
+      const onAbort = () => {
+        try {
+          ws.close(1e3, "client aborted");
+        } catch {
+        }
+      };
+      if (opts.signal.aborted) onAbort();
+      else opts.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    return ws;
+  }
   async pollUntil(label, init, predicate, opts = {}) {
     const intervalMs = opts.intervalMs ?? 1500;
     const timeoutMs = opts.timeoutMs ?? 5 * 6e4;

package/dist/index.mjs

@@ -7808,6 +7808,91 @@ var EndpointAPI = class {
    * )
    * ```
    */
+  /**
+   * Open a native browser `WebSocket` to a user model server (e.g. ComfyUI's
+   * `/ws` event channel) through the ConnectBase proxy.
+   *
+   * Background: native browser `WebSocket` cannot send custom headers, so
+   * `X-Public-Key` cannot be supplied on the Upgrade request. This helper
+   * solves that by:
+   *   1. POSTing to `/v1/proxy/<label>/ws-ticket` (with `X-Public-Key`)
+   *      to obtain a single-use 30s token,
+   *   2. Opening `wss://<base>/v1/proxy/<label><path>?ticket=<token>&...`,
+   *   3. Returning the established `WebSocket` to the caller.
+   *
+   * Both the client→upstream and upstream→client byte streams flow
+   * transparently — the proxy server adds no framing of its own.
+   *
+   * @example ComfyUI native event channel
+   * ```ts
+   * const ws = await cb.endpoint.connectWebSocket("comfyui-main", {
+   *     path: "/ws",
+   *     query: { clientId: crypto.randomUUID() },
+   * })
+   * ws.onmessage = (e) => {
+   *     const msg = JSON.parse(typeof e.data === "string" ? e.data : "")
+   *     if (msg.type === "progress") {
+   *         // progress.value / progress.max — exact node-level progress
+   *     }
+   * }
+   * ```
+   */
+  async connectWebSocket(label, opts = {}) {
+    if (!label) {
+      throw new Error("EndpointAPI.connectWebSocket: label required");
+    }
+    const path = opts.path ?? "/";
+    if (!path.startsWith("/")) {
+      throw new Error(
+        `EndpointAPI.connectWebSocket: path must start with '/', got ${JSON.stringify(path)}`
+      );
+    }
+    const baseUrl = this.http.getBaseUrl().replace(/\/+$/, "");
+    const ticketUrl = `${baseUrl}/v1/proxy/${encodeURIComponent(label)}/ws-ticket`;
+    const ticketHeaders = new Headers();
+    const pk = this.http.getPublicKey();
+    if (!pk) {
+      throw new Error(
+        "EndpointAPI.connectWebSocket: publicKey not configured. Pass `publicKey` to ConnectBase constructor."
+      );
+    }
+    ticketHeaders.set("X-Public-Key", pk);
+    const ticketRes = await fetch(ticketUrl, {
+      method: "POST",
+      headers: ticketHeaders,
+      signal: opts.signal
+    });
+    if (!ticketRes.ok) {
+      const text = await ticketRes.text().catch(() => "");
+      throw new Error(
+        `EndpointAPI.connectWebSocket: ticket issuance failed (${ticketRes.status}) ${text.slice(0, 200)}`
+      );
+    }
+    const { ticket } = await ticketRes.json();
+    if (!ticket) {
+      throw new Error("EndpointAPI.connectWebSocket: server returned empty ticket");
+    }
+    const wsUrl = new URL(`${baseUrl}/v1/proxy/${encodeURIComponent(label)}${path}`);
+    wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        wsUrl.searchParams.set(k, v);
+      }
+    }
+    wsUrl.searchParams.set("ticket", ticket);
+    const ws = opts.protocols ? new WebSocket(wsUrl.toString(), opts.protocols) : new WebSocket(wsUrl.toString());
+    if (opts.signal) {
+      const onAbort = () => {
+        try {
+          ws.close(1e3, "client aborted");
+        } catch {
+        }
+      };
+      if (opts.signal.aborted) onAbort();
+      else opts.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    return ws;
+  }
   async pollUntil(label, init, predicate, opts = {}) {
     const intervalMs = opts.intervalMs ?? 1500;
     const timeoutMs = opts.timeoutMs ?? 5 * 6e4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",