connectbase-client 3.35.1 → 3.36.0

package/dist/index.d.mts

@@ -96,10 +96,10 @@ interface AbortOptions {
  * Recent API calls breadcrumb buffer — SDK 디버깅 / platform issue 발행 시 자동 첨부.
  *
  * **저장 정책 (PII 보호):**
- *   - method, path (query string strip), status, duration_ms, timestamp 만 저장
+ *   - method, path (query string 전체 strip), status, duration_ms, timestamp 만 저장
  *   - body / response body / 인증 토큰 미저장
- *   - URL 내 secret-like 패턴 (key=, token=, password=) 자동 redact
- *   - `/v1/auth/*`, `/v1/oauth/token` 등 민감 endpoint 는 path 만 (쿼리 strip)
+ *   - 쿼리스트링은 키 단위 redact 가 아니라 통째로 제거 (토큰/PII 누출 가능성 0)
+ *   - 따라서 `/v1/auth/*`, `/v1/oauth/token` 등 민감 endpoint 도 path 만 보존
  */
 interface RecentApiCall {
     method: string;
@@ -187,7 +187,7 @@ declare class HttpClient {
     private refreshLockedUntil;
     /**
      * 최근 API 호출 breadcrumb (PII strip 후 저장). platform_issue 발행 시 자동 첨부 가능.
-     * `client.support.getRecentCalls()` 로 외부 노출.
+     * `client.support.getRecentApiCalls()` 로 외부 노출.
      */
     private recentCalls;
     /**
@@ -1324,7 +1324,8 @@ interface BulkError {
     error: string;
 }
 interface DeleteWhereResponse {
-    deleted: number;
+    deleted_count: number;
+    failed_count?: number;
 }
 interface SecurityRule {
     id: string;
@@ -4111,8 +4112,8 @@ declare class OAuthAPI {
     } | null>;
 }
 
-type PaymentProvider = 'toss' | 'stripe';
-type PaymentStatus = 'pending' | 'ready' | 'in_progress' | 'done' | 'canceled' | 'partial_canceled' | 'aborted' | 'expired' | 'failed';
+type PaymentProvider = "toss" | "stripe" | "payapp";
+type PaymentStatus = "pending" | "ready" | "in_progress" | "done" | "canceled" | "partial_canceled" | "aborted" | "expired" | "failed";
 interface PreparePaymentRequest {
     amount: number;
     order_name: string;
@@ -4134,6 +4135,8 @@ interface PreparePaymentResponse {
     fail_url: string;
     stripe_client_secret?: string;
     stripe_publishable_key?: string;
+    payapp_pay_url?: string;
+    payapp_mul_no?: string;
 }
 interface CreateCheckoutSessionRequest {
     amount: number;
@@ -4249,7 +4252,16 @@ declare class PaymentAPI {
      *   // Mount PaymentElement, then:
      *   // stripe.confirmPayment({ elements, redirect: 'if_required' })
      * }
+     *
+     * // PayApp 결제 플로우 (위젯 불필요 — 호스팅 결제창으로 redirect)
+     * // 결제 결과는 서버의 feedbackurl webhook 으로 확정되며, 사용자는 success_url 로 복귀한다.
+     * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
+     *   window.location.href = result.payapp_pay_url
+     * }
      * ```
+     *
+     * @remarks
+     * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -4410,8 +4422,8 @@ interface ListBillingKeysResponse {
 type BillingCycle = 'daily' | 'weekly' | 'monthly' | 'yearly';
 type SubscriptionStatus = 'active' | 'paused' | 'canceled' | 'past_due' | 'expired' | 'trial';
 interface CreateSubscriptionRequest {
-    /** 빌링키 ID */
-    billing_key_id: string;
+    /** 빌링키 ID (toss/stripe 필수, payapp 미사용 — payurl 모델) */
+    billing_key_id?: string;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -4430,6 +4442,10 @@ interface CreateSubscriptionRequest {
     customer_email?: string;
     /** 고객 이름 */
     customer_name?: string;
+    /** 고객 전화번호 (payapp 정기결제 필수 — rebillRegist recvphone) */
+    customer_phone?: string;
+    /** payapp 정기결제 만료일 yyyy-mm-dd (미입력시 +10년) */
+    expire_date?: string;
     /** 메타데이터 */
     metadata?: Record<string, unknown>;
 }
@@ -4438,6 +4454,10 @@ interface SubscriptionResponse {
     id: string;
     /** 구독 ID (문자열) */
     subscription_id: string;
+    /** 결제 프로바이더 */
+    provider?: 'toss' | 'stripe' | 'payapp';
+    /** payapp: 카드등록+1회차 결제창 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
+    payapp_pay_url?: string;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -5062,20 +5082,22 @@ declare class PushAPI {
      */
     unregisterWebPush(deviceToken: string): Promise<void>;
     /**
-     * 회원 ID 목록으로 푸시 발송 — Functions / cb_sk_ 인증 환경 전용.
+     * 회원 ID 목록으로 푸시 발송 — Functions / 서버사이드 인증 환경 전용.
      *
-     * 백엔드 라우트 `POST /v1/apps/:appID/push/send` 는 콘솔 JWT 또는 User Secret Key
-     * (`cb_sk_`) 만 받는다. 브라우저 SDK 의 Public Key(`cb_pk_`) 인스턴스에서는 호출
-     * 자체가 차단되며, 권한 누설을 막기 위해 명확한 에러를 던진다.
+     * 백엔드 라우트 `POST /v1/apps/:appID/push/send` 는 콘솔 JWT, User Secret Key(`cb_sk_`),
+     * 또는 service_role 토큰(`ctx.cbAdmin`)을 받는다. 브라우저 SDK 의 Public Key(`cb_pk_`)
+     * **단독** 인스턴스에서는 호출 자체가 차단되며(권한 누설 방지), 명확한 에러를 던진다.
+     * 위임 Bearer 토큰을 가진 인스턴스(`ctx.cbAdmin`/`ctx.cb`)는 cb_pk_ 가 앱 식별용으로만
+     * 실리므로 허용된다.
      *
-     * @param appId 발송 대상 앱 ID (cb_sk_ 환경은 user 단위 권한이므로 명시 전달).
+     * @param appId 발송 대상 앱 ID.
      * @param memberIds 받는 회원 ID 배열 (UUID).
      * @param payload 푸시 내용/옵션.
      *
      * @example
      * ```ts
-     * // ConnectBase Function (Node.js, secrets.CB_SECRET_KEY 주입)
-     * const result = await cb.push.sendToMembers(APP_ID, [memberId], {
+     * // ConnectBase Function (service_role=true) — 시크릿 키 없이 ctx.cbAdmin 으로 발송
+     * const result = await ctx.cbAdmin.push.sendToMembers(ctx.appId, [memberId], {
      *     title: '새 알림',
      *     body: '확인해보세요',
      *     data: { route: '/notifications' },
@@ -5165,9 +5187,11 @@ interface UpdateVideoRequest {
     thumbnail_url?: string;
 }
 interface StreamURLResponse {
-    url: string;
+    /** 마스터 HLS 플레이리스트 URL (적응형 비트레이트) */
+    master_playlist: string;
+    /** 화질 키 → 화질별 플레이리스트 URL 맵 (예: { "720p": "https://..." }) */
+    qualities: Record<string, string>;
     expires_at: string;
-    quality?: string;
 }
 interface InitUploadResponse {
     upload_id: string;
@@ -5470,8 +5494,9 @@ declare class VideoAPI {
      *
      * @example
      * ```ts
-     * const { url, expires_at } = await cb.video.getStreamUrl(videoId, '720p')
-     * videoElement.src = url
+     * const { master_playlist, qualities, expires_at } = await cb.video.getStreamUrl(videoId)
+     * videoElement.src = master_playlist // 적응형 비트레이트(HLS.js 등으로 재생)
+     * // 특정 화질 고정이 필요하면 qualities['720p'] 사용
      * ```
      */
     getStreamUrl(videoId: string, quality?: string): Promise<StreamURLResponse>;
@@ -5597,12 +5622,18 @@ declare class VideoAPI {
     getMembershipTiers(channelId: string): Promise<MembershipTier[]>;
     /**
      * Join a membership tier
+     *
+     * @param _channelId 현재 서버에서 무시됩니다 (tier 가 채널을 함의). API 안정성을 위해 시그니처만 유지.
+     * @param tierId 가입할 멤버십 티어 ID
      */
-    joinMembership(channelId: string, tierId: string): Promise<ChannelMembership>;
+    joinMembership(_channelId: string, tierId: string): Promise<ChannelMembership>;
     /**
      * Cancel membership
+     *
+     * @param _channelId 현재 서버에서 무시됩니다. API 안정성을 위해 시그니처만 유지.
+     * @param membershipId 취소할 멤버십 ID
      */
-    cancelMembership(channelId: string, membershipId: string): Promise<void>;
+    cancelMembership(_channelId: string, membershipId: string): Promise<void>;
     /**
      * Send a super chat
      */
@@ -5613,6 +5644,8 @@ declare class VideoAPI {
     getSuperChats(videoId: string): Promise<SuperChat[]>;
     /**
      * Get recommended videos
+     *
+     * @deprecated Use getHomeFeed() — 동일한 개인화 피드(`/recommendations/feed`)를 반환합니다.
      */
     getRecommendations(limit?: number): Promise<Video[]>;
     /**
@@ -5742,7 +5775,7 @@ declare class GameConfigAPI {
     /**
      * 단일 기능 활성화 — set() 의 편의 wrapper.
      *
-     * @example await cb.game.config.enable(appId, "matchqueue")
+     * @example await cb.game.config.enable(appId, "matchqueue_enabled")
      */
     enable(appId: string, feature: keyof GameConfig): Promise<GameConfig>;
     /**
@@ -7981,6 +8014,9 @@ declare class EndpointAPI {
      * predicate 는 같은 Response 를 한 번만 읽을 수 있으므로, 헬퍼 내부에서
      * `res.clone().json()` 형태로 안전하게 파싱한 뒤 호출자에게 전달.
      *
+     * predicate 의 `body` 는 `unknown` 으로 전달되므로, 호출자가 자신의 응답
+     * 스키마로 narrowing 한 뒤 사용한다 (런타임 검증 책임은 호출자에게 있음).
+     *
      * @example ComfyUI 결과 폴링
      * ```typescript
      * type Hist = Record<string, { outputs: Record<string, { images?: { filename: string }[] }> }>
@@ -7988,7 +8024,8 @@ declare class EndpointAPI {
      * const filename = await cb.endpoint.pollUntil<string>(
      *     "comfyui-main",
      *     { path: `/history/${promptId}` },
-     *     (data: Hist) => {
+     *     (body) => {
+     *         const data = body as Hist
      *         const entry = data[promptId]
      *         if (!entry) return undefined // 아직 큐에 있음
      *         for (const out of Object.values(entry.outputs)) {
@@ -8031,7 +8068,7 @@ declare class EndpointAPI {
      * ```
      */
     connectWebSocket(label: string, opts?: ConnectWebSocketOptions): Promise<WebSocket>;
-    pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: any, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
+    pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: unknown, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
 }
 /**
  * EndpointAPI.call 의 init 인자.

package/dist/index.d.ts

@@ -96,10 +96,10 @@ interface AbortOptions {
  * Recent API calls breadcrumb buffer — SDK 디버깅 / platform issue 발행 시 자동 첨부.
  *
  * **저장 정책 (PII 보호):**
- *   - method, path (query string strip), status, duration_ms, timestamp 만 저장
+ *   - method, path (query string 전체 strip), status, duration_ms, timestamp 만 저장
  *   - body / response body / 인증 토큰 미저장
- *   - URL 내 secret-like 패턴 (key=, token=, password=) 자동 redact
- *   - `/v1/auth/*`, `/v1/oauth/token` 등 민감 endpoint 는 path 만 (쿼리 strip)
+ *   - 쿼리스트링은 키 단위 redact 가 아니라 통째로 제거 (토큰/PII 누출 가능성 0)
+ *   - 따라서 `/v1/auth/*`, `/v1/oauth/token` 등 민감 endpoint 도 path 만 보존
  */
 interface RecentApiCall {
     method: string;
@@ -187,7 +187,7 @@ declare class HttpClient {
     private refreshLockedUntil;
     /**
      * 최근 API 호출 breadcrumb (PII strip 후 저장). platform_issue 발행 시 자동 첨부 가능.
-     * `client.support.getRecentCalls()` 로 외부 노출.
+     * `client.support.getRecentApiCalls()` 로 외부 노출.
      */
     private recentCalls;
     /**
@@ -1324,7 +1324,8 @@ interface BulkError {
     error: string;
 }
 interface DeleteWhereResponse {
-    deleted: number;
+    deleted_count: number;
+    failed_count?: number;
 }
 interface SecurityRule {
     id: string;
@@ -4111,8 +4112,8 @@ declare class OAuthAPI {
     } | null>;
 }
 
-type PaymentProvider = 'toss' | 'stripe';
-type PaymentStatus = 'pending' | 'ready' | 'in_progress' | 'done' | 'canceled' | 'partial_canceled' | 'aborted' | 'expired' | 'failed';
+type PaymentProvider = "toss" | "stripe" | "payapp";
+type PaymentStatus = "pending" | "ready" | "in_progress" | "done" | "canceled" | "partial_canceled" | "aborted" | "expired" | "failed";
 interface PreparePaymentRequest {
     amount: number;
     order_name: string;
@@ -4134,6 +4135,8 @@ interface PreparePaymentResponse {
     fail_url: string;
     stripe_client_secret?: string;
     stripe_publishable_key?: string;
+    payapp_pay_url?: string;
+    payapp_mul_no?: string;
 }
 interface CreateCheckoutSessionRequest {
     amount: number;
@@ -4249,7 +4252,16 @@ declare class PaymentAPI {
      *   // Mount PaymentElement, then:
      *   // stripe.confirmPayment({ elements, redirect: 'if_required' })
      * }
+     *
+     * // PayApp 결제 플로우 (위젯 불필요 — 호스팅 결제창으로 redirect)
+     * // 결제 결과는 서버의 feedbackurl webhook 으로 확정되며, 사용자는 success_url 로 복귀한다.
+     * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
+     *   window.location.href = result.payapp_pay_url
+     * }
      * ```
+     *
+     * @remarks
+     * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -4410,8 +4422,8 @@ interface ListBillingKeysResponse {
 type BillingCycle = 'daily' | 'weekly' | 'monthly' | 'yearly';
 type SubscriptionStatus = 'active' | 'paused' | 'canceled' | 'past_due' | 'expired' | 'trial';
 interface CreateSubscriptionRequest {
-    /** 빌링키 ID */
-    billing_key_id: string;
+    /** 빌링키 ID (toss/stripe 필수, payapp 미사용 — payurl 모델) */
+    billing_key_id?: string;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -4430,6 +4442,10 @@ interface CreateSubscriptionRequest {
     customer_email?: string;
     /** 고객 이름 */
     customer_name?: string;
+    /** 고객 전화번호 (payapp 정기결제 필수 — rebillRegist recvphone) */
+    customer_phone?: string;
+    /** payapp 정기결제 만료일 yyyy-mm-dd (미입력시 +10년) */
+    expire_date?: string;
     /** 메타데이터 */
     metadata?: Record<string, unknown>;
 }
@@ -4438,6 +4454,10 @@ interface SubscriptionResponse {
     id: string;
     /** 구독 ID (문자열) */
     subscription_id: string;
+    /** 결제 프로바이더 */
+    provider?: 'toss' | 'stripe' | 'payapp';
+    /** payapp: 카드등록+1회차 결제창 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
+    payapp_pay_url?: string;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -5062,20 +5082,22 @@ declare class PushAPI {
      */
     unregisterWebPush(deviceToken: string): Promise<void>;
     /**
-     * 회원 ID 목록으로 푸시 발송 — Functions / cb_sk_ 인증 환경 전용.
+     * 회원 ID 목록으로 푸시 발송 — Functions / 서버사이드 인증 환경 전용.
      *
-     * 백엔드 라우트 `POST /v1/apps/:appID/push/send` 는 콘솔 JWT 또는 User Secret Key
-     * (`cb_sk_`) 만 받는다. 브라우저 SDK 의 Public Key(`cb_pk_`) 인스턴스에서는 호출
-     * 자체가 차단되며, 권한 누설을 막기 위해 명확한 에러를 던진다.
+     * 백엔드 라우트 `POST /v1/apps/:appID/push/send` 는 콘솔 JWT, User Secret Key(`cb_sk_`),
+     * 또는 service_role 토큰(`ctx.cbAdmin`)을 받는다. 브라우저 SDK 의 Public Key(`cb_pk_`)
+     * **단독** 인스턴스에서는 호출 자체가 차단되며(권한 누설 방지), 명확한 에러를 던진다.
+     * 위임 Bearer 토큰을 가진 인스턴스(`ctx.cbAdmin`/`ctx.cb`)는 cb_pk_ 가 앱 식별용으로만
+     * 실리므로 허용된다.
      *
-     * @param appId 발송 대상 앱 ID (cb_sk_ 환경은 user 단위 권한이므로 명시 전달).
+     * @param appId 발송 대상 앱 ID.
      * @param memberIds 받는 회원 ID 배열 (UUID).
      * @param payload 푸시 내용/옵션.
      *
      * @example
      * ```ts
-     * // ConnectBase Function (Node.js, secrets.CB_SECRET_KEY 주입)
-     * const result = await cb.push.sendToMembers(APP_ID, [memberId], {
+     * // ConnectBase Function (service_role=true) — 시크릿 키 없이 ctx.cbAdmin 으로 발송
+     * const result = await ctx.cbAdmin.push.sendToMembers(ctx.appId, [memberId], {
      *     title: '새 알림',
      *     body: '확인해보세요',
      *     data: { route: '/notifications' },
@@ -5165,9 +5187,11 @@ interface UpdateVideoRequest {
     thumbnail_url?: string;
 }
 interface StreamURLResponse {
-    url: string;
+    /** 마스터 HLS 플레이리스트 URL (적응형 비트레이트) */
+    master_playlist: string;
+    /** 화질 키 → 화질별 플레이리스트 URL 맵 (예: { "720p": "https://..." }) */
+    qualities: Record<string, string>;
     expires_at: string;
-    quality?: string;
 }
 interface InitUploadResponse {
     upload_id: string;
@@ -5470,8 +5494,9 @@ declare class VideoAPI {
      *
      * @example
      * ```ts
-     * const { url, expires_at } = await cb.video.getStreamUrl(videoId, '720p')
-     * videoElement.src = url
+     * const { master_playlist, qualities, expires_at } = await cb.video.getStreamUrl(videoId)
+     * videoElement.src = master_playlist // 적응형 비트레이트(HLS.js 등으로 재생)
+     * // 특정 화질 고정이 필요하면 qualities['720p'] 사용
      * ```
      */
     getStreamUrl(videoId: string, quality?: string): Promise<StreamURLResponse>;
@@ -5597,12 +5622,18 @@ declare class VideoAPI {
     getMembershipTiers(channelId: string): Promise<MembershipTier[]>;
     /**
      * Join a membership tier
+     *
+     * @param _channelId 현재 서버에서 무시됩니다 (tier 가 채널을 함의). API 안정성을 위해 시그니처만 유지.
+     * @param tierId 가입할 멤버십 티어 ID
      */
-    joinMembership(channelId: string, tierId: string): Promise<ChannelMembership>;
+    joinMembership(_channelId: string, tierId: string): Promise<ChannelMembership>;
     /**
      * Cancel membership
+     *
+     * @param _channelId 현재 서버에서 무시됩니다. API 안정성을 위해 시그니처만 유지.
+     * @param membershipId 취소할 멤버십 ID
      */
-    cancelMembership(channelId: string, membershipId: string): Promise<void>;
+    cancelMembership(_channelId: string, membershipId: string): Promise<void>;
     /**
      * Send a super chat
      */
@@ -5613,6 +5644,8 @@ declare class VideoAPI {
     getSuperChats(videoId: string): Promise<SuperChat[]>;
     /**
      * Get recommended videos
+     *
+     * @deprecated Use getHomeFeed() — 동일한 개인화 피드(`/recommendations/feed`)를 반환합니다.
      */
     getRecommendations(limit?: number): Promise<Video[]>;
     /**
@@ -5742,7 +5775,7 @@ declare class GameConfigAPI {
     /**
      * 단일 기능 활성화 — set() 의 편의 wrapper.
      *
-     * @example await cb.game.config.enable(appId, "matchqueue")
+     * @example await cb.game.config.enable(appId, "matchqueue_enabled")
      */
     enable(appId: string, feature: keyof GameConfig): Promise<GameConfig>;
     /**
@@ -7981,6 +8014,9 @@ declare class EndpointAPI {
      * predicate 는 같은 Response 를 한 번만 읽을 수 있으므로, 헬퍼 내부에서
      * `res.clone().json()` 형태로 안전하게 파싱한 뒤 호출자에게 전달.
      *
+     * predicate 의 `body` 는 `unknown` 으로 전달되므로, 호출자가 자신의 응답
+     * 스키마로 narrowing 한 뒤 사용한다 (런타임 검증 책임은 호출자에게 있음).
+     *
      * @example ComfyUI 결과 폴링
      * ```typescript
      * type Hist = Record<string, { outputs: Record<string, { images?: { filename: string }[] }> }>
@@ -7988,7 +8024,8 @@ declare class EndpointAPI {
      * const filename = await cb.endpoint.pollUntil<string>(
      *     "comfyui-main",
      *     { path: `/history/${promptId}` },
-     *     (data: Hist) => {
+     *     (body) => {
+     *         const data = body as Hist
      *         const entry = data[promptId]
      *         if (!entry) return undefined // 아직 큐에 있음
      *         for (const out of Object.values(entry.outputs)) {
@@ -8031,7 +8068,7 @@ declare class EndpointAPI {
      * ```
      */
     connectWebSocket(label: string, opts?: ConnectWebSocketOptions): Promise<WebSocket>;
-    pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: any, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
+    pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: unknown, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
 }
 /**
  * EndpointAPI.call 의 init 인자.