@monetize.software/sdk-react 3.0.0-alpha.2 → 3.0.0-alpha.20

package/README.md

@@ -1,13 +1,17 @@
 # @monetize.software/sdk-react
 
-React bindings для [`@monetize.software/sdk`](../sdk) — Provider, хуки и декларативные компоненты для пейвола. Работает с web SDK и extension SDK (любой drop-in-совместимый `PaywallUI`).
+React bindings for [`@monetize.software/sdk`](../sdk) — Provider, hooks and
+declarative paywall components. Works with the web SDK and the extension SDK
+(any drop-in-compatible `PaywallUI`).
 
-- **Bundle**: < 2 KB gzip (только bindings, никакого UI — он внутри SDK).
-- **React**: >= 18, использует `useSyncExternalStore` для concurrent-safe чтения снимков.
-- **SSR**: безопасно. На сервере хуки отдают `null` / `{ status: 'loading' }`, инстанс PaywallUI создаётся только на клиенте.
-- **TypeScript**: полный тип-уровень контракт ([`src/contract.ts`](src/contract.ts)) — если в основном SDK поедет публичная поверхность, сборка sdk-react падает на этапе `tsc`.
+- **Bundle**: < 2 KB gzip (bindings only — the UI lives inside the SDK).
+- **React**: >= 18, uses `useSyncExternalStore` for concurrent-safe snapshot reads.
+- **SSR**: safe out of the box. On the server, hooks return `null` /
+  `{ status: 'loading' }`; the `PaywallUI` instance is created only on the client.
+- **TypeScript**: full type-level contract ([`src/contract.ts`](src/contract.ts)) —
+  if the public surface of the SDK shifts, the `sdk-react` build fails at `tsc`.
 
-## Установка
+## Installation
 
 ```bash
 pnpm add @monetize.software/sdk-react @monetize.software/sdk react
@@ -25,7 +29,13 @@ import {
 
 function App() {
   return (
-    <PaywallProvider options={{ paywallId: 'YOUR_ID', auth: true }}>
+    <PaywallProvider
+      options={{
+        paywallId: 'YOUR_ID',
+        apiOrigin: 'https://your-paywall-domain.com',
+        auth: true
+      }}
+    >
       <PaywallGate fallback={<UpgradeCTA />}>
         <PremiumFeature />
       </PaywallGate>
@@ -36,54 +46,64 @@ function App() {
 }
 
 function UpgradeCTA() {
-  const user = usePaywallUser();
-  return <p>Привет, {user?.email ?? 'гость'}! Открой полный доступ.</p>;
+  const account = usePaywallUser();
+  if (account.status === 'loading') return <p>…</p>;
+  if (account.status === 'guest') return <p>Hi guest! Unlock full access.</p>;
+  return <p>Hi, {account.user?.email ?? 'there'}! Unlock full access.</p>;
 }
 ```
 
+`apiOrigin` must match the `custom_domain` configured for your paywall in the
+platform.
+
 ## Provider
 
-`<PaywallProvider>` принимает один из двух пропсов:
+`<PaywallProvider>` accepts one of two props:
 
 ```tsx
-// Вариант 1 — Provider сам создаёт инстанс
+// Option 1 — Provider creates the instance itself
 <PaywallProvider options={{ paywallId, apiOrigin, auth: true }}>
 
-// Вариант 2 — готовый инстанс снаружи (extension / shared / тесты)
+// Option 2 — host supplies a ready instance (extension / shared singleton / tests)
 import { createPaywallUI } from '@monetize.software/sdk-extension';
-const paywall = createPaywallUI({ paywallId });
+const paywall = createPaywallUI({ paywallId, apiOrigin });
 
 <PaywallProvider instance={paywall}>
 ```
 
-Если `paywallId` динамически меняется, перемонтируй Provider через `<PaywallProvider key={paywallId} options={...}>` — реактивная пересборка опций намеренно не делается.
+If `paywallId` changes dynamically, remount the Provider via
+`<PaywallProvider key={paywallId} options={...}>` — reactive option rebuilds are
+intentionally not performed.
 
-## Хуки
+## Hooks
 
-| Хук | Возвращает | Когда триггерит rerender |
+| Hook | Returns | When it triggers a rerender |
 |---|---|---|
-| `usePaywall()` | `PaywallUI \| null` | смена инстанса (редко) |
-| `usePaywallState()` | `{ open, view, error }` | любое изменение state-машины |
-| `usePaywallUser()` | `PaywallUser \| null` | event `userChange` |
+| `usePaywall()` | `PaywallUI \| null` | instance change (rare) |
+| `usePaywallState()` | `{ open, view, error }` | any state-machine change |
+| `usePaywallUser()` | `PaywallUserState` (`loading` \| `guest` \| `signed_in`) | `userChange` / `authChange` |
 | `usePaywallAccess(opts?)` | `{ status, result }` | `userChange` / `purchase_completed` |
 | `usePaywallPrices()` | `{ prices, loading, error }` | bootstrap refresh |
+| `usePaywallOffer(priceId)` | `ResolvedOffer \| null` | `ready` + 1Hz tick while countdown is live |
+| `usePaywallOffers()` | `PaywallOffer[] \| null` | `ready` (bootstrap refresh) |
 | `usePaywallTrial()` | `TrialStatus \| null` | `trial_blocked` / `trial_expired` |
 | `usePaywallVisibility()` | `VisibilityStatus \| null` | `ready` / `visibility_blocked` |
-| `usePaywallEvent(event, handler)` | — | подписка с stable-handler-ref |
+| `usePaywallEvent(event, handler)` | — | subscribes with a stable handler ref |
 
-Все хуки безопасны до mount-а Provider'а (отдают `null` / loading) — можно использовать в SSR без `'use client'`-обёрток на ветке дерева.
+All hooks are safe before the Provider mounts (they return `null` / loading) —
+you can use them in SSR without `'use client'` wrappers on the consuming subtree.
 
-## Компоненты
+## Components
 
 ### `<PaywallGate>`
 
-Декларативный гейт: loading → fallback → children.
+Declarative gate: loading → fallback → children.
 
 ```tsx
 <PaywallGate
   loading={<Skeleton />}
   fallback={({ open }) => <button onClick={open}>Upgrade</button>}
-  openOnBlocked={false}  // если true — автоматом дёргает paywall.open()
+  openOnBlocked={false}  // if true — calls paywall.open() automatically
 >
   <PremiumFeature />
 </PaywallGate>
@@ -91,7 +111,9 @@ const paywall = createPaywallUI({ paywallId });
 
 ### `<PaywallButton>` / `<PaywallSupportButton>`
 
-Сахар над `paywall.open()`. По умолчанию рендерится как нативный `<button>` со всеми твоими `className`/`disabled`/`aria-*`. Для кастомного элемента — render-prop:
+Sugar over `paywall.open()`. By default renders a native `<button>` with all
+your `className`/`disabled`/`aria-*` props forwarded. For a custom element use
+the render prop:
 
 ```tsx
 <PaywallButton render={({ open, ready }) => (
@@ -99,58 +121,72 @@ const paywall = createPaywallUI({ paywallId });
 )} />
 ```
 
-`mode` переключает между `open()` / `openSupport()` / `openAuth()` / `openAnonGate()`:
+`mode` switches between `open()` / `openSupport()` / `openSignin()` / `openSignup()`:
 
 ```tsx
 <PaywallButton mode="support">Need help?</PaywallButton>
-<PaywallButton mode="auth">Sign in</PaywallButton>
+<PaywallButton mode="signin">Sign in</PaywallButton>
+<PaywallButton mode="signup">Create account</PaywallButton>
 ```
 
+`mode="auth"` оставлен как алиас для `signin` (back-compat).
+
+Для анонимного signin'а используй `usePaywall().signInAnonymously()` напрямую — он headless (без модалки), хост сам управляет loading-стейтом кнопки.
+
 ## SSR / Next.js
 
 ```tsx
-'use client';  // на Provider, не на дерево потомков
+'use client';  // on the Provider, not on the consumer subtree
 
 import { PaywallProvider } from '@monetize.software/sdk-react';
 
 export function PaywallProviders({ children }) {
   return (
-    <PaywallProvider options={{ paywallId: process.env.NEXT_PUBLIC_PAYWALL_ID! }}>
+    <PaywallProvider
+      options={{
+        paywallId: process.env.NEXT_PUBLIC_PAYWALL_ID!,
+        apiOrigin: process.env.NEXT_PUBLIC_PAYWALL_ORIGIN!
+      }}
+    >
       {children}
     </PaywallProvider>
   );
 }
 ```
 
-Хуки можно вызывать из server components только при типизированных-null-сценариях (всё равно вернётся `null`/`loading`). Рекомендация — выносить хук-логику в client component.
+Hooks can be called from server components in typed-null scenarios (they'll
+return `null` / loading anyway). The recommendation is to keep hook logic in a
+client component.
 
-## Защита от изменений в SDK
+## SDK contract guard
 
-`pnpm typecheck` проверяет [`src/contract.ts`](src/contract.ts) — там перечислены все точки опоры на public API SDK (методы PaywallUI, поля snapshot'ов, имена событий). Любое разъезжание в `../sdk` ловится здесь раньше, чем в проде.
+`pnpm typecheck` validates [`src/contract.ts`](src/contract.ts) — it lists every
+point of contact with the public SDK API (`PaywallUI` methods, snapshot fields,
+event names). Any drift in `../sdk` is caught here before it hits production.
 
-После изменений в SDK обнови dist для типов:
+After SDK changes, refresh the dist for type resolution:
 
 ```bash
 cd ../sdk && pnpm build
 cd ../sdk-react && pnpm typecheck
 ```
 
-## Разработка
+## Development
 
 ```bash
 pnpm install
 pnpm dev          # → http://localhost:5080/demo/
-pnpm typecheck    # TS-валидация + контракт
+pnpm typecheck    # TS validation + contract guard
 pnpm test         # vitest + @testing-library/react
-pnpm test:e2e     # playwright против демо
+pnpm test:e2e     # playwright against the demo
 pnpm build        # ESM + CJS + d.ts → dist/
 ```
 
 ## API reference
 
-Полные JSDoc-комментарии на каждый публичный экспорт смотри в исходниках:
+Full JSDoc comments on every public export are inline in the sources:
 
 - [`src/PaywallProvider.tsx`](src/PaywallProvider.tsx) — Provider, lifecycle
-- [`src/hooks/`](src/hooks/) — все хуки
-- [`src/components/`](src/components/) — декларативные компоненты
-- [`src/contract.ts`](src/contract.ts) — точки опоры на SDK
+- [`src/hooks/`](src/hooks/) — all hooks
+- [`src/components/`](src/components/) — declarative components
+- [`src/contract.ts`](src/contract.ts) — SDK contact points

package/dist/PaywallProvider.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { PaywallUI, PaywallUIOptions } from '../../sdk/src';
+import { PaywallUI, PaywallUIOptions } from '@monetize.software/sdk';
 /**
  * Два взаимоисключающих режима использования:
  *

package/dist/components/PaywallButton.d.ts

@@ -1,5 +1,5 @@
 import { ButtonHTMLAttributes, ReactElement, ReactNode } from 'react';
-import { OpenOptions } from '../../../sdk/src';
+import { OpenOptions } from '@monetize.software/sdk';
 /**
  * Параметры открытия пейвола, проксируются в `paywall.open(opts)`.
  * Любые поля {@link OpenOptions} применимы: `identity`, `renew`, `skipTrial`,
@@ -7,8 +7,18 @@ import { OpenOptions } from '../../../sdk/src';
  */
 type OpenProps = OpenOptions;
 interface CommonProps extends OpenProps {
-    /** Что открывать: layout (default), support, auth-gate, anon-gate. */
-    mode?: 'paywall' | 'support' | 'auth' | 'anon';
+    /** Что открывать: layout (default), support, auth-gate (signin),
+     *  signup-форма. 'auth' эквивалентен 'signin' (исторически — openAuth
+     *  дефолтит в signin-mode). Для анонимного signin используй
+     *  `usePaywall().signInAnonymously()` напрямую — headless без модалки. */
+    mode?: 'paywall' | 'support' | 'auth' | 'signin' | 'signup';
+    /** Direct-checkout: при заданном `priceId` клик вызывает
+     *  `paywall.checkout(priceId, opts)` минуя layout с тарифами. `mode`
+     *  при этом игнорируется. Layout-flow (`mode='paywall'`, дефолт) и
+     *  direct-checkout — взаимоисключающие: либо юзер выбирает план в
+     *  модалке, либо хост уже выбрал и ведёт в checkout. См.
+     *  `PaywallUI.checkout()` про preauth/already-paid поведение. */
+    priceId?: string;
     /** Render-prop для полного контроля над элементом-триггером. Когда задан,
      *  все обычные `<button>`-пропсы (children, type, и т.д.) игнорируются. */
     render?: (args: PaywallButtonRenderArgs) => ReactElement;
@@ -18,6 +28,11 @@ export interface PaywallButtonRenderArgs {
     open: () => void;
     /** Готов ли инстанс PaywallUI. До mount-а Provider'а / на SSR — `false`. */
     ready: boolean;
+    /** Direct-checkout в процессе headless bootstrap+createCheckout (только когда
+     *  у кнопки задан `priceId`). Render-prop может показать спиннер прямо на
+     *  своей кнопке и задизейблить её, чтобы юзер не кликал ещё раз. Для
+     *  не-priceId-режимов всегда false. */
+    processing: boolean;
 }
 /**
  * Props собственно `<button>`-рендера. Любые HTML-атрибуты — `disabled`,
@@ -48,6 +63,12 @@ export type PaywallButtonProps = CommonProps & ButtonRenderProps;
  *
  * // саппорт-форма вместо тарифов
  * <PaywallButton mode="support">Need help?</PaywallButton>
+ *
+ * // direct-checkout: хост уже выбрал план в своём UI (pricing-карточки),
+ * // клик ведёт прямо в провайдера, минуя layout с тарифами.
+ * <PaywallButton priceId={price.id} className="btn-primary">
+ *   Get this plan
+ * </PaywallButton>
  * ```
  *
  * До mount-а Provider'а или на SSR кнопка рендерится с `disabled=true`

package/dist/components/PaywallButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PaywallButton.d.ts","sourceRoot":"","sources":["../../src/components/PaywallButton.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1D;;;;GAIG;AACH,KAAK,SAAS,GAAG,WAAW,CAAC;AAE7B,UAAU,WAAY,SAAQ,SAAS;IACrC,sEAAsE;IACtE,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/C;+EAC2E;IAC3E,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,uBAAuB,KAAK,YAAY,CAAC;CAC1D;AAED,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,KAAK,iBAAiB,GAAG,IAAI,CAC3B,oBAAoB,CAAC,iBAAiB,CAAC,EACvC,MAAM,SAAS,GAAG,UAAU,CAC7B,GAAG;IACF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa;eA9Bb,SAAS;qDAyFrB,CAAC"}
+{"version":3,"file":"PaywallButton.d.ts","sourceRoot":"","sources":["../../src/components/PaywallButton.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D;;;;GAIG;AACH,KAAK,SAAS,GAAG,WAAW,CAAC;AAE7B,UAAU,WAAY,SAAQ,SAAS;IACrC;;;8EAG0E;IAC1E,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC5D;;;;;qEAKiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;+EAC2E;IAC3E,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,uBAAuB,KAAK,YAAY,CAAC;CAC1D;AAED,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;IACf;;;2CAGuC;IACvC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,KAAK,iBAAiB,GAAG,IAAI,CAC3B,oBAAoB,CAAC,iBAAiB,CAAC,EACvC,MAAM,SAAS,GAAG,UAAU,CAC7B,GAAG;IACF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,aAAa;eApCb,SAAS;qDAiHrB,CAAC"}

package/dist/components/PaywallGate.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { PaywallAccessResult } from '../../../sdk/src';
+import { PaywallAccessResult } from '@monetize.software/sdk';
 export interface PaywallGateProps {
     /** Что показать, пока `getAccess()` не вернул ответ (initial fetch / Provider mount). */
     loading?: ReactNode;

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import { PaywallUI } from '../../sdk/src';
+import { PaywallUI } from '@monetize.software/sdk';
 /**
  * Внутренний React Context, в который PaywallProvider кладёт PaywallUI-инстанс.
  *

package/dist/hooks/usePaywall.d.ts

@@ -1,4 +1,4 @@
-import { PaywallUI } from '../../../sdk/src';
+import { PaywallUI } from '@monetize.software/sdk';
 /**
  * Достаёт PaywallUI-инстанс из ближайшего {@link PaywallProvider}.
  *

package/dist/hooks/usePaywallAccess.d.ts

@@ -1,4 +1,4 @@
-import { GetAccessOptions, PaywallAccessResult } from '../../../sdk/src';
+import { GetAccessOptions, PaywallAccessResult } from '@monetize.software/sdk';
 /**
  * `loading` — первый fetch ещё в полёте (или Provider не готов).
  * `ready` — есть свежий ответ; `result` гарантированно non-null.

package/dist/hooks/usePaywallEvent.d.ts

@@ -1,4 +1,4 @@
-import { PaywallEvent, PaywallEventHandler } from '../../../sdk/src';
+import { PaywallEvent, PaywallEventHandler } from '@monetize.software/sdk';
 /**
  * Декларативная подписка на событие PaywallUI. Обёртка над `paywall.on(event, cb)`
  * с двумя важными отличиями от ручного useEffect:

package/dist/hooks/usePaywallOffer.d.ts

@@ -0,0 +1,42 @@
+import { ResolvedOffer } from '@monetize.software/sdk';
+/**
+ * Reactive resolved offer for a given price.
+ *
+ * Returns the same shape as `paywall.getOfferForPrice(priceId)`, plus a live
+ * countdown — re-renders every second while there's a positive `remainingMs`,
+ * stops ticking when the offer expires (one final re-render brings the value
+ * to `null`). Re-fetches on `ready` event too, so a bootstrap refresh that
+ * brings new offers reflects immediately.
+ *
+ * Returns `null` when:
+ *  - Provider isn't mounted yet (SSR / pre-mount);
+ *  - bootstrap hasn't loaded the offers list;
+ *  - no offer targets this price (no targeted match, no global offer);
+ *  - the matching offer is a `duration_minutes`-only timer that hasn't been
+ *    started yet (i.e. the paywall hasn't been opened by this user). The
+ *    renderer writes the start on first paywall view — refreshing the page
+ *    after the first view will then surface the countdown here.
+ *  - the matching offer has already expired.
+ *
+ * ```tsx
+ * const offer = usePaywallOffer(price.id);
+ *
+ * if (!offer) return <span>{formatAmount(price.amount)}</span>;
+ *
+ * const discounted = price.amount * (1 - offer.discountPercent / 100);
+ * return (
+ *   <>
+ *     <s>{formatAmount(price.amount)}</s>
+ *     <strong>{formatAmount(discounted)}</strong>
+ *     <Badge>-{offer.discountPercent}%</Badge>
+ *     {offer.remainingMs !== null && <Countdown ms={offer.remainingMs} />}
+ *   </>
+ * );
+ * ```
+ *
+ * Implementation: a single `setInterval(1000)` ticks while there's a live
+ * countdown. The PaywallUI handle is read on each tick, so a Provider re-mount
+ * doesn't leave a stale closure.
+ */
+export declare function usePaywallOffer(priceId: string): ResolvedOffer | null;
+//# sourceMappingURL=usePaywallOffer.d.ts.map

package/dist/hooks/usePaywallOffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePaywallOffer.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallOffer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAoDrE"}

package/dist/hooks/usePaywallOffers.d.ts

@@ -0,0 +1,16 @@
+import { PaywallOffer } from '@monetize.software/sdk';
+/**
+ * Cached offers list, refreshed on every `ready` event (= bootstrap refresh).
+ *
+ * Returns `null` before bootstrap loads, then the server-filtered offer list
+ * (server-side targeting on countries / emails / mode is already applied).
+ * Client code is still responsible for `price_id` matching (use
+ * `findApplicableOffer` from `@monetize.software/sdk` or the higher-level
+ * `usePaywallOffer(priceId)` hook).
+ *
+ * Mostly useful for hosts that want to iterate offers manually (e.g. render
+ * a global "Limited offer" banner above the page). For per-price strike-
+ * through + countdown, `usePaywallOffer(priceId)` is the right primitive.
+ */
+export declare function usePaywallOffers(): PaywallOffer[] | null;
+//# sourceMappingURL=usePaywallOffers.d.ts.map

package/dist/hooks/usePaywallOffers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePaywallOffers.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallOffers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,YAAY,EAAE,GAAG,IAAI,CAgBxD"}

package/dist/hooks/usePaywallPrices.d.ts

@@ -1,4 +1,4 @@
-import { PaywallPrice } from '../../../sdk/src';
+import { PaywallPrice } from '@monetize.software/sdk';
 /**
  * `prices` — кешированный snapshot bootstrap.prices (`null` до первого fetch'а
  * или когда инстанс ещё не готов).

package/dist/hooks/usePaywallState.d.ts

@@ -1,4 +1,4 @@
-import { PaywallStateSnapshot } from '../../../sdk/src';
+import { PaywallStateSnapshot } from '@monetize.software/sdk';
 /**
  * Подписка на состояние модалки пейвола: открыта/закрыта, текущий view,
  * последняя ошибка.

package/dist/hooks/usePaywallState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePaywallState.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAYnE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,IAAI,oBAAoB,CAmBtD"}
+{"version":3,"file":"usePaywallState.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAiBnE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,IAAI,oBAAoB,CAmBtD"}

package/dist/hooks/usePaywallTrial.d.ts

@@ -1,4 +1,4 @@
-import { PaywallUI } from '../../../sdk/src';
+import { PaywallUI } from '@monetize.software/sdk';
 type TrialStatus = NonNullable<ReturnType<PaywallUI['getTrialStatus']>>;
 /**
  * Текущий статус триала ({@link TrialStatus}) с автоматическим ре-рендером на

package/dist/hooks/usePaywallUser.d.ts

@@ -1,30 +1,50 @@
-import { PaywallUser } from '../../../sdk/src';
+import { AuthSession, PaywallUser } from '@monetize.software/sdk';
 /**
- * Подписка на текущего юзера пейвола (sync snapshot + автоматический ре-рендер
- * на любой userChange — bootstrap, /me refresh, после-checkout watcher).
+ * Состояние «кто такой текущий пользователь» с точки зрения хоста.
  *
- * Возвращает `null` до первого ответа сети или когда инстанс ещё не готов
- * (SSR / до useEffect Provider'а / Provider не оборачивает дерево с инстансом).
+ * Discriminated union намеренно совмещает три источника: готовность инстанса
+ * PaywallUI (Provider mount), наличие session у managed-auth и `getCachedUser()`
+ * от bootstrap'а. Это убирает у хоста нужду различать «пейвол ещё грузится»
+ * vs «никого нет» вручную — типы сужают каждый случай.
  *
- * Удобно для подсветки текущего плана / e-mail юзера в собственном UI без
- * необходимости держать дублирующий state и руками подписываться на
- * `paywall.on('userChange', ...)`.
+ *  - `loading` — Provider ещё не смонтировал PaywallUI (SSR / pre-mount /
+ *     dev-double-mount cleanup). На этом этапе показывать skeleton.
+ *  - `guest` — у пейвола нет identity:
+ *      • managed-auth: `auth.getCachedSession()` вернул null;
+ *      • hybrid (без managed-auth): bootstrap прошёл, но user-snapshot пуст.
+ *     В этом состоянии валидно показать CTA «Sign in» / `<PaywallButton mode="signin">`.
+ *  - `signed_in` — есть identity. `user` — последний снимок из BillingClient
+ *     (может быть `null`, пока /me-refresh после signIn в полёте — UI должен
+ *     показать skeleton, не «sign-in» CTA). `session` — managed-auth session
+ *     или `null` для hybrid-режима.
  *
+ * Хост обычно делает три проверки подряд:
  * ```tsx
- * const user = usePaywallUser();
- * if (user?.has_active_subscription) {
- *   return <ProBadge plan={user.active_subscription?.plan_name} />;
- * }
+ * const account = usePaywallUser();
+ * if (account.status === 'loading') return <Skeleton />;
+ * if (account.status === 'guest') return <SignInCTA />;
+ * // account.user может быть null, пока /me грузится — показать skeleton тут же.
+ * if (!account.user) return <Skeleton />;
+ * return <Profile user={account.user} />;
  * ```
  *
- * Реализация поверх `paywall.on('userChange', cb)` + `billing.getCachedUser()`.
- * `paywall.on` не делает initial replay'я, поэтому useSyncExternalStore сам
- * читает старт-snapshot через getSnapshot — без лишних cb-вызовов.
- *
- * Ссылочная стабильность: BillingClient сравнивает user shape перед update'ом
- * (`sameUser`), так что между неизменными обновлениями `getCachedUser()`
- * возвращает ===-равный объект. Это гарантирует, что useSyncExternalStore
- * не дёргает ре-рендер при no-op refresh'ах.
+ * Реализация подписана и на `userChange`, и на `authChange` — любой источник
+ * меняющий status триггерит rerender. Snapshot reference закеширован через
+ * useRef, чтобы useSyncExternalStore не словил infinite-loop на новых
+ * объектах при каждом getSnapshot.
  */
-export declare function usePaywallUser(): PaywallUser | null;
+export type PaywallUserState = {
+    status: 'loading';
+    user: null;
+    session: null;
+} | {
+    status: 'guest';
+    user: null;
+    session: null;
+} | {
+    status: 'signed_in';
+    user: PaywallUser | null;
+    session: AuthSession | null;
+};
+export declare function usePaywallUser(): PaywallUserState;
 //# sourceMappingURL=usePaywallUser.d.ts.map

package/dist/hooks/usePaywallUser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePaywallUser.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallUser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAgBnD"}
+{"version":3,"file":"usePaywallUser.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallUser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC9C;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAC7B,CAAC;AAKN,wBAAgB,cAAc,IAAI,gBAAgB,CA8EjD"}

package/dist/hooks/usePaywallVisibility.d.ts

@@ -1,4 +1,4 @@
-import { PaywallUI } from '../../../sdk/src';
+import { PaywallUI } from '@monetize.software/sdk';
 type VisibilityStatus = NonNullable<ReturnType<PaywallUI['getVisibility']>>;
 /**
  * Server-computed visibility-снимок ({@link VisibilityStatus}): попадает ли

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react/jsx-runtime"),l=require("react"),m=require("@monetize.software/sdk"),b=l.createContext(null);b.displayName="PaywallContext";const g=l.createContext(!1);g.displayName="PaywallProviderMarker";function A(e){const n="instance"in e?e.instance:void 0,t="options"in e?e.options:void 0,[r,a]=l.useState(n??null);return l.useEffect(()=>{if(n){a(n);return}if(!t)return;const s=new m.PaywallUI(t);return a(s),()=>{s.destroy(),a(null)}},[n]),o.jsx(g.Provider,{value:!0,children:o.jsx(b.Provider,{value:r,children:e.children})})}function i(){const e=l.useContext(g),n=l.useContext(b);if(!e)throw new Error("[sdk-react] usePaywall() called outside <PaywallProvider>. Wrap your tree with <PaywallProvider options={...}> or pass an externally-created instance via <PaywallProvider instance={paywall}>.");return n}const S={open:!1,view:null,error:null};function T(){const e=i(),n=l.useCallback(r=>e?e.onStateChange(r,{immediate:"none"}):()=>{},[e]),t=l.useCallback(()=>e?e.getState():S,[e]);return l.useSyncExternalStore(n,t,()=>S)}function j(){const e=i(),n=l.useCallback(r=>e?e.on("userChange",()=>r()):()=>{},[e]),t=l.useCallback(()=>e?e.billing.getCachedUser():null,[e]);return l.useSyncExternalStore(n,t,B)}function B(){return null}function V(e,n){const t=i(),r=l.useRef(n);r.current=n,l.useEffect(()=>{if(t)return t.on(e,a=>{r.current(a)})},[t,e])}const k={status:"loading",result:null};function C(e={}){const n=i(),[t,r]=l.useState(k),a=e.skipTrial===!0,s=e.skipVisibility===!0;return l.useEffect(()=>{if(!n){r(k);return}const c=new AbortController;let y=!1;const u=()=>{n.getAccess({skipTrial:a,skipVisibility:s,signal:c.signal}).then(P=>{y||c.signal.aborted||r({status:"ready",result:P})}).catch(()=>{})};u();const d=n.on("userChange",u),w=n.on("purchase_completed",u);return()=>{y=!0,c.abort(),d(),w()}},[n,a,s]),t}function R(){const e=i(),[n,t]=l.useState(()=>({prices:e?.getCachedPrices()??null,loading:!0,error:null}));return l.useEffect(()=>{if(!e){t({prices:null,loading:!0,error:null});return}const r=e.getCachedPrices();t({prices:r,loading:r===null,error:null});const a=new AbortController;let s=!1;(()=>{e.getPrices({signal:a.signal}).then(u=>{s||t({prices:u,loading:!1,error:null})}).catch(u=>{s||a.signal.aborted||t(d=>({prices:d.prices,loading:!1,error:u instanceof Error?u:new Error(String(u))}))})})();const y=e.on("ready",()=>{const u=e.getCachedPrices();u&&t({prices:u,loading:!1,error:null})});return()=>{s=!0,a.abort(),y()}},[e]),n}function O(){const e=i(),[n,t]=l.useState(()=>e?.getTrialStatus()??null),r=l.useCallback(()=>{if(!e){t(null);return}t(e.getTrialStatus())},[e]);return l.useEffect(()=>{if(!e){t(null);return}r();const a=e.on("trial_blocked",r),s=e.on("trial_expired",r);return()=>{a(),s()}},[e,r]),n}function _(){const e=i(),[n,t]=l.useState(()=>e?.getVisibility()??null),r=l.useCallback(()=>{if(!e){t(null);return}t(e.getVisibility())},[e]);return l.useEffect(()=>{if(!e){t(null);return}r();const a=e.on("ready",r),s=e.on("visibility_blocked",r);return()=>{a(),s()}},[e,r]),n}function U(e){const n=i(),t=C(),r=t.status==="ready"&&t.result.access==="blocked",a=e.openOnBlocked===!0&&r;if(l.useEffect(()=>{a&&n&&n.open()},[a,n]),t.status==="loading")return o.jsx(o.Fragment,{children:e.loading??null});if(t.result.access==="granted")return o.jsx(o.Fragment,{children:e.children});const s=e.fallback;return typeof s=="function"?o.jsx(o.Fragment,{children:s({result:t.result,open:()=>n?.open()})}):o.jsx(o.Fragment,{children:s??null})}const v=l.forwardRef(function(n,t){const r=i(),{mode:a="paywall",identity:s,renew:c,skipTrial:y,skipVisibility:u,render:d,onClick:w,disabled:P,...x}=n,p=r!==null,f={identity:s,renew:c,skipTrial:y,skipVisibility:u},h=()=>{if(r)switch(a){case"support":r.openSupport(f);return;case"auth":r.openAuth(f);return;case"anon":r.openAnonGate(f);return;default:r.open(f)}};return d?d({open:h,ready:p}):o.jsx("button",{ref:t,type:"button",disabled:P||!p,"aria-busy":p?void 0:!0,onClick:E=>{h(),w?.(E)},...x})}),F=l.forwardRef(function(n,t){return o.jsx(v,{...n,mode:"support",ref:t})});exports.PaywallButton=v;exports.PaywallGate=U;exports.PaywallProvider=A;exports.PaywallSupportButton=F;exports.usePaywall=i;exports.usePaywallAccess=C;exports.usePaywallEvent=V;exports.usePaywallPrices=R;exports.usePaywallState=T;exports.usePaywallTrial=O;exports.usePaywallUser=j;exports.usePaywallVisibility=_;
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const f=require("react/jsx-runtime"),s=require("react"),B=require("@monetize.software/sdk"),S=s.createContext(null);S.displayName="PaywallContext";const k=s.createContext(!1);k.displayName="PaywallProviderMarker";function _(e){const t="instance"in e?e.instance:void 0,n="options"in e?e.options:void 0,[r,l]=s.useState(t??null);return s.useEffect(()=>{if(t){l(t);return}if(!n)return;const a=new B.PaywallUI(n);return l(a),()=>{a.destroy(),l(null)}},[t]),f.jsx(k.Provider,{value:!0,children:f.jsx(S.Provider,{value:r,children:e.children})})}function y(){const e=s.useContext(k),t=s.useContext(S);if(!e)throw new Error("[sdk-react] usePaywall() called outside <PaywallProvider>. Wrap your tree with <PaywallProvider options={...}> or pass an externally-created instance via <PaywallProvider instance={paywall}>.");return t}const C={open:!1,view:null,error:null,processing:!1};function E(){const e=y(),t=s.useCallback(r=>e?e.onStateChange(r,{immediate:"none"}):()=>{},[e]),n=s.useCallback(()=>e?e.getState():C,[e]);return s.useSyncExternalStore(t,n,()=>C)}const P={status:"loading",user:null,session:null},g={status:"guest",user:null,session:null};function V(){const e=y(),t=s.useRef(P),n=s.useCallback(l=>{if(!e)return()=>{};const a=e.on("userChange",()=>l()),u=e.auth?e.on("authChange",()=>l()):null;return()=>{a(),u?.()}},[e]),r=s.useCallback(()=>{if(!e)return t.current=P,P;const l=e.billing.getCachedUser();if(e.auth){const a=e.auth.getCachedSession();if(!a)return t.current=g,g;const u=t.current;if(u.status==="signed_in"&&u.user===l&&u.session===a)return u;const i={status:"signed_in",user:l,session:a};return t.current=i,i}if(l){const a=t.current;if(a.status==="signed_in"&&a.user===l&&a.session===null)return a;const u={status:"signed_in",user:l,session:null};return t.current=u,u}return t.current=g,g},[e]);return s.useSyncExternalStore(n,r,U)}function U(){return P}function F(e,t){const n=y(),r=s.useRef(t);r.current=t,s.useEffect(()=>{if(n)return n.on(e,l=>{r.current(l)})},[n,e])}const x={status:"loading",result:null};function m(e={}){const t=y(),[n,r]=s.useState(x),l=e.skipTrial===!0,a=e.skipVisibility===!0;return s.useEffect(()=>{if(!t){r(x);return}const u=new AbortController;let i=!1;const o=()=>{t.getAccess({skipTrial:l,skipVisibility:a,signal:u.signal}).then(p=>{i||u.signal.aborted||r({status:"ready",result:p})}).catch(()=>{})};o();const c=t.on("userChange",o),d=t.on("purchase_completed",o);return()=>{i=!0,u.abort(),c(),d()}},[t,l,a]),n}function I(){const e=y(),[t,n]=s.useState(()=>({prices:e?.getCachedPrices()??null,loading:!0,error:null}));return s.useEffect(()=>{if(!e){n({prices:null,loading:!0,error:null});return}const r=e.getCachedPrices();n({prices:r,loading:r===null,error:null});const l=new AbortController;let a=!1;(()=>{e.getPrices({signal:l.signal}).then(o=>{a||n({prices:o,loading:!1,error:null})}).catch(o=>{a||l.signal.aborted||n(c=>({prices:c.prices,loading:!1,error:o instanceof Error?o:new Error(String(o))}))})})();const i=e.on("ready",()=>{const o=e.getCachedPrices();o&&n({prices:o,loading:!1,error:null})});return()=>{a=!0,l.abort(),i()}},[e]),t}function M(e){const t=y(),[n,r]=s.useState(()=>t?t.getOfferForPrice(e):null),l=s.useRef(e);return l.current=e,s.useEffect(()=>{if(!t){r(null);return}let a=!1;const u=()=>{if(a)return;const d=t.getOfferForPrice(l.current);return r(d),d},i=u(),o=t.on("ready",()=>u());let c=null;return i&&i.remainingMs!==null&&(c=setInterval(()=>{const d=u();(!d||d.remainingMs===null||d.remainingMs<=0)&&(c&&clearInterval(c),c=null)},1e3)),()=>{a=!0,o(),c&&clearInterval(c)}},[t,e]),n}function G(){const e=y(),t=s.useCallback(r=>e?e.on("ready",()=>r()):()=>{},[e]),n=s.useCallback(()=>e?e.getCachedOffers():null,[e]);return s.useSyncExternalStore(t,n,N)}function N(){return null}function q(){const e=y(),[t,n]=s.useState(()=>e?.getTrialStatus()??null),r=s.useCallback(()=>{if(!e){n(null);return}n(e.getTrialStatus())},[e]);return s.useEffect(()=>{if(!e){n(null);return}r();const l=e.on("trial_blocked",r),a=e.on("trial_expired",r);return()=>{l(),a()}},[e,r]),t}function D(){const e=y(),[t,n]=s.useState(()=>e?.getVisibility()??null),r=s.useCallback(()=>{if(!e){n(null);return}n(e.getVisibility())},[e]);return s.useEffect(()=>{if(!e){n(null);return}r();const l=e.on("ready",r),a=e.on("visibility_blocked",r);return()=>{l(),a()}},[e,r]),t}function L(e){const t=y(),n=m(),r=n.status==="ready"&&n.result.access==="blocked",l=e.openOnBlocked===!0&&r;if(s.useEffect(()=>{l&&t&&t.open()},[l,t]),n.status==="loading")return f.jsx(f.Fragment,{children:e.loading??null});if(n.result.access==="granted")return f.jsx(f.Fragment,{children:e.children});const a=e.fallback;return typeof a=="function"?f.jsx(f.Fragment,{children:a({result:n.result,open:()=>t?.open()})}):f.jsx(f.Fragment,{children:a??null})}const O=s.forwardRef(function(t,n){const r=y(),l=E(),{mode:a="paywall",priceId:u,identity:i,renew:o,skipTrial:c,skipVisibility:d,render:p,onClick:R,disabled:T,...A}=t,b=r!==null,h=!!u&&l.processing,w={identity:i,renew:o,skipTrial:c,skipVisibility:d},v=()=>{if(r){if(u){r.checkout(u,w);return}switch(a){case"support":r.openSupport(w);return;case"auth":case"signin":r.openSignin(w);return;case"signup":r.openSignup(w);return;default:r.open(w)}}};return p?p({open:v,ready:b,processing:h}):f.jsx("button",{ref:n,type:"button",disabled:T||!b||h,"aria-busy":!b||h?!0:void 0,onClick:j=>{v(),R?.(j)},...A})}),H=s.forwardRef(function(t,n){return f.jsx(O,{...t,mode:"support",ref:n})});exports.PaywallButton=O;exports.PaywallGate=L;exports.PaywallProvider=_;exports.PaywallSupportButton=H;exports.usePaywall=y;exports.usePaywallAccess=m;exports.usePaywallEvent=F;exports.usePaywallOffer=M;exports.usePaywallOffers=G;exports.usePaywallPrices=I;exports.usePaywallState=E;exports.usePaywallTrial=q;exports.usePaywallUser=V;exports.usePaywallVisibility=D;
 //# sourceMappingURL=index.cjs.map