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

package/README.md

@@ -1,9 +1,15 @@
 # @monetize.software/sdk
 
-SDK 3.0 — bundled billing client and paywall render engine. Embeds into Chrome
-extensions and websites via npm / CDN, with no iframe and no remote code.
+SDK 3.0 — bundled billing client and paywall render engine. Renders the paywall
+in a Shadow DOM modal on your page, with no iframe.
 
-Status: **alpha, WIP**. See [TODO.md](../TODO.md).
+- **Websites:** install via npm and bundle, or load from a CDN (`esm.sh`/`unpkg`/`jsDelivr`).
+- **Chrome extensions:** use the dedicated [`@monetize.software/sdk-extension`](https://www.npmjs.com/package/@monetize.software/sdk-extension)
+  package and bundle as an npm dependency — Chrome Web Store MV3 policy forbids
+  remote code execution, so CDN loading is **not** allowed.
+
+Status: **alpha**. API surface is stabilizing but may still shift between alpha
+releases; see [CHANGELOG.md](CHANGELOG.md).
 
 ## Three entrypoints
 
@@ -25,6 +31,7 @@ import { PaywallUI } from '@monetize.software/sdk';
 
 const paywall = new PaywallUI({
   paywallId: 'pw_abc123',
+  apiOrigin: 'https://your-paywall-domain.com',  // required: your custom_domain
   identity: { email: user.email, userId: user.id }
 });
 
@@ -35,6 +42,10 @@ paywall.on('checkout_started', ({ url }) => {
 document.getElementById('upgrade').onclick = () => paywall.open();
 ```
 
+`apiOrigin` must match the `custom_domain` configured for your paywall in the
+platform. The SDK validates it against the bootstrap response and throws
+`invalid_config` on mismatch.
+
 ## Scripts
 
 ```bash
@@ -53,8 +64,8 @@ pnpm test
 - **Tailwind v4**, compiled into a CSS string and injected into the shadow root.
 - **Server-driven layout** — JSON schema of blocks (`heading`, `price_grid`, `cta_button`, ...).
   SDK knows how to render blocks; the server controls order, copy, and visibility.
-- **Server-driven checkout** — SDK is provider-agnostic (Stripe/Paddle/Chargebee),
-  it just opens the `checkout_url` returned by the server.
+- **Server-driven checkout** — SDK is provider-agnostic (Stripe, Paddle, Freemius,
+  Chargebee, Overpay), it just opens the `checkout_url` returned by the server.
 
 ## Metered AI proxy (`ApiGatewayClient`)
 
@@ -65,8 +76,8 @@ this proxy and maintains local balance state.
 ```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 auth = new AuthClient({ paywallId: 'pw_abc', apiOrigin: 'https://your-paywall-domain.com' });
+const billing = new BillingClient({ paywallId: 'pw_abc', apiOrigin: 'https://your-paywall-domain.com', auth });
 const gateway = billing.createApiGatewayClient();
 
 billing.onBalanceChange((balances) => {
@@ -98,9 +109,19 @@ try {
   `.body.getReader()`, or async-iter — anything that works on a `fetch` Response.
 - On 402, `QuotaExceededError` is thrown with `balances` / `queryType` / `currentBalance`.
 
-## Not in this version (alpha)
-
-- Auth layer (Google / Apple / Email) — coming after the hybrid beta.
-- Timer-based trials, A/B variants, localization.
-- Framework adapters (`@monetize/react`).
-- Tests.
+## What's included
+
+- **Auth layer** — Email/password, OAuth (Google, Apple, Facebook, GitHub),
+  password reset and OTP confirmation flows. Lazy-loaded chunk: pay for it only
+  if you instantiate `AuthClient` or open the SDK with `auth: true`.
+- **Trials** — time-based trial counter (LocalTrialStore on web,
+  RemoteTrialStore in the extension offscreen) with server-side validation.
+- **Localization** — 27 bundled locales, lazy-loaded per active language; falls
+  back to canonical English baked into block strings.
+- **Server-driven layout** — blocks, ordering, copy and visibility are owned by
+  the platform; the SDK renders. Live preview API for the admin editor.
+- **React bindings** — see [`@monetize.software/sdk-react`](https://www.npmjs.com/package/@monetize.software/sdk-react)
+  for `<PaywallProvider>`, hooks and declarative gate/button components.
+- **Chrome extensions** — see [`@monetize.software/sdk-extension`](https://www.npmjs.com/package/@monetize.software/sdk-extension)
+  for the offscreen-backed integration (single source of truth across tabs,
+  popups, side panels).