@house-rules/notifications 0.0.0-stage → 0.1.1

package/dist/notification/operations.js

@@ -0,0 +1,119 @@
+import { defineOperation, NoInput } from "@house-rules/domain/contract";
+import { Schema } from "effect";
+import { DueDelivery, MyPreferences, NotificationForbidden, NotificationInputInvalid, NotificationList, NotificationPage, NotificationStoreUnavailable, NotifyInput, NotifyResult, Preference, QuietHours, ReadResult, TimeZone, } from "./notification.js";
+import { NotificationPermissions } from "./permissions.js";
+const failure = Schema.Union([
+    NotificationForbidden,
+    NotificationInputInvalid,
+    NotificationStoreUnavailable,
+]);
+const notify = defineOperation("Notifications.notify", {
+    description: "Create inbox notifications and channel ledger rows for app-selected recipients. System callers only.",
+    input: NotifyInput,
+    output: NotifyResult,
+    failure,
+    permission: NotificationPermissions.write,
+    transactional: true,
+});
+const listMine = defineOperation("Notifications.listMine", {
+    description: "Read the caller's inbox, newest first.",
+    input: Schema.Struct({ page: Schema.optionalKey(NotificationPage) }),
+    output: NotificationList,
+    failure,
+    permission: NotificationPermissions.read,
+    readOnly: true,
+});
+const unreadCount = defineOperation("Notifications.unreadCount", {
+    description: "Count the caller's unread notifications.",
+    input: NoInput,
+    output: Schema.Int,
+    failure,
+    permission: NotificationPermissions.read,
+    readOnly: true,
+});
+const markRead = defineOperation("Notifications.markRead", {
+    description: "Mark one owned notification read and return its event fact once.",
+    input: Schema.Struct({ notificationId: Schema.NonEmptyString }),
+    output: ReadResult,
+    failure,
+    permission: NotificationPermissions.write,
+    transactional: true,
+});
+const markAllRead = defineOperation("Notifications.markAllRead", {
+    description: "Mark the caller's unread inbox read and return event facts.",
+    input: NoInput,
+    output: ReadResult,
+    failure,
+    permission: NotificationPermissions.write,
+    transactional: true,
+});
+const getMyPreferences = defineOperation("Notifications.getMyPreferences", {
+    description: "Read effective channel preferences, time zone and quiet hours for the caller.",
+    input: NoInput,
+    output: MyPreferences,
+    failure,
+    permission: NotificationPermissions.read,
+    readOnly: true,
+});
+const setMyPreference = defineOperation("Notifications.setMyPreference", {
+    description: "Set a caller-owned category and channel preference.",
+    input: Preference,
+    output: Schema.Void,
+    failure,
+    permission: NotificationPermissions.write,
+    transactional: true,
+});
+const setMyQuietHours = defineOperation("Notifications.setMyQuietHours", {
+    description: "Set or clear the caller's local quiet window and refresh queued deliveries.",
+    input: Schema.Struct({ quietHours: Schema.NullOr(QuietHours) }),
+    output: Schema.Void,
+    failure,
+    permission: NotificationPermissions.write,
+    transactional: true,
+});
+const setMyTimeZone = defineOperation("Notifications.setMyTimeZone", {
+    description: "Set or clear the caller's IANA time zone and refresh queued deliveries.",
+    input: Schema.Struct({ timeZone: Schema.NullOr(TimeZone) }),
+    output: Schema.Void,
+    failure,
+    permission: NotificationPermissions.write,
+    transactional: true,
+});
+const dueDeliveries = defineOperation("Notifications.dueDeliveries", {
+    description: "Select bounded complete due groups by recipient, channel and mode. System callers only.",
+    input: NoInput,
+    output: Schema.Array(DueDelivery),
+    failure,
+    permission: NotificationPermissions.deliver,
+    readOnly: true,
+});
+const markSent = defineOperation("Notifications.markSent", {
+    description: "Settle sent ledger rows idempotently. System callers only.",
+    input: Schema.Struct({ deliveryIds: Schema.Array(Schema.NonEmptyString) }),
+    output: Schema.Void,
+    failure,
+    permission: NotificationPermissions.deliver,
+    transactional: true,
+});
+const markFailed = defineOperation("Notifications.markFailed", {
+    description: "Record a failed send without changing the inbox. System callers only.",
+    input: Schema.Struct({ deliveryId: Schema.NonEmptyString, error: Schema.String }),
+    output: Schema.Void,
+    failure,
+    permission: NotificationPermissions.deliver,
+    transactional: true,
+});
+export const NotificationsOperations = {
+    notify,
+    listMine,
+    unreadCount,
+    markRead,
+    markAllRead,
+    getMyPreferences,
+    setMyPreference,
+    setMyQuietHours,
+    setMyTimeZone,
+    dueDeliveries,
+    markSent,
+    markFailed,
+};

package/dist/notification/options.d.ts

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+export declare const NotificationCategory: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly defaultChannels: Schema.$Array<Schema.Literals<readonly ["inapp", "push", "email"]>>;
+    readonly mandatory: Schema.Boolean;
+}>;
+export type NotificationCategory = typeof NotificationCategory.Type;
+export declare const NotificationsOptions: Schema.Struct<{
+    readonly recipientKind: Schema.NonEmptyString;
+    readonly channels: Schema.$Array<Schema.Literals<readonly ["inapp", "push", "email"]>>;
+    readonly categories: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.NonEmptyString;
+        readonly defaultChannels: Schema.$Array<Schema.Literals<readonly ["inapp", "push", "email"]>>;
+        readonly mandatory: Schema.Boolean;
+    }>>;
+    readonly dailyDigestTime: Schema.optionalKey<Schema.String>;
+    readonly maxPageSize: Schema.Int;
+    readonly maxDueBatch: Schema.optionalKey<Schema.Int>;
+    readonly maxAttempts: Schema.optionalKey<Schema.Int>;
+    readonly retryBaseMs: Schema.optionalKey<Schema.Int>;
+    readonly retryCapMs: Schema.optionalKey<Schema.Int>;
+}>;
+export type NotificationsOptions = typeof NotificationsOptions.Type;

package/dist/notification/options.js

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+import { Channel, LocalTime } from "./notification.js";
+const positive = Schema.Int.check(Schema.isGreaterThan(0));
+export const NotificationCategory = Schema.Struct({
+    name: Schema.NonEmptyString,
+    defaultChannels: Schema.Array(Channel),
+    mandatory: Schema.Boolean,
+});
+export const NotificationsOptions = Schema.Struct({
+    recipientKind: Schema.NonEmptyString,
+    channels: Schema.Array(Channel).check(Schema.isMinLength(1)),
+    categories: Schema.Array(NotificationCategory).check(Schema.isMinLength(1)),
+    dailyDigestTime: Schema.optionalKey(LocalTime),
+    maxPageSize: positive,
+    maxDueBatch: Schema.optionalKey(positive),
+    maxAttempts: Schema.optionalKey(positive),
+    retryBaseMs: Schema.optionalKey(positive),
+    retryCapMs: Schema.optionalKey(positive),
+}).check(Schema.makeFilter((options) => new Set(options.channels).size === options.channels.length &&
+    new Set(options.categories.map((category) => category.name)).size ===
+        options.categories.length &&
+    options.categories.every((category) => new Set(category.defaultChannels).size === category.defaultChannels.length &&
+        category.defaultChannels.every((channel) => options.channels.includes(channel)))));

package/dist/notification/permissions.d.ts

@@ -0,0 +1,6 @@
+export declare const NotificationPermissions: {
+    readonly read: "notifications:read";
+    readonly write: "notifications:write";
+    readonly deliver: "notifications:deliver";
+};
+export type NotificationPermission = (typeof NotificationPermissions)[keyof typeof NotificationPermissions];

package/dist/notification/permissions.js

@@ -0,0 +1,5 @@
+export const NotificationPermissions = {
+    read: "notifications:read",
+    write: "notifications:write",
+    deliver: "notifications:deliver",
+};

package/dist/notification/timing.d.ts

@@ -0,0 +1,4 @@
+import type { Delivery, QuietHours } from "./notification.js";
+export declare const isQuiet: (instant: number, hours: QuietHours, timeZone: string) => boolean;
+export declare const releaseAt: (instant: number, hours: QuietHours, timeZone: string) => number;
+export declare const digestAt: (instant: number, mode: Delivery["mode"], zone: string, dailyTime: string) => number;

package/dist/notification/timing.js

@@ -0,0 +1,54 @@
+const minute = 60_000;
+const formatter = (timeZone) => new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+});
+const local = (format, instant) => {
+    const parts = format.formatToParts(instant);
+    const part = (name) => parts.find((p) => p.type === name)?.value ?? "";
+    return {
+        date: `${part("year")}-${part("month")}-${part("day")}`,
+        time: `${part("hour")}:${part("minute")}`,
+    };
+};
+export const isQuiet = (instant, hours, timeZone) => {
+    const { time } = local(formatter(timeZone), instant);
+    return hours.start < hours.end
+        ? time >= hours.start && time < hours.end
+        : time >= hours.start || time < hours.end;
+};
+export const releaseAt = (instant, hours, timeZone) => {
+    if (!isQuiet(instant, hours, timeZone))
+        return instant;
+    const format = formatter(timeZone);
+    // Walk real minutes so skipped and repeated DST hours cannot invent an instant.
+    for (let next = Math.floor(instant / minute) * minute + minute; next <= instant + 49 * 60 * minute; next += minute) {
+        const { time } = local(format, next);
+        const quiet = hours.start < hours.end
+            ? time >= hours.start && time < hours.end
+            : time >= hours.start || time < hours.end;
+        if (!quiet)
+            return next;
+    }
+    return instant + 49 * 60 * minute;
+};
+export const digestAt = (instant, mode, zone, dailyTime) => {
+    if (mode === "immediate")
+        return instant;
+    const format = formatter(zone);
+    const current = local(format, instant);
+    const sameDay = current.time < dailyTime;
+    for (let next = Math.floor(instant / minute) * minute + minute; next <= instant + 49 * 60 * minute; next += minute) {
+        const candidate = local(format, next);
+        if (mode === "hourly"
+            ? candidate.time.endsWith(":00")
+            : (sameDay || candidate.date > current.date) && candidate.time >= dailyTime)
+            return next;
+    }
+    return instant + 49 * 60 * minute;
+};

package/dist/storage.d.ts

@@ -0,0 +1,36 @@
+import type { NoOpenUnit } from "@house-rules/domain";
+import { Context, type Effect } from "effect";
+import type { Delivery, DeliveryItem, Notification, NotificationCursor, NotificationStoreUnavailable, Preference, QuietHours, Recipient } from "./notification/notification.js";
+type Read<A> = Effect.Effect<A, NotificationStoreUnavailable>;
+type Write<A = void> = Effect.Effect<A, NotificationStoreUnavailable | NoOpenUnit>;
+declare const NotificationStore_base: Context.ServiceClass<NotificationStore, "@house-rules/notifications/NotificationStore", {
+    readonly insert: (notification: Notification, deliveries: readonly Delivery[]) => Write;
+    readonly list: (recipient: Recipient, page: {
+        readonly size: number;
+        readonly after?: NotificationCursor;
+    }) => Read<readonly Notification[]>;
+    readonly unreadCount: (recipient: Recipient) => Read<number>;
+    readonly markRead: (recipient: Recipient, at: number, id?: string) => Write<readonly Notification[]>;
+    readonly preferences: (recipient: Recipient) => Read<readonly Preference[]>;
+    readonly setPreference: (recipient: Recipient, preference: Preference) => Write;
+    readonly quietHours: (recipient: Recipient) => Read<QuietHours | null>;
+    readonly setQuietHours: (recipient: Recipient, hours: QuietHours | null) => Write;
+    readonly timeZone: (recipient: Recipient) => Read<string | null>;
+    readonly setTimeZone: (recipient: Recipient, timeZone: string | null) => Write;
+    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;
+    readonly markFailed: (id: string, error: string, at: number, retry: {
+        readonly maxAttempts: number;
+        readonly baseMs: number;
+        readonly capMs: number;
+    }) => Write;
+    readonly erase: (recipient: Recipient) => Write;
+}>;
+export declare class NotificationStore extends NotificationStore_base {
+}
+export {};

package/dist/storage.js

@@ -0,0 +1,3 @@
+import { Context } from "effect";
+export class NotificationStore extends Context.Service()("@house-rules/notifications/NotificationStore") {
+}

package/migrations/0001_notifications.sql

@@ -0,0 +1,61 @@
+CREATE TABLE notifications (
+  id text PRIMARY KEY,
+  recipient_kind text NOT NULL,
+  recipient_id text NOT NULL,
+  category text NOT NULL,
+  title text NOT NULL,
+  body text NOT NULL,
+  data jsonb NOT NULL,
+  created_at bigint NOT NULL,
+  read_at bigint,
+  UNIQUE (id, recipient_kind, recipient_id)
+);
+--> statement-breakpoint
+CREATE INDEX notifications_inbox ON notifications (recipient_kind, recipient_id, created_at DESC, id COLLATE "C" DESC);
+--> statement-breakpoint
+CREATE TABLE notification_preferences (
+  recipient_kind text NOT NULL,
+  recipient_id text NOT NULL,
+  category text NOT NULL,
+  channel text NOT NULL CHECK (channel IN ('inapp', 'push', 'email')),
+  mode text NOT NULL CHECK (mode IN ('immediate', 'hourly', 'daily', 'off')),
+  PRIMARY KEY (recipient_kind, recipient_id, category, channel)
+);
+--> statement-breakpoint
+CREATE TABLE notification_quiet_hours (
+  recipient_kind text NOT NULL,
+  recipient_id text NOT NULL,
+  start_time text NOT NULL,
+  end_time text NOT NULL,
+  PRIMARY KEY (recipient_kind, recipient_id)
+);
+--> statement-breakpoint
+CREATE TABLE notification_time_zones (
+  recipient_kind text NOT NULL,
+  recipient_id text NOT NULL,
+  time_zone text NOT NULL,
+  PRIMARY KEY (recipient_kind, recipient_id)
+);
+--> statement-breakpoint
+CREATE TABLE notification_deliveries (
+  id text PRIMARY KEY,
+  notification_id text NOT NULL,
+  recipient_kind text NOT NULL,
+  recipient_id text NOT NULL,
+  channel text NOT NULL CHECK (channel IN ('inapp', 'push', 'email')),
+  mode text NOT NULL CHECK (mode IN ('immediate', 'hourly', 'daily')),
+  state text NOT NULL CHECK (state IN ('pending', 'held', 'sent', 'failed', 'cancelled')),
+  due_at bigint NOT NULL,
+  retry_at bigint,
+  sent_at bigint,
+  attempts integer NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+  last_error text,
+  UNIQUE (notification_id, channel, recipient_kind, recipient_id),
+  FOREIGN KEY (notification_id, recipient_kind, recipient_id) REFERENCES notifications (id, recipient_kind, recipient_id) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE INDEX notification_deliveries_due ON notification_deliveries (due_at, id COLLATE "C") WHERE state IN ('pending', 'held');
+--> statement-breakpoint
+CREATE INDEX notification_deliveries_unsettled ON notification_deliveries (recipient_kind, recipient_id, id COLLATE "C") WHERE state IN ('pending', 'held');
+--> statement-breakpoint
+CREATE VIEW notifications_published AS SELECT id, recipient_kind, recipient_id, category, title, body, data, created_at, read_at FROM notifications;

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@house-rules/notifications",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Inbox, channel preferences, quiet hours and a delivery ledger.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "migrations",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JakubSzwajka/house-rules.git",
+    "directory": "packages/notifications"
+  },
+  "bugs": {
+    "url": "https://github.com/JakubSzwajka/house-rules/issues"
+  },
+  "homepage": "https://github.com/JakubSzwajka/house-rules",
+  "houseRules": {
+    "migrations": "migrations"
+  },
+  "peerDependencies": {
+    "@house-rules/application": "0.3.0",
+    "@house-rules/domain": "0.2.1",
+    "effect": "4.0.3"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.3",
+    "@effect/platform-node-shared": "4.0.3",
+    "@effect/sql-pg": "4.0.3",
+    "@effect/vitest": "4.0.3",
+    "@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"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "varlock run --path ../../ -- vitest run"
+  }
 }