@monetize.software/sdk-react 3.0.0-alpha.4 → 3.0.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +65 -38
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,13 +1,17 @@
1
1
  # @monetize.software/sdk-react
2
2
 
3
- React bindings для [`@monetize.software/sdk`](../sdk) — Provider, хуки и декларативные компоненты для пейвола. Работает с web SDK и extension SDK (любой drop-in-совместимый `PaywallUI`).
3
+ React bindings for [`@monetize.software/sdk`](../sdk) — Provider, hooks and
4
+ declarative paywall components. Works with the web SDK and the extension SDK
5
+ (any drop-in-compatible `PaywallUI`).
4
6
 
5
- - **Bundle**: < 2 KB gzip (только bindings, никакого UI — он внутри SDK).
6
- - **React**: >= 18, использует `useSyncExternalStore` для concurrent-safe чтения снимков.
7
- - **SSR**: безопасно. На сервере хуки отдают `null` / `{ status: 'loading' }`, инстанс PaywallUI создаётся только на клиенте.
8
- - **TypeScript**: полный тип-уровень контракт ([`src/contract.ts`](src/contract.ts)) — если в основном SDK поедет публичная поверхность, сборка sdk-react падает на этапе `tsc`.
7
+ - **Bundle**: < 2 KB gzip (bindings only — the UI lives inside the SDK).
8
+ - **React**: >= 18, uses `useSyncExternalStore` for concurrent-safe snapshot reads.
9
+ - **SSR**: safe out of the box. On the server, hooks return `null` /
10
+ `{ status: 'loading' }`; the `PaywallUI` instance is created only on the client.
11
+ - **TypeScript**: full type-level contract ([`src/contract.ts`](src/contract.ts)) —
12
+ if the public surface of the SDK shifts, the `sdk-react` build fails at `tsc`.
9
13
 
10
- ## Установка
14
+ ## Installation
11
15
 
12
16
  ```bash
13
17
  pnpm add @monetize.software/sdk-react @monetize.software/sdk react
@@ -25,7 +29,13 @@ import {
25
29
 
26
30
  function App() {
27
31
  return (
28
- <PaywallProvider options={{ paywallId: 'YOUR_ID', auth: true }}>
32
+ <PaywallProvider
33
+ options={{
34
+ paywallId: 'YOUR_ID',
35
+ apiOrigin: 'https://your-paywall-domain.com',
36
+ auth: true
37
+ }}
38
+ >
29
39
  <PaywallGate fallback={<UpgradeCTA />}>
30
40
  <PremiumFeature />
31
41
  </PaywallGate>
@@ -37,53 +47,59 @@ function App() {
37
47
 
38
48
  function UpgradeCTA() {
39
49
  const user = usePaywallUser();
40
- return <p>Привет, {user?.email ?? 'гость'}! Открой полный доступ.</p>;
50
+ return <p>Hi, {user?.email ?? 'guest'}! Unlock full access.</p>;
41
51
  }
42
52
  ```
43
53
 
54
+ `apiOrigin` must match the `custom_domain` configured for your paywall in the
55
+ platform.
56
+
44
57
  ## Provider
45
58
 
46
- `<PaywallProvider>` принимает один из двух пропсов:
59
+ `<PaywallProvider>` accepts one of two props:
47
60
 
48
61
  ```tsx
49
- // Вариант 1 — Provider сам создаёт инстанс
62
+ // Option 1 — Provider creates the instance itself
50
63
  <PaywallProvider options={{ paywallId, apiOrigin, auth: true }}>
51
64
 
52
- // Вариант 2 — готовый инстанс снаружи (extension / shared / тесты)
65
+ // Option 2 — host supplies a ready instance (extension / shared singleton / tests)
53
66
  import { createPaywallUI } from '@monetize.software/sdk-extension';
54
- const paywall = createPaywallUI({ paywallId });
67
+ const paywall = createPaywallUI({ paywallId, apiOrigin });
55
68
 
56
69
  <PaywallProvider instance={paywall}>
57
70
  ```
58
71
 
59
- Если `paywallId` динамически меняется, перемонтируй Provider через `<PaywallProvider key={paywallId} options={...}>` — реактивная пересборка опций намеренно не делается.
72
+ If `paywallId` changes dynamically, remount the Provider via
73
+ `<PaywallProvider key={paywallId} options={...}>` — reactive option rebuilds are
74
+ intentionally not performed.
60
75
 
61
- ## Хуки
76
+ ## Hooks
62
77
 
63
- | Хук | Возвращает | Когда триггерит rerender |
78
+ | Hook | Returns | When it triggers a rerender |
64
79
  |---|---|---|
65
- | `usePaywall()` | `PaywallUI \| null` | смена инстанса (редко) |
66
- | `usePaywallState()` | `{ open, view, error }` | любое изменение state-машины |
67
- | `usePaywallUser()` | `PaywallUser \| null` | event `userChange` |
80
+ | `usePaywall()` | `PaywallUI \| null` | instance change (rare) |
81
+ | `usePaywallState()` | `{ open, view, error }` | any state-machine change |
82
+ | `usePaywallUser()` | `PaywallUser \| null` | `userChange` event |
68
83
  | `usePaywallAccess(opts?)` | `{ status, result }` | `userChange` / `purchase_completed` |
69
84
  | `usePaywallPrices()` | `{ prices, loading, error }` | bootstrap refresh |
70
85
  | `usePaywallTrial()` | `TrialStatus \| null` | `trial_blocked` / `trial_expired` |
71
86
  | `usePaywallVisibility()` | `VisibilityStatus \| null` | `ready` / `visibility_blocked` |
72
- | `usePaywallEvent(event, handler)` | — | подписка с stable-handler-ref |
87
+ | `usePaywallEvent(event, handler)` | — | subscribes with a stable handler ref |
73
88
 
74
- Все хуки безопасны до mount-а Provider'а (отдают `null` / loading) — можно использовать в SSR без `'use client'`-обёрток на ветке дерева.
89
+ All hooks are safe before the Provider mounts (they return `null` / loading) —
90
+ you can use them in SSR without `'use client'` wrappers on the consuming subtree.
75
91
 
76
- ## Компоненты
92
+ ## Components
77
93
 
78
94
  ### `<PaywallGate>`
79
95
 
80
- Декларативный гейт: loading → fallback → children.
96
+ Declarative gate: loading → fallback → children.
81
97
 
82
98
  ```tsx
83
99
  <PaywallGate
84
100
  loading={<Skeleton />}
85
101
  fallback={({ open }) => <button onClick={open}>Upgrade</button>}
86
- openOnBlocked={false} // если true — автоматом дёргает paywall.open()
102
+ openOnBlocked={false} // if true — calls paywall.open() automatically
87
103
  >
88
104
  <PremiumFeature />
89
105
  </PaywallGate>
@@ -91,7 +107,9 @@ const paywall = createPaywallUI({ paywallId });
91
107
 
92
108
  ### `<PaywallButton>` / `<PaywallSupportButton>`
93
109
 
94
- Сахар над `paywall.open()`. По умолчанию рендерится как нативный `<button>` со всеми твоими `className`/`disabled`/`aria-*`. Для кастомного элемента — render-prop:
110
+ Sugar over `paywall.open()`. By default renders a native `<button>` with all
111
+ your `className`/`disabled`/`aria-*` props forwarded. For a custom element use
112
+ the render prop:
95
113
 
96
114
  ```tsx
97
115
  <PaywallButton render={({ open, ready }) => (
@@ -99,7 +117,7 @@ const paywall = createPaywallUI({ paywallId });
99
117
  )} />
100
118
  ```
101
119
 
102
- `mode` переключает между `open()` / `openSupport()` / `openAuth()` / `openAnonGate()`:
120
+ `mode` switches between `open()` / `openSupport()` / `openAuth()` / `openAnonGate()`:
103
121
 
104
122
  ```tsx
105
123
  <PaywallButton mode="support">Need help?</PaywallButton>
@@ -109,48 +127,57 @@ const paywall = createPaywallUI({ paywallId });
109
127
  ## SSR / Next.js
110
128
 
111
129
  ```tsx
112
- 'use client'; // на Provider, не на дерево потомков
130
+ 'use client'; // on the Provider, not on the consumer subtree
113
131
 
114
132
  import { PaywallProvider } from '@monetize.software/sdk-react';
115
133
 
116
134
  export function PaywallProviders({ children }) {
117
135
  return (
118
- <PaywallProvider options={{ paywallId: process.env.NEXT_PUBLIC_PAYWALL_ID! }}>
136
+ <PaywallProvider
137
+ options={{
138
+ paywallId: process.env.NEXT_PUBLIC_PAYWALL_ID!,
139
+ apiOrigin: process.env.NEXT_PUBLIC_PAYWALL_ORIGIN!
140
+ }}
141
+ >
119
142
  {children}
120
143
  </PaywallProvider>
121
144
  );
122
145
  }
123
146
  ```
124
147
 
125
- Хуки можно вызывать из server components только при типизированных-null-сценариях (всё равно вернётся `null`/`loading`). Рекомендация — выносить хук-логику в client component.
148
+ Hooks can be called from server components in typed-null scenarios (they'll
149
+ return `null` / loading anyway). The recommendation is to keep hook logic in a
150
+ client component.
126
151
 
127
- ## Защита от изменений в SDK
152
+ ## SDK contract guard
128
153
 
129
- `pnpm typecheck` проверяет [`src/contract.ts`](src/contract.ts) — там перечислены все точки опоры на public API SDK (методы PaywallUI, поля snapshot'ов, имена событий). Любое разъезжание в `../sdk` ловится здесь раньше, чем в проде.
154
+ `pnpm typecheck` validates [`src/contract.ts`](src/contract.ts) — it lists every
155
+ point of contact with the public SDK API (`PaywallUI` methods, snapshot fields,
156
+ event names). Any drift in `../sdk` is caught here before it hits production.
130
157
 
131
- После изменений в SDK обнови dist для типов:
158
+ After SDK changes, refresh the dist for type resolution:
132
159
 
133
160
  ```bash
134
161
  cd ../sdk && pnpm build
135
162
  cd ../sdk-react && pnpm typecheck
136
163
  ```
137
164
 
138
- ## Разработка
165
+ ## Development
139
166
 
140
167
  ```bash
141
168
  pnpm install
142
169
  pnpm dev # → http://localhost:5080/demo/
143
- pnpm typecheck # TS-валидация + контракт
170
+ pnpm typecheck # TS validation + contract guard
144
171
  pnpm test # vitest + @testing-library/react
145
- pnpm test:e2e # playwright против демо
172
+ pnpm test:e2e # playwright against the demo
146
173
  pnpm build # ESM + CJS + d.ts → dist/
147
174
  ```
148
175
 
149
176
  ## API reference
150
177
 
151
- Полные JSDoc-комментарии на каждый публичный экспорт смотри в исходниках:
178
+ Full JSDoc comments on every public export are inline in the sources:
152
179
 
153
180
  - [`src/PaywallProvider.tsx`](src/PaywallProvider.tsx) — Provider, lifecycle
154
- - [`src/hooks/`](src/hooks/) — все хуки
155
- - [`src/components/`](src/components/) — декларативные компоненты
156
- - [`src/contract.ts`](src/contract.ts) — точки опоры на SDK
181
+ - [`src/hooks/`](src/hooks/) — all hooks
182
+ - [`src/components/`](src/components/) — declarative components
183
+ - [`src/contract.ts`](src/contract.ts) — SDK contact points
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@monetize.software/sdk-react",
3
- "version": "3.0.0-alpha.4",
3
+ "version": "3.0.0-alpha.5",
4
4
  "description": "React bindings for @monetize.software/sdk — Provider, hooks and declarative components. Works with the web SDK and the extension SDK (any drop-in compatible PaywallUI).",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -26,7 +26,7 @@
26
26
  },
27
27
  "peerDependencies": {
28
28
  "react": ">=18",
29
- "@monetize.software/sdk": "3.0.0-alpha.6"
29
+ "@monetize.software/sdk": "3.0.0-alpha.7"
30
30
  },
31
31
  "peerDependenciesMeta": {
32
32
  "@monetize.software/sdk": {
@@ -48,7 +48,7 @@
48
48
  "vite": "^6.0.5",
49
49
  "vite-plugin-dts": "^4.3.0",
50
50
  "vitest": "^2.1.8",
51
- "@monetize.software/sdk": "3.0.0-alpha.6"
51
+ "@monetize.software/sdk": "3.0.0-alpha.7"
52
52
  },
53
53
  "scripts": {
54
54
  "dev": "vite",