@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.
Files changed (2) hide show
  1. package/README.md +158 -0
  2. 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.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.0",
33
- "@molecule/api-push-notifications": "^1.0.0",
34
- "@molecule/api-secrets": "^1.0.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.0",
38
- "@molecule/api-push-notifications": "1.0.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",