connectbase-client 5.3.0 → 5.4.0

package/dist/index.d.mts

@@ -5587,6 +5587,11 @@ interface PreparePaymentResponse {
     launch_mode?: "overlay" | "redirect";
 }
 interface CreateCheckoutSessionRequest {
+    /**
+     * 사용할 자격증명 모드 오버라이드(선택). `prepare()` 의 `payment_mode` 와 적용 조건이 같다 —
+     * 서버 시크릿 키(`cb_sk_*`) 호출에서만 적용되고, 브라우저 공개 키 호출에서는 무시된다.
+     */
+    payment_mode?: PaymentMode;
     amount: number;
     currency: string;
     product_name: string;
@@ -7754,6 +7759,20 @@ type SubscriptionStatus = "active" | "paused" | "canceled" | "past_due" | "expir
 interface CreateSubscriptionRequest {
     /** 빌링키 ID (toss/stripe 필수, payapp 미사용 — payurl 모델) */
     billing_key_id?: string;
+    /**
+     * 구독 ID 를 직접 지정한다(선택). 미지정이면 서버가 `sub_<uuid>` 로 생성한다.
+     *
+     * 재시도 시 같은 값을 넘기면 최초 청구 orderID 가 결정적으로 만들어져 이중청구를 막는다 —
+     * 네트워크 실패로 create 를 다시 호출해야 할 때 쓴다.
+     */
+    subscription_id?: string;
+    /**
+     * true 면 구독 생성 즉시 1회차를 청구한다(빌링키 모델). false(기본)면 다음 결제일부터 청구.
+     * `trial_days` 가 있으면 즉시 청구하지 않는다(체험 종료 후 첫 청구).
+     *
+     * MoR(paddle/dodo)은 결제창에서 1회차를 받으므로 이 값을 쓰지 않는다.
+     */
+    start_now?: boolean;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -7920,6 +7939,34 @@ interface UpdateSubscriptionRequest {
     amount?: number;
     /** 메타데이터 */
     metadata?: Record<string, unknown>;
+    /**
+     * 다음 정기 결제일을 이 시점으로 옮깁니다 (RFC3339 또는 `YYYY-MM-DD` = 00:00 UTC).
+     *
+     * 요금제·금액은 그대로 두고 **청구 시점만** 옮기므로, 구독 중인 고객에게 기간을 얹어 줄 때
+     * (기간권·선물 코드·CS 보상) 씁니다. 상대 일수로 미루려면
+     * {@link SubscriptionAPI.postponeBilling} 이 낫습니다 — 현재 결제일을 PG 에서 읽어 더하므로
+     * 갱신 직전 경쟁 조건을 서버가 처리합니다.
+     *
+     * ⚠️ 이 필드만 **서버 시크릿 키(`cb_sk_*`)가 필요합니다** — 무상 기간 지급이라 브라우저
+     * 퍼블릭 키만으로는 403 입니다(다른 필드는 기존대로 퍼블릭 키로 수정 가능).
+     *
+     * 과거 시각은 400 `next_billing_date_invalid`,
+     * 결제일을 옮길 수 없는 프로바이더(payapp/paypal)는 400 `next_billing_date_unsupported`.
+     */
+    next_billing_date?: string;
+}
+/**
+ * 다음 결제일 미루기 요청 — `days` 와 `next_billing_date` 중 **정확히 하나**를 지정합니다.
+ *
+ * 둘 다 주거나 둘 다 비우면 400 `postpone_billing_input_invalid`.
+ */
+interface PostponeBillingRequest {
+    /** 미룰 일수 (1~3650). 예) 31일 선물권 → 다음 결제일이 31일 뒤로 밀림 */
+    days?: number;
+    /** 절대 날짜 지정 (RFC3339 또는 `YYYY-MM-DD` = 00:00 UTC). `days` 와 동시 지정 불가 */
+    next_billing_date?: string;
+    /** 기록용 사유 (선택, 200자) — 서버 로그에만 남습니다 */
+    reason?: string;
 }
 interface PauseSubscriptionRequest {
     /** 일시정지 사유 */
@@ -8292,9 +8339,78 @@ declare class SubscriptionAPI {
      *     plan_name: '엔터프라이즈 플랜',
      *     amount: 29900
      * })
+     *
+     * // 다음 결제일을 특정 날짜로 옮기기 (기간권·보상)
+     * await client.subscription.update(subscriptionId, {
+     *     next_billing_date: '2026-09-01',
+     * })
      * ```
+     *
+     * @remarks
+     * `next_billing_date` 는 PG 의 청구 스케줄까지 함께 옮깁니다. 그래서 결제일을 옮길 수 없는
+     * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
+     * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
+     * {@link postponeBilling} 참조.
      */
     update(subscriptionId: string, data: UpdateSubscriptionRequest): Promise<SubscriptionResponse>;
+    /**
+     * 다음 결제일 미루기 — 구독 중인 고객에게 **기간을 얹어 줍니다** (서버 전용)
+     *
+     * 요금제·금액은 그대로 두고 다음 정기 결제일만 옮깁니다. 기간권·선물 코드·CS 보상
+     * ("불편을 드려 한 달 무료")처럼 "구독은 유지한 채 N일 공짜" 를 표현하는 표준 경로입니다.
+     *
+     * `days` 를 쓰면 **현재 결제일을 PG 에서 읽어** 더합니다 — 앱마다 "조회 → 더하기 → 쓰기" 를
+     * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
+     * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
+     *
+     * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
+     * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
+     * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
+     * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+     *
+     * @param subscriptionId - 구독 ID
+     * @param data - `days`(상대) 또는 `next_billing_date`(절대)
+     * @returns 갱신된 구독 정보 (`next_billing_at` 이 옮겨진 값)
+     *
+     * @example
+     * ```typescript
+     * // 서버사이드: 선물 코드를 검증한 뒤 지급
+     * const cb = new ConnectBase({
+     *     publicKey: process.env.CB_PUBLIC_KEY,   // 앱 식별
+     *     secretKey: process.env.CB_SECRET_KEY,   // 관리자 권한 (cb_sk_*)
+     * })
+     *
+     * // 31일 선물권 등록 → 다음 결제일이 31일 뒤로
+     * const sub = await cb.subscription.postponeBilling(subscriptionId, {
+     *     days: 31,
+     *     reason: 'gift-code:ABC123',
+     * })
+     * console.log(sub.next_billing_at)
+     *
+     * // 특정 날짜로 못박기
+     * await cb.subscription.postponeBilling(subscriptionId, {
+     *     next_billing_date: '2026-09-01T00:00:00Z',
+     * })
+     * ```
+     *
+     * @remarks
+     * **프로바이더 지원 범위** — 청구 스케줄의 주인이 다르기 때문에 갈립니다:
+     * - **Dodo · Paddle (MoR)**: PG 의 결제일 변경 API 로 옮깁니다. Paddle 은 이동 구간에 대해
+     *   청구도 크레딧도 만들지 않습니다(`do_not_bill`) — 미뤄 준 기간이 차액으로 상쇄되지 않습니다.
+     * - **toss · stripe**: ConnectBase 스케줄러가 청구하므로 즉시 반영됩니다.
+     * - **payapp · paypal**: PG 가 청구를 소유하면서 결제일 변경 수단을 주지 않아
+     *   400 `next_billing_date_unsupported` 입니다(로컬만 미루면 원래 날짜에 출금되므로 거절).
+     *
+     * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
+     * - 과거 시각 → 400 `next_billing_date_invalid`
+     * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+     * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
+     * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
+     * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`
+     *   (종료일이 정해져 있어 결제일을 미뤄도 기간이 늘지 않기 때문)
+     * - MoR 최초 결제 전 → 409 `subscription_not_activated`
+     */
+    postponeBilling(subscriptionId: string, data: PostponeBillingRequest): Promise<SubscriptionResponse>;
     /**
      * 구독 일시정지
      *
@@ -10143,4 +10259,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { AIAPI, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, 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 AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, 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 ListAppMembersOptions, 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, toAIError, toCreateRoomWire };
+export { AIAPI, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, 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 AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, 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 ListAppMembersOptions, 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 PostponeBillingRequest, 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, toAIError, toCreateRoomWire };

package/dist/index.d.ts

@@ -5587,6 +5587,11 @@ interface PreparePaymentResponse {
     launch_mode?: "overlay" | "redirect";
 }
 interface CreateCheckoutSessionRequest {
+    /**
+     * 사용할 자격증명 모드 오버라이드(선택). `prepare()` 의 `payment_mode` 와 적용 조건이 같다 —
+     * 서버 시크릿 키(`cb_sk_*`) 호출에서만 적용되고, 브라우저 공개 키 호출에서는 무시된다.
+     */
+    payment_mode?: PaymentMode;
     amount: number;
     currency: string;
     product_name: string;
@@ -7754,6 +7759,20 @@ type SubscriptionStatus = "active" | "paused" | "canceled" | "past_due" | "expir
 interface CreateSubscriptionRequest {
     /** 빌링키 ID (toss/stripe 필수, payapp 미사용 — payurl 모델) */
     billing_key_id?: string;
+    /**
+     * 구독 ID 를 직접 지정한다(선택). 미지정이면 서버가 `sub_<uuid>` 로 생성한다.
+     *
+     * 재시도 시 같은 값을 넘기면 최초 청구 orderID 가 결정적으로 만들어져 이중청구를 막는다 —
+     * 네트워크 실패로 create 를 다시 호출해야 할 때 쓴다.
+     */
+    subscription_id?: string;
+    /**
+     * true 면 구독 생성 즉시 1회차를 청구한다(빌링키 모델). false(기본)면 다음 결제일부터 청구.
+     * `trial_days` 가 있으면 즉시 청구하지 않는다(체험 종료 후 첫 청구).
+     *
+     * MoR(paddle/dodo)은 결제창에서 1회차를 받으므로 이 값을 쓰지 않는다.
+     */
+    start_now?: boolean;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -7920,6 +7939,34 @@ interface UpdateSubscriptionRequest {
     amount?: number;
     /** 메타데이터 */
     metadata?: Record<string, unknown>;
+    /**
+     * 다음 정기 결제일을 이 시점으로 옮깁니다 (RFC3339 또는 `YYYY-MM-DD` = 00:00 UTC).
+     *
+     * 요금제·금액은 그대로 두고 **청구 시점만** 옮기므로, 구독 중인 고객에게 기간을 얹어 줄 때
+     * (기간권·선물 코드·CS 보상) 씁니다. 상대 일수로 미루려면
+     * {@link SubscriptionAPI.postponeBilling} 이 낫습니다 — 현재 결제일을 PG 에서 읽어 더하므로
+     * 갱신 직전 경쟁 조건을 서버가 처리합니다.
+     *
+     * ⚠️ 이 필드만 **서버 시크릿 키(`cb_sk_*`)가 필요합니다** — 무상 기간 지급이라 브라우저
+     * 퍼블릭 키만으로는 403 입니다(다른 필드는 기존대로 퍼블릭 키로 수정 가능).
+     *
+     * 과거 시각은 400 `next_billing_date_invalid`,
+     * 결제일을 옮길 수 없는 프로바이더(payapp/paypal)는 400 `next_billing_date_unsupported`.
+     */
+    next_billing_date?: string;
+}
+/**
+ * 다음 결제일 미루기 요청 — `days` 와 `next_billing_date` 중 **정확히 하나**를 지정합니다.
+ *
+ * 둘 다 주거나 둘 다 비우면 400 `postpone_billing_input_invalid`.
+ */
+interface PostponeBillingRequest {
+    /** 미룰 일수 (1~3650). 예) 31일 선물권 → 다음 결제일이 31일 뒤로 밀림 */
+    days?: number;
+    /** 절대 날짜 지정 (RFC3339 또는 `YYYY-MM-DD` = 00:00 UTC). `days` 와 동시 지정 불가 */
+    next_billing_date?: string;
+    /** 기록용 사유 (선택, 200자) — 서버 로그에만 남습니다 */
+    reason?: string;
 }
 interface PauseSubscriptionRequest {
     /** 일시정지 사유 */
@@ -8292,9 +8339,78 @@ declare class SubscriptionAPI {
      *     plan_name: '엔터프라이즈 플랜',
      *     amount: 29900
      * })
+     *
+     * // 다음 결제일을 특정 날짜로 옮기기 (기간권·보상)
+     * await client.subscription.update(subscriptionId, {
+     *     next_billing_date: '2026-09-01',
+     * })
      * ```
+     *
+     * @remarks
+     * `next_billing_date` 는 PG 의 청구 스케줄까지 함께 옮깁니다. 그래서 결제일을 옮길 수 없는
+     * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
+     * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
+     * {@link postponeBilling} 참조.
      */
     update(subscriptionId: string, data: UpdateSubscriptionRequest): Promise<SubscriptionResponse>;
+    /**
+     * 다음 결제일 미루기 — 구독 중인 고객에게 **기간을 얹어 줍니다** (서버 전용)
+     *
+     * 요금제·금액은 그대로 두고 다음 정기 결제일만 옮깁니다. 기간권·선물 코드·CS 보상
+     * ("불편을 드려 한 달 무료")처럼 "구독은 유지한 채 N일 공짜" 를 표현하는 표준 경로입니다.
+     *
+     * `days` 를 쓰면 **현재 결제일을 PG 에서 읽어** 더합니다 — 앱마다 "조회 → 더하기 → 쓰기" 를
+     * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
+     * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
+     *
+     * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
+     * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
+     * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
+     * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+     *
+     * @param subscriptionId - 구독 ID
+     * @param data - `days`(상대) 또는 `next_billing_date`(절대)
+     * @returns 갱신된 구독 정보 (`next_billing_at` 이 옮겨진 값)
+     *
+     * @example
+     * ```typescript
+     * // 서버사이드: 선물 코드를 검증한 뒤 지급
+     * const cb = new ConnectBase({
+     *     publicKey: process.env.CB_PUBLIC_KEY,   // 앱 식별
+     *     secretKey: process.env.CB_SECRET_KEY,   // 관리자 권한 (cb_sk_*)
+     * })
+     *
+     * // 31일 선물권 등록 → 다음 결제일이 31일 뒤로
+     * const sub = await cb.subscription.postponeBilling(subscriptionId, {
+     *     days: 31,
+     *     reason: 'gift-code:ABC123',
+     * })
+     * console.log(sub.next_billing_at)
+     *
+     * // 특정 날짜로 못박기
+     * await cb.subscription.postponeBilling(subscriptionId, {
+     *     next_billing_date: '2026-09-01T00:00:00Z',
+     * })
+     * ```
+     *
+     * @remarks
+     * **프로바이더 지원 범위** — 청구 스케줄의 주인이 다르기 때문에 갈립니다:
+     * - **Dodo · Paddle (MoR)**: PG 의 결제일 변경 API 로 옮깁니다. Paddle 은 이동 구간에 대해
+     *   청구도 크레딧도 만들지 않습니다(`do_not_bill`) — 미뤄 준 기간이 차액으로 상쇄되지 않습니다.
+     * - **toss · stripe**: ConnectBase 스케줄러가 청구하므로 즉시 반영됩니다.
+     * - **payapp · paypal**: PG 가 청구를 소유하면서 결제일 변경 수단을 주지 않아
+     *   400 `next_billing_date_unsupported` 입니다(로컬만 미루면 원래 날짜에 출금되므로 거절).
+     *
+     * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
+     * - 과거 시각 → 400 `next_billing_date_invalid`
+     * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+     * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
+     * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
+     * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`
+     *   (종료일이 정해져 있어 결제일을 미뤄도 기간이 늘지 않기 때문)
+     * - MoR 최초 결제 전 → 409 `subscription_not_activated`
+     */
+    postponeBilling(subscriptionId: string, data: PostponeBillingRequest): Promise<SubscriptionResponse>;
     /**
      * 구독 일시정지
      *
@@ -10143,4 +10259,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { AIAPI, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, 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 AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, 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 ListAppMembersOptions, 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, toAIError, toCreateRoomWire };
+export { AIAPI, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, 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 AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, 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 ListAppMembersOptions, 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 PostponeBillingRequest, 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, toAIError, toCreateRoomWire };

package/dist/index.js

@@ -9137,7 +9137,18 @@ var SubscriptionAPI = class {
    *     plan_name: '엔터프라이즈 플랜',
    *     amount: 29900
    * })
+   *
+   * // 다음 결제일을 특정 날짜로 옮기기 (기간권·보상)
+   * await client.subscription.update(subscriptionId, {
+   *     next_billing_date: '2026-09-01',
+   * })
    * ```
+   *
+   * @remarks
+   * `next_billing_date` 는 PG 의 청구 스케줄까지 함께 옮깁니다. 그래서 결제일을 옮길 수 없는
+   * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
+   * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
+   * {@link postponeBilling} 참조.
    */
   async update(subscriptionId, data) {
     const prefix = this.getPublicPrefix();
@@ -9146,6 +9157,70 @@ var SubscriptionAPI = class {
       data
     );
   }
+  /**
+   * 다음 결제일 미루기 — 구독 중인 고객에게 **기간을 얹어 줍니다** (서버 전용)
+   *
+   * 요금제·금액은 그대로 두고 다음 정기 결제일만 옮깁니다. 기간권·선물 코드·CS 보상
+   * ("불편을 드려 한 달 무료")처럼 "구독은 유지한 채 N일 공짜" 를 표현하는 표준 경로입니다.
+   *
+   * `days` 를 쓰면 **현재 결제일을 PG 에서 읽어** 더합니다 — 앱마다 "조회 → 더하기 → 쓰기" 를
+   * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
+   * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
+   *
+   * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
+   * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
+   * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
+   * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+   *
+   * @param subscriptionId - 구독 ID
+   * @param data - `days`(상대) 또는 `next_billing_date`(절대)
+   * @returns 갱신된 구독 정보 (`next_billing_at` 이 옮겨진 값)
+   *
+   * @example
+   * ```typescript
+   * // 서버사이드: 선물 코드를 검증한 뒤 지급
+   * const cb = new ConnectBase({
+   *     publicKey: process.env.CB_PUBLIC_KEY,   // 앱 식별
+   *     secretKey: process.env.CB_SECRET_KEY,   // 관리자 권한 (cb_sk_*)
+   * })
+   *
+   * // 31일 선물권 등록 → 다음 결제일이 31일 뒤로
+   * const sub = await cb.subscription.postponeBilling(subscriptionId, {
+   *     days: 31,
+   *     reason: 'gift-code:ABC123',
+   * })
+   * console.log(sub.next_billing_at)
+   *
+   * // 특정 날짜로 못박기
+   * await cb.subscription.postponeBilling(subscriptionId, {
+   *     next_billing_date: '2026-09-01T00:00:00Z',
+   * })
+   * ```
+   *
+   * @remarks
+   * **프로바이더 지원 범위** — 청구 스케줄의 주인이 다르기 때문에 갈립니다:
+   * - **Dodo · Paddle (MoR)**: PG 의 결제일 변경 API 로 옮깁니다. Paddle 은 이동 구간에 대해
+   *   청구도 크레딧도 만들지 않습니다(`do_not_bill`) — 미뤄 준 기간이 차액으로 상쇄되지 않습니다.
+   * - **toss · stripe**: ConnectBase 스케줄러가 청구하므로 즉시 반영됩니다.
+   * - **payapp · paypal**: PG 가 청구를 소유하면서 결제일 변경 수단을 주지 않아
+   *   400 `next_billing_date_unsupported` 입니다(로컬만 미루면 원래 날짜에 출금되므로 거절).
+   *
+   * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
+   * - 과거 시각 → 400 `next_billing_date_invalid`
+   * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+   * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
+   * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
+   * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`
+   *   (종료일이 정해져 있어 결제일을 미뤄도 기간이 늘지 않기 때문)
+   * - MoR 최초 결제 전 → 409 `subscription_not_activated`
+   */
+  async postponeBilling(subscriptionId, data) {
+    const prefix = this.getPublicPrefix();
+    return this.http.post(
+      `${prefix}/subscriptions/${subscriptionId}/postpone-billing`,
+      data
+    );
+  }
   /**
    * 구독 일시정지
    *

package/dist/index.mjs

@@ -9088,7 +9088,18 @@ var SubscriptionAPI = class {
    *     plan_name: '엔터프라이즈 플랜',
    *     amount: 29900
    * })
+   *
+   * // 다음 결제일을 특정 날짜로 옮기기 (기간권·보상)
+   * await client.subscription.update(subscriptionId, {
+   *     next_billing_date: '2026-09-01',
+   * })
    * ```
+   *
+   * @remarks
+   * `next_billing_date` 는 PG 의 청구 스케줄까지 함께 옮깁니다. 그래서 결제일을 옮길 수 없는
+   * 프로바이더는 조용히 무시되지 않고 400 `next_billing_date_unsupported` 로 거절됩니다
+   * (로컬 기록만 미루면 PG 는 원래 날짜에 그대로 출금합니다). 지원표와 상세는
+   * {@link postponeBilling} 참조.
    */
   async update(subscriptionId, data) {
     const prefix = this.getPublicPrefix();
@@ -9097,6 +9108,70 @@ var SubscriptionAPI = class {
       data
     );
   }
+  /**
+   * 다음 결제일 미루기 — 구독 중인 고객에게 **기간을 얹어 줍니다** (서버 전용)
+   *
+   * 요금제·금액은 그대로 두고 다음 정기 결제일만 옮깁니다. 기간권·선물 코드·CS 보상
+   * ("불편을 드려 한 달 무료")처럼 "구독은 유지한 채 N일 공짜" 를 표현하는 표준 경로입니다.
+   *
+   * `days` 를 쓰면 **현재 결제일을 PG 에서 읽어** 더합니다 — 앱마다 "조회 → 더하기 → 쓰기" 를
+   * 다시 구현하지 않아도 되고, 갱신 직전에 호출해도 방금 갱신된 주기 위에 얹힙니다.
+   * 절대 날짜로 못박으려면 `next_billing_date` 를 쓰세요(둘 중 하나만 지정).
+   *
+   * ⚠️ **서버 시크릿 키(`cb_sk_*`)가 필요합니다.** 무상 기간 지급은 머천트 결정이라
+   * 브라우저에 노출되는 퍼블릭 키만으로는 열려 있지 않습니다(그러면 클라이언트가 자기 구독을
+   * 무한히 미룰 수 있습니다). 클라이언트를 `publicKey` + `secretKey` 로 초기화한 서버에서
+   * 호출하세요 — 퍼블릭 키만 있으면 403 입니다.
+   *
+   * @param subscriptionId - 구독 ID
+   * @param data - `days`(상대) 또는 `next_billing_date`(절대)
+   * @returns 갱신된 구독 정보 (`next_billing_at` 이 옮겨진 값)
+   *
+   * @example
+   * ```typescript
+   * // 서버사이드: 선물 코드를 검증한 뒤 지급
+   * const cb = new ConnectBase({
+   *     publicKey: process.env.CB_PUBLIC_KEY,   // 앱 식별
+   *     secretKey: process.env.CB_SECRET_KEY,   // 관리자 권한 (cb_sk_*)
+   * })
+   *
+   * // 31일 선물권 등록 → 다음 결제일이 31일 뒤로
+   * const sub = await cb.subscription.postponeBilling(subscriptionId, {
+   *     days: 31,
+   *     reason: 'gift-code:ABC123',
+   * })
+   * console.log(sub.next_billing_at)
+   *
+   * // 특정 날짜로 못박기
+   * await cb.subscription.postponeBilling(subscriptionId, {
+   *     next_billing_date: '2026-09-01T00:00:00Z',
+   * })
+   * ```
+   *
+   * @remarks
+   * **프로바이더 지원 범위** — 청구 스케줄의 주인이 다르기 때문에 갈립니다:
+   * - **Dodo · Paddle (MoR)**: PG 의 결제일 변경 API 로 옮깁니다. Paddle 은 이동 구간에 대해
+   *   청구도 크레딧도 만들지 않습니다(`do_not_bill`) — 미뤄 준 기간이 차액으로 상쇄되지 않습니다.
+   * - **toss · stripe**: ConnectBase 스케줄러가 청구하므로 즉시 반영됩니다.
+   * - **payapp · paypal**: PG 가 청구를 소유하면서 결제일 변경 수단을 주지 않아
+   *   400 `next_billing_date_unsupported` 입니다(로컬만 미루면 원래 날짜에 출금되므로 거절).
+   *
+   * **거절되는 경우** — 조용한 no-op 대신 사유를 돌려줍니다:
+   * - 과거 시각 → 400 `next_billing_date_invalid`
+   * - 퍼블릭 키만으로 호출 → 403 (서버 시크릿 키 필요)
+   * - `days` 와 `next_billing_date` 를 함께/둘 다 생략 → 400 `postpone_billing_input_invalid`
+   * - active/trial 이 아닌 구독 → 409 `subscription_not_active`
+   * - 해지 예약된 구독(`cancel()` 후) → 409 `subscription_scheduled_to_end`
+   *   (종료일이 정해져 있어 결제일을 미뤄도 기간이 늘지 않기 때문)
+   * - MoR 최초 결제 전 → 409 `subscription_not_activated`
+   */
+  async postponeBilling(subscriptionId, data) {
+    const prefix = this.getPublicPrefix();
+    return this.http.post(
+      `${prefix}/subscriptions/${subscriptionId}/postpone-billing`,
+      data
+    );
+  }
   /**
    * 구독 일시정지
    *

package/package.json

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