@monetize.software/sdk-extension 0.1.0-alpha.0 → 3.0.0-alpha.2
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 +52 -52
- package/dist/chunks/{chrome-port-BXHR4SOG.js → chrome-port-DPFUj1MP.js} +144 -98
- package/dist/chunks/chrome-port-DPFUj1MP.js.map +1 -0
- package/dist/chunks/{chrome-port-EtYqHf3p.js → chrome-port-MoMohiHB.js} +2 -2
- package/dist/chunks/chrome-port-MoMohiHB.js.map +1 -0
- package/dist/content.cjs +2 -2
- package/dist/content.cjs.map +1 -1
- package/dist/content.js +37 -17
- package/dist/content.js.map +1 -1
- package/dist/offscreen.cjs +1 -1
- package/dist/offscreen.js +1 -1
- package/package.json +1 -1
- package/dist/chunks/chrome-port-BXHR4SOG.js.map +0 -1
- package/dist/chunks/chrome-port-EtYqHf3p.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
# @monetize.software/sdk-extension
|
|
2
2
|
|
|
3
|
-
SDK
|
|
4
|
-
AuthClient
|
|
5
|
-
|
|
3
|
+
SDK for Chrome extensions. A single offscreen document holds the BillingClient,
|
|
4
|
+
AuthClient and EventTracker — the single source of truth for all tabs, popups,
|
|
5
|
+
side panels, and extension pages.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
host
|
|
9
|
-
|
|
7
|
+
The content-script public API is **drop-in compatible** with `@monetize.software/sdk` —
|
|
8
|
+
the host writes `import { PaywallUI } from '@monetize.software/sdk-extension'` and
|
|
9
|
+
gets the same class with the same method set.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Architecture
|
|
12
12
|
|
|
13
13
|
```
|
|
14
14
|
content script (per tab) ──port──▶ service worker ──port──▶ offscreen
|
|
@@ -19,23 +19,23 @@ content script (per tab) ──port──▶ service worker ──port──▶
|
|
|
19
19
|
UserWatcher
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
- **content-script:** UI + RemoteBillingClient (proxy
|
|
23
|
-
- **service worker:**
|
|
24
|
-
|
|
25
|
-
- **offscreen:**
|
|
26
|
-
|
|
22
|
+
- **content-script:** UI + RemoteBillingClient (proxy over a port into offscreen).
|
|
23
|
+
- **service worker:** content↔offscreen router; OAuth flow via `chrome.identity`
|
|
24
|
+
(offscreen can't access it directly).
|
|
25
|
+
- **offscreen:** the real SDK state, survives tab closes, the sole coordination
|
|
26
|
+
point for auth refresh / trial counter / analytics batching.
|
|
27
27
|
|
|
28
|
-
##
|
|
28
|
+
## Status
|
|
29
29
|
|
|
30
|
-
Phase 0 —
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
Phase 0 — skeleton: package.json, vite multi-entry, wire-protocol types,
|
|
31
|
+
stubs for content/offscreen/sw and a demo-extension manifest. Actual routing
|
|
32
|
+
and `RemoteBillingClient` come in the next phases.
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
See TODO in the repo and `src/shared/protocol.ts` for the message contract.
|
|
35
35
|
|
|
36
|
-
##
|
|
36
|
+
## Usage (target shape, when complete)
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
**In the extension:**
|
|
39
39
|
|
|
40
40
|
```ts
|
|
41
41
|
// service-worker.ts
|
|
@@ -50,18 +50,18 @@ startOffscreenServer({ paywallId: '...', apiOrigin: 'https://...' });
|
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
```ts
|
|
53
|
-
// content-script.ts (
|
|
53
|
+
// content-script.ts (in every tab)
|
|
54
54
|
import { PaywallUI } from '@monetize.software/sdk-extension';
|
|
55
55
|
const paywall = new PaywallUI({ paywallId: '...', apiOrigin: '...' });
|
|
56
|
-
paywall.open(); //
|
|
56
|
+
paywall.open(); // exactly like @monetize.software/sdk
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
**On websites** — keep using `@monetize.software/sdk`, nothing changes.
|
|
60
60
|
|
|
61
|
-
## Manifest:
|
|
61
|
+
## Manifest: what to declare in the host extension
|
|
62
62
|
|
|
63
|
-
SDK
|
|
64
|
-
|
|
63
|
+
The SDK itself does not add anything to the manifest — the host extension picks
|
|
64
|
+
permissions to match its own UX. Minimum for the SDK to work:
|
|
65
65
|
|
|
66
66
|
```json
|
|
67
67
|
{
|
|
@@ -71,43 +71,43 @@ SDK сам по себе ничего в манифест не добавляе
|
|
|
71
71
|
}
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
Optional:
|
|
75
75
|
|
|
76
|
-
- `"permissions": ["identity"]` —
|
|
77
|
-
- `web_accessible_resources`
|
|
78
|
-
service worker
|
|
79
|
-
|
|
80
|
-
|
|
76
|
+
- `"permissions": ["identity"]` — if you enable OAuth flows (`auth: true` + Google/etc.).
|
|
77
|
+
- `web_accessible_resources` for `offscreen.html` is **not required** — the
|
|
78
|
+
document is created by the service worker via `chrome.offscreen.createDocument`,
|
|
79
|
+
that's a Chrome API and doesn't need WAR. Listing it adds attack surface (any
|
|
80
|
+
site could `<iframe>` your offscreen, plus it fingerprints your extension ID).
|
|
81
81
|
|
|
82
|
-
### `host_permissions` —
|
|
82
|
+
### `host_permissions` — what to pick
|
|
83
83
|
|
|
84
|
-
`host_permissions`
|
|
85
|
-
offscreen / SW / content-script)
|
|
86
|
-
|
|
84
|
+
`host_permissions` control two things: where the extension can `fetch` (from
|
|
85
|
+
offscreen / SW / content-script) and which origins the content-script can be
|
|
86
|
+
injected into (together with `content_scripts.matches`).
|
|
87
87
|
|
|
88
|
-
|
|
|
88
|
+
| Scenario | Recommendation |
|
|
89
89
|
|---|---|
|
|
90
|
-
| **Host extension
|
|
91
|
-
| **Host extension
|
|
92
|
-
|
|
|
90
|
+
| **Host extension already needs `<all_urls>`** (recorder, all-sites tool, assistant) | Keep `<all_urls>`. SDK works as-is. **Risk:** Chrome Web Store review for `<all_urls>` is a manual audit and takes longer; AV vendors (Avast/Kaspersky/etc.) are more likely to flag such extensions as PUA. That's the price of broad injection — it's a property of your use case, not an SDK risk. |
|
|
91
|
+
| **Host extension only talks to your backend and gates its own features** (popup tool, side-panel app) | Do NOT request `<all_urls>`. Your `apiOrigin` is enough: `["https://api.your-domain.com/*"]`. No content-script injection on every site needed. |
|
|
92
|
+
| **Hybrid** — popup tool, but content-script needed on a narrow list of domains | Constrain both `host_permissions` and `content_scripts.matches` to those domains: `["https://*.your-target.com/*", "https://api.your-domain.com/*"]`. |
|
|
93
93
|
|
|
94
|
-
|
|
95
|
-
`<all_urls>`
|
|
96
|
-
|
|
94
|
+
The main signal to CWS/AV: the narrower `host_permissions`, the less suspicion.
|
|
95
|
+
Keep `<all_urls>` only when it's genuinely required for your UX, and be ready to
|
|
96
|
+
justify it in CWS review (the "Permission justification" field).
|
|
97
97
|
|
|
98
|
-
## Demo extension
|
|
98
|
+
## Demo extension: build modes
|
|
99
99
|
|
|
100
|
-
|
|
101
|
-
|
|
100
|
+
For self-testing and e2e there's `demo-extension/` — a reference implementation.
|
|
101
|
+
Two builds are available:
|
|
102
102
|
|
|
103
103
|
```bash
|
|
104
|
-
pnpm build:demo # production build (=
|
|
105
|
-
pnpm build:demo:e2e # debug build —
|
|
104
|
+
pnpm build:demo # production build (= the template clients can copy)
|
|
105
|
+
pnpm build:demo:e2e # debug build — exposes window.__paywall for Playwright
|
|
106
106
|
```
|
|
107
107
|
|
|
108
|
-
`build:demo`
|
|
109
|
-
`import.meta.env.MODE !== 'e2e'`).
|
|
110
|
-
|
|
111
|
-
|
|
108
|
+
`build:demo` does NOT put `window.__paywall` into the bundle (dead-code-eliminated
|
|
109
|
+
via `import.meta.env.MODE !== 'e2e'`). The template clients copy stays clean: any
|
|
110
|
+
script on the page could otherwise call `paywall.open()` / `paywall.track()` and
|
|
111
|
+
abuse someone else's extension.
|
|
112
112
|
|
|
113
|
-
`pnpm dev:demo`
|
|
113
|
+
`pnpm dev:demo` builds in e2e mode (handy for live debugging from the DevTools console).
|