connectbase-client 5.1.0 → 5.2.0

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/dist/index.d.mts

@@ -5511,6 +5511,29 @@ interface PreparePaymentRequest {
      * 상품별로 세금 카테고리를 달리 할 때만 지정한다. Paddle 은 무시한다.
      */
     provider_price_ref?: string;
+    /**
+     * 이 결제에 미리 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드(Dodo Discounts / Paddle Discounts)에서 발행한다 — ConnectBase 는 코드를
+     * 전달만 하고 발행/한도/유효기간은 PG 설정이 권위다. Paddle 은 API 가 코드 대신 내부 ID 를
+     * 받으므로 서버가 코드를 조회해 해소한다.
+     *
+     * 실패는 조용히 정가로 넘어가지 않고 400 으로 거절된다:
+     * - `discount_code_invalid` — 없거나 만료/비활성 코드
+     * - `discount_code_unsupported` — 할인 코드를 지원하지 않는 프로바이더(toss/stripe/payapp/paypal)
+     *
+     * 할인이 적용되면 확정 응답의 `amount` 는 **실제 청구액**(할인 후)이고 차감분은
+     * `discount_amount` 로 온다.
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 **고객이 직접** 쿠폰을 입력하도록 허용할지(선택).
+     *
+     * 미지정이면 프로바이더 기본값을 따른다. Dodo 는 결제창마다 켜고 끌 수 있다.
+     * Paddle 오버레이는 입력칸을 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     amount: number;
     order_name: string;
     order_id?: string;
@@ -5573,7 +5596,10 @@ interface ConfirmPaymentRequest {
 interface ConfirmPaymentResponse {
     payment_id: string;
     order_id: string;
+    /** **실제 청구된** 금액. 할인이 적용되면 준비 금액보다 작다. */
     amount: number;
+    /** 할인으로 차감된 금액(준비 금액 − 실제 청구액). 할인이 없으면 생략된다. */
+    discount_amount?: number;
     status: PaymentStatus;
     method: string;
     receipt_url?: string;
@@ -5610,6 +5636,13 @@ interface PaymentDetail {
     settlement_currency?: string;
     /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
     country?: string;
+    /** 적용된 할인 코드 (준비 시 지정한 경우). */
+    discount_code?: string;
+    /**
+     * 할인으로 차감된 금액. `amount` 는 이미 할인이 반영된 실제 청구액이므로,
+     * 정가를 표시하려면 `amount + discount_amount` 로 복원한다.
+     */
+    discount_amount?: number;
     status: PaymentStatus;
     payment_provider?: PaymentProvider;
     /** 이 결제가 사용한 자격증명 모드 (test | live). */
@@ -5719,10 +5752,23 @@ declare class PaymentAPI {
      * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
      *   window.location.href = result.payapp_pay_url
      * }
+     *
+     * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+     * const discounted = await cb.payment.prepare({
+     *   amount: 10000,
+     *   order_name: '프리미엄 1개월',
+     *   discount_code: 'LAUNCH50',   // 미리 적용
+     *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+     * })
+     * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+     * // discount_amount 는 차감분이다.
      * ```
      *
      * @remarks
      * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+     *
+     * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+     * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -7687,8 +7733,31 @@ interface CreateSubscriptionRequest {
     billing_cycle: BillingCycle;
     /** 결제일 (monthly: 1-28일, weekly: 0-6 요일) */
     billing_day?: number;
-    /** 트라이얼 기간 (일) */
+    /**
+     * 트라이얼(무료 체험) 기간 (일).
+     *
+     * 빌링키 모델(toss/stripe)에서는 ConnectBase 스케줄러가 체험 종료일에 첫 청구를 건다.
+     * MoR 은 PG 가 정기청구를 소유하므로 결제창 생성 시 체험 일수를 함께 보낸다:
+     * - **Dodo**: 구독마다 지정 가능(0~10000일)
+     * - **Paddle**: 트라이얼이 요금제(price)에 붙는 속성이라 구독마다 지정할 수 없다 →
+     *   400 `trial_days_unsupported`. 체험이 설정된 price 를 Paddle 대시보드에서 따로 만들어 쓴다.
+     */
     trial_days?: number;
+    /**
+     * 첫 결제에 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드에서 발행하며, 몇 주기까지 할인할지도 그쪽 설정이 정한다
+     * (예: Dodo `subscription_cycles` 로 "3개월간 50%"). ConnectBase 는 코드만 전달한다.
+     *
+     * 400 `discount_code_invalid`(없거나 만료) / `discount_code_unsupported`(미지원 프로바이더).
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 고객이 직접 쿠폰을 입력하도록 허용할지(선택).
+     * Paddle 오버레이는 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     /** 고객 이메일 */
     customer_email?: string;
     /** 고객 이름 */
@@ -8124,7 +8193,27 @@ declare class SubscriptionAPI {
      *     billing_day: 15,  // 매월 15일 결제
      *     trial_days: 7     // 7일 무료 체험
      * })
+     *
+     * // MoR(dodo/paddle) 구독 + 할인 코드
+     * const promo = await client.subscription.create({
+     *     plan_name: '프리미엄 플랜',
+     *     amount: 9900,
+     *     billing_cycle: 'monthly',
+     *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+     *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+     *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+     * })
      * ```
+     *
+     * @remarks
+     * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+     * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+     * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+     *   체험은 요금제(price) 속성이라 구독별 지정 불가
+     * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+     *
+     * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+     * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
      */
     create(data: CreateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**

package/dist/index.d.ts

@@ -5511,6 +5511,29 @@ interface PreparePaymentRequest {
      * 상품별로 세금 카테고리를 달리 할 때만 지정한다. Paddle 은 무시한다.
      */
     provider_price_ref?: string;
+    /**
+     * 이 결제에 미리 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드(Dodo Discounts / Paddle Discounts)에서 발행한다 — ConnectBase 는 코드를
+     * 전달만 하고 발행/한도/유효기간은 PG 설정이 권위다. Paddle 은 API 가 코드 대신 내부 ID 를
+     * 받으므로 서버가 코드를 조회해 해소한다.
+     *
+     * 실패는 조용히 정가로 넘어가지 않고 400 으로 거절된다:
+     * - `discount_code_invalid` — 없거나 만료/비활성 코드
+     * - `discount_code_unsupported` — 할인 코드를 지원하지 않는 프로바이더(toss/stripe/payapp/paypal)
+     *
+     * 할인이 적용되면 확정 응답의 `amount` 는 **실제 청구액**(할인 후)이고 차감분은
+     * `discount_amount` 로 온다.
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 **고객이 직접** 쿠폰을 입력하도록 허용할지(선택).
+     *
+     * 미지정이면 프로바이더 기본값을 따른다. Dodo 는 결제창마다 켜고 끌 수 있다.
+     * Paddle 오버레이는 입력칸을 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     amount: number;
     order_name: string;
     order_id?: string;
@@ -5573,7 +5596,10 @@ interface ConfirmPaymentRequest {
 interface ConfirmPaymentResponse {
     payment_id: string;
     order_id: string;
+    /** **실제 청구된** 금액. 할인이 적용되면 준비 금액보다 작다. */
     amount: number;
+    /** 할인으로 차감된 금액(준비 금액 − 실제 청구액). 할인이 없으면 생략된다. */
+    discount_amount?: number;
     status: PaymentStatus;
     method: string;
     receipt_url?: string;
@@ -5610,6 +5636,13 @@ interface PaymentDetail {
     settlement_currency?: string;
     /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
     country?: string;
+    /** 적용된 할인 코드 (준비 시 지정한 경우). */
+    discount_code?: string;
+    /**
+     * 할인으로 차감된 금액. `amount` 는 이미 할인이 반영된 실제 청구액이므로,
+     * 정가를 표시하려면 `amount + discount_amount` 로 복원한다.
+     */
+    discount_amount?: number;
     status: PaymentStatus;
     payment_provider?: PaymentProvider;
     /** 이 결제가 사용한 자격증명 모드 (test | live). */
@@ -5719,10 +5752,23 @@ declare class PaymentAPI {
      * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
      *   window.location.href = result.payapp_pay_url
      * }
+     *
+     * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+     * const discounted = await cb.payment.prepare({
+     *   amount: 10000,
+     *   order_name: '프리미엄 1개월',
+     *   discount_code: 'LAUNCH50',   // 미리 적용
+     *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+     * })
+     * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+     * // discount_amount 는 차감분이다.
      * ```
      *
      * @remarks
      * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+     *
+     * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+     * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -7687,8 +7733,31 @@ interface CreateSubscriptionRequest {
     billing_cycle: BillingCycle;
     /** 결제일 (monthly: 1-28일, weekly: 0-6 요일) */
     billing_day?: number;
-    /** 트라이얼 기간 (일) */
+    /**
+     * 트라이얼(무료 체험) 기간 (일).
+     *
+     * 빌링키 모델(toss/stripe)에서는 ConnectBase 스케줄러가 체험 종료일에 첫 청구를 건다.
+     * MoR 은 PG 가 정기청구를 소유하므로 결제창 생성 시 체험 일수를 함께 보낸다:
+     * - **Dodo**: 구독마다 지정 가능(0~10000일)
+     * - **Paddle**: 트라이얼이 요금제(price)에 붙는 속성이라 구독마다 지정할 수 없다 →
+     *   400 `trial_days_unsupported`. 체험이 설정된 price 를 Paddle 대시보드에서 따로 만들어 쓴다.
+     */
     trial_days?: number;
+    /**
+     * 첫 결제에 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드에서 발행하며, 몇 주기까지 할인할지도 그쪽 설정이 정한다
+     * (예: Dodo `subscription_cycles` 로 "3개월간 50%"). ConnectBase 는 코드만 전달한다.
+     *
+     * 400 `discount_code_invalid`(없거나 만료) / `discount_code_unsupported`(미지원 프로바이더).
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 고객이 직접 쿠폰을 입력하도록 허용할지(선택).
+     * Paddle 오버레이는 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     /** 고객 이메일 */
     customer_email?: string;
     /** 고객 이름 */
@@ -8124,7 +8193,27 @@ declare class SubscriptionAPI {
      *     billing_day: 15,  // 매월 15일 결제
      *     trial_days: 7     // 7일 무료 체험
      * })
+     *
+     * // MoR(dodo/paddle) 구독 + 할인 코드
+     * const promo = await client.subscription.create({
+     *     plan_name: '프리미엄 플랜',
+     *     amount: 9900,
+     *     billing_cycle: 'monthly',
+     *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+     *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+     *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+     * })
      * ```
+     *
+     * @remarks
+     * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+     * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+     * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+     *   체험은 요금제(price) 속성이라 구독별 지정 불가
+     * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+     *
+     * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+     * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
      */
     create(data: CreateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**

package/dist/index.js

@@ -6138,10 +6138,23 @@ var PaymentAPI = class {
    * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
    *   window.location.href = result.payapp_pay_url
    * }
+   *
+   * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+   * const discounted = await cb.payment.prepare({
+   *   amount: 10000,
+   *   order_name: '프리미엄 1개월',
+   *   discount_code: 'LAUNCH50',   // 미리 적용
+   *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+   * })
+   * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+   * // discount_amount 는 차감분이다.
    * ```
    *
    * @remarks
    * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+   *
+   * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+   * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
    */
   async prepare(data) {
     const prefix = this.getPublicPrefix();
@@ -9023,7 +9036,27 @@ var SubscriptionAPI = class {
    *     billing_day: 15,  // 매월 15일 결제
    *     trial_days: 7     // 7일 무료 체험
    * })
+   *
+   * // MoR(dodo/paddle) 구독 + 할인 코드
+   * const promo = await client.subscription.create({
+   *     plan_name: '프리미엄 플랜',
+   *     amount: 9900,
+   *     billing_cycle: 'monthly',
+   *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+   *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+   *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+   * })
    * ```
+   *
+   * @remarks
+   * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+   * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+   * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+   *   체험은 요금제(price) 속성이라 구독별 지정 불가
+   * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+   *
+   * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+   * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
    */
   async create(data) {
     const prefix = this.getPublicPrefix();

package/dist/index.mjs

@@ -6089,10 +6089,23 @@ var PaymentAPI = class {
    * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
    *   window.location.href = result.payapp_pay_url
    * }
+   *
+   * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+   * const discounted = await cb.payment.prepare({
+   *   amount: 10000,
+   *   order_name: '프리미엄 1개월',
+   *   discount_code: 'LAUNCH50',   // 미리 적용
+   *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+   * })
+   * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+   * // discount_amount 는 차감분이다.
    * ```
    *
    * @remarks
    * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+   *
+   * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+   * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
    */
   async prepare(data) {
     const prefix = this.getPublicPrefix();
@@ -8974,7 +8987,27 @@ var SubscriptionAPI = class {
    *     billing_day: 15,  // 매월 15일 결제
    *     trial_days: 7     // 7일 무료 체험
    * })
+   *
+   * // MoR(dodo/paddle) 구독 + 할인 코드
+   * const promo = await client.subscription.create({
+   *     plan_name: '프리미엄 플랜',
+   *     amount: 9900,
+   *     billing_cycle: 'monthly',
+   *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+   *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+   *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+   * })
    * ```
+   *
+   * @remarks
+   * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+   * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+   * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+   *   체험은 요금제(price) 속성이라 구독별 지정 불가
+   * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+   *
+   * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+   * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
    */
   async create(data) {
     const prefix = this.getPublicPrefix();

package/package.json

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