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

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./core.cjs"),r=require("./chunks/PaywallUI-Bvx8nRL0.js");exports.ApiClient=e.ApiClient;exports.ApiGatewayClient=e.ApiGatewayClient;exports.AuthClient=e.AuthClient;exports.BillingClient=e.BillingClient;exports.EventTracker=e.EventTracker;exports.PaywallError=e.PaywallError;exports.QuotaExceededError=e.QuotaExceededError;exports.SDK_VERSION=e.SDK_VERSION;exports.STORAGE_KEYS=e.STORAGE_KEYS;exports.createStorage=e.createStorage;exports.ensureVisitorId=e.ensureVisitorId;exports.generateVisitorId=e.generateVisitorId;exports.PaywallUI=r.PaywallUI;exports.blockRegistry=r.blockRegistry;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/index-CzDSBl4d.js"),r=require("./chunks/PaywallUI-CCwYgagL.js");exports.ApiClient=e.ApiClient;exports.ApiGatewayClient=e.ApiGatewayClient;exports.AuthClient=e.AuthClient;exports.BillingClient=e.BillingClient;exports.EventTracker=e.EventTracker;exports.PaywallError=e.PaywallError;exports.QuotaExceededError=e.QuotaExceededError;exports.SDK_VERSION=e.SDK_VERSION;exports.STORAGE_KEYS=e.STORAGE_KEYS;exports.createStorage=e.createStorage;exports.ensureVisitorId=e.ensureVisitorId;exports.findApplicableOffer=e.findApplicableOffer;exports.generateVisitorId=e.generateVisitorId;exports.offerStartStorageKey=e.offerStartStorageKey;exports.readBrowserOfferStart=e.readBrowserOfferStart;exports.resolveOffer=e.resolveOffer;exports.PaywallUI=r.PaywallUI;exports.blockRegistry=r.blockRegistry;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -262,10 +262,8 @@ export declare class AuthClient {
      * когда сервер начнёт возвращать challenge_required в риск-сценариях,
      * SDK сможет передать proof-of-something обратно без breaking change.
      *
-     * `forceCaptcha: true` пропускает шаги 1-2 и сразу делает /signin (создаёт
-     * нового anon-юзера). Используется в switch-account flow. Имя поля исторически
-     * остаётся `forceCaptcha`, хотя капчи там больше нет — менять имя ломает
-     * host-сигнатуру; смысл «принудительно новая anon-сессия» сохранён.
+     * `forceNewAnon: true` пропускает шаги 1-2 и сразу делает /signin (создаёт
+     * нового anon-юзера). Используется в switch-account flow.
      *
      * Параллельные вызовы дедуплицируются через `inflightAnonSignin` — два
      * click'а на «Войти как гость» не создадут двух anon-юзеров (два /signup =
@@ -274,7 +272,7 @@ export declare class AuthClient {
     signInAnonymously(input?: {
         captchaToken?: string;
         userMeta?: Record<string, string>;
-        forceCaptcha?: boolean;
+        forceNewAnon?: boolean;
     }): Promise<AuthSession>;
     /**
      * Внутренний resume — пробует /auth/refresh с сохранённым anon refresh_token.
@@ -639,6 +637,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 хоста с тем, что фактически показывает пейвол — чтобы
@@ -765,6 +770,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
@@ -791,7 +807,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');
      * ```
      *
@@ -803,6 +821,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;
     }>;
@@ -813,21 +839,31 @@ export declare class BillingClient {
      * `/api/v1/paywall/[id]/user` без unstable_cache, потому что list для UI
      * должен быть свежим после cancel-а.
      *
-     * Auth: Bearer обязателен (через AuthClient). Без Bearer — 401 от бэка,
-     * пробрасываем как PaywallError('http_401'). Гость → пустой список.
+     * Auth (два пути):
+     *  - Bearer (через AuthClient) — user.id резолвится из сессии, identity
+     *    в query игнорируется.
+     *  - `apiKey` + `identity.email`/`identity.userId` — server-SDK путь для
+     *    интеграций со своей авторизацией. Бэк проверяет, что identity линкована
+     *    к этому пейволу (защита от cross-paywall lookup).
+     * Без auth и без apiKey+identity — `identity_required`.
      */
     listPurchases(opts?: {
         signal?: AbortSignal;
     }): Promise<PaywallPurchaseDetailed[]>;
     /**
-     * Отменить подписку. Бэк проверит что subscription принадлежит auth-юзеру
-     * и сделает cancel у acquiring'а (Stripe/Paddle/Chargebee). По умолчанию
-     * cancel в конце текущего периода — юзер сохраняет access до renewal date'ы.
+     * Отменить подписку. Бэк проверит, что subscription принадлежит юзеру
+     * (Bearer-путь — из сессии; apiKey-путь — из identity), и сделает cancel у
+     * acquiring'а (Stripe/Paddle/Chargebee/Overpay). По умолчанию cancel в
+     * конце текущего периода — юзер сохраняет access до renewal date'ы.
      *
-     * `reason` обязательна (валидация на бэке). Удобно собрать через select
-     * причин в host-UI, как в legacy customer portal'е.
+     * `reason` обязательна (валидация на бэке).
      *
-     * Auth: Bearer обязателен.
+     * Auth (два пути):
+     *  - Bearer (через AuthClient) — стандартный путь для UI customer-portal'a.
+     *  - `apiKey` + `identity.email`/`identity.userId` — для self-service UI на
+     *    бэке клиента со своей авторизацией. Бэк дополнительно фильтрует
+     *    subscription по paywall_id, чтобы owner пейвола A не отменил подписку
+     *    пейвола B.
      */
     cancelSubscription(params: {
         subscriptionId: string;
@@ -984,6 +1020,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 GetAccessOptions {
@@ -1150,6 +1191,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 interface OpenOptions {
     identity?: Identity;
     /** Принудительно открыть, минуя pre-paywall trial check. По умолчанию SDK
@@ -1327,8 +1373,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;
@@ -1355,7 +1403,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;
@@ -1444,12 +1492,25 @@ declare type PaywallStateListener = (state: PaywallStateSnapshot) => void;
  * один call onState; повторы (`useSyncExternalStore`-friendly).
  */
 export declare interface PaywallStateSnapshot {
-    /** Модалка отрендерена и видна. False — closed (или ещё не открывалась). */
+    /** Модалка отрендерена и видна. False — closed (или ещё не открывалась).
+     *  Может быть false при `processing=true` — direct-checkout (paywall.checkout)
+     *  делает bootstrap + createCheckout headless до того, как решит надо ли
+     *  монтировать модалку. */
     open: boolean;
     /** Что показывается в модалке. null когда `open=false`. */
     view: 'loading' | 'error' | 'layout' | 'auth' | 'support' | 'awaiting_payment' | 'popup_blocked' | 'purchased' | null;
     /** Заполнено только когда `view === 'error'`. */
     error: PaywallError | null;
+    /** SDK делает фоновую работу для `paywall.checkout(priceId)` — bootstrap,
+     *  visibility/trial-gates, createCheckout — до того, как реально нужна
+     *  UI-модалка. Хост на этой фазе может задизейблить свою кнопку и
+     *  показать спиннер прямо на ней, чтобы у юзера не было ощущения «клик
+     *  ничего не сделал». Сбрасывается в false сразу после mountAndShow
+     *  (модалка взяла на себя UI), либо после headless reject (already-paid,
+     *  ошибка createCheckout без модалки). Для `paywall.open()`-flow всегда
+     *  false: там модалка появляется мгновенно со своим LoadingView и
+     *  отдельный «processing» не нужен. */
+    processing: boolean;
 }
 
 export declare class PaywallUI {
@@ -1469,6 +1530,12 @@ export declare class PaywallUI {
     private watcher;
     private tracker;
     private purchased;
+    /** View, с которым последний раз монтировалась модалка. Гейтит аналитику
+     *  `paywall_opened`/`paywall_viewed` на реальный пейвол (`'layout'`): открытие
+     *  support / standalone-auth / awaiting_payment эмитит публичный `'open'` и
+     *  `'ready'`, но это не «пейвол открыт/просмотрен» — иначе саппорт-клик шлёт
+     *  ложный `paywall_opened`. */
+    private lastMountedView;
     /** Lazy-инстанс TrialStore. Резолвится при первом open(), когда уже знаем
      *  `bootstrap.settings.trial`. null — триал отключён в конфиге пейвола. */
     private trialStore;
@@ -1590,6 +1657,65 @@ export declare class PaywallUI {
      * Без managed-auth — no-op.
      */
     openSignup(opts?: OpenOptions): void;
+    /**
+     * Direct-checkout: создать checkout-URL по конкретной цене и сразу открыть
+     * платёжного провайдера, минуя layout с тарифами. Полезно когда
+     * host-приложение рендерит pricing-карточки/таблицу собственным UI и
+     * хочет, чтобы клик по «Buy / Get this plan» вёл прямо в Stripe/Paddle.
+     *
+     * **Late-mount UX.** В отличие от `open()`, модалка не появляется во время
+     * фоновой работы (bootstrap + visibility/trial gates + createCheckout).
+     * Хост на этой фазе показывает busy-state прямо на своей кнопке (через
+     * `state.processing === true` из `paywall.getState()` — или автоматически
+     * через `<PaywallButton priceId>` в sdk-react). Модалка монтируется
+     * ТОЛЬКО когда реально нужна UI:
+     *  - `checkout_mode='preauth'` + managed-auth + не залогинен → auth-gate
+     *    (форма signin'а); после успеха auto-resume в createCheckout.
+     *  - popup провайдера заблокирован браузером → popup_blocked view с
+     *    retry-кнопкой под fresh user gesture.
+     *  - popup открылся успешно → awaiting_payment view (индикатор «оплати
+     *    в новой вкладке» + I've paid).
+     *
+     * Что эмитится без модалки:
+     *  - `purchase_completed{restored:true, priceId}` когда юзер уже подписан
+     *    (cached user, fresh bootstrap, или 409 hasActivePurchase от бэка) —
+     *    headless reject;
+     *  - `error` когда createCheckout упал или identity.email отсутствует;
+     *  - `visibility_blocked` / `trial_blocked` — стандартные gate-эвенты.
+     *
+     * Что эмитится одновременно с модалкой:
+     *  - `checkout_started{priceId, url, acquiring}` ровно когда headless URL
+     *    получен, ДО mount'а awaiting_payment/popup_blocked.
+     *
+     * Offer (countdown-скидка) автоматически резолвится из cached offers'ов
+     * через `getOfferForPrice(priceId)` и передаётся в createCheckout как
+     * `offerId` — чтобы duration_minutes-офферы тоже применились на бэке
+     * (для них нет server-side таймера, без явного offer-id скидка теряется).
+     *
+     * Требования:
+     *  - `identity.email` должен быть выставлен (через `opts.identity`, либо
+     *    managed-auth, либо ранний `setIdentity`/`paywall.open({identity})`).
+     *    Без email бэк `/start-checkout` 400'нёт; SDK эмитнет `error`.
+     *  - В `checkout_mode='preauth'` без managed-auth — backend требует
+     *    email-юзера; убедись что `identity.email` явно задан.
+     *
+     * Без модалки совсем (когда host рендерит свой awaiting-payment экран) —
+     * используй `paywall.billing.createCheckout({priceId, offerId})` напрямую,
+     * но тогда auth-gate / popup_blocked / awaiting_payment придётся рисовать
+     * самостоятельно.
+     */
+    checkout(priceId: string, opts?: OpenOptions): void;
+    /** Headless prep-work для `checkout(priceId, opts)`: bootstrap → gates →
+     *  preauth check → createCheckout → mount модалки с финальным view.
+     *  Вынесено отдельным методом ради чистого async/await flow вместо вложенных
+     *  then-chain'ов (5+ ветвей). Любая ошибка не пробрасывается наружу: эмитим
+     *  через `paywall.emit('error')` и выходим — host подписан на `error`-event. */
+    private runDirectCheckout;
+    /** Trial-check без mount'а (для late-mount direct-checkout). Возвращает
+     *  true если trial заблокировал — caller должен прекратить flow. На любой
+     *  storage-ошибке log+продолжаем (не блокируем продажу). */
+    private checkTrialBeforeCheckout;
+    private applyProcessing;
     /**
      * Headless anonymous signin без открытия модалки. Внутри:
      * idempotent (если уже анон — instant return) → resume через сохранённый
@@ -1656,6 +1782,26 @@ export declare class PaywallUI {
     }): Promise<PaywallPrice[]>;
     /** Sync-снимок цен. null — bootstrap ещё не загружали. */
     getCachedPrices(): PaywallPrice[] | null;
+    /** Sync-снимок офферов. null = bootstrap не загружали, [] = пейвол без офферов.
+     *  Бэк уже применил серверный targeting (страны/email/режим) — наружу
+     *  выезжает только то, что применимо к текущему юзеру. */
+    getCachedOffers(): PaywallOffer[] | null;
+    /**
+     * Резолвит активный offer для конкретной цены: price_id-таргетинг +
+     * countdown (`expires_at` ИЛИ `duration_minutes` от первого открытия
+     * пейвола, см. clientStorage `pw-offer-{id}-start`).
+     *
+     * Read-only — НЕ записывает start для `duration_minutes`-офферов. Запись
+     * стартует только когда модалка реально открыта (renderer'ом). До этого
+     * `getOfferForPrice` вернёт `null` для duration-only офферов, чтобы
+     * страницы-хосты вне модалки (pricing, landing) не активировали countdown
+     * раньше времени.
+     *
+     * Хост-странице нужен countdown, который тикает каждую секунду — для
+     * этого использовать React-хук `usePaywallOffer(priceId)` из sdk-react
+     * либо обёртку поверх `setInterval(1000)` + повторный вызов этого метода.
+     */
+    getOfferForPrice(priceId: string): ResolvedOffer | null;
     /** Снимок текущего «языка юзера» — proxy над `billing.getUserLanguage()`.
      *  Используй, чтобы синхронизировать i18n host'а с тем, что фактически
      *  показывает пейвол. См. подробности в `BillingClient.getUserLanguage`. */
@@ -1775,6 +1921,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 = {

package/dist/index.js

@@ -1,19 +1,23 @@
-import { ApiClient as t, ApiGatewayClient as a, AuthClient as i, BillingClient as l, EventTracker as o, PaywallError as n, QuotaExceededError as E, SDK_VERSION as s, STORAGE_KEYS as S, createStorage as c, ensureVisitorId as d, generateVisitorId as g } from "./core.js";
-import { P as y, b as A } from "./chunks/PaywallUI-BrDiS6zg.js";
+import { A as r, a as s, b as t, B as i, E as o, P as l, Q as f, S as n, c as S, d as E, e as d, f as c, h as p, o as A, r as g, i as y } from "./chunks/index-CLB1AgLg.js";
+import { P as b, b as w } from "./chunks/PaywallUI-CDlJL5Em.js";
 export {
-  t as ApiClient,
-  a as ApiGatewayClient,
-  i as AuthClient,
-  l as BillingClient,
+  r as ApiClient,
+  s as ApiGatewayClient,
+  t as AuthClient,
+  i as BillingClient,
   o as EventTracker,
-  n as PaywallError,
-  y as PaywallUI,
-  E as QuotaExceededError,
-  s as SDK_VERSION,
+  l as PaywallError,
+  b as PaywallUI,
+  f as QuotaExceededError,
+  n as SDK_VERSION,
   S as STORAGE_KEYS,
-  A as blockRegistry,
-  c as createStorage,
+  w as blockRegistry,
+  E as createStorage,
   d as ensureVisitorId,
-  g as generateVisitorId
+  c as findApplicableOffer,
+  p as generateVisitorId,
+  A as offerStartStorageKey,
+  g as readBrowserOfferStart,
+  y as resolveOffer
 };
 //# sourceMappingURL=index.js.map

package/dist/ui.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/PaywallUI-Bvx8nRL0.js");exports.PaywallUI=e.PaywallUI;exports.blockRegistry=e.blockRegistry;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/PaywallUI-CCwYgagL.js");exports.PaywallUI=e.PaywallUI;exports.blockRegistry=e.blockRegistry;
 //# sourceMappingURL=ui.cjs.map