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

package/dist/core.d.ts

@@ -248,10 +248,8 @@ export declare class AuthClient {
      * когда сервер начнёт возвращать challenge_required в риск-сценариях,
      * SDK сможет передать proof-of-something обратно без breaking change.
      *
-     * `forceCaptcha: true` пропускает шаги 1-2 и сразу делает /signin (создаёт
-     * нового anon-юзера). Используется в switch-account flow. Имя поля исторически
-     * остаётся `forceCaptcha`, хотя капчи там больше нет — менять имя ломает
-     * host-сигнатуру; смысл «принудительно новая anon-сессия» сохранён.
+     * `forceNewAnon: true` пропускает шаги 1-2 и сразу делает /signin (создаёт
+     * нового anon-юзера). Используется в switch-account flow.
      *
      * Параллельные вызовы дедуплицируются через `inflightAnonSignin` — два
      * click'а на «Войти как гость» не создадут двух anon-юзеров (два /signup =
@@ -260,7 +258,7 @@ export declare class AuthClient {
     signInAnonymously(input?: {
         captchaToken?: string;
         userMeta?: Record<string, string>;
-        forceCaptcha?: boolean;
+        forceNewAnon?: boolean;
     }): Promise<AuthSession>;
     /**
      * Внутренний resume — пробует /auth/refresh с сохранённым anon refresh_token.
@@ -612,6 +610,13 @@ export declare class BillingClient {
     }): Promise<PaywallPrice[]>;
     /** Sync-снимок цен из последнего bootstrap'а. null = ещё не загружали. */
     getCachedPrices(): PaywallPrice[] | null;
+    /** Sync-снимок офферов из последнего bootstrap'а. null = bootstrap ещё не
+     *  загружали, пустой массив = бэк отдал пейвол без офферов. Бэк уже
+     *  применил серверный таргетинг (target_countries / target_emails /
+     *  targeting_mode из offer_settings) — наружу выезжает только то, что
+     *  применимо к текущему юзеру. Клиентская сторона остаётся ответственной
+     *  за price_id-matching и countdown (см. core/offer.ts → resolveOffer). */
+    getCachedOffers(): PaywallOffer[] | null;
     /**
      * Снимок того, какой язык SDK сейчас считает «языком юзера». Полезно для
      * синхронизации i18n хоста с тем, что фактически показывает пейвол — чтобы
@@ -738,6 +743,17 @@ export declare class BillingClient {
         errorUrl?: string;
         shopUrl?: string;
         trialDays?: number;
+        /** Активный offer для этой цены — резолвится host'ом через
+         *  `paywall.getOfferForPrice(priceId)?.offer.id` или
+         *  `findApplicableOffer(client.getCachedOffers(), priceId)?.id`. Без
+         *  явной передачи бэк сделает auto-resolve по email — но только для
+         *  end_date-офферов. duration_minutes-офферы тикают в clientStorage и
+         *  сервер их не видит: для них offerId ОБЯЗАН прийти от клиента, иначе
+         *  скидка не применится на чекауте, хотя UI её показывал.
+         *
+         *  Передавать offer-id всегда безопасно — бэк сам проверит applicable
+         *  ли offer к этому юзеру (страна/email/режим) и игнорирует если нет. */
+        offerId?: string;
         /**
          * Stage 1 защиты от дубликатов покупок. Идемпотентный ключ запроса
          * (UUID). Повторный вызов с тем же ключом вернёт тот же checkout-URL
@@ -764,7 +780,9 @@ export declare class BillingClient {
      * инвойсы). Опен-флоу управляется host'ом:
      *
      * ```ts
-     * const { url } = await billing.getCustomerPortalUrl();
+     * const { url } = await billing.getCustomerPortalUrl({
+     *   returnUrl: 'https://your-app.com/account'
+     * });
      * window.open(url, '_blank');
      * ```
      *
@@ -776,6 +794,14 @@ export declare class BillingClient {
      */
     getCustomerPortalUrl(opts?: {
         signal?: AbortSignal;
+        /** URL для return-button у провайдера (Stripe «Return to ...», Paddle
+         *  и Chargebee redirect_url'ы). Передавай туда страницу-аккаунт твоего
+         *  app'а — `https://your-app.com/account`. Без явного returnUrl бэк
+         *  применяет fallback в порядке: `paywall_settings.shop_url` →
+         *  custom_domain пейвола → NEXT_PUBLIC_ONLINE_ORIGIN (последнее — это
+         *  страница в самом online-сервисе, годится только для legacy
+         *  v2-iframe-флоу). */
+        returnUrl?: string;
     }): Promise<{
         url: string;
     }>;
@@ -786,21 +812,31 @@ export declare class BillingClient {
      * `/api/v1/paywall/[id]/user` без unstable_cache, потому что list для UI
      * должен быть свежим после cancel-а.
      *
-     * Auth: Bearer обязателен (через AuthClient). Без Bearer — 401 от бэка,
-     * пробрасываем как PaywallError('http_401'). Гость → пустой список.
+     * Auth (два пути):
+     *  - Bearer (через AuthClient) — user.id резолвится из сессии, identity
+     *    в query игнорируется.
+     *  - `apiKey` + `identity.email`/`identity.userId` — server-SDK путь для
+     *    интеграций со своей авторизацией. Бэк проверяет, что identity линкована
+     *    к этому пейволу (защита от cross-paywall lookup).
+     * Без auth и без apiKey+identity — `identity_required`.
      */
     listPurchases(opts?: {
         signal?: AbortSignal;
     }): Promise<PaywallPurchaseDetailed[]>;
     /**
-     * Отменить подписку. Бэк проверит что subscription принадлежит auth-юзеру
-     * и сделает cancel у acquiring'а (Stripe/Paddle/Chargebee). По умолчанию
-     * cancel в конце текущего периода — юзер сохраняет access до renewal date'ы.
+     * Отменить подписку. Бэк проверит, что subscription принадлежит юзеру
+     * (Bearer-путь — из сессии; apiKey-путь — из identity), и сделает cancel у
+     * acquiring'а (Stripe/Paddle/Chargebee/Overpay). По умолчанию cancel в
+     * конце текущего периода — юзер сохраняет access до renewal date'ы.
      *
-     * `reason` обязательна (валидация на бэке). Удобно собрать через select
-     * причин в host-UI, как в legacy customer portal'е.
+     * `reason` обязательна (валидация на бэке).
      *
-     * Auth: Bearer обязателен.
+     * Auth (два пути):
+     *  - Bearer (через AuthClient) — стандартный путь для UI customer-portal'a.
+     *  - `apiKey` + `identity.email`/`identity.userId` — для self-service UI на
+     *    бэке клиента со своей авторизацией. Бэк дополнительно фильтрует
+     *    subscription по paywall_id, чтобы owner пейвола A не отменил подписку
+     *    пейвола B.
      */
     cancelSubscription(params: {
         subscriptionId: string;
@@ -931,6 +967,11 @@ export declare interface EventTrackerOptions {
     sendBeacon?: (url: string, data: BodyInit) => boolean;
 }
 
+/** Pick the offer applicable to a price. Targeted (`price_id === id`) wins
+ *  over the global default (`price_id === null`). Offers without a positive
+ *  `discount_percent` are ignored. */
+export declare function findApplicableOffer(offers: PaywallOffer[] | null | undefined, priceId: string): PaywallOffer | null;
+
 export declare function generateVisitorId(): string;
 
 export declare interface Identity {
@@ -1091,6 +1132,11 @@ export declare interface LocaleOverrides {
 
 export declare type OAuthProvider = 'google' | 'apple' | 'github' | 'facebook';
 
+/** Storage key under which a relative `duration_minutes` offer records its
+ *  first-view timestamp. Shared between the renderer (which writes the
+ *  start on first open) and the host SDK helpers (which read it). */
+export declare function offerStartStorageKey(offerId: string): string;
+
 export declare type OtpVerifyType = 'email' | 'recovery' | 'signup' | 'magiclink' | 'invite';
 
 export declare interface PaywallBootstrap {
@@ -1131,8 +1177,10 @@ export declare interface PaywallOffer {
     expires_at: string | null;
     /** Относительный таймер: сколько минут offer живёт **от первого просмотра
      *  пейвола** данным юзером. Старт хранится в clientStorage под ключом
-     *  `pw-offer-{id}-start`, по истечении — auto-cleanup. Используется, когда
-     *  бэк хочет показывать "remaining time" без жёсткой server-time, а считать
+     *  `pw-offer-{id}-start` и остаётся там **после** expiry — это
+     *  forever-marker, чтобы юзер не мог «фармить» offer (re-open пейвола
+     *  не запускает countdown заново). Используется, когда бэк хочет
+     *  показывать "remaining time" без жёсткой server-time, а считать
      *  относительно сессии юзера. expires_at имеет приоритет если задано. */
     duration_minutes?: number | null;
     price_id: string | null;
@@ -1159,7 +1207,7 @@ export declare interface PaywallPrice {
  *  идёт из `/user-state` и имеет минимум для access-gate'а), этот shape
  *  включает цену/валюту/discount — чтобы host мог нарисовать список подписок
  *  как в legacy customer portal'е. */
-declare interface PaywallPurchaseDetailed {
+export declare interface PaywallPurchaseDetailed {
     id: string;
     status: string | null;
     cancel_at: string | null;
@@ -1279,6 +1327,51 @@ export declare class QuotaExceededError extends PaywallError {
     });
 }
 
+/** Safe browser localStorage getter — returns null in SSR / private mode. */
+export declare function readBrowserOfferStart(offerId: string): string | null;
+
+/**
+ * Resolved view of a paywall offer — what host UI actually needs to render
+ * a strike-through price + countdown without re-implementing the math.
+ *
+ * `remainingMs` ticks down with wall-clock time and reaches 0 on expiry.
+ * `totalMs` stays constant — useful for progress bars / share-of-time UX.
+ * `expiresAt` is the Date.now()-comparable epoch ms of expiry.
+ *
+ * For offers without an expiry mechanism (no `expires_at` and no
+ * `duration_minutes`), `remainingMs`/`totalMs`/`expiresAt` are all `null`,
+ * but the resolved view is still returned — discount badge / strike-through
+ * still make sense for "perpetual sale" offers.
+ */
+export declare interface ResolvedOffer {
+    offer: PaywallOffer;
+    discountPercent: number;
+    remainingMs: number | null;
+    totalMs: number | null;
+    expiresAt: number | null;
+}
+
+/** Compute the resolved view of an offer. Pure, no side-effects. */
+export declare function resolveOffer(offer: PaywallOffer, opts?: ResolveOfferOptions): ResolvedOffer | null;
+
+export declare interface ResolveOfferOptions {
+    /** Current epoch ms. Inject for deterministic tests; default `Date.now()`. */
+    now?: number;
+    /**
+     * Synchronous reader for the `duration_minutes` start-timestamp ISO string.
+     * Host passes a closure over its sync storage (browser → `localStorage`,
+     * memory → in-process map). Return `null` if no start has been recorded.
+     *
+     * Intentionally synchronous, because consumers call this from UI render —
+     * an async StorageAdapter would force every price card to suspend.
+     *
+     * If omitted, `duration_minutes`-only offers return `expiresAt = null`,
+     * which makes the resolved view treat them as "not yet started" (the
+     * renderer is responsible for writing the start on first paywall view).
+     */
+    readStart?: (offerId: string) => string | null;
+}
+
 export declare const SDK_VERSION = "3.0.0-alpha.0";
 
 export declare type SignUpResult = {