connectbase-client 6.5.0 → 6.6.0

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [6.6.0] - 2026-10-21
+
+### Added — 카테고리 발행 정책: 방송인과 "위로만" 가는 메시지
+
+1명이 방송하고 많은 사람이 받는 카테고리(가상 콘서트, 라이브 방송)를 위해 카테고리에 방송인 역할(`publisher_roles`)과
+발행 정책(`send_policy`)을 둘 수 있습니다(콘솔, API, MCP 도구). 방송인은 그 역할을 가진 **로그인 멤버 연결**입니다.
+
+- `open`(기본): 누가 보내든 구독자 모두가 받습니다 (지금과 같음).
+- `upstream`: 방송인의 메시지는 모두에게, 방송인이 아닌 구독자의 메시지는 방송인에게만 갑니다. 관객 1,000명의 반응이
+  관객 1,000명에게 복사되지 않습니다.
+- `publishers_only`: 방송인만 보낼 수 있습니다 (관객이 보내면 `SEND_NOT_ALLOWED`).
+
+SDK 쪽 추가:
+- `subscription.info.isPublisher`, `subscription.info.sendPolicy`
+- `message.fromPublisher` — 보낸 쪽이 방송인이라는 **서버 보증** (클라이언트가 위조할 수 없음)
+- `send(data, { to: 'publishers' })` — 정책이 `open` 이어도 이 메시지만 방송인에게 (채팅은 모두에게, 반응은 위로)
+
+```ts
+const concert = await cb.realtime.subscribe('concert')
+concert.onMessage((m) => {
+  if (m.fromPublisher) renderStage(m.data)   // 방송인 화면
+  else countReaction(m.data)                  // 방송인만 받는 관객 반응
+})
+await concert.send({ cheer: 1 })              // upstream 이면 방송인에게만
+```
+
+### Added — 요청 거부 코드: `RealtimeRequestError`
+
+`subscribe`/`send`/`getHistory` 등을 서버가 거부하면 서버 오류 코드(`SEND_NOT_ALLOWED`, `RATE_LIMITED`,
+`MESSAGE_TOO_LARGE`, `NOT_SUBSCRIBED` 등)를 담은 `RealtimeRequestError` 를 던집니다. 예전에는 코드를 버리고
+메시지만 담은 `Error` 였습니다. `Error` 를 상속하므로 기존 `catch` 코드는 그대로 동작합니다.
+
+### Changed — 연결이 몰릴 때 SSE 로 넘어가지 않고 서버가 알려 준 시간 뒤 스스로 다시 붙습니다
+
+한 IP 에서 연결을 짧은 시간에 많이 열면 서버가 연결 속도 제한으로 거부합니다. 예전에는 이 거부가 업그레이드 전 HTTP
+429 라 브라우저가 이유를 못 읽었고, SDK 가 "네트워크가 WebSocket 을 막았다" 로 오인해 SSE 로 넘어갔습니다. 이제 서버가
+`rate_limited` 와 재시도 시각(`retryAfterMs`)을 알려 주고, `connect()` 는 연결 제한 시간(`timeout`) 안에서 그 시각에
+지터를 더해 스스로 다시 붙습니다. 시간 안에 못 붙으면 `RealtimeConnectionError`(`code: 'rate_limited'`, `retryAfterMs`)를
+던집니다.
+
+이유 없는 핸드셰이크 실패도 한 번에 SSE 로 넘어가지 않고 두 번 더 시도합니다 — 네트워크가 WebSocket 을 실제로 막으면
+매번 실패하고, 일시적인 거부는 다시 하면 붙습니다. 자동 재연결 대기에는 지터를 더해(백오프의 절반에서 전체 사이)
+서버 재시작 뒤 모든 클라이언트가 같은 순간에 다시 몰리지 않게 했습니다.
+
+### Fixed — Node 에서 `connect()` 나 HTTP 요청이 끝나지 않던 문제
+
+Node 의 fetch(undici)는 같은 원본으로 요청이 수백 개 몰릴 때 드물게 시간 제한의 abort 를 무시하고 영원히 대기합니다
+(실측: 동시 400개 중 2개). SDK 는 시간 제한을 abort 에만 맡겨, 그 요청과 그것을 기다리는 `realtime.connect()` 가 끝나지
+않았습니다. 이제 시간 제한이 지나면 fetch 의 응답을 기다리지 않고 SDK 가 먼저 끝냅니다(HTTP 요청, 토큰 재발급, 원본 힌트).
+
+### Fixed — 브라우저도 첫 연결부터 저지연 원본(ws-direct)을 씁니다
+
+6.5.0 의 원본 힌트 조회(`/v1/public/edge-hints`)는 공개 키 헤더를 붙여 보내 브라우저가 CORS 사전 요청을 먼저 보냈고
+(Cloudflare 왕복 두 번), 앱의 "로컬 개발 origin 허용" 이 꺼진 localhost 페이지에서는 막혔습니다. 그래서 Node 는 direct 로
+붙고 브라우저는 Cloudflare 경로로 붙었습니다. 이제 헤더 없는 단순 GET 으로 묻고 본문으로 배웁니다(서버도 키 없이 답합니다).
+
 ## [6.5.0] - 2026-10-21
 
 ### Added — 실시간 연결 거부 사유: `RealtimeConnectionError`

package/README.md

@@ -1029,6 +1029,45 @@ try {
 보냅니다. 서버 코드(함수)에서 realtime 을 쓴다면 끝날 때 `cb.realtime.disconnect()` 를 부르세요 — 함수 컨테이너는
 호출 사이에 재사용되므로 닫지 않은 소켓이 호출마다 쌓입니다(`unsubscribe()` 는 소켓을 닫지 않습니다).
 
+한 IP 에서 연결이 몰려 서버가 `rate_limited` 로 거부하면(v6.6.0+) `connect()` 가 서버가 알려 준 시간(`retryAfterMs`)에
+지터를 더해 스스로 다시 붙습니다. 연결 제한 시간(`timeout`, 기본 30초) 안에 못 붙을 때만 이 에러를 던집니다.
+
+#### Broadcast categories: publishers (v6.6.0)
+
+1명이 방송하고 많은 사람이 받는 카테고리는 콘솔에서 **방송인 역할**(`publisher_roles`)과 **발행 정책**(`send_policy`)을
+설정합니다. 방송인은 그 역할을 가진 로그인 멤버(`accessToken`) 연결이고, 공개 키(익명) 연결은 방송인이 될 수 없습니다.
+
+| `send_policy` | 방송인의 메시지 | 방송인이 아닌 구독자의 메시지 |
+|---|---|---|
+| `open` (기본) | 모두에게 | 모두에게 |
+| `upstream` | 모두에게 | **방송인에게만** (히스토리에 저장되지 않음) |
+| `publishers_only` | 모두에게 | 보낼 수 없음 (`SEND_NOT_ALLOWED`) |
+
+```typescript
+import { RealtimeRequestError } from 'connectbase-client'
+
+const concert = await cb.realtime.subscribe('concert')
+concert.info.isPublisher   // 이 연결이 방송인인가 (구독할 때 정해짐)
+concert.info.sendPolicy    // 'open' | 'upstream' | 'publishers_only'
+
+concert.onMessage((m) => {
+  if (m.fromPublisher) renderStage(m.data)   // 서버가 보증하는 방송인 메시지 (위조 불가)
+  else countReaction(m.data)                  // upstream: 방송인만 받는 관객 반응
+})
+
+await concert.send({ cheer: 1 })                         // upstream 이면 방송인에게만
+await concert.send({ cheer: 1 }, { to: 'publishers' })   // open 카테고리에서도 이 메시지만 방송인에게
+
+try {
+  await concert.send({ x: 1 })
+} catch (e) {
+  if (e instanceof RealtimeRequestError && e.code === 'SEND_NOT_ALLOWED') hideSendButton()
+}
+```
+
+방송인 여부는 구독할 때 정해집니다. 멤버 역할이나 카테고리 설정을 바꾸면 다시 구독(또는 재연결)할 때 반영되고,
+카테고리 설정은 서버 캐시 때문에 최대 5분 뒤에 반영됩니다.
+
 #### Presence / Typing
 
 Presence(온라인 상태) 와 typing(입력 중 표시) 은 `cb.realtime.*` 가 단일 SoT 입니다.

package/dist/cli.js

@@ -156,7 +156,7 @@ function handleTunnelError(msg, appId, localPort) {
 }
 
 // src/cli.ts
-var VERSION = "6.5.0" ? "6.5.0" : getPackageVersion();
+var VERSION = "6.6.0" ? "6.6.0" : getPackageVersion();
 var DEFAULT_BASE_URL = "https://api.connectbase.world";
 var colors = {
   reset: "\x1B[0m",