@molecule/api-push-notifications-web-push 1.0.0 → 1.0.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 +158 -0
- package/package.json +8 -7
package/README.md
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-08-04T01:48:58.858Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# @molecule/api-push-notifications-web-push
|
|
10
|
+
|
|
11
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
+
|
|
15
|
+
Web Push provider for molecule.dev push notifications.
|
|
16
|
+
|
|
17
|
+
Provides push notification delivery using the Web Push protocol (VAPID)
|
|
18
|
+
via the `web-push` library.
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { setProvider } from '@molecule/api-push-notifications'
|
|
24
|
+
import { provider } from '@molecule/api-push-notifications-web-push'
|
|
25
|
+
|
|
26
|
+
setProvider(provider) // VAPID config is read from env on first send
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Type
|
|
30
|
+
|
|
31
|
+
`provider`
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npm install @molecule/api-push-notifications-web-push @molecule/api-bond @molecule/api-push-notifications @molecule/api-secrets web-push
|
|
37
|
+
npm install -D @types/web-push
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## API
|
|
41
|
+
|
|
42
|
+
### Functions
|
|
43
|
+
|
|
44
|
+
#### `createProvider()`
|
|
45
|
+
|
|
46
|
+
Creates a new `WebPushProvider` instance. VAPID credentials are configured lazily on first send.
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
function createProvider(): PushNotificationProvider
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**Returns:** A `PushNotificationProvider` backed by the `web-push` library.
|
|
53
|
+
|
|
54
|
+
### Constants
|
|
55
|
+
|
|
56
|
+
#### `provider`
|
|
57
|
+
|
|
58
|
+
Lazily-initialized push notification provider using the `web-push` library.
|
|
59
|
+
Created on first property access via a `Proxy` so no work is done at import time.
|
|
60
|
+
|
|
61
|
+
The `set` trap is REQUIRED, not defensive: methods reached through the proxy
|
|
62
|
+
run with `this` bound to the proxy, so an instance-state write like
|
|
63
|
+
`this.configured = true` would otherwise land on the dummy `{}` target while
|
|
64
|
+
every read passes through to the real instance — `configure()` could then
|
|
65
|
+
never take effect and every send would throw "not configured".
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
const provider: PushNotificationProvider
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
#### `pushNotificationsWebPushSecretDefinitions`
|
|
72
|
+
|
|
73
|
+
Secret definitions required by the Web Push notifications bond.
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
const pushNotificationsWebPushSecretDefinitions: SecretDefinition[]
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Core Interface
|
|
80
|
+
|
|
81
|
+
Implements `@molecule/api-push-notifications` interface.
|
|
82
|
+
|
|
83
|
+
## Bond Wiring
|
|
84
|
+
|
|
85
|
+
Setup function to register this provider with the core interface:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
import { setProvider } from '@molecule/api-push-notifications'
|
|
89
|
+
import { provider } from '@molecule/api-push-notifications-web-push'
|
|
90
|
+
|
|
91
|
+
export function setupPushNotificationsWebPush(): void {
|
|
92
|
+
setProvider(provider)
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Injection Notes
|
|
97
|
+
|
|
98
|
+
### Requirements
|
|
99
|
+
|
|
100
|
+
Peer dependencies:
|
|
101
|
+
|
|
102
|
+
- `@molecule/api-bond` ^1.0.1
|
|
103
|
+
- `@molecule/api-push-notifications` ^1.0.1
|
|
104
|
+
- `@molecule/api-secrets` ^1.0.1
|
|
105
|
+
|
|
106
|
+
### Environment Variables
|
|
107
|
+
|
|
108
|
+
- `VAPID_PUBLIC_KEY` _(required)_ — Web Push VAPID public key
|
|
109
|
+
- **Auto-generated at scaffold — no manual setup.**
|
|
110
|
+
- `VAPID_PRIVATE_KEY` _(required)_ — Web Push VAPID private key
|
|
111
|
+
- **Auto-generated at scaffold — no manual setup.**
|
|
112
|
+
- `VAPID_EMAIL` _(required)_ — Web Push contact email
|
|
113
|
+
- Setup: Contact address sent to push services with each request (mailto: form).
|
|
114
|
+
- Example: `mailto:you@example.com`
|
|
115
|
+
|
|
116
|
+
### Runtime Dependencies
|
|
117
|
+
|
|
118
|
+
- `@molecule/api-bond`
|
|
119
|
+
- `@molecule/api-push-notifications`
|
|
120
|
+
- `@molecule/api-secrets`
|
|
121
|
+
- `web-push`
|
|
122
|
+
|
|
123
|
+
Configuration is lazy and env-driven: `configure()` — called automatically on
|
|
124
|
+
the first `send()` if you never call it — reads `VAPID_EMAIL`,
|
|
125
|
+
`VAPID_PUBLIC_KEY`, and `VAPID_PRIVATE_KEY` unless an explicit `VapidConfig`
|
|
126
|
+
is passed. With any of the three missing, wiring/boot does NOT fail:
|
|
127
|
+
`configure()` logs a warning ("Push notifications disabled: missing …") and
|
|
128
|
+
every subsequent `send()`/`sendMany()` THROWS "Push notifications not
|
|
129
|
+
configured" — so a missing env var surfaces at first send, not at startup.
|
|
130
|
+
`VAPID_EMAIL` accepts a bare address or the `mailto:`/`https:` form (a bare
|
|
131
|
+
address is normalized to `mailto:…` — don't prepend `mailto:` to a value that
|
|
132
|
+
already has it). `getPublicKey()` serves the key browsers need to subscribe
|
|
133
|
+
(configured key first, `VAPID_PUBLIC_KEY` fallback); `generateVapidKeys()`
|
|
134
|
+
mints a fresh pair — scaffolds auto-generate these secrets, so it's only
|
|
135
|
+
needed for manual provisioning or rotation. `sendMany()` uses
|
|
136
|
+
`Promise.allSettled`: one dead subscription never aborts the batch (check
|
|
137
|
+
each result's `error`).
|
|
138
|
+
|
|
139
|
+
## E2E Tests
|
|
140
|
+
|
|
141
|
+
Integration checklist — drive the real UI (live preview, no mocks), adapt
|
|
142
|
+
each item to this app's actual screens/flows, and check every box off one
|
|
143
|
+
by one. A box you can't check is an integration bug to fix — not a skip:
|
|
144
|
+
|
|
145
|
+
- [ ] The UI offers an enable-notifications control; activating it triggers
|
|
146
|
+
the browser permission prompt and, once granted, the subscription is
|
|
147
|
+
stored (the UI still shows "enabled" after a full reload).
|
|
148
|
+
- [ ] An event this app notifies about actually delivers a push to the
|
|
149
|
+
subscribed session, with a readable title/body (not raw JSON). The sandbox
|
|
150
|
+
CAPTURES outbound pushes instead of delivering — read the captured message
|
|
151
|
+
with the `read_activity` tool (filter type 'push'); never mock the flow or
|
|
152
|
+
modify production code to expose it.
|
|
153
|
+
- [ ] Clicking the delivered notification opens/focuses the relevant screen
|
|
154
|
+
(when the app claims deep-linking).
|
|
155
|
+
- [ ] Denying the permission leaves the app fully usable and truthful about
|
|
156
|
+
the state (no crash, no false "enabled").
|
|
157
|
+
- [ ] Disabling/unsubscribing stops deliveries, and the disabled state
|
|
158
|
+
persists across a reload.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/api-push-notifications-web-push",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Web Push provider for molecule.dev push notifications",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -17,7 +17,8 @@
|
|
|
17
17
|
}
|
|
18
18
|
},
|
|
19
19
|
"files": [
|
|
20
|
-
"dist"
|
|
20
|
+
"dist",
|
|
21
|
+
"README.md"
|
|
21
22
|
],
|
|
22
23
|
"keywords": [
|
|
23
24
|
"molecule",
|
|
@@ -29,13 +30,13 @@
|
|
|
29
30
|
"web-push": "3.6.7"
|
|
30
31
|
},
|
|
31
32
|
"peerDependencies": {
|
|
32
|
-
"@molecule/api-bond": "^1.0.
|
|
33
|
-
"@molecule/api-push-notifications": "^1.0.
|
|
34
|
-
"@molecule/api-secrets": "^1.0.
|
|
33
|
+
"@molecule/api-bond": "^1.0.1",
|
|
34
|
+
"@molecule/api-push-notifications": "^1.0.1",
|
|
35
|
+
"@molecule/api-secrets": "^1.0.1"
|
|
35
36
|
},
|
|
36
37
|
"devDependencies": {
|
|
37
|
-
"@molecule/api-bond": "1.0.
|
|
38
|
-
"@molecule/api-push-notifications": "1.0.
|
|
38
|
+
"@molecule/api-bond": "1.0.1",
|
|
39
|
+
"@molecule/api-push-notifications": "1.0.1",
|
|
39
40
|
"@types/node": "26.1.2",
|
|
40
41
|
"@types/web-push": "3.6.4",
|
|
41
42
|
"typescript": "6.0.3",
|