connectbase-client 4.2.0 → 4.4.0

package/dist/index.mjs

@@ -6115,11 +6115,19 @@ var PublicKeyAPI = class {
   constructor(http) {
     this.http = http;
   }
+  ensureServerAuth(method) {
+    if (this.http.hasPublicKey() && !this.http.hasJWT()) {
+      throw new Error(
+        `cb.publicKey.${method}() \uB294 \uCF58\uC194 JWT \uB610\uB294 service_role(ctx.cbAdmin, management_scopes: ["publickey:read" | "publickey:manage"]) \uC778\uC99D\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. Public Key(cb_pk_) \uB2E8\uB3C5 SDK \uC778\uC2A4\uD134\uC2A4\uB85C\uB294 \uD638\uCD9C\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 Functions \uD658\uACBD\uC5D0\uC11C \uC0AC\uC6A9\uD558\uC138\uC694.`
+      );
+    }
+  }
   /**
-   * 앱의 Public Key 목록을 조회합니다
+   * 앱의 Public Key 목록을 조회합니다 (management_scope: `publickey:read`)
    * @param appId 앱 ID
    */
   async getPublicKeys(appId) {
+    this.ensureServerAuth("getPublicKeys");
     return this.http.get(
       `/v1/apps/${appId}/public-keys`
     );
@@ -6131,32 +6139,39 @@ var PublicKeyAPI = class {
    * 안전한 곳에 저장하세요.
    *
    * @param appId 앱 ID
-   * @param data 생성할 Public Key 정보
+   * @param data 생성할 Public Key 정보 (`payment_mode` 로 결제 모드 고정 가능)
+   *
+   * (management_scope: `publickey:manage`)
    */
   async createPublicKey(appId, data) {
+    this.ensureServerAuth("createPublicKey");
     return this.http.post(
       `/v1/apps/${appId}/public-keys`,
       data
     );
   }
   /**
-   * Public Key 를 수정합니다 (이름 변경, 활성화/비활성화)
+   * Public Key 를 수정합니다 (이름 변경, 활성화/비활성화, `payment_mode` 변경)
+   *
+   * (management_scope: `publickey:manage`)
    * @param appId 앱 ID
    * @param keyId Public Key ID
    * @param data 수정할 정보
    */
   async updatePublicKey(appId, keyId, data) {
+    this.ensureServerAuth("updatePublicKey");
     return this.http.patch(
       `/v1/apps/${appId}/public-keys/${keyId}`,
       data
     );
   }
   /**
-   * Public Key 를 삭제합니다
+   * Public Key 를 삭제합니다 (management_scope: `publickey:manage`)
    * @param appId 앱 ID
    * @param keyId Public Key ID
    */
   async deletePublicKey(appId, keyId) {
+    this.ensureServerAuth("deletePublicKey");
     await this.http.delete(`/v1/apps/${appId}/public-keys/${keyId}`);
   }
 };
@@ -8941,14 +8956,19 @@ var SubscriptionAPI = class {
     );
   }
   /**
-   * 요금제 스왑 (플랜 변경) — 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 + 정산 옵션
@@ -8957,7 +8977,7 @@ var SubscriptionAPI = class {
    * @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',
@@ -8972,12 +8992,20 @@ var SubscriptionAPI = class {
     );
   }
   /**
-   * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (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 정산 미리보기 (지금 청구/크레딧 · 새 정기 청구액 · 다음 청구일)
@@ -8987,7 +9015,9 @@ var SubscriptionAPI = class {
    * 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)
    * ```
    */
   async previewChangePlan(subscriptionId, data) {

package/package.json

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