connectbase-client 4.1.0 → 4.3.0

package/dist/index.d.ts

@@ -4440,6 +4440,27 @@ declare global {
 }
 interface NativeBridgeInterface {
     platform?: "electron" | "react-native" | "ios" | "android";
+    /** 실행 OS (react-native: 'ios' | 'android', electron: process.platform) */
+    os?: string;
+    /** 네이티브 셸에서 실행 중인지 (패키징 앱이면 항상 true) */
+    isNative?: boolean;
+    /** 브릿지 원시 호출 (문서화되지 않은 타입 호출용) */
+    call?: (type: string, payload?: unknown, options?: {
+        timeoutMs?: number;
+    }) => Promise<unknown>;
+    app?: {
+        getVersion?: () => Promise<string>;
+        getName?: () => Promise<string>;
+        getInfo?: () => Promise<NativeAppInfo>;
+        getPath?: (name: string) => Promise<string | null>;
+        reload?: () => Promise<void>;
+        quit?: () => Promise<void>;
+    };
+    browser?: {
+        openExternal: (url: string) => Promise<{
+            success: boolean;
+        }>;
+    };
     camera?: {
         takePicture: (options?: CameraOptions) => Promise<ImageResult>;
         pickImage: (options?: PickImageOptions) => Promise<ImageResult[]>;
@@ -4455,6 +4476,9 @@ interface NativeBridgeInterface {
         scheduleLocal: (options: LocalNotificationOptions) => Promise<{
             notificationId: string;
         }>;
+        setBadgeCount?: (count: number) => Promise<{
+            success: boolean;
+        }>;
     };
     speech?: {
         recognize: (options?: SpeechRecognizeOptions) => Promise<SpeechResult>;
@@ -4497,12 +4521,6 @@ interface NativeBridgeInterface {
             rewarded: boolean;
         }>;
     };
-    app?: {
-        getVersion: () => Promise<string>;
-        getName: () => Promise<string>;
-        getPath: (name: string) => Promise<string | null>;
-        quit: () => Promise<void>;
-    };
     system?: {
         getInfo: () => Promise<SystemInfo>;
         getMemory: () => Promise<MemoryInfo>;
@@ -4592,10 +4610,34 @@ interface NativeBridgeInterface {
         saveToGallery?: (uri: string) => Promise<{
             uri: string;
         }>;
+        /** 모바일: 앱 문서/캐시 디렉터리 URI */
+        getDirectories?: () => Promise<{
+            document: string | null;
+            cache: string | null;
+        }>;
+        /** 데스크톱: 접근이 허용된 앱 전용 데이터 폴더 */
+        getAppDir?: () => Promise<string>;
     };
     onDeepLink?: (callback: (url: string) => void) => () => void;
 }
 type Platform = "web" | "mobile" | "desktop";
+/** 패키징 앱 정보 (`cb.native.getAppInfo()`) */
+interface NativeAppInfo {
+    platform: string;
+    os?: string;
+    osVersion?: string;
+    arch?: string;
+    appVersion?: string;
+    electronVersion?: string;
+    webUrl?: string;
+}
+/** 위치 추적 핸들 (`cb.native.location.watchPosition()`) */
+interface LocationWatch {
+    /** 네이티브 watch 식별자 (웹 폴백에서는 geolocation watch id) */
+    watchId: string;
+    /** 추적 중지 */
+    clear: () => Promise<void>;
+}
 interface CameraOptions {
     quality?: number;
     base64?: boolean;
@@ -4748,6 +4790,20 @@ declare class NativeAPI {
      * 현재 플랫폼 감지
      */
     getPlatform(): Platform;
+    /**
+     * 패키징 앱(네이티브 셸) 안에서 실행 중인지
+     */
+    isNativeApp(): boolean;
+    /**
+     * 패키징 앱 정보 조회 (웹에서는 null)
+     *
+     * @example
+     * ```typescript
+     * const info = await cb.native.getAppInfo()
+     * // { platform: 'react-native', os: 'ios', appVersion: '1.0.0', webUrl: '...' }
+     * ```
+     */
+    getAppInfo(): Promise<NativeAppInfo | null>;
     /**
      * 특정 네이티브 기능 지원 여부 확인
      */
@@ -4835,6 +4891,42 @@ declare class NativeAPI {
          * 현재 위치 가져오기
          */
         getCurrentPosition: (options?: LocationOptions) => Promise<Position>;
+        /**
+         * 위치 추적 시작.
+         *
+         * 패키징 앱(모바일)에서는 네이티브가 `nativeLocationUpdate` 이벤트로 갱신을 보내고,
+         * 웹/데스크톱에서는 Geolocation `watchPosition` 을 사용한다.
+         *
+         * @example
+         * ```typescript
+         * const watch = await cb.native.location.watchPosition((pos) => console.log(pos))
+         * // 나중에
+         * await watch.clear()
+         * ```
+         */
+        watchPosition: (onUpdate: (position: Position) => void, options?: LocationOptions) => Promise<LocationWatch>;
+    };
+    /**
+     * 모바일 전용 푸시 API
+     *
+     * 패키징 앱은 raw 디바이스 토큰(iOS=APNS, Android=FCM)을 발급받아
+     * `cb.push.registerDevice()` 로 등록해야 서버 발송이 가능하다.
+     */
+    push: {
+        /**
+         * 네이티브 디바이스 푸시 토큰 조회.
+         * 웹(패키징 앱이 아닌 경우)에서는 null 을 반환한다.
+         */
+        getToken: () => Promise<{
+            token: string;
+            platform?: string;
+        } | null>;
+        /** 알림 권한 요청 (웹은 Web Notification 권한) */
+        requestPermission: () => Promise<boolean>;
+        /** 로컬 알림 예약 (패키징 앱 전용) */
+        scheduleLocal: (options: LocalNotificationOptions) => Promise<string | null>;
+        /** 앱 아이콘 배지 숫자 설정 (미지원 플랫폼에서는 무시) */
+        setBadgeCount: (count: number) => Promise<boolean>;
     };
     /**
      * 크로스 플랫폼 알림 API
@@ -5183,11 +5275,15 @@ type PaymentStatus = "pending" | "ready" | "in_progress" | "done" | "canceled" |
 interface PreparePaymentRequest {
     payment_provider?: PaymentProvider;
     /**
-     * 사용할 자격증명 모드 오버라이드(선택). 미지정 시 콘솔의 프로바이더 모드를 따른다.
+     * 사용할 자격증명 모드 오버라이드(선택).
      *
      * **서버에서 시크릿 키(`cb_sk_*`)로 호출할 때만 적용된다.** 브라우저에 실리는 공개 키
      * (`cb_pk_*`) 호출에서는 무시된다 — 클라이언트가 test 를 골라 실제 돈 없이 "결제 성공"을
      * 만들 수 있으면 결제 성공에 걸린 권한 부여가 통째로 우회되기 때문이다.
+     *
+     * 모드 결정 우선순위: 이 오버라이드 → **퍼블릭 키에 고정된 모드**(콘솔에서 키마다 지정) →
+     * 콘솔의 프로바이더 모드 → test. 브라우저 앱에서 QA/프로덕션 결제를 나누려면 이 필드가 아니라
+     * 키 단위 `payment_mode` 를 쓴다(`cb.publicKey` 참조).
      */
     payment_mode?: PaymentMode;
     /**
@@ -5282,8 +5378,21 @@ interface PaymentDetail {
     payment_id: string;
     order_id: string;
     order_name: string;
+    /** 고객이 실제 청구받은 금액 — `currency` 기준 최소단위 */
     amount: number;
+    /** `amount` 의 통화 (ISO 4217) */
     currency: string;
+    /**
+     * 정산통화 환산액 (MoR 프로바이더가 제공할 때만).
+     *
+     * Paddle/Dodo 는 고객에게 표시통화로 청구하고 머천트에게는 환산된 정산통화로 지급한다.
+     * 실제 입금액 대사에 쓰고, **고객에게 보여줄 금액은 언제나 `amount`/`currency`** 다.
+     */
+    settlement_amount?: number;
+    /** `settlement_amount` 의 통화 (ISO 4217) */
+    settlement_currency?: string;
+    /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
+    country?: string;
     status: PaymentStatus;
     payment_provider?: PaymentProvider;
     /** 이 결제가 사용한 자격증명 모드 (test | live). */
@@ -5322,7 +5431,10 @@ interface PaymentListItem {
     payment_id: string;
     order_id: string;
     order_name: string;
+    /** 고객이 실제 청구받은 금액 — `currency` 기준 최소단위 */
     amount: number;
+    /** `amount` 의 통화 (ISO 4217). 다통화 결제에서 앱 기본 통화를 가정하면 거짓 금액이 된다 */
+    currency: string;
     status: PaymentStatus;
     method?: string;
     /** toss | stripe 등 */
@@ -5499,6 +5611,22 @@ declare class PaymentAPI {
 /**
  * Public Key 관련 타입 정의
  */
+/**
+ * 이 키로 들어온 결제가 쓸 자격증명 모드.
+ *
+ * - `inherit`(기본): 앱 결제 설정의 프로바이더 모드를 따른다.
+ * - `test`: 이 키의 결제는 항상 테스트 키로 처리된다.
+ * - `live`: 이 키의 결제는 항상 라이브 키로 처리된다.
+ *
+ * 앱 하나로 QA 빌드와 프로덕션 빌드를 함께 운영할 때 쓴다 — QA 빌드에 `test` 키를 심으면
+ * 앱 설정이 라이브여도 그 키의 결제만 테스트로 처리되므로, 라이브 전환 이후에도 안전하게
+ * 결제 회귀 테스트를 할 수 있다.
+ *
+ * 모드를 정하는 주체가 **서버에 저장된 키 설정**이라 클라이언트는 고를 수 없다. QA 키가
+ * 유출돼도 만들 수 있는 건 테스트 결제뿐이다(권한 지급 로직이 결제의 `payment_mode` 를 함께
+ * 검사하도록 만드는 것을 권장한다).
+ */
+type PublicKeyPaymentMode = "inherit" | "test" | "live";
 /**
  * Public Key 아이템
  */
@@ -5511,6 +5639,8 @@ interface PublicKeyItem {
     key_prefix: string;
     /** 활성화 상태 */
     is_active: boolean;
+    /** 이 키로 들어온 결제의 자격증명 모드 */
+    payment_mode: PublicKeyPaymentMode;
     /** 마지막 사용 시간 */
     last_used_at?: string;
     /** 만료일 (null이면 무제한) */
@@ -5524,6 +5654,8 @@ interface PublicKeyItem {
 interface CreatePublicKeyRequest {
     /** Public Key 이름 (예: Production, Development) */
     name: string;
+    /** 이 키로 들어온 결제의 자격증명 모드 (기본: inherit) */
+    payment_mode?: PublicKeyPaymentMode;
     /** 만료일 (옵션) */
     expires_at?: string;
 }
@@ -5541,6 +5673,8 @@ interface CreatePublicKeyResponse {
     key_prefix: string;
     /** 활성화 상태 */
     is_active: boolean;
+    /** 이 키로 들어온 결제의 자격증명 모드 */
+    payment_mode: PublicKeyPaymentMode;
     /** 만료일 */
     expires_at?: string;
     /** 생성일 */
@@ -5560,6 +5694,8 @@ interface UpdatePublicKeyRequest {
     name?: string;
     /** 활성화/비활성화 */
     is_active?: boolean;
+    /** 이 키로 들어온 결제의 자격증명 모드 변경 */
+    payment_mode?: PublicKeyPaymentMode;
 }
 /**
  * Public Key 수정 응답
@@ -5569,6 +5705,7 @@ interface UpdatePublicKeyResponse {
     name: string;
     key_prefix: string;
     is_active: boolean;
+    payment_mode: PublicKeyPaymentMode;
     expires_at?: string;
     created_at: string;
 }
@@ -7318,8 +7455,19 @@ interface CreateSubscriptionRequest {
     customer_phone?: string;
     /** payapp 정기결제 만료일 yyyy-mm-dd (미입력시 +10년) */
     expire_date?: string;
-    /** paddle 필수: Paddle 카탈로그의 recurring price ID (pri_*) */
+    /** MoR 필수: PG 카탈로그의 recurring price/product ref (Paddle `pri_*` / Dodo `pdt_*`) */
     provider_price_ref?: string;
+    /**
+     * 사용할 자격증명 모드 오버라이드 (test|live). 단건결제 `prepare()` 의 `payment_mode` 와
+     * 적용 조건이 **완전히 동일**하다 — 서버 시크릿 키(`cb_sk_*`)로 승격된 호출에서만 적용되고,
+     * 브라우저 공개 키(`cb_pk_*`) 호출에서는 무시된다.
+     *
+     * 모드 결정 우선순위: 이 오버라이드 → 퍼블릭 키에 고정된 모드 → 앱 결제 설정의 프로바이더 모드
+     * → test. 브라우저 앱에서 QA/프로덕션을 나누려면 이 필드가 아니라 키 단위 모드를 쓴다.
+     *
+     * 구독은 생성 시점 모드가 고정되므로 이후 갱신 청구·해지도 같은 키로 처리된다.
+     */
+    payment_mode?: "test" | "live";
     /** 메타데이터 */
     metadata?: Record<string, unknown>;
 }
@@ -7349,10 +7497,26 @@ interface SubscriptionResponse {
     plan_name: string;
     /** 플랜 설명 */
     plan_description: string;
-    /** 결제 금액 */
+    /**
+     * 이 구독이 고정한 자격증명 모드 (test=테스트 키 | live=실결제).
+     *
+     * 생성 시점 값이 박히므로 이후 앱 모드를 바꿔도 갱신 청구는 원래 키로 처리된다.
+     * **프로바이더 중립 필드**라 목록에서 테스트 구독과 실구독을 가르는 데 이 필드를 쓴다
+     * (`environment` 는 Paddle 의 sandbox|production 이라 다른 프로바이더에서는 기대할 수 없다).
+     */
+    payment_mode?: "test" | "live";
+    /**
+     * 정기 청구 단가 (`currency` 기준 최소단위).
+     *
+     * MoR(Paddle/Dodo)은 상품 통화와 고객 표시통화가 다를 수 있으므로(adaptive currency),
+     * 이 값을 해석할 때는 반드시 `currency` 를 함께 봐야 한다. 앱의 기본 통화를 가정하면
+     * 거짓 금액이 된다(예: $10.10 을 ₩1,010 으로 표기).
+     */
     amount: number;
-    /** 통화 */
+    /** `amount` 의 통화 (ISO 4217) */
     currency: string;
+    /** 청구 국가 ISO 3166-1 alpha-2 (MoR 프로바이더가 제공할 때만) */
+    country?: string;
     /** 결제 주기 */
     billing_cycle: BillingCycle;
     /** 결제일 */
@@ -7373,7 +7537,10 @@ interface SubscriptionResponse {
     ended_at: string | null;
     /** 트라이얼 종료일 */
     trial_end_at: string | null;
-    /** 총 결제 금액 */
+    /**
+     * 총 결제 금액 — 결제 이력 금액의 합이며 **각 결제의 표시통화** 기준이다.
+     * 위 `currency` 와 다를 수 있으므로, 통화별 정확한 집계는 결제 이력의 `currency` 로 그룹핑할 것.
+     */
     total_paid: number;
     /** 결제 횟수 */
     payment_count: number;
@@ -7421,7 +7588,23 @@ interface CancelSubscriptionRequest {
  * - `full_next_billing_period`: 새 플랜 전액을 다음 청구일에 부과.
  * - `do_not_bill`: 전환만 하고 청구하지 않음.
  */
-type ProrationMode = "prorated_immediately" | "prorated_next_billing_period" | "full_immediately" | "full_next_billing_period" | "do_not_bill";
+/**
+ * 요금제 스왑 시 남은 금액 정산 방식.
+ *
+ * **프로바이더별 지원 범위가 다르다.** 미지원 값은 근사 대체 없이 400
+ * `invalid_proration_mode` 로 거절된다 — "다음 청구일에 부과"를 조용히 "지금 청구"로 바꾸면
+ * 요청하지 않은 즉시 출금이 발생하기 때문이다.
+ *
+ * | 값 | Paddle | Dodo |
+ * | --- | --- | --- |
+ * | `prorated_immediately` (기본) | ✅ | ✅ |
+ * | `full_immediately` | ✅ | ✅ |
+ * | `do_not_bill` | ✅ | ✅ |
+ * | `prorated_next_billing_period` | ✅ | ❌ |
+ * | `full_next_billing_period` | ✅ | ❌ |
+ * | `difference_immediately` | ❌ | ✅ |
+ */
+type ProrationMode = "prorated_immediately" | "prorated_next_billing_period" | "full_immediately" | "full_next_billing_period" | "difference_immediately" | "do_not_bill";
 /**
  * 즉시청구(prorated/full_immediately) 실패 시 플랜 변경을 적용할지.
  *
@@ -7430,19 +7613,22 @@ type ProrationMode = "prorated_immediately" | "prorated_next_billing_period" | "
  */
 type OnPaymentFailure = "prevent_change" | "apply_change";
 /**
- * 요금제 스왑(플랜 변경) 요청 — Paddle(MoR) 구독 전용.
+ * 요금제 스왑(플랜 변경) 요청 — MoR(Paddle/Dodo) 구독 전용.
  *
- * 하나의 구독을 유지한 채(id 동일) 다른 recurring price 로 갈아타고 남은 금액을 Paddle proration 으로
- * 정산한다. 예) 혼자→가족 in-place 업그레이드.
+ * 하나의 구독을 유지한 채(id 동일) 다른 recurring price/product 로 갈아타고 남은 금액을 PG 의
+ * proration 으로 정산한다. 예) 혼자→가족 in-place 업그레이드.
+ *
+ * toss/stripe/payapp/paypal 구독은 PG 네이티브 proration 이 없어 400
+ * `plan_change_unsupported` 다.
  */
 interface ChangePlanRequest {
-    /** 새 recurring price ID (pri_*) — 필수 */
+    /** 새 recurring price/product ref (Paddle `pri_*` / Dodo `pdt_*`) — 필수 */
     provider_price_ref: string;
     /** 우리 표시용 플랜명 (선택) */
     plan_name?: string;
     /** 우리 표시용 플랜 설명 (선택) */
     plan_description?: string;
-    /** 우리 기록용 정기 금액 (선택 — 미지정 시 Paddle 값으로 자동 수렴) */
+    /** 우리 기록용 정기 금액 (선택 — 미지정 시 PG 값으로 자동 수렴) */
     amount?: number;
     /** 정산 방식 (기본: prorated_immediately) */
     proration_mode?: ProrationMode;
@@ -7454,8 +7640,12 @@ interface ChangePlanRequest {
 /**
  * 요금제 스왑 미리보기 응답 — 실제 적용 없이 정산 결과만 계산.
  *
- * `immediate_charge_amount` 는 세금·기존 크레딧 잔액까지 반영된 Paddle 계산값(권위)이다.
- * 확정 화면에 "지금 ₩X 청구, 이후 ₩Y/주기" 로 그대로 노출한다.
+ * `immediate_charge_amount` 는 세금·기존 크레딧 잔액까지 반영된 PG 계산값(권위)이다.
+ * 확정 화면에 "지금 ₩X 청구, 이후 ₩Y/주기" 로 그대로 노출한다(직접 차액을 계산하지 말 것).
+ *
+ * **통화가 둘인 이유**: 즉시청구는 고객 표시통화로, 정기 단가는 상품 통화로 계산된다. MoR 의
+ * adaptive currency 에서 이 둘이 다를 수 있어 각각 통화를 싣는다. 금액을 표시할 때는 반드시
+ * 짝이 되는 통화 필드를 함께 써야 한다 — 하나의 통화로 뭉치면 확정 직전 화면에 거짓 금액이 뜬다.
  */
 interface ChangePlanPreview {
     /** 적용된 정산 모드 */
@@ -7464,13 +7654,19 @@ interface ChangePlanPreview {
     immediate_charge_action?: "charge" | "credit";
     /** 지금 순액(minor). 청구=양수, 크레딧=음수 */
     immediate_charge_amount: number;
+    /** `immediate_charge_amount` 의 통화 (ISO 4217) */
+    currency: string;
     /** 새 플랜의 다음 정기 청구액(minor) */
     recurring_amount: number;
-    /** 통화 (ISO 4217) */
-    currency: string;
+    /** `recurring_amount` 의 통화. 비어 있으면 `currency` 와 동일 */
+    recurring_currency?: string;
+    /** 즉시청구의 정산통화 환산액 (MoR 제공 시) — 매출 대사용, 고객 표시에는 쓰지 말 것 */
+    settlement_amount?: number;
+    /** `settlement_amount` 의 통화 */
+    settlement_currency?: string;
     /** 다음 청구 예정일 */
     next_billed_at?: string | null;
-    /** 미리보기가 반영한 새 price ID */
+    /** 미리보기가 반영한 새 price/product ref */
     new_provider_price_ref?: string;
 }
 interface ListSubscriptionsRequest {
@@ -7493,14 +7689,22 @@ interface SubscriptionPaymentResponse {
     id: string;
     /** 구독 ID */
     subscription_id: string;
+    /** 이 청구를 처리한 결제 프로바이더 */
+    provider?: string;
     /** 토스 결제 키 */
     payment_key: string;
     /** 주문 ID */
     order_id: string;
-    /** 결제 금액 */
+    /** 결제 금액 — 고객이 실제 청구받은 **표시통화** 기준 */
     amount: number;
-    /** 통화 */
+    /** `amount` 의 통화 (ISO 4217) */
     currency: string;
+    /** 정산통화 환산액 (MoR 제공 시) — 매출 대사용, 고객 표시에는 쓰지 말 것 */
+    settlement_amount?: number;
+    /** `settlement_amount` 의 통화 */
+    settlement_currency?: string;
+    /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
+    country?: string;
     /** 결제 상태 */
     status: SubscriptionPaymentStatus;
     /** 기간 시작일 */
@@ -7769,14 +7973,19 @@ declare class SubscriptionAPI {
      */
     cancel(subscriptionId: string, data?: CancelSubscriptionRequest): Promise<SubscriptionResponse>;
     /**
-     * 요금제 스왑 (플랜 변경) — Paddle(MoR) 구독 전용
+     * 요금제 스왑 (플랜 변경) — MoR(Paddle · Dodo) 구독 전용
      *
-     * 하나의 구독을 유지한 채(id 동일) 다른 recurring price 로 갈아타고 남은 금액을 Paddle proration 으로
-     * 즉시 정산합니다. 예) 혼자→가족 in-place 업그레이드 — 이미 낸 혼자 미사용분을 Paddle 이 자동 크레딧해
-     * 첫 가족 청구에서 차감합니다. 즉시청구 차액의 결제 확정은 웹훅(SoT)으로 수렴합니다.
+     * 하나의 구독을 유지한 채(id 동일) 다른 recurring price/product 로 갈아타고 남은 금액을 PG 의
+     * proration 으로 즉시 정산합니다. 예) 혼자→가족 in-place 업그레이드 — 이미 낸 혼자 미사용분을
+     * PG 가 자동 크레딧해 첫 가족 청구에서 차감합니다. 즉시청구 차액의 결제 확정은 웹훅(SoT)으로
+     * 수렴합니다.
      *
      * `proration_mode` 미지정 시 `prorated_immediately`(업그레이드 기본)가 적용됩니다.
-     * 확정 전 정산액을 보여주려면 {@link previewChangePlan} 을 먼저 호출하세요.
+     * 프로바이더가 지원하지 않는 정산 모드는 근사 대체 없이 400 `invalid_proration_mode` 입니다
+     * (지원표는 {@link ProrationMode} 참조). 확정 전 정산액을 보여주려면 {@link previewChangePlan}
+     * 을 먼저 호출하세요.
+     *
+     * toss/stripe/payapp/paypal 구독은 400 `plan_change_unsupported` 입니다.
      *
      * @param subscriptionId - 구독 ID
      * @param data - 새 price + 정산 옵션
@@ -7785,7 +7994,7 @@ declare class SubscriptionAPI {
      * @example
      * ```typescript
      * await client.subscription.changePlan(subscriptionId, {
-     *     provider_price_ref: 'pri_family_monthly',
+     *     provider_price_ref: 'pri_family_monthly', // Dodo 는 'pdt_*'
      *     plan_name: '가족 플랜',
      *     amount: 24900,
      *     proration_mode: 'prorated_immediately',
@@ -7794,12 +8003,20 @@ declare class SubscriptionAPI {
      */
     changePlan(subscriptionId: string, data: ChangePlanRequest): Promise<SubscriptionResponse>;
     /**
-     * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (Paddle 전용)
+     * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (Paddle · Dodo)
      *
-     * 세금·기존 크레딧 잔액까지 반영된 Paddle 계산값을 반환하므로, 확정 화면에
+     * 세금·기존 크레딧 잔액까지 반영된 PG 계산값을 반환하므로, 확정 화면에
      * "지금 ₩X 청구, 이후 ₩Y/주기 (다음 청구일 …)" 를 그대로 노출하면 됩니다.
      * 직접 차액을 계산하지 마세요 — 이 값이 권위입니다.
      *
+     * **금액은 반드시 짝이 되는 통화와 함께 표시하세요.** 즉시청구는 고객 표시통화
+     * (`currency`), 정기 단가는 상품 통화(`recurring_currency`, 비면 `currency` 와 동일)입니다 —
+     * MoR 의 adaptive currency 에서 둘이 다를 수 있습니다.
+     *
+     * 미리보기를 제공하지 않는 프로바이더는 400 `plan_change_preview_unsupported` 입니다.
+     * 이는 **미리보기만** 없다는 뜻이며 {@link changePlan} 자체는 동작합니다
+     * (요금제 변경 자체가 불가한 경우는 `plan_change_unsupported` 로 구분됩니다).
+     *
      * @param subscriptionId - 구독 ID
      * @param data - 새 price + 정산 옵션 ({@link changePlan} 과 동일 body)
      * @returns 정산 미리보기 (지금 청구/크레딧 · 새 정기 청구액 · 다음 청구일)
@@ -7809,7 +8026,9 @@ declare class SubscriptionAPI {
      * const preview = await client.subscription.previewChangePlan(subscriptionId, {
      *     provider_price_ref: 'pri_family_monthly',
      * })
-     * // preview.immediate_charge_amount, preview.recurring_amount, preview.next_billed_at
+     * // 통화를 함께 포맷한다 — 금액만 쓰면 다통화에서 거짓 금액이 된다
+     * format(preview.immediate_charge_amount, preview.currency)
+     * format(preview.recurring_amount, preview.recurring_currency ?? preview.currency)
      * ```
      */
     previewChangePlan(subscriptionId: string, data: ChangePlanRequest): Promise<ChangePlanPreview>;
@@ -9546,4 +9765,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { AIAPI, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AgenticSearchProgress, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchOperationResult, type BatchSetPageMetaRequest, type BatchWriteResult, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type ChangePlanPreview, type ChangePlanRequest, type Channel, type ChannelMembership, type ChannelStats, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsentOptions, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateCheckoutSessionRequest, type CreateCheckoutSessionResponse, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateRolePayload, type CreateRoleResult, type CreateRoomResult, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type CreateVideoStorageRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, EndpointAPI, type EndpointCallInit, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchDataResponse, type FetchFilesResponse, type FetchPublicKeysResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConfig, GameConfigAPI, type GameConfigPatch, type GameConnectionState, type GameConnectionStatus, type GameDelta, GameError, type GameErrorCode, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoBoundingBox, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LeaderboardEntry, type LeaderboardListResponse, type LeaderboardScoreEntry, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListPaymentsOptions, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchResult, type MatchmakingTicket, type MatchqueueListResponse, type MatchqueueTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OnPaymentFailure, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentListItem, type PaymentListResult, type PaymentMode, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type PlayerStats, type Playlist, type PlaylistItem, type PollUntilOptions, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type ProrationMode, type PublicKeyItem, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type PushStatsResult, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoleDetail, type RoleList, type RoleListItem, type RolePermissionItem, type RoleUserItem, RolesAPI, type RoomInfo, type RoomStaleMessage, type RoomSummary, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptMeta, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type SendSuperChatOptions, type SendSuperChatResponse, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type SpeechRecognizeOptions, type SpeechResult, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StorageUploadProgress, type StreamContentPart, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamImageURLPart, type StreamMessage, type StreamOptions, type StreamSession, type StreamTextPart, type StreamTokenCallback, type StreamToolCallCallback, type StreamToolResultCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SuperChatType, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionResult, type TransactionWrite, type TransactionWriteResult, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateDocumentRequest, type UpdateLobbyRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateRolePayload, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoCompleteUploadResponse, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageListResponse, type VideoVisibility, type VoiceChannel, type VoiceMember, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported, toCreateRoomWire };
+export { AIAPI, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AgenticSearchProgress, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchOperationResult, type BatchSetPageMetaRequest, type BatchWriteResult, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type ChangePlanPreview, type ChangePlanRequest, type Channel, type ChannelMembership, type ChannelStats, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsentOptions, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateCheckoutSessionRequest, type CreateCheckoutSessionResponse, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateRolePayload, type CreateRoleResult, type CreateRoomResult, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type CreateVideoStorageRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, EndpointAPI, type EndpointCallInit, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchDataResponse, type FetchFilesResponse, type FetchPublicKeysResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConfig, GameConfigAPI, type GameConfigPatch, type GameConnectionState, type GameConnectionStatus, type GameDelta, GameError, type GameErrorCode, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoBoundingBox, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LeaderboardEntry, type LeaderboardListResponse, type LeaderboardScoreEntry, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListPaymentsOptions, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchResult, type MatchmakingTicket, type MatchqueueListResponse, type MatchqueueTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OnPaymentFailure, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentListItem, type PaymentListResult, type PaymentMode, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type PlayerStats, type Playlist, type PlaylistItem, type PollUntilOptions, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type ProrationMode, type PublicKeyItem, type PublicKeyPaymentMode, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type PushStatsResult, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoleDetail, type RoleList, type RoleListItem, type RolePermissionItem, type RoleUserItem, RolesAPI, type RoomInfo, type RoomStaleMessage, type RoomSummary, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptMeta, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type SendSuperChatOptions, type SendSuperChatResponse, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type SpeechRecognizeOptions, type SpeechResult, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StorageUploadProgress, type StreamContentPart, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamImageURLPart, type StreamMessage, type StreamOptions, type StreamSession, type StreamTextPart, type StreamTokenCallback, type StreamToolCallCallback, type StreamToolResultCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SuperChatType, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionResult, type TransactionWrite, type TransactionWriteResult, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateDocumentRequest, type UpdateLobbyRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateRolePayload, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoCompleteUploadResponse, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageListResponse, type VideoVisibility, type VoiceChannel, type VoiceMember, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported, toCreateRoomWire };