connectbase-client 5.1.0 → 5.1.1

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [5.1.1] - 2026-07-30
+
+### Docs — README 에 Server-side (Admin) 섹션 신설
+
+**코드 변경 없음.** 빌드 산출물(`dist/`)은 5.1.0 과 동일하다.
+
+README API Reference 가 클라이언트 모듈만 다루고 있어서, 앱 소유자 권한으로 호출하는 관리
+API 가 npm 페이지에서 통째로 보이지 않았다. 5.1.0 에서 추가한 `cb.appMembers` 를 포함해
+서버사이드 표면을 한 섹션으로 정리했다:
+
+- `appMembers.list/get`(이메일 포함) · `roles.*` · `publicKey.*` · `payment.list` · `push.getStats`
+- `service_role` + `management_scopes` 최소권한 모델과 스코프↔메서드 대응표 7종
+- 브라우저(`cb_pk_` 단독)에서 호출할 수 없는 이유와, 멤버 본인 조회는 `cb.auth.getMe()` 라는 구분
+- `cb_sk_` 단독은 401 이며 시크릿이 이 경로에 등장하지 않는다는 점
+
+섹션의 모든 예제 시그니처는 발행된 타입 정의에 대해 `tsc --strict` 로 검증했다.
+
 ## [5.1.0] - 2026-07-30
 
 ### Added — 앱 멤버 관리자 조회 `cb.appMembers` (이메일 포함)

package/README.md

@@ -117,6 +117,7 @@ try {
 - **Knowledge Base (RAG)**: Document indexing + BM25 search with nori 한국어 형태소. PDF / DOCX / text file upload via `addDocumentFromFile`
 - **Endpoint**: Call your own GPU models on your own PC through one `cb_pk_*` key — ConnectBase forwards the payload as-is (dumb pipe)
 - **Support**: End-user feedback/issue reporting — users send issues to app operators, AI auto-classifies summary/urgency/category
+- **Server-side (Admin)**: App-owner APIs for members (incl. email), roles/RBAC, public keys, payments and push stats — via console JWT or a serverless function's `ctx.cbAdmin` with least-privilege `management_scopes`
 - **CLI**: Command-line tool for deploying web storage and tunneling local services
 
 ## CLI
@@ -1335,6 +1336,78 @@ await cb.support.reportIssue({
 
 발행자가 결과를 조회하는 채널은 후속 plan 에서 추가될 예정 — 현재는 운영자가 외부 webhook(이메일/Slack 등)으로 회신하는 방식 권장.
 
+### Server-side (Admin)
+
+앱 소유자 권한으로 호출하는 **관리 API**. 위의 클라이언트 모듈과 달리 **브라우저에서 Public Key(`cb_pk_`) 단독으로는 호출할 수 없다** — 다른 회원의 개인정보나 키 발급 같은 표면이라, 콘솔 JWT 또는 서버리스 함수의 `ctx.cbAdmin` 컨텍스트가 필요하다. 잘못된 인증으로 호출하면 SDK 가 요청 전에 예외를 던진다.
+
+함수에서 쓰려면 두 가지가 필요하다:
+
+1. 함수 생성 시 `service_role: true` — 런타임이 `ctx.cbAdmin` 을 주입한다 (RLS 우회, 이 앱 스코프).
+2. `management_scopes` 에 필요한 스코프만 opt-in — 최소권한. 스코프 없이 호출하면 403.
+
+| 스코프 | 열리는 메서드 |
+|---|---|
+| `app_member:read` | `appMembers.list` / `appMembers.get` — 멤버 목록·상세 (**이메일 포함**) |
+| `role:read` | `roles.list` / `roles.get` |
+| `role:manage` | `roles.create` / `roles.update` / `roles.assign` / `roles.delete` |
+| `payment:read` | `payment.list` — 결제 내역 |
+| `publickey:read` | `publicKey.getPublicKeys` |
+| `publickey:manage` | `publicKey.createPublicKey` / `updatePublicKey` / `deletePublicKey` |
+| `push:read` | `push.getStats` |
+
+시크릿 키(`cb_sk_`)는 이 경로에 등장하지 않는다 — 함수가 service-role 토큰으로 키 없이 호출하고, 토큰은 클러스터를 벗어나지 않는다. `cb_sk_` 단독으로 관리 API 를 호출하면 401 이다.
+
+```typescript
+// 함수 안에서 (service_role: true, management_scopes: ["app_member:read"])
+export async function handler(payload, ctx) {
+  if (!ctx.cbAdmin) throw new Error('service_role not enabled')
+
+  // 문의로 들어온 이메일이 어느 회원인지 대조 (닉네임·이메일·로그인 identity 부분 일치)
+  const found = await ctx.cbAdmin.appMembers.list(ctx.appId, { search: payload.email })
+  if (found.total_count === 0) return { matched: false }
+
+  // 회원 상세 — 로그인 수단까지
+  const member = await ctx.cbAdmin.appMembers.get(ctx.appId, found.app_members[0].id)
+  return {
+    matched: true,
+    memberId: member.id,
+    email: member.email,
+    providers: member.identities.map((i) => i.type),  // ['GOOGLE']
+  }
+}
+```
+
+`appMembers.list` 의 `email` 은 `app_members.email` 컬럼이 우선이고, 비어 있으면 `EMAIL` identity 의 `provider_uid` 로 fallback 한다. 소셜 제공자가 이메일을 주지 않은 회원은 빈 문자열이다. `total_count` 는 `search` 필터를 반영하므로 페이지네이션에 그대로 쓸 수 있다.
+
+**멤버가 자기 정보를 볼 때는 `cb.auth.getMe()` 를 쓴다.** `appMembers.*` 는 운영자 방향 조회 전용이고, 멤버 쓰기(생성·삭제·정지·수정)는 콘솔 전용이라 `app_member:read` 로 열리지 않는다.
+
+```typescript
+// 역할(RBAC) 관리 — management_scopes: ["role:read", "role:manage"]
+const roles = await ctx.cbAdmin.roles.list(ctx.appId)
+const { id } = await ctx.cbAdmin.roles.create(ctx.appId, {
+  title: '읽기전용 운영자',
+  description: '조회만',
+})
+// assign 은 "이 역할을 가질 사용자 전체" 로 동기화한다 (추가가 아님)
+await ctx.cbAdmin.roles.assign(ctx.appId, id, ['user-uuid-1', 'user-uuid-2'])
+
+// Public Key 관리 — management_scopes: ["publickey:read", "publickey:manage"]
+// payment_mode 로 키마다 결제 자격증명 모드를 고정할 수 있다 (QA 빌드에 test 키)
+const created = await ctx.cbAdmin.publicKey.createPublicKey(ctx.appId, {
+  name: 'QA',
+  payment_mode: 'test',
+})
+console.log(created.key)  // 전체 키값은 이때만 볼 수 있다
+
+// 결제 내역 — management_scopes: ["payment:read"]
+const payments = await ctx.cbAdmin.payment.list(ctx.appId, { status: 'paid', limit: 50 })
+
+// 푸시 통계 — management_scopes: ["push:read"]
+const stats = await ctx.cbAdmin.push.getStats(ctx.appId)
+```
+
+콘솔 JWT 로 브라우저/서버에서 직접 호출할 때는 같은 메서드를 `cb.appMembers.*`, `cb.roles.*`, `cb.publicKey.*` 로 쓴다 (스코프 대신 콘솔 RBAC 권한이 적용된다).
+
 ## Types
 
 ### GameState

package/package.json

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