@monetize.software/sdk 3.0.0-alpha.0

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,106 @@
+# @monetize.software/sdk
+
+SDK 3.0 — bundled billing client и render engine пейвола. Встраивается в расширения Chrome
+и веб-сайты через npm / CDN, без iframe и без remote code.
+
+Статус: **alpha, WIP**. См. [TODO.md](../TODO.md).
+
+## Три entrypoint'а
+
+```ts
+// server / headless billing — только API, без UI
+import { BillingClient } from '@monetize.software/sdk/core';
+
+// host сам показывает UI, но нужна наша модалка
+import { PaywallUI } from '@monetize.software/sdk/ui';
+
+// все в одном — auth-слой подгружается лениво
+import { PaywallUI } from '@monetize.software/sdk';
+```
+
+## Быстрый старт
+
+```ts
+import { PaywallUI } from '@monetize.software/sdk';
+
+const paywall = new PaywallUI({
+  paywallId: 'pw_abc123',
+  identity: { email: user.email, userId: user.id }
+});
+
+paywall.on('checkout_started', ({ url }) => {
+  window.open(url, '_blank');
+});
+
+document.getElementById('upgrade').onclick = () => paywall.open();
+```
+
+## Скрипты
+
+```bash
+pnpm install
+pnpm dev          # локальная демка на http://localhost:5060/demo/
+pnpm build        # ESM + CJS + .d.ts в dist/
+pnpm typecheck
+pnpm size         # bundle-size gate
+pnpm test
+```
+
+## Архитектура (коротко)
+
+- **Preact** (не React) — 3KB вместо 45KB. Critical для bundle-бюджета.
+- **Shadow DOM** (`{ mode: 'closed' }`) — изоляция стилей.
+- **Tailwind v4**, скомпилированный в CSS-строку и инжектированный в shadow root.
+- **Server-driven layout** — JSON-схема блоков (`heading`, `price_grid`, `cta_button`, ...).
+  SDK умеет рендерить блоки; server управляет порядком, текстами, visibility.
+- **Server-driven checkout** — SDK не знает провайдеров (Stripe/Paddle/Chargebee),
+  просто открывает `checkout_url`, который вернул сервер.
+
+## Метированный AI-прокси (`ApiGatewayClient`)
+
+Платформа поддерживает прокси-вызовы к OpenAI/Anthropic/любому HTTP-API с
+посчётом токенов из `paywall_balances`. SDK даёт тонкий клиент к этому прокси
+и хранит локальное состояние балансов.
+
+```ts
+import { BillingClient, AuthClient, QuotaExceededError } from '@monetize.software/sdk/core';
+
+const auth = new AuthClient({ paywallId: 'pw_abc' });
+const billing = new BillingClient({ paywallId: 'pw_abc', auth });
+const gateway = billing.createApiGatewayClient();
+
+billing.onBalanceChange((balances) => {
+  // Рисуем счётчик квот в UI
+});
+
+try {
+  // SSE-стрим: возвращается голый Response, без своего парсера.
+  const res = await gateway.call({
+    providerId: 'prov_openai',
+    path: '',
+    body: { model: 'gpt-4', stream: true, messages: [...] },
+    signal: controller.signal
+  });
+  for await (const chunk of res.body!) {
+    /* ... */
+  }
+} catch (e) {
+  if (e instanceof QuotaExceededError) {
+    paywall.open(); // upgrade-prompt
+  } else throw e;
+}
+```
+
+- `BillingClient.createApiGatewayClient()` подключает Bearer из `AuthClient`,
+  оптимистично декрементит `cachedBalances` на success, ре-фетчит `/balances`
+  на 402.
+- `gateway.call()` отдаёт сырой `Response`. Caller сам решает: `.json()`,
+  `.body.getReader()`, или async-iter — всё работает из коробки `fetch`.
+- На 402 бросается `QuotaExceededError` с `balances`/`queryType`/`currentBalance`.
+
+## Нет в этой версии (alpha)
+
+- Auth-слой (Google/Apple/Email) — будет после hybrid-бета.
+- Трейлы с таймером, A/B-варианты, локализация.
+- Framework adapters (`@monetize/react`).
+- Tests.