@monetize.software/sdk 3.0.0-alpha.0

package/dist/core.d.ts

@@ -0,0 +1,1229 @@
+declare type Acquiring = 'stripe' | 'paddle' | 'chargebee' | 'overpay' | 'freemius';
+
+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;
+}
+
+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 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 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 type OtpVerifyType = 'email' | 'recovery' | 'signup' | 'magiclink' | 'invite';
+
+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 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;
+}
+
+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;
+}
+
+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';
+}
+
+/** Результат `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 { }