connectbase-client 3.22.0 → 3.23.0

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.23.0] - 2026-05-26
+
+### Fixed — OAuth 표준 흐름 페이지 리로드 후 세션 유실 (platform-issue 019e638d)
+
+문서의 OAuth redirect 표준 예제 그대로 따라가도 **콜백 → 메인 페이지** 전환 직후 `cb.auth.getMe()` 가 401 으로 떨어져 비개발자 사용자가 영원히 로그인 루프에 갇히던 회귀를 3개 race + 1개 충돌 가드로 동시에 닫는다.
+
+**(1) Race A — callback fire-and-forget cookie 부트스트랩**
+`getCallbackResult()` / `exchangeCodeFromCallback()` 가 `setTokens` 직후 `bootstrapRefreshCookie()` 를 fire-and-forget 으로 호출했다. 표준 예제처럼 `window.location.href='/'` 가 즉시 발화하면 fetch 가 abort 되어 `cb_member_refresh_token` cookie 가 발급되지 않았다. 모바일·느린 네트워크에서 특히 잘 깨졌다.
+- **변경**: `getCallbackResult()` 시그니처를 동기 → `Promise` 로 변경 (BREAKING — prelaunch 단계라 backward-compat 가드 생략). `exchangeCodeFromCallback()` / popup 핸들러도 cookie 부트스트랩을 *await* 한 뒤에 resolve. 호출자가 `await cb.oauth.getCallbackResult()` 후 navigation 하면 cookie 가 안전하게 저장된 상태가 보장된다.
+
+**(2) Race B — 메인 페이지 entry race**
+ConnectBase 인스턴스 생성 시 `tryRestoreSessionFromCookie()` 가 fire-and-forget 으로 진행되는데, 사용자 코드의 첫 인증 호출(`getMe()` 등) 이 그 promise 보다 먼저 발화하면 메모리 토큰 빈 채로 401 받았다.
+- **변경**: 부팅 시 시작된 복구 promise 를 HttpClient 에 등록해, `prepareHeaders` 가 인증 호출 직전에 1회 await. 표준 예제 무수정으로 race 가 닫힌다.
+
+**(3) 401 자동 복구**
+인증 호출이 401 받으면 cookie 기반 복구를 *한 번* 시도하고 retry. cookie 가 살아 있는 사용자의 첫 호출이 화면 401 으로 깨지지 않게 한다 (cookie 복구 실패 시엔 원본 401 그대로 throw — 무한 retry 차단).
+
+**(4) Backend strict X-Public-Key dispatch (충돌 C)**
+같은 `.connectbase.world` 루트의 콘솔 admin refresh cookie 가 `credentials:'include'` 로 SDK 호출에 함께 첨부되어, SDK 가 콘솔 User JWT 를 silent reject 하는 케이스 차단. backend `/v1/auth/re-issue` 에서 cross-source cookie fallback 을 제거 — SDK 호출(X-Public-Key 있음) 은 `cb_member_refresh_token` 만, 콘솔 호출은 `refresh_token` 만 사용한다. 한쪽이 없으면 401 로 깔끔히 떨어뜨려 SDK 가드(`isConsolePlatformToken`) 가 더 이상 트리거되지 않는다.
+
+### Breaking
+
+- `cb.oauth.getCallbackResult()` 가 `Promise` 를 반환합니다. 호출자는 반드시 `await` 해야 합니다. 컴파일 타임에 잡히지만, 동기 호출 코드는 콜백 결과를 `Promise<...>` 로 받아 `result.error` 가 항상 undefined 로 보입니다.
+  - **마이그레이션**: `const result = cb.oauth.getCallbackResult()` → `const result = await cb.oauth.getCallbackResult()`. React `useEffect` 안에서는 IIFE 패턴: `;(async () => { const result = await cb.oauth.getCallbackResult(); ... })()`.
+
+### Tests
+
+- `test/http-race-recovery.test.ts` — race B / 401 auto-recovery / skipAuth 보존 5 케이스
+- `test/oauth-callback-cookie-bootstrap.test.ts` — `await` 시그니처 + bootstrap-before-result 보장 추가
+
+## [3.22.1] - 2026-05-26
+
+### Documentation
+
+README 에 3.22.0 에서 추가된 공개 API 3종을 정식 섹션으로 문서화. 코드 동작 변경 없음.
+
+- **Key Types** 섹션에 `Server-side admin context` 추가 — `new ConnectBase({ publicKey, secretKey })` 가 admin 헤더(`X-Public-Key` + `Authorization: Bearer cb_sk_*`) 를 첨부하고 서버 `OptionalAdminSecretKey` 미들웨어가 RLS 를 우회한다는 점을 명시.
+- **Authentication** 섹션에 `cb.auth.adminUpdateMember(memberID, fields)` 예제 + `secretKey` 미설정 시 throw / self-update 거절 동작 + `role` 이 RLS `auth.role` 의 backing field 임을 명시.
+- **Server Functions** 섹션 신설 (Realtime 과 Endpoint 사이) — `cb.functions.invoke` + `cb.functions.getWebhookURL` + `http_trigger_auth` 3종(`none` / `public_key` / `secret_key`) + raw body / 헤더 forward / 10MB 한도 / Discord interactions 응답 예제.
+
 ## [3.22.0] - 2026-05-25
 
 ### Added — 서버사이드 admin (cb_sk_) 권한으로 data CRUD + 멤버 role 관리 (platform-issue 019e5a04, 019e59ca)

package/README.md

@@ -37,6 +37,29 @@ Connect Base provides **two types** of Keys. Use the right key for your use case
 
 Create Keys in the Console under **Settings > API tab**. Choose Public or Secret type when creating. The full key is shown **only once** at creation time.
 
+#### Server-side admin context (v3.22.0+)
+
+When you create the SDK with **both** `publicKey` and `secretKey`, the client
+attaches `X-Public-Key` (app identity) and `Authorization: Bearer cb_sk_*`
+(privilege escalation) on every request. The server's `OptionalAdminSecretKey`
+middleware verifies the secret key, sets an admin context, and **skips RLS**
+for that request — useful for backend sync scripts, admin tools, and
+`cb.auth.adminUpdateMember()`.
+
+```typescript
+// SERVER-SIDE ONLY — never ship this in a browser/mobile bundle
+const cb = new ConnectBase({
+  publicKey: process.env.CB_PUBLIC_KEY!,  // cb_pk_
+  secretKey: process.env.CB_SECRET_KEY!,  // cb_sk_  (admin)
+})
+
+// Bypasses RLS .write/.read rules
+await cb.database.createData('orders', { ... })
+```
+
+Without `secretKey`, every request is RLS-evaluated as normal — there is no
+behavioral change for browser clients.
+
 ## Quick Start
 
 ```typescript
@@ -515,6 +538,36 @@ const result = await cb.oauth.signInWithPopup('google', 'https://myapp.com/oauth
 await cb.auth.signOut()
 ```
 
+#### Admin: update another member (v3.22.0+)
+
+Set another member's `nickname`, `role`, or `custom_data` from a server-side
+admin context. Requires the SDK to be initialized with `secretKey` — calling
+this without one throws synchronously. Self-update is rejected by the server.
+
+```typescript
+// SERVER-SIDE ONLY — admin context required (publicKey + secretKey)
+const cb = new ConnectBase({
+  publicKey: process.env.CB_PUBLIC_KEY!,
+  secretKey: process.env.CB_SECRET_KEY!,
+})
+
+// Grant role used by RLS `auth.role` expressions
+await cb.auth.adminUpdateMember('019abc12-...', { role: 'editor' })
+
+// Clear the role
+await cb.auth.adminUpdateMember('019abc12-...', { role: '' })
+
+// Multi-field update
+await cb.auth.adminUpdateMember('019abc12-...', {
+  nickname: 'Alice',
+  role: 'admin',
+  custom_data: { level: 5 },
+})
+```
+
+`role` is the only way to populate the RLS expression variable `auth.role` —
+end-users can't set it on themselves through the public profile API.
+
 ### Database
 
 ```typescript
@@ -956,6 +1009,56 @@ await session.stop()
 | `promptTokens` | `number` | Input prompt tokens |
 | `duration` | `number` | Generation time in ms |
 
+### Server Functions
+
+Invoke a deployed function from the SDK, or expose it as a raw HTTP webhook
+that external services (Discord, Stripe, GitHub, Slack Events, etc.) can call
+directly.
+
+```typescript
+// Invoke a function (publicKey-authenticated; runs in your Knative pod)
+const result = await cb.functions.invoke('019abc12-...', { orderId: '...' })
+```
+
+#### Raw HTTP webhook URL (v3.22.0+)
+
+For external SaaS webhooks where you can't customize the request shape (raw
+body, vendor-specific signature headers, arbitrary HTTP methods), enable
+`http_trigger_enabled` on the function (Console or MCP `update_function`) and
+register the URL returned by `getWebhookURL()` with the upstream service.
+
+```typescript
+const url = cb.functions.getWebhookURL('019abc12-...')
+// → https://api.connectbase.world/v1/public/functions/019abc12-.../webhook
+```
+
+| `http_trigger_auth` | Required header | Use for |
+|---|---|---|
+| `none` | _(none)_ | External SaaS webhooks (function verifies signature itself) |
+| `public_key` | `X-Public-Key: cb_pk_*` | Your own clients/services |
+| `secret_key` | `Authorization: Bearer cb_sk_*` | Server-to-server admin calls |
+
+The endpoint forwards the **raw request body** (no JSON wrap), preserves
+method/path/query, and forwards all headers — so signature checks (Ed25519,
+HMAC-SHA256, Stripe-Signature, X-Hub-Signature-256) work end-to-end. Body
+limit is 10MB.
+
+Return `{ statusCode, headers, body }` from the handler to emit a custom
+HTTP response (for example, Discord Interactions requires a `200` with a
+JSON body within 3 seconds):
+
+```javascript
+export async function handler(event, ctx) {
+  // event.method / event.path / event.query / event.headers / event.body
+  // are populated for webhook invocations.
+  return {
+    statusCode: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 1 }),  // Discord PING ack
+  }
+}
+```
+
 ### Endpoint (Local Model Tunnel)
 
 `cb.endpoint.*` is a dumb pipe to your own GPU/model server running behind a