@ultimat3/notify 12.0.0

package/src/notification.ts

@@ -0,0 +1,63 @@
+// The vocabulary a notification is addressed with: who it is for, and what happened.
+//
+// Both shapes are STRUCTURAL and deliberately thin. A `Recipient` is not a user row and never
+// becomes one: this package cannot read an app's `users` table, and a channel that needs more than
+// an id resolves it itself inside `deliver`.
+
+import type { Schema } from '@ultimat3/schema';
+import { t } from '@ultimat3/schema';
+
+/**
+ * Whoever a notification is addressed to.
+ *
+ * `id` is the only required field, because it is the only one the framework itself reads: it is
+ * half of the delivery ledger's unique key and half of an inbox row. Everything else is a hint a
+ * channel may use.
+ *
+ * `to` is ONE transport address — an email, a webhook URL, a device token — and not a bag keyed by
+ * channel. A bag would be a `Record` this package reads with a data key, which is exactly the
+ * prototype-index defect `bun run proto-index` refuses; and an app whose recipients carry two
+ * different addresses already has the lookup, so its channel's `deliver` is where it belongs.
+ */
+export interface Recipient {
+  readonly id: string;
+  /** BCP-47. A channel that renders text for a person must not guess this. */
+  readonly locale?: string | undefined;
+  /** IANA zone. Required by the house rule for any date a channel renders. */
+  readonly tz?: string | undefined;
+  /** The transport address, when the app already has it at fan-out time. */
+  readonly to?: string | undefined;
+}
+
+/**
+ * Validated at the queue boundary, because a recipient list handed to `.enqueue()` is serialised
+ * JSON by the time the worker reads it — the one place an unvalidated `to` could reach a channel.
+ */
+export const recipientSchema: Schema<unknown, Recipient> = t.object({
+  id: t.string,
+  locale: t.locale.optional(),
+  tz: t.timezone.optional(),
+  to: t.string.optional(),
+}) as unknown as Schema<unknown, Recipient>;
+
+/**
+ * One thing that happened, once. `noticed` writes this as an `Event` row; here it is a value the
+ * fan-out carries, and it is persisted only by the channels that persist — the inbox writes it,
+ * the ledger records that a channel accepted it, and a notifier with neither installed writes no
+ * rows at all.
+ */
+export interface NotifyEvent<Params = unknown> {
+  /** The notifier's name — its queue key, its manifest row, and the ledger's first column. */
+  readonly notifier: string;
+  /**
+   * What makes two invocations the SAME notification. Declared by the author as `key`, and used
+   * twice on purpose: it is the job's `idempotencyKey` and the delivery ledger's event column.
+   * Those are one question — "have we already told them this?" — asked at two layers, so two
+   * values would be two answers that can disagree.
+   */
+  readonly key: string;
+  /** The validated payload. */
+  readonly params: Params;
+  /** When the fan-out ran, from `ctx.now()` — never `new Date()`, so a frozen clock holds. */
+  readonly at: Date;
+}

package/src/notifier.ts

@@ -0,0 +1,160 @@
+// `notifier()` — one declaration, many channels, declared as a `job` and NOT as a ninth primitive.
+//
+// A notification is durable background work with an input schema, an idempotency key, a retry
+// policy and a queue, which is the definition of a `job` — so this file is a FACTORY over `job()`,
+// exactly as `llm()` is one over `action()` and `backfill()` is one over `job()`. That is what
+// gives a notifier `.enqueue()`, the worker's cancellation, the dead-letter path, `x jobs show` and
+// a manifest row without a line here.
+//
+// The declaration lives here and the fan-out lives in `fanout.ts` — the same split `backfill.ts`
+// and `backfill-pass.ts` already have.
+
+import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
+import { DEFAULT_RETRY, job } from '@ultimat3/jobs';
+import type { Schema } from '@ultimat3/schema';
+import { t } from '@ultimat3/schema';
+import { isBulkChannel } from './channel';
+import {
+  NotifyChannelDuplicateError,
+  NotifyChannelsEmptyError,
+  NotifyDigestUnsupportedError,
+} from './errors';
+import { runFanout } from './fanout';
+import type { Recipient } from './notification';
+import { recipientSchema } from './notification';
+import type {
+  ChannelDelivery,
+  NotifyDuration,
+  NotifyPayload,
+  NotifyPlan,
+  RecipientArgs,
+  ResolvedDelivery,
+} from './plan';
+import { toDurationMs } from './plan';
+
+/**
+ * One run is one queue row and one step trace, and every recipient in it is a durable step row. The
+ * ceiling is a real number rather than a shrug: past it the shape is a bulk channel or a paged
+ * sweep, and `X_NOTIFY_FANOUT_TOO_WIDE` says so with both numbers in it.
+ */
+export const DEFAULT_MAX_RECIPIENTS = 500;
+
+/**
+ * `NoInfer` on every field but `input`, deliberately. Without it `Params` is inferred from all six
+ * at once and `deliver: [inAppChannel()]` — whose own default is `unknown` — wins, so an author
+ * who did not write `notifier<Params>(…)` got `params` typed `unknown` in `key`, `tenant`,
+ * `recipients` and every gate. The schema is the ONE declaration of what the params are, which is
+ * the same rule every other primitive in this framework follows; this makes the inference agree.
+ */
+export interface NotifierDefinition<Params> {
+  /**
+   * REQUIRED, unlike a job's. A notifier's name is a durable key — the queue row, the delivery
+   * ledger, every inbox row and the app's preference taxonomy all carry it — so it is never left
+   * to whichever export name a module happened to use.
+   */
+  readonly name: string;
+  /** The params, as a schema and not a `required_params` list: validated once at the boundary,
+   * which is also what gives the notifier a manifest row and a typed client. */
+  readonly input: Schema<unknown, Params>;
+  /** REQUIRED, exactly as on `job()`. A notifier IS a job and declares the org it runs under. */
+  readonly tenant: JobTenant<NoInfer<Params>>;
+  /**
+   * What makes two invocations the SAME notification, for the queue AND for the delivery ledger.
+   * Required for the reason `job().idempotencyKey` is: queues deliver at least once, so "did this
+   * already go out?" is a question every notifier must be able to answer.
+   */
+  readonly key: (params: NoInfer<Params>) => string;
+  /**
+   * The audience, resolved on the worker inside a durable step. Omit it and every enqueue must
+   * name its own recipients — `noticed`'s two modes, and both are here because both are real: a
+   * "post liked" notifier derives its audience, and an admin broadcast is handed one.
+   */
+  readonly recipients?:
+    | ((
+        args: RecipientArgs<NoInfer<Params>>,
+      ) => Promise<readonly Recipient[]> | readonly Recipient[])
+    | undefined;
+  /** At least one. Order does not matter — the fan-out sorts by `wait`. */
+  readonly deliver: readonly ChannelDelivery<NoInfer<Params>>[];
+  readonly queue?: string | undefined;
+  readonly retry?: RetryPolicy | undefined;
+  readonly timeout?: NotifyDuration | undefined;
+  /** Defaults to `DEFAULT_MAX_RECIPIENTS`. */
+  readonly maxRecipients?: number | undefined;
+}
+
+/** Normalised once, at declaration: the run body never re-parses a duration per recipient. */
+function resolve<Params>(
+  name: string,
+  deliveries: readonly ChannelDelivery<Params>[],
+): readonly ResolvedDelivery<Params>[] {
+  if (deliveries.length === 0) throw new NotifyChannelsEmptyError({ notifier: name });
+  const seen = new Set<string>();
+  const resolved = deliveries.map((delivery): ResolvedDelivery<Params> => {
+    const channel = delivery.channel;
+    if (seen.has(channel.name)) {
+      throw new NotifyChannelDuplicateError({ notifier: name, channel: channel.name });
+    }
+    seen.add(channel.name);
+    if (delivery.digest !== undefined && isBulkChannel(channel)) {
+      throw new NotifyDigestUnsupportedError({ notifier: name, channel: channel.name });
+    }
+    return {
+      channel,
+      waitMs: delivery.wait === undefined ? 0 : toDurationMs(delivery.wait),
+      when: delivery.if,
+      unless: delivery.unless,
+      digestMs: delivery.digest === undefined ? undefined : toDurationMs(delivery.digest.window),
+      group: delivery.digest?.group,
+    };
+  });
+  // Ascending, so the fan-out sleeps the delta between one channel and the next. A stable sort
+  // keeps two channels with the same wait in declaration order, which is the order their step
+  // names appear in a trace.
+  return [...resolved].sort((a, b) => a.waitMs - b.waitMs);
+}
+
+export function notifier<Params>(
+  definition: NotifierDefinition<Params>,
+): JobHandle<NotifyPayload<Params>> {
+  const deliveries = resolve(definition.name, definition.deliver);
+  const declared = definition.recipients;
+  const plan: NotifyPlan<Params> = {
+    name: definition.name,
+    maxRecipients: definition.maxRecipients ?? DEFAULT_MAX_RECIPIENTS,
+    deliveries,
+    keyFor: (params) => definition.key(params),
+    // Bound to the definition rather than torn off it, so an author who writes `recipients` as a
+    // method rather than an arrow still gets the right `this`. An enqueue that names no audience
+    // and a notifier that resolves none is an empty fan-out, not an error: a broadcast with no
+    // subscribers left is a legitimate run that delivers nothing.
+    recipientsFor: (args) => (declared === undefined ? [] : declared.call(definition, args)),
+  };
+
+  // Nested rather than spread into the job's input: an app's params may legitimately carry a field
+  // called `recipients`, and a reserved top-level key would collide with the first notification
+  // that is *about* recipients.
+  const payload = t.object({
+    params: definition.input,
+    recipients: t.array(recipientSchema).optional(),
+  }) as unknown as Schema<unknown, NotifyPayload<Params>>;
+
+  return job<NotifyPayload<Params>>({
+    name: definition.name,
+    input: payload,
+    // The declared key verbatim. One value for the queue's dedupe and the ledger's event column,
+    // because they ask one question — a second spelling would be two answers that can disagree.
+    idempotencyKey: (value) => definition.key(value.params),
+    // Forwarded, never decided here: a notifier that declared its tenant and then ran under
+    // somebody else's would be a factory deciding authz.
+    tenant:
+      typeof definition.tenant === 'function'
+        ? (value: NotifyPayload<Params>) =>
+            (definition.tenant as (params: Params) => string)(value.params)
+        : definition.tenant,
+    retry: definition.retry ?? DEFAULT_RETRY,
+    ...(definition.queue === undefined ? {} : { queue: definition.queue }),
+    ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }),
+    run: (args) => runFanout(plan, args),
+  });
+}

package/src/plan.ts

@@ -0,0 +1,105 @@
+// The declaration an app writes, and the resolved plan the fan-out runs. Two shapes rather than
+// one: everything an author may express in `DurationInput` or omit is normalised ONCE at
+// declaration, so the run body never re-parses a duration or re-decides a default per recipient.
+
+import type { Ctx } from '@ultimat3/core';
+import { parseDuration } from '@ultimat3/time';
+import type { AnyNotifyChannel } from './channel';
+import type { NotifyEvent, Recipient } from './notification';
+
+/** `'5m'` | `300_000`. Numbers pass through so a caller may stay explicit, exactly as jobs does. */
+export type NotifyDuration = string | number;
+
+export const toDurationMs = (duration: NotifyDuration): number =>
+  typeof duration === 'number' ? duration : parseDuration(duration);
+
+/**
+ * What a notifier is enqueued with.
+ *
+ * `noticed`'s `PostLiked.with(params).deliver(recipients)` in one object. Nested rather than
+ * flattened: an app's params may legitimately carry a field called `recipients`, and a payload
+ * that could collide with the framework's own reserved key is a bug waiting for the first app
+ * whose notification is *about* recipients.
+ */
+export interface NotifyPayload<Params> {
+  readonly params: Params;
+  /**
+   * The audience, when the caller already knows it. Omitted, the notifier's own `recipients`
+   * resolver runs inside a durable step — which is the form to prefer, because it is re-derived
+   * on the worker rather than serialised through the queue.
+   */
+  readonly recipients?: readonly Recipient[] | undefined;
+}
+
+/** What `if` / `unless` decide about. */
+export interface DeliveryGate<Params> {
+  readonly event: NotifyEvent<Params>;
+  readonly ctx: Ctx;
+}
+
+export interface DigestWindow<Params> {
+  /** How long the window stays open, from its FIRST event. Rolling, never calendar-aligned. */
+  readonly window: NotifyDuration;
+  /**
+   * What coalesces together within one recipient's slot. Defaults to the notifier's name — every
+   * `post.commented` for one person in one digest. Return a thread id for one digest per thread.
+   */
+  readonly group?: ((event: NotifyEvent<Params>) => string) | undefined;
+}
+
+export interface ChannelDelivery<Params> {
+  readonly channel: AnyNotifyChannel<Params>;
+  /**
+   * How long to hold this channel before it fires. `noticed`'s `wait`, and it behaves the way
+   * `noticed` promises and most hand-rolled versions do not: `if` and `unless` are evaluated
+   * AFTER it, so a five-minute delay whose condition went false in minute three sends nothing.
+   */
+  readonly wait?: NotifyDuration | undefined;
+  /** Fire only when this answers true. Evaluated after `wait`. */
+  readonly if?: ((gate: DeliveryGate<Params>) => boolean | Promise<boolean>) | undefined;
+  /** Fire unless this answers true. Both may be declared; both must pass. */
+  readonly unless?: ((gate: DeliveryGate<Params>) => boolean | Promise<boolean>) | undefined;
+  /** Coalesce into one delivery per recipient per window. Individual channels only. */
+  readonly digest?: DigestWindow<Params> | undefined;
+}
+
+/** One delivery with every duration in ms and every default already decided. */
+export interface ResolvedDelivery<Params> {
+  readonly channel: AnyNotifyChannel<Params>;
+  readonly waitMs: number;
+  readonly when: ((gate: DeliveryGate<Params>) => boolean | Promise<boolean>) | undefined;
+  readonly unless: ((gate: DeliveryGate<Params>) => boolean | Promise<boolean>) | undefined;
+  readonly digestMs: number | undefined;
+  readonly group: ((event: NotifyEvent<Params>) => string) | undefined;
+}
+
+export interface RecipientArgs<Params> {
+  readonly input: Params;
+  readonly ctx: Ctx;
+}
+
+/** Everything `runFanout` reads. Built once by `notifier()`, never rebuilt per run. */
+export interface NotifyPlan<Params> {
+  readonly name: string;
+  readonly maxRecipients: number;
+  /** Sorted by `waitMs` ascending — the fan-out sleeps the DELTA between one and the next, so a
+   * channel with no wait fires immediately even when a later one waits an hour. */
+  readonly deliveries: readonly ResolvedDelivery<Params>[];
+  keyFor(params: Params): string;
+  recipientsFor(args: RecipientArgs<Params>): Promise<readonly Recipient[]> | readonly Recipient[];
+}
+
+/** What one run reports, bounded so `x jobs show` can print it. */
+export interface NotifyReport {
+  readonly recipients: number;
+  /** Deliveries this run actually handed to a channel. */
+  readonly delivered: number;
+  /** Suppressed by the preference gate. */
+  readonly suppressed: number;
+  /** Skipped by `if` / `unless`, counted per (recipient, channel) so it compares with `delivered`. */
+  readonly skipped: number;
+  /** Already `sent` in the ledger — a replay that correctly did nothing. */
+  readonly replayed: number;
+  /** Appended to an open digest window that somebody else owns the flush of. */
+  readonly digested: number;
+}

package/src/preferences.ts

@@ -0,0 +1,72 @@
+// The preference gate: one question, asked once per (recipient, notifier, channel), after the wait.
+//
+// `noticed` has no gate at all — it leaves opt-out to a `config.if` closure the app writes per
+// channel, which is four teams writing the same closure four times. So the GATE ships here. What
+// does NOT ship, and never will, is what it consults: the notification taxonomy is the app's, and
+// so is `quietHours` — "quiet" is 22:00–07:00 in the recipient's zone for one product, working
+// hours only for the next, and a framework that picked one would be shipping a business
+// convention (axiom 8).
+//
+// Which is why this file declares an interface and two trivial implementations and nothing else.
+
+import type { Ctx } from '@ultimat3/core';
+import type { NotifyEvent, Recipient } from './notification';
+
+export interface PreferenceQuery<Params = unknown> {
+  readonly recipient: Recipient;
+  /** The notifier's name — the app's taxonomy key, whatever its taxonomy is. */
+  readonly notifier: string;
+  readonly channel: string;
+  readonly event: NotifyEvent<Params>;
+  /** The run's context: `ctx.now()` is the clock a quiet-hours rule must read, never `Date.now()`. */
+  readonly ctx: Ctx;
+}
+
+export interface PreferenceStore {
+  /**
+   * `false` suppresses THIS channel and nothing else — the other channels of the same notifier
+   * still fire. That is the whole point of asking per channel: "email me weekly, ping me in-app
+   * immediately" is one recipient's normal answer, and a gate that returned one boolean for the
+   * notification could not express it.
+   */
+  allows(query: PreferenceQuery): Promise<boolean> | boolean;
+}
+
+/**
+ * The default, and it is `true`. An app that installs nothing gets `noticed`'s behaviour, which is
+ * the right default for a framework: silence-by-default would mean a notifier that delivers
+ * nothing until an app writes a store, and the first symptom would be a missing email.
+ */
+export const allowAllPreferences = (): PreferenceStore => ({ allows: () => true });
+
+export interface MemoryPreferenceStore extends PreferenceStore {
+  /** Opt `recipient` out of `channel` for `notifier`. `'*'` as the notifier is every notifier. */
+  deny(input: { recipient: string; notifier: string; channel: string }): void;
+  clear(): void;
+}
+
+const optOutKey = (recipient: string, notifier: string, channel: string): string =>
+  JSON.stringify([recipient, notifier, channel]);
+
+/**
+ * A test double and a dev store, not a product. Real preferences live in the app's own table
+ * beside the taxonomy that names them; this exists so the gate can be exercised without one.
+ */
+export function createMemoryPreferenceStore(): MemoryPreferenceStore {
+  const denied = new Set<string>();
+  return {
+    allows(query) {
+      const id = query.recipient.id;
+      return (
+        !denied.has(optOutKey(id, query.notifier, query.channel)) &&
+        !denied.has(optOutKey(id, '*', query.channel))
+      );
+    },
+    deny(input) {
+      denied.add(optOutKey(input.recipient, input.notifier, input.channel));
+    },
+    clear() {
+      denied.clear();
+    },
+  };
+}

package/src/stores.ts

@@ -0,0 +1,80 @@
+// The four seams a fan-out reads, installed once per process. Same shape as `setJobDriver` in
+// @ultimat3/jobs and for the same reason: a notifier is declared at import time, long before a
+// boot has a database, so the store cannot be a constructor argument.
+//
+// One installer, never four. Handing them over in one call is what makes "the ledger is Postgres
+// but the inbox is still the memory one" a visible line of code rather than a forgotten fifth call.
+
+import type { DigestStore } from './digest';
+import { NotifyStoreMissingError } from './errors';
+import type { InboxStore } from './inbox';
+import type { DeliveryLedger } from './ledger';
+import { createMemoryDeliveryLedger } from './ledger';
+import type { PreferenceStore } from './preferences';
+import { allowAllPreferences } from './preferences';
+
+export interface NotifyStores {
+  /**
+   * Defaults to `createMemoryDeliveryLedger()`. A default is correct here and nowhere else in this
+   * interface: one process with one replica is genuinely deduped by a heap map, and the failure
+   * mode of having none at all — a replayed attempt sending twice — is worse than the failure mode
+   * of a dev default, which is a second send only after a restart.
+   */
+  readonly ledger?: DeliveryLedger | undefined;
+  /** No default: a channel that writes the inbox refuses rather than dropping the row. */
+  readonly inbox?: InboxStore | undefined;
+  /** Defaults to `allowAllPreferences()` — `noticed`'s behaviour, and the safe one for a boot
+   * that has not written a preferences table yet. Denying by default would mean a notifier that
+   * silently delivers nothing, whose first symptom is a missing email. */
+  readonly preferences?: PreferenceStore | undefined;
+  /** No default: a digest window has nowhere to coalesce into. */
+  readonly digest?: DigestStore | undefined;
+}
+
+export interface InstalledNotifyStores {
+  readonly ledger: DeliveryLedger;
+  readonly inbox: InboxStore | undefined;
+  readonly preferences: PreferenceStore;
+  readonly digest: DigestStore | undefined;
+}
+
+const defaults = (): InstalledNotifyStores => ({
+  ledger: createMemoryDeliveryLedger(),
+  inbox: undefined,
+  preferences: allowAllPreferences(),
+  digest: undefined,
+});
+
+let installed: InstalledNotifyStores = defaults();
+
+/** Whole-object replacement, never a merge: two calls with different halves is the split-brain
+ * `RuntimeOverrides` exists to refuse, and a merge would hide the second call's omissions. */
+export function setNotifyStores(stores: NotifyStores): void {
+  installed = {
+    ledger: stores.ledger ?? createMemoryDeliveryLedger(),
+    inbox: stores.inbox,
+    preferences: stores.preferences ?? allowAllPreferences(),
+    digest: stores.digest,
+  };
+}
+
+export const notifyStores = (): InstalledNotifyStores => installed;
+
+/** Tests only — the same escape `resetJobDriver` offers, so one suite cannot leak into the next. */
+export function resetNotifyStores(): void {
+  installed = defaults();
+}
+
+/** The inbox, or the refusal that names the install call. Never an optional chain at the call
+ * site: a silently skipped inbox write is a notification the user never sees and nobody logs. */
+export function requireInbox(notifier: string): InboxStore {
+  const store = installed.inbox;
+  if (store === undefined) throw new NotifyStoreMissingError({ notifier, store: 'inbox' });
+  return store;
+}
+
+export function requireDigest(notifier: string): DigestStore {
+  const store = installed.digest;
+  if (store === undefined) throw new NotifyStoreMissingError({ notifier, store: 'digest' });
+  return store;
+}

package/src/type-pins.ts

@@ -0,0 +1,53 @@
+// Compile-time pins for the inference this package promises. Source, not a `.test.ts`, on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a claim
+// written there can never fail. Nothing here emits — a regression is a build error (axiom 3).
+
+import type { JobHandle } from '@ultimat3/jobs';
+import { t } from '@ultimat3/schema';
+import { inAppChannel } from './channel-in-app';
+import { notifier } from './notifier';
+import type { NotifyPayload } from './plan';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+/**
+ * THE README'S DECLARATION, without an explicit type argument — the form every app writes and the
+ * one the `typecheck` step cannot read out of a README fence.
+ *
+ * It is here because it did not compile. Before `NoInfer` landed on every field but `input`,
+ * `Params` was inferred from all six at once and `deliver: [inAppChannel()]` — whose own default is
+ * `unknown` — won, so `params.postId` below was a `TS18046: 'params' is of type 'unknown'`. The
+ * schema is the one declaration of what the params are; this is what makes the inference agree.
+ */
+function readmeDeclaration() {
+  return notifier({
+    name: 'notify.type-pin',
+    input: t.object({ postId: t.uuid, orgId: t.uuid, author: t.string }),
+    tenant: (params) => params.orgId,
+    key: (params) => `pin:${params.postId}`,
+    recipients: ({ input }) => [{ id: input.author }],
+    deliver: [{ channel: inAppChannel(), unless: ({ event }) => event.params.author === 'system' }],
+  });
+}
+
+/**
+ * Inside a function that is never CALLED, so this module registers nothing. `notifier()` builds a
+ * `job()` and a job's name is claimed at declaration — a module-scope call here would put a
+ * phantom `notify.type-pin` in every app's queue registry, which is the "built and never called"
+ * defect in its most literal form.
+ */
+type Inferred = ReturnType<typeof readmeDeclaration>;
+
+/** A notifier IS a `job`, so every worker path and every `x jobs` command reaches it unchanged. */
+export type _NotifierIsAJobHandle = Assert<
+  Inferred extends JobHandle<NotifyPayload<{ postId: string; orgId: string; author: string }>>
+    ? true
+    : false
+>;
+
+/** The payload nests `params`; a flattened one would collide with an app field called
+ * `recipients`, which is the reason it is nested at all. */
+export type _PayloadNestsParams = Assert<
+  Parameters<Inferred['idempotencyKeyFor']>[0] extends { params: { postId: string } } ? true : false
+>;