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

package/dist/events.d.ts

@@ -0,0 +1,212 @@
+/**
+ * engine-notifications' event contract — what a VERTICAL imports so that reading this
+ * engine's outcomes by event is checked rather than guessed.
+ *
+ * Types plus one stamp, the same shape as every other engine's `events.ts`: the runtime
+ * contract is the fat payload and the consumer's own Zod parse; `emitNotificationsEvent`
+ * forwards to `ctx.emit`, adding only the `schemaVersion` from
+ * `notificationsEventVersions` (#1597).
+ *
+ * **No address appears.** Each payload but `topic-recorded`'s names a principal (pseudonymous, and the event's
+ * `subjectId`) and never where their mail goes: the address is erasable and lives only on
+ * the engine's recipient row and on the platform's send intent, both of which an erasure
+ * reaches. A field added here must keep that true.
+ *
+ * Additive, like every other engine surface: a new event type may appear, an existing
+ * payload field does not change shape without a `schemaVersion` bump.
+ */
+import type { DomainEventInput, EntityRef } from '@substrat-run/contracts';
+import type { OperationContext } from '@substrat-run/kernel';
+/**
+ * What `notify` did for one (occasion, topic, person, channel).
+ *
+ * `requested`: a send intent was written, and `request` is its id. `skipped`: nothing was
+ * sent on its own, by preference (`reason: 'muted'`), for want of an address (`'no_address'`),
+ * or because the person takes this topic in a digest (`'digest'`): the occasion is held for
+ * their next one. What becomes of a held occasion is told later, naming this `deliveryId`: the
+ * `notifications.digest-sent` that carried it, the `notifications.preference-set` whose
+ * switch-off withdrew it (its delivery then reads `skipped`/`muted`), or the
+ * `notifications.digest-quarantined` that set it aside unreadable (`skipped`/`quarantined`, until
+ * a `notifications.digest-released` holds it again), or the `notifications.digest-withdrawn` that
+ * withdrew it because the topic was switched off since (`skipped`/`muted`). An erasure of the person
+ * deletes it with no event, like a held send it cancels, and its delivery stays as it was.
+ * `dedupeKey` is the occasion as the caller named it — from a consumer, the triggering event's id.
+ *
+ * A digest is a delivery as well, under the reserved topic `@digest` (no vertical topic can be
+ * spelled that way), with `about: null`.
+ */
+export interface NotificationsDeliveryRecordedPayload {
+    deliveryId: string;
+    topic: string;
+    principal: string;
+    channel: string;
+    status: 'requested' | 'skipped';
+    reason: string | null;
+    request: string | null;
+    dedupeKey: string;
+    about: EntityRef | null;
+}
+/**
+ * What the platform reported back for a `requested` delivery: the provider accepted it
+ * (`sent`), refused it for good (`refused`), or every attempt failed (`dead_lettered`).
+ * `code` is the platform's taxonomy code for a refusal or the last failure; null on `sent`.
+ */
+export interface NotificationsDeliverySettledPayload {
+    deliveryId: string;
+    topic: string;
+    principal: string;
+    channel: string;
+    status: 'sent' | 'refused' | 'dead_lettered';
+    code: string | null;
+    request: string;
+}
+/**
+ * A person switched one topic on or off for one channel, and perhaps chose when it arrives.
+ * A switch-off also withdraws that topic's occasions still held for their digest.
+ */
+export interface NotificationsPreferenceSetPayload {
+    principal: string;
+    topic: string;
+    channel: string;
+    enabled: boolean;
+    /**
+     * When the topic reaches them after the call — always `immediate` for a required topic.
+     * Absent on events written before digests existed.
+     */
+    cadence?: 'immediate' | 'daily-digest';
+    /**
+     * The deliveries of the occasions this switch-off withdrew from the person's digest, each now
+     * `skipped`/`muted`. Absent when it withdrew none.
+     */
+    withdrawn?: string[];
+}
+/** A person set or cleared where their notifications go — whether, never what. */
+export interface NotificationsRecipientUpdatedPayload {
+    principal: string;
+    hasAddress: boolean;
+}
+/** A topic was first used, or its description or `required` changed. Names nobody. */
+export interface NotificationsTopicRecordedPayload {
+    topic: string;
+    description: string;
+    required: boolean;
+}
+/** One occasion a digest carried, named by its own (`skipped`, `digest`) delivery. */
+export interface NotificationsDigestItem {
+    deliveryId: string;
+    topic: string;
+    dedupeKey: string;
+    about: EntityRef | null;
+    queuedAt: string;
+}
+/**
+ * One person's digest was composed from everything held for them: the occasions it carried,
+ * oldest first, and the digest's own delivery (topic `@digest`). `status` is that delivery's:
+ * `requested` with the send intent's `request`, or `skipped` with `reason: 'no_address'` when
+ * the person had cleared their address since. Either way the items are no longer held, and the
+ * digest's delivery settles like any other.
+ */
+export interface NotificationsDigestSentPayload {
+    deliveryId: string;
+    principal: string;
+    channel: string;
+    cadence: 'daily-digest';
+    status: 'requested' | 'skipped';
+    reason: string | null;
+    request: string | null;
+    items: NotificationsDigestItem[];
+}
+/**
+ * A person's digest was due and could not be composed or written — a send or a write that
+ * failed. (A held message that no longer reads is set aside instead; see
+ * `notifications.digest-quarantined`.) Nothing was sent for them and nothing of theirs was let
+ * go: their `items` stay held, and the next attempt is at `retryAt`, a window later. Everyone
+ * else's digest in the same pass went out regardless. `code` is the platform's error code; the
+ * cause itself is on the error line the pass writes, not here.
+ */
+export interface NotificationsDigestFailedPayload {
+    principal: string;
+    channel: string;
+    cadence: 'daily-digest';
+    items: number;
+    code: string;
+    retryAt: string;
+}
+/**
+ * Held occasions of one person's digest no longer read — a stored row that left the shape this
+ * engine publishes — and were set aside rather than mailed or allowed to block the rest. Each is
+ * marked, its delivery reads `skipped` with reason `quarantined`, and the person's readable
+ * messages went out as usual. A set-aside row is read again once a window and released when it
+ * reads (`notifications.digest-released`); this event is written when a row is first set aside,
+ * never again while it stays unreadable. `occasions` names the deliveries whose id still read;
+ * `unidentified` counts the rows whose id did not. Never what a row held.
+ */
+export interface NotificationsDigestQuarantinedPayload {
+    principal: string;
+    channel: string;
+    occasions: string[];
+    unidentified: number;
+}
+/**
+ * Set-aside occasions of one person read again — whatever left them unreadable, a version that
+ * stored a shape this one rejects, say, is gone — and are held for the digest once more: each
+ * delivery reads `skipped`/`digest` again, unsettled, and goes out in the person's next digest.
+ * One whose topic the person has switched off since is not released but withdrawn
+ * (`notifications.digest-withdrawn`).
+ */
+export interface NotificationsDigestReleasedPayload {
+    principal: string;
+    channel: string;
+    occasions: string[];
+}
+/**
+ * Held occasions of one person were withdrawn, unsent, because the person has switched their
+ * topic off since they were held, found when a set-aside row read again or when the digest was
+ * composed. Each delivery reads `skipped`/`muted`. (A switch-off's own withdrawal is named on
+ * `notifications.preference-set`.) A mute always wins over a digest.
+ */
+export interface NotificationsDigestWithdrawnPayload {
+    principal: string;
+    channel: string;
+    occasions: string[];
+}
+export type NotificationsEvents = {
+    events: {
+        'notifications.delivery-recorded': NotificationsDeliveryRecordedPayload;
+        'notifications.delivery-settled': NotificationsDeliverySettledPayload;
+        'notifications.preference-set': NotificationsPreferenceSetPayload;
+        'notifications.recipient-updated': NotificationsRecipientUpdatedPayload;
+        'notifications.topic-recorded': NotificationsTopicRecordedPayload;
+        'notifications.digest-sent': NotificationsDigestSentPayload;
+        'notifications.digest-failed': NotificationsDigestFailedPayload;
+        'notifications.digest-quarantined': NotificationsDigestQuarantinedPayload;
+        'notifications.digest-released': NotificationsDigestReleasedPayload;
+        'notifications.digest-withdrawn': NotificationsDigestWithdrawnPayload;
+    };
+};
+/** Every event type this engine emits. */
+export type NotificationsEventType = keyof NotificationsEvents['events'];
+/** The one home for each event's `schemaVersion` (#1597); `emits` is read off it. */
+export declare const notificationsEventVersions: {
+    readonly 'notifications.delivery-recorded': 1;
+    readonly 'notifications.delivery-settled': 1;
+    readonly 'notifications.preference-set': 1;
+    readonly 'notifications.recipient-updated': 1;
+    readonly 'notifications.topic-recorded': 1;
+    readonly 'notifications.digest-sent': 1;
+    readonly 'notifications.digest-failed': 1;
+    readonly 'notifications.digest-quarantined': 1;
+    readonly 'notifications.digest-released': 1;
+    readonly 'notifications.digest-withdrawn': 1;
+};
+/** The manifest's `events.emits`, read off {@link notificationsEventVersions}. */
+export declare const notificationsEmitDeclarations: {
+    type: string;
+    schemaVersion: number;
+}[];
+/** `ctx.emit` with the event type and its payload welded together, and the version stamped. */
+export declare function emitNotificationsEvent<K extends NotificationsEventType>(ctx: OperationContext, event: Omit<DomainEventInput, 'type' | 'payload' | 'schemaVersion'> & {
+    type: K;
+    payload: NotificationsEvents['events'][K];
+}): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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

package/dist/events.js

@@ -0,0 +1,20 @@
+/** The one home for each event's `schemaVersion` (#1597); `emits` is read off it. */
+export const notificationsEventVersions = {
+    'notifications.delivery-recorded': 1,
+    'notifications.delivery-settled': 1,
+    'notifications.preference-set': 1,
+    'notifications.recipient-updated': 1,
+    'notifications.topic-recorded': 1,
+    'notifications.digest-sent': 1,
+    'notifications.digest-failed': 1,
+    'notifications.digest-quarantined': 1,
+    'notifications.digest-released': 1,
+    'notifications.digest-withdrawn': 1,
+};
+/** The manifest's `events.emits`, read off {@link notificationsEventVersions}. */
+export const notificationsEmitDeclarations = Object.entries(notificationsEventVersions).map(([type, schemaVersion]) => ({ type, schemaVersion }));
+/** `ctx.emit` with the event type and its payload welded together, and the version stamped. */
+export function emitNotificationsEvent(ctx, event) {
+    ctx.emit({ ...event, schemaVersion: notificationsEventVersions[event.type] });
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AA0MA,qFAAqF;AACrF,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,iCAAiC,EAAE,CAAC;IACpC,gCAAgC,EAAE,CAAC;IACnC,8BAA8B,EAAE,CAAC;IACjC,iCAAiC,EAAE,CAAC;IACpC,8BAA8B,EAAE,CAAC;IACjC,2BAA2B,EAAE,CAAC;IAC9B,6BAA6B,EAAE,CAAC;IAChC,kCAAkC,EAAE,CAAC;IACrC,+BAA+B,EAAE,CAAC;IAClC,gCAAgC,EAAE,CAAC;CACsB,CAAC;AAE5D,kFAAkF;AAClF,MAAM,CAAC,MAAM,6BAA6B,GAA8C,MAAM,CAAC,OAAO,CACpG,0BAA0B,CAC3B,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;AAE5D,+FAA+F;AAC/F,MAAM,UAAU,sBAAsB,CACpC,GAAqB,EACrB,KAGC;IAED,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,aAAa,EAAE,0BAA0B,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAChF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,411 @@
+/**
+ * engine-notifications — composed **by call**, not by event.
+ *
+ * The in-scope functions are the surface: `notify`, which turns one occasion into mail to the
+ * people it concerns, and the preference functions behind the operations below. A vertical
+ * decides WHEN to notify — usually in its own consumer of a domain event, e.g. Handlebar's
+ * consumer of `workorder.assigned` — and calls `notify(ctx, …)` there, inside its own
+ * transaction, with the template it owns. The engine owns everything after that call: the
+ * mute and required check, the address, the escaped render, the send intent, and a delivery
+ * row that follows the send to its outcome.
+ *
+ * Placement (K-47): notifications are domain logic over the kernel's primitives, so they are
+ * an engine. The kernel's whole part is the transactional send intent (`requestEmail`, #2102)
+ * and the outcome events its settle writes back; the transport behind that intent is
+ * `adapter-email`. Nothing here reaches a provider.
+ *
+ * The registration is one frozen constant like every other engine's. Its only consumers are the
+ * three email outcome events, which settle the deliveries it wrote; what triggers a notification
+ * is the vertical's code, so nothing about that appears here.
+ *
+ * Digests are the person's choice, per topic: a topic they take as `daily-digest` is held
+ * rather than mailed. The engine's own schedule (`notifications/send-digests`, run by its system
+ * principal every `DIGEST_TICK_MINUTES`) sends each person whose oldest held message is a day old
+ * one mail of up to `DIGEST_MAX_ITEMS` of them, oldest first, through the same send intent and
+ * delivery row as any notification, one person at a time and never more at once than the
+ * scope's send backlog has room for. A mute still wins, and a required topic always goes out at
+ * once.
+ *
+ * Deferred, and stated so an absence reads as intent: channels other than email (SMS, push,
+ * in-app — each a transport and a `notificationChannel` value), tenant-edited or per-locale
+ * templates (a table keyed by topic overriding the template the caller passes, which is also
+ * where a digest's own wording would come from), quiet hours and a digest's time of day, other
+ * digest cadences (today any cadence row holds a topic for the one daily schedule: a second
+ * cadence needs a `digestCadence` value, the cadence recorded on each held item, and a schedule
+ * that sends only its own).
+ */
+import { z } from 'zod';
+import { type Page } from '@substrat-run/contracts';
+import { type ModuleRegistration, type OperationContext, type PageParams } from '@substrat-run/kernel';
+/**
+ * The conflict reasons this engine raises, narrowing the platform's `conflict` code (#113).
+ * Additive only: new reasons may appear, existing ones do not change spelling.
+ */
+export declare const NOTIFICATIONS_CONFLICT_REASONS: readonly ['topic_required'];
+export type NotificationsConflictReason = (typeof NOTIFICATIONS_CONFLICT_REASONS)[number];
+export { notificationsEntities, deliveryRow, myDeliveryRow } from './entities.js';
+import { deliveryRow, myDeliveryRow } from './entities.js';
+export { notificationsOperations, NOTIFICATIONS_PERMISSIONS, notificationCadence, notificationChannel, myPreferences, topicPreference, type NotificationCadence, type NotificationChannel, } from './operations.js';
+import { myPreferences, type NotificationCadence, type NotificationChannel } from './operations.js';
+export { type NotificationsEvents, type NotificationsEventType, type NotificationsDeliveryRecordedPayload, type NotificationsDeliverySettledPayload, type NotificationsDigestFailedPayload, type NotificationsDigestItem, type NotificationsDigestQuarantinedPayload, type NotificationsDigestReleasedPayload, type NotificationsDigestWithdrawnPayload, type NotificationsDigestSentPayload, type NotificationsPreferenceSetPayload, type NotificationsRecipientUpdatedPayload, type NotificationsTopicRecordedPayload, } from './events.js';
+export { type NotificationTemplate } from './render.js';
+export declare const NOTIFICATIONS_PERM: {
+    self: string & z.$brand<"PermissionKey">;
+    read: string & z.$brand<"PermissionKey">;
+    sendDigests: string & z.$brand<"PermissionKey">;
+};
+/**
+ * The topic of a digest's own delivery. A vertical's topic is a lowercase slug, so none can be
+ * spelled this way: filtering the delivery list on it lists digests and nothing else.
+ */
+export declare const DIGEST_TOPIC = "@digest";
+/**
+ * How often the digest schedule looks for people whose digest is due. Each pass is one indexed
+ * query when nobody is; a backlog bigger than one pass's room drains over the next passes.
+ */
+export declare const DIGEST_TICK_MINUTES = 15;
+/**
+ * The pending-send slots a digest pass leaves free, of the scope's
+ * `MAX_PENDING_PLATFORM_REQUESTS`: digests can wait for the drain, and mail that must not —
+ * a required topic above all — is never refused because digests filled the backlog.
+ */
+export declare const DIGEST_RESERVE = 8;
+/**
+ * The most held occasions one digest carries, oldest first. The rest stay held and are due by
+ * the same rule as any — once the oldest of them is a window old — so a person with more held
+ * than this gets several digests rather than one unbounded mail, and a pass reads a bounded
+ * number of rows for each person.
+ */
+export declare const DIGEST_MAX_ITEMS = 50;
+export declare const notificationsManifest: {
+    id: string & z.$brand<"ModuleId">;
+    version: string;
+    kernelContract: string;
+    permissions: {
+        key: string & z.$brand<"PermissionKey">;
+        description: string;
+        holder?: "system" | undefined;
+    }[];
+    events: {
+        emits: {
+            type: string;
+            schemaVersion: number;
+        }[];
+        consumes: {
+            type: string;
+            schemaVersion: number;
+            from?: string | undefined;
+        }[];
+        exports?: {
+            type: string;
+            schemaVersion: number;
+            readPermission: string & z.$brand<"PermissionKey">;
+        }[] | undefined;
+    };
+    migrations: {
+        journalDir: string;
+        compatibleFrom: string;
+    };
+    attachmentTargets: {
+        entityType: string;
+        readPermission: string & z.$brand<"PermissionKey">;
+        writePermission?: (string & z.$brand<"PermissionKey">) | undefined;
+        uploadLinks?: {
+            maxBytes: number;
+            contentTypes?: string[] | undefined;
+        } | undefined;
+    }[];
+    liveTargets?: {
+        entityType: string;
+        readPermission: string & z.$brand<"PermissionKey">;
+    }[] | undefined;
+    entityRelations?: {
+        entityType: string;
+        parentType: string;
+    }[] | undefined;
+    guards?: {
+        before: string;
+        predicate: string;
+        config: Record<string, unknown>;
+    }[] | undefined;
+    schedules?: {
+        operation: string;
+        cadence: {
+            everyMinutes: number;
+        };
+        input?: Record<string, unknown> | undefined;
+        permissions: (string & z.$brand<"PermissionKey">)[];
+        purge?: {
+            entityType: string;
+        } | undefined;
+    }[] | undefined;
+    peers?: {
+        vertical: string;
+        operations: string[];
+        permissions: (string & z.$brand<"PermissionKey">)[];
+    }[] | undefined;
+    connections?: {
+        provider: string;
+        operation: string;
+        permission: string & z.$brand<"PermissionKey">;
+        options?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    freshness?: {
+        eventType: string;
+        within: {
+            hours: number;
+        };
+    }[] | undefined;
+    withdraws?: string[] | undefined;
+    entitlementKey: string;
+    envSpec?: {
+        key: string;
+        label?: string | undefined;
+        description: string;
+        placeholder?: string | undefined;
+        required: boolean;
+        secret: boolean;
+        default?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    ownerGrants?: (string & z.$brand<"PermissionKey">)[] | undefined;
+    entitlements?: string[] | undefined;
+    provides?: string[] | undefined;
+    requires?: string[] | undefined;
+    api?: string | undefined;
+    searchables?: {
+        entityType: string;
+        fields: string[];
+        table?: string | undefined;
+        idColumn?: string | undefined;
+        tokenizer?: "prefix" | "substring" | undefined;
+    }[] | undefined;
+    lists?: {
+        entityType: string;
+        sortable: string[];
+        filterable?: string[] | undefined;
+        table?: string | undefined;
+        idColumn?: string | undefined;
+    }[] | undefined;
+    entityStates?: {
+        archivePermission?: (string & z.$brand<"PermissionKey">) | undefined;
+        trashPermission?: (string & z.$brand<"PermissionKey">) | undefined;
+        purgeAfterDays?: number | undefined;
+        purgeEarly?: boolean | undefined;
+        table?: string | undefined;
+        idColumn?: string | undefined;
+        entityType: string;
+    }[] | undefined;
+    erasure?: {
+        tables: string[];
+        entities: {
+            entityType: string;
+            table: string;
+            mode: "blank" | "custom" | "delete" | "unreached";
+            subjects?: string[] | undefined;
+            fields: {
+                name: string;
+                blank: "" | null;
+            }[];
+        }[];
+    } | undefined;
+    updatedStamps?: {
+        table: string;
+        idColumn: string;
+        at?: string | undefined;
+        by?: string | undefined;
+        entityType: string;
+    }[] | undefined;
+    ui?: {
+        routes?: {
+            path: string;
+            screen: string;
+            permission: string & z.$brand<"PermissionKey">;
+        }[] | undefined;
+        nav?: {
+            label: string;
+            icon?: string | undefined;
+            to: string;
+            permission: string & z.$brand<"PermissionKey">;
+        }[] | undefined;
+        entityViews?: {
+            entityType: string;
+            view: string;
+        }[] | undefined;
+        widgets?: {
+            slot: string;
+            component: string;
+            permission: string & z.$brand<"PermissionKey">;
+        }[] | undefined;
+        settingsPanels?: {
+            label: string;
+            component: string;
+            permission: string & z.$brand<"PermissionKey">;
+        }[] | undefined;
+    } | undefined;
+};
+export declare const notificationsMigrations: {
+    version: string;
+    sql: string;
+}[];
+export declare const notifyInput: z.ZodObject<{
+    topic: z.ZodString;
+    description: z.ZodString;
+    dedupeKey: z.ZodString;
+    recipients: z.ZodArray<z.core.$ZodBranded<z.ZodString, "DataSubjectId", "out">>;
+    vars: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    about: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>>>;
+    template: z.ZodObject<{
+        subject: z.ZodString;
+        text: z.ZodString;
+        html: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    required: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type NotifyInput = z.input<typeof notifyInput>;
+/** What `notify` did for one recipient. */
+export interface NotifyOutcome {
+    principal: string;
+    status: 'requested' | 'skipped';
+    /**
+     * On a skip: `muted`, `no_address`, `duplicate` (this key already reached them), or `digest`
+     * (held for their next digest rather than mailed on its own). Null when requested.
+     */
+    reason: string | null;
+    /** The send intent's id, when one was written. */
+    request: string | null;
+    /** The delivery row, or null on a `duplicate`, which writes none. */
+    deliveryId: string | null;
+}
+/**
+ * Notify `recipients` about one occasion, inside the caller's transaction.
+ *
+ * For each person: a delivery this `dedupeKey` already made for them is left alone; a muted
+ * topic (unless `required`) or a missing address records a `skipped` delivery; a topic they
+ * take as a digest (unless `required`) records a `skipped` delivery with reason `digest` and
+ * holds the rendered message for `sendDigests`; otherwise a send intent is written with
+ * `requestEmail`, naming the person as its `subjectId`, and a `requested` delivery records it.
+ * The platform's outcome event settles that delivery later (the engine's own consumers).
+ *
+ * **It throws `validation_failed`, writing nothing, when the template cannot be filled** — a
+ * placeholder with no variable, or a message every word of which was a blank variable — or a
+ * recipient is not a principal id. That is a defect in the caller, and the throw rolls back the
+ * caller's whole transaction: from a consumer, the event dead-letters in the kernel's delivery
+ * journal with the topic and the reason in its error; from an operation, the operation fails.
+ * A blank mail is never the fallback.
+ *
+ * No permission check: like every by-call engine function, the caller checks first. A consumer
+ * calling it runs under the kernel's consumer authority.
+ */
+export declare function notify(ctx: OperationContext, rawInput: NotifyInput): NotifyOutcome[];
+/** The caller's address and every known topic's switch and cadence. */
+export declare function myPreferencesOf(ctx: OperationContext): z.infer<typeof myPreferences>;
+/** Set or clear where the caller's notifications go. */
+export declare function setMyAddress(ctx: OperationContext, input: {
+    email: string | null;
+}): z.infer<typeof myPreferences>;
+/**
+ * Switch one topic on or off for the caller, and with `cadence`, choose whether it arrives at
+ * once or in their daily digest (absent leaves that as it is). The topic must be one this scope
+ * has used (`not_found` otherwise). A required topic refuses to be switched off, and refuses a
+ * digest: mail a person must not miss does not wait a day either.
+ *
+ * Switching a topic off withdraws its items still held for the caller's digest — a mute wins
+ * over the queue. Each withdrawn occasion's delivery is settled `skipped`/`muted`, as if the mute
+ * had come first, and the event names them. Switching a digest back to `immediate` leaves what is
+ * already held to go out with the next digest.
+ */
+export declare function setMyPreference(ctx: OperationContext, input: {
+    topic: string;
+    channel: NotificationChannel;
+    enabled: boolean;
+    cadence?: NotificationCadence | undefined;
+}): z.infer<typeof myPreferences>;
+/** What became of each notification, newest first. */
+export declare function listDeliveries(ctx: OperationContext, page: PageParams): Page<z.infer<typeof deliveryRow>>;
+/**
+ * What became of each notification sent to the caller, newest first: the same page as
+ * `listDeliveries`, with the `principal` filter pinned to `ctx.principal`, last, so nothing in
+ * `page` can name anyone else.
+ *
+ * Every delivery of theirs is listed, including the ones that were not mailed on their own — a
+ * topic they muted (`skipped`/`muted`), a missing address (`skipped`/`no_address`), an occasion
+ * held for their digest (`skipped`/`digest`, settled once the digest that carried it is
+ * written) — and the digest itself, which is a delivery of its own under `DIGEST_TOPIC`. A held
+ * message set aside as unreadable reads `skipped`/`quarantined` until it is released.
+ *
+ * The row is `myDeliveryRow`, not the administrator's: it names neither the caller's idempotency
+ * key nor the platform's send intent, and a `refused` or `dead_lettered` row carries no `reason`,
+ * since that is the platform's outcome code (a missing sender grant, a provider refusal) and
+ * belongs to whoever reads the whole log. The `reason` of a `skipped` row is the engine's own
+ * word for it.
+ *
+ * No permission check: like every by-call engine function, the caller checks first.
+ */
+export declare function listMyDeliveries(ctx: OperationContext, page: PageParams): Page<z.infer<typeof myDeliveryRow>>;
+/** What one pass of `sendDigests` did. */
+export interface DigestPass {
+    /** People whose digest went out (or was recorded skipped for want of an address). */
+    digests: number;
+    /** The occasions those digests carried. */
+    items: number;
+    /** People whose digest could not be composed: theirs stay held, retried a window later. */
+    failed: number;
+    /** People who were due but left for a later pass, because the scope had no room for more sends. */
+    deferred: number;
+    /** Held occasions found unreadable and set aside this pass, unsent. */
+    quarantined: number;
+    /** Set-aside occasions that read again this pass and are held for the digest once more. */
+    released: number;
+    /** Held occasions withdrawn this pass, unsent, because their person has switched the topic off since. */
+    withdrawn: number;
+}
+/**
+ * Send each person whose digest is due one mail of what is held for them.
+ *
+ * **Who is due.** A person is due once their oldest held message is a whole window old (a day,
+ * for `daily-digest`). So nothing waits much longer than a day, and while no more than
+ * `DIGEST_MAX_ITEMS` are held, a person gets one digest a day: everything held after it is
+ * younger. Oldest first, so a backlog drains in the order it built up. A person whose last
+ * attempt failed waits a window before the next.
+ *
+ * **How many people.** Each mail is a platform send intent, and a scope may hold only
+ * `MAX_PENDING_PLATFORM_REQUESTS` of those waiting for the drain — this transaction's own
+ * included. A pass therefore sends to at most the room that is left, less `DIGEST_RESERVE`
+ * slots kept for mail that must not wait, and leaves everyone else held for the next pass. It
+ * never asks for more room than there is, so it never meets the cap's refusal.
+ *
+ * **How much each.** One digest carries at most `DIGEST_MAX_ITEMS` occasions, oldest first. The
+ * rest stay held, and are due by the same rule: as soon as the oldest of them is a window old —
+ * on the very next pass if it already is. That is the one case where a person gets more than one
+ * digest a day.
+ *
+ * **What does not read.** A held row that no longer matches the published shape is set aside
+ * (`quarantine`) rather than mailed or allowed to block the rest: the person's readable messages
+ * go out, and the set-aside row counts toward nothing — not who is due, not a switch-off's
+ * withdrawal, not the stale-hold warning. Its cause may pass (a version that stored a shape this
+ * one rejects is rolled forward again), so each set-aside row is read again once a window
+ * (`releaseReadable`, at the start of a pass) and held once more when it reads — unless its topic
+ * was switched off meanwhile, when it is withdrawn instead.
+ *
+ * **A mute wins, last of all.** The read that composes a digest carries each row's mute
+ * (`MUTED`), and a held message whose topic is switched off is withdrawn (`withdrawMuted`), never
+ * mailed, whatever path brought it there.
+ *
+ * **One person at a time.** Each person's digest is its own `ctx.atomic`: one mail written with
+ * `requestEmail`, one delivery under `DIGEST_TOPIC`, the carried occasions settled and no longer
+ * held. If any of that throws, none of it happened for that person — their messages stay held,
+ * `notifications.digest-failed` and an error line say so — and everyone else's digest still goes
+ * out. A person who cleared their address since gets a `skipped` (`no_address`) digest, as an
+ * immediate notification would have.
+ *
+ * The engine's schedule runs it through `notifications/send-digests` every
+ * `DIGEST_TICK_MINUTES`; a vertical may also call it, after its own permission check, like every
+ * by-call function here. Either way it is one pass, and it sends only the people who are due.
+ */
+export declare function sendDigests(ctx: OperationContext): Promise<DigestPass>;
+export declare const notificationsModule: ModuleRegistration;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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