@wavezfm/api 0.7.26 → 0.7.27

package/CHANGELOG.md

@@ -8,12 +8,12 @@
 - 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
 

package/README.md

@@ -435,6 +435,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/types.d.ts

@@ -1175,6 +1175,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;

package/package.json

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