connectbase-client 3.2.0 → 3.2.1

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.2.1] - 2026-04-29
+
+### Fixed — Docs
+
+`cb.endpoint.url(label, path)` 의 README/JSDoc 예제와 CHANGELOG `[3.2.0]` 설명을
+ConnectBase 프록시 인증 모델에 맞춰 정정. 코드 동작 변화 없음 (JSDoc / README /
+CHANGELOG 만 수정).
+
+- 3.2.0 의 `<img src={cb.endpoint.url(...)}>` / `new WebSocket(cb.endpoint.url(...))`
+  예제는 실제로는 401 — `/v1/proxy/:label/*` 가 `X-Public-Key` 헤더를 강제하고
+  쿼리 파라미터 폴백이 없어, 커스텀 헤더를 못 보내는 브라우저 네이티브 API
+  (`<img>`, native `WebSocket`, `<script src>`, `EventSource`) 는 인증 자체가
+  불가능. 잘못된 시연 코드를 제거.
+- 정정된 사용 사례:
+  - **이미지 렌더링**: `cb.endpoint.call(...)` 로 받아
+    `URL.createObjectURL(await res.blob())` 패턴 사용. 영구 URL 이 필요하면
+    `cb.storage.uploadByPath` 로 업로드.
+  - **URL 전달**: Service Worker / 백엔드 워커 / 커스텀 fetch wrapper 처럼 호출자가
+    `X-Public-Key` 헤더를 직접 부착할 수 있는 환경.
+  - **로깅·디버깅**: 라벨 → 최종 URL 매핑 확인.
+- `EndpointAPI` 클래스 / `cb.endpoint.{call,url,pollUntil}` 동작은 3.2.0 과 동일.
+
 ## [3.2.0] - 2026-04-29
 
 ### Added — Endpoint API 헬퍼 (`pollUntil` / `url`)
@@ -16,10 +38,13 @@ ComfyUI × 웹스토리지 같은 e2e 통합 패턴 (작업 제출 → 폴링
   "작업 제출 → 폴링" 패턴 전용. `predicate` 가 값을 반환할 때까지 반복 호출,
   HTTP 5xx/네트워크 오류는 재시도, 4xx 는 즉시 reject, `AbortSignal`/`timeoutMs`
   지원. `parse: "json" | "text" | "none"` 으로 본문 파싱 방식 선택.
-- **`cb.endpoint.url(label, path)`** — 라벨 + path 의 최종 호출 URL 을 조립해서
-  반환. WebSocket / `<img src>` / `new Image()` 같이 SDK 의 `call()` 이 아닌
-  직접 호출이 필요할 때. `X-Public-Key` 는 자동 주입되지 않으므로 모델 서버가
-  자체 토큰으로 인증을 별도 처리해야 함 (ConnectBase 는 dumb pipe).
+- **`cb.endpoint.url(label, path)`** — 라벨 + path 의 최종 호출 URL
+  (`${baseUrl}/v1/proxy/${label}${path}`) 만 조립해서 반환. URL 을 Service
+  Worker / 백엔드 워커로 넘기거나 로깅·디버깅 용도. ⚠️ `<img src>` / 네이티브
+  `WebSocket` / `<script src>` / `EventSource` 처럼 커스텀 헤더를 못 보내는
+  브라우저 API 에 직접 넘기면 401 — ConnectBase 프록시는 항상 `X-Public-Key`
+  헤더를 요구하고 쿼리 파라미터 폴백이 없음. 그 경우엔 `call()` 로 받아
+  `URL.createObjectURL(await res.blob())` 패턴 사용.
 - 신규 export: `PollUntilOptions` 타입.
 
 ### Docs

package/README.md

@@ -929,23 +929,41 @@ const filename = await cb.endpoint.pollUntil<string>(
 
 #### `cb.endpoint.url(label, path): string`
 
-Returns the assembled call URL (`${baseUrl}/v1/proxy/${label}${path}`) for cases
-where the SDK's `call()` doesn't fit — `<img src>`, `new Image()`, native
-`WebSocket`, etc.
+Returns the assembled call URL (`${baseUrl}/v1/proxy/${label}${path}`) for
+URL-passing scenarios where you control the request and can attach the
+`X-Public-Key` header yourself.
 
-⚠️ Direct calls do **not** get automatic `X-Public-Key` injection. If your model
-server requires authentication, your model server must validate a token of its
-own (ConnectBase is a dumb pipe, not an auth gate).
+⚠️ **Browser-native APIs that cannot set custom headers will fail with `401`.**
+ConnectBase's proxy requires `X-Public-Key` on every call (header-only — no
+`?api_key=` fallback), so `<img src>`, `new Image()`, native `WebSocket`,
+`<script src>`, EventSource, etc. **cannot authenticate** through this URL.
+Use `cb.endpoint.call()` instead for those cases:
 
 ```typescript
-// Render a ComfyUI output image directly into <img>
-img.src =
-  cb.endpoint.url('comfyui-main', `/view?filename=${encodeURIComponent(name)}`)
+// ✅ Render an image: download via call(), then convert to a blob URL
+const res = await cb.endpoint.call('comfyui-main', {
+  path: `/view?filename=${encodeURIComponent(name)}`,
+})
+img.src = URL.createObjectURL(await res.blob())
+// ...later: URL.revokeObjectURL(img.src)
 ```
 
+For permanent images (works across CDN, survives tunnel restarts), upload the
+blob to `cb.storage` and use `saved.url` — see
+[`examples/ai-image-generator/`](https://github.com/connectbase-world/connectbase/tree/release/examples/ai-image-generator).
+
+When `cb.endpoint.url()` IS the right tool:
+
+- Logging / debugging the resolved tunnel URL
+- Passing the URL to a backend service or worker that will make the call with proper headers
+- Building a `RequestInfo` for a custom `fetch()` wrapper (you control headers)
+
 ```typescript
-// Native WebSocket to a tunneled service
-const ws = new WebSocket(cb.endpoint.url('my-ws-server', '/socket'))
+console.log(cb.endpoint.url('comfyui-main', '/prompt'))
+// → https://api.connectbase.world/v1/proxy/comfyui-main/prompt
+
+// Hand the URL to a Service Worker that injects X-Public-Key
+sw.postMessage({ url: cb.endpoint.url('comfyui-main', '/prompt'), key: PK })
 ```
 
 ### Push Notifications

package/dist/index.d.mts

@@ -6772,18 +6772,30 @@ declare class EndpointAPI {
      */
     call(label: string, init: EndpointCallInit): Promise<Response>;
     /**
-     * 라벨 + path 의 최종 호출 URL 을 조립해서 반환. fetch / WebSocket / new Image()
-     * 같이 SDK 의 `call()` 이 아닌 직접 호출이 필요할 때 사용.
+     * 라벨 + path 의 최종 호출 URL `${baseUrl}/v1/proxy/${label}${path}` 을 조립해서
+     * 반환. URL 을 다른 시스템 (Service Worker, 백엔드 워커, 로깅) 에 넘기거나
+     * 디버깅 용도일 때 사용.
      *
-     * 주의: WebSocket 같이 `X-Public-Key` 헤더를 못 보내는 경로면, 모델 서버가
-     * 자체 토큰으로 별도 인증을 해야 합니다 (ConnectBase 는 인증 게이트가 아닌
-     * dumb pipe 라 path 만으로 인증하지 않음).
+     * ⚠️ **`<img src>` / 네이티브 `WebSocket` / `<script src>` / `EventSource` 처럼
+     * 커스텀 헤더를 못 보내는 브라우저 API 에 직접 넘기면 401 입니다.** ConnectBase
+     * 프록시는 모든 요청에 `X-Public-Key` 헤더를 요구하고, 쿼리 파라미터 폴백은
+     * 제공하지 않습니다. 그런 경우엔 `call()` 로 받아서 Blob URL 로 변환하세요.
      *
-     * @example
+     * @example URL 을 워커로 넘겨 호출 (✅)
+     * ```typescript
+     * sw.postMessage({
+     *     url: cb.endpoint.url("comfyui-main", "/prompt"),
+     *     key: publicKey, // 워커가 X-Public-Key 헤더로 부착
+     * })
+     * ```
+     *
+     * @example 이미지 렌더링은 call() + Blob URL 패턴으로 (✅)
      * ```typescript
-     * // 결과 이미지를 <img> 로 바로 그리기
-     * img.src = `${cb.endpoint.url("comfyui-main", `/view?filename=${name}`)}` +
-     *           `&__pk=${publicKey}` // 모델 서버가 직접 검증하는 토큰
+     * const res = await cb.endpoint.call("comfyui-main", {
+     *     path: `/view?filename=${encodeURIComponent(name)}`,
+     * })
+     * img.src = URL.createObjectURL(await res.blob())
+     * // 나중에 URL.revokeObjectURL(img.src)
      * ```
      */
     url(label: string, path: string): string;

package/dist/index.d.ts

@@ -6772,18 +6772,30 @@ declare class EndpointAPI {
      */
     call(label: string, init: EndpointCallInit): Promise<Response>;
     /**
-     * 라벨 + path 의 최종 호출 URL 을 조립해서 반환. fetch / WebSocket / new Image()
-     * 같이 SDK 의 `call()` 이 아닌 직접 호출이 필요할 때 사용.
+     * 라벨 + path 의 최종 호출 URL `${baseUrl}/v1/proxy/${label}${path}` 을 조립해서
+     * 반환. URL 을 다른 시스템 (Service Worker, 백엔드 워커, 로깅) 에 넘기거나
+     * 디버깅 용도일 때 사용.
      *
-     * 주의: WebSocket 같이 `X-Public-Key` 헤더를 못 보내는 경로면, 모델 서버가
-     * 자체 토큰으로 별도 인증을 해야 합니다 (ConnectBase 는 인증 게이트가 아닌
-     * dumb pipe 라 path 만으로 인증하지 않음).
+     * ⚠️ **`<img src>` / 네이티브 `WebSocket` / `<script src>` / `EventSource` 처럼
+     * 커스텀 헤더를 못 보내는 브라우저 API 에 직접 넘기면 401 입니다.** ConnectBase
+     * 프록시는 모든 요청에 `X-Public-Key` 헤더를 요구하고, 쿼리 파라미터 폴백은
+     * 제공하지 않습니다. 그런 경우엔 `call()` 로 받아서 Blob URL 로 변환하세요.
      *
-     * @example
+     * @example URL 을 워커로 넘겨 호출 (✅)
+     * ```typescript
+     * sw.postMessage({
+     *     url: cb.endpoint.url("comfyui-main", "/prompt"),
+     *     key: publicKey, // 워커가 X-Public-Key 헤더로 부착
+     * })
+     * ```
+     *
+     * @example 이미지 렌더링은 call() + Blob URL 패턴으로 (✅)
      * ```typescript
-     * // 결과 이미지를 <img> 로 바로 그리기
-     * img.src = `${cb.endpoint.url("comfyui-main", `/view?filename=${name}`)}` +
-     *           `&__pk=${publicKey}` // 모델 서버가 직접 검증하는 토큰
+     * const res = await cb.endpoint.call("comfyui-main", {
+     *     path: `/view?filename=${encodeURIComponent(name)}`,
+     * })
+     * img.src = URL.createObjectURL(await res.blob())
+     * // 나중에 URL.revokeObjectURL(img.src)
      * ```
      */
     url(label: string, path: string): string;

package/dist/index.js

@@ -7718,18 +7718,30 @@ var EndpointAPI = class {
     });
   }
   /**
-   * 라벨 + path 의 최종 호출 URL 을 조립해서 반환. fetch / WebSocket / new Image()
-   * 같이 SDK 의 `call()` 이 아닌 직접 호출이 필요할 때 사용.
+   * 라벨 + path 의 최종 호출 URL `${baseUrl}/v1/proxy/${label}${path}` 을 조립해서
+   * 반환. URL 을 다른 시스템 (Service Worker, 백엔드 워커, 로깅) 에 넘기거나
+   * 디버깅 용도일 때 사용.
    *
-   * 주의: WebSocket 같이 `X-Public-Key` 헤더를 못 보내는 경로면, 모델 서버가
-   * 자체 토큰으로 별도 인증을 해야 합니다 (ConnectBase 는 인증 게이트가 아닌
-   * dumb pipe 라 path 만으로 인증하지 않음).
+   * ⚠️ **`<img src>` / 네이티브 `WebSocket` / `<script src>` / `EventSource` 처럼
+   * 커스텀 헤더를 못 보내는 브라우저 API 에 직접 넘기면 401 입니다.** ConnectBase
+   * 프록시는 모든 요청에 `X-Public-Key` 헤더를 요구하고, 쿼리 파라미터 폴백은
+   * 제공하지 않습니다. 그런 경우엔 `call()` 로 받아서 Blob URL 로 변환하세요.
    *
-   * @example
+   * @example URL 을 워커로 넘겨 호출 (✅)
+   * ```typescript
+   * sw.postMessage({
+   *     url: cb.endpoint.url("comfyui-main", "/prompt"),
+   *     key: publicKey, // 워커가 X-Public-Key 헤더로 부착
+   * })
+   * ```
+   *
+   * @example 이미지 렌더링은 call() + Blob URL 패턴으로 (✅)
    * ```typescript
-   * // 결과 이미지를 <img> 로 바로 그리기
-   * img.src = `${cb.endpoint.url("comfyui-main", `/view?filename=${name}`)}` +
-   *           `&__pk=${publicKey}` // 모델 서버가 직접 검증하는 토큰
+   * const res = await cb.endpoint.call("comfyui-main", {
+   *     path: `/view?filename=${encodeURIComponent(name)}`,
+   * })
+   * img.src = URL.createObjectURL(await res.blob())
+   * // 나중에 URL.revokeObjectURL(img.src)
    * ```
    */
   url(label, path) {

package/dist/index.mjs

@@ -7679,18 +7679,30 @@ var EndpointAPI = class {
     });
   }
   /**
-   * 라벨 + path 의 최종 호출 URL 을 조립해서 반환. fetch / WebSocket / new Image()
-   * 같이 SDK 의 `call()` 이 아닌 직접 호출이 필요할 때 사용.
+   * 라벨 + path 의 최종 호출 URL `${baseUrl}/v1/proxy/${label}${path}` 을 조립해서
+   * 반환. URL 을 다른 시스템 (Service Worker, 백엔드 워커, 로깅) 에 넘기거나
+   * 디버깅 용도일 때 사용.
    *
-   * 주의: WebSocket 같이 `X-Public-Key` 헤더를 못 보내는 경로면, 모델 서버가
-   * 자체 토큰으로 별도 인증을 해야 합니다 (ConnectBase 는 인증 게이트가 아닌
-   * dumb pipe 라 path 만으로 인증하지 않음).
+   * ⚠️ **`<img src>` / 네이티브 `WebSocket` / `<script src>` / `EventSource` 처럼
+   * 커스텀 헤더를 못 보내는 브라우저 API 에 직접 넘기면 401 입니다.** ConnectBase
+   * 프록시는 모든 요청에 `X-Public-Key` 헤더를 요구하고, 쿼리 파라미터 폴백은
+   * 제공하지 않습니다. 그런 경우엔 `call()` 로 받아서 Blob URL 로 변환하세요.
    *
-   * @example
+   * @example URL 을 워커로 넘겨 호출 (✅)
+   * ```typescript
+   * sw.postMessage({
+   *     url: cb.endpoint.url("comfyui-main", "/prompt"),
+   *     key: publicKey, // 워커가 X-Public-Key 헤더로 부착
+   * })
+   * ```
+   *
+   * @example 이미지 렌더링은 call() + Blob URL 패턴으로 (✅)
    * ```typescript
-   * // 결과 이미지를 <img> 로 바로 그리기
-   * img.src = `${cb.endpoint.url("comfyui-main", `/view?filename=${name}`)}` +
-   *           `&__pk=${publicKey}` // 모델 서버가 직접 검증하는 토큰
+   * const res = await cb.endpoint.call("comfyui-main", {
+   *     path: `/view?filename=${encodeURIComponent(name)}`,
+   * })
+   * img.src = URL.createObjectURL(await res.blob())
+   * // 나중에 URL.revokeObjectURL(img.src)
    * ```
    */
   url(label, path) {

package/package.json

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