@wavezfm/api 0.7.26 → 0.7.28

package/CHANGELOG.md

@@ -2,22 +2,28 @@
 
 ## Unreleased
 
+### Short prepaid Subscriber plans
+
+- Added exported `SubscriptionCycle` values `weekly` (seven days) and `fortnightly` (fifteen days) to subscription checkout, Mercado Pago prepaid payment and checkout status contracts. Both are single payments without automatic renewal; Stripe supports enabled prices in all eight billing currencies, while Mercado Pago remains the BRL default.
+- Confirm the current returned short-plan price with `expectedAmountMinor`, using whole JPY/KRW and hundredths for other currencies. The SDK forwards the buyer's confirmed amount without deriving a monthly fraction, changing providers or retrying payment.
+- Subscription gifts and the legacy Mercado Pago recurring helper retain monthly/annual cycles through the exported `RecurringSubscriptionCycle` type.
+
 ### 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.
+- Stripe annual upgrades retain the existing subscription's actual currency and charge the annual plan upfront. Remaining paid access is kept as time, then another 12 calendar months are added; the next annual renewal moves to the combined end. There is no monetary proration credit for the retained time. 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.
+- Added `billing.previewSubscriptionUpgrade()` with typed amounts, ISO currency, expiry, charge timing and retained-time dates: `remainingAccessSeconds`, `annualStartsAt`, `accessUntil`, `renewalAt` and `remainingTimeTreatment`. `billing.upgradeSubscription()` requires the returned `quoteId` after the buyer confirms the displayed charge and dates. Older quote-free calls and old monetary-credit quotes 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.
+- 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. Monthly/annual prepaid Stripe Pix remains BRL-only and does not renew automatically.
 - Added admin-session `adminMedia` listing, multipart upload and folder/asset management helpers and types. Moving or renaming an image changes its direct URL; folder rename/delete requires an empty folder.
 - Added session-authenticated bot appearance/access and deletion helpers, bot list `canEdit`/`canDelete`, and the `delete_protected_messages` permission to types and creation validation.
 - Typed effective private-command sender role, assigned room badge and platform role without changing raw event delivery. Documented platform staff hierarchy, protected bot targets, inline private replies and target-aware ephemeral visibility with local dismissal.

package/README.md

@@ -109,8 +109,10 @@ 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.
+other fields: the server replaces the appearance object and omitted image/color
+fields reset to `null`. `iconBackground` defaults to `true`; set it to `false`
+to remove the chat icon's tinted background and border without changing its artwork
+or the bot avatar. `setBotAppearanceAccess(roomId, enabled)` is platform-admin-only.
 
 ```ts
 await client.roomBot.sendMessage('room-id', {
@@ -435,6 +437,27 @@ not an available new recurring checkout flow. Annual-upgrade management for
 Mercado Pago applies only to existing managed recurring subscriptions, not new
 prepaid purchases.
 
+### Annual upgrade with remaining paid time
+
+Call `billing.previewSubscriptionUpgrade({ locale })` and display the returned
+quote before confirming with `billing.upgradeSubscription({ quoteId, locale })`.
+Stripe keeps the existing subscription currency and charges the annual price
+upfront. Remaining paid access is preserved as time, without a monetary
+proration credit, and another 12 calendar months are added after it.
+
+The quote exposes `remainingAccessSeconds`, `annualStartsAt`, `accessUntil`,
+`renewalAt` and `remainingTimeTreatment`. For Stripe the dates are ISO values,
+`remainingTimeTreatment` is `preserved_time` (including when no time remains),
+and the next annual renewal occurs at `renewalAt`, after the retained time plus
+the purchased year. Display the exact `amountDueMinor` and currency; invoice
+adjustments may affect the amount due. For existing Mercado Pago recurring
+subscriptions, the existing deferred-change flow remains: the amount due now
+is zero, the new time fields are null/zero and the treatment is `none`.
+
+Old monetary-credit quotes are not valid for this policy. Obtain a fresh quote
+and explicit buyer confirmation; never automatically retry a payment. Earlier
+paid upgrades are not changed retroactively.
+
 ## 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, 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";
+export type { BotPrivateCommand, AdminMediaAsset, AdminMediaFolder, AdminMediaListing, BillingCurrency, BillingCheckoutPolicy, SubscriptionPaymentMode, SubscriptionCycle, RecurringSubscriptionCycle, 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;
@@ -492,7 +492,7 @@ export declare function createApiClient(config: ApiClientConfig): {
             subscriptionPaymentMode?: import("./types.js").SubscriptionPaymentMode | null;
             announceInRoom?: boolean;
             announceRoomSlug?: string | null;
-            cycle?: string | null;
+            cycle?: import("./types.js").SubscriptionCycle | null;
             currency?: string | null;
             locale?: string | null;
             returnPath?: string | null;
@@ -549,7 +549,7 @@ export declare function createApiClient(config: ApiClientConfig): {
             expectedAmountMinor: number;
             recipientUsername?: string | null;
             recipientUserId?: string | null;
-            cycle?: string | null;
+            cycle?: import("./types.js").RecurringSubscriptionCycle | null;
             currency?: string | null;
             locale?: string | null;
             returnPath?: string | null;
@@ -576,7 +576,7 @@ export declare function createApiClient(config: ApiClientConfig): {
         createMercadoPagoPayment(input: {
             kind: string;
             expectedAmountMinor?: number;
-            cycle?: string | null;
+            cycle?: import("./types.js").SubscriptionCycle | null;
             quantity?: number;
             amountCents?: number;
             itemId?: string | null;
@@ -597,7 +597,7 @@ export declare function createApiClient(config: ApiClientConfig): {
         getMercadoPagoPaymentStatus(paymentId: string): Promise<import("./types.js").ApiSuccessResponse<Record<string, unknown>>>;
         createMercadoPagoSubscription(input: {
             expectedAmountMinor: number;
-            cycle?: string | null;
+            cycle?: import("./types.js").RecurringSubscriptionCycle | null;
             locale?: string | null;
             returnPath?: string | null;
             formData?: Record<string, unknown> | 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,4 +1,4 @@
-import type { ApiLike, CheckoutSessionResponse, CheckoutSessionStatus, SubscriptionPaymentMode, SubscriptionUpgradePreviewResponse } from "../types.js";
+import type { ApiLike, CheckoutSessionResponse, CheckoutSessionStatus, RecurringSubscriptionCycle, SubscriptionCycle, 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>>>;
@@ -15,11 +15,11 @@ export declare function createBillingResource(api: ApiLike): {
     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. */
+        /** Weekly and fortnightly are prepaid in all supported Stripe currencies; monthly/annual Stripe prepaid remains BRL Pix. */
         subscriptionPaymentMode?: SubscriptionPaymentMode | null;
         announceInRoom?: boolean;
         announceRoomSlug?: string | null;
-        cycle?: string | null;
+        cycle?: SubscriptionCycle | null;
         currency?: string | null;
         locale?: string | null;
         returnPath?: string | null;
@@ -76,7 +76,7 @@ export declare function createBillingResource(api: ApiLike): {
         expectedAmountMinor: number;
         recipientUsername?: string | null;
         recipientUserId?: string | null;
-        cycle?: string | null;
+        cycle?: RecurringSubscriptionCycle | null;
         currency?: string | null;
         locale?: string | null;
         returnPath?: string | null;
@@ -105,7 +105,8 @@ export declare function createBillingResource(api: ApiLike): {
         kind: string;
         /** Required for subscription_prepaid and gift_subscription_prepaid; BRL cents. */
         expectedAmountMinor?: number;
-        cycle?: string | null;
+        /** Subscription purchases accept short prepaid cycles; gifts remain monthly or annual. */
+        cycle?: SubscriptionCycle | null;
         quantity?: number;
         amountCents?: number;
         itemId?: string | null;
@@ -126,7 +127,8 @@ export declare function createBillingResource(api: ApiLike): {
     getMercadoPagoPaymentStatus(paymentId: string): Promise<import("../types.js").ApiSuccessResponse<Record<string, unknown>>>;
     createMercadoPagoSubscription(input: {
         expectedAmountMinor: number;
-        cycle?: string | null;
+        /** Legacy recurring-management flow; short terms use createMercadoPagoPayment(). */
+        cycle?: RecurringSubscriptionCycle | null;
         locale?: string | null;
         returnPath?: string | null;
         formData?: Record<string, unknown> | null;

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,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"}
+{"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,KAsBxB;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,KAO7B;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

@@ -789,6 +789,10 @@ export interface StoreCatalogResponse {
 /** Supported fiat currencies. JPY and KRW have zero-decimal Stripe checkout amounts. */
 export type BillingCurrency = "usd" | "brl" | "eur" | "czk" | "jpy" | "pln" | "krw" | "nok";
 export type SubscriptionPaymentMode = "recurring" | "prepaid";
+/** Short cycles are prepaid: exactly seven or fifteen days, without automatic renewal. */
+export type SubscriptionCycle = "monthly" | "annual" | "weekly" | "fortnightly";
+/** Recurring subscriptions and subscription gifts retain monthly or annual cycles. */
+export type RecurringSubscriptionCycle = "monthly" | "annual";
 export interface BillingCheckoutPolicy {
     stripeBrlEnabled: boolean;
     /** Applies to new Stripe BRL checkouts, not existing recurring renewals. */
@@ -883,6 +887,8 @@ export interface RoomBotAppearance {
     icon: string | null;
     /** HTTPS chat-avatar image; falls back to photoUrl, then the default robot. */
     chatImageUrl: string | null;
+    /** Whether the name badge has a tinted background and border. Defaults to true. */
+    iconBackground?: boolean;
 }
 export interface RoomBotAppearanceAccess {
     enabled: boolean;
@@ -1175,6 +1181,16 @@ export interface SubscriptionUpgradeQuote {
     expiresAt: string;
     chargeTiming: "immediate" | "next_billing_date";
     scheduledChangeAt: string | null;
+    /** Paid access retained by this upgrade, in whole seconds. */
+    remainingAccessSeconds: number;
+    /** Start of the additional annual coverage; ISO date for Stripe, null for Mercado Pago. */
+    annualStartsAt: string | null;
+    /** End of paid coverage after adding 12 calendar months; ISO date for Stripe. */
+    accessUntil: string | null;
+    /** Stripe's next annual renewal, after the retained time plus the purchased year. */
+    renewalAt: string | null;
+    /** Retained time is access, not a monetary proration credit. */
+    remainingTimeTreatment: "preserved_time" | "none";
 }
 export interface SubscriptionUpgradePreviewResponse {
     success: true;
@@ -1185,7 +1201,7 @@ export interface CheckoutSessionStatus {
     status: string | null;
     paymentStatus: string | null;
     kind: string | null;
-    cycle: "monthly" | "annual" | null;
+    cycle: SubscriptionCycle | null;
     subscriptionPaymentMode?: SubscriptionPaymentMode | null;
     /** Recorded amount in hundredths of the major currency unit. */
     amount?: number | null;

package/package.json

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