@monetize.software/sdk-react

React bindings для @monetize.software/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) — если в основном SDK поедет публичная поверхность, сборка sdk-react падает на этапе tsc.

Установка

pnpm add @monetize.software/sdk-react @monetize.software/sdk react

Quick start

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> принимает один из двух пропсов:

// Вариант 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.

<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:

<PaywallButton render={({ open, ready }) => (
  <MyButton onClick={open} disabled={!ready}>Upgrade</MyButton>
)} />

mode переключает между open() / openSupport() / openAuth() / openAnonGate():

<PaywallButton mode="support">Need help?</PaywallButton>
<PaywallButton mode="auth">Sign in</PaywallButton>

SSR / Next.js

'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 — там перечислены все точки опоры на public API SDK (методы PaywallUI, поля snapshot'ов, имена событий). Любое разъезжание в ../sdk ловится здесь раньше, чем в проде.

После изменений в SDK обнови dist для типов:

cd ../sdk && pnpm build
cd ../sdk-react && pnpm typecheck

Разработка

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 — Provider, lifecycle
src/hooks/ — все хуки
src/components/ — декларативные компоненты
src/contract.ts — точки опоры на SDK