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

package/dist/ui.d.ts

@@ -248,10 +248,8 @@ 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 =
@@ -260,7 +258,7 @@ declare class AuthClient {
     signInAnonymously(input?: {
         captchaToken?: string;
         userMeta?: Record<string, string>;
-        forceCaptcha?: boolean;
+        forceNewAnon?: boolean;
     }): Promise<AuthSession>;
     /**
      * Внутренний resume — пробует /auth/refresh с сохранённым anon refresh_token.
@@ -625,6 +623,13 @@ 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 хоста с тем, что фактически показывает пейвол — чтобы
@@ -751,6 +756,17 @@ 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
@@ -777,7 +793,9 @@ 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');
      * ```
      *
@@ -789,6 +807,14 @@ 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;
     }>;
@@ -799,21 +825,31 @@ 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;
@@ -1266,8 +1302,10 @@ 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;
@@ -1383,12 +1421,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 {
@@ -1408,6 +1459,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;
@@ -1529,6 +1586,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 через сохранённый
@@ -1595,6 +1711,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`. */
@@ -1714,6 +1850,27 @@ declare class QuotaExceededError extends PaywallError {
     });
 }
 
+/**
+ * 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.
+ */
+declare interface ResolvedOffer {
+    offer: PaywallOffer;
+    discountPercent: number;
+    remainingMs: number | null;
+    totalMs: number | null;
+    expiresAt: number | null;
+}
+
 declare type SignUpResult = {
     kind: 'signed_in';
     session: AuthSession;

package/dist/ui.js

@@ -1,4 +1,4 @@
-import { P as o, b as r } from "./chunks/PaywallUI-BrDiS6zg.js";
+import { P as o, b as r } from "./chunks/PaywallUI-CDlJL5Em.js";
 export {
   o as PaywallUI,
   r as blockRegistry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monetize.software/sdk",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-beta.0",
   "description": "Monetize SDK — bundled billing client and paywall render engine for web and Chrome extensions",
   "type": "module",
   "sideEffects": false,