@monetize.software/sdk-react 3.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 monetize.software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @monetize.software/sdk-react
+
+React bindings для [`@monetize.software/sdk`](../sdk) — Provider, хуки и декларативные компоненты для пейвола. Работает с web SDK и extension SDK (любой drop-in-совместимый `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`.
+
+## Установка
+
+```bash
+pnpm add @monetize.software/sdk-react @monetize.software/sdk react
+```
+
+## Quick start
+
+```tsx
+import {
+  PaywallProvider,
+  PaywallGate,
+  PaywallButton,
+  usePaywallUser
+} from '@monetize.software/sdk-react';
+
+function App() {
+  return (
+    <PaywallProvider options={{ paywallId: 'YOUR_ID', auth: true }}>
+      <PaywallGate fallback={<UpgradeCTA />}>
+        <PremiumFeature />
+      </PaywallGate>
+
+      <PaywallButton>Upgrade</PaywallButton>
+    </PaywallProvider>
+  );
+}
+
+function UpgradeCTA() {
+  const user = usePaywallUser();
+  return <p>Привет, {user?.email ?? 'гость'}! Открой полный доступ.</p>;
+}
+```
+
+## Provider
+
+`<PaywallProvider>` принимает один из двух пропсов:
+
+```tsx
+// Вариант 1 — Provider сам создаёт инстанс
+<PaywallProvider options={{ paywallId, apiOrigin, auth: true }}>
+
+// Вариант 2 — готовый инстанс снаружи (extension / shared / тесты)
+import { createPaywallUI } from '@monetize.software/sdk-extension';
+const paywall = createPaywallUI({ paywallId });
+
+<PaywallProvider instance={paywall}>
+```
+
+Если `paywallId` динамически меняется, перемонтируй Provider через `<PaywallProvider key={paywallId} options={...}>` — реактивная пересборка опций намеренно не делается.
+
+## Хуки
+
+| Хук | Возвращает | Когда триггерит rerender |
+|---|---|---|
+| `usePaywall()` | `PaywallUI \| null` | смена инстанса (редко) |
+| `usePaywallState()` | `{ open, view, error }` | любое изменение state-машины |
+| `usePaywallUser()` | `PaywallUser \| null` | event `userChange` |
+| `usePaywallAccess(opts?)` | `{ status, result }` | `userChange` / `purchase_completed` |
+| `usePaywallPrices()` | `{ prices, loading, error }` | bootstrap refresh |
+| `usePaywallTrial()` | `TrialStatus \| null` | `trial_blocked` / `trial_expired` |
+| `usePaywallVisibility()` | `VisibilityStatus \| null` | `ready` / `visibility_blocked` |
+| `usePaywallEvent(event, handler)` | — | подписка с stable-handler-ref |
+
+Все хуки безопасны до mount-а Provider'а (отдают `null` / loading) — можно использовать в SSR без `'use client'`-обёрток на ветке дерева.
+
+## Компоненты
+
+### `<PaywallGate>`
+
+Декларативный гейт: loading → fallback → children.
+
+```tsx
+<PaywallGate
+  loading={<Skeleton />}
+  fallback={({ open }) => <button onClick={open}>Upgrade</button>}
+  openOnBlocked={false}  // если true — автоматом дёргает paywall.open()
+>
+  <PremiumFeature />
+</PaywallGate>
+```
+
+### `<PaywallButton>` / `<PaywallSupportButton>`
+
+Сахар над `paywall.open()`. По умолчанию рендерится как нативный `<button>` со всеми твоими `className`/`disabled`/`aria-*`. Для кастомного элемента — render-prop:
+
+```tsx
+<PaywallButton render={({ open, ready }) => (
+  <MyButton onClick={open} disabled={!ready}>Upgrade</MyButton>
+)} />
+```
+
+`mode` переключает между `open()` / `openSupport()` / `openAuth()` / `openAnonGate()`:
+
+```tsx
+<PaywallButton mode="support">Need help?</PaywallButton>
+<PaywallButton mode="auth">Sign in</PaywallButton>
+```
+
+## SSR / Next.js
+
+```tsx
+'use client';  // на Provider, не на дерево потомков
+
+import { PaywallProvider } from '@monetize.software/sdk-react';
+
+export function PaywallProviders({ children }) {
+  return (
+    <PaywallProvider options={{ paywallId: process.env.NEXT_PUBLIC_PAYWALL_ID! }}>
+      {children}
+    </PaywallProvider>
+  );
+}
+```
+
+Хуки можно вызывать из server components только при типизированных-null-сценариях (всё равно вернётся `null`/`loading`). Рекомендация — выносить хук-логику в client component.
+
+## Защита от изменений в SDK
+
+`pnpm typecheck` проверяет [`src/contract.ts`](src/contract.ts) — там перечислены все точки опоры на public API SDK (методы PaywallUI, поля snapshot'ов, имена событий). Любое разъезжание в `../sdk` ловится здесь раньше, чем в проде.
+
+После изменений в SDK обнови dist для типов:
+
+```bash
+cd ../sdk && pnpm build
+cd ../sdk-react && pnpm typecheck
+```
+
+## Разработка
+
+```bash
+pnpm install
+pnpm dev          # → http://localhost:5080/demo/
+pnpm typecheck    # TS-валидация + контракт
+pnpm test         # vitest + @testing-library/react
+pnpm test:e2e     # playwright против демо
+pnpm build        # ESM + CJS + d.ts → dist/
+```
+
+## API reference
+
+Полные JSDoc-комментарии на каждый публичный экспорт смотри в исходниках:
+
+- [`src/PaywallProvider.tsx`](src/PaywallProvider.tsx) — Provider, lifecycle
+- [`src/hooks/`](src/hooks/) — все хуки
+- [`src/components/`](src/components/) — декларативные компоненты
+- [`src/contract.ts`](src/contract.ts) — точки опоры на SDK

package/dist/PaywallProvider.d.ts

@@ -0,0 +1,58 @@
+import { ReactNode } from 'react';
+import { PaywallUI, PaywallUIOptions } from '../../sdk/src';
+/**
+ * Два взаимоисключающих режима использования:
+ *
+ *  - `options` — Provider сам конструирует `PaywallUI` в useEffect и
+ *     прибирает в cleanup. Самый частый кейс — обычный сайт.
+ *  - `instance` — хост создаёт PaywallUI сам и передаёт готовым. Нужно для
+ *     extension'ов (`@monetize.software/sdk-extension` поставляет structurally
+ *     compatible PaywallUI с RemoteBillingClient), для shared-инстанса между
+ *     несколькими React-деревьями и для тестов.
+ *
+ * Discriminated union на уровне типов — TS не даст передать оба сразу.
+ */
+export type PaywallProviderProps = {
+    options: PaywallUIOptions;
+    instance?: never;
+    children: ReactNode;
+} | {
+    instance: PaywallUI;
+    options?: never;
+    children: ReactNode;
+};
+/**
+ * Корневой Provider для всех React-биндингов SDK.
+ *
+ * ```tsx
+ * // вариант 1: Provider сам создаёт инстанс
+ * <PaywallProvider options={{ paywallId: '...', auth: true }}>
+ *   <App />
+ * </PaywallProvider>
+ *
+ * // вариант 2: готовый инстанс снаружи (extension / shared)
+ * const paywall = createPaywallUI({ paywallId: '...' });
+ * <PaywallProvider instance={paywall}>
+ *   <App />
+ * </PaywallProvider>
+ * ```
+ *
+ * SSR: инстанс создаётся в useEffect, на сервере context value=null. Все
+ * хуки делают graceful fallback (`null` / `{ status: 'loading' }`), так что
+ * Provider можно безопасно рендерить в Next.js / Remix без `'use client'`-
+ * ограничений на дерево потомков.
+ *
+ * StrictMode: cleanup-эффект зовёт `destroy()`, чтобы dev double-mount не
+ * оставлял утечек listener'ов и подписок. Микротик-эффекты PaywallUI-
+ * конструктора (`autoDetectReturn`) на первом инстансе становятся no-op
+ * после destroy.
+ *
+ * Смена `options` между рендерами: не реактивна — Provider создаёт инстанс
+ * один раз. Если хосту реально нужно пересоздать (поменялся `paywallId`),
+ * следует менять `key` у Provider'а — это идиоматичный React-способ форсить
+ * пересоздание. Делать «умное» сравнение опций мы намеренно не пытаемся:
+ * структурный equality глубоких options всегда ломается на функциях-колбеках
+ * и live-обновлениях storage'а.
+ */
+export declare function PaywallProvider(props: PaywallProviderProps): JSX.Element;
+//# sourceMappingURL=PaywallProvider.d.ts.map

package/dist/PaywallProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaywallProvider.d.ts","sourceRoot":"","sources":["../src/PaywallProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;CACrB,GACD;IACE,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,GAAG,CAAC,OAAO,CAgDxE"}

package/dist/components/PaywallButton.d.ts

@@ -0,0 +1,61 @@
+import { ButtonHTMLAttributes, ReactElement, ReactNode } from 'react';
+import { OpenOptions } from '../../../sdk/src';
+/**
+ * Параметры открытия пейвола, проксируются в `paywall.open(opts)`.
+ * Любые поля {@link OpenOptions} применимы: `identity`, `renew`, `skipTrial`,
+ * `skipVisibility`.
+ */
+type OpenProps = OpenOptions;
+interface CommonProps extends OpenProps {
+    /** Что открывать: layout (default), support, auth-gate, anon-gate. */
+    mode?: 'paywall' | 'support' | 'auth' | 'anon';
+    /** Render-prop для полного контроля над элементом-триггером. Когда задан,
+     *  все обычные `<button>`-пропсы (children, type, и т.д.) игнорируются. */
+    render?: (args: PaywallButtonRenderArgs) => ReactElement;
+}
+export interface PaywallButtonRenderArgs {
+    /** Открыть пейвол согласно `mode` + переданным opts. */
+    open: () => void;
+    /** Готов ли инстанс PaywallUI. До mount-а Provider'а / на SSR — `false`. */
+    ready: boolean;
+}
+/**
+ * Props собственно `<button>`-рендера. Любые HTML-атрибуты — `disabled`,
+ * `className`, `aria-label`, `type`, и т.д. — пробрасываются на нативный
+ * элемент. `onClick` объединяется с нашим open()-хендлером (мы вызываем
+ * наш первым, потом ваш — чтобы хост мог prevent'ить через event.preventDefault).
+ */
+type ButtonRenderProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof OpenProps | 'children'> & {
+    children?: ReactNode;
+};
+export type PaywallButtonProps = CommonProps & ButtonRenderProps;
+/**
+ * Сахар над `usePaywall().open()`. Кнопка по умолчанию рендерится как
+ * нативный `<button>` со всеми твоими className/style/disabled, но при нужде
+ * можно передать `render` для произвольного элемента (Radix-style asChild
+ * паттерн через render-prop).
+ *
+ * ```tsx
+ * // обычный кейс
+ * <PaywallButton className="btn-primary" renew>
+ *   Renew subscription
+ * </PaywallButton>
+ *
+ * // custom-элемент
+ * <PaywallButton render={({ open, ready }) => (
+ *   <MyFancyButton onClick={open} disabled={!ready}>Upgrade</MyFancyButton>
+ * )} />
+ *
+ * // саппорт-форма вместо тарифов
+ * <PaywallButton mode="support">Need help?</PaywallButton>
+ * ```
+ *
+ * До mount-а Provider'а или на SSR кнопка рендерится с `disabled=true`
+ * (через CSS-pseudo `[aria-busy]` хост может стилизовать loading-state) —
+ * клик в этот момент no-op, потому что инстанса PaywallUI ещё нет.
+ */
+export declare const PaywallButton: import('react').ForwardRefExoticComponent<CommonProps & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | keyof OpenOptions> & {
+    children?: ReactNode;
+} & import('react').RefAttributes<HTMLButtonElement>>;
+export {};
+//# sourceMappingURL=PaywallButton.d.ts.map

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

@@ -0,0 +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"}

package/dist/components/PaywallGate.d.ts

@@ -0,0 +1,61 @@
+import { ReactNode } from 'react';
+import { PaywallAccessResult } from '../../../sdk/src';
+export interface PaywallGateProps {
+    /** Что показать, пока `getAccess()` не вернул ответ (initial fetch / Provider mount). */
+    loading?: ReactNode;
+    /**
+     * Fallback для `blocked` ответа — обычно CTA «Upgrade». Принимает либо
+     * статичный ReactNode, либо render-функцию, получающую callback
+     * `open()` — удобно, чтобы кастомная кнопка сама дёргала модалку:
+     *
+     * ```tsx
+     * fallback={({ open }) => <MyCTA onClick={open}>Upgrade</MyCTA>}
+     * ```
+     *
+     * Если не передан — компонент рендерит `null` для blocked (host
+     * полагается на `openOnBlocked` или ловит open() сам через `usePaywall`).
+     */
+    fallback?: ReactNode | ((args: BlockedRenderArgs) => ReactNode);
+    /**
+     * Автоматически дёргать `paywall.open()` сразу как только access перешёл в
+     * blocked. Удобно для feature-разделителей вида «нажми и попадёшь на
+     * paywall»: компонент сам открывает модалку, не нужно писать onClick.
+     *
+     * По умолчанию `false` — большинство хостов хотят сначала показать
+     * объясняющий CTA, а модалку открывать по клику. Включать осознанно.
+     */
+    openOnBlocked?: boolean;
+    /** Премиум-контент. Рендерится только когда access=granted. */
+    children: ReactNode;
+}
+export interface BlockedRenderArgs {
+    result: Extract<PaywallAccessResult, {
+        access: 'blocked';
+    }>;
+    open: () => void;
+}
+/**
+ * Декларативная обёртка над {@link usePaywallAccess} + {@link usePaywall}.open().
+ *
+ * Три состояния:
+ *  - `loading` (первый fetch / Provider не готов) — рендерим `props.loading`;
+ *  - `granted` (есть подписка / visibility / trial) — рендерим `children`;
+ *  - `blocked` — рендерим `fallback` (если задан) и опционально дёргаем
+ *    `paywall.open()` при `openOnBlocked={true}`.
+ *
+ * ```tsx
+ * <PaywallGate
+ *   loading={<Skeleton />}
+ *   fallback={({ open }) => <button onClick={open}>Upgrade</button>}
+ * >
+ *   <PremiumFeature />
+ * </PaywallGate>
+ * ```
+ *
+ * Для нестандартных сценариев (показать "Try free trial" вместо upgrade,
+ * комбинировать с собственным auth-flow'ом) использовать
+ * {@link usePaywallAccess} напрямую — gate решает 80% кейсов, не пытаясь
+ * стать конфигурируемым на каждый чих.
+ */
+export declare function PaywallGate(props: PaywallGateProps): JSX.Element | null;
+//# sourceMappingURL=PaywallGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PaywallGate.d.ts","sourceRoot":"","sources":["../../src/components/PaywallGate.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAIlE,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,iBAAiB,KAAK,SAAS,CAAC,CAAC;IAChE;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC,mBAAmB,EAAE;QAAE,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAC5D,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,GAAG,CAAC,OAAO,GAAG,IAAI,CAoCvE"}

package/dist/components/PaywallSupportButton.d.ts

@@ -0,0 +1,13 @@
+import { PaywallButtonProps } from './PaywallButton';
+export type PaywallSupportButtonProps = Omit<PaywallButtonProps, 'mode'>;
+/**
+ * Сахар над `<PaywallButton mode="support">`. Самостоятельная компонента, а
+ * не пресет prop'а, для discoverability — название говорит за себя, и в
+ * больших layout-ах легче видеть, где саппорт, а где основной upgrade-CTA.
+ *
+ * ```tsx
+ * <PaywallSupportButton className="link">Help</PaywallSupportButton>
+ * ```
+ */
+export declare const PaywallSupportButton: import('react').ForwardRefExoticComponent<PaywallSupportButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
+//# sourceMappingURL=PaywallSupportButton.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PaywallSupportButton.d.ts","sourceRoot":"","sources":["../../src/components/PaywallSupportButton.tsx"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,yHAK/B,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+import { PaywallUI } from '../../sdk/src';
+/**
+ * Внутренний React Context, в который PaywallProvider кладёт PaywallUI-инстанс.
+ *
+ * value === null до того, как Provider успел смонтировать инстанс (SSR,
+ * первый render до useEffect, дев double-mount в StrictMode после cleanup).
+ * Хуки должны корректно обрабатывать null — отдавать loading/null/no-op,
+ * а не падать.
+ *
+ * defaultValue intentionally `null`, а не `undefined` — это позволяет
+ * usePaywall() различать «Provider не оборачивает дерево» (undefined-симуляция
+ * через sentinel-объект ниже не нужна, мы это ловим иначе) и «Provider есть,
+ * но инстанс ещё не создан» (null).
+ */
+export declare const PaywallContext: import('react').Context<PaywallUI>;
+/**
+ * Sentinel для отслеживания: «компонент вообще находится внутри Provider'а?».
+ *
+ * React Context отдаёт defaultValue, когда `<Provider>` не оборачивает дерево.
+ * Если defaultValue=null, а Provider тоже легально кладёт null (на SSR /
+ * до mount-а) — мы не различаем эти два случая. Поэтому Provider всегда
+ * оборачивает второй Context с маркером HAS_PROVIDER=true, который usePaywall
+ * проверяет первым.
+ */
+export declare const PaywallProviderMarker: import('react').Context<boolean>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,oCAAwC,CAAC;AAGpE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,kCAAgC,CAAC"}

package/dist/contract.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type-level контракт между sdk-react и @monetize.software/sdk.
+ *
+ * Этот файл компилируется в TS-сборке (`pnpm typecheck`), но не экспортируется
+ * наружу — это «assertion'ы», а не runtime-код. Каждая проверка фиксирует
+ * конкретное ожидание относительно публичной поверхности SDK, на которое
+ * полагаются Provider / hooks / components.
+ *
+ * Если в SDK кто-то:
+ *   - переименует/удалит публичный метод PaywallUI,
+ *   - поменяет сигнатуру конструктора `new PaywallUI(opts)`,
+ *   - выкинет поле из `PaywallStateSnapshot` / `PaywallAccessResult`,
+ *   - изменит payload-тип события (например, `purchase_completed`),
+ *
+ * — `tsc --noEmit` в sdk-react падает на этом файле раньше, чем кто-то
+ * заметит расхождение в проде. Это и есть «контракт»: эксплицитно
+ * перечисленные точки опоры.
+ *
+ * Дисциплина: при добавлении нового хука/компонента, который тянет что-то
+ * новое из SDK, добавлять проверку сюда. Контракт должен быть проверяем
+ * сам по себе, а не косвенно через успешный typecheck бизнес-кода (бизнес-
+ * код может незаметно переехать на другую API-точку, и контракт по
+ * фактическому использованию потеряет смысл).
+ *
+ * Тип-имена с префиксом `_` намеренно — сигнализирует, что это assertion'ы
+ * для компилятора, а не общедоступные алиасы.
+ */
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/hooks/usePaywall.d.ts

@@ -0,0 +1,23 @@
+import { PaywallUI } from '../../../sdk/src';
+/**
+ * Достаёт PaywallUI-инстанс из ближайшего {@link PaywallProvider}.
+ *
+ * Бросает ошибку, если вызван вне Provider'а — это явный программный баг,
+ * не runtime-флоу. На SSR / до useEffect Provider'а возвращает `null`
+ * (Provider есть, но инстанс ещё не смонтирован).
+ *
+ * Подавляющему большинству пейволов от хоста нужны `paywall.open()`,
+ * `paywall.openSupport()`, подписки на события — для всего этого
+ * usePaywall() самый прямой путь:
+ *
+ * ```tsx
+ * const paywall = usePaywall();
+ * <button onClick={() => paywall?.open()}>Upgrade</button>
+ * ```
+ *
+ * Для типичных кейсов (gating, state-driven UI) обычно удобнее
+ * специализированные хуки: {@link usePaywallState}, {@link usePaywallAccess},
+ * {@link usePaywallUser}.
+ */
+export declare function usePaywall(): PaywallUI | null;
+//# sourceMappingURL=usePaywall.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePaywall.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywall.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,IAAI,SAAS,GAAG,IAAI,CAa7C"}

package/dist/hooks/usePaywallAccess.d.ts

@@ -0,0 +1,47 @@
+import { GetAccessOptions, PaywallAccessResult } from '../../../sdk/src';
+/**
+ * `loading` — первый fetch ещё в полёте (или Provider не готов).
+ * `ready` — есть свежий ответ; `result` гарантированно non-null.
+ *
+ * Сделано discriminated union'ом, чтобы хост мог сужать тип одним if-ом:
+ *
+ *   `if (access.status === 'ready') access.result.access === 'granted'`
+ */
+export type PaywallAccessState = {
+    status: 'loading';
+    result: null;
+} | {
+    status: 'ready';
+    result: PaywallAccessResult;
+};
+/**
+ * Главный хук для гейтинга фич: «нужно ли блокировать фичу для этого юзера?».
+ *
+ * Под капотом — `paywall.getAccess(opts)` без side-effect'ов (модалка не
+ * монтируется, trial-storage не двигается). На каждый `userChange` событие
+ * автоматически рефетчится — после успешной покупки `has_subscription`
+ * сработает мгновенно, и хост перерендерит UI без feature-lock'а.
+ *
+ * Bootstrap кешируется в BillingClient, так что usePaywallAccess можно дёргать
+ * в любом компоненте дерева — сетевой запрос будет ровно один (или ни одного,
+ * если кеш свежий).
+ *
+ * ```tsx
+ * const access = usePaywallAccess();
+ * const paywall = usePaywall();
+ *
+ * if (access.status === 'loading') return <Skeleton />;
+ * if (access.result.access === 'blocked') {
+ *   return <button onClick={() => paywall?.open()}>Upgrade</button>;
+ * }
+ * return <PremiumFeature />;
+ * ```
+ *
+ * Опции `opts` десериализуются по `skipTrial`/`skipVisibility` — стабильность
+ * ссылки `opts` не требуется, эффект перезапустится только при реальном
+ * изменении этих флагов. `signal` мы дропаем из deps (на каждый рендер у него
+ * новый ref) — отмена inflight-запроса делается локально через AbortController
+ * в cleanup-эффекте.
+ */
+export declare function usePaywallAccess(opts?: GetAccessOptions): PaywallAccessState;
+//# sourceMappingURL=usePaywallAccess.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePaywallAccess.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallAccess.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CAyDhF"}

package/dist/hooks/usePaywallEvent.d.ts

@@ -0,0 +1,27 @@
+import { PaywallEvent, PaywallEventHandler } from '../../../sdk/src';
+/**
+ * Декларативная подписка на событие PaywallUI. Обёртка над `paywall.on(event, cb)`
+ * с двумя важными отличиями от ручного useEffect:
+ *
+ * 1. handler не нужно мемоизировать через `useCallback` — внутри храним
+ *    последнюю версию в `useRef`, само subscription пересоздаётся только
+ *    при смене `event` или инстанса paywall'а. Это убирает класс багов с
+ *    «забыл useCallback → подписка отписывается-переподписывается на каждый
+ *    рендер → события теряются».
+ *
+ * 2. Корректно обрабатывает `paywall === null` (SSR / до Provider mount-а):
+ *    подписка просто не создаётся, ждёт пока инстанс появится.
+ *
+ * ```tsx
+ * usePaywallEvent('purchase_completed', (payload) => {
+ *   toast.success(`Покупка ${payload.priceId} прошла`);
+ *   queryClient.invalidateQueries(['user']);
+ * });
+ * ```
+ *
+ * Для self-cleaning логики (host эмит'а аналитики, инвалидаций кешей, гидрации
+ * локального стейта) это самый прямой паттерн — компонент гарантированно
+ * отпишется при unmount'е, и не нужно держать unsub-ref'ы вручную.
+ */
+export declare function usePaywallEvent<E extends PaywallEvent>(event: E, handler: PaywallEventHandler<E>): void;
+//# sourceMappingURL=usePaywallEvent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePaywallEvent.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallEvent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAUhF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI,CAkBN"}

package/dist/hooks/usePaywallPrices.d.ts

@@ -0,0 +1,38 @@
+import { PaywallPrice } from '../../../sdk/src';
+/**
+ * `prices` — кешированный snapshot bootstrap.prices (`null` до первого fetch'а
+ * или когда инстанс ещё не готов).
+ * `loading` — true пока первый запрос в полёте, после первого ответа всегда false.
+ * `error` — последняя ошибка fetch'а (`null` если успешный или ещё не падал).
+ *
+ * Намеренно нет дискриминирующего поля типа `status: 'loading'|'ready'|'error'`
+ * как в `usePaywallAccess`, потому что для прайсингов хосту обычно нужны три
+ * независимые величины одновременно (показать предыдущий список + skeleton +
+ * сообщение об ошибке поверх) — discriminated union тут только усложняет.
+ */
+export interface PaywallPricesState {
+    prices: PaywallPrice[] | null;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Загружает и подписывается на цены пейвола. Подходит для отдельной
+ * прайсинг-страницы / pricing-карточек, где host хочет показать те же цены,
+ * что и в модалке, без открытия paywall'а.
+ *
+ * Реализация:
+ *  - initial sync read через `getCachedPrices()` (если bootstrap уже в кеше
+ *    BillingClient'а — например, после `paywall.preload()` или предыдущего
+ *    open'а — цены доступны мгновенно);
+ *  - `useEffect` дёргает `getPrices()` для гарантированной загрузки;
+ *  - subscription на `ready` event — рефетч bootstrap'а на новом open()
+ *    может принести обновлённые цены, мы обновляем snapshot.
+ *
+ * ```tsx
+ * const { prices, loading } = usePaywallPrices();
+ * if (loading && !prices) return <Skeleton />;
+ * return prices?.map((p) => <PriceCard key={p.id} price={p} />);
+ * ```
+ */
+export declare function usePaywallPrices(): PaywallPricesState;
+//# sourceMappingURL=usePaywallPrices.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePaywallPrices.d.ts","sourceRoot":"","sources":["../../src/hooks/usePaywallPrices.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,CA0DrD"}

package/dist/hooks/usePaywallState.d.ts

@@ -0,0 +1,23 @@
+import { PaywallStateSnapshot } from '../../../sdk/src';
+/**
+ * Подписка на состояние модалки пейвола: открыта/закрыта, текущий view,
+ * последняя ошибка.
+ *
+ * Реализована поверх `paywall.onStateChange` + `paywall.getState` через
+ * `useSyncExternalStore` — это даёт корректную concurrent-rendering семантику
+ * (никаких tearing'ов, snapshot стабилен в рамках одного React-commit'а) и
+ * минимум re-render'ов (snapshot равенство по `Object.is`).
+ *
+ * До mount-а Provider'а или на сервере возвращает `{ open: false, view: null,
+ * error: null }` — это та же форма, что PaywallUI кладёт во внутренний
+ * CLOSED_STATE, так что хосту не нужно отдельно проверять «инстанс готов».
+ *
+ * ```tsx
+ * const { open, view } = usePaywallState();
+ * useEffect(() => {
+ *   if (open) analytics.track('paywall_seen');
+ * }, [open]);
+ * ```
+ */
+export declare function usePaywallState(): PaywallStateSnapshot;
+//# sourceMappingURL=usePaywallState.d.ts.map

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

@@ -0,0 +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"}