connectbase-client 5.4.0 → 5.4.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.4.1] - 2026-07-31
+
+### Docs — 함수 안에서 `postponeBilling()` 을 쓰는 방법 (`subscription:manage`)
+
+**동작 변경 없음.** 실행 코드는 5.4.0 과 동일하고 JSDoc/타입 선언의 주석만 바뀐다.
+
+5.4.0 문서가 "서버 전용 = `cb_sk_*` 필요" 로만 안내해서, 결정 코드가 ConnectBase Functions 안에
+있는 앱은 시크릿 키를 함수 시크릿에 심는 수밖에 없어 보였다 — 시크릿을 자동화 컨텍스트로 흘리지
+않는다는 기존 정책과 어긋난다 (platform-issue 019fb299). 백엔드에 `subscription:manage` 관리
+스코프가 생겨 `ctx.cbAdmin.subscription.postponeBilling()` / `update({ next_billing_date })` 가
+시크릿 키 없이 동작하므로, JSDoc·README 에 그 경로를 명시했다.
+
+- 허용 경로 2가지를 나란히 문서화: 내 서버(`cb_sk_*`) / 함수(`management_scopes:
+  ["subscription:manage"]` + `ctx.cbAdmin`).
+- `update()` 는 `next_billing_date` **가 있을 때만** 그 권한을 요구한다는 점 명시.
+- 403 사유 문구를 두 경로 모두 언급하도록 정정.
+
 ## [5.4.0] - 2026-07-30
 
 ### Added — 다음 결제일 미루기 `subscription.postponeBilling()` (기간 얹어 주기)

package/README.md

@@ -1310,8 +1310,12 @@ await cb.subscription.cancel(subscription.id)
 ```
 
 **기간 얹어 주기 (기간권·선물 코드·CS 보상)** — 요금제·금액은 그대로 두고 다음 결제일만 미룹니다.
-무상 기간 지급은 머천트 결정이라 **서버에서** `publicKey`(앱 식별) + `secretKey`(`cb_sk_*`, 관리자
-권한)로 초기화한 클라이언트로만 호출할 수 있습니다. 브라우저 퍼블릭 키 단독 호출은 403 입니다.
+무상 기간 지급은 머천트 결정이라 **서버에서만** 호출할 수 있습니다. 브라우저 퍼블릭 키 단독
+호출은 403 입니다. 서버 경로는 둘입니다:
+
+- **내 서버**: `publicKey`(앱 식별) + `secretKey`(`cb_sk_*`, 관리자 권한)로 초기화한 클라이언트
+- **ConnectBase Functions**: `service_role: true` + `management_scopes: ["subscription:manage"]`
+  로 만든 함수에서 `ctx.cbAdmin.subscription.*` — 시크릿 키를 함수 시크릿에 넣지 마세요
 
 ```typescript
 // 서버사이드 — 선물 코드를 검증한 뒤 지급
@@ -1328,6 +1332,16 @@ const extended = await cb.subscription.postponeBilling(subscription.id, {
 console.log(extended.next_billing_at)
 ```
 
+```javascript
+// ConnectBase Functions — 시크릿 키 없이 관리 스코프로 (management_scopes: ["subscription:manage"])
+export async function handler(payload, ctx) {
+  if (!ctx.cbAdmin) throw new Error('service_role not enabled')
+  const sub = await ctx.cbAdmin.subscription.get(payload.subscription_id)
+  if (sub.customer_email !== payload.email) throw new Error('not your subscription')
+  return ctx.cbAdmin.subscription.postponeBilling(sub.id, { days: 31, reason: `gift:${payload.code}` })
+}
+```
+
 서버가 현재 결제일을 PG 에서 직접 읽어 더하므로, 갱신 직전에 호출해도 방금 갱신된 주기 위에
 얹힙니다. payapp/paypal 은 PG 가 결제일 변경 API 를 주지 않아 400 `next_billing_date_unsupported`
 입니다 (로컬만 미루면 원래 날짜에 그대로 출금되므로 조용히 처리하지 않습니다).

package/dist/index.d.mts

@@ -8351,6 +8351,9 @@ declare class SubscriptionAPI {
      * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
      * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
      * {@link postponeBilling} 참조.
+     *
+     * `next_billing_date` **가 있을 때만** 서버 권한(`cb_sk_*` 또는 함수의 `subscription:manage`
+     * 관리 스코프)을 요구합니다 — 다른 필드만 바꾸는 퍼블릭 키 호출은 그대로 동작합니다.
      */
     update(subscriptionId: string, data: UpdateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**
@@ -8363,10 +8366,15 @@ declare class SubscriptionAPI {
      * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
      * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
      *
-     * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
-     * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
-     * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
-     * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+     * ⚠️ **서버 전용입니다.** 무상 기간 지급은 머천트 결정이라 브라우저에 노출되는 퍼블릭 키만으로는
+     * 열려 있지 않습니다(그러면 클라이언트가 자기 구독을 무한히 미룰 수 있습니다) — 퍼블릭 키만
+     * 있으면 403 입니다. 허용되는 서버 경로는 둘입니다:
+     *
+     * 1. **내 서버**: 클라이언트를 `publicKey` + `secretKey`(`cb_sk_*`)로 초기화해 호출.
+     * 2. **ConnectBase Functions**: `service_role: true` + `management_scopes:
+     *    ["subscription:manage"]` 로 만든 함수에서 `ctx.cbAdmin.subscription.postponeBilling(...)`.
+     *    시크릿 키를 함수 시크릿에 넣을 필요가 없습니다 — 스코프를 켠 함수만, 그 앱의 구독에만
+     *    통합니다.
      *
      * @param subscriptionId - 구독 ID
      * @param data - `days`(상대) 또는 `next_billing_date`(절대)
@@ -8403,7 +8411,7 @@ declare class SubscriptionAPI {
      *
      * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
      * - 과거 시각 → 400 `next_billing_date_invalid`
-     * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+     * - 퍼블릭 키만으로 호출 → 403 (`cb_sk_*` 또는 함수의 `subscription:manage` 스코프 필요)
      * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
      * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
      * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`

package/dist/index.d.ts

@@ -8351,6 +8351,9 @@ declare class SubscriptionAPI {
      * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
      * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
      * {@link postponeBilling} 참조.
+     *
+     * `next_billing_date` **가 있을 때만** 서버 권한(`cb_sk_*` 또는 함수의 `subscription:manage`
+     * 관리 스코프)을 요구합니다 — 다른 필드만 바꾸는 퍼블릭 키 호출은 그대로 동작합니다.
      */
     update(subscriptionId: string, data: UpdateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**
@@ -8363,10 +8366,15 @@ declare class SubscriptionAPI {
      * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
      * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
      *
-     * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
-     * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
-     * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
-     * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+     * ⚠️ **서버 전용입니다.** 무상 기간 지급은 머천트 결정이라 브라우저에 노출되는 퍼블릭 키만으로는
+     * 열려 있지 않습니다(그러면 클라이언트가 자기 구독을 무한히 미룰 수 있습니다) — 퍼블릭 키만
+     * 있으면 403 입니다. 허용되는 서버 경로는 둘입니다:
+     *
+     * 1. **내 서버**: 클라이언트를 `publicKey` + `secretKey`(`cb_sk_*`)로 초기화해 호출.
+     * 2. **ConnectBase Functions**: `service_role: true` + `management_scopes:
+     *    ["subscription:manage"]` 로 만든 함수에서 `ctx.cbAdmin.subscription.postponeBilling(...)`.
+     *    시크릿 키를 함수 시크릿에 넣을 필요가 없습니다 — 스코프를 켠 함수만, 그 앱의 구독에만
+     *    통합니다.
      *
      * @param subscriptionId - 구독 ID
      * @param data - `days`(상대) 또는 `next_billing_date`(절대)
@@ -8403,7 +8411,7 @@ declare class SubscriptionAPI {
      *
      * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
      * - 과거 시각 → 400 `next_billing_date_invalid`
-     * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+     * - 퍼블릭 키만으로 호출 → 403 (`cb_sk_*` 또는 함수의 `subscription:manage` 스코프 필요)
      * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
      * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
      * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`

package/dist/index.js

@@ -9149,6 +9149,9 @@ var SubscriptionAPI = class {
    * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
    * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
    * {@link postponeBilling} 참조.
+   *
+   * `next_billing_date` **가 있을 때만** 서버 권한(`cb_sk_*` 또는 함수의 `subscription:manage`
+   * 관리 스코프)을 요구합니다 — 다른 필드만 바꾸는 퍼블릭 키 호출은 그대로 동작합니다.
    */
   async update(subscriptionId, data) {
     const prefix = this.getPublicPrefix();
@@ -9167,10 +9170,15 @@ var SubscriptionAPI = class {
    * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
    * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
    *
-   * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
-   * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
-   * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
-   * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+   * ⚠️ **서버 전용입니다.** 무상 기간 지급은 머천트 결정이라 브라우저에 노출되는 퍼블릭 키만으로는
+   * 열려 있지 않습니다(그러면 클라이언트가 자기 구독을 무한히 미룰 수 있습니다) — 퍼블릭 키만
+   * 있으면 403 입니다. 허용되는 서버 경로는 둘입니다:
+   *
+   * 1. **내 서버**: 클라이언트를 `publicKey` + `secretKey`(`cb_sk_*`)로 초기화해 호출.
+   * 2. **ConnectBase Functions**: `service_role: true` + `management_scopes:
+   *    ["subscription:manage"]` 로 만든 함수에서 `ctx.cbAdmin.subscription.postponeBilling(...)`.
+   *    시크릿 키를 함수 시크릿에 넣을 필요가 없습니다 — 스코프를 켠 함수만, 그 앱의 구독에만
+   *    통합니다.
    *
    * @param subscriptionId - 구독 ID
    * @param data - `days`(상대) 또는 `next_billing_date`(절대)
@@ -9207,7 +9215,7 @@ var SubscriptionAPI = class {
    *
    * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
    * - 과거 시각 → 400 `next_billing_date_invalid`
-   * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+   * - 퍼블릭 키만으로 호출 → 403 (`cb_sk_*` 또는 함수의 `subscription:manage` 스코프 필요)
    * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
    * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
    * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`

package/dist/index.mjs

@@ -9100,6 +9100,9 @@ var SubscriptionAPI = class {
    * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
    * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
    * {@link postponeBilling} 참조.
+   *
+   * `next_billing_date` **가 있을 때만** 서버 권한(`cb_sk_*` 또는 함수의 `subscription:manage`
+   * 관리 스코프)을 요구합니다 — 다른 필드만 바꾸는 퍼블릭 키 호출은 그대로 동작합니다.
    */
   async update(subscriptionId, data) {
     const prefix = this.getPublicPrefix();
@@ -9118,10 +9121,15 @@ var SubscriptionAPI = class {
    * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
    * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
    *
-   * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
-   * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
-   * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
-   * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+   * ⚠️ **서버 전용입니다.** 무상 기간 지급은 머천트 결정이라 브라우저에 노출되는 퍼블릭 키만으로는
+   * 열려 있지 않습니다(그러면 클라이언트가 자기 구독을 무한히 미룰 수 있습니다) — 퍼블릭 키만
+   * 있으면 403 입니다. 허용되는 서버 경로는 둘입니다:
+   *
+   * 1. **내 서버**: 클라이언트를 `publicKey` + `secretKey`(`cb_sk_*`)로 초기화해 호출.
+   * 2. **ConnectBase Functions**: `service_role: true` + `management_scopes:
+   *    ["subscription:manage"]` 로 만든 함수에서 `ctx.cbAdmin.subscription.postponeBilling(...)`.
+   *    시크릿 키를 함수 시크릿에 넣을 필요가 없습니다 — 스코프를 켠 함수만, 그 앱의 구독에만
+   *    통합니다.
    *
    * @param subscriptionId - 구독 ID
    * @param data - `days`(상대) 또는 `next_billing_date`(절대)
@@ -9158,7 +9166,7 @@ var SubscriptionAPI = class {
    *
    * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
    * - 과거 시각 → 400 `next_billing_date_invalid`
-   * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+   * - 퍼블릭 키만으로 호출 → 403 (`cb_sk_*` 또는 함수의 `subscription:manage` 스코프 필요)
    * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
    * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
    * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`

package/package.json

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