@monetize.software/sdk 3.0.0-alpha.0 → 3.0.0-alpha.1
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.
- package/README.md +35 -35
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,24 +1,24 @@
|
|
|
1
1
|
# @monetize.software/sdk
|
|
2
2
|
|
|
3
|
-
SDK 3.0 — bundled billing client
|
|
4
|
-
|
|
3
|
+
SDK 3.0 — bundled billing client and paywall render engine. Embeds into Chrome
|
|
4
|
+
extensions and websites via npm / CDN, with no iframe and no remote code.
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
Status: **alpha, WIP**. See [TODO.md](../TODO.md).
|
|
7
7
|
|
|
8
|
-
##
|
|
8
|
+
## Three entrypoints
|
|
9
9
|
|
|
10
10
|
```ts
|
|
11
|
-
// server / headless billing —
|
|
11
|
+
// server / headless billing — API only, no UI
|
|
12
12
|
import { BillingClient } from '@monetize.software/sdk/core';
|
|
13
13
|
|
|
14
|
-
// host
|
|
14
|
+
// host renders its own UI but needs our modal
|
|
15
15
|
import { PaywallUI } from '@monetize.software/sdk/ui';
|
|
16
16
|
|
|
17
|
-
//
|
|
17
|
+
// all in one — auth layer is loaded lazily
|
|
18
18
|
import { PaywallUI } from '@monetize.software/sdk';
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
##
|
|
21
|
+
## Quick start
|
|
22
22
|
|
|
23
23
|
```ts
|
|
24
24
|
import { PaywallUI } from '@monetize.software/sdk';
|
|
@@ -35,32 +35,32 @@ paywall.on('checkout_started', ({ url }) => {
|
|
|
35
35
|
document.getElementById('upgrade').onclick = () => paywall.open();
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
##
|
|
38
|
+
## Scripts
|
|
39
39
|
|
|
40
40
|
```bash
|
|
41
41
|
pnpm install
|
|
42
|
-
pnpm dev #
|
|
43
|
-
pnpm build # ESM + CJS + .d.ts
|
|
42
|
+
pnpm dev # local demo at http://localhost:5060/demo/
|
|
43
|
+
pnpm build # ESM + CJS + .d.ts into dist/
|
|
44
44
|
pnpm typecheck
|
|
45
45
|
pnpm size # bundle-size gate
|
|
46
46
|
pnpm test
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
##
|
|
49
|
+
## Architecture (in brief)
|
|
50
50
|
|
|
51
|
-
- **Preact** (
|
|
52
|
-
- **Shadow DOM** (`{ mode: 'closed' }`) —
|
|
53
|
-
- **Tailwind v4**,
|
|
54
|
-
- **Server-driven layout** — JSON
|
|
55
|
-
SDK
|
|
56
|
-
- **Server-driven checkout** — SDK
|
|
57
|
-
|
|
51
|
+
- **Preact** (not React) — 3KB instead of 45KB. Critical for the bundle budget.
|
|
52
|
+
- **Shadow DOM** (`{ mode: 'closed' }`) — style isolation.
|
|
53
|
+
- **Tailwind v4**, compiled into a CSS string and injected into the shadow root.
|
|
54
|
+
- **Server-driven layout** — JSON schema of blocks (`heading`, `price_grid`, `cta_button`, ...).
|
|
55
|
+
SDK knows how to render blocks; the server controls order, copy, and visibility.
|
|
56
|
+
- **Server-driven checkout** — SDK is provider-agnostic (Stripe/Paddle/Chargebee),
|
|
57
|
+
it just opens the `checkout_url` returned by the server.
|
|
58
58
|
|
|
59
|
-
##
|
|
59
|
+
## Metered AI proxy (`ApiGatewayClient`)
|
|
60
60
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
61
|
+
The platform supports proxying calls to OpenAI/Anthropic/any HTTP API with
|
|
62
|
+
token accounting against `paywall_balances`. The SDK ships a thin client to
|
|
63
|
+
this proxy and maintains local balance state.
|
|
64
64
|
|
|
65
65
|
```ts
|
|
66
66
|
import { BillingClient, AuthClient, QuotaExceededError } from '@monetize.software/sdk/core';
|
|
@@ -70,11 +70,11 @@ const billing = new BillingClient({ paywallId: 'pw_abc', auth });
|
|
|
70
70
|
const gateway = billing.createApiGatewayClient();
|
|
71
71
|
|
|
72
72
|
billing.onBalanceChange((balances) => {
|
|
73
|
-
//
|
|
73
|
+
// Render quota counter in UI
|
|
74
74
|
});
|
|
75
75
|
|
|
76
76
|
try {
|
|
77
|
-
// SSE
|
|
77
|
+
// SSE stream: returns a raw Response, no built-in parser.
|
|
78
78
|
const res = await gateway.call({
|
|
79
79
|
providerId: 'prov_openai',
|
|
80
80
|
path: '',
|
|
@@ -86,21 +86,21 @@ try {
|
|
|
86
86
|
}
|
|
87
87
|
} catch (e) {
|
|
88
88
|
if (e instanceof QuotaExceededError) {
|
|
89
|
-
paywall.open(); // upgrade
|
|
89
|
+
paywall.open(); // upgrade prompt
|
|
90
90
|
} else throw e;
|
|
91
91
|
}
|
|
92
92
|
```
|
|
93
93
|
|
|
94
|
-
- `BillingClient.createApiGatewayClient()`
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- `gateway.call()`
|
|
98
|
-
`.body.getReader()`,
|
|
99
|
-
-
|
|
94
|
+
- `BillingClient.createApiGatewayClient()` wires the Bearer from `AuthClient`,
|
|
95
|
+
optimistically decrements `cachedBalances` on success, and refetches `/balances`
|
|
96
|
+
on 402.
|
|
97
|
+
- `gateway.call()` returns the raw `Response`. Caller decides: `.json()`,
|
|
98
|
+
`.body.getReader()`, or async-iter — anything that works on a `fetch` Response.
|
|
99
|
+
- On 402, `QuotaExceededError` is thrown with `balances` / `queryType` / `currentBalance`.
|
|
100
100
|
|
|
101
|
-
##
|
|
101
|
+
## Not in this version (alpha)
|
|
102
102
|
|
|
103
|
-
- Auth
|
|
104
|
-
-
|
|
103
|
+
- Auth layer (Google / Apple / Email) — coming after the hybrid beta.
|
|
104
|
+
- Timer-based trials, A/B variants, localization.
|
|
105
105
|
- Framework adapters (`@monetize/react`).
|
|
106
106
|
- Tests.
|
package/package.json
CHANGED