@ultimat3/notify 25.2.0 → 26.1.0

package/CLAUDE.md

@@ -12,7 +12,7 @@ returns a `job`, which is the whole design.
 | Never | Because |
 |---|---|
 | `@ultimat3/mail` | Same tier (4). A `Mailer` is declared **structurally** in `channel-mail.ts` — one method, no dependency — exactly as `PgExecutor` (`@ultimat3/core`) mirrors `@ultimat3/db`. Moving `notify` to tier 5 to legalise the import would put notifications above `render`, `pwa` and `ui` for one channel's transport, and would then need a `cli → notify` edge the way `cli → scraping` does. |
-| `@ultimat3/render`, `@ultimat3/ui`, `@ultimat3/ai`, `@ultimat3/mcp`, `@ultimat3/pwa` | Same tier. A notification has no view — the inbox is rendered by the app's page out of `InboxStore.list`, which is data. |
+| `@ultimat3/render`, `@ultimat3/ui`, `@ultimat3/ai`, `@ultimat3/mcp`, `@ultimat3/pwa` | Same tier. A notification has no view — the inbox is rendered by the app's page out of `InboxStore.list`, which is data. `pushChannel` takes a STRUCTURAL `Pusher` (`channel-push.ts`), exactly as `mailChannel` takes a `Mailer`: `@ultimat3/pwa`'s `webPush()` satisfies it, and `NotifyPushMessage` mirrors pwa's `PushNotification` field for field — catalog keys, never text. |
 | `@ultimat3/db`, `@ultimat3/entity` | Legal downward, and deliberately not taken. The three tables this package owns are **DDL constants applied by the boot** (`SQL_NOTIFY_DELIVERIES_TABLE`, `SQL_NOTIFY_INBOX_TABLE`, `SQL_NOTIFY_DIGESTS_TABLE`), the way `x_jobs`, `x_idempotency` and `x_audit` are — never `entity()` declarations, which would put framework tables in the app's migration graph and make an app's `x db gen` responsible for them. The Postgres stores take a structural `PgExecutor`, imported as a **type** from `@ultimat3/core` (its one declaration; `bun run flight-copies` refuses another, `X_HELPER_COPY`). |
 | `@ultimat3/policy` | A notification is addressed to exactly one person and the audience is `recipients`. There is no row a policy could decide about here. The **inbox read surface** is where authz belongs, and that is the app's query. |
 
@@ -87,7 +87,7 @@ so an `open` checkpointed with duplicates by an earlier version is repaired on r
 | `fanout.ts` | the run body: audience, wait order, gates, delivery |
 | `fanout-digest.ts` · `fanout-walk.ts` | the digest branch, and the state both halves share |
 | `attempt.ts` | claim → send → settle, once |
-| `channel.ts` · `channel-in-app.ts` · `channel-mail.ts` | the seam and the two shipped channels |
+| `channel.ts` · `channel-in-app.ts` · `channel-mail.ts` · `channel-push.ts` | the seam and the three shipped channels |
 | `ledger.ts` · `ledger-pg.ts` | the delivery ledger, memory and Postgres |
 | `inbox.ts` · `inbox-pg.ts` | the in-app inbox, memory and Postgres |
 | `preferences.ts` · `digest.ts` | the gate and the window, as seams |

package/README.md

@@ -170,15 +170,15 @@ A read row ages from `read_at` and an unread one from `created_at` — ageing a
 ```ts
 import { bulkChannel, deliveryChannel } from '@ultimat3/notify';
 
-// The app's push vendor and its Slack webhook — a channel is where an SDK belongs.
-declare const pushService: {
-  send(token: string, payload: unknown, init: { signal: AbortSignal }): Promise<void>;
+// The app's SMS vendor and its Slack webhook — a channel is where an SDK belongs.
+declare const smsService: {
+  send(to: string, payload: unknown, init: { signal: AbortSignal }): Promise<void>;
 };
 declare const SLACK_URL: string;
 
 // One call per recipient. The retry unit is one address.
-export const push = deliveryChannel('push', async ({ recipient, event, signal }) => {
-  await pushService.send(recipient.to ?? '', event.params, { signal });
+export const sms = deliveryChannel('sms', async ({ recipient, event, signal }) => {
+  await smsService.send(recipient.to ?? '', event.params, { signal });
 });
 
 // ONE call for the whole audience — a Slack post, a webhook, a digest to an ops channel.
@@ -191,8 +191,55 @@ export const slack = bulkChannel('slack', async ({ recipients, event, signal })
 });
 ```
 
-`inAppChannel()` and `mailChannel({ mailer })` ship. `mailChannel` takes a **structural** `Mailer` —
-one method, no dependency on `@ultimat3/mail`, which is the same tier.
+`inAppChannel()`, `mailChannel({ mailer })` and `pushChannel({ pusher, message })` ship. `mailChannel`
+takes a **structural** `Mailer` — one method, no dependency on `@ultimat3/mail`, which is the same
+tier — and `pushChannel` a structural `Pusher`, for the same reason about `@ultimat3/pwa`.
+
+### Push
+
+`pushChannel` sends one notification to **every device the recipient subscribed**, each rendered in
+the locale that browser subscribed with. `@ultimat3/pwa`'s `webPush()` is the pusher: RFC 8291
+encryption and RFC 8292 (VAPID) signing on WebCrypto, over the runtime the boot installs once
+`app.config.ts` says `pwa: { push: true, vapid: { subject } }`.
+
+```ts
+import { notifier, pushChannel, t } from '@ultimat3/notify';
+import { webPush } from '@ultimat3/pwa';
+
+export const commentPushed = notifier({
+  name: 'post.commented.push',
+  input: t.object({ postId: t.uuid, author: t.string }),
+  tenant: 'none',
+  key: (params) => `comment-push:${params.postId}`,
+  deliver: [
+    {
+      channel: pushChannel<{ postId: string; author: string }>({
+        pusher: webPush(),
+        // Catalog KEYS, never text. `tag` is the device's collapse key — set it: a retried delivery
+        // re-sends to the devices that already got it, and the tag makes that a replacement.
+        message: ({ event }) => ({
+          titleKey: 'push.comment.title',
+          bodyKey: 'push.comment.body',
+          params: { who: event.params.author },
+          url: `/posts/${event.params.postId}`,
+          tag: `post:${event.params.postId}`,
+        }),
+      }),
+    },
+  ],
+});
+```
+
+| `NotifyPushMessage` | |
+|---|---|
+| `titleKey`, `bodyKey`, `params`, `actions[].titleKey` | catalog keys, rendered per subscription |
+| `url` | a path on this app — a tap opens it, anything else opens the root |
+| `tag`, `renotify`, `requireInteraction`, `icon`, `badge` | the Notifications API's, as the worker shows them; `renotify` needs a `tag` |
+| `ttlSeconds`, `urgency`, `topic` | RFC 8030 — how long the push service holds it, how hard it wakes the device, and its collapse key while the device is offline |
+
+A recipient with no subscription is not a failure: the delivery settles, as `mailChannel` settles an
+addressless recipient. A push service that answers 429 or 5xx throws `X_PWA_PUSH_FAILED` after every
+other device was tried, so the job retries; 404/410 deletes the subscription.
 
 ## The inbox
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/notify",
-  "version": "25.2.0",
+  "version": "26.1.0",
   "description": "Notifications: one declaration, many channels — fan-out, preference gate, digest window, delivery ledger, in-app inbox",
   "license": "MIT",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.2.0",
-    "@ultimat3/jobs": "25.2.0",
-    "@ultimat3/schema": "25.2.0",
-    "@ultimat3/time": "25.2.0"
+    "@ultimat3/core": "26.1.0",
+    "@ultimat3/jobs": "26.1.0",
+    "@ultimat3/schema": "26.1.0",
+    "@ultimat3/time": "26.1.0"
   }
 }

package/src/channel-push.ts

@@ -0,0 +1,87 @@
+// Web Push as a channel, over a STRUCTURAL pusher rather than an import of @ultimat3/pwa — the tier
+// argument `channel-mail.ts` makes about `@ultimat3/mail`, word for word: `pwa` is tier 4 and so is
+// this package. `@ultimat3/pwa`'s `webPush()` satisfies `Pusher` in one call, and reaches EVERY
+// device the recipient subscribed, each in its own locale:
+//
+//   pushChannel<CommentPosted>({
+//     pusher: webPush(),
+//     message: ({ event }) => ({
+//       titleKey: 'push.comment.title',
+//       bodyKey: 'push.comment.body',
+//       params: { who: event.params.commenter },
+//       url: `/posts/${event.params.postId}`,
+//       tag: `post:${event.params.postId}`,
+//     }),
+//   })
+
+import type { DeliveryArgs, NotifyChannel } from './channel';
+import { deliveryChannel } from './channel';
+
+/**
+ * What one push says, as catalog KEYS — never text. The pusher renders them per subscription, in
+ * the locale that browser subscribed with, because the server sending a push has no request to
+ * read a language off and a notification in the wrong language is a real bug.
+ */
+export interface NotifyPushMessage {
+  readonly titleKey: string;
+  readonly bodyKey: string;
+  readonly params?: Readonly<Record<string, string | number>> | undefined;
+  /** A PATH on this app, opened by a tap. Another origin opens the app's root instead. */
+  readonly url: string;
+  /**
+   * Collapse key ON THE DEVICE: a newer notification with this tag replaces the older one. Set it —
+   * a retried delivery re-sends to the devices that already got it, and a tag is what makes that
+   * a replacement rather than a second notification.
+   */
+  readonly tag?: string | undefined;
+  /** Alert again when `tag` replaces one. Dropped, with a warning, without a tag. */
+  readonly renotify?: boolean | undefined;
+  readonly requireInteraction?: boolean | undefined;
+  readonly icon?: string | undefined;
+  readonly badge?: string | undefined;
+  readonly actions?: readonly { readonly action: string; readonly titleKey: string }[] | undefined;
+  /** Seconds the push service holds it for an offline device. Default one day. */
+  readonly ttlSeconds?: number | undefined;
+  readonly urgency?: 'very-low' | 'low' | 'normal' | 'high' | undefined;
+  /** Collapse key AT THE PUSH SERVICE, for a device that is offline. */
+  readonly topic?: string | undefined;
+}
+
+/** The seam. `@ultimat3/pwa`'s `webPush()` is the framework's; a vendor SDK fits it too. */
+export interface Pusher {
+  send(push: {
+    /** The recipient's id — the actor whose subscriptions receive it. */
+    readonly to: string;
+    readonly message: NotifyPushMessage;
+    readonly signal: AbortSignal;
+  }): Promise<void> | void;
+}
+
+export const PUSH_CHANNEL = 'push';
+
+export interface PushChannelOptions<Params> {
+  readonly pusher: Pusher;
+  /**
+   * The message for this delivery. `batch` is the whole digest window when the delivery is
+   * digested — render a count from `batch.length`, not one push per event.
+   */
+  readonly message: (args: DeliveryArgs<Params>) => NotifyPushMessage;
+  readonly name?: string | undefined;
+}
+
+/**
+ * One delivery per recipient, to every device they subscribed. A recipient with no subscription is
+ * NOT a failure — the pusher sends to nobody and the delivery settles, exactly as `mailChannel`
+ * settles an addressless recipient: a retry would find the same empty list.
+ */
+export function pushChannel<Params = unknown>(
+  options: PushChannelOptions<Params>,
+): NotifyChannel<Params> {
+  return deliveryChannel<Params>(options.name ?? PUSH_CHANNEL, async (args) => {
+    await options.pusher.send({
+      to: args.recipient.id,
+      message: options.message(args),
+      signal: args.signal,
+    });
+  });
+}

package/src/errors.ts

@@ -170,13 +170,13 @@ export class NotifyDeliveryFailedError extends UltimateError {
     super({
       code: 'X_NOTIFY_DELIVERY_FAILED',
       cause: `channel "${input.channel}" of notifier "${input.notifier}" failed for ${String(input.recipients)} recipient(s): ${renderThrowable(input.cause)}`,
-      // `x jobs ls` first, and never `x jobs show` handed a notifier NAME: that command takes a job id
+      // `x jobs list` first, and never `x jobs show` handed a notifier NAME: that command takes a job id
       // positional and resolves it through `inspectJob`, which answers `X_JOB_UNKNOWN` for
       // anything else — so a notifier NAME made the one command this refusal printed fail every
       // time it was run. A `fix:` that fails is worse than none, because the reader spends their
       // trust on it before finding out. The two-step shape is what `wiki/Error-Codes.md` already
       // documents for this code.
-      fix: `x jobs ls --json   # find the run, then: x jobs show <id> --json — the failing step is deliver:${input.channel}`,
+      fix: `x jobs list --json   # find the run, then: x jobs show <id> --json — the failing step is deliver:${input.channel}`,
       meta: { notifier: input.notifier, channel: input.channel },
     });
   }

package/src/index.ts

@@ -21,6 +21,8 @@ export type { InAppChannelOptions } from './channel-in-app';
 export { IN_APP_CHANNEL, inAppChannel } from './channel-in-app';
 export type { MailChannelOptions, Mailer, NotifyMail } from './channel-mail';
 export { MAIL_CHANNEL, mailChannel } from './channel-mail';
+export type { NotifyPushMessage, PushChannelOptions, Pusher } from './channel-push';
+export { PUSH_CHANNEL, pushChannel } from './channel-push';
 export type {
   DigestAppend,
   DigestBucket,