@substrat-run/engine-notifications 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @substrat-run/engine-notifications
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Notifications engine for [Substrat](https://github.com/substrat-run/substrat). It turns an
+occasion a vertical names into email to the people it concerns, with per-person
+preferences, escaped templates and tracked deliveries.
+
+Configured for **public npm publication**; the first npm release is pending. The Handlebar
+demo already uses it in-repo.
+
+## How a vertical uses it
+
+The engine is composed **by call**. Register the module, then call `notify` inside your own
+transaction wherever something is worth telling someone, usually your own consumer of a
+domain event:
+
+```ts
+import { notificationsModule, notify } from '@substrat-run/engine-notifications';
+
+host.registerModule(notificationsModule);
+
+// In your module's `consumers`:
+'workorder.assigned': async (ctx, event) => {
+  const { orderId, technician } = assignedPayload.parse(event.payload); // your own parse
+  notify(ctx, {
+    topic: 'repair-assigned',
+    description: 'A repair was assigned to you', // shown beside the switch
+    dedupeKey: event.id, // a redelivered event mails nobody twice
+    recipients: [technician], // principal ids, never addresses
+    vars: { orderId },
+    about: event.entity,
+    template: { subject: 'New repair: {{orderId}}', text: 'You have repair {{orderId}}.' },
+  });
+},
+```
+
+`notify` checks no permission, like every by-call engine function: the caller checks first.
+
+**Prerequisite: the vertical's `emailSender` grant.** `notify` writes its sends with the kernel's `requestEmail`, and the platform delivers those only for a vertical that staff have granted the email-sender capability (the console's `setVerticalEmailSender`). Without it, nothing fails at the call: every delivery is written `requested`, and then settles `refused` with reason `permission_denied` when the platform's outcome comes back.
+
+## What it owns
+
+- **Dispatch.** For each person, it writes one send intent with the kernel's `requestEmail`
+  in the caller's transaction. The platform's drain delivers it through `adapter-email`.
+  Nothing here talks to a provider.
+- **Templates, rendered safely.** `{{name}}` placeholders are filled from `vars`. A value is
+  HTML-escaped in the HTML part and kept to one line in the subject. A placeholder with no
+  variable makes `notify` throw `validation_failed`, which rolls back the caller: from a
+  consumer, the event dead-letters with the reason; from an operation, the operation fails.
+  A blank mail is never sent.
+- **Preferences.** Each person sets where their notifications go
+  (`notifications/set-my-address`) and switches topics off (`notifications/set-my-preference`).
+  A topic passed as `required` cannot be switched off. A topic is recorded the first time it
+  is used, and that record is what a preferences screen lists.
+- **Delivery tracking.** There is one row per (dedupe key, topic, person, channel), unique on
+  those four. It moves from `requested` to `sent`, `refused` or `dead_lettered` when the
+  platform's outcome event arrives. A delivery that was not sent on its own says why: `muted`,
+  `no_address`, or `digest`.
+- **A person's own history.** `notifications/my-deliveries`, under `notifications:self`, pages
+  the caller's deliveries newest first (`listMyDeliveries` in scope). It is `list-deliveries`
+  with the caller's principal pinned in and no `principal` input, so holding the key never
+  reaches anyone else's rows; `status` and `topic` narrow it. The row is narrower than the
+  administrator's: no `principal`, no `dedupe_key` (the caller's idempotency key) and no
+  `request_id` (the platform's send intent). Its `reason` is kept on a `skipped` row,
+  where it is this engine's own word (`muted`, `no_address`, `digest`, `quarantined`), and
+  is `null` on a `refused` or `dead_lettered` one, whose reason is the platform's outcome
+  code and stays with whoever reads the whole log. Digest rows are listed as they are: an
+  occasion held for the digest reads `skipped`/`digest` and gets a `settled_at` once the
+  digest that carried it is written, the digest is a row of its own under `@digest`
+  (`DIGEST_TOPIC`), and a withdrawn one reads `skipped`/`muted`.
+- **Daily digests.** A person can take any topic that is not required as a daily digest
+  (`notifications/set-my-preference` with `cadence: 'daily-digest'`). `notify` then records the
+  occasion as `skipped` with reason `digest` and holds the rendered message.
+
+  The engine's own schedule, `notifications/send-digests`, runs every 15 minutes
+  (`DIGEST_TICK_MINUTES`) under the engine's system principal. A person is due once their oldest
+  held message is a day old, so nothing waits much longer than a day, and a person with no more
+  than 50 held gets one digest a day. When a digest is due depends on that person's activity,
+  not on a clock.
+
+  Each due person gets one mail of what is held for them, up to 50 messages, oldest first. That
+  mail is one more delivery,
+  under the reserved topic `@digest` (`DIGEST_TOPIC`), and it settles like any other. The
+  occasions it carried are settled into it: still `skipped`/`digest`, now with a `settled_at`.
+  `notifications.digest-sent` lists them.
+
+  **Backlog limit.** A scope holds at most 32 sends waiting for the platform's drain
+  (`MAX_PENDING_PLATFORM_REQUESTS`). A pass therefore sends to at most the room left, less
+  `DIGEST_RESERVE` (8) slots kept for mail that must not wait. Everyone else stays held for the
+  next pass, oldest first, so a backlog drains over a few passes. The pass never meets the
+  cap's refusal.
+
+  **Item limit.** One digest carries at most 50 occasions (`DIGEST_MAX_ITEMS`), oldest first.
+  The rest stay held and are due by the same rule: once the oldest of them is a day old. That is
+  on the very next pass if it already is. It is the one case where a person gets more than one
+  digest a day.
+
+  **Contained failures.** Each person's digest is its own `ctx.atomic`. If writing it fails (a
+  send or a write that throws), nothing of it happened for that person. Their messages stay held
+  and everyone else's digest still goes out. `notifications.digest-failed` and an error line say
+  so, and their next attempt waits a day.
+
+  **Unreadable rows.** A held row that no longer reads, because it left the published shape, is
+  set aside rather than allowed to block the rest. It is marked `quarantined_at` and not sent.
+  It counts toward nothing: not who is due, not a switch-off's withdrawal, not the stale-hold
+  warning. Its occasion's delivery settles `skipped`/`quarantined`, and
+  `notifications.digest-quarantined` and an error line name the occasions, never their
+  content. The person's readable messages go out as usual.
+
+  The cause may pass, for instance a rollback to a version that rejects what a newer one
+  stored. So a set-aside row is read again once a day. When it reads, it is released: held
+  again, its delivery back to `skipped`/`digest`, and `notifications.digest-released` names it.
+  It then goes out in the person's next digest. If its person has switched the topic off in the
+  meantime, it is withdrawn instead: deleted unsent, its delivery settled `skipped`/`muted`, and
+  `notifications.digest-withdrawn` names it. A row that still does not read waits another day,
+  and nothing is said again. An erasure of the person deletes set-aside rows with the
+  rest.
+
+  **Mutes and required topics.** A mute still wins: switching a topic off withdraws what is
+  held for it, and those occasions' deliveries then read `skipped`/`muted`. The digest checks
+  again as it composes: a held message whose topic is switched off is withdrawn, never mailed,
+  whatever path brought it there. A required topic always goes out at once, and overrides a
+  mute written before it became required. Mutes are per topic and channel; there is no mute
+  for a whole channel.
+
+  A digest adds no words of its own. A digest of one message is that message. A digest of
+  several uses the first one's subject with `(+N)` and puts each message under its own subject,
+  so the mail stays in the vertical's language. The result is one document. A message whose
+  html is a whole document (`<!doctype html><html>…`) cannot nest, so its text part stands in.
+
+  **Something must run the schedule.** On the hosted platform the scope sweeper does, once a
+  scope's provision has granted the schedule's key: an install provisioned before this engine
+  declared the schedule gets it from the reconcile that follows a promote. A self-hosted server
+  must run `runDueSchedules` or `startPlatformSweeper`, as Handlebar's dev server does.
+
+  **Something must drain the sends.** Room only comes back as the platform drains the scope's
+  pending sends. On the hosted platform the control plane's sweep does this every 15 minutes. A
+  scheduled pass gets no immediate drain kick, unlike an operation a request ran. A server that
+  drains nothing, as Handlebar's dev server does not, fills its backlog: from then on every
+  pass defers everyone and logs that it did.
+
+  Wherever the schedule does not run or the sends do not drain, messages are held and nothing
+  fails. A hold that finds a person's oldest message (set-aside rows aside) two days old writes
+  a warning line, whatever the cause.
+
+**One topic, one declaration.** A topic's `description` and `required` are recorded from the call that uses it, and follow the latest caller, so a deploy that changes them updates the scope. Every call site for a topic must pass the same pair: two that disagree make the topic flip with whichever ran last, and a mute be refused or allowed accordingly. Keep each topic in one constant that its call sites spread, and change it there.
+
+## Personal data
+
+Events carry principals, never addresses. The address lives on the engine's recipient row,
+which a subject erasure deletes (K-46). The send intent carries the recipient as its
+`subjectId`, so the same erasure cancels a send that is still waiting. A message held for a
+digest is rendered mail addressed to the person, so the same erasure deletes it too. Its
+occasion's delivery keeps reason `digest` with no `settled_at`, the way a cancelled send's keeps
+`requested`: an erasure writes no event the engine could settle it from.
+
+## Not yet
+
+Channels other than email (SMS, push, in-app), tenant-edited or per-locale templates
+(including a digest's own wording), quiet hours and a digest's time of day, digest cadences
+other than daily. See K-47 for where this engine sits and
+why it is not kernel code.
+
+## Permissions
+
+| Key | What it allows |
+| --- | --- |
+| `notifications:self` | Set where your own notifications go and which topics reach you, and read what became of them |
+| `notifications:read` | Read what became of every notification in the scope |
+| `notifications:send-digests` | The digest schedule's key. The engine's system principal holds it. The manifest declares it `holder: 'system'`, so `lint:permissions` refuses a role or entity grant shape that grants it to a person |
+
+## Licence
+
+AGPL-3.0-only, or a commercial licence.

package/dist/entities.d.ts

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+/** The cadences that hold a topic back for a digest — what a cadence row stores. */
+export declare const digestCadence: z.ZodEnum<{
+    "daily-digest": "daily-digest";
+}>;
+/**
+ * engine-notifications' entities.
+ *
+ * - **`notification-topic`** is a kind of notification this scope has sent: recorded by
+ *   `notify` the first time a topic is used, and kept to the caller's latest description and
+ *   `required`. It is what a preferences screen lists and what a mute must name — the topics
+ *   are the vertical's code, so the scope learns them by being told, not by registration.
+ * - **`notification-recipient`** is where a person's notifications go: one address per
+ *   principal. It lives HERE rather than on an event because an address is erasable and an
+ *   event is the one copy an erasure cannot rewrite (the same reason `todo.list-shared`
+ *   carries a principal and no address), and module code has no other place to find one:
+ *   the identity directory is not reachable through `ctx`. Erasing the principal deletes
+ *   the row (K-46), and the send intents already written for them carry their `subjectId`,
+ *   so a held send is cancelled by the same erasure.
+ * - **`notification-mute`** is a channel a person has switched off for one topic. Its
+ *   presence is the fact: a topic is on until muted, so a new topic reaches people without
+ *   a preference row being written for each of them first.
+ * - **`notification-delivery`** is what became of one (occasion, topic, person, channel). It
+ *   names the principal and the platform request, never the address, so it is not
+ *   personal data beyond the pseudonymous id the event spine already carries.
+ *   `UNIQUE (dedupe_key, topic, principal, channel)` is the idempotency: the caller names the
+ *   occasion (from a consumer, the event's id), and a repeat — a redelivered event — mails
+ *   nobody twice. A digest is one delivery too, under the reserved topic `@digest`.
+ * - **`notification-cadence`** is a topic a person has asked to receive in a digest rather
+ *   than at once, per channel. Like a mute, its presence is the fact: no row is `immediate`,
+ *   which is what every person had before digests existed.
+ * - **`notification-digest-item`** is one occasion held for a person's next digest: the
+ *   message as `notify` rendered it, keyed by the occasion's own delivery row (`id`). A row
+ *   leaves when its digest is sent or a switch-off withdraws it. `failed_at` marks a person whose
+ *   digest could not be written, so the next attempt waits; `quarantined_at` marks a row found
+ *   unreadable, set aside — unsent, and in nobody's way — and stays until it reads again and is
+ *   released, or an erasure deletes it; it is when the row was last read and found unreadable.
+ *   The rendered text is about the occasion and addressed to the person, so it is erasable, and
+ *   an erasure of the person deletes all their items with their address.
+ */
+export declare const notificationsEntities: {
+    readonly 'notification-topic': {
+        readonly table: "notifications_topics";
+        readonly fields: z.ZodObject<{
+            topic: z.ZodString;
+            description: z.ZodString;
+            required: z.ZodNumber;
+            recorded_at: z.ZodString;
+        }, z.core.$strip>;
+        readonly primaryKey: readonly ["topic"];
+    };
+    readonly 'notification-recipient': {
+        readonly table: "notifications_recipients";
+        readonly fields: z.ZodObject<{
+            principal: z.ZodString;
+            email: z.ZodString;
+            updated_at: z.ZodString;
+        }, z.core.$strip>;
+        readonly primaryKey: readonly ["principal"];
+        readonly erasable: readonly ["email"];
+        readonly erasure: {
+            readonly subjects: readonly ["principal"];
+            readonly mode: "delete";
+        };
+    };
+    readonly 'notification-mute': {
+        readonly table: "notifications_mutes";
+        readonly fields: z.ZodObject<{
+            principal: z.ZodString;
+            topic: z.ZodString;
+            channel: z.ZodString;
+            created_at: z.ZodString;
+        }, z.core.$strip>;
+        readonly primaryKey: readonly ["principal", "topic", "channel"];
+    };
+    readonly 'notification-delivery': {
+        readonly table: "notifications_deliveries";
+        readonly fields: z.ZodObject<{
+            id: z.ZodString;
+            topic: z.ZodString;
+            dedupe_key: z.ZodString;
+            principal: z.ZodString;
+            channel: z.ZodString;
+            status: z.ZodEnum<{
+                dead_lettered: "dead_lettered";
+                refused: "refused";
+                requested: "requested";
+                sent: "sent";
+                skipped: "skipped";
+            }>;
+            reason: z.ZodNullable<z.ZodString>;
+            request_id: z.ZodNullable<z.ZodString>;
+            about_type: z.ZodNullable<z.ZodString>;
+            about_id: z.ZodNullable<z.ZodString>;
+            created_at: z.ZodString;
+            settled_at: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        readonly key: readonly ["dedupe_key", "topic", "principal", "channel"];
+    };
+    readonly 'notification-cadence': {
+        readonly table: "notifications_cadences";
+        readonly fields: z.ZodObject<{
+            principal: z.ZodString;
+            topic: z.ZodString;
+            channel: z.ZodString;
+            cadence: z.ZodEnum<{
+                "daily-digest": "daily-digest";
+            }>;
+            updated_at: z.ZodString;
+        }, z.core.$strip>;
+        readonly primaryKey: readonly ["principal", "topic", "channel"];
+    };
+    readonly 'notification-digest-item': {
+        readonly table: "notifications_digest_items";
+        readonly fields: z.ZodObject<{
+            id: z.ZodString;
+            principal: z.ZodString;
+            channel: z.ZodString;
+            topic: z.ZodString;
+            dedupe_key: z.ZodString;
+            subject: z.ZodString;
+            text: z.ZodString;
+            html: z.ZodString;
+            about_type: z.ZodNullable<z.ZodString>;
+            about_id: z.ZodNullable<z.ZodString>;
+            queued_at: z.ZodString;
+            failed_at: z.ZodNullable<z.ZodString>;
+            quarantined_at: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        readonly erasable: readonly ["subject", "text", "html"];
+        readonly erasure: {
+            readonly subjects: readonly ["principal"];
+            readonly mode: "delete";
+        };
+    };
+};
+/** One delivery, as stored and as published — it holds nothing the reader may not see. */
+export declare const deliveryRow: z.ZodObject<{
+    id: z.ZodString;
+    topic: z.ZodString;
+    dedupe_key: z.ZodString;
+    principal: z.ZodString;
+    channel: z.ZodString;
+    status: z.ZodEnum<{
+        dead_lettered: "dead_lettered";
+        refused: "refused";
+        requested: "requested";
+        sent: "sent";
+        skipped: "skipped";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    request_id: z.ZodNullable<z.ZodString>;
+    about_type: z.ZodNullable<z.ZodString>;
+    about_id: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    settled_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * One delivery as the person it went to reads it: what became of it, and what it was about.
+ *
+ * Left out, deliberately: `principal` (always the reader), `dedupe_key` (the caller's idempotency
+ * key — an event id, an entity id — which says nothing to the person), `request_id` (the
+ * platform's send intent). `reason` is kept only where the engine wrote it — on a `skipped`
+ * row — and is `null` on a `refused` or `dead_lettered` one, whose reason is the platform's
+ * outcome code and belongs to whoever reads the whole log (`notifications:read`).
+ */
+export declare const myDeliveryRow: z.ZodObject<{
+    id: z.ZodString;
+    topic: z.ZodString;
+    channel: z.ZodString;
+    status: z.ZodEnum<{
+        dead_lettered: "dead_lettered";
+        refused: "refused";
+        requested: "requested";
+        sent: "sent";
+        skipped: "skipped";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    about_type: z.ZodNullable<z.ZodString>;
+    about_id: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    settled_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** One pending digest item, as stored — read back only to compose the digest. */
+export declare const digestItemRow: z.ZodObject<{
+    id: z.ZodString;
+    principal: z.ZodString;
+    channel: z.ZodString;
+    topic: z.ZodString;
+    dedupe_key: z.ZodString;
+    subject: z.ZodString;
+    text: z.ZodString;
+    html: z.ZodString;
+    about_type: z.ZodNullable<z.ZodString>;
+    about_id: z.ZodNullable<z.ZodString>;
+    queued_at: z.ZodString;
+    failed_at: z.ZodNullable<z.ZodString>;
+    quarantined_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=entities.d.ts.map

package/dist/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oFAAoF;AACpF,eAAO,MAAM,aAAa;;EAA2B,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqFhC,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;iBAAwD,CAAC;AAEjF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;iBAUxB,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;iBAA2D,CAAC"}

package/dist/entities.js

@@ -0,0 +1,150 @@
+import { defineEntities } from '@substrat-run/contracts';
+import { z } from 'zod';
+/** The cadences that hold a topic back for a digest — what a cadence row stores. */
+export const digestCadence = z.enum(['daily-digest']);
+/**
+ * engine-notifications' entities.
+ *
+ * - **`notification-topic`** is a kind of notification this scope has sent: recorded by
+ *   `notify` the first time a topic is used, and kept to the caller's latest description and
+ *   `required`. It is what a preferences screen lists and what a mute must name — the topics
+ *   are the vertical's code, so the scope learns them by being told, not by registration.
+ * - **`notification-recipient`** is where a person's notifications go: one address per
+ *   principal. It lives HERE rather than on an event because an address is erasable and an
+ *   event is the one copy an erasure cannot rewrite (the same reason `todo.list-shared`
+ *   carries a principal and no address), and module code has no other place to find one:
+ *   the identity directory is not reachable through `ctx`. Erasing the principal deletes
+ *   the row (K-46), and the send intents already written for them carry their `subjectId`,
+ *   so a held send is cancelled by the same erasure.
+ * - **`notification-mute`** is a channel a person has switched off for one topic. Its
+ *   presence is the fact: a topic is on until muted, so a new topic reaches people without
+ *   a preference row being written for each of them first.
+ * - **`notification-delivery`** is what became of one (occasion, topic, person, channel). It
+ *   names the principal and the platform request, never the address, so it is not
+ *   personal data beyond the pseudonymous id the event spine already carries.
+ *   `UNIQUE (dedupe_key, topic, principal, channel)` is the idempotency: the caller names the
+ *   occasion (from a consumer, the event's id), and a repeat — a redelivered event — mails
+ *   nobody twice. A digest is one delivery too, under the reserved topic `@digest`.
+ * - **`notification-cadence`** is a topic a person has asked to receive in a digest rather
+ *   than at once, per channel. Like a mute, its presence is the fact: no row is `immediate`,
+ *   which is what every person had before digests existed.
+ * - **`notification-digest-item`** is one occasion held for a person's next digest: the
+ *   message as `notify` rendered it, keyed by the occasion's own delivery row (`id`). A row
+ *   leaves when its digest is sent or a switch-off withdraws it. `failed_at` marks a person whose
+ *   digest could not be written, so the next attempt waits; `quarantined_at` marks a row found
+ *   unreadable, set aside — unsent, and in nobody's way — and stays until it reads again and is
+ *   released, or an erasure deletes it; it is when the row was last read and found unreadable.
+ *   The rendered text is about the occasion and addressed to the person, so it is erasable, and
+ *   an erasure of the person deletes all their items with their address.
+ */
+export const notificationsEntities = defineEntities({
+    'notification-topic': {
+        table: 'notifications_topics',
+        fields: z.object({
+            topic: z.string(),
+            description: z.string(),
+            required: z.number(),
+            recorded_at: z.string(),
+        }),
+        primaryKey: ['topic'],
+    },
+    'notification-recipient': {
+        table: 'notifications_recipients',
+        fields: z.object({
+            principal: z.string(),
+            email: z.string(),
+            updated_at: z.string(),
+        }),
+        primaryKey: ['principal'],
+        erasable: ['email'],
+        // The address is the person's data whole; nothing about the row survives them.
+        erasure: { subjects: ['principal'], mode: 'delete' },
+    },
+    'notification-mute': {
+        table: 'notifications_mutes',
+        fields: z.object({
+            principal: z.string(),
+            topic: z.string(),
+            channel: z.string(),
+            created_at: z.string(),
+        }),
+        primaryKey: ['principal', 'topic', 'channel'],
+    },
+    'notification-delivery': {
+        table: 'notifications_deliveries',
+        fields: z.object({
+            id: z.string(),
+            topic: z.string(),
+            dedupe_key: z.string(),
+            principal: z.string(),
+            channel: z.string(),
+            status: z.enum(['requested', 'skipped', 'sent', 'refused', 'dead_lettered']),
+            reason: z.string().nullable(),
+            request_id: z.string().nullable(),
+            about_type: z.string().nullable(),
+            about_id: z.string().nullable(),
+            created_at: z.string(),
+            settled_at: z.string().nullable(),
+        }),
+        key: ['dedupe_key', 'topic', 'principal', 'channel'],
+    },
+    'notification-cadence': {
+        table: 'notifications_cadences',
+        fields: z.object({
+            principal: z.string(),
+            topic: z.string(),
+            channel: z.string(),
+            cadence: digestCadence,
+            updated_at: z.string(),
+        }),
+        primaryKey: ['principal', 'topic', 'channel'],
+    },
+    'notification-digest-item': {
+        table: 'notifications_digest_items',
+        fields: z.object({
+            id: z.string(),
+            principal: z.string(),
+            channel: z.string(),
+            topic: z.string(),
+            dedupe_key: z.string(),
+            subject: z.string(),
+            text: z.string(),
+            html: z.string(),
+            about_type: z.string().nullable(),
+            about_id: z.string().nullable(),
+            queued_at: z.string(),
+            /** When the last attempt to send this person's digest failed; the next waits a window. */
+            failed_at: z.string().nullable(),
+            /** When this row was last read and found unreadable; null while it is held as usual. */
+            quarantined_at: z.string().nullable(),
+        }),
+        erasable: ['subject', 'text', 'html'],
+        // Mail addressed to the person: nothing about a pending item survives them.
+        erasure: { subjects: ['principal'], mode: 'delete' },
+    },
+});
+/** One delivery, as stored and as published — it holds nothing the reader may not see. */
+export const deliveryRow = notificationsEntities['notification-delivery'].fields;
+/**
+ * One delivery as the person it went to reads it: what became of it, and what it was about.
+ *
+ * Left out, deliberately: `principal` (always the reader), `dedupe_key` (the caller's idempotency
+ * key — an event id, an entity id — which says nothing to the person), `request_id` (the
+ * platform's send intent). `reason` is kept only where the engine wrote it — on a `skipped`
+ * row — and is `null` on a `refused` or `dead_lettered` one, whose reason is the platform's
+ * outcome code and belongs to whoever reads the whole log (`notifications:read`).
+ */
+export const myDeliveryRow = deliveryRow.pick({
+    id: true,
+    topic: true,
+    channel: true,
+    status: true,
+    reason: true,
+    about_type: true,
+    about_id: true,
+    created_at: true,
+    settled_at: true,
+});
+/** One pending digest item, as stored — read back only to compose the digest. */
+export const digestItemRow = notificationsEntities['notification-digest-item'].fields;
+//# sourceMappingURL=entities.js.map

package/dist/entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"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"}