connectbase-client 6.6.1 → 6.8.0

package/dist/index.js

@@ -2074,6 +2074,11 @@ var AuthAPI = class {
    *     role: 'editor',
    *     custom_data: { level: 5 }
    * })
+   *
+   * // 역할 여러 개 (6.7.0+): role 은 주 역할(RLS auth.role), roles 는 추가 역할 목록을 **통째로 바꾼다**
+   * // ([] 면 비우고, 빼면 그대로). auth.roles, hasRole(), 실시간 publisher_roles 는 role + roles 를 함께 본다.
+   * await cb.auth.adminUpdateMember('member-uuid', { roles: ['performer'] })
+   * // → { role: 'admin', roles: ['performer'], effective_roles: ['admin', 'performer'], ... }
    * ```
    */
   async adminUpdateMember(memberID, fields) {
@@ -7571,7 +7576,7 @@ var PushAPI = class {
   /**
    * 디바이스 등록 해제
    *
-   * @param deviceToken 디바이스 토큰
+   * @param deviceToken 디바이스 토큰 (웹 푸시 기기는 등록 응답의 `device_token`, 즉 endpoint URL)
    *
    * @example
    * ```typescript
@@ -7580,13 +7585,18 @@ var PushAPI = class {
    */
   async unregisterDevice(deviceToken) {
     const prefix = this.getPublicPrefix();
-    await this.http.delete(`${prefix}/push/devices/${deviceToken}`);
+    await this.http.post(`${prefix}/push/devices/unregister`, {
+      device_token: deviceToken
+    });
   }
   // ============ Topic Subscription ============
   /**
    * 토픽 구독
    *
-   * @param deviceToken 디바이스 토큰
+   * 토픽은 미리 있어야 한다(콘솔에서 만든다). 없으면 404 로 거부된다.
+   *
+   * @param deviceToken 디바이스 토큰 — `registerDevice` / `registerWebPush` 응답의 `device_token`
+   *   (웹 푸시 기기는 endpoint URL. 6.7.0 이하는 웹 기기를 구독시키지 못했다)
    * @param topicName 토픽 이름
    *
    * @example
@@ -7596,11 +7606,11 @@ var PushAPI = class {
    */
   async subscribeTopic(deviceToken, topicName) {
     const prefix = this.getPublicPrefix();
-    const request = { topic_name: topicName };
-    await this.http.post(
-      `${prefix}/push/devices/${deviceToken}/topics/subscribe`,
-      request
-    );
+    const request = {
+      device_token: deviceToken,
+      topic_name: topicName
+    };
+    await this.http.post(`${prefix}/push/topics/subscribe`, request);
   }
   /**
    * 토픽 구독 해제
@@ -7615,9 +7625,11 @@ var PushAPI = class {
    */
   async unsubscribeTopic(deviceToken, topicName) {
     const prefix = this.getPublicPrefix();
-    await this.http.delete(
-      `${prefix}/push/devices/${deviceToken}/topics/${topicName}/unsubscribe`
-    );
+    const request = {
+      device_token: deviceToken,
+      topic_name: topicName
+    };
+    await this.http.post(`${prefix}/push/topics/unsubscribe`, request);
   }
   // ============ Web Push ============
   /**
@@ -7694,13 +7706,10 @@ var PushAPI = class {
   /**
    * Web Push 구독 해제
    *
-   * @param deviceToken Web Push endpoint URL (등록 시 사용한 endpoint)
+   * @param deviceToken Web Push endpoint URL (등록 응답의 `device_token`)
    */
   async unregisterWebPush(deviceToken) {
-    const prefix = this.getPublicPrefix();
-    await this.http.delete(
-      `${prefix}/push/devices/${encodeURIComponent(deviceToken)}`
-    );
+    await this.unregisterDevice(deviceToken);
   }
   // ============ Server-side Send (Functions / cb_sk_ 전용) ============
   /**
@@ -7803,6 +7812,42 @@ var PushAPI = class {
       body
     );
   }
+  /**
+   * 토픽 만들기 — 서버 코드 전용 (6.8.0+).
+   *
+   * 방마다 쓰는 토픽처럼 서버 코드가 토픽을 만들어 두고, 기기는 그 뒤에 `subscribeTopic` 으로 구독한다. 같은 이름의
+   * 토픽이 이미 있으면 오류 없이 그 토픽을 돌려준다(설정은 바꾸지 않는다) — 트리거가 다시 실행돼도 안전하다.
+   *
+   * Public Key(cb_pk_) 단독 인스턴스로는 호출할 수 없다(공개 키로는 토픽을 만들 수 없다). service_role(ctx.cbAdmin)은
+   * 함수의 management_scopes 에 `push:write` 가 있어야 한다. User Secret Key(cb_sk_), 콘솔 JWT 도 된다.
+   *
+   * @param appId 앱 ID
+   * @param name 토픽 이름 (255바이트 이하, 앞뒤 공백은 지운다)
+   * @param options 표시 이름, 설명
+   * @returns 만들었거나 이미 있던 토픽
+   *
+   * @example
+   * ```typescript
+   * // concerts 트리거 함수: 공연이 생기면 그 방의 알림 토픽을 만들어 둔다
+   * await ctx.cbAdmin.push.createTopic(appId, `cc_${row.room}`, { displayName: row.title })
+   * ```
+   */
+  async createTopic(appId, name, options = {}) {
+    if (this.http.hasPublicKey() && !this.http.hasJWT()) {
+      throw new Error(
+        "cb.push.createTopic() \uB294 User Secret Key(cb_sk_), \uCF58\uC194 JWT, \uB610\uB294 service_role(ctx.cbAdmin) \uC778\uC99D\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. Public Key(cb_pk_) \uB2E8\uB3C5 SDK \uC778\uC2A4\uD134\uC2A4\uB85C\uB294 \uD1A0\uD53D\uC744 \uB9CC\uB4E4 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 Functions \uD658\uACBD\uC5D0\uC11C \uC0AC\uC6A9\uD558\uC138\uC694."
+      );
+    }
+    if (!name || !name.trim()) {
+      throw new Error("cb.push.createTopic(): name \uC774 \uBE44\uC5B4\uC788\uC2B5\uB2C8\uB2E4.");
+    }
+    return this.http.post(`/v1/apps/${appId}/push/topics`, {
+      name,
+      if_not_exists: true,
+      ...options.displayName !== void 0 ? { display_name: options.displayName } : {},
+      ...options.description !== void 0 ? { description: options.description } : {}
+    });
+  }
   /**
    * 앱의 푸시 통계(도달/오픈율/클릭율, 디바이스/메시지/토픽 수)를 조회한다.
    *
@@ -7991,6 +8036,38 @@ var ConnectCancelledError = class extends Error {
   }
 };
 var MAX_HANDSHAKE_RETRIES = 2;
+var RETRY_IN_CONNECT_CODES = /* @__PURE__ */ new Set(["rate_limited", "auth_unavailable"]);
+var CHANNEL_CATEGORY_RE = /^[A-Za-z0-9_-]{1,128}$/;
+var CHANNEL_ROOM_RE = /^[A-Za-z0-9._-]{1,128}$/;
+var MAX_CHANNEL_LENGTH = 256;
+function toChannel(category, room) {
+  if (room === void 0) return category;
+  const show = (v) => typeof v === "string" ? JSON.stringify(v) : String(v);
+  if (typeof room !== "string" || !CHANNEL_ROOM_RE.test(room)) {
+    throw new Error(
+      `Invalid room ${show(room)}: use 1-128 characters of letters, digits, "-", "_" or "." (the realtime channel is "<category>:<room>").`
+    );
+  }
+  if (typeof category !== "string" || !CHANNEL_CATEGORY_RE.test(category)) {
+    throw new Error(
+      `Invalid category ${show(category)} for a room subscription: use the base category name (1-128 characters of letters, digits, "-" or "_") and pass the room separately with { room }.`
+    );
+  }
+  const channel = `${category}:${room}`;
+  if (channel.length > MAX_CHANNEL_LENGTH) {
+    throw new Error(
+      `Realtime channel "${channel}" is too long (max ${MAX_CHANNEL_LENGTH} characters including ":").`
+    );
+  }
+  return channel;
+}
+function roomOf(channel) {
+  const idx = channel.indexOf(":");
+  return idx > 0 && idx < channel.length - 1 ? channel.slice(idx + 1) : void 0;
+}
+function toMemberId(value) {
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
 function jitter(max) {
   return Math.floor(Math.random() * Math.max(0, max));
 }
@@ -8211,31 +8288,46 @@ var RealtimeAPI = class {
   }
   /**
    * 카테고리 구독
+   *
+   * `options.room` 을 주면 그 카테고리의 room 하나를 구독한다 (6.7.0+). 서버 채널 이름은
+   * `${category}:${room}` 이고, 구독 객체의 `send` / `getHistory` / `unsubscribe` / `onMessage`, 재연결 뒤
+   * 다시 구독하기는 모두 이 채널 이름으로 동작한다(`subscription.channel`).
+   *
+   * @example
+   * ```typescript
+   * const stage = await client.realtime.subscribe('concert', { room: 'show-1025' })
+   * stage.channel          // 'concert:show-1025'
+   * stage.room             // 'show-1025'
+   * stage.info.isPublisher // room 인가 함수가 publisher: true 를 돌려준 로그인 멤버면 true
+   * ```
    */
   async subscribe(category, options = {}) {
+    const channel = toChannel(category, options.room);
     this.assertBidirectional("subscribe");
     if (this.state !== "connected") {
       throw new Error("Not connected. Call connect() first.");
     }
     const requestId = this.generateRequestId();
     const response = await this.sendRequest({
-      category,
+      category: channel,
       action: "subscribe",
       request_id: requestId
     });
     const info = toCategoryInfo(response);
     const handlers = [];
-    this.subscriptions.set(category, { info, handlers });
+    this.subscriptions.set(channel, { info, handlers });
     const subscription = {
       info,
+      channel,
+      room: roomOf(channel),
       send: async (data, sendOptions) => {
-        await this.sendMessage(category, data, sendOptions);
+        await this.sendMessage(channel, data, sendOptions);
       },
       getHistory: async (limit) => {
-        return this.getHistory(category, limit ?? options.historyLimit);
+        return this.getHistory(channel, limit ?? options.historyLimit);
       },
       unsubscribe: async () => {
-        await this.unsubscribe(category);
+        await this.unsubscribe(channel);
       },
       onMessage: (handler) => {
         handlers.push(handler);
@@ -8249,6 +8341,7 @@ var RealtimeAPI = class {
   }
   /**
    * 구독 해제
+   * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
    */
   async unsubscribe(category) {
     if (this.state !== "connected") {
@@ -8264,7 +8357,7 @@ var RealtimeAPI = class {
   }
   /**
    * 메시지 전송
-   * @param category 카테고리 이름
+   * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
    * @param data 전송할 데이터
    * @param options 전송 옵션 (includeSelf: 발신자도 메시지 수신 여부, 기본값 true)
    */
@@ -8285,6 +8378,7 @@ var RealtimeAPI = class {
   }
   /**
    * 히스토리 조회
+   * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
    */
   async getHistory(category, limit) {
     this.assertBidirectional("getHistory");
@@ -8304,6 +8398,7 @@ var RealtimeAPI = class {
         id: m.id,
         category: m.category,
         from: m.from,
+        fromMember: toMemberId(m.from_member),
         data: m.data,
         sentAt: m.sent_at
       })),
@@ -8993,7 +9088,9 @@ var RealtimeAPI = class {
    * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
    * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
    * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
-   * 세션당 한 번만 묻는다.
+   * 인스턴스당 한 번만 묻고, 같은 baseUrl 의 인스턴스끼리는 진행 중인 조회와 배운 결과를 함께 쓴다
+   * (6.7.0+, HttpClient.primeEdgeHints 참고 — 한 페이지의 인스턴스 10개가 동시에 물어 대부분 1.5초를 넘기던
+   * platform-issue 01a15e81).
    */
   async primeDirectRealtime() {
     if (this.directRealtimePrimed) return;
@@ -9012,12 +9109,17 @@ var RealtimeAPI = class {
   /**
    * 첫 연결을 연결 제한 시간(`timeout`) 안에서 다시 시도한다 (6.6.0+, platform-issue 01a15e24).
    *
-   * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: 한 IP 에서 연결이 몰린 `rate_limited`):
-   *   그 시각에 지터를 더해 다시 붙는다. 공연 시작처럼 한꺼번에 들어올 때 앱이 재시도를 짜지 않아도 된다.
+   * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: 한 IP 에서 연결이 몰린 `rate_limited`, 인증 서버가
+   *   잠깐 닿지 않는 `auth_unavailable`): 그 시각에 지터를 더해 다시 붙는다. 공연 시작처럼 한꺼번에 들어올 때
+   *   앱이 재시도를 짜지 않아도 된다.
+   * - `rate_limited` / `auth_unavailable` 인데 재시도 시각이 없으면(사유 프레임 없이 close 코드만 왔거나 구버전
+   *   서버) 지수 백오프로 다시 한다. `auth_unavailable` 은 6.6.0 까지 바로 던져, 인증 서버가 몇 초 흔들리는
+   *   동안 들어온 관객이 전부 연결에 실패했다(6.7.0, platform-issue 01a15e81).
    * - 이유 없는 핸드셰이크 실패: 두 번까지 백오프 후 다시 한다. 네트워크가 WebSocket 을 실제로 막으면
    *   매번 실패하고, 앞단의 일시 거부는 다시 하면 붙는다 — 한 번 실패로 SSE 폴백하던 것이 연결 속도
    *   제한을 "네트워크 차단" 으로 오진한 원인이었다.
-   * - 그 밖의 거부(자격증명, 동시접속 한도 등)와 시간 초과는 바로 던진다.
+   * - 그 밖의 거부(자격증명, 동시접속 한도 등)와 시간 초과는 바로 던진다. 다시 시도할 시간이 남지 않아도
+   *   마지막 거부를 그대로 던진다(`retryAfterMs` 가 있으면 앱이 그 시각에 다시 부를 수 있다).
    */
   async connectWithRetry() {
     const generation = this.connectGeneration;
@@ -9031,10 +9133,10 @@ var RealtimeAPI = class {
           return;
         } catch (e) {
           let wait = null;
-          if (e instanceof RealtimeConnectionError) {
-            if (e.retryable && e.retryAfterMs !== void 0) {
+          if (e instanceof RealtimeConnectionError && e.retryable) {
+            if (e.retryAfterMs !== void 0) {
               wait = e.retryAfterMs + jitter(Math.min(100 * 2 ** attempt, 3e3));
-            } else if (e.code === "rate_limited") {
+            } else if (RETRY_IN_CONNECT_CODES.has(e.code)) {
               const base = Math.min(500 * 2 ** (attempt - 1), 8e3);
               wait = base / 2 + jitter(base / 2);
             }
@@ -9265,7 +9367,9 @@ var RealtimeAPI = class {
           const message = {
             id: data.id,
             category: data.category,
+            // from 은 클라이언트가 정한 client_id 라 믿을 수 없다. 보낸 사람은 fromMember(서버 검증)로 본다.
             from: data.from,
+            fromMember: toMemberId(data.from_member),
             data: data.data,
             sentAt: data.sent_at,
             fromPublisher: data.from_publisher === true
@@ -11125,8 +11229,8 @@ var SupportAPI = class {
   }
 };
 function detectSdkVersion() {
-  if (typeof __SDK_VERSION__ !== "undefined" && __SDK_VERSION__) {
-    return __SDK_VERSION__;
+  if ("6.8.0") {
+    return "6.8.0";
   }
   return "unknown";
 }
@@ -12718,6 +12822,63 @@ function isConsolePlatformToken(token) {
   const role = decodeJwtPayload(token)?.role;
   return role === "User" || role === "AdminInvite";
 }
+var EDGE_HINTS_TTL_MS = 10 * 6e4;
+var sharedEdgeHints = /* @__PURE__ */ new Map();
+function lookupEdgeHints(baseUrl, timeoutMs) {
+  const cached = sharedEdgeHints.get(baseUrl);
+  if (cached && Date.now() < cached.expiresAt) return cached.promise;
+  const entry = {
+    promise: fetchEdgeHintAdverts(baseUrl, timeoutMs),
+    // 진행 중에는 만료되지 않는다 — 시간 제한(withAbort) 때문에 timeoutMs 안에 반드시 끝난다. 늦게 합류한
+    // 인스턴스는 남은 시간만 기다린다.
+    expiresAt: Number.POSITIVE_INFINITY
+  };
+  sharedEdgeHints.set(baseUrl, entry);
+  entry.promise.then(
+    () => {
+      entry.expiresAt = Date.now() + EDGE_HINTS_TTL_MS;
+    },
+    () => {
+      if (sharedEdgeHints.get(baseUrl) === entry) {
+        sharedEdgeHints.delete(baseUrl);
+      }
+    }
+  );
+  return entry.promise;
+}
+async function fetchEdgeHintAdverts(baseUrl, timeoutMs) {
+  const { signal, cleanup } = createTimeoutController({ timeout: timeoutMs });
+  try {
+    const response = await withAbort(
+      fetch(`${baseUrl}/v1/public/edge-hints`, {
+        method: "GET",
+        credentials: "omit",
+        signal
+      }),
+      signal
+    );
+    if (!response.ok) {
+      throw new Error(`edge-hints HTTP ${response.status}`);
+    }
+    const header = {
+      direct: response.headers?.get("X-CB-Direct-Base") || null,
+      realtime: response.headers?.get("X-CB-Realtime-Direct-Base") || null
+    };
+    let body;
+    try {
+      body = await withAbort(response.json(), signal);
+    } catch (err) {
+      if (header.direct || header.realtime) return [header];
+      throw err;
+    }
+    return [
+      header,
+      { direct: body?.direct_base, realtime: body?.realtime_direct_base }
+    ];
+  } finally {
+    cleanup();
+  }
+}
 var HttpClient = class {
   constructor(config) {
     this.isRefreshing = false;
@@ -13523,28 +13684,18 @@ var HttpClient = class {
    * 먼저 보내 Cloudflare 를 두 번 왕복하고, 앱의 "로컬 개발 origin 허용" 이 꺼진 localhost 페이지에서는
    * 키 기반 opt-in 에 막혀 브라우저만 direct 를 못 썼다(Node 는 썼다 — platform-issue 01a15e24).
    * 서버는 이 경로를 키 없이 열어 두고 같은 값을 본문으로도 준다. 본문을 읽으므로 CORS
-   * Expose-Headers 에도 기대지 않는다. 실패는 조용히 무시한다 — direct 는 최적화일 뿐이다.
+   * Expose-Headers 에도 기대지 않는다. 실패는 호출자에게 던지고 호출자(RealtimeAPI)가 조용히 넘어간다 —
+   * direct 는 최적화일 뿐이다.
+   *
+   * 조회 자체는 같은 baseUrl 의 인스턴스끼리 함께 쓴다(6.7.0+, {@link sharedEdgeHints} 참고). 진행 중인
+   * 조회가 있으면 새로 보내지 않고 기다리며, 성공한 결과는 잠시 다시 쓴다. 받아들일지는 이 인스턴스가 정한다 —
+   * 이미 배웠거나(`directRealtimeBaseUrl`) direct 를 포기했으면(`directRealtimeDisabled`) 바꾸지 않는다.
    */
   async primeEdgeHints(timeoutMs) {
     if (this.directRealtimeBaseUrl || this.directRealtimeDisabled) return;
-    const { signal, cleanup } = createTimeoutController({ timeout: timeoutMs });
-    try {
-      const response = await withAbort(
-        fetch(`${this.config.baseUrl}/v1/public/edge-hints`, {
-          method: "GET",
-          credentials: "omit",
-          signal
-        }),
-        signal
-      );
-      if (!response.ok) {
-        throw new Error(`edge-hints HTTP ${response.status}`);
-      }
-      this.learnDirectOrigin(response);
-      const body = await withAbort(response.json(), signal);
-      this.adoptDirectBases(body?.direct_base, body?.realtime_direct_base);
-    } finally {
-      cleanup();
+    const adverts = await lookupEdgeHints(this.config.baseUrl, timeoutMs);
+    for (const advert of adverts) {
+      this.adoptDirectBases(advert.direct, advert.realtime);
     }
   }
   /**