@house-rules/notifications 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,21 @@
+# @house-rules/notifications: notes for agents
+
+## Mounting
+
+Use `NotificationsMount` with `Notifications.layerMemory(options)` or `Notifications.layerPostgres(options)` in composition/modules.ts. Provide one matching unit adapter. Postgres needs `SqlClient` and this package's migrations before acquisition. Register `{ "package": "@house-rules/notifications" }` in the app's module list.
+
+## Options and ports
+
+Options declare `recipientKind`, enabled `channels`, `categories` with unique names, default channels and mandatory flags, and `maxPageSize`. `dailyDigestTime` defaults to `08:00`; `maxDueBatch` defaults to 100 complete delivery groups, not rows. Retry options are `maxAttempts` (default 5), `retryBaseMs` (1000) and `retryCapMs` (3600000). `Notifications.presets.default` supplies these limits and all three channels. Add your recipient kind and categories. There is no host port. Person methods accept an explicit Actor and use `{ kind: recipientKind, id: actor.id }`.
+
+## Fixed rules
+
+Only system callers may use notify, dueDeliveries, markSent and markFailed bindings. Other operation bindings require a person. Writes join the feature's unit and never open one. `erase(recipient)` is a facade cascade hook, not an operation.
+
+The module owns inbox rows, preferences, quiet windows and delivery ledger rows. It never sends, emits events, captures CurrentActor or imports event-log. NotificationCreated and NotificationRead schemas are in the contract; writes return their facts alongside notifications.
+
+The inbox row is the in-app delivery. Never create in-app ledger rows. In-app is immediate and cannot be disabled. Mandatory default channels ignore saved off/digest modes and quiet hours. Quiet windows hold push/email until the next real local minute outside the window. Timing uses Intl and the Effect clock. `setMyTimeZone(actor, zone)` stores a person's zone independently of quiet hours; null restores UTC. Quiet hours contain only start/end. Digests and quiet windows use the same person zone.
+
+Preference, quiet-hours and zone writes query only that person's pending/held rows, then refresh non-mandatory external rows in the same unit. Keep retryAt independent of dueAt: recompute quiet-window holds on retry rows, never scheduling before their backoff. Off cancels queued rows without delivery. Sent, cancelled and failed rows stay terminal; mandatory rows are untouched. Digest groups are keyed by recipient, channel and mode. Selection bounds groups and never splits their due rows.
+
+Send schedule items through a separate app system feature and channel plugs. Settle their delivery ids with markSent only after sending. Use ledger ids as provider idempotency keys. markFailed increments attempts and stores the private error. Below maxAttempts it sets retryAt to now + min(retryBaseMs * 2^attempts, retryCapMs). For a non-mandatory external delivery, dueAt is held until quiet hours end when retryAt falls inside the recipient's window and zone; retryAt stays independent of dueAt. At maxAttempts it becomes terminal failed. dueDeliveries does not re-check quiet hours at selection, so a late polling tick can select a row whose scheduled time was before the window. No distributed lease or exactly-once provider guarantee exists.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Szwajka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @house-rules/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.
+An inbox with channel preferences, quiet hours and a delivery ledger. Push and email senders live outside this package.
+
+## Mount
+
+```ts
+const options = {
+  ...Notifications.presets.default,
+  recipientKind: "person",
+  categories: [
+    { name: "news", defaultChannels: ["inapp", "email"], mandatory: false },
+    { name: "security", defaultChannels: ["email", "push"], mandatory: true },
+  ],
+};
+
+// In composition/modules.ts, pair NotificationsMount with this layer.
+const notifications = Notifications.layerPostgres(options);
+```
+
+Provide SqlClient and the SQL unit adapter for Postgres, or use layerMemory and the memory unit adapter. Run the shipped migrations through `@house-rules/migrations`. No contact, party or event-log service is required.
+
+## Operations
+
+Import `NotificationsOperations` and schemas from `@house-rules/notifications/contract`. `NotificationsMount` captures `bindNotifications` once during composition.
+
+| Operation | Caller | Permission | Result |
+| --- | --- | --- | --- |
+| notify | system | notifications:write | `{ notifications, events: NotificationCreated[] }` |
+| listMine | person | notifications:read | `{ notifications, next? }` |
+| unreadCount | person | notifications:read | number |
+| markRead, markAllRead | person | notifications:write | `{ notifications, events: NotificationRead[] }` |
+| getMyPreferences | person | notifications:read | `{ preferences, quietHours, timeZone }` |
+| setMyPreference, setMyQuietHours, setMyTimeZone | person | notifications:write | void |
+| dueDeliveries | system | notifications:deliver | schedule item array |
+| markSent, markFailed | system | notifications:deliver | void |
+
+All writes require the feature's open unit. `notify` takes `{ recipients: [{ kind, id }], category, title, body, data }`. It deduplicates recipients and creates inbox and ledger rows atomically. It returns facts, never publishes them. The app feature decides whether to record these facts through event-log.
+
+Mine operations derive a ref using configured recipientKind and the explicit actor id. They never accept another person's ref. Lists sort newest first with exclusive `(createdAt, id)` cursors and clamp requested size to maxPageSize. Read marks return facts only for rows that changed from unread to read. Missing, already-read and foreign ids return empty results.
+
+`erase(recipient)` removes the inbox, ledger, preferences, time zone and quiet hours in one unit. It is a facade-only account deletion hook.
+
+## Modes and timing
+
+Enabled channels are inapp, push and email. An explicit non-off preference enables a non-default push/email channel; otherwise category defaults select channels. The inbox row is the in-app delivery, so no in-app ledger rows are created. In-app stays immediate. The inbox exists even when all external channels are off.
+
+Mandatory categories force their default channels to immediate even if old stored preferences say off or digest. They ignore quiet hours. The preference setter rejects attempts to delay mandatory categories or disable/delay in-app.
+
+Hourly digests use the next local hour boundary. Daily digests use the next local dailyDigestTime, default 08:00. `setMyTimeZone(actor, timeZone)` stores the person's IANA zone independently of quiet hours. Null clears it and restores UTC. `getMyPreferences` returns the stored zone or null. Digests and quiet hours use that zone. `setMyQuietHours(actor, { start, end })` accepts HH:mm values; null clears the window. Equal endpoints are invalid. A window can cross midnight.
+
+Quiet hours hold external deliveries whose scheduled send falls inside the window. dueAt becomes the end of that window in the person's zone. DST gaps release at the first real minute outside the window. Repeated hours are checked as real instants. All current time reads use Effect's testable clock; Intl handles zone conversion. Changing preferences, quiet hours or time zone refreshes that person's pending/held non-mandatory external rows in the same unit. Refresh queries exclude terminal ledger history. Scheduling starts from the notification's creation time and keeps elapsed digest times due. Each row stores retryAt separately from dueAt, so a changed quiet window can release a retry sooner without shortening its backoff. Switching a channel off cancels its queued rows without delivery. Mandatory and terminal rows are untouched.
+
+## Delivery work
+
+```text
+app system feature -> notify -> inbox + ledger -> returned facts
+schedule selector -> dueDeliveries -> one item per immediate row
+                                   -> one digest per recipient/channel/mode
+schedule item -> channel sender -> markSent(deliveryIds)
+                               -> markFailed(deliveryId, error)
+```
+
+maxDueBatch bounds complete groups, default 100. Each item includes recipient, channel, mode and deliveries with the inbox content and ledger ids. Digest rows group by recipient, channel and mode, so hourly and daily work never mixes. One group's due rows are never split at the limit; a large group can exceed maxDueBatch rows. Immediate rows stay individual items. Sent, failed and cancelled rows are terminal and are not selected; pending and released held rows are. Selection does not re-check quiet hours: a delivery scheduled before a window can be returned during it if the polling tick runs late. Quiet hours govern the scheduled send time, not a later selection time.
+
+markSent is idempotent, including repeated ids, and does not change an already sent row's timestamp or attempts. markFailed increments attempts and keeps the private error in the ledger, without losing the inbox notification. Below maxAttempts (default 5), it sets retryAt = now + min(retryBaseMs * 2^attempts, retryCapMs). Defaults are 1000 ms base and 3600000 ms cap. For a non-mandatory external delivery, if retryAt falls inside quiet hours, dueAt moves to the end of that window in the recipient's time zone. DST gaps and repeated hours use the same real-instant release rule as initial scheduling. Otherwise dueAt equals retryAt. dueDeliveries reselects retries at or after dueAt. At maxAttempts the row becomes terminal failed. Neither settlement method changes terminal rows; a late failure cannot overwrite sent.
+
+Pass each ledger id as a provider idempotency key. Sending then settling is at least once: a crash between them can duplicate a send. There is no distributed lease, and read selection does not claim rows. Event-log outbox wiring and channel consumers belong to the app, so a rolled-back notification never produces committed delivery work.

package/dist/adapters/memory/notification.d.ts

@@ -0,0 +1,3 @@
+import { Layer } from "effect";
+import { NotificationStore } from "../../storage.js";
+export declare const memoryNotificationStore: () => Layer.Layer<NotificationStore>;

package/dist/adapters/memory/notification.js

@@ -0,0 +1,197 @@
+import { UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer } from "effect";
+import { NotificationStoreUnavailable, } from "../../notification/notification.js";
+import { NotificationStore } from "../../storage.js";
+const same = (a, b) => a.kind === b.kind && a.id === b.id;
+const key = (recipient) => JSON.stringify([recipient.kind, recipient.id]);
+export const memoryNotificationStore = () => Layer.sync(NotificationStore, () => {
+    const notifications = new Map();
+    const deliveries = new Map();
+    const preferences = new Map();
+    const quiet = new Map();
+    const timeZones = new Map();
+    const change = Effect.fn("NotificationStore.memory.change")(function* (run) {
+        yield* UnitOfWork.required;
+        const snapshots = [
+            new Map(notifications),
+            new Map(deliveries),
+            new Map(preferences),
+            new Map(quiet),
+            new Map(timeZones),
+        ];
+        yield* UnitOfWork.onRollback(Effect.sync(() => {
+            notifications.clear();
+            for (const [id, row] of snapshots[0])
+                notifications.set(id, row);
+            deliveries.clear();
+            for (const [id, row] of snapshots[1])
+                deliveries.set(id, row);
+            preferences.clear();
+            for (const [id, rows] of snapshots[2])
+                preferences.set(id, rows);
+            quiet.clear();
+            for (const [id, row] of snapshots[3])
+                quiet.set(id, row);
+            timeZones.clear();
+            for (const [id, row] of snapshots[4])
+                timeZones.set(id, row);
+        }));
+        run();
+    });
+    return NotificationStore.of({
+        insert: Effect.fn("NotificationStore.memory.insert")(function* (notification, rows) {
+            yield* UnitOfWork.required;
+            const naturalKeys = rows.map((row) => JSON.stringify([row.notificationId, row.channel, key(row.recipient)]));
+            if (notifications.has(notification.id) ||
+                new Set(rows.map((row) => row.id)).size !== rows.length ||
+                new Set(naturalKeys).size !== rows.length ||
+                rows.some((row) => deliveries.has(row.id) ||
+                    row.notificationId !== notification.id ||
+                    !same(row.recipient, notification.recipient)))
+                return yield* new NotificationStoreUnavailable({
+                    cause: "Duplicate or inconsistent notification delivery.",
+                });
+            yield* change(() => {
+                notifications.set(notification.id, structuredClone(notification));
+                for (const row of rows)
+                    deliveries.set(row.id, structuredClone(row));
+            });
+        }),
+        list: (recipient, page) => Effect.sync(() => [...notifications.values()]
+            .filter((row) => same(row.recipient, recipient) &&
+            (page.after === undefined ||
+                row.createdAt < page.after.createdAt ||
+                (row.createdAt === page.after.createdAt && row.id < page.after.id)))
+            .sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? 1 : a.id === b.id ? 0 : -1))
+            .slice(0, page.size)
+            .map((row) => structuredClone(row))),
+        unreadCount: (recipient) => Effect.sync(() => [...notifications.values()].filter((row) => same(row.recipient, recipient) && row.readAt === null).length),
+        markRead: Effect.fn("NotificationStore.memory.markRead")(function* (recipient, at, id) {
+            const changed = [];
+            yield* change(() => {
+                for (const [rowId, row] of notifications)
+                    if (same(row.recipient, recipient) &&
+                        row.readAt === null &&
+                        (id === undefined || rowId === id)) {
+                        const next = { ...row, readAt: at };
+                        notifications.set(rowId, next);
+                        changed.push(structuredClone(next));
+                    }
+            });
+            return changed.sort((a, b) => (a.id < b.id ? -1 : a.id === b.id ? 0 : 1));
+        }),
+        preferences: (recipient) => Effect.sync(() => structuredClone(preferences.get(key(recipient)) ?? [])),
+        setPreference: (recipient, preference) => change(() => {
+            const entries = preferences.get(key(recipient)) ?? [];
+            preferences.set(key(recipient), [
+                ...entries.filter((row) => row.category !== preference.category || row.channel !== preference.channel),
+                structuredClone(preference),
+            ]);
+        }),
+        quietHours: (recipient) => Effect.sync(() => structuredClone(quiet.get(key(recipient)) ?? null)),
+        setQuietHours: (recipient, hours) => change(() => {
+            if (hours === null)
+                quiet.delete(key(recipient));
+            else
+                quiet.set(key(recipient), structuredClone(hours));
+        }),
+        timeZone: (recipient) => Effect.sync(() => timeZones.get(key(recipient)) ?? null),
+        setTimeZone: (recipient, timeZone) => change(() => {
+            if (timeZone === null)
+                timeZones.delete(key(recipient));
+            else
+                timeZones.set(key(recipient), timeZone);
+        }),
+        deliveries: (recipient, query) => Effect.sync(() => [...deliveries.values()]
+            .filter((row) => same(row.recipient, recipient) &&
+            (!query?.unsettledOnly || row.state === "pending" || row.state === "held"))
+            .sort((a, b) => (a.id < b.id ? -1 : a.id === b.id ? 0 : 1))
+            .flatMap((delivery) => {
+            const notification = notifications.get(delivery.notificationId);
+            return notification === undefined
+                ? []
+                : [structuredClone({ delivery, notification })];
+        })),
+        delivery: (id) => Effect.sync(() => {
+            const delivery = deliveries.get(id);
+            const notification = delivery === undefined ? undefined : notifications.get(delivery.notificationId);
+            return delivery === undefined || notification === undefined
+                ? null
+                : structuredClone({ delivery, notification });
+        }),
+        reschedule: (id, schedule) => change(() => {
+            const row = deliveries.get(id);
+            if (row !== undefined && (row.state === "pending" || row.state === "held"))
+                deliveries.set(id, {
+                    ...row,
+                    mode: schedule.mode,
+                    state: schedule.state,
+                    dueAt: schedule.dueAt,
+                });
+        }),
+        due: (at, limit) => Effect.sync(() => {
+            const rows = [...deliveries.values()]
+                .filter((row) => (row.state === "pending" || row.state === "held") && row.dueAt <= at)
+                .sort((a, b) => a.dueAt - b.dueAt || (a.id < b.id ? -1 : a.id === b.id ? 0 : 1));
+            const groups = new Set();
+            return rows
+                .filter((row) => {
+                const group = row.mode === "immediate"
+                    ? row.id
+                    : JSON.stringify([key(row.recipient), row.channel, row.mode]);
+                if (!groups.has(group) && groups.size >= limit)
+                    return false;
+                groups.add(group);
+                return true;
+            })
+                .flatMap((delivery) => {
+                const notification = notifications.get(delivery.notificationId);
+                return notification === undefined
+                    ? []
+                    : [structuredClone({ delivery, notification })];
+            });
+        }),
+        markSent: (ids, at) => change(() => {
+            for (const id of new Set(ids)) {
+                const row = deliveries.get(id);
+                if (row !== undefined &&
+                    row.state !== "sent" &&
+                    row.state !== "failed" &&
+                    row.state !== "cancelled")
+                    deliveries.set(id, {
+                        ...row,
+                        state: "sent",
+                        sentAt: at,
+                        attempts: row.attempts + 1,
+                        lastError: null,
+                    });
+            }
+        }),
+        markFailed: (id, error, at, retry) => change(() => {
+            const row = deliveries.get(id);
+            if (row !== undefined && (row.state === "pending" || row.state === "held")) {
+                const attempts = row.attempts + 1;
+                const retryAt = at + Math.min(retry.baseMs * 2 ** attempts, retry.capMs);
+                deliveries.set(id, {
+                    ...row,
+                    state: attempts >= retry.maxAttempts ? "failed" : "pending",
+                    dueAt: attempts >= retry.maxAttempts ? row.dueAt : retryAt,
+                    retryAt: attempts >= retry.maxAttempts ? row.retryAt : retryAt,
+                    attempts,
+                    lastError: error,
+                });
+            }
+        }),
+        erase: (recipient) => change(() => {
+            for (const [id, row] of deliveries)
+                if (same(row.recipient, recipient))
+                    deliveries.delete(id);
+            for (const [id, row] of notifications)
+                if (same(row.recipient, recipient))
+                    notifications.delete(id);
+            preferences.delete(key(recipient));
+            quiet.delete(key(recipient));
+            timeZones.delete(key(recipient));
+        }),
+    });
+});

package/dist/adapters/postgres/notification.d.ts

@@ -0,0 +1,4 @@
+import { Layer } from "effect";
+import { SqlClient } from "effect/sql/SqlClient";
+import { NotificationStore } from "../../storage.js";
+export declare const postgresNotificationStore: Layer.Layer<NotificationStore, never, SqlClient>;

package/dist/adapters/postgres/notification.js

@@ -0,0 +1,75 @@
+import { UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer, Schema } from "effect";
+import { SqlClient } from "effect/sql/SqlClient";
+import { DeliveryItem, Notification, NotificationStoreUnavailable, Preference, QuietHours, TimeZone, } from "../../notification/notification.js";
+import { NotificationStore } from "../../storage.js";
+const unavailable = (cause) => new NotificationStoreUnavailable({ cause });
+export const postgresNotificationStore = Layer.effect(NotificationStore, Effect.gen(function* () {
+    const sql = yield* SqlClient;
+    const columns = sql.literal(`id, json_build_object('kind', recipient_kind, 'id', recipient_id) as recipient, category, title, body, data, created_at::float8 as "createdAt", read_at::float8 as "readAt"`);
+    const deliveryColumns = sql.literal(`json_build_object('id', d.id, 'notificationId', d.notification_id, 'recipient', json_build_object('kind', d.recipient_kind, 'id', d.recipient_id), 'channel', d.channel, 'mode', d.mode, 'state', d.state, 'dueAt', d.due_at::float8, 'retryAt', d.retry_at::float8, 'sentAt', d.sent_at::float8, 'attempts', d.attempts, 'lastError', d.last_error) as delivery, json_build_object('id', n.id, 'recipient', json_build_object('kind', n.recipient_kind, 'id', n.recipient_id), 'category', n.category, 'title', n.title, 'body', n.body, 'data', n.data, 'createdAt', n.created_at::float8, 'readAt', n.read_at::float8) as notification`);
+    const read = (schema, query) => query.pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(schema))), Effect.mapError(unavailable));
+    const write = Effect.fn("NotificationStore.postgres.write")(function* (query) {
+        yield* UnitOfWork.required;
+        yield* query.pipe(Effect.mapError(unavailable));
+    });
+    return NotificationStore.of({
+        insert: Effect.fn("NotificationStore.postgres.insert")(function* (notification, deliveries) {
+            yield* write(sql `insert into notifications (id, recipient_kind, recipient_id, category, title, body, data, created_at, read_at) values (${notification.id}, ${notification.recipient.kind}, ${notification.recipient.id}, ${notification.category}, ${notification.title}, ${notification.body}, ${JSON.stringify(notification.data)}::jsonb, ${notification.createdAt}, ${notification.readAt})`);
+            for (const row of deliveries)
+                yield* write(sql `insert into notification_deliveries (id, notification_id, recipient_kind, recipient_id, channel, mode, state, due_at, retry_at, sent_at, attempts, last_error) values (${row.id}, ${row.notificationId}, ${row.recipient.kind}, ${row.recipient.id}, ${row.channel}, ${row.mode}, ${row.state}, ${row.dueAt}, ${row.retryAt}, ${row.sentAt}, ${row.attempts}, ${row.lastError})`);
+        }),
+        list: (recipient, page) => read(Notification, page.after === undefined
+            ? sql `select ${columns} from notifications where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id} order by created_at desc, id collate "C" desc limit ${page.size}`
+            : sql `select ${columns} from notifications where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id} and (created_at, id collate "C") < (${page.after.createdAt}, ${page.after.id}) order by created_at desc, id collate "C" desc limit ${page.size}`),
+        unreadCount: (recipient) => read(Schema.Struct({ count: Schema.Int }), sql `select count(*)::int as count from notifications where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id} and read_at is null`).pipe(Effect.map((rows) => rows[0]?.count ?? 0)),
+        markRead: Effect.fn("NotificationStore.postgres.markRead")(function* (recipient, at, id) {
+            yield* UnitOfWork.required;
+            const rows = yield* read(Notification, id === undefined
+                ? sql `update notifications set read_at = ${at} where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id} and read_at is null returning ${columns}`
+                : sql `update notifications set read_at = ${at} where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id} and id = ${id} and read_at is null returning ${columns}`);
+            return [...rows].sort((a, b) => (a.id < b.id ? -1 : a.id === b.id ? 0 : 1));
+        }),
+        preferences: (recipient) => read(Preference, sql `select category, channel, mode from notification_preferences where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id} order by category collate "C", channel collate "C"`),
+        setPreference: (recipient, preference) => write(sql `insert into notification_preferences (recipient_kind, recipient_id, category, channel, mode) values (${recipient.kind}, ${recipient.id}, ${preference.category}, ${preference.channel}, ${preference.mode}) on conflict (recipient_kind, recipient_id, category, channel) do update set mode = excluded.mode`),
+        quietHours: (recipient) => read(QuietHours, sql `select start_time as start, end_time as end from notification_quiet_hours where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`).pipe(Effect.map((rows) => rows[0] ?? null)),
+        setQuietHours: (recipient, hours) => write(hours === null
+            ? sql `delete from notification_quiet_hours where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`
+            : sql `insert into notification_quiet_hours (recipient_kind, recipient_id, start_time, end_time) values (${recipient.kind}, ${recipient.id}, ${hours.start}, ${hours.end}) on conflict (recipient_kind, recipient_id) do update set start_time = excluded.start_time, end_time = excluded.end_time`),
+        timeZone: (recipient) => read(Schema.Struct({ timeZone: TimeZone }), sql `select time_zone as "timeZone" from notification_time_zones where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`).pipe(Effect.map((rows) => rows[0]?.timeZone ?? null)),
+        setTimeZone: (recipient, timeZone) => write(timeZone === null
+            ? sql `delete from notification_time_zones where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`
+            : sql `insert into notification_time_zones (recipient_kind, recipient_id, time_zone) values (${recipient.kind}, ${recipient.id}, ${timeZone}) on conflict (recipient_kind, recipient_id) do update set time_zone = excluded.time_zone`),
+        deliveries: (recipient, query) => read(DeliveryItem, sql `select ${deliveryColumns} from notification_deliveries d join notifications n on n.id = d.notification_id where d.recipient_kind = ${recipient.kind} and d.recipient_id = ${recipient.id} ${query?.unsettledOnly ? sql `and d.state in ('pending', 'held')` : sql ``} order by d.id collate "C"`),
+        delivery: (id) => read(DeliveryItem, sql `select ${deliveryColumns} from notification_deliveries d join notifications n on n.id = d.notification_id where d.id = ${id}`).pipe(Effect.map((rows) => rows[0] ?? null)),
+        reschedule: (id, schedule) => write(sql `update notification_deliveries set mode = ${schedule.mode}, state = ${schedule.state}, due_at = ${schedule.dueAt} where id = ${id} and state in ('pending', 'held')`),
+        due: (at, limit) => read(DeliveryItem, sql `with eligible as (
+              select *, case when mode = 'immediate' then jsonb_build_array(id)
+                else jsonb_build_array(recipient_kind, recipient_id, channel, mode) end as group_key
+              from notification_deliveries where state in ('pending', 'held') and due_at <= ${at}
+            ), selected as (
+              select group_key from eligible group by group_key
+              order by min(due_at), min(id collate "C") limit ${limit}
+            ) select ${deliveryColumns} from eligible d join selected s on s.group_key = d.group_key
+              join notifications n on n.id = d.notification_id order by d.due_at, d.id collate "C"`),
+        markSent: Effect.fn("NotificationStore.postgres.markSent")(function* (ids, at) {
+            yield* UnitOfWork.required;
+            for (const id of new Set(ids))
+                yield* write(sql `update notification_deliveries set state = 'sent', sent_at = ${at}, attempts = attempts + 1, last_error = null where id = ${id} and state <> 'sent' and state not in ('failed', 'cancelled')`);
+        }),
+        markFailed: (id, error, at, retry) => write(sql `update notification_deliveries set
+              state = case when attempts + 1 >= ${retry.maxAttempts} then 'failed' else 'pending' end,
+              due_at = case when attempts + 1 >= ${retry.maxAttempts} then due_at
+                else ${at}::bigint + least(${retry.baseMs}::numeric * power(2::numeric, attempts + 1), ${retry.capMs}::numeric)::bigint end,
+              retry_at = case when attempts + 1 >= ${retry.maxAttempts} then retry_at
+                else ${at}::bigint + least(${retry.baseMs}::numeric * power(2::numeric, attempts + 1), ${retry.capMs}::numeric)::bigint end,
+              attempts = attempts + 1, last_error = ${error}
+              where id = ${id} and state in ('pending', 'held')`),
+        erase: Effect.fn("NotificationStore.postgres.erase")(function* (recipient) {
+            yield* write(sql `delete from notifications where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`);
+            yield* write(sql `delete from notification_preferences where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`);
+            yield* write(sql `delete from notification_quiet_hours where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`);
+            yield* write(sql `delete from notification_time_zones where recipient_kind = ${recipient.kind} and recipient_id = ${recipient.id}`);
+        }),
+    });
+}));

package/dist/contract.d.ts

@@ -0,0 +1,22 @@
+export { NotificationsOperations } from "./notification/operations.js";
+export { type NotificationPermission, NotificationPermissions, } from "./notification/permissions.js";
+export { Channel, Delivery, DeliveryItem, DeliveryMode, DueDelivery, LocalTime, MyPreferences, Notification, NotificationCreated, NotificationCursor, NotificationForbidden, NotificationInputInvalid, NotificationList, NotificationNotFound, NotificationPage, NotificationRead, NotificationStoreUnavailable, NotifyInput, NotifyResult, Preference, QuietHours, ReadResult, Recipient, TimeZone, } from "./notification/notification.js";
+export declare const NotificationEvents: {
+    readonly NotificationCreated: import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"NotificationCreated">;
+        readonly notificationId: import("effect/Schema").NonEmptyString;
+        readonly recipient: import("effect/Schema").Struct<{
+            readonly kind: import("effect/Schema").NonEmptyString;
+            readonly id: import("effect/Schema").NonEmptyString;
+        }>;
+        readonly channels: import("effect/Schema").$Array<import("effect/Schema").Literals<readonly ["inapp", "push", "email"]>>;
+    }>;
+    readonly NotificationRead: import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"NotificationRead">;
+        readonly notificationId: import("effect/Schema").NonEmptyString;
+        readonly recipient: import("effect/Schema").Struct<{
+            readonly kind: import("effect/Schema").NonEmptyString;
+            readonly id: import("effect/Schema").NonEmptyString;
+        }>;
+    }>;
+};

package/dist/contract.js

@@ -0,0 +1,5 @@
+export { NotificationsOperations } from "./notification/operations.js";
+export { NotificationPermissions, } from "./notification/permissions.js";
+export { Channel, Delivery, DeliveryItem, DeliveryMode, DueDelivery, LocalTime, MyPreferences, Notification, NotificationCreated, NotificationCursor, NotificationForbidden, NotificationInputInvalid, NotificationList, NotificationNotFound, NotificationPage, NotificationRead, NotificationStoreUnavailable, NotifyInput, NotifyResult, Preference, QuietHours, ReadResult, Recipient, TimeZone, } from "./notification/notification.js";
+import { NotificationCreated, NotificationRead } from "./notification/notification.js";
+export const NotificationEvents = { NotificationCreated, NotificationRead };