@monetize.software/sdk 3.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,1695 @@
+import { ComponentType } from 'preact';
+
+declare type Acquiring = 'stripe' | 'paddle' | 'chargebee' | 'overpay' | 'freemius';
+
+export declare interface AnalyticsOptions {
+    enabled?: boolean;
+    /** Полный URL до /events. По умолчанию — `${apiOrigin}/api/v1/paywall/${id}/events`. */
+    endpoint?: string;
+    flushIntervalMs?: number;
+    maxBufferSize?: number;
+    /** Тестовый override fetch'а (jsdom/Vitest). */
+    fetch?: typeof fetch;
+    /** Тестовый override sendBeacon'а. */
+    sendBeacon?: (url: string, data: BodyInit) => boolean;
+}
+
+export declare class ApiClient {
+    private opts;
+    constructor(opts: ApiClientOptions);
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+}
+
+export declare interface ApiClientOptions {
+    apiOrigin: string;
+    paywallId: string;
+    getAuthToken?: () => string | null | Promise<string | null>;
+    capabilities?: string[];
+    fetch?: typeof fetch;
+}
+
+export declare interface ApiGatewayCallParams {
+    /** UUID api-провайдера из платформы (`paywall_internal_api_providers.id`). */
+    providerId: string;
+    /** Путь после провайдера: `v1/chat/completions`, `messages`, и т.д.
+     *  Конкатенируется через `/`. Пустая строка/undefined = root провайдера. */
+    path?: string;
+    method?: 'GET' | 'POST';
+    /** JSON-сериализуемый объект → application/json. FormData → multipart с
+     *  авто-boundary. ReadableStream/Blob/string — пробрасываются как есть.
+     *  Если undefined и method='POST' — отправляется пустое тело. */
+    body?: unknown;
+    /** Дополнительные хедеры. Перетирают наши, кроме Authorization (его всегда
+     *  ставим из auth) и X-Paywall-Id. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+
+export declare class ApiGatewayClient {
+    readonly paywallId: string;
+    readonly apiOrigin: string;
+    private auth;
+    private userId;
+    private capabilities;
+    private customFetch;
+    private onChargeSuccess;
+    private onQuotaExceeded;
+    constructor(opts: ApiGatewayClientOptions);
+    call(params: ApiGatewayCallParams): Promise<Response>;
+}
+
+export declare interface ApiGatewayClientOptions {
+    paywallId: string;
+    apiOrigin?: string;
+    /** AuthClient — Bearer добавляется автоматически. На 401 от gateway клиент
+     *  не делает refresh: AuthClient уже сделал lazy-refresh в getAccessToken. */
+    auth?: AuthClient;
+    /** Headless-сценарий или legacy-флоу: явный userId вместо Bearer.
+     *  Передаётся как `X-User-ID`. Если задан и `auth` — Bearer выигрывает. */
+    userId?: string;
+    capabilities?: string[];
+    fetch?: typeof fetch;
+    /** Хук для оптимистичного декремента балансов в BillingClient.
+     *  ApiGatewayClient его дёргает на 200 (success), передавая queryType из
+     *  ответа (если бэк его прислал в `X-Query-Type`) или undefined.
+     *  Парсить body для извлечения queryType ApiGatewayClient НЕ умеет — это
+     *  было бы лишним чтением body, а главное — body может быть стримом. */
+    onChargeSuccess?: (queryType: string | undefined) => void;
+    /** Хук для рефетча балансов после 402. BillingClient ходит к /balances
+     *  и обновляет state, чтобы UI показал актуальный счётчик. */
+    onQuotaExceeded?: (err: QuotaExceededError) => void;
+}
+
+export declare type AuthChangeListener = (session: AuthSession | null) => void;
+
+export declare class AuthClient {
+    readonly paywallId: string;
+    readonly apiOrigin: string;
+    private storage;
+    private api;
+    private openPopup;
+    private session;
+    private hydrated;
+    private inflightRefresh;
+    /** Дедупликация параллельных signInAnonymously: два click'а на «Войти как
+     *  гость» должны попасть в одного юзера, не плодить двух (двойная капча +
+     *  второй /signup создал бы вторую запись с потерянным trial-балансом). */
+    private inflightAnonSignin;
+    private listeners;
+    private storageUnwatch;
+    private destroyed;
+    /** Pending OAuth flows: state → {verifier, userMeta, startedAt}. Между
+     *  startOAuthFlow и completeOAuthFlow. GC'атся через OAUTH_FLOW_TTL_MS. */
+    private oauthFlows;
+    constructor(opts: AuthClientOptions);
+    /**
+     * Подписывается на изменения session-ключа в storage из других контекстов:
+     *  - Chrome Extension: `chrome.storage.onChanged` шарится popup ↔ background ↔
+     *    options ↔ content script. Логин в одном контексте → остальные сразу
+     *    эмитят onAuthChange и в getAccessToken отдают свежий Bearer.
+     *  - Web: `window.storage` event фаерится в ДРУГИХ вкладках того же origin'а
+     *    (своя вкладка свой setItem не получает — петель нет).
+     *
+     * Loop-guard: сравниваем content по полям session перед applySession, чтобы
+     * не фрить лишних onAuthChange при идентичной перезаписи. Вызовы из других
+     * контекстов с тем же содержимым (пересохранение) — no-op.
+     */
+    private startStorageWatch;
+    private applyExternalSession;
+    /**
+     * Promise гидратации session из storage. До его resolve getCachedSession()
+     * может ещё вернуть null. getAccessToken/refresh/signOut/sign* awaitят его
+     * сами, наружу выставляем для UI'я, чтобы он мог дождаться initial state
+     * прежде чем рисовать «logged-out» вспышку.
+     */
+    ready(): Promise<void>;
+    /** Sync snapshot без сетевых запросов. null = разлогинен или ещё не гидрировались. */
+    getCachedSession(): AuthSession | null;
+    getCachedUser(): AuthUser | null;
+    /**
+     * access_token для Authorization-хедера. Если до expiry < REFRESH_LEEWAY_MS,
+     * делает lazy refresh. null = разлогинен или refresh упал на 401 (refresh
+     * token revoked) — вызывающему стоит редиректить на логин.
+     *
+     * Сетевые/5xx ошибки refresh бросаются — текущий access ещё валиден,
+     * вызывающий может попробовать запрос с ним; следующий getAccessToken
+     * попробует refresh снова.
+     */
+    getAccessToken(): Promise<string | null>;
+    signInWithEmail(input: {
+        email: string;
+        password: string;
+        userMeta?: Record<string, string>;
+        /** Idempotency-key (UUID) — повторный submit при двойном клике вернёт
+         *  тот же результат вместо второго запроса в GoTrue. Без передачи
+         *  inflight-дедупликации нет; SDK не дедуплицирует auth по умолчанию,
+         *  потому что email/password можно поменять между кликами. */
+        idempotencyKey?: string;
+    }): Promise<AuthSession>;
+    /**
+     * Signup. Если в Supabase включён email confirm — сервер возвращает
+     * `{status: 'confirmation_required', user}` и НЕ выдаёт токены. В этом
+     * случае setSession не зовётся, юзер должен пройти OTP/magic-link
+     * (отдельная фича следующего PR).
+     */
+    signUp(input: {
+        email: string;
+        password: string;
+        userMeta?: Record<string, string>;
+        /** Idempotency-key (UUID). Защита от двойного клика на «Sign Up» —
+         *  без неё бэк может создать trial-balances и отправить confirmation-email
+         *  дважды. */
+        idempotencyKey?: string;
+    }): Promise<SignUpResult>;
+    /**
+     * Повторная отправка confirmation-email после signUp с включённым
+     * email-confirm. Использует GoTrue `/resend` type='signup'. Бэк всегда
+     * отдаёт ok (anti-enumeration), кроме 429 при rate-limit (~1 раз/мин на
+     * email на стороне Supabase). Host обрабатывает 429 показом «подождите
+     * минуту»; остальное — как success.
+     */
+    resendConfirmation(input: {
+        email: string;
+        /** Защита от двойного клика. */
+        idempotencyKey?: string;
+    }): Promise<void>;
+    /**
+     * Email-OTP / signin без password. Шлёт 6-значный код юзеру на email.
+     * Anti-enumeration: бэк всегда отдаёт ok, поэтому метод не различает
+     * «email не существует» и «отправлено» — следующий шаг (verifyOtp) сам
+     * упадёт invalid_otp если юзера нет. Под капотом GoTrue с create_user=true,
+     * так что новые юзеры через OTP логинятся за один шаг (отправка → ввод
+     * кода → session).
+     */
+    sendOtp(input: {
+        email: string;
+        createUser?: boolean;
+        userMeta?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Верификация OTP. type='email' (signin/signup-by-otp) — после успеха
+     * setSession и onAuthChange. type='recovery' — после /requestPasswordReset:
+     * выдаётся короткоживущий access_token для последующего updatePassword.
+     * Мы храним recovery-session так же, как обычную: SDK не различает «можно
+     * залогиниться» vs «можно сменить пароль» — это одна и та же session.
+     */
+    verifyOtp(input: {
+        email: string;
+        token: string;
+        type?: OtpVerifyType;
+        userMeta?: Record<string, string>;
+    }): Promise<AuthSession>;
+    /**
+     * Запрос recovery email. Бэк всегда ok, чтобы не палить enumeration.
+     * Юзер вводит код из письма в SDK-ui → verifyOtp({type:'recovery'}) →
+     * получает session → updatePassword.
+     */
+    requestPasswordReset(input: {
+        email: string;
+    }): Promise<void>;
+    /**
+     * Меняет пароль текущей session. Работает после verifyOtp({type:'recovery'})
+     * (recovery-session) и после обычного логина — оба случая дают валидный
+     * access_token. Если session нет — бросаем PaywallError('not_authenticated')
+     * до сетевого запроса, чтобы UI не дёргал бэк впустую.
+     */
+    updatePassword(input: {
+        password: string;
+    }): Promise<void>;
+    /**
+     * Анонимный signin (Supabase user без email). Лестница попыток:
+     *
+     *   1. Если уже залогинены анонимно (session.user.is_anonymous === true) —
+     *      no-op, возвращаем текущую session. Идемпотентно для UI'я, который
+     *      может звать signInAnonymously() в render-loop'е, не отслеживая state.
+     *
+     *   2. Resume через сохранённый anon refresh_token (`STORAGE_KEYS.anonRefreshToken`).
+     *      Если токен есть — пробуем `/auth/refresh` им. Success → setSession,
+     *      возвращаем юзера ТОГО ЖЕ id что был при предыдущем anon signin'е
+     *      (обещание из user-фидбека: «если разлогинился из анонимного —
+     *      логинить в этот же акк»).
+     *
+     *   3. Иначе → POST /auth/anonymous/signin → setSession + сохраняем
+     *      refresh_token в anonRefreshToken.
+     *
+     * `captchaToken` сейчас не требуется — captcha protection в Supabase
+     * отключена, защита от per-IP abuse держится на rate-limit'е Supabase'а
+     * (30/час per real-IP, см. IP forwarding setup в supabaseAuthRest.ts) +
+     * CF Bot Fight Mode на edge. Поле оставлено optional для forward-compat:
+     * когда сервер начнёт возвращать challenge_required в риск-сценариях,
+     * SDK сможет передать proof-of-something обратно без breaking change.
+     *
+     * `forceCaptcha: true` пропускает шаги 1-2 и сразу делает /signin (создаёт
+     * нового anon-юзера). Используется в switch-account flow. Имя поля исторически
+     * остаётся `forceCaptcha`, хотя капчи там больше нет — менять имя ломает
+     * host-сигнатуру; смысл «принудительно новая anon-сессия» сохранён.
+     *
+     * Параллельные вызовы дедуплицируются через `inflightAnonSignin` — два
+     * click'а на «Войти как гость» не создадут двух anon-юзеров (два /signup =
+     * два user_id, второй trial-баланс улетает в нирвану).
+     */
+    signInAnonymously(input?: {
+        captchaToken?: string;
+        userMeta?: Record<string, string>;
+        forceCaptcha?: boolean;
+    }): Promise<AuthSession>;
+    /**
+     * Внутренний resume — пробует /auth/refresh с сохранённым anon refresh_token.
+     * Возвращает session при успехе, null если токена нет или он отозван (401).
+     * Сетевые ошибки бросает наружу — caller сам решает, ретраить или просить
+     * пользователя пройти капчу.
+     */
+    private resumeAnonymous;
+    /**
+     * Анон → email/password upgrade. Сохраняет тот же auth.user.id, балансы
+     * и trial-quotas остаются. Поведение зависит от Supabase email-confirm
+     * настройки проекта:
+     *
+     *  - Confirmation OFF → backend сразу обновляет email + password в auth.users.
+     *    Возвращаем `kind: 'updated'`, локально патчим session.user.email +
+     *    is_anonymous=false (текущий access_token остаётся валидным, перевыдавать
+     *    не нужно — GoTrue не вращает токены на updateUser).
+     *
+     *  - Confirmation ON → backend отдаёт `confirmation_required`. Текущая
+     *    session ОСТАЁТСЯ анонимной до клика юзером по confirmation-ссылке.
+     *    Password применяется сразу (можно дальше логиниться по нему даже до
+     *    confirm'а). После клика — следующий /auth/refresh подтянет обновлённый
+     *    is_anonymous=false из JWT (refresh не возвращает user, так что
+     *    UI может явно подёргать `auth.refresh()` через минуту-другую, либо
+     *    дождаться lazy-refresh при истечении access).
+     *
+     * Без активной session бросает `not_authenticated`. Дедупликации нет —
+     * двойной submit формы UI должен предотвратить idempotencyKey'ом.
+     */
+    upgradeAnonymousToEmail(input: {
+        email: string;
+        password: string;
+        userMeta?: Record<string, string>;
+        /** Idempotency-key для защиты от двойного клика. GoTrue PUT /user не
+         *  идемпотентен сам по себе — повторный submit при двойном клике может
+         *  вызвать race с email-confirmation (две confirmation-ссылки на тот же
+         *  адрес). UI должен передать UUID. */
+        idempotencyKey?: string;
+    }): Promise<UpgradeAnonymousResult>;
+    /**
+     * OAuth signin через popup с PKCE. Жизненный цикл:
+     * 1. Генерим verifier+challenge+state локально (verifier не уходит на бэк
+     *    до /exchange — это защита от перехвата code'а).
+     * 2. POST /oauth/init с challenge → бэк отдаёт authorize_url.
+     * 3. Открываем popup, ждём postMessage с типом 'pw-oauth' и нашим state.
+     * 4. POST /oauth/exchange с {auth_code, code_verifier} → session.
+     *
+     * Таймаут — 5 минут от открытия popup'а. Если юзер закрыл popup до конца
+     * флоу (window.closed → true) — бросаем PaywallError('oauth_cancelled').
+     * Параллельные вызовы НЕ дедупятся — каждый открывает свой popup; вызывать
+     * параллельно не имеет смысла, но защищаться от этого код не должен.
+     *
+     * onPopupOpened вызывается сразу после успешного window.open (до ожидания
+     * code'а). UI использует это, чтобы сбросить loading-state кнопки: дальше
+     * ответственность за флоу у popup'а, основная страница не должна висеть.
+     * Если popup'ом не вернулся code (юзер закрыл вкладку, closed-detection
+     * не сработал из-за COOP-severance) — promise дойдёт до oauth_timeout
+     * через 5 минут, но кнопка к этому моменту уже свободна.
+     */
+    signInWithOAuth(input: {
+        provider: OAuthProvider;
+        scopes?: string;
+        userMeta?: Record<string, string>;
+        onPopupOpened?: () => void;
+    }): Promise<AuthSession>;
+    /**
+     * Шаг 1 OAuth split-API: инициирует flow на бэке, генерит PKCE verifier
+     * + state, сохраняет их у себя, возвращает `{authorize_url, state}` для
+     * открытия popup'а. Верификатор НЕ выходит наружу — его держит AuthClient
+     * до `completeOAuthFlow`.
+     *
+     * Используется в offscreen-архитектуре (@monetize/sdk-extension): start
+     * вызывается через RPC из content-script'а, content открывает popup
+     * нативно (gesture preserved), затем зовёт completeOAuthFlow с code'ом.
+     * AuthClient (в offscreen'е) делает /exchange с сохранённым verifier'ом.
+     *
+     * Pending flows GC'атся через 10мин — больше чем юзеру нужно прокликать
+     * Google. Без cleanup'а Map бы рос на каждый закрытый popup.
+     */
+    startOAuthFlow(input: {
+        provider: OAuthProvider;
+        scopes?: string;
+        userMeta?: Record<string, string>;
+    }): Promise<{
+        authorize_url: string;
+        state: string;
+    }>;
+    /**
+     * Шаг 2 OAuth split-API: обменивает code (полученный из popup) на session,
+     * используя verifier, сохранённый при startOAuthFlow. После успеха — set
+     * session и эмит onAuthChange.
+     *
+     * Если flow не найден (state не из startOAuthFlow или GC'нулся за TTL'ом) —
+     * бросает `oauth_invalid_state`. Caller должен начать заново через
+     * startOAuthFlow.
+     */
+    completeOAuthFlow(input: {
+        state: string;
+        code: string;
+    }): Promise<AuthSession>;
+    private gcOAuthFlows;
+    /**
+     * Refresh access/refresh пары через текущий refresh_token. Дедуплицирует
+     * параллельные вызовы (один in-flight promise на весь клиент).
+     *
+     * - 401 → refresh_token отозван/невалиден → чистим session, эмитим logout.
+     * - Сеть/5xx → пробрасываем ошибку, session оставляем — юзер не должен
+     *   разлогиниваться из-за временной сетевой проблемы.
+     * - Нет session → возвращаем null без сетевого запроса.
+     */
+    refresh(): Promise<AuthSession | null>;
+    /**
+     * Глобальный logout — инвалидирует ВСЕ refresh-токены юзера на всех
+     * устройствах/контекстах через GoTrue `/logout?scope=global`. Используется
+     * для compromise-account флоу («подозрительная активность, разлогинить
+     * везде»).
+     *
+     * Local-side: чистим текущую session, остальные контексты (другие вкладки
+     * / extension popup и background) подхватят logout через storage-watch
+     * автоматически. Active access-токены в других контекстах останутся валидны
+     * до их естественного истечения (1 час max), но refresh уже не сработает —
+     * после первого `getAccessToken()` каждый контекст разлогинится сам.
+     *
+     * Безопасность: бэк не принимает целевой user_id — резолвит юзера из
+     * Bearer, нельзя разлогинить чужой аккаунт.
+     */
+    revokeAllSessions(): Promise<void>;
+    /**
+     * Signout: чистит локальную session СРАЗУ (UX — мгновенный logout без
+     * ожидания сети), потом best-effort POST /auth/signout с текущим access.
+     * Ошибка сети/5xx тут уже не критична — на бэке токен и так истечёт.
+     *
+     * Anon-aware: по умолчанию anonRefreshToken сохраняется. Это позволяет
+     * после signOut() позвать signInAnonymously() и попасть в ТОТ ЖЕ
+     * анон-аккаунт без капчи (см. resumeAnonymous). Поведение предсказуемое
+     * для UX'а «гость → залогинился → разлогинился → снова гость с теми же
+     * балансами».
+     *
+     * `forgetAnonymous: true` — полное забытие, вместе с anonRefreshToken.
+     * Нужно для сценариев типа «свич аккаунта на устройстве» или жалоб на
+     * приватность («очисти все мои следы»).
+     */
+    signOut(opts?: {
+        forgetAnonymous?: boolean;
+    }): Promise<void>;
+    /**
+     * Подписка на изменения session: signin/signup/refresh/signOut/expired-401.
+     * Колбек вызывается с текущим snapshot через microtask (если session есть)
+     * + на каждое реальное изменение. Возвращает unsubscribe.
+     */
+    onAuthChange(cb: AuthChangeListener): () => void;
+    private isFresh;
+    private toSession;
+    private setSession;
+    private emit;
+    private storageKey;
+    private hydrate;
+    private rehydrateFromStorage;
+    /**
+     * Освобождает ресурсы AuthClient'а: отписывает storage-watch, чистит
+     * listener'ы, выставляет destroyed-флаг. После destroy все async-операции
+     * (inflight refresh, OAuth popup, applyExternalSession) early-return'ят
+     * через `isDestroyed()` guard'ы — никаких write-back'ов в storage,
+     * никаких эмитов на пустые listener'ы.
+     *
+     * destroy() идемпотентен: повторный вызов — no-op.
+     */
+    destroy(): void;
+    /** Sync-проверка: был ли вызван destroy(). Полезно для UI / тестов. */
+    isDestroyed(): boolean;
+    private persist;
+    private readAnonRefreshToken;
+    private writeAnonRefreshToken;
+    private clearAnonRefreshToken;
+    /**
+     * Читает stable visitor_id из storage если он там уже есть. НЕ генерит:
+     * AuthClient может быть инстанцирован раньше BillingClient, а синтетический
+     * visitor_id без касания пейвола не имеет смысла (нет гостевых покупок,
+     * которые надо бы линковать). undefined → бэк сам пропустит ветку
+     * "merge guest purchases".
+     */
+    private readVisitorId;
+}
+
+export declare interface AuthClientOptions {
+    paywallId: string;
+    apiOrigin?: string;
+    storage?: StorageAdapter;
+    fetch?: typeof fetch;
+    openPopup?: (url: string, name: string) => Window | null;
+}
+
+/**
+ * Managed-auth конфиг. Передай `auth: true` — PaywallUI создаёт `AuthClient`
+ * сам (с тем же `paywallId/apiOrigin/storage`, как BillingClient). Передай
+ * объект — те же дефолты + override опций. Передай готовый `AuthClient` —
+ * PaywallUI просто прокинет его в BillingClient (полезно, если хост хочет
+ * иметь общий AuthClient на несколько пейволов / делать manual signIn/signOut
+ * из своего UI до открытия модалки).
+ *
+ * Без `auth` опции SDK работает в hybrid-режиме: identity передаётся снаружи
+ * через `opts.identity` или `paywall.open({identity})`.
+ */
+declare type AuthOption = true | AuthClient | Partial<Omit<AuthClientOptions, 'paywallId'>>;
+
+export declare interface AuthSession {
+    access_token: string;
+    refresh_token: string;
+    /** Absolute timestamp в ms (Date.now() сравнимо). null/0 не пишем. */
+    expires_at: number;
+    user: AuthUser;
+}
+
+export declare interface AuthUser {
+    id: string;
+    /** null для анонимного юзера (signInAnonymously). Для всех остальных flow — заполнен. */
+    email: string | null;
+    country?: string | null;
+    /** true — Supabase anonymous user. UI использует, чтобы решать «sign in» vs
+     *  «signed in as ...», и чтобы при OAuth-апгрейде звать linkIdentity вместо
+     *  signInWithOAuth (зеркалит легаси StartAuthPage.tsx). */
+    is_anonymous?: boolean;
+}
+
+/** Балансы AI-провайдеров пейвола: один элемент на `query_type` из
+ *  `paywall_settings.tokenization_queries`. count = доступно вызовов. */
+export declare interface Balance {
+    type: string;
+    count: number;
+}
+
+declare type BalancesListener = (balances: Balance[]) => void;
+
+export declare class BillingClient {
+    readonly paywallId: string;
+    readonly apiOrigin: string;
+    readonly capabilities: string[] | undefined;
+    /** AuthClient, если был передан в options. Иначе undefined. */
+    readonly auth: AuthClient | undefined;
+    private api;
+    private storage;
+    private identity;
+    private apiKey;
+    private fetchImpl;
+    private cachedBootstrap;
+    private cachedBootstrapAt;
+    private inflightBootstrap;
+    private bootstrapListeners;
+    private bootstrapStorageUnwatch;
+    private authUnsubscribe;
+    private cachedUser;
+    private cachedUserAt;
+    private inflightUser;
+    private userListeners;
+    private visitorIdPromise;
+    private visitorId;
+    private inflightCheckouts;
+    private cachedBalances;
+    private cachedBalancesAt;
+    private balancesStorageUnwatch;
+    private inflightBalances;
+    private balanceListeners;
+    constructor(opts: BillingClientOptions);
+    /**
+     * Stable visitor_id (UUID v4). Первый вызов awaitит первичный резолв из
+     * storage; последующие — мгновенно из in-memory кеша. Используется
+     * EventTracker'ом для атрибуции аналитики.
+     */
+    getVisitorId(): Promise<string>;
+    /** Sync-доступ к visitor_id. null если ещё не зарезолвили (первые ms жизни). */
+    getCachedVisitorId(): string | null;
+    setIdentity(identity: Identity | undefined): void;
+    /**
+     * Отписаться от auth-event'ов и сбросить listener'ы. Вызывать когда
+     * BillingClient больше не нужен (тесты, hot-reload, переинициализация).
+     * Без destroy() listener на AuthClient переживёт BillingClient и будет
+     * дёргать setIdentity на освобождённом инстансе. Слушатели user/balance
+     * чистятся, чтобы упавший host (например, размонтированный React-tree)
+     * не держал замыкания на эти колбеки.
+     */
+    destroy(): void;
+    getIdentity(): Identity | undefined;
+    getStorage(): StorageAdapter;
+    bootstrap(forceOrOpts?: boolean | {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<PaywallBootstrap>;
+    /**
+     * Подписка на изменения bootstrap'а: applyBootstrap (сетевой revalidate,
+     * cross-context storage.watch). Срабатывает ТОЛЬКО при реальном изменении
+     * `version` (unchanged-ответ от сервера не дёргает listener'ов). Возвращает
+     * unsubscribe.
+     */
+    onBootstrapChange(cb: (b: PaywallBootstrap) => void): () => void;
+    private fetchBootstrap;
+    private revalidateBootstrap;
+    private applyBootstrap;
+    private hydrateBootstrapFromStorage;
+    private persistBootstrap;
+    private subscribeBootstrapStorage;
+    /** Возвращает последний загруженный bootstrap без сетевого запроса.
+     *  null = bootstrap ещё не загружали. Удобно для post-checkout-логики
+     *  (PaywallUI читает success_redirect_url, не делая второго round-trip'а). */
+    getCachedBootstrap(): PaywallBootstrap | null;
+    /**
+     * Шорткат поверх `bootstrap()`: ждёт загрузку структуры пейвола и возвращает
+     * цены. Полезно когда host рисует цены вне модалки (карточки на лендинге,
+     * "Pricing" page и т.п.) и не хочет руками распаковывать bootstrap.
+     *
+     * Locale-оверрайды (`label`/`description` под `navigator.language`) уже
+     * применены — массив готов к рендеру. Кэш/TTL/stale-while-revalidate — те
+     * же, что у `bootstrap()`: повторный вызов не штурмует сервер.
+     */
+    getPrices(opts?: {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<PaywallPrice[]>;
+    /** Sync-снимок цен из последнего bootstrap'а. null = ещё не загружали. */
+    getCachedPrices(): PaywallPrice[] | null;
+    /**
+     * Снимок того, какой язык SDK сейчас считает «языком юзера». Полезно для
+     * синхронизации i18n хоста с тем, что фактически показывает пейвол — чтобы
+     * окружающий UI не противоречил модалке (например, host рисует кнопку
+     * "Subscribe" на английском, а пейвол показывает «Подписаться» на русском).
+     *
+     * Возвращает структуру, а не один тэг, чтобы интегратор мог:
+     *  - быстро взять `tag` для своих переводов;
+     *  - отличить «пейвол реально на этом языке» (`applied !== null`) от
+     *    «SDK угадал, но локали для этого языка нет — рендерится база»;
+     *  - решить, чему доверять при противоречии browserLanguage vs countryLanguage
+     *    (тур, expat, VPN — у каждого свой ответ).
+     *
+     * Sync-вызов: данные уже в bootstrap'е, отдельных запросов не делает.
+     * Если `bootstrap()` ещё не вызывался — `applied` и `countryLanguage`
+     * будут `null`, но `browserLanguage` и `tag` всё равно отдадутся, если
+     * есть `navigator.language`.
+     */
+    getUserLanguage(): UserLanguageInfo;
+    /**
+     * Получить актуальное состояние подписки/покупок.
+     *
+     * - In-memory cache TTL 5с — naïve setInterval(1000) не нагружает сервер.
+     * - In-flight dedupe — параллельные вызовы получают один promise.
+     * - `force: true` обходит кеш (для post-checkout проверки).
+     * - Без identity возвращает empty-state (сервер тоже так делает).
+     */
+    getUser({ force, signal }?: {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<PaywallUser>;
+    /**
+     * Подписка на изменения user-state. Колбек вызывается:
+     * - сразу с last-known user (если есть в кеше) — по умолчанию через
+     *   microtask, опционально SYNC (см. опции);
+     * - на каждое реальное изменение (getUser/bootstrap принёс другой shape).
+     *
+     * `opts.immediate`:
+     *   - `'microtask'` (default) — initial snapshot отдаётся в queueMicrotask,
+     *     чтобы host успел доресетнуть state в том же тике. Безопасный выбор
+     *     для большинства интеграций.
+     *   - `'sync'` — initial snapshot отдаётся прямо в текущем frame'е, до
+     *     возврата из onUserChange. Удобно для React/Vue useEffect-cleanup'а
+     *     (избегаем лишнего ре-рендера) и SSR (мгновенная синхронизация).
+     *   - `'none'` — не отдавать initial snapshot, только реальные изменения.
+     *
+     * Возвращает функцию отписки.
+     */
+    onUserChange(cb: UserListener, opts?: {
+        immediate?: 'microtask' | 'sync' | 'none';
+    }): () => void;
+    /** Текущий cached user без сетевого запроса. null = ещё не загружали. */
+    getCachedUser(): PaywallUser | null;
+    private applyUser;
+    private storageKey;
+    private hydrateUserFromStorage;
+    private persistUser;
+    /**
+     * Балансы AI-провайдеров (`paywall_balances` × `tokenization_queries`).
+     *
+     * - In-memory cache TTL 5с — параллельные UI-renders не дёргают сеть;
+     * - In-flight dedupe — параллельные `getBalances` получают один promise;
+     * - `force: true` обходит кеш (типичный кейс — после QuotaExceededError);
+     * - Без auth (Bearer не выдан) возвращает пустой массив без сетевого
+     *   запроса: бэк всё равно ответит 401, нет смысла тратить round-trip.
+     *
+     * Если у пейвола `tokenization=false` — бэк отдаёт `[]`, как для гостя.
+     * SDK не различает «нет квоты» и «нет квот вообще» — caller сам решает
+     * по `currentBalance` в QuotaExceededError или `balances.length`.
+     */
+    getBalances({ force, signal }?: {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Balance[]>;
+    private fetchBalances;
+    /** Sync snapshot. null = ещё не загружали (или explicit clear на re-login). */
+    getCachedBalances(): Balance[] | null;
+    /**
+     * Подписка на изменения балансов: getBalances/decrementBalanceLocal/setIdentity.
+     * `opts.immediate` работает так же, как в `onUserChange`: 'microtask'
+     * (default), 'sync' (для React/Vue useEffect), 'none' (только изменения).
+     * Возвращает unsubscribe.
+     */
+    onBalanceChange(cb: BalancesListener, opts?: {
+        immediate?: 'microtask' | 'sync' | 'none';
+    }): () => void;
+    /**
+     * Оптимистично уменьшает count для `queryType` на 1 и нотифицирует
+     * listener'ов. Используется ApiGatewayClient'ом сразу после успешного
+     * gateway-вызова (бэк уже снял кредит, см. `chargeApiQueries`).
+     *
+     * Если queryType отсутствует в кеше или count<=0 — no-op (не уходим в
+     * отрицательные значения, бэк всё равно правильный source-of-truth).
+     * Если кеша нет вовсе — тоже no-op: явный getBalances({force:true}) на
+     * следующем рендере подтянет актуальный shape.
+     *
+     * queryType может быть undefined (gateway не прислал X-Query-Type) —
+     * в этом случае декремент не делаем, но просим refreshBalances() для
+     * выравнивания.
+     */
+    decrementBalanceLocal(queryType: string | undefined): void;
+    /** Принудительный re-fetch — типичный вызов после QuotaExceededError, чтобы
+     *  UI получил актуальный balance=0 и нарисовал upgrade-prompt. */
+    refreshBalances(): Promise<Balance[]>;
+    /**
+     * Фабрика ApiGatewayClient'а с подключённым к этому billing'у balance-стейтом:
+     *  - Bearer/identity берутся из текущего auth/identity;
+     *  - на success декрементим cachedBalances оптимистично;
+     *  - на 402 (QuotaExceededError) триггерим refreshBalances() для актуального snapshot'а.
+     *
+     * Если переопределить опции через `overrides` — принимаются как есть, но
+     * `onChargeSuccess`/`onQuotaExceeded` всё равно вызываются (composable, host
+     * может добавить свой колбек поверх).
+     */
+    createApiGatewayClient(overrides?: Partial<Omit<ApiGatewayClientOptions, 'paywallId' | 'auth' | 'userId'>>): ApiGatewayClient;
+    private applyBalances;
+    private balancesStorageKey;
+    private hydrateBalancesFromStorage;
+    private persistBalances;
+    private subscribeBalancesStorage;
+    createCheckout(params: {
+        priceId: string;
+        successUrl?: string;
+        errorUrl?: string;
+        shopUrl?: string;
+        trialDays?: number;
+        /**
+         * Stage 1 защиты от дубликатов покупок. Идемпотентный ключ запроса
+         * (UUID). Повторный вызов с тем же ключом вернёт тот же checkout-URL
+         * без второго обращения к платёжному провайдеру. Если не передан —
+         * SDK генерит UUID v4 сам и дедуплицирует параллельные клики по
+         * `auto:${priceId}`.
+         */
+        idempotencyKey?: string;
+        /** Renewal/upgrade flow — игнорирует у бэка проверку has_active_subscription.
+         *  По умолчанию /start-checkout возвращает 409 если у юзера уже есть
+         *  active subscription (защита от случайных двойных оплат). С
+         *  `ignoreActivePurchase: true` бэк создаёт новый checkout, прежняя
+         *  подписка отменится после успешной оплаты. Передавать только когда
+         *  юзер явно выбрал "Renew/Upgrade" в host-UI. */
+        ignoreActivePurchase?: boolean;
+        /** Отмена inflight-запроса. Параллельные вызовы дедуплицируются по
+         *  `inflightKey`, поэтому signal отменяет ВСЕ ожидающие на этот ключ —
+         *  это OK для типичного UX (юзер закрыл модалку — все checkout'ы отменены). */
+        signal?: AbortSignal;
+    }): Promise<CheckoutResult>;
+    /**
+     * URL Stripe/Paddle/Chargebee customer portal — место, где залогиненный
+     * юзер может управлять подпиской (отменить, обновить карту, скачать
+     * инвойсы). Опен-флоу управляется host'ом:
+     *
+     * ```ts
+     * const { url } = await billing.getCustomerPortalUrl();
+     * window.open(url, '_blank');
+     * ```
+     *
+     * Auth: Bearer (через AuthClient) или server-side `apiKey`. Без auth и
+     * без apiKey бросает PaywallError('identity_required'). 403 от бэка
+     * (нет активной подписки / acquiring не поддерживает portal) пробрасывается
+     * как PaywallError('forbidden') с `status: 403` — host рендерит "no
+     * subscription to manage".
+     */
+    getCustomerPortalUrl(opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Список покупок юзера с rich-полями (цена, валюта, interval, discount,
+     * cancel-метаданные). Подходит для customer-portal UI: cards с кнопками
+     * Cancel/Renew/Manage. Менее cache-friendly чем `getUser` — ходит в
+     * `/api/v1/paywall/[id]/user` без unstable_cache, потому что list для UI
+     * должен быть свежим после cancel-а.
+     *
+     * Auth: Bearer обязателен (через AuthClient). Без Bearer — 401 от бэка,
+     * пробрасываем как PaywallError('http_401'). Гость → пустой список.
+     */
+    listPurchases(opts?: {
+        signal?: AbortSignal;
+    }): Promise<PaywallPurchaseDetailed[]>;
+    /**
+     * Отменить подписку. Бэк проверит что subscription принадлежит auth-юзеру
+     * и сделает cancel у acquiring'а (Stripe/Paddle/Chargebee). По умолчанию
+     * cancel в конце текущего периода — юзер сохраняет access до renewal date'ы.
+     *
+     * `reason` обязательна (валидация на бэке). Удобно собрать через select
+     * причин в host-UI, как в legacy customer portal'е.
+     *
+     * Auth: Bearer обязателен.
+     */
+    cancelSubscription(params: {
+        subscriptionId: string;
+        reason: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        subscription: {
+            status: string | null;
+            canceled_at: string | null;
+            cancel_at: string | null;
+            cancel_at_period_end: boolean | null;
+        };
+    }>;
+    /**
+     * Создаёт саппорт-тикет. Если есть `files` — multipart/form-data, иначе JSON.
+     * Email берётся (1) из явного поля payload.email; (2) из identity если оно есть.
+     * Если ни того, ни другого нет — бэк отвергнет тикет (`email_required`).
+     *
+     * Bearer-токен (если AuthClient подключён) добавляется автоматически — бэк
+     * перевешивает customer_email на email из сессии (защита от подделки).
+     */
+    createSupportTicket(payload: {
+        subject: string;
+        content: string;
+        email?: string;
+        files?: File[];
+    }): Promise<{
+        ticket: {
+            id: number;
+            status: string;
+        };
+    }>;
+}
+
+export declare interface BillingClientOptions {
+    paywallId: string;
+    apiOrigin?: string;
+    identity?: Identity;
+    storage?: StorageAdapter;
+    capabilities?: string[];
+    fetch?: typeof fetch;
+    /**
+     * Server SDK API key. Используется для `/start-checkout` в headless/hybrid-сценариях,
+     * где вызов идёт из trusted-окружения (backend клиента). В client-native пути
+     * ключ НЕ передавать — приватный токен утечёт в браузер.
+     */
+    apiKey?: string;
+    /**
+     * AuthClient для подключения Bearer-авторизации и автосинка identity. Если
+     * передан — все запросы получают `Authorization: Bearer <access_token>`,
+     * а identity пересчитывается из auth.user на каждом login/logout/refresh
+     * (перетирает явно заданный `opts.identity` после первого auth-event'а).
+     *
+     * Без auth BillingClient работает как раньше: identity приходит снаружи
+     * через `setIdentity`, Bearer не отправляется.
+     */
+    auth?: AuthClient;
+}
+
+export declare type BlockComponent<B extends LayoutBlock = LayoutBlock> = ComponentType<BlockProps<B>>;
+
+export declare interface BlockContext {
+    bootstrap: PaywallBootstrap;
+    selectedPriceId: string | null;
+    setSelectedPriceId: (id: string) => void;
+    onAction: (action: string, payload?: unknown) => void;
+    /** AuthClient, если PaywallUI был сконфигурирован с managed-auth. Без него
+     *  auth_panel-блок рендерит fallback ("auth not configured"). */
+    auth?: AuthClient;
+    /** Текущая auth-session (snapshot из AuthClient). null = разлогинен. PaywallRoot
+     *  подписан на onAuthChange и пробрасывает свежий snapshot сюда. */
+    authSession: AuthSession | null;
+}
+
+export declare interface BlockProps<B extends LayoutBlock = LayoutBlock> {
+    block: B;
+    ctx: BlockContext;
+}
+
+export declare const blockRegistry: Record<LayoutBlock['type'], BlockComponent<any>>;
+
+export declare interface CheckoutResult {
+    url: string;
+    sessionId?: string;
+    /** Платёжный процессор, к которому ушёл checkout. Полезно для аналитики
+     *  конверсии по эквайрингам (host может ветвить UX по acquiring). */
+    acquiring?: Acquiring;
+}
+
+export declare function createStorage(override?: StorageAdapter): StorageAdapter;
+
+export declare function ensureVisitorId(storage: StorageAdapter): Promise<string>;
+
+export declare class EventTracker {
+    private opts;
+    private buffer;
+    private flushTimer;
+    private destroyed;
+    private unloadHandler;
+    private visibilityHandler;
+    constructor(opts: EventTrackerOptions);
+    private isEnabled;
+    track(type: string, props?: Record<string, unknown>): void;
+    private scheduleFlush;
+    flush(): Promise<void>;
+    /**
+     * Отправка через navigator.sendBeacon — для unload/pagehide. Гарантированно
+     * долетает (POST с keepalive тоже почти, но beacon сделан именно под это).
+     * Headers ставить нельзя (спецификация), поэтому SDK metadata едет в body
+     * как fallback-поля, которые сервер читает в дополнение к headers.
+     */
+    flushBeacon(): void;
+    private buildHeaders;
+    private attachUnloadHandlers;
+    private detachUnloadHandlers;
+    destroy(): void;
+}
+
+export declare interface EventTrackerOptions {
+    endpoint: string;
+    paywallId: string;
+    capabilities?: string[];
+    getVisitorId: () => Promise<string>;
+    getCachedVisitorId?: () => string | null;
+    getUserId?: () => string | null | undefined;
+    enabled?: boolean;
+    flushIntervalMs?: number;
+    maxBufferSize?: number;
+    /** Тестовый override fetch'а. */
+    fetch?: typeof fetch;
+    /** Тестовый override sendBeacon'а — позволяет проверить unload-flow в jsdom. */
+    sendBeacon?: (url: string, data: BodyInit) => boolean;
+}
+
+export declare function generateVisitorId(): string;
+
+export declare interface GetAccessOptions {
+    skipTrial?: boolean;
+    skipVisibility?: boolean;
+    signal?: AbortSignal;
+}
+
+export declare interface Identity {
+    email?: string;
+    userId?: string;
+    anonymousId?: string;
+}
+
+export declare interface Layout {
+    type: 'modal';
+    blocks: LayoutBlock[];
+}
+
+export declare type LayoutBlock = {
+    type: 'heading';
+    text: string;
+    level?: 1 | 2 | 3;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'price_grid';
+    priceIds?: string[];
+    /** Раскладка карточек цен. `vertical` (default) — стек сверху вниз;
+     *  `horizontal` — ряд side-by-side. v2-аналог `view: 'default' | 'telegram'`. */
+    view?: 'vertical' | 'horizontal';
+    /** ID цены, которая помечается лейблом «популярный план». v2-аналог
+     *  пары `price_label_id` + `price_label`. */
+    popular_price_id?: string;
+    /** Текст лейбла «популярный план». По умолчанию "Most popular".
+     *  v2-аналог `price_label_text`. Локализация — через bootstrap.locales. */
+    popular_label?: string;
+} | {
+    type: 'cta_button';
+    label: string;
+    action: 'checkout' | 'close';
+    priceId?: string;
+} | {
+    /** Footer-блок под cta_button: залогинен — рисует "Signed in as <email> | Sign out",
+     *  иначе — кнопку "Restore purchases", которая открывает auth-gate без pendingCheckout
+     *  (после signIn gate просто схлопывается, юзер видит свой signed-in state). */
+    type: 'current_session';
+} | {
+    type: 'auth_panel';
+    /** OAuth-провайдеры в порядке отображения. Пусто/опущено — только email-форма. */
+    providers?: Array<'google' | 'apple' | 'github' | 'facebook'>;
+    /** Показывать toggle "Sign up". По умолчанию true. */
+    allow_signup?: boolean;
+    /** Показывать ссылку "Forgot password?". По умолчанию true. */
+    allow_password_reset?: boolean;
+    /** Скрывать панель, если юзер уже залогинен. По умолчанию true.
+     *  false — показываем "Signed in as ... [Sign out]" даже после логина. */
+    hide_when_authenticated?: boolean;
+    /** Заголовок над формой (h2). Если опущен — заголовок не рендерится. */
+    heading?: string;
+} | {
+    /** Список фич/преимуществ продукта. v2-аналог `features_list` + `features_view`.
+     *  До 5 элементов — рендерим как чек-лист с заголовком и описанием. */
+    type: 'features_list';
+    items: Array<{
+        id: string;
+        name: string;
+        desc?: string;
+    }>;
+} | {
+    /** Информационный список «что включено в выбранный план» — рендерится
+     *  под price_grid, без интерактивности. v2-аналог `tokenization` +
+     *  `tokenization_queries`. Для каждого query показываем count,
+     *  умноженный на множитель интервала выбранной цены (`week=0.25`,
+     *  `month=1`, `year=12`) — т.е. count в БД хранится как месячная
+     *  норма. Заголовок реактивно отражает текущий interval. */
+    type: 'tokenization_gate';
+    queries: Array<{
+        id: string;
+        name: string;
+        desc: string;
+        count: number;
+    }>;
+};
+
+/** Локализационные оверрайды для одного языка. Накатываются поверх дефолтного
+ *  layout/prices при матче `navigator.language` ↔ ключа в `bootstrap.locales`.
+ *  v2-аналог поля `translations` JSON в paywall_settings. */
+export declare interface LocaleOverrides {
+    /** Полная замена layout для языка. Если опущен — берётся дефолтный
+     *  bootstrap.layout. */
+    layout?: Layout;
+    /** Точечные оверрайды текстовых полей цен. Ключ — price.id, значения
+     *  накатываются на label/description. */
+    prices?: Record<string, {
+        label?: string;
+        description?: string;
+    }>;
+}
+
+export declare type OAuthProvider = 'google' | 'apple' | 'github' | 'facebook';
+
+export declare interface OpenOptions {
+    identity?: Identity;
+    /** Принудительно открыть, минуя pre-paywall trial check. По умолчанию SDK
+     *  читает `bootstrap.settings.trial` и блокирует open(), пока триал активен.
+     *  Эскейп-хатч для случаев типа «host решил показать всё-таки» или дев-режим. */
+    skipTrial?: boolean;
+    /** Принудительно открыть, минуя targeting-gate. По умолчанию SDK читает
+     *  `bootstrap.settings.visibility` и эмитит `visibility_blocked` без
+     *  открытия модалки, если visible=false (страна/девайс/visibility-флаг
+     *  не сошлись). Эскейп-хатч для дев-отладки. */
+    skipVisibility?: boolean;
+    /** Renewal/upgrade flow. По умолчанию (false) SDK после bootstrap'а или
+     *  signIn проверяет `user.has_active_subscription` и переключается в
+     *  restored success-view, не показывая тарифы — open() для уже подписанного
+     *  юзера превращается в подтверждение «у вас уже есть подписка». С
+     *  `renew: true` все эти проверки пропускаются: тарифы показываются всегда,
+     *  и при checkout SDK передаёт `ignoreActivePurchase: true` на бэк, чтобы
+     *  /start-checkout не вернул 409. Использовать когда host-UI явно
+     *  показывает кнопку «Renew»/«Upgrade plan». */
+    renew?: boolean;
+}
+
+declare interface OpensTrialStatus {
+    mode: 'opens';
+    /** true — триал ещё активен, паывол не показывается. */
+    blocked: boolean;
+    /** Сколько ещё «бесплатных» открытий осталось. 0 — триал истёк. */
+    remainingActions: number;
+    /** Полное число «бесплатных» открытий (payload). */
+    totalActions: number;
+}
+
+export declare type OtpVerifyType = 'email' | 'recovery' | 'signup' | 'magiclink' | 'invite';
+
+/**
+ * Результат `paywall.getAccess()` — отвечает на главный вопрос хоста: «нужно
+ * ли блокировать фичу для этого юзера?». Без побочных эффектов: на trial-storage
+ * `recordBlock` не вызывается (счётчики не двигаются), модалка не монтируется.
+ *
+ * Семантика `access`:
+ *  - `granted` — фичу НЕ блокировать. Один из сценариев:
+ *    - `has_subscription` — у юзера активная подписка/покупка;
+ *    - `visibility_blocked` — таргетинг (страна/девайс/visibility-флаг) не
+ *       сошёлся, юзер вне monetization-scope'а пейвола → монетизация неприменима;
+ *    - `trial_blocked` — пре-пейвольный триал ещё активен.
+ *  - `blocked` — фичу заблокировать и вызвать `paywall.open()`. Reason всегда
+ *     `no_subscription`.
+ *
+ * Discriminated union по `access`: type-narrowing на `result.access === 'blocked'`
+ * сужает `reason` до `'no_subscription'`, на `'granted'` — до трёх granted-вариантов.
+ */
+export declare type PaywallAccessResult = {
+    access: 'granted';
+    reason: 'has_subscription' | 'visibility_blocked' | 'trial_blocked';
+    visibility: VisibilityStatus | null;
+    trial: TrialStatus | null;
+    user: PaywallUser | null;
+} | {
+    access: 'blocked';
+    reason: 'no_subscription';
+    visibility: VisibilityStatus | null;
+    trial: TrialStatus | null;
+    user: PaywallUser | null;
+};
+
+export declare interface PaywallBootstrap {
+    settings: PaywallSettings;
+    prices: PaywallPrice[];
+    offers: PaywallOffer[];
+    layout?: Layout;
+    /** Snapshot user-state на момент bootstrap'а. Без identity (гость) — всё пусто.
+     *  Дальше обновляется через BillingClient.getUser() / PaywallUI.onUserChange. */
+    user?: PaywallUser;
+    /** Локализационные оверрайды по BCP-47 кодам (`en`, `en-US`, `ru`, ...).
+     *  BillingClient.bootstrap() матчит `navigator.language` с fallback на
+     *  `settings.locale_default` и применяет оверрайды поверх layout/prices. */
+    locales?: Record<string, LocaleOverrides>;
+    /** Stable content-hash структурной части bootstrap'а (без user). SDK
+     *  персистит payload в StorageAdapter и шлёт `?if_version=<v>` на
+     *  ревалидации — бэк отвечает `{unchanged:true, version, user}` без
+     *  полного payload, если version совпала. Optional для совместимости
+     *  с старыми бэками. */
+    version?: string;
+}
+
+export declare class PaywallError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, opts?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+
+export declare type PaywallEvent = keyof PaywallEventPayloads;
+
+export declare type PaywallEventHandler<E extends PaywallEvent = PaywallEvent> = (payload: PaywallEventPayloads[E]) => void;
+
+declare interface PaywallEventPayloads {
+    /** Модалка открыта (запрос на открытие — данные могут ещё грузиться). */
+    open: void;
+    /** Модалка закрыта. */
+    close: void;
+    /** Bootstrap загружен, модалка показывает контент. Подходит для impression-метрик. */
+    ready: PaywallBootstrap;
+    /** Любая ошибка SDK (bootstrap, checkout). */
+    error: PaywallError;
+    /** Юзер выбрал тариф (клик по плану), ещё не инициировал checkout. */
+    price_selected: {
+        priceId: string;
+        price: PaywallPrice;
+    };
+    /** Checkout URL получен с бэка и открыт в новой вкладке. `acquiring` —
+     *  имя платёжного процессора, на который ушёл checkout (для конверсии
+     *  по эквайрингам в host-аналитике). */
+    checkout_started: {
+        priceId: string;
+        url: string;
+        acquiring?: Acquiring;
+    };
+    /** Юзер вернулся с успешной оплатой (через URL-маркеры или postMessage),
+     *  либо после signIn / попытки checkout-а выяснилось, что подписка уже
+     *  активна (`restored: true`). priceId = null когда payment-интент не
+     *  был привязан к конкретной цене (UserWatcher-tick, restore-flow). */
+    purchase_completed: {
+        priceId: string | null;
+        sessionId: string | null;
+        /** true — это не свежая оплата, а активная подписка, которую SDK обнаружил
+         *  и показал juзеру success/restored view. Hostу полезно различать (для
+         *  metrics — «restore» vs «new purchase»). */
+        restored?: boolean;
+    };
+    /** Юзер вернулся с ошибкой/cancel от провайдера. */
+    purchase_failed: {
+        reason: string | null;
+    };
+    /** 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;
+    /** Триал заблокировал показ модалки. payload содержит свежий статус (после
+     *  recordBlock). Для `mode: 'time'` — startedAt/expiresAt/remainingMs;
+     *  для `mode: 'opens'` — remainingActions/totalActions. Хост может
+     *  использовать payload для показа собственного UI («осталось 3 показа»). */
+    trial_blocked: TrialStatus;
+    /** Триал истёк, паывол показывается впервые после истечения. Эмитится
+     *  раз за жизнь PaywallUI-инстанса (не персистится между перезагрузками
+     *  страницы — на каждом page-load событие может стрельнуть один раз). */
+    trial_expired: void;
+    /** Targeting не сошёлся — паывол не открывается. payload содержит
+     *  server-computed snapshot из bootstrap (visible=false + reason + country +
+     *  tier). Хост может показать собственный fallback («сервис недоступен в
+     *  вашей стране») или просто залогировать impression для аналитики. */
+    visibility_blocked: VisibilityStatus;
+}
+
+export declare interface PaywallOffer {
+    id: string;
+    discount_percent: number | null;
+    expires_at: string | null;
+    price_id: string | null;
+    label?: string | null;
+}
+
+export declare interface PaywallPrice {
+    id: string;
+    currency: string;
+    amount: number;
+    interval: 'month' | 'year' | 'week' | 'day' | 'lifetime' | null;
+    interval_count: number | null;
+    trial_days: number | null;
+    label?: string | null;
+    description?: string | null;
+    local?: {
+        currency: string;
+        amount: number;
+    } | null;
+}
+
+/** Rich-shape от `/api/v1/paywall/[id]/user` для customer-portal UX (cancel,
+ *  renew, история платежей). В отличие от `PaywallUserPurchase` (которая
+ *  идёт из `/user-state` и имеет минимум для access-gate'а), этот shape
+ *  включает цену/валюту/discount — чтобы host мог нарисовать список подписок
+ *  как в legacy customer portal'е. */
+declare interface PaywallPurchaseDetailed {
+    id: string;
+    status: string | null;
+    cancel_at: string | null;
+    cancel_at_period_end: boolean;
+    canceled_at: string | null;
+    created: string;
+    ended_at: string | null;
+    current_period_end: string | null;
+    current_period_start: string | null;
+    /** Цена в minor units (центах). Для legacy совместимости — sometimes из
+     *  `paywall_internal_prices.unit_amount * 100`, иногда из local_amount. */
+    unit_amount: number;
+    currency: string;
+    interval: string | null;
+    /** Скидка в процентах от offer (если был применён). undefined — без offer'а. */
+    discount?: number;
+}
+
+export declare interface PaywallSettings {
+    id: string;
+    name: string;
+    brand_color?: string | null;
+    custom_css?: string | null;
+    locale_default?: string | null;
+    runtime_mode?: 'client' | 'hybrid' | 'server' | 'client-native' | 'hybrid-native';
+    /** true, если эквайринг пейвола в test-mode — SDK рисует TEST MODE бейдж. */
+    is_test_mode?: boolean;
+    /** Auth-flow относительно checkout. `guest` (default) — без auth перед оплатой;
+     *  `preauth` — клик по cta_button=checkout сначала открывает AuthPanel-gate,
+     *  после signIn auto-resume исходного createCheckout. Поле общее с legacy v2. */
+    checkout_mode?: 'guest' | 'preauth';
+    /** OAuth-провайдеры для preauth-gate в порядке отображения. Бэк сейчас отдаёт
+     *  фиксированный список (google + apple); если поле не задано — gate рисует
+     *  только email-форму. Не путать с `block.providers` у inline-блока auth_panel. */
+    auth_providers?: Array<'google' | 'apple' | 'github' | 'facebook'>;
+    /** Разрешён ли вход без email — анонимный юзер. `paywall.signInAnonymously()`
+     *  падает с code='anonymous_disabled', если флаг = false. Поле дублирует
+     *  `paywall_settings.allow_anonymous` из БД, то же что используется в legacy
+     *  v2 (PayWallIframeOpener.tsx). Защита от abuse — на стороне сервера (Supabase
+     *  rate-limit per real-IP + CF Bot Fight Mode), capтча в SDK не используется. */
+    allow_anonymous?: boolean;
+    /** Можно ли закрыть модалку (крестик, клик по overlay, ESC). По умолчанию true.
+     *  false — модалка показывается до успешной покупки или явного host-close().
+     *  v2-аналог `allow_close`. */
+    allow_close?: boolean;
+    /** Авто-подгонка размера шрифта heading-блока, чтобы заголовок влезал в 2
+     *  строки. v2-аналог `title_auto_fit`. По умолчанию false. */
+    title_auto_fit?: boolean;
+    /** URL, куда редиректить вкладку после успешной покупки (server-confirmed
+     *  через UserWatcher). null/undefined — остаёмся на месте, показываем
+     *  PurchaseSuccessView. v2-аналог `success_redirect_url`. */
+    success_redirect_url?: string | null;
+    /** URL "Вернуться в магазин" — пробрасывается в createCheckout как `shopUrl`
+     *  для Stripe/Paddle страницы оплаты. v2-аналог `checkout_shop_url`. */
+    checkout_shop_url?: string | null;
+    /** Имя продукта на странице оплаты Stripe/Paddle (line_item.name). Бэк
+     *  использует при создании checkout-сессии. v2-аналог `checkout_product_name`. */
+    checkout_product_name?: string | null;
+    /** Конфиг pre-paywall триала (паывол не показывается, пока триал активен).
+     *  null/undefined — триал отключён, `paywall.open()` сразу открывает модалку.
+     *  v2-аналог пары `trial` + `trial_payload` в paywall_settings. Не путать с
+     *  card-trial (PaywallPrice.trial_days) — это автосписание после оплаты. */
+    trial?: TrialConfig | null;
+    /** Server-computed targeting-gate: матчится ли текущий юзер (страна/девайс)
+     *  под настройки таргетинга пейвола, плюс общий on/off-флаг. SDK перед open()
+     *  читает `visible`: false → эмитит `visibility_blocked` и не монтирует
+     *  модалку. country/tier выдаются всегда — host'ы используют для аналитики.
+     *  v2-аналог `visibilityEnabledAndTargetingMatch` + `detectInvisible` в
+     *  PaywallClient.tsx + StateService. */
+    visibility?: VisibilityStatus;
+}
+
+declare type PaywallStateListener = (state: PaywallStateSnapshot) => void;
+
+/**
+ * Публичный snapshot состояния PaywallUI для host'а. Производится из internal
+ * LoadState + GateState + open/purchased флагов. Каждое реальное изменение —
+ * один call onState; повторы (`useSyncExternalStore`-friendly).
+ */
+export declare interface PaywallStateSnapshot {
+    /** Модалка отрендерена и видна. False — closed (или ещё не открывалась). */
+    open: boolean;
+    /** Что показывается в модалке. null когда `open=false`. */
+    view: 'loading' | 'error' | 'layout' | 'auth' | 'anon' | 'support' | 'awaiting_payment' | 'popup_blocked' | 'purchased' | null;
+    /** Заполнено только когда `view === 'error'`. */
+    error: PaywallError | null;
+}
+
+export declare class PaywallUI {
+    readonly billing: BillingClient;
+    /** AuthClient (managed-auth) или undefined в hybrid-режиме. Доступен публично:
+     *  host может вызывать `paywall.auth?.signOut()`, читать `getCachedSession()`,
+     *  подписываться на `onAuthChange` напрямую. */
+    readonly auth: AuthClient | undefined;
+    private ownsAuth;
+    private host?;
+    private shadowMode;
+    private handle;
+    private isOpen;
+    private listeners;
+    private userUnsub;
+    private authUnsub;
+    private watcher;
+    private tracker;
+    private purchased;
+    /** Lazy-инстанс TrialStore. Резолвится при первом open(), когда уже знаем
+     *  `bootstrap.settings.trial`. null — триал отключён в конфиге пейвола. */
+    private trialStore;
+    /** Конфиг, под который создан текущий trialStore — пересобираем, если он
+     *  поменялся между bootstrap-фетчами (например, владелец переключил режим
+     *  в админке между сессиями SDK). */
+    private trialStoreConfig;
+    /** In-memory snapshot последнего check() — для синхронного getTrialStatus(). */
+    private lastTrialStatus;
+    /** Флаг dedupe для `trial_expired` события в рамках жизни инстанса. */
+    private trialExpiredFired;
+    /** In-memory snapshot последнего bootstrap'а — для синхронного getVisibility(). */
+    private lastVisibility;
+    /** Поведение open() при холодном bootstrap'е. См. PaywallUIOptions.mountThenLoad. */
+    private mountThenLoad;
+    /** Текущий snapshot UI state-machine. Обновляется PaywallRoot'ом через
+     *  `onState` prop; при close сбрасывается обратно в CLOSED_STATE. */
+    private currentState;
+    private stateListeners;
+    constructor(opts: PaywallUIOptions);
+    private initTracker;
+    /**
+     * Отправить произвольное аналитическое событие. Имена из системного whitelist'а
+     * (`app_opened`, `paywall_viewed`, ...) разрешены как есть. Кастомные —
+     * с префиксом `host:` (например `host:user_clicked_upgrade`). Сервер
+     * дропает события с неразрешёнными именами.
+     *
+     * Самый частый кейс — `track('app_opened')` от хоста сразу после загрузки
+     * приложения, чтобы зафиксировать воронку до открытия пейвола.
+     */
+    track(name: string, props?: Record<string, unknown>): void;
+    /**
+     * Удобный шорткат вместо `paywall.on('userChange', cb)` — самый частый
+     * паттерн в host-коде, поэтому отдельный named метод. Колбек получает
+     * last-known user из кеша синхронно через microtask, если он есть.
+     */
+    onUserChange(handler: PaywallEventHandler<'userChange'>): () => void;
+    on<E extends PaywallEvent>(event: E, handler: PaywallEventHandler<E>): () => void;
+    off<E extends PaywallEvent>(event: E, handler: PaywallEventHandler<E>): void;
+    private emit;
+    open(opts?: OpenOptions): void;
+    /**
+     * Прогревает bootstrap-кеш и balance-кеш заранее, без открытия модалки.
+     * Полезно когда host знает, что юзер скоро откроет paywall (hover на CTA,
+     * mount компонента) — первый `open()` рендерится мгновенно, без loading-flash.
+     *
+     * Не throw'ает: если сеть упала, тихо игнорирует (повторный open() сделает
+     * fresh-bootstrap с error-state как обычно). `signal` для отмены — например,
+     * если хост размонтирует компонент быстрее, чем bootstrap вернётся.
+     *
+     * Вызывать можно сколько угодно раз — последующие вызовы возвращают cached
+     * Promise (BillingClient уже дедуплицирует).
+     */
+    preload(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Открывает модалку сразу с саппорт-формой (минуя layout с тарифами).
+     * Полезно, когда host-приложение хочет дать юзеру кнопку «Help / Support»,
+     * не связанную с пейволом-апгрейдом. Back/Done в саппорт-форме закрывают
+     * модалку (не возвращают к тарифам), потому что юзер пришёл сюда напрямую.
+     *
+     * Из обычного `paywall.open()`-flow саппорт всё равно доступен через
+     * Contact Support-ссылку в `current_session`-блоке (там Back возвращает
+     * к layout).
+     */
+    openSupport(opts?: OpenOptions): void;
+    /**
+     * Открывает модалку сразу с auth-gate (логин/регистрация), без layout с
+     * тарифами. Сценарий: returning customer уже купил, ему просто нужно
+     * залогиниться, чтобы SDK подцепил его purchases. После signIn модалка
+     * закрывается; Back тоже закрывает (юзер пришёл только за логином).
+     *
+     * Без `auth` (managed-auth не подключён) метод — no-op: некому делать
+     * signIn. Если юзер уже залогинен — модалка всё равно откроется и
+     * закроется через auto-resume в auth_gate effect'е (мгновение).
+     *
+     * Триал не блокирует этот флоу — auth не connect'ится с trial-механикой.
+     */
+    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).
+     *
+     * После успешного signIn'а модалка закрывается; host подхватывает свежую
+     * session через `auth.onAuthChange` или `paywall.onUserChange`. Для UX
+     * "просто залогиниться чтобы api-gateway работал, без покупок".
+     *
+     * Без managed-auth (`auth` не подключён) метод — no-op. Триал и
+     * visibility-таргетинг этот flow обходит: анон-логин не должен зависеть
+     * от страны юзера или trial-стейджа.
+     */
+    openAnonGate(opts?: OpenOptions): void;
+    private openInternal;
+    /** Применить gates ПОСЛЕ того, как модалка уже смонтирована (mount-then-load
+     *  путь). Если gate блокирует — close() + emit. Если юзер уже сам закрыл
+     *  модалку до резолва bootstrap'а — no-op (isOpen=false). */
+    private runDelayedGates;
+    private runOpenGates;
+    private gateThroughTrial;
+    private ensureTrialStore;
+    private mountAndShow;
+    private applyState;
+    /**
+     * Sync-snapshot текущего состояния модалки. Подходит для `useSyncExternalStore`
+     * в React (`useSyncExternalStore(paywall.onStateChange, paywall.getState)`)
+     * и для одноразовых проверок («открыт ли пейвол сейчас?»).
+     *
+     * Snapshot стабилен — пока state не изменился, повторный getState() вернёт
+     * `===`-равный объект (важно для useSyncExternalStore чтобы не ре-рендерить).
+     */
+    getState(): PaywallStateSnapshot;
+    /**
+     * Подписка на изменения state. Колбек вызывается при каждом реальном
+     * изменении (closed → loading → ready → ...). По умолчанию initial snapshot
+     * отдаётся через microtask после подписки; через `{immediate: 'sync'|'none'}`
+     * можно сделать sync-доставку (для useSyncExternalStore — там она не нужна,
+     * snapshot читается через getSnapshot отдельно) или вовсе пропустить
+     * initial.
+     *
+     * Возвращает unsubscribe.
+     */
+    onStateChange(cb: PaywallStateListener, opts?: {
+        immediate?: 'microtask' | 'sync' | 'none';
+    }): () => void;
+    /** Sync-доступ к последнему известному статусу триала. null — `paywall.open()`
+     *  ещё не вызывался либо триал отключён в конфиге пейвола. Удобно для
+     *  собственного UI хоста («осталось 3 показа», «триал истечёт через 2ч»). */
+    getTrialStatus(): TrialStatus | null;
+    /** Sync-доступ к последнему server-computed visibility-статусу. null —
+     *  bootstrap ещё не загружен или сервер не отдаёт `settings.visibility`
+     *  (например, старая версия online без targeting-патча). Хост может
+     *  использовать для собственного fallback'а: «сервис недоступен в вашей
+     *  стране». Обновляется на каждом open(), который проходит через gate. */
+    getVisibility(): VisibilityStatus | null;
+    /**
+     * Цены пейвола — шорткат над `bootstrap()`. Локали уже применены, кэш и
+     * stale-while-revalidate идентичны `billing.bootstrap()`. Подходит для
+     * pricing-страниц/карточек на сайте, где host хочет показать те же цены,
+     * что и в модалке, не вытаскивая bootstrap руками.
+     */
+    getPrices(opts?: {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<PaywallPrice[]>;
+    /** Sync-снимок цен. null — bootstrap ещё не загружали. */
+    getCachedPrices(): PaywallPrice[] | null;
+    /** Снимок текущего «языка юзера» — proxy над `billing.getUserLanguage()`.
+     *  Используй, чтобы синхронизировать i18n host'а с тем, что фактически
+     *  показывает пейвол. См. подробности в `BillingClient.getUserLanguage`. */
+    getUserLanguage(): UserLanguageInfo;
+    /**
+     * Решает, нужно ли блокировать фичу для текущего юзера. Без побочных эффектов
+     * (на trial-storage `recordBlock` не вызывается, модалка не монтируется).
+     *
+     * Порядок проверок (первый сработавший — финальный):
+     *  1. `has_active_subscription` — самый сильный сигнал, перебивает остальные.
+     *     Юзер с подпиской получает доступ независимо от visibility/trial.
+     *  2. `visibility` (страна/девайс/disabled-флаг) — юзер вне monetization-scope'а
+     *     пейвола, гейтить нельзя.
+     *  3. `trial` — пре-пейвольный бесплатный период активен.
+     *  4. Иначе — `blocked`, host лочит фичу и зовёт `paywall.open()`.
+     *
+     * Bootstrap кешируется в BillingClient — `getAccess()` можно дёргать на
+     * каждый рендер host-компонента, /bootstrap не дублируется. При упавшей сети
+     * fallback на persistent-cached user из storage: юзер с прошлой подпиской
+     * получает `granted` офлайн, иначе `blocked` (host покажет пейвол с
+     * error-state, юзер сможет ретрайнуть). Side-эффект: обновляются
+     * `lastVisibility` / `lastTrialStatus`, чтобы синхронные геттеры
+     * `getVisibility()` / `getTrialStatus()` видели свежие данные после первого
+     * `getAccess()`, а не только после первого `open()`.
+     */
+    getAccess(opts?: GetAccessOptions): Promise<PaywallAccessResult>;
+    /** Сбросить состояние триала в storage. Полезно для дев-режима / админ-кнопки
+     *  «прогнать сценарий заново». В проде хост обычно не дёргает. */
+    resetTrial(): Promise<void>;
+    private startUserWatcher;
+    close(): void;
+    /**
+     * Сканирует текущий URL на маркеры возврата с checkout и эмитит
+     * purchase_completed / purchase_failed. Маркеры удаляются из URL
+     * через history.replaceState. Ищет и в hash, и в search (hash приоритетнее —
+     * защита от клиентских SPA-роутеров, перехватывающих query).
+     */
+    checkReturn(): void;
+    destroy(): void;
+}
+
+export declare interface PaywallUIOptions extends Omit<BillingClientOptions, 'auth'> {
+    client?: BillingClient;
+    host?: HTMLElement;
+    /** Подключить managed-auth слой. См. {@link AuthOption}. */
+    auth?: AuthOption;
+    /**
+     * Автоматически парсить URL при создании PaywallUI, чтобы поймать возврат
+     * с checkout-провайдера (?paywall_status=paid|failed|cancelled). Дефолт: true.
+     * Эмитит purchase_completed / purchase_failed через microtask — подпишись синхронно.
+     */
+    autoDetectReturn?: boolean;
+    /**
+     * Режим shadow DOM. По умолчанию `closed` — полная изоляция от хоста.
+     * Для e2e тестов (Playwright) и live-preview в админке передавать `open`.
+     */
+    shadowMode?: 'open' | 'closed';
+    /**
+     * Аналитика SDK 3.0. По умолчанию включена. Передай `false` для полного
+     * отключения (ничего не шлётся на бэк). Принимает объект с настройками
+     * batch'а или endpoint-override.
+     */
+    analytics?: boolean | AnalyticsOptions;
+    /**
+     * Когда bootstrap не в кеше — модалку рендерить **сразу** со спиннером и
+     * прогонять gates (visibility/trial) после получения данных, или **ждать**
+     * bootstrap и монтировать только если gates прошли. Дефолт `true` —
+     * snappy open, кнопка «открыть» отзывается мгновенно.
+     *
+     * Trade-off: при `true` и блокирующем gate'е модалка моргнёт (открылась
+     * → закрылась через ~200-500мс). На extension'ах и сайтах с включённым
+     * targeting-fallback'ом это редкий путь, поэтому дефолт оптимизирован
+     * под основной 99%-кейс. Передай `false`, если для вашего use-case'а
+     * флеш на blocked-странах/устройствах хуже воспринимаемой латентности.
+     */
+    mountThenLoad?: boolean;
+}
+
+export declare interface PaywallUser {
+    /** Главный флаг для большинства интеграций. true, если есть активная подписка
+     *  ИЛИ оплаченный lifetime ИЛИ активный trial. */
+    has_active_subscription: boolean;
+    purchases: PaywallUserPurchase[];
+    trial: {
+        started_at: string | null;
+        expires_at: string | null;
+    } | null;
+}
+
+export declare interface PaywallUserPurchase {
+    id: string;
+    status: string | null;
+    current_period_end: string | null;
+    cancel_at_period_end: boolean | null;
+}
+
+/** 402 от api-gateway: квота закончилась. UI ловит и открывает paywall;
+ *  headless caller — обрабатывает сам. balances/queryType/currentBalance —
+ *  то же, что отдаёт бэк в `details`. */
+export declare class QuotaExceededError extends PaywallError {
+    readonly balances: Balance[];
+    readonly queryType: string;
+    readonly currentBalance: Balance | null;
+    constructor(input: {
+        balances: Balance[];
+        queryType: string;
+        currentBalance: Balance | null;
+        message?: string;
+    });
+}
+
+export declare const SDK_VERSION = "3.0.0-alpha.0";
+
+export declare type SignUpResult = {
+    kind: 'signed_in';
+    session: AuthSession;
+} | {
+    kind: 'confirmation_required';
+    user: {
+        id: string;
+        email: string;
+    };
+};
+
+export declare const STORAGE_KEYS: {
+    visitorId: string;
+    lastLoginMethod: (paywallId: string) => string;
+    lastLoginEmail: (paywallId: string) => string;
+    userState: (paywallId: string, identityKey: string) => string;
+    authSession: (paywallId: string) => string;
+    anonRefreshToken: (paywallId: string) => string;
+    bootstrap: (paywallId: string) => string;
+    balances: (paywallId: string, identityKey: string) => string;
+};
+
+export declare interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    /**
+     * Опционально: подписка на изменение `key` извне (другая вкладка /
+     * background-контекст extension'а). Возвращает unsubscribe.
+     *
+     * Контракт callback'а:
+     *  - `value` — новое значение (string) или `null` (удалили / нет).
+     *  - Вызывается ТОЛЬКО для cross-context изменений; собственный setItem
+     *    / removeItem callback дёргать НЕ обязан (для chrome.storage.onChanged
+     *    он дёрнется и так — потребитель обязан фильтровать сам).
+     *
+     * Адаптеры без поддержки (memory) опускают это поле, потребитель должен
+     * проверять `typeof storage.watch === 'function'`.
+     */
+    watch?(key: string, cb: (value: string | null) => void): () => void;
+}
+
+declare interface TimeTrialStatus {
+    mode: 'time';
+    /** true — триал ещё активен, паывол не показывается. */
+    blocked: boolean;
+    /** Unix ms первого `open()`. null — триал ещё не стартовал. */
+    startedAt: number | null;
+    /** Unix ms окончания триала. null — триал ещё не стартовал. */
+    expiresAt: number | null;
+    /** Сколько ещё ms триал активен. 0 — истёк или не активен. */
+    remainingMs: number;
+    /** Полная длина триала в ms (payload часов × 3_600_000). */
+    totalMs: number;
+}
+
+export declare interface TrackedEvent {
+    type: string;
+    ts: number;
+    props?: Record<string, unknown>;
+}
+
+declare interface TrialConfig {
+    /** `time` — паывол скрыт N часов после первого open(); `opens` — N первых
+     *  open() закрываются молча, N+1-й уже показывает паывол. */
+    mode: 'time' | 'opens';
+    /** Часы для `time`, количество открытий для `opens`. */
+    payload: number;
+    /** Где живёт состояние триала. `client` — localStorage (default, мгновенно,
+     *  юзер может сбросить очисткой storage). `server` — серверный endpoint
+     *  (сейчас стаб; включится, когда будет серверный handler). */
+    storage: 'client' | 'server';
+}
+
+/** Статус триала на момент `paywall.open()`. SDK эмитит в payload событий
+ *  `trial_blocked`, и возвращает синхронно из `paywall.getTrialStatus()`. */
+declare type TrialStatus = {
+    mode: 'none';
+    blocked: false;
+} | TimeTrialStatus | OpensTrialStatus;
+
+/** Результат `upgradeAnonymousToEmail`. `updated` — confirmation off либо
+ *  прошёл; session.user.email уже обновлён, is_anonymous=false. `confirmation_required` —
+ *  GoTrue отправил confirmation на новый email; session всё ещё анонимная,
+ *  юзер должен кликнуть ссылку (после чего может вызвать `auth.refresh()` —
+ *  токены обновятся с email'ом и is_anonymous=false). */
+declare type UpgradeAnonymousResult = {
+    kind: 'updated';
+    session: AuthSession;
+} | {
+    kind: 'confirmation_required';
+    email: string;
+};
+
+/** Снимок language-resolution для синхронизации i18n host-приложения с тем, что
+ *  показывает пейвол. Возвращается из `BillingClient.getUserLanguage()` /
+ *  `PaywallUI.getUserLanguage()`. */
+export declare interface UserLanguageInfo {
+    /** Best-guess BCP-47 тэг для host'а. Приоритет: `applied` → `browserLanguage`
+     *  → `countryLanguage`. null — bootstrap ещё не загружен и navigator
+     *  недоступен (например, ранний вызов в service worker). */
+    tag: string | null;
+    /** Ключ из `bootstrap.locales`, который SDK фактически применил к
+     *  layout/prices. null = match'а не было, рендерится база из layout/prices
+     *  без оверрайдов. */
+    applied: string | null;
+    /** `navigator.language` — что репортит браузер. null в окружениях без
+     *  navigator (service worker до пропатчивания, Node). */
+    browserLanguage: string | null;
+    /** Server-resolved язык по стране юзера (IP). Берётся из
+     *  `bootstrap.settings.locale_default` — AT→de, RU→ru, LV→en, и т.д.
+     *  null — bootstrap ещё не загружен или сервер не отдал поле. */
+    countryLanguage: string | null;
+}
+
+declare type UserListener = (user: PaywallUser) => void;
+
+declare interface VisibilityStatus {
+    /** true — паывол можно открывать. false — какой-то таргетинг не сошёлся,
+     *  смотри `reason`. */
+    visible: boolean;
+    /** Почему `visible=false`. null когда `visible=true`.
+     *  - `disabled` — владелец выключил visibility-флаг.
+     *  - `country_not_match` — страна юзера не в whitelist (countries_tier +
+     *    extra_countries).
+     *  - `device_not_match` — extension-канал (device_target=true), юзер не на
+     *    macOS. Имеет приоритет над country, потому что в этом канале device —
+     *    главное условие.
+     */
+    reason: 'country_not_match' | 'device_not_match' | 'disabled' | null;
+    /** ISO-код страны юзера (по IP). null — не удалось определить. */
+    country: string | null;
+    /** Тир страны 1/2/3 (см. legacy `new_country_code_to_tier`). null — страна
+     *  не определилась. Все unmapped страны → 3. */
+    tier: 1 | 2 | 3 | null;
+}
+
+export { }