@house-rules/notifications 0.1.0 → 0.1.1

package/AGENTS.md

@@ -18,4 +18,4 @@ The inbox row is the in-app delivery. Never create in-app ledger rows. In-app is
 
 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 returns the row to pending at now + min(retryBaseMs * 2^attempts, retryCapMs). At maxAttempts it becomes terminal failed. dueDeliveries reselects pending retries after backoff. No distributed lease or exactly-once provider guarantee exists.
+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/README.md

@@ -61,8 +61,8 @@ 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.
+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 pending with dueAt = now + min(retryBaseMs * 2^attempts, retryCapMs). Defaults are 1000 ms base and 3600000 ms cap. dueDeliveries reselects retries after backoff. At maxAttempts the row becomes terminal failed. Neither settlement method changes terminal rows; a late failure cannot overwrite sent.
+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.js

@@ -112,6 +112,13 @@ export const memoryNotificationStore = () => Layer.sync(NotificationStore, () =>
                 ? []
                 : [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"))

package/dist/adapters/postgres/notification.js

@@ -41,6 +41,7 @@ export const postgresNotificationStore = Layer.effect(NotificationStore, Effect.
             ? 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)

package/dist/notification/notifications.js

@@ -210,11 +210,28 @@ export const makeNotifications = (store, options) => {
             yield* UnitOfWork.required;
             const id = yield* decode(Schema.NonEmptyString)(deliveryId);
             const detail = yield* decode(Schema.String)(error);
-            yield* store.markFailed(id, detail, yield* now, {
+            const at = yield* now;
+            const retry = {
                 maxAttempts: options.maxAttempts ?? 5,
                 baseMs: options.retryBaseMs ?? 1000,
                 capMs: options.retryCapMs ?? 3_600_000,
-            });
+            };
+            yield* store.markFailed(id, detail, at, retry);
+            const item = yield* store.delivery(id);
+            if (item === null || item.delivery.state !== "pending")
+                return;
+            if (item.delivery.channel === "inapp")
+                return;
+            const category = categoryOf(item.notification.category);
+            if (category === undefined || category.mandatory)
+                return;
+            const hours = yield* store.quietHours(item.delivery.recipient);
+            if (hours === null)
+                return;
+            const retryAt = item.delivery.retryAt ?? at;
+            const dueAt = releaseAt(retryAt, hours, (yield* store.timeZone(item.delivery.recipient)) ?? "UTC");
+            if (dueAt > retryAt)
+                yield* store.reschedule(item.delivery.id, { ...item.delivery, state: "held", dueAt });
         }),
         erase: Effect.fn("Notifications.erase")(function* (recipient) {
             yield* UnitOfWork.required;

package/dist/storage.d.ts

@@ -20,6 +20,7 @@ declare const NotificationStore_base: Context.ServiceClass<NotificationStore, "@
     readonly deliveries: (recipient: Recipient, query?: {
         readonly unsettledOnly: boolean;
     }) => Read<readonly DeliveryItem[]>;
+    readonly delivery: (id: string) => Read<DeliveryItem | null>;
     readonly reschedule: (id: string, schedule: Pick<Delivery, "mode" | "state" | "dueAt">) => Write;
     readonly due: (at: number, limit: number) => Read<readonly DeliveryItem[]>;
     readonly markSent: (ids: readonly string[], at: number) => Write;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house-rules/notifications",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Inbox, channel preferences, quiet hours and a delivery ledger.",
   "license": "MIT",
   "type": "module",
@@ -36,8 +36,8 @@
     "migrations": "migrations"
   },
   "peerDependencies": {
-    "@house-rules/application": "0.2.0",
-    "@house-rules/domain": "0.2.0",
+    "@house-rules/application": "0.3.0",
+    "@house-rules/domain": "0.2.1",
     "effect": "4.0.3"
   },
   "devDependencies": {
@@ -45,9 +45,9 @@
     "@effect/platform-node-shared": "4.0.3",
     "@effect/sql-pg": "4.0.3",
     "@effect/vitest": "4.0.3",
-    "@house-rules/application": "0.2.0",
-    "@house-rules/domain": "0.2.0",
-    "@house-rules/migrations": "0.4.0",
+    "@house-rules/application": "0.3.0",
+    "@house-rules/domain": "0.2.1",
+    "@house-rules/migrations": "0.4.1",
     "effect": "4.0.3",
     "typescript": "7.0.2",
     "vitest": "5.0.1"