@wavezfm/api 0.7.24 → 0.7.26

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+### Subscription prices, currency and localization
+
+- Subscription checkout, subscription gifts and room gifts now require `expectedAmountMinor`, the current price shown to the buyer. Use whole yen/won for JPY/KRW and hundredths for the other supported currencies. Room gifts confirm the requested count times the displayed monthly unit price; fewer eligible recipients can reduce the final charge.
+- Mercado Pago payment submission requires `expectedAmountMinor` for `subscription_prepaid` and `gift_subscription_prepaid`, using the displayed Mercado Pago checkout configuration's BRL amount multiplied by 100. The field remains optional for other payment kinds.
+- New Mercado Pago Subscriber purchases remain prepaid, including card payments, without automatic renewal. The retained legacy `createMercadoPagoSubscription()` helper requires a confirmed BRL amount but does not make new recurring checkout available; Mercado Pago upgrade management applies only to existing managed recurring subscriptions.
+- The updated server rejects missing confirmations with `BILLING_PRICE_CONFIRMATION_REQUIRED` and price changes with `BILLING_PRICE_CHANGED` before starting payment. Older clients must reload current prices and obtain buyer confirmation; the SDK never accepts a replacement price or retries payment automatically.
+- Stripe annual upgrades retain the existing subscription's actual currency and credit unused monthly time on the invoice. That credit reduces the payment instead of adding monthly days to the new annual period. Current cycle synchronization resolves provider state rather than accepting an outdated webhook snapshot.
+- New Stripe subscription product names use the supplied locale across all eleven website languages, including Czech. Existing paid invoices keep their historical names. Fixed local annual defaults were updated; explicit configured prices retain priority, and existing recurring subscriptions are not repriced retroactively.
+
+### Annual subscription upgrade confirmation
+
+- Added `billing.previewSubscriptionUpgrade()` with typed amounts, ISO currency, proration credit, expiry and charge timing. `billing.upgradeSubscription()` now requires the returned `quoteId` after the buyer confirms the displayed charge. Older quote-free calls are rejected by the server before charging; no automatic retry or confirmation is performed by the SDK.
+
 ### October 10 contract synchronization
 
 - Added typed `billingCheckoutPolicy`, eight supported fiat currencies and donation currency maps, checkout payment modes, returned payment mode/amount/currency, and `subscriptionPaymentMode` plus announcement options to subscription checkout. Prepaid Stripe Pix remains BRL-only and does not renew automatically.

package/README.md

@@ -105,8 +105,9 @@ if (access.canEdit) {
 ```
 
 `icon` accepts a Tabler identifier or HTTPS image URL for the badge beside the
-name and is the chat-avatar fallback when `chatImageUrl` is unset. `photoUrl`
-is the profile photo and fallback when neither chat image nor icon is set.
+name only; changing it does not change the bot avatar. The chat avatar uses
+`chatImageUrl`, then `photoUrl`, then the default robot. `photoUrl` also supplies
+the profile photo.
 Image artwork retains its own colors. Send the full appearance when preserving
 other fields: the server replaces all four fields and omitted fields reset to
 `null`. `setBotAppearanceAccess(roomId, enabled)` is platform-admin-only.
@@ -387,12 +388,20 @@ item. The server rejects unsupported currencies rather than defaulting to USD.
 Prices are configured values; selecting a currency does not request a live FX
 conversion. Existing checkout helpers retain their string currency inputs.
 
+Subscription checkout and gifts require `expectedAmountMinor`, the current price
+the buyer reviewed for the provider, currency and cycle. Use whole units for
+JPY/KRW and hundredths for the other currencies. Obtain live prices before
+enabling confirmation; `BILLING_PRICE_CHANGED` requires a new review rather than
+an automatic retry. Room gifts confirm requested count × monthly unit price;
+fewer eligible recipients can reduce the charge.
+
 ```ts
 const { data: status } = await client.system.status();
 if (status.billingCheckoutPolicy?.stripeBrlEnabled) {
   const { data: checkout } = await client.billing.createSubscriptionCheckout({
     currency: 'brl', provider: 'stripe', cycle: 'monthly',
     subscriptionPaymentMode: 'prepaid', locale: 'pt-BR', uiMode: 'hosted',
+    expectedAmountMinor: confirmedStripeBrlMonthlyAmountMinor,
   });
   // Hosted Stripe Pix: a one-time month or year, without automatic renewal.
   if (checkout.checkoutUrl) console.log(checkout.checkoutUrl);
@@ -403,6 +412,9 @@ if (status.billingCheckoutPolicy?.stripeBrlEnabled) {
 payments and prevents new recurring BRL Stripe checkout. Existing renewals are
 unchanged. Explicit `subscriptionPaymentMode: 'recurring'` requires card support;
 Stripe prepaid Pix is BRL-only. Mercado Pago remains the default BRL provider.
+New Mercado Pago Subscriber purchases are prepaid card/Pix payments without
+automatic renewal; submit the returned payment form through
+`createMercadoPagoPayment()`.
 Check payment status before treating a purchase as fulfilled: pending Pix
 payments do not grant access. `getCheckoutSessionStatus()` exposes the payment
 mode, amount and currency along with the Stripe session status.
@@ -412,6 +424,17 @@ a major currency unit for every currency**, including JPY/KRW. For example,
 1,000 JPY is represented as `100000`. Stripe checkout converts JPY/KRW to
 whole-unit minor amounts. Format them without fractional currency digits.
 
+Mercado Pago payment submission requires `expectedAmountMinor` for `subscription_prepaid` and
+`gift_subscription_prepaid`, using the displayed Mercado Pago checkout
+configuration's `mercadoPago.amount` multiplied by 100. It remains optional for
+other payment kinds. Do not substitute the Stripe BRL price for this amount.
+
+The SDK retains `createMercadoPagoSubscription()` for compatibility with the
+legacy subscription handler, which also requires a confirmed BRL amount. It is
+not an available new recurring checkout flow. Annual-upgrade management for
+Mercado Pago applies only to existing managed recurring subscriptions, not new
+prepaid purchases.
+
 ## Admin CDN images
 
 `client.adminMedia` uses an administrator **user session** and CSRF protection;

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { createAdminMediaResource } from "./resources/adminMedia.js";
 export { parseRoomQueueSnapshot } from "./utils/roomQueue.js";
 export { formatMentionText } from "./utils/chat.js";
 export { createRoomBotRealtimeClient } from "./realtime/roomBot.js";
-export type { BotPrivateCommand, AdminMediaAsset, AdminMediaFolder, AdminMediaListing, BillingCurrency, BillingCheckoutPolicy, SubscriptionPaymentMode, CheckoutSessionStatus, RoomBotAppearance, RoomBotAppearanceAccess, CountryFlagSettings, TeamDirectory, StageHoverSettings, UserProfileOptions, ApiClientConfig, ApiLike, ApiQuery, ApiQueryValue, ApiRequestOptions, ApiSuccessResponse, AuthMode, AuthUser, BadgeAssignment, ChatImageUploadResponse, ChatLinkReview, ChatMediaPreviewResponse, ChatMessage, CheckoutSessionResponse, GifFavorite, Giveaway, GiveawayEntry, GiveawayJoinEligibility, GiveawayListResponse, GiveawayMutationResponse, GiveawayPrizeDeliveryStatus, GiveawayPrizeType, GiveawayScope, GiveawayStatus, InventoryResponse, InventoryCatalogEntry, InventoryCatalogItem, PurchaseHistoryCategory, PurchaseHistoryCurrency, PurchaseHistoryItem, PurchaseHistoryOptions, PurchaseHistoryResponse, LastFmAccountProfile, LastFmLinkStatus, LastFmWriteResponse, MediaSearchResponse, YouTubeRegionAvailability, RoomOwnershipTransferChallenge, RoomOwnershipTransferResult, MediaSearchResult, MiscShopUserState, MiscStoreCurrency, MiscStoreItemKind, MiscStoreRenderMode, NotificationCenterClearResponse, NotificationCenterStatus, PlaylistExternalImportResult, PlaylistExternalImportSource, PlaylistJsonExport, PlaylistJsonImportResult, PlaylistJsonTrack, PlaylistSummary, PlaylistTrack, PlaylistTrackAvailabilityInput, PlaylistTrackAvailabilityResult, PlaylistTrackSearchResult, PrivateConversation, PrivateMessage, PrivateMessageCustomEmoji, PrivateMessageReply, PrivateMessageSendInput, PrivateMessageSendResponse, PrivateMessageUser, RoomBotPermission, RoomExternalMediaMetadataResponse, RoomExternalMediaProvider, RoomExternalMediaSubtitleTrack, RoomExternalMediaValidationResponse, RoomActiveUser, RoomCustomEmoji, RoomLinkFiltersUpdateInput, RoomGuestPresenceResponse, RoomGuestViewer, RoomGlobalLimits, RoomGlobalLimitsUpdateInput, RoomPlaybackHistoryEntry, RoomPermission, RoomPermissionOverrideMap, RoomQueueEntry, RoomQueuePlayback, RoomQueueSnapshot, RoomQueueStatusResponse, RoomQueueUser, RoomQueueViewerStatus, RoomRoleName, RoomSettingsUpdateInput, RoomStateSnapshot, RoomBotEditMessageInput, RoomBotChatEmbed, RoomBotMessageReplyInput, RoomBotEventsResponse, RoomPresenceEventFilterType, RoomBotQueueAddResponse, RoomBotRealtimeClient, RoomBotRealtimeSendMessageInput, RoomBotRealtimeOptions, RoomActionActor, RoomBotUserKickedPayload, RoomBotUserBannedPayload, RoomBotUserUnbannedPayload, RoomBotQueueRemovalReason, RoomBotQueueRemovedPayload, RoomBotQueueLeftPayload, RoomBotTrackSkippedPayload, RoomBotQueueReorderedPayload, RoomBotMessageDeletedPayload, RoomBotChatClearedPayload, RoomBotUserUpdatedPayload, RoomBotRoomSettingsUpdatedPayload, RoomBotRealtimeEventPayloads, RoomBotRealtimeEventName, RoomBotSendMessageInput, RoomBotSendMessageResponse, RoomBotState, RoomBotToken, RoomBotSettings, RoomBotSettingsUpdateInput, RoomPresenceEvent, RoomPresenceEventType, RoomSummary, RoomSystemAlert, RoomEvent, RoomEventApprovalStatus, RoomEventListResponse, RoomEventMutationResponse, RoomEventScope, RoomEventStatus, RoomEventSubmissionInput, WavezApiLocale, WavezApiMessageKey, WavezApiMessages, WavezApiMessageValues, StoreCatalogResponse, StoreCatalogItem, StoreCatalogSection, MiscStoreItem, AdminSystemHealth, AdminSystemStatus, SystemDonationGoal, SystemAlert, SystemAlertAppearance, SystemAlertCustomEmoji, SystemAlertInput, SystemAlertResponse, SystemHealth, SystemPublicStats, SystemProgressionXp, SystemStatus, TwoFactorStatus, UserSettings, UserSystemAlert, UserProfile, UserBlockState, WalletBalance, WebSocketLike, WsPacket, } from "./types.js";
+export type { BotPrivateCommand, AdminMediaAsset, AdminMediaFolder, AdminMediaListing, BillingCurrency, BillingCheckoutPolicy, SubscriptionPaymentMode, SubscriptionUpgradeQuote, SubscriptionUpgradePreviewResponse, CheckoutSessionStatus, RoomBotAppearance, RoomBotAppearanceAccess, CountryFlagSettings, TeamDirectory, StageHoverSettings, UserProfileOptions, ApiClientConfig, ApiLike, ApiQuery, ApiQueryValue, ApiRequestOptions, ApiSuccessResponse, AuthMode, AuthUser, BadgeAssignment, ChatImageUploadResponse, ChatLinkReview, ChatMediaPreviewResponse, ChatMessage, CheckoutSessionResponse, GifFavorite, Giveaway, GiveawayEntry, GiveawayJoinEligibility, GiveawayListResponse, GiveawayMutationResponse, GiveawayPrizeDeliveryStatus, GiveawayPrizeType, GiveawayScope, GiveawayStatus, InventoryResponse, InventoryCatalogEntry, InventoryCatalogItem, PurchaseHistoryCategory, PurchaseHistoryCurrency, PurchaseHistoryItem, PurchaseHistoryOptions, PurchaseHistoryResponse, LastFmAccountProfile, LastFmLinkStatus, LastFmWriteResponse, MediaSearchResponse, YouTubeRegionAvailability, RoomOwnershipTransferChallenge, RoomOwnershipTransferResult, MediaSearchResult, MiscShopUserState, MiscStoreCurrency, MiscStoreItemKind, MiscStoreRenderMode, NotificationCenterClearResponse, NotificationCenterStatus, PlaylistExternalImportResult, PlaylistExternalImportSource, PlaylistJsonExport, PlaylistJsonImportResult, PlaylistJsonTrack, PlaylistSummary, PlaylistTrack, PlaylistTrackAvailabilityInput, PlaylistTrackAvailabilityResult, PlaylistTrackSearchResult, PrivateConversation, PrivateMessage, PrivateMessageCustomEmoji, PrivateMessageReply, PrivateMessageSendInput, PrivateMessageSendResponse, PrivateMessageUser, RoomBotPermission, RoomExternalMediaMetadataResponse, RoomExternalMediaProvider, RoomExternalMediaSubtitleTrack, RoomExternalMediaValidationResponse, RoomActiveUser, RoomCustomEmoji, RoomLinkFiltersUpdateInput, RoomGuestPresenceResponse, RoomGuestViewer, RoomGlobalLimits, RoomGlobalLimitsUpdateInput, RoomPlaybackHistoryEntry, RoomPermission, RoomPermissionOverrideMap, RoomQueueEntry, RoomQueuePlayback, RoomQueueSnapshot, RoomQueueStatusResponse, RoomQueueUser, RoomQueueViewerStatus, RoomRoleName, RoomSettingsUpdateInput, RoomStateSnapshot, RoomBotEditMessageInput, RoomBotChatEmbed, RoomBotMessageReplyInput, RoomBotEventsResponse, RoomPresenceEventFilterType, RoomBotQueueAddResponse, RoomBotRealtimeClient, RoomBotRealtimeSendMessageInput, RoomBotRealtimeOptions, RoomActionActor, RoomBotUserKickedPayload, RoomBotUserBannedPayload, RoomBotUserUnbannedPayload, RoomBotQueueRemovalReason, RoomBotQueueRemovedPayload, RoomBotQueueLeftPayload, RoomBotTrackSkippedPayload, RoomBotQueueReorderedPayload, RoomBotMessageDeletedPayload, RoomBotChatClearedPayload, RoomBotUserUpdatedPayload, RoomBotRoomSettingsUpdatedPayload, RoomBotRealtimeEventPayloads, RoomBotRealtimeEventName, RoomBotSendMessageInput, RoomBotSendMessageResponse, RoomBotState, RoomBotToken, RoomBotSettings, RoomBotSettingsUpdateInput, RoomPresenceEvent, RoomPresenceEventType, RoomSummary, RoomSystemAlert, RoomEvent, RoomEventApprovalStatus, RoomEventListResponse, RoomEventMutationResponse, RoomEventScope, RoomEventStatus, RoomEventSubmissionInput, WavezApiLocale, WavezApiMessageKey, WavezApiMessages, WavezApiMessageValues, StoreCatalogResponse, StoreCatalogItem, StoreCatalogSection, MiscStoreItem, AdminSystemHealth, AdminSystemStatus, SystemDonationGoal, SystemAlert, SystemAlertAppearance, SystemAlertCustomEmoji, SystemAlertInput, SystemAlertResponse, SystemHealth, SystemPublicStats, SystemProgressionXp, SystemStatus, TwoFactorStatus, UserSettings, UserSystemAlert, UserProfile, UserBlockState, WalletBalance, WebSocketLike, WsPacket, } from "./types.js";
 import type { ApiClientConfig } from "./types.js";
 export declare function createApiClient(config: ApiClientConfig): {
     api: import("./core/api.js").WavezApi;
@@ -479,11 +479,16 @@ export declare function createApiClient(config: ApiClientConfig): {
         getCheckoutSessionStatus(sessionId: string): Promise<import("./types.js").ApiSuccessResponse<import("./types.js").CheckoutSessionStatus>>;
         cancelSubscription(): Promise<import("./types.js").ApiSuccessResponse<Record<string, unknown>>>;
         resumeSubscription(): Promise<import("./types.js").ApiSuccessResponse<Record<string, unknown>>>;
-        upgradeSubscription(input?: {
+        previewSubscriptionUpgrade(input?: {
+            locale?: string | null;
+        }): Promise<import("./types.js").ApiSuccessResponse<import("./types.js").SubscriptionUpgradePreviewResponse>>;
+        upgradeSubscription(input: {
+            quoteId: string;
             locale?: string | null;
         }): Promise<import("./types.js").ApiSuccessResponse<Record<string, unknown>>>;
         listSubscriptionPaymentHistory(): Promise<import("./types.js").ApiSuccessResponse<unknown[]>>;
-        createSubscriptionCheckout(input?: {
+        createSubscriptionCheckout(input: {
+            expectedAmountMinor: number;
             subscriptionPaymentMode?: import("./types.js").SubscriptionPaymentMode | null;
             announceInRoom?: boolean;
             announceRoomSlug?: string | null;
@@ -541,6 +546,7 @@ export declare function createApiClient(config: ApiClientConfig): {
             uiMode?: string | null;
         }): Promise<import("./types.js").ApiSuccessResponse<import("./types.js").CheckoutSessionResponse>>;
         createSubscriptionGiftCheckout(input: {
+            expectedAmountMinor: number;
             recipientUsername?: string | null;
             recipientUserId?: string | null;
             cycle?: string | null;
@@ -555,6 +561,7 @@ export declare function createApiClient(config: ApiClientConfig): {
             provider?: string | null;
         }): Promise<import("./types.js").ApiSuccessResponse<import("./types.js").CheckoutSessionResponse>>;
         createSubscriptionRoomGiftCheckout(input: {
+            expectedAmountMinor: number;
             roomSlug: string;
             count?: number;
             excludeActiveSubscribers?: boolean;
@@ -568,6 +575,7 @@ export declare function createApiClient(config: ApiClientConfig): {
         }): Promise<import("./types.js").ApiSuccessResponse<import("./types.js").CheckoutSessionResponse>>;
         createMercadoPagoPayment(input: {
             kind: string;
+            expectedAmountMinor?: number;
             cycle?: string | null;
             quantity?: number;
             amountCents?: number;
@@ -587,7 +595,8 @@ export declare function createApiClient(config: ApiClientConfig): {
             formData?: Record<string, unknown> | null;
         }): Promise<import("./types.js").ApiSuccessResponse<Record<string, unknown>>>;
         getMercadoPagoPaymentStatus(paymentId: string): Promise<import("./types.js").ApiSuccessResponse<Record<string, unknown>>>;
-        createMercadoPagoSubscription(input?: {
+        createMercadoPagoSubscription(input: {
+            expectedAmountMinor: number;
             cycle?: string | null;
             locale?: string | null;
             returnPath?: string | null;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/resources/billing.d.ts

@@ -1,13 +1,20 @@
-import type { ApiLike, CheckoutSessionResponse, CheckoutSessionStatus, SubscriptionPaymentMode } from "../types.js";
+import type { ApiLike, CheckoutSessionResponse, CheckoutSessionStatus, SubscriptionPaymentMode, SubscriptionUpgradePreviewResponse } from "../types.js";
 export declare function createBillingResource(api: ApiLike): {
     getCheckoutSessionStatus(sessionId: string): Promise<import("../types.js").ApiSuccessResponse<CheckoutSessionStatus>>;
     cancelSubscription(): Promise<import("../types.js").ApiSuccessResponse<Record<string, unknown>>>;
     resumeSubscription(): Promise<import("../types.js").ApiSuccessResponse<Record<string, unknown>>>;
-    upgradeSubscription(input?: {
+    previewSubscriptionUpgrade(input?: {
+        locale?: string | null;
+    }): Promise<import("../types.js").ApiSuccessResponse<SubscriptionUpgradePreviewResponse>>;
+    /** Confirm a current server quote after displaying its charge to the buyer. */
+    upgradeSubscription(input: {
+        quoteId: string;
         locale?: string | null;
     }): Promise<import("../types.js").ApiSuccessResponse<Record<string, unknown>>>;
     listSubscriptionPaymentHistory(): Promise<import("../types.js").ApiSuccessResponse<unknown[]>>;
-    createSubscriptionCheckout(input?: {
+    createSubscriptionCheckout(input: {
+        /** Confirmed catalog amount in Stripe minor units: whole JPY/KRW; hundredths otherwise. */
+        expectedAmountMinor: number;
         /** Prepaid Stripe Pix is available only for BRL; recurring requires card support. */
         subscriptionPaymentMode?: SubscriptionPaymentMode | null;
         announceInRoom?: boolean;
@@ -66,6 +73,7 @@ export declare function createBillingResource(api: ApiLike): {
         uiMode?: string | null;
     }): Promise<import("../types.js").ApiSuccessResponse<CheckoutSessionResponse>>;
     createSubscriptionGiftCheckout(input: {
+        expectedAmountMinor: number;
         recipientUsername?: string | null;
         recipientUserId?: string | null;
         cycle?: string | null;
@@ -80,6 +88,8 @@ export declare function createBillingResource(api: ApiLike): {
         provider?: string | null;
     }): Promise<import("../types.js").ApiSuccessResponse<CheckoutSessionResponse>>;
     createSubscriptionRoomGiftCheckout(input: {
+        /** Requested count times the displayed monthly unit price, in minor units. */
+        expectedAmountMinor: number;
         roomSlug: string;
         count?: number;
         excludeActiveSubscribers?: boolean;
@@ -93,6 +103,8 @@ export declare function createBillingResource(api: ApiLike): {
     }): Promise<import("../types.js").ApiSuccessResponse<CheckoutSessionResponse>>;
     createMercadoPagoPayment(input: {
         kind: string;
+        /** Required for subscription_prepaid and gift_subscription_prepaid; BRL cents. */
+        expectedAmountMinor?: number;
         cycle?: string | null;
         quantity?: number;
         amountCents?: number;
@@ -112,7 +124,8 @@ export declare function createBillingResource(api: ApiLike): {
         formData?: Record<string, unknown> | null;
     }): Promise<import("../types.js").ApiSuccessResponse<Record<string, unknown>>>;
     getMercadoPagoPaymentStatus(paymentId: string): Promise<import("../types.js").ApiSuccessResponse<Record<string, unknown>>>;
-    createMercadoPagoSubscription(input?: {
+    createMercadoPagoSubscription(input: {
+        expectedAmountMinor: number;
         cycle?: string | null;
         locale?: string | null;
         returnPath?: string | null;

package/dist/resources/billing.js

@@ -11,14 +11,18 @@ export function createBillingResource(api) {
         resumeSubscription() {
             return api.post("/billing/subscription/resume", {});
         },
+        previewSubscriptionUpgrade(input) {
+            return api.post("/billing/subscription/upgrade/preview", input ?? {});
+        },
+        /** Confirm a current server quote after displaying its charge to the buyer. */
         upgradeSubscription(input) {
-            return api.post("/billing/subscription/upgrade", input ?? {});
+            return api.post("/billing/subscription/upgrade", input);
         },
         listSubscriptionPaymentHistory() {
             return api.get("/billing/subscription/payment-history");
         },
         createSubscriptionCheckout(input) {
-            return api.post("/billing/checkout/subscription", input ?? {});
+            return api.post("/billing/checkout/subscription", input);
         },
         createDiamondCheckout(input) {
             return api.post("/billing/checkout/diamonds", input ?? {});

package/dist/resources/billing.js.map

@@ -1 +1 @@
-{"version":3,"file":"billing.js","sourceRoot":"","sources":["../../src/resources/billing.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAC9C,OAAO;QACH,wBAAwB,CAAC,SAAiB;YACtC,OAAO,GAAG,CAAC,GAAG,CAAwB,kCAAkC,EAAE;gBACtE,KAAK,EAAE,EAAE,SAAS,EAAE;aACvB,CAAC,CAAC;QACP,CAAC;QAED,kBAAkB;YACd,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,EAAE,CACL,CAAC;QACN,CAAC;QAED,kBAAkB;YACd,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,EAAE,CACL,CAAC;QACN,CAAC;QAED,mBAAmB,CAAC,KAAkC;YAClD,OAAO,GAAG,CAAC,IAAI,CACX,+BAA+B,EAC/B,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,8BAA8B;YAC1B,OAAO,GAAG,CAAC,GAAG,CACV,uCAAuC,CAC1C,CAAC;QACN,CAAC;QAED,0BAA0B,CAAC,KAW1B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,gCAAgC,EAChC,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,qBAAqB,CAAC,KAOrB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,4BAA4B,EAC5B,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,sBAAsB,CAAC,KAStB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,KAAK,CACR,CAAC;QACN,CAAC;QAED,0BAA0B,CACtB,MAAc,EACd,KAOC;YAED,OAAO,GAAG,CAAC,IAAI,CACX,2BAA2B,kBAAkB,CAAC,MAAM,CAAC,WAAW,EAChE,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,4BAA4B,CAAC,KAO5B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,mCAAmC,EACnC,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,yBAAyB,CAAC,KAWzB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,iCAAiC,EACjC,KAAK,CACR,CAAC;QACN,CAAC;QAED,8BAA8B,CAAC,KAa9B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,qCAAqC,EACrC,KAAK,CACR,CAAC;QACN,CAAC;QAED,kCAAkC,CAAC,KAWlC;YACG,OAAO,GAAG,CAAC,IAAI,CACX,0CAA0C,EAC1C,KAAK,CACR,CAAC;QACN,CAAC;QAED,wBAAwB,CAAC,KAmBxB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,KAAK,CACR,CAAC;QACN,CAAC;QAED,2BAA2B,CAAC,SAAiB;YACzC,OAAO,GAAG,CAAC,GAAG,CACV,gCAAgC,kBAAkB,CAAC,SAAS,CAAC,SAAS,CACzE,CAAC;QACN,CAAC;QAED,6BAA6B,CAAC,KAK7B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,mCAAmC,EACnC,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,gBAAgB;YACZ,OAAO,GAAG,CAAC,GAAG,CAAY,wBAAwB,CAAC,CAAC;QACxD,CAAC;QAED,YAAY,CAAC,MAAc;YACvB,OAAO,GAAG,CAAC,IAAI,CACX,kBAAkB,kBAAkB,CAAC,MAAM,CAAC,OAAO,EACnD,EAAE,CACL,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"billing.js","sourceRoot":"","sources":["../../src/resources/billing.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAC9C,OAAO;QACH,wBAAwB,CAAC,SAAiB;YACtC,OAAO,GAAG,CAAC,GAAG,CAAwB,kCAAkC,EAAE;gBACtE,KAAK,EAAE,EAAE,SAAS,EAAE;aACvB,CAAC,CAAC;QACP,CAAC;QAED,kBAAkB;YACd,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,EAAE,CACL,CAAC;QACN,CAAC;QAED,kBAAkB;YACd,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,EAAE,CACL,CAAC;QACN,CAAC;QAED,0BAA0B,CAAC,KAAkC;YACzD,OAAO,GAAG,CAAC,IAAI,CACX,uCAAuC,EACvC,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,+EAA+E;QAC/E,mBAAmB,CAAC,KAAkD;YAClE,OAAO,GAAG,CAAC,IAAI,CACX,+BAA+B,EAC/B,KAAK,CACR,CAAC;QACN,CAAC;QAED,8BAA8B;YAC1B,OAAO,GAAG,CAAC,GAAG,CACV,uCAAuC,CAC1C,CAAC;QACN,CAAC;QAED,0BAA0B,CAAC,KAa1B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,gCAAgC,EAChC,KAAK,CACR,CAAC;QACN,CAAC;QAED,qBAAqB,CAAC,KAOrB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,4BAA4B,EAC5B,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,sBAAsB,CAAC,KAStB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,KAAK,CACR,CAAC;QACN,CAAC;QAED,0BAA0B,CACtB,MAAc,EACd,KAOC;YAED,OAAO,GAAG,CAAC,IAAI,CACX,2BAA2B,kBAAkB,CAAC,MAAM,CAAC,WAAW,EAChE,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,4BAA4B,CAAC,KAO5B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,mCAAmC,EACnC,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,yBAAyB,CAAC,KAWzB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,iCAAiC,EACjC,KAAK,CACR,CAAC;QACN,CAAC;QAED,8BAA8B,CAAC,KAc9B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,qCAAqC,EACrC,KAAK,CACR,CAAC;QACN,CAAC;QAED,kCAAkC,CAAC,KAalC;YACG,OAAO,GAAG,CAAC,IAAI,CACX,0CAA0C,EAC1C,KAAK,CACR,CAAC;QACN,CAAC;QAED,wBAAwB,CAAC,KAqBxB;YACG,OAAO,GAAG,CAAC,IAAI,CACX,8BAA8B,EAC9B,KAAK,CACR,CAAC;QACN,CAAC;QAED,2BAA2B,CAAC,SAAiB;YACzC,OAAO,GAAG,CAAC,GAAG,CACV,gCAAgC,kBAAkB,CAAC,SAAS,CAAC,SAAS,CACzE,CAAC;QACN,CAAC;QAED,6BAA6B,CAAC,KAM7B;YACG,OAAO,GAAG,CAAC,IAAI,CACX,mCAAmC,EACnC,KAAK,IAAI,EAAE,CACd,CAAC;QACN,CAAC;QAED,gBAAgB;YACZ,OAAO,GAAG,CAAC,GAAG,CAAY,wBAAwB,CAAC,CAAC;QACxD,CAAC;QAED,YAAY,CAAC,MAAc;YACvB,OAAO,GAAG,CAAC,IAAI,CACX,kBAAkB,kBAAkB,CAAC,MAAM,CAAC,OAAO,EACnD,EAAE,CACL,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/types.d.ts

@@ -876,11 +876,12 @@ export interface RoomBotSettings {
 }
 export type RoomBotSettingsUpdateInput = Pick<RoomBotSettings, "botName" | "commandPrefix" | "permissions" | "allowSelfRename">;
 export interface RoomBotAppearance {
+    /** Profile photo and chat-avatar fallback when chatImageUrl is unset. */
     photoUrl: string | null;
     color: string | null;
-    /** Tabler identifier or HTTPS image URL for the badge beside the name. */
+    /** Tabler identifier or HTTPS image URL for the name badge only; never the avatar. */
     icon: string | null;
-    /** HTTPS image URL for the chat avatar. */
+    /** HTTPS chat-avatar image; falls back to photoUrl, then the default robot. */
     chatImageUrl: string | null;
 }
 export interface RoomBotAppearanceAccess {
@@ -1161,6 +1162,24 @@ export interface CheckoutSessionResponse {
     publishableKey?: string | null;
     [key: string]: unknown;
 }
+export interface SubscriptionUpgradeQuote {
+    /** Opaque account-bound confirmation token; expires after five minutes. */
+    quoteId: string;
+    provider: "stripe" | "mercadopago";
+    currency: Uppercase<BillingCurrency>;
+    /** Provider minor units: whole yen/won for JPY/KRW, hundredths otherwise. */
+    amountDueMinor: number;
+    /** Annual plan price before invoice taxes, discounts or account adjustments. */
+    annualAmountMinor: number;
+    prorationCreditMinor: number;
+    expiresAt: string;
+    chargeTiming: "immediate" | "next_billing_date";
+    scheduledChangeAt: string | null;
+}
+export interface SubscriptionUpgradePreviewResponse {
+    success: true;
+    quote: SubscriptionUpgradeQuote;
+}
 export interface CheckoutSessionStatus {
     sessionId: string;
     status: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavezfm/api",
-  "version": "0.7.24",
+  "version": "0.7.26",
   "description": "Official JavaScript/TypeScript API client for WavezFM.",
   "homepage": "https://docs.wavez.fm/docs",
   "repository": {