@monetize.software/sdk 3.0.0-alpha.9 → 3.0.0-beta.0

package/dist/core.d.ts

@@ -610,6 +610,13 @@ export declare class BillingClient {
     }): Promise<PaywallPrice[]>;
     /** Sync-снимок цен из последнего bootstrap'а. null = ещё не загружали. */
     getCachedPrices(): PaywallPrice[] | null;
+    /** Sync-снимок офферов из последнего bootstrap'а. null = bootstrap ещё не
+     *  загружали, пустой массив = бэк отдал пейвол без офферов. Бэк уже
+     *  применил серверный таргетинг (target_countries / target_emails /
+     *  targeting_mode из offer_settings) — наружу выезжает только то, что
+     *  применимо к текущему юзеру. Клиентская сторона остаётся ответственной
+     *  за price_id-matching и countdown (см. core/offer.ts → resolveOffer). */
+    getCachedOffers(): PaywallOffer[] | null;
     /**
      * Снимок того, какой язык SDK сейчас считает «языком юзера». Полезно для
      * синхронизации i18n хоста с тем, что фактически показывает пейвол — чтобы
@@ -736,6 +743,17 @@ export declare class BillingClient {
         errorUrl?: string;
         shopUrl?: string;
         trialDays?: number;
+        /** Активный offer для этой цены — резолвится host'ом через
+         *  `paywall.getOfferForPrice(priceId)?.offer.id` или
+         *  `findApplicableOffer(client.getCachedOffers(), priceId)?.id`. Без
+         *  явной передачи бэк сделает auto-resolve по email — но только для
+         *  end_date-офферов. duration_minutes-офферы тикают в clientStorage и
+         *  сервер их не видит: для них offerId ОБЯЗАН прийти от клиента, иначе
+         *  скидка не применится на чекауте, хотя UI её показывал.
+         *
+         *  Передавать offer-id всегда безопасно — бэк сам проверит applicable
+         *  ли offer к этому юзеру (страна/email/режим) и игнорирует если нет. */
+        offerId?: string;
         /**
          * Stage 1 защиты от дубликатов покупок. Идемпотентный ключ запроса
          * (UUID). Повторный вызов с тем же ключом вернёт тот же checkout-URL
@@ -762,7 +780,9 @@ export declare class BillingClient {
      * инвойсы). Опен-флоу управляется host'ом:
      *
      * ```ts
-     * const { url } = await billing.getCustomerPortalUrl();
+     * const { url } = await billing.getCustomerPortalUrl({
+     *   returnUrl: 'https://your-app.com/account'
+     * });
      * window.open(url, '_blank');
      * ```
      *
@@ -774,6 +794,14 @@ export declare class BillingClient {
      */
     getCustomerPortalUrl(opts?: {
         signal?: AbortSignal;
+        /** URL для return-button у провайдера (Stripe «Return to ...», Paddle
+         *  и Chargebee redirect_url'ы). Передавай туда страницу-аккаунт твоего
+         *  app'а — `https://your-app.com/account`. Без явного returnUrl бэк
+         *  применяет fallback в порядке: `paywall_settings.shop_url` →
+         *  custom_domain пейвола → NEXT_PUBLIC_ONLINE_ORIGIN (последнее — это
+         *  страница в самом online-сервисе, годится только для legacy
+         *  v2-iframe-флоу). */
+        returnUrl?: string;
     }): Promise<{
         url: string;
     }>;
@@ -939,6 +967,11 @@ export declare interface EventTrackerOptions {
     sendBeacon?: (url: string, data: BodyInit) => boolean;
 }
 
+/** Pick the offer applicable to a price. Targeted (`price_id === id`) wins
+ *  over the global default (`price_id === null`). Offers without a positive
+ *  `discount_percent` are ignored. */
+export declare function findApplicableOffer(offers: PaywallOffer[] | null | undefined, priceId: string): PaywallOffer | null;
+
 export declare function generateVisitorId(): string;
 
 export declare interface Identity {
@@ -1099,6 +1132,11 @@ export declare interface LocaleOverrides {
 
 export declare type OAuthProvider = 'google' | 'apple' | 'github' | 'facebook';
 
+/** Storage key under which a relative `duration_minutes` offer records its
+ *  first-view timestamp. Shared between the renderer (which writes the
+ *  start on first open) and the host SDK helpers (which read it). */
+export declare function offerStartStorageKey(offerId: string): string;
+
 export declare type OtpVerifyType = 'email' | 'recovery' | 'signup' | 'magiclink' | 'invite';
 
 export declare interface PaywallBootstrap {
@@ -1139,8 +1177,10 @@ export declare interface PaywallOffer {
     expires_at: string | null;
     /** Относительный таймер: сколько минут offer живёт **от первого просмотра
      *  пейвола** данным юзером. Старт хранится в clientStorage под ключом
-     *  `pw-offer-{id}-start`, по истечении — auto-cleanup. Используется, когда
-     *  бэк хочет показывать "remaining time" без жёсткой server-time, а считать
+     *  `pw-offer-{id}-start` и остаётся там **после** expiry — это
+     *  forever-marker, чтобы юзер не мог «фармить» offer (re-open пейвола
+     *  не запускает countdown заново). Используется, когда бэк хочет
+     *  показывать "remaining time" без жёсткой server-time, а считать
      *  относительно сессии юзера. expires_at имеет приоритет если задано. */
     duration_minutes?: number | null;
     price_id: string | null;
@@ -1167,7 +1207,7 @@ export declare interface PaywallPrice {
  *  идёт из `/user-state` и имеет минимум для access-gate'а), этот shape
  *  включает цену/валюту/discount — чтобы host мог нарисовать список подписок
  *  как в legacy customer portal'е. */
-declare interface PaywallPurchaseDetailed {
+export declare interface PaywallPurchaseDetailed {
     id: string;
     status: string | null;
     cancel_at: string | null;
@@ -1287,6 +1327,51 @@ export declare class QuotaExceededError extends PaywallError {
     });
 }
 
+/** Safe browser localStorage getter — returns null in SSR / private mode. */
+export declare function readBrowserOfferStart(offerId: string): string | null;
+
+/**
+ * Resolved view of a paywall offer — what host UI actually needs to render
+ * a strike-through price + countdown without re-implementing the math.
+ *
+ * `remainingMs` ticks down with wall-clock time and reaches 0 on expiry.
+ * `totalMs` stays constant — useful for progress bars / share-of-time UX.
+ * `expiresAt` is the Date.now()-comparable epoch ms of expiry.
+ *
+ * For offers without an expiry mechanism (no `expires_at` and no
+ * `duration_minutes`), `remainingMs`/`totalMs`/`expiresAt` are all `null`,
+ * but the resolved view is still returned — discount badge / strike-through
+ * still make sense for "perpetual sale" offers.
+ */
+export declare interface ResolvedOffer {
+    offer: PaywallOffer;
+    discountPercent: number;
+    remainingMs: number | null;
+    totalMs: number | null;
+    expiresAt: number | null;
+}
+
+/** Compute the resolved view of an offer. Pure, no side-effects. */
+export declare function resolveOffer(offer: PaywallOffer, opts?: ResolveOfferOptions): ResolvedOffer | null;
+
+export declare interface ResolveOfferOptions {
+    /** Current epoch ms. Inject for deterministic tests; default `Date.now()`. */
+    now?: number;
+    /**
+     * Synchronous reader for the `duration_minutes` start-timestamp ISO string.
+     * Host passes a closure over its sync storage (browser → `localStorage`,
+     * memory → in-process map). Return `null` if no start has been recorded.
+     *
+     * Intentionally synchronous, because consumers call this from UI render —
+     * an async StorageAdapter would force every price card to suspend.
+     *
+     * If omitted, `duration_minutes`-only offers return `expiresAt = null`,
+     * which makes the resolved view treat them as "not yet started" (the
+     * renderer is responsible for writing the start on first paywall view).
+     */
+    readStart?: (offerId: string) => string | null;
+}
+
 export declare const SDK_VERSION = "3.0.0-alpha.0";
 
 export declare type SignUpResult = {