@voltro/plugin-notifications 0.52.0 → 0.54.0

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-notifications itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (6 packages).
+Generated from the resolved runtime dependency closure (12 packages).
 
 ---
 
@@ -37,6 +37,146 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## @tanstack/devtools-event-client@0.4.4
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) 2025 TanStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## @tanstack/form-core@1.33.5
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) 2021-present Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## @tanstack/pacer-lite@0.1.1
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## @tanstack/react-store@0.11.1
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) 2021 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## @tanstack/store@0.11.1
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) 2021 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## jose@6.2.8
 
 License: MIT
@@ -329,6 +469,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## use-sync-external-store@1.6.0
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## uuid@11.1.1
 
 License: MIT

package/dist/index.d.ts

@@ -24,10 +24,17 @@ export declare const buildNotificationService: (deps: {
 }) => NotificationServiceShape;
 
 /** A delivery channel. `id` is the channel key prefs target (e.g. 'email',
- *  'slack', 'sms', 'push', 'inApp'). */
+ *  'slack', 'sms', 'push', 'inApp').
+ *
+ *  A MULTI-ENDPOINT channel (web push, mobile push) additionally implements
+ *  `deliverDetailed`: per-endpoint outcomes, each endpoint isolated — one dead
+ *  registration never aborts the others, and the delivery log says per
+ *  endpoint what happened (the per-CHANNEL record the old push loop wrote
+ *  could not). The service prefers it over `deliver` when present. */
 export declare interface Channel {
     readonly id: string;
     readonly deliver: (msg: ChannelMessage) => Promise<void>;
+    readonly deliverDetailed?: (msg: ChannelMessage) => Promise<ReadonlyArray<EndpointDelivery>>;
 }
 
 /** A built notification to deliver on one channel. */
@@ -65,6 +72,19 @@ export declare const customChannel: (id: string, deliver: (msg: ChannelMessage)
  */
 export declare const dataStoreNotificationStore: (store: DataStore) => NotificationStore;
 
+export declare const dataStorePushSubscriptionStore: (store: DataStore) => PushSubscriptionStore;
+
+/**
+ * The receiver side — what a browser does with the body above. Shipped (not
+ * test-only) because the mock-push-endpoint test IS the product's proof: a test
+ * that asserts "some bytes arrived" proves transport, this proves the bytes
+ * decrypt with the subscriber's keys and nothing else.
+ */
+export declare const decryptWebPushPayload: (body: Buffer, receiver: {
+    readonly uaPrivate: Buffer;
+    readonly authSecret: Buffer;
+}) => Buffer;
+
 export declare const deliveriesTable: Table<"_voltro_notification_deliveries", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "id", boolean>;
     readonly recipient: ColumnBuilder<string, "text", boolean>;
@@ -73,9 +93,14 @@ export declare const deliveriesTable: Table<"_voltro_notification_deliveries", F
     readonly status: ColumnBuilder<string, "text", boolean>;
     readonly error: ColumnBuilder<string | null, "text", boolean>;
     readonly at: ColumnBuilder<Date, "timestamp", true>;
-}>, true, "byDeliveriesAt">;
-
-/** Per-channel delivery outcome (for the delivery log). */
+    readonly endpoint: ColumnBuilder<string | null, "text", boolean>;
+    readonly clickToken: ColumnBuilder<string | null, "text", boolean>;
+    readonly clickedAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+}>, true, "byDeliveriesAt" | "byDeliveriesClickToken">;
+
+/** Per-channel delivery outcome (for the delivery log). A multi-endpoint
+ *  channel writes ONE record per endpoint (`endpoint` set); single-target
+ *  channels write one per channel as before. */
 export declare interface DeliveryRecord {
     readonly id: string;
     readonly to: string;
@@ -84,6 +109,13 @@ export declare interface DeliveryRecord {
     readonly status: 'sent' | 'failed' | 'skipped';
     readonly error?: string;
     readonly at: string;
+    /** The device token / push endpoint this record is about, on multi-endpoint
+     *  channels. Absent on single-target channels. */
+    readonly endpoint?: string | null;
+    /** Click-report capability (web push). Never sent to a dashboard reader. */
+    readonly clickToken?: string | null;
+    /** Set when the recipient clicked the delivered notification. */
+    readonly clickedAt?: string | null;
 }
 
 /** Email channel — the app supplies the sender (compose with
@@ -95,6 +127,39 @@ export declare const emailChannel: (send: (msg: {
     text: string;
 }) => Promise<void>) => Channel;
 
+/** Test seam: fixed ephemeral key + salt reproduce RFC 8291 Appendix A. */
+declare interface EncryptOverrides {
+    readonly asPrivate?: Buffer;
+    readonly salt?: Buffer;
+}
+
+/**
+ * Encrypt one payload for one subscription — the complete `aes128gcm` body
+ * (header ‖ ciphertext) a push service accepts, per RFC 8291. Single record
+ * (web-push payloads are capped ~4 KB by every push service, so multi-record
+ * framing buys nothing).
+ */
+export declare const encryptWebPushPayload: (keys: PushSubscriptionKeys, payload: Buffer, overrides?: EncryptOverrides) => Buffer;
+
+/** One endpoint's (device token's / browser subscription's) outcome inside a
+ *  multi-endpoint channel delivery. `pruned` marks a registration the channel
+ *  itself removed (the push service said it is gone). */
+declare interface EndpointDelivery {
+    readonly endpoint: string;
+    readonly status: 'sent' | 'failed';
+    readonly error?: string;
+    readonly pruned?: boolean;
+    /** Capability for the notification-click report — stored on the delivery
+     *  record, carried in the push payload, matched constant-time. */
+    readonly clickToken?: string;
+}
+
+export declare const endpointHashOf: (endpoint: string) => string;
+
+/** Mint a fresh P-256 private scalar, base64url — what the dev secret mint and
+ *  `voltro secret generate` produce for `VOLTRO_VAPID_PRIVATE_KEY`. */
+export declare const generateVapidPrivateKey: () => string;
+
 /** One notification held for later delivery — a digest window rollup or a
  *  quiet-hours deferral. `flushAt` is the ISO instant it becomes deliverable
  *  (the window boundary / the digest flush tick). `kind` marks WHY it was held
@@ -205,6 +270,8 @@ export declare const makeSubjectId: (resolve: NotificationsPluginOptions["resolv
 
 export declare const memoryNotificationStore: () => NotificationStore;
 
+export declare const memoryPushSubscriptionStore: () => PushSubscriptionStore;
+
 /** The minute-of-day (0–1439) `at` falls on in the IANA `tz`. Uses `Intl` so no
  *  date-math library is needed; an unknown zone falls back to UTC. */
 export declare const minuteOfDayInZone: (at: Date, tz: string) => number;
@@ -374,6 +441,10 @@ export declare interface NotificationStore {
     readonly listDeliveries: (opts?: {
         limit?: number;
     }) => Promise<ReadonlyArray<DeliveryRecord>>;
+    /** Stamp `clickedAt` on the delivery record carrying this click token.
+     *  Constant-time token match happens in the caller; this is the lookup +
+     *  write. Returns false when no record carries the token. */
+    readonly markClicked: (clickToken: string) => Promise<boolean>;
     readonly subscribeTopic: (sub: TopicSubscription) => Promise<void>;
     readonly unsubscribeTopic: (topic: string, subjectId: string) => Promise<void>;
     readonly listTopicSubscribers: (topic: string) => Promise<ReadonlyArray<TopicSubscription>>;
@@ -418,6 +489,10 @@ export declare const pushChannel: (opts: {
     readonly id?: string;
     readonly tokensFor: (subjectId: string) => Promise<ReadonlyArray<string>>;
     readonly transport: (payload: PushPayload) => Promise<void>;
+    /** Called when the transport threw `PushTokenRejected` for one token — the
+     *  app's prune hook (this channel's registry is the APP's table, so the app
+     *  deletes; web push, whose registry is the plugin's own, prunes itself). */
+    readonly onTokenRejected?: (token: string, reason: string) => Promise<void>;
 }) => Channel;
 
 /** The provider-agnostic push payload `pushChannel` builds per device token —
@@ -432,6 +507,54 @@ export declare interface PushPayload {
     readonly data: Record<string, unknown>;
 }
 
+/** A browser push subscription's crypto material, as `PushSubscription.toJSON()`
+ *  hands it to the page: base64url `p256dh` (the UA public key) + `auth`. */
+export declare interface PushSubscriptionKeys {
+    readonly p256dh: string;
+    readonly auth: string;
+}
+
+export declare interface PushSubscriptionRow {
+    readonly subjectId: string;
+    readonly endpoint: string;
+    readonly endpointHash: string;
+    readonly p256dh: string;
+    readonly auth: string;
+    readonly ua: string | null;
+    readonly tenantId: string | null;
+}
+
+export declare const pushSubscriptionsTable: Table<"_voltro_notification_push_subscriptions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly subjectId: ColumnBuilder<string, "text", boolean>;
+    /** sha256 hex of `endpoint` — the unique key (endpoint URLs can exceed the
+     *  unique-index byte ceiling on mssql/mysql, so the hash carries the
+     *  constraint and the URL rides as plain text). */
+    readonly endpointHash: ColumnBuilder<string, "text", boolean>;
+    readonly endpoint: ColumnBuilder<string, "text", boolean>;
+    /** Browser subscription crypto material (`PushSubscription.toJSON().keys`). */
+    readonly p256dh: ColumnBuilder<string, "text", boolean>;
+    readonly auth: ColumnBuilder<string, "text", boolean>;
+    readonly ua: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
+}>, true, "byPushSubject">;
+
+export declare interface PushSubscriptionStore {
+    /** Idempotent per endpoint: a re-subscribe (same browser, possibly a new
+     *  logged-in subject) takes the row over — the endpoint belongs to the
+     *  browser profile, and the latest authenticated subject is its owner. */
+    readonly upsert: (row: PushSubscriptionRow) => Promise<void>;
+    readonly listForSubject: (subjectId: string) => Promise<ReadonlyArray<PushSubscriptionRow>>;
+    /** Unsubscribe — scoped to the CALLING subject so one subject cannot detach
+     *  another's browser. */
+    readonly removeForSubject: (endpointHash: string, subjectId: string) => Promise<boolean>;
+    /** Prune — unconditional by hash: the push service said the endpoint is gone,
+     *  whoever it belonged to. */
+    readonly removeByHash: (endpointHash: string) => Promise<void>;
+    readonly countForSubject: (subjectId: string) => Promise<number>;
+}
+
 /** A push transport rejected a device token (unregistered / invalid / expired —
  *  the APNs `Unregistered` / FCM `UNREGISTERED` class). Thrown by `pushChannel`'s
  *  `deliver` so the fan-out records the delivery `failed` with the token that was
@@ -478,6 +601,9 @@ export declare const quietHoursTable: Table<"_voltro_notification_quiet_hours",
     readonly policy: ColumnBuilder<string, "text", true>;
 }>, true, never>;
 
+/** Test seam. */
+export declare const resetWebPushStoreForTest: () => void;
+
 /**
  * Resolve which channel ids to deliver on. Order: caller-requested `channels`
  * (intersected with configured) ELSE all configured; then drop any the
@@ -509,6 +635,9 @@ export declare interface SendResult {
     readonly held?: 'digest' | 'quiet-held' | 'quiet-drop';
 }
 
+/** POST one encrypted payload to one subscription's push service. */
+export declare const sendWebPush: (target: WebPushTarget, payload: Buffer, options: WebPushSendOptions) => Promise<WebPushOutcome>;
+
 /** SMS via a generic REST sender (Twilio etc.) — app supplies the send fn. */
 export declare const smsChannel: (send: (to: string, body: string) => Promise<void>) => Channel;
 
@@ -527,6 +656,19 @@ export declare const topicSubscriptionsTable: Table<"_voltro_notification_topic_
     readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
 }>, true, "byTopic">;
 
+/**
+ * The `Authorization: vapid t=<jwt>, k=<pub>` header value for one push-service
+ * origin (RFC 8292). `aud` is the ENDPOINT's origin (scheme+host), `exp` 12h
+ * out (the spec ceiling is 24h), `sub` the operator contact when configured —
+ * push services use it to reach whoever is sending, so it is worth setting.
+ */
+export declare const vapidAuthorization: (endpoint: string, privateKeyB64url: string, contact?: string, nowMs?: number) => string;
+
+/** The browser-facing application server key (65-byte uncompressed point,
+ *  base64url) derived from the private scalar. Throws on a malformed key —
+ *  a wrong VAPID key must fail the boot, not the first delivery. */
+export declare const vapidPublicKeyFor: (privateKeyB64url: string) => string;
+
 /** POST the message to an incoming webhook (Slack / Discord / Teams / generic).
  *  `format` shapes the JSON body; default Slack-style `{ text }`. */
 export declare const webhookChannel: (opts: {
@@ -536,4 +678,60 @@ export declare const webhookChannel: (opts: {
     readonly headers?: Record<string, string>;
 }) => Channel;
 
+/**
+ * The Web Push channel. Delivery is per endpoint and isolated — the fan-out
+ * records one `EndpointDelivery` per registered endpoint, prunes on `gone`,
+ * and never lets one endpoint's failure abort another's send.
+ */
+export declare const webPushChannel: (options?: WebPushChannelOptions) => Channel;
+
+export declare interface WebPushChannelOptions {
+    /** Override the channel id (prefs key). Default `webPush`. */
+    readonly id?: string;
+    /** The VAPID private scalar. Default: `VOLTRO_VAPID_PRIVATE_KEY` from the
+     *  environment, read at delivery time (env files load after config). */
+    readonly privateKey?: string;
+    /** VAPID `sub` contact (`mailto:`/https) push services may use to reach the
+     *  operator. Strongly recommended for production. */
+    readonly contact?: string;
+    /** Push-service retention (TTL header), seconds. Default 24h. */
+    readonly ttl?: number;
+    /** Test seam — injected into `sendWebPush`. */
+    readonly fetchImpl?: typeof fetch;
+}
+
+export declare type WebPushOutcome = {
+    readonly kind: 'delivered';
+    readonly status: number;
+}
+/** 404/410 — the subscription no longer exists at the push service. The ONE
+*  signal a registry may prune on. */
+| {
+    readonly kind: 'gone';
+    readonly status: number;
+} | {
+    readonly kind: 'failed';
+    readonly status: number;
+    readonly detail: string;
+};
+
+/** The browser-facing application server key for the configured private key. */
+export declare const webPushPublicKey: (explicit?: string) => string;
+
+export declare interface WebPushSendOptions {
+    readonly privateKey: string;
+    /** VAPID `sub` claim — `mailto:` or https URL the push service can reach the
+     *  operator at. */
+    readonly contact?: string;
+    /** Push-service retention for an undeliverable message, seconds. Default 24h. */
+    readonly ttl?: number;
+    /** Injectable for the mock-endpoint tests. */
+    readonly fetchImpl?: typeof fetch;
+}
+
+export declare interface WebPushTarget {
+    readonly endpoint: string;
+    readonly keys: PushSubscriptionKeys;
+}
+
 export { }