@monetize.software/sdk 3.0.0-alpha.2 → 3.0.0-alpha.21

package/dist/ui.d.ts

@@ -46,7 +46,9 @@ declare class ApiGatewayClient {
 
 declare interface ApiGatewayClientOptions {
     paywallId: string;
-    apiOrigin?: string;
+    /** Origin серверного API SDK — обязательное поле, тот же `custom_domain`, что
+     *  у BillingClient/AuthClient. См. {@link BillingClientOptions.apiOrigin}. */
+    apiOrigin: string;
     /** AuthClient — Bearer добавляется автоматически. На 401 от gateway клиент
      *  не делает refresh: AuthClient уже сделал lazy-refresh в getAccessToken. */
     auth?: AuthClient;
@@ -66,7 +68,28 @@ declare interface ApiGatewayClientOptions {
     onQuotaExceeded?: (err: QuotaExceededError) => void;
 }
 
-declare type AuthChangeListener = (session: AuthSession | null) => void;
+/** Дискриминатор для `onAuthChange`. Позволяет listener'у отличать первый
+ *  callback (восстановление сессии из storage / синтетический snapshot для
+ *  свежей подписки) от реальных переходов. Конвенция Supabase, минус события,
+ *  которых у нас нет (MFA, EMAIL_VERIFIED).
+ *
+ *  - INITIAL_SESSION — единственный гарантированный первый callback на каждую
+ *    подписку. Дёргается через microtask после resolve hydrated-promise, даже
+ *    если session=null. Listener'ы по этому event'у НЕ должны делать побочные
+ *    эффекты типа force-refetch — это просто доставка стартового state'а.
+ *  - SIGNED_IN — свежий вход: email/OAuth/anon, или появление session в этом
+ *    инстансе из другого контекста (storage.watch), когда раньше был null.
+ *  - SIGNED_OUT — signOut, revokeAllSessions, 401 на refresh, удаление session
+ *    из другого контекста.
+ *  - TOKEN_REFRESHED — тот же user, обновлённые токены: refresh(), либо
+ *    storage.watch когда содержимое сменилось но user.id остался.
+ *  - USER_UPDATED — изменился user.email / user.user_metadata (updatePassword,
+ *    upgradeAnonymousToEmail) при том же user.id.
+ *  - PASSWORD_RECOVERY — verifyOtp(type='recovery'). Listener знает, что надо
+ *    показать «set new password» UI вместо обычного post-login flow'а. */
+declare type AuthChangeEvent = 'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'PASSWORD_RECOVERY';
+
+declare type AuthChangeListener = (event: AuthChangeEvent, session: AuthSession | null) => void;
 
 declare class AuthClient {
     readonly paywallId: string;
@@ -225,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 =
@@ -237,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.
@@ -385,8 +406,19 @@ declare class AuthClient {
     }): Promise<void>;
     /**
      * Подписка на изменения session: signin/signup/refresh/signOut/expired-401.
-     * Колбек вызывается с текущим snapshot через microtask (если session есть)
-     * + на каждое реальное изменение. Возвращает unsubscribe.
+     *
+     * Гарантированный контракт: ПЕРВЫЙ callback каждому subscriber'у — всегда
+     * `event = 'INITIAL_SESSION'`, дёргается асинхронно после resolve hydrate'а
+     * (даже если session=null — listener получает explicit «нет сессии», а не
+     * молчание). Все последующие callback'и — реальные переходы с конкретным
+     * event'ом (SIGNED_IN / SIGNED_OUT / TOKEN_REFRESHED / USER_UPDATED /
+     * PASSWORD_RECOVERY).
+     *
+     * Это позволяет listener'у безопасно делать «only on real signin» побочные
+     * эффекты (force refetch balances и т.п.) через `event === 'SIGNED_IN'`,
+     * не путая их с восстановлением из storage.
+     *
+     * Возвращает unsubscribe.
      */
     onAuthChange(cb: AuthChangeListener): () => void;
     private isFresh;
@@ -412,6 +444,18 @@ declare class AuthClient {
     private readAnonRefreshToken;
     private writeAnonRefreshToken;
     private clearAnonRefreshToken;
+    /**
+     * Last-used auth method + email — для UI бейджа "Last used" и pre-fill'а
+     * email-инпута. Storage paywall-scoped, поэтому переключение между
+     * пейволами на одном host'е не пересекает данные. Чтение всегда возвращает
+     * объект — отсутствующие поля = null. */
+    getLastLogin(): Promise<LastLogin | null>;
+    /** Запись method и email атомарно (для email/password flows — оба известны
+     *  на момент signin/signup'а). OAuth-flows используют раздельные
+     *  recordLastLoginMethod (до popup) и recordLastLoginEmail (после exchange). */
+    private recordLastLogin;
+    private recordLastLoginMethod;
+    private recordLastLoginEmail;
     /**
      * Читает stable visitor_id из storage если он там уже есть. НЕ генерит:
      * AuthClient может быть инстанцирован раньше BillingClient, а синтетический
@@ -424,7 +468,9 @@ declare class AuthClient {
 
 declare interface AuthClientOptions {
     paywallId: string;
-    apiOrigin?: string;
+    /** Origin серверного API SDK — обязательное поле, тот же `custom_domain`, что
+     *  у BillingClient. См. {@link BillingClientOptions.apiOrigin}. */
+    apiOrigin: string;
     storage?: StorageAdapter;
     fetch?: typeof fetch;
     openPopup?: (url: string, name: string) => Window | null;
@@ -577,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 хоста с тем, что фактически показывает пейвол — чтобы
@@ -703,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
@@ -729,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');
      * ```
      *
@@ -741,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;
     }>;
@@ -751,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;
@@ -802,7 +886,15 @@ declare class BillingClient {
 
 declare interface BillingClientOptions {
     paywallId: string;
-    apiOrigin?: string;
+    /**
+     * Origin серверного API SDK — обязательное поле. Должно совпадать с
+     * `custom_domain`, заданным для пейвола в платформе (модерация привязывает
+     * домен к paywall_id). SDK сверяет это значение с `bootstrap.settings.custom_domain`
+     * на первом ответе и кидает `invalid_config` при расхождении — защита от
+     * опечаток интегратора. Промежуточный `appbox.space` в новом SDK НЕ
+     * используется (это только для legacy v2).
+     */
+    apiOrigin: string;
     identity?: Identity;
     storage?: StorageAdapter;
     capabilities?: string[];
@@ -848,6 +940,10 @@ export declare interface BlockContext {
     /** Текущая auth-session (snapshot из AuthClient). null = разлогинен. PaywallRoot
      *  подписан на onAuthChange и пробрасывает свежий snapshot сюда. */
     authSession: AuthSession | null;
+    /** Стартовый mode для AuthPanel — переопределяет дефолт 'signin'.
+     *  Выставляется AuthGate'ом когда host вызвал openSignup()/openSignin().
+     *  Остальные блоки игнорируют. */
+    initialAuthMode?: 'signin' | 'signup';
 }
 
 export declare interface BlockProps<B extends LayoutBlock = LayoutBlock> {
@@ -877,6 +973,18 @@ declare interface Identity {
     anonymousId?: string;
 }
 
+declare interface LastLogin {
+    method: LastLoginMethod;
+    email: string | null;
+}
+
+/** Метод, которым юзер залогинился в последний раз на этом пейволе.
+ *  Хранится per-paywall в storage и используется UI чтобы:
+ *   - предзаполнить email-инпут last-known email'ом;
+ *   - подсветить ту же OAuth-кнопку / email-форму бейджем "Last used".
+ *  `email` — email/password forms (signin или signup → confirm). */
+declare type LastLoginMethod = OAuthProvider | 'email';
+
 declare interface Layout {
     type: 'modal';
     blocks: LayoutBlock[];
@@ -892,9 +1000,13 @@ declare type LayoutBlock = {
 } | {
     type: 'price_grid';
     priceIds?: string[];
-    /** Раскладка карточек цен. `vertical` (default) — стек сверху вниз;
-     *  `horizontal` — ряд side-by-side. v2-аналог `view: 'default' | 'telegram'`. */
-    view?: 'vertical' | 'horizontal';
+    /** Раскладка карточек цен:
+     *  - `vertical` (default) — стек карточек сверху вниз;
+     *  - `compact` — компактный список (одна строка на цену, без карточки,
+     *    с разделителем); v2-аналог `view: 'telegram'`;
+     *  - `horizontal` — несколько карточек рядом в ряд; v2-only с момента
+     *    SDK 3.0 (legacy не показывает выбор этой опции в админке). */
+    view?: 'vertical' | 'compact' | 'horizontal';
     /** ID цены, которая помечается лейблом «популярный план». v2-аналог
      *  пары `price_label_id` + `price_label`. */
     popular_price_id?: string;
@@ -903,7 +1015,10 @@ declare type LayoutBlock = {
     popular_label?: string;
 } | {
     type: 'cta_button';
-    label: string;
+    /** Текст на кнопке. Если не задан — рендерер сам подберёт по
+     *  selected price'у и `trial_days`: "Start N-Day Free Trial",
+     *  "Get Lifetime Access", "Get Monthly Plan" и т.п. */
+    label?: string;
     action: 'checkout' | 'close';
     priceId?: string;
 } | {
@@ -922,8 +1037,23 @@ declare type LayoutBlock = {
     /** Скрывать панель, если юзер уже залогинен. По умолчанию true.
      *  false — показываем "Signed in as ... [Sign out]" даже после логина. */
     hide_when_authenticated?: boolean;
-    /** Заголовок над формой (h2). Если опущен — заголовок не рендерится. */
+    /** Кастомный заголовок над формой. Если задан — отображается вместо
+     *  дефолтного (определяется по mode'у — "Welcome back!" / "Welcome!" /
+     *  "Forgot password?" / ...). Без `submit_label` также используется как
+     *  submit-лейбл для signin (например `heading="Restore Purchases"` →
+     *  submit тоже "Restore Purchases"). Длинные heading (типа "Войдите,
+     *  чтобы продолжить покупку") в кнопку влезают плохо — задай
+     *  `submit_label` отдельно. */
     heading?: string;
+    /** Подпись под заголовком. Если опущен — подставляется default-текст
+     *  для текущего mode'а. Передай пустую строку чтобы скрыть подпись. */
+    subheading?: string;
+    /** Явный текст submit-кнопки. Имеет приоритет над heading-эхо. Нужен
+     *  для интентов с длинным descriptive heading'ом (preauth: "Войдите,
+     *  чтобы продолжить покупку" — кнопка только "Войти"). Для коротких
+     *  action-headings (restore: "Restore Purchases") опускай — эхо
+     *  даёт правильный UX. */
+    submit_label?: string;
 } | {
     /** Список фич/преимуществ продукта. v2-аналог `features_list` + `features_view`.
      *  До 5 элементов — рендерим как чек-лист с заголовком и описанием. */
@@ -947,6 +1077,35 @@ declare type LayoutBlock = {
         desc: string;
         count: number;
     }>;
+} | {
+    /** Money-back guarantee badge под cta_button: иконка + жирный заголовок +
+     *  пояснение мелким шрифтом + bottom divider, который визуально стыкуется
+     *  с current_session ниже. v2-аналог inline-блока в `PaywallPricing`. */
+    type: 'guarantee_badge';
+    /** Заголовок жирным. По умолчанию "100% Money-Back Guarantee". */
+    title?: string;
+    /** Подзаголовок мелким серым. По умолчанию
+     *  "Not satisfied? We'll refund you — no questions asked.". */
+    subtitle?: string;
+    /** Иконка слева от заголовка. По умолчанию `dollar_shield` —
+     *  зелёный shield с долларом (legacy-вид). `none` — без иконки. */
+    icon?: 'dollar_shield' | 'none';
+} | {
+    /** Urgency-баннер с countdown'ом до конца offer'а. Берёт первый offer
+     *  из `bootstrap.offers` с валидным `expires_at` или `duration_minutes`.
+     *  Авто-скрывается по истечении, чтобы не показывать "0d 0h 0m 0s".
+     *  Размещение — обычно первый блок в layout (над heading). */
+    type: 'offer_banner';
+    /** ID конкретного offer'а из bootstrap.offers. Если не задано — берётся
+     *  первый offer с активным таймером. */
+    offer_id?: string;
+    /** Текст слева от countdown'а. Если опущен — берётся `offer.label`,
+     *  иначе fallback "Limited-time offer". К нему дописывается процент:
+     *  "{title} {discount_percent}%" если discount задан. */
+    title?: string;
+    /** В превью админки — игнорировать expired-state, всё равно показывать
+     *  banner с нулями. Прод-режим — false (banner исчезает). */
+    force?: boolean;
 };
 
 /** Локализационные оверрайды для одного языка. Накатываются поверх дефолтного
@@ -1106,9 +1265,19 @@ declare interface PaywallEventPayloads {
     /** User-state изменился (bootstrap snapshot, getUser refresh, watcher tick).
      *  Дёргается также сразу с last-known user после первой подписки. */
     userChange: PaywallUser;
-    /** Auth-session изменилась (signin / signup / refresh / signout / 401-revoke).
-     *  null = разлогинен. Дёргается сразу с last-known session после первой подписки. */
-    authChange: AuthSession | null;
+    /** Auth-session изменилась. Payload содержит `event` (см. AuthChangeEvent —
+     *  INITIAL_SESSION / SIGNED_IN / SIGNED_OUT / TOKEN_REFRESHED / USER_UPDATED /
+     *  PASSWORD_RECOVERY) и `session` (null = разлогинен).
+     *
+     *  Гарантированный контракт: первый callback каждому subscriber'у — всегда
+     *  INITIAL_SESSION с восстановленной из storage сессией (или null если нет).
+     *  Дальше — реальные переходы. Listener'у с побочными эффектами вроде
+     *  force-refetch balances ловить SIGNED_IN, а не любой truthy session,
+     *  иначе reload страницы будет триггерить лишний запрос. */
+    authChange: {
+        event: AuthChangeEvent;
+        session: AuthSession | null;
+    };
     /** Триал заблокировал показ модалки. payload содержит свежий статус (после
      *  recordBlock). Для `mode: 'time'` — startedAt/expiresAt/remainingMs;
      *  для `mode: 'opens'` — remainingActions/totalActions. Хост может
@@ -1128,7 +1297,17 @@ declare interface PaywallEventPayloads {
 declare interface PaywallOffer {
     id: string;
     discount_percent: number | null;
+    /** Абсолютная expiration date (ISO 8601). Если задана — countdown отсчитывает
+     *  до этого момента, по истечении offer считается истёкшим. */
     expires_at: string | null;
+    /** Относительный таймер: сколько минут offer живёт **от первого просмотра
+     *  пейвола** данным юзером. Старт хранится в clientStorage под ключом
+     *  `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;
     label?: string | null;
 }
@@ -1178,6 +1357,14 @@ declare interface PaywallSettings {
     brand_color?: string | null;
     custom_css?: string | null;
     locale_default?: string | null;
+    /** Origin, на котором живёт бэк пейвола (тот же, что мерчант передаёт в
+     *  `BillingClientOptions.apiOrigin` при инициализации SDK). Бэк присылает
+     *  его на каждом bootstrap'е, SDK сверяет с init.apiOrigin — расхождение
+     *  даёт `invalid_config` (защита от опечатки интегратора). Без схемы:
+     *  "pay.your-domain.com" или "https://pay.your-domain.com" — оба валидны.
+     *  Для новых пейволов поле всегда заполнено (модерация требует custom_domain);
+     *  для legacy v2 может быть null/undefined. */
+    custom_domain?: string | null;
     runtime_mode?: 'client' | 'hybrid' | 'server' | 'client-native' | 'hybrid-native';
     /** true, если эквайринг пейвола в test-mode — SDK рисует TEST MODE бейдж. */
     is_test_mode?: boolean;
@@ -1234,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' | 'anon' | 'support' | 'awaiting_payment' | 'popup_blocked' | 'purchased' | null;
+    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 {
@@ -1274,6 +1474,10 @@ export declare class PaywallUI {
     private lastVisibility;
     /** Поведение open() при холодном bootstrap'е. См. PaywallUIOptions.mountThenLoad. */
     private mountThenLoad;
+    /** Inline-режим (live-preview редактора). См. PaywallUIOptions.inline. */
+    private inline;
+    /** Force-locale для I18nProvider. См. PaywallUIOptions.locale. */
+    private forceLocale;
     /** Текущий snapshot UI state-machine. Обновляется PaywallRoot'ом через
      *  `onState` prop; при close сбрасывается обратно в CLOSED_STATE. */
     private currentState;
@@ -1307,6 +1511,15 @@ export declare class PaywallUI {
      * почти всегда нежелательна.
      */
     setBootstrap(partial: Partial<PaywallBootstrap>): void;
+    /**
+     * Сменить force-locale на лету — для live-preview редактора админки, когда
+     * юзер переключает «Preview as user from <country>». Грузит соответствующий
+     * static-чанк и форсит re-render через handle.update. См. PaywallUIOptions.locale.
+     *
+     * Передай `null`/`undefined`, чтобы вернуть автоматическую резолв-логику
+     * (navigator.language → locale_default).
+     */
+    setLocale(locale: string | null | undefined): void;
     on<E extends PaywallEvent>(event: E, handler: PaywallEventHandler<E>): () => void;
     off<E extends PaywallEvent>(event: E, handler: PaywallEventHandler<E>): void;
     private emit;
@@ -1351,23 +1564,93 @@ export declare class PaywallUI {
      */
     openAuth(opts?: OpenOptions): void;
     /**
-     * Открывает модалку с anonymous-gate. AnonGate сразу зовёт
-     * `auth.signInAnonymously()`:
-     *   - если в storage есть `anonRefreshToken` — silent resume через
-     *     /auth/refresh, модалка схлопывается мгновенно (юзер видит лёгкий
-     *     спиннер ~100мс);
-     *   - иначе — fresh POST /auth/anonymous/signin без captcha (защита от
-     *     abuse держится на Supabase per-real-IP rate-limit + CF Bot Fight Mode).
+     * Шорткат над `openAuth()` — открывает модалку сразу на signin-форме.
+     * Эквивалент `openAuth()` (signin — дефолт). Существует для симметрии с
+     * `openSignup()` и читаемости host-кода:
+     *   - `paywall.openSignin()` — «вход в существующий аккаунт»
+     *   - `paywall.openSignup()` — «новая регистрация»
+     * Без managed-auth — no-op.
+     */
+    openSignin(opts?: OpenOptions): void;
+    /**
+     * Открывает модалку с auth-gate сразу в режиме регистрации (signup-mode
+     * AuthPanel'а — email/password/repeat). Если в paywall layout админ
+     * отключил allow_signup, AuthPanel игнорит mode и стартует с signin —
+     * соблюдается admin-конфиг.
+     * Без 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.
      *
-     * После успешного signIn'а модалка закрывается; host подхватывает свежую
-     * session через `auth.onAuthChange` или `paywall.onUserChange`. Для UX
-     * "просто залогиниться чтобы api-gateway работал, без покупок".
+     * Offer (countdown-скидка) автоматически резолвится из cached offers'ов
+     * через `getOfferForPrice(priceId)` и передаётся в createCheckout как
+     * `offerId` — чтобы duration_minutes-офферы тоже применились на бэке
+     * (для них нет server-side таймера, без явного offer-id скидка теряется).
      *
-     * Без managed-auth (`auth` не подключён) метод — no-op. Триал и
-     * visibility-таргетинг этот flow обходит: анон-логин не должен зависеть
-     * от страны юзера или trial-стейджа.
+     * Требования:
+     *  - `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 придётся рисовать
+     * самостоятельно.
      */
-    openAnonGate(opts?: OpenOptions): void;
+    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 через сохранённый
+     * refresh_token → fresh /auth/anonymous/signin. Дедуплицирует
+     * параллельные вызовы внутри AuthClient'а.
+     *
+     * Удобно для host-кнопок типа «Continue as guest» — host сам управляет
+     * loading-стейтом на своей кнопке, без полупустой модалки со спиннером.
+     * Без managed-auth — резолвится rejected promise'ом (нет AuthClient'а
+     * чтобы делать signin).
+     */
+    signInAnonymously(): Promise<AuthSession>;
     private openInternal;
     /** Применить gates ПОСЛЕ того, как модалка уже смонтирована (mount-then-load
      *  путь). Если gate блокирует — close() + emit. Если юзер уже сам закрыл
@@ -1422,6 +1705,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`. */
@@ -1498,6 +1801,8 @@ export declare interface PaywallUIOptions extends Omit<BillingClientOptions, 'au
      * флеш на blocked-странах/устройствах хуже воспринимаемой латентности.
      */
     mountThenLoad?: boolean;
+    /* Excluded from this release type: inline */
+    /* Excluded from this release type: locale */
 }
 
 declare interface PaywallUser {
@@ -1509,6 +1814,12 @@ declare interface PaywallUser {
         started_at: string | null;
         expires_at: string | null;
     } | null;
+    /** Был ли у юзера хотя бы один trial по этому пейволу когда-либо (включая
+     *  истёкшие и отменённые). Anti-abuse флаг для UI: CtaButton скрывает
+     *  "Start N-Day Free Trial" если true. Серверный enforcement в
+     *  `/start-checkout` дублирует — даже если UI обмануть, бэк не отдаст
+     *  trial_days в Stripe/Paddle. */
+    had_previous_trial: boolean;
 }
 
 declare interface PaywallUserPurchase {
@@ -1533,6 +1844,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;