@voyantjs/notifications 0.28.1 → 0.29.0

package/dist/service-sequence.d.ts

@@ -0,0 +1,113 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { type NotificationReminderRule, type NotificationReminderRuleStage, type NotificationReminderStageCadenceInterval, type NotificationReminderStageChannel, type NotificationSettings } from "./schema.js";
+export type ReminderTargetSnapshot = {
+    id: string;
+    bookingId: string | null;
+    dueDate: string | null;
+    issuedAt: string | null;
+    departureDate: string | null;
+    bookingCreatedAt: string | null;
+    status: string;
+    isTerminal: boolean;
+};
+export type SequenceHistoryEntry = {
+    scheduledFor: Date;
+    sentAt: Date | null;
+    status: string;
+};
+export type StageDecision = {
+    fire: false;
+    reason: string;
+    stage?: NotificationReminderRuleStage;
+} | {
+    fire: true;
+    stage: NotificationReminderRuleStage;
+    anchorDate: Date;
+    sendCountAtFire: number;
+};
+export declare const DEFAULT_NOTIFICATION_SETTINGS: NotificationSettings;
+export declare function getNotificationSettings(db: PostgresJsDatabase, scope?: string): Promise<NotificationSettings>;
+export declare function listStagesForRule(db: PostgresJsDatabase, reminderRuleId: string): Promise<NotificationReminderRuleStage[]>;
+export declare function listChannelsForStage(db: PostgresJsDatabase, stageId: string): Promise<NotificationReminderStageChannel[]>;
+export declare function pickActiveStage(stages: NotificationReminderRuleStage[], sendsSoFar: number): NotificationReminderRuleStage | null;
+export declare function inWindow(today: Date, anchorDate: Date, stage: NotificationReminderRuleStage): boolean;
+export declare function pickEscalatingInterval(intervals: NotificationReminderStageCadenceInterval[] | null | undefined, daysUntilDue: number | null): NotificationReminderStageCadenceInterval | null;
+export declare function cadenceElapsed(today: Date, lastSentAt: Date | null, stage: NotificationReminderRuleStage, daysUntilDue: number | null): boolean;
+export declare function resolveAnchor(anchor: NotificationReminderRuleStage["anchor"], target: ReminderTargetSnapshot, history: SequenceHistoryEntry[]): Date | null;
+export declare function evaluateStage(_rule: NotificationReminderRule, stages: NotificationReminderRuleStage[], target: ReminderTargetSnapshot, history: SequenceHistoryEntry[], today: Date): StageDecision;
+export declare function applyQuietHours(now: Date, stage: NotificationReminderRuleStage, settings: NotificationSettings, recipientTimezone?: string | null): {
+    scheduledAt: Date;
+    deferred: boolean;
+};
+export declare function exceedsRecipientRateLimit(db: PostgresJsDatabase, recipient: string, channel: string, settings: NotificationSettings, now: Date): Promise<boolean>;
+export declare function suppressedByGroup(db: PostgresJsDatabase, recipient: string | null, suppressionGroup: string | null, settings: NotificationSettings, now: Date): Promise<boolean>;
+export declare function loadHistory(db: PostgresJsDatabase, reminderRuleId: string, targetId: string): Promise<SequenceHistoryEntry[]>;
+/**
+ * Computes the date range a target's `due_date` (or `issue_date`) needs to
+ * fall in for any of the rule's stages to be inside their eligibility window
+ * today.
+ *
+ * From `inWindow`: today must satisfy
+ *   anchor + windowStartDays ≤ today ≤ anchor + windowEndDays
+ * Solving for anchor:
+ *   today − windowEndDays ≤ anchor ≤ today − windowStartDays
+ *
+ * Across all stages with anchor=`due_date`, we union the [start, end] ranges
+ * and use the resulting envelope as a SQL `BETWEEN` filter. Returns null when
+ * no stage is anchored on the requested column (e.g. all stages anchor on
+ * `departure_date`) — caller should skip the pushdown in that case.
+ */
+export declare function computeAnchorDateEnvelope(stages: NotificationReminderRuleStage[], today: Date, anchor: NotificationReminderRuleStage["anchor"]): {
+    from: string;
+    to: string;
+} | null;
+export type DateEnvelopes = {
+    /** When set, only fetch payment schedules whose `due_date` falls in this range. */
+    paymentScheduleDueDate?: {
+        from: string;
+        to: string;
+    };
+    /** When set, only fetch invoices whose `due_date` falls in this range. */
+    invoiceDueDate?: {
+        from: string;
+        to: string;
+    };
+    /** When set, only fetch invoices whose `issue_date` falls in this range. */
+    invoiceIssueDate?: {
+        from: string;
+        to: string;
+    };
+};
+export declare function fetchOpenPaymentScheduleTargets(db: PostgresJsDatabase, envelopes?: DateEnvelopes): Promise<ReminderTargetSnapshot[]>;
+export declare function fetchOpenInvoiceTargets(db: PostgresJsDatabase, envelopes?: DateEnvelopes): Promise<ReminderTargetSnapshot[]>;
+/**
+ * Per-rule target fetch that pushes a date envelope into the WHERE when all
+ * relevant stages share an anchor we can SQL-filter on (`due_date` for both
+ * target types, `invoice_issued_at` for invoices). Other anchors fall through
+ * to the unfiltered fetch — they're expected to be rare and the in-app
+ * window check still rejects misses.
+ */
+export declare function fetchTargetsForRule(db: PostgresJsDatabase, rule: NotificationReminderRule, stages?: NotificationReminderRuleStage[], today?: Date): Promise<ReminderTargetSnapshot[]>;
+export declare function listActiveRulesByPriority(db: PostgresJsDatabase): Promise<NotificationReminderRule[]>;
+export type PreviewRow = {
+    ruleId: string;
+    ruleName: string;
+    ruleSlug: string;
+    targetType: string;
+    targetId: string;
+    bookingId: string | null;
+    stageId: string;
+    stageName: string | null;
+    stageOrderIndex: number;
+    anchor: string;
+    anchorDate: string;
+    scheduledAt: string;
+    sendCountAtFire: number;
+    reasoning: string;
+};
+export declare function previewReminders(db: PostgresJsDatabase, options?: {
+    now?: Date;
+    ruleId?: string;
+    targetId?: string;
+}): Promise<PreviewRow[]>;
+//# sourceMappingURL=service-sequence.d.ts.map

package/dist/service-sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-sequence.d.ts","sourceRoot":"","sources":["../src/service-sequence.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,KAAK,wCAAwC,EAC7C,KAAK,gCAAgC,EACrC,KAAK,oBAAoB,EAM1B,MAAM,aAAa,CAAA;AAGpB,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,EAAE,IAAI,CAAA;IAClB,MAAM,EAAE,IAAI,GAAG,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,6BAA6B,CAAA;CAAE,GACtE;IACE,IAAI,EAAE,IAAI,CAAA;IACV,KAAK,EAAE,6BAA6B,CAAA;IACpC,UAAU,EAAE,IAAI,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAEL,eAAO,MAAM,6BAA6B,EAAE,oBAW3C,CAAA;AAED,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,kBAAkB,EACtB,KAAK,SAAY,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAO/B;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,kBAAkB,EACtB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,6BAA6B,EAAE,CAAC,CAM1C;AAED,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAS7C;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,6BAA6B,EAAE,EACvC,UAAU,EAAE,MAAM,GACjB,6BAA6B,GAAG,IAAI,CAWtC;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,6BAA6B,WAK3F;AAOD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,wCAAwC,EAAE,GAAG,IAAI,GAAG,SAAS,EACxE,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,wCAAwC,GAAG,IAAI,CAqBjD;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,IAAI,EACX,UAAU,EAAE,IAAI,GAAG,IAAI,EACvB,KAAK,EAAE,6BAA6B,EACpC,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAgBT;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,6BAA6B,CAAC,QAAQ,CAAC,EAC/C,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,oBAAoB,EAAE,GAC9B,IAAI,GAAG,IAAI,CAsBb;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,6BAA6B,EAAE,EACvC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,oBAAoB,EAAE,EAC/B,KAAK,EAAE,IAAI,GACV,aAAa,CAgCf;AAOD,wBAAgB,eAAe,CAC7B,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,6BAA6B,EACpC,QAAQ,EAAE,oBAAoB,EAC9B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC;IAAE,WAAW,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CA+B1C;AAiCD,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,kBAAkB,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,oBAAoB,EAC9B,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,kBAAkB,EACtB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,EAC/B,QAAQ,EAAE,oBAAoB,EAC9B,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED,wBAAsB,WAAW,CAC/B,EAAE,EAAE,kBAAkB,EACtB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAqBjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,6BAA6B,EAAE,EACvC,KAAK,EAAE,IAAI,EACX,MAAM,EAAE,6BAA6B,CAAC,QAAQ,CAAC,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgBrC;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,mFAAmF;IACnF,sBAAsB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD,0EAA0E;IAC1E,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7C,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAChD,CAAA;AAED,wBAAsB,+BAA+B,CACnD,EAAE,EAAE,kBAAkB,EACtB,SAAS,GAAE,aAAkB,GAC5B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAgCnC;AAED,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,kBAAkB,EACtB,SAAS,GAAE,aAAkB,GAC5B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CA+CnC;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,wBAAwB,EAC9B,MAAM,GAAE,6BAA6B,EAAO,EAC5C,KAAK,GAAE,IAAiB,GACvB,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAcnC;AAED,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,kBAAkB,GACrB,OAAO,CAAC,wBAAwB,EAAE,CAAC,CASrC;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,eAAe,EAAE,MAAM,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,kBAAkB,EACtB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/D,OAAO,CAAC,UAAU,EAAE,CAAC,CAwCvB"}

package/dist/service-sequence.js

@@ -0,0 +1,432 @@
+import { bookings } from "@voyantjs/bookings/schema";
+import { bookingPaymentSchedules, invoices } from "@voyantjs/finance";
+import { and, asc, eq, gt, gte, lte, or, sql } from "drizzle-orm";
+import { notificationReminderRuleStages, notificationReminderRules, notificationReminderRuns, notificationReminderStageChannels, notificationSettings, } from "./schema.js";
+import { addUtcDays, startOfUtcDay } from "./service-shared.js";
+export const DEFAULT_NOTIFICATION_SETTINGS = {
+    id: "nset_default",
+    scope: "default",
+    quietHoursLocal: null,
+    blackoutDates: null,
+    skipWeekends: false,
+    recipientRateLimitPerDay: null,
+    suppressionWindowHours: 24,
+    metadata: null,
+    createdAt: new Date(0),
+    updatedAt: new Date(0),
+};
+export async function getNotificationSettings(db, scope = "default") {
+    const [row] = await db
+        .select()
+        .from(notificationSettings)
+        .where(eq(notificationSettings.scope, scope))
+        .limit(1);
+    return row ?? { ...DEFAULT_NOTIFICATION_SETTINGS, scope };
+}
+export async function listStagesForRule(db, reminderRuleId) {
+    return db
+        .select()
+        .from(notificationReminderRuleStages)
+        .where(eq(notificationReminderRuleStages.reminderRuleId, reminderRuleId))
+        .orderBy(asc(notificationReminderRuleStages.orderIndex));
+}
+export async function listChannelsForStage(db, stageId) {
+    return db
+        .select()
+        .from(notificationReminderStageChannels)
+        .where(eq(notificationReminderStageChannels.stageId, stageId))
+        .orderBy(asc(notificationReminderStageChannels.orderIndex), asc(notificationReminderStageChannels.createdAt));
+}
+export function pickActiveStage(stages, sendsSoFar) {
+    if (stages.length === 0)
+        return null;
+    let cumulative = 0;
+    for (const stage of stages) {
+        const cap = stage.maxSendsInStage ?? Number.POSITIVE_INFINITY;
+        if (sendsSoFar < cumulative + cap) {
+            return stage;
+        }
+        cumulative += cap;
+    }
+    return null;
+}
+export function inWindow(today, anchorDate, stage) {
+    const start = addUtcDays(startOfUtcDay(anchorDate), stage.windowStartDays);
+    const end = addUtcDays(startOfUtcDay(anchorDate), stage.windowEndDays);
+    const todayStart = startOfUtcDay(today);
+    return todayStart >= start && todayStart <= end;
+}
+function daysBetweenUtc(a, b) {
+    const ms = startOfUtcDay(a).getTime() - startOfUtcDay(b).getTime();
+    return Math.round(ms / (24 * 60 * 60 * 1000));
+}
+export function pickEscalatingInterval(intervals, daysUntilDue) {
+    if (!intervals || intervals.length === 0)
+        return null;
+    for (const interval of intervals) {
+        const gtOk = interval.whenDaysUntilDueGT == null || daysUntilDue == null
+            ? interval.whenDaysUntilDueGT == null
+            : daysUntilDue > interval.whenDaysUntilDueGT;
+        const ltOk = interval.whenDaysUntilDueLT == null || daysUntilDue == null
+            ? interval.whenDaysUntilDueLT == null
+            : daysUntilDue < interval.whenDaysUntilDueLT;
+        if (interval.whenDaysUntilDueGT == null && interval.whenDaysUntilDueLT == null) {
+            return interval;
+        }
+        if (gtOk && ltOk)
+            return interval;
+    }
+    // Fall back to the last interval with no constraints (the "default bucket").
+    const fallback = intervals.find((i) => i.whenDaysUntilDueGT == null && i.whenDaysUntilDueLT == null);
+    return fallback ?? null;
+}
+export function cadenceElapsed(today, lastSentAt, stage, daysUntilDue) {
+    if (stage.cadenceKind === "once") {
+        return lastSentAt === null;
+    }
+    if (stage.cadenceKind === "every_n_days") {
+        if (lastSentAt === null)
+            return true;
+        const every = stage.cadenceEveryDays ?? 1;
+        return daysBetweenUtc(today, lastSentAt) >= every;
+    }
+    if (stage.cadenceKind === "escalating") {
+        if (lastSentAt === null)
+            return true;
+        const interval = pickEscalatingInterval(stage.cadenceIntervals, daysUntilDue);
+        if (!interval)
+            return false;
+        return daysBetweenUtc(today, lastSentAt) >= interval.repeatEveryDays;
+    }
+    return false;
+}
+export function resolveAnchor(anchor, target, history) {
+    switch (anchor) {
+        case "due_date":
+            return target.dueDate ? new Date(`${target.dueDate}T00:00:00Z`) : null;
+        case "booking_created_at":
+            return target.bookingCreatedAt ? new Date(target.bookingCreatedAt) : null;
+        case "departure_date":
+            return target.departureDate ? new Date(`${target.departureDate}T00:00:00Z`) : null;
+        case "invoice_issued_at":
+            return target.issuedAt ? new Date(`${target.issuedAt}T00:00:00Z`) : null;
+        case "last_send_at": {
+            const sent = history.filter((h) => h.status === "sent" && h.sentAt);
+            if (sent.length === 0)
+                return null;
+            const last = sent.reduce((acc, e) => (e.sentAt && e.sentAt > acc ? e.sentAt : acc), sent[0].sentAt);
+            return last;
+        }
+        default:
+            return null;
+    }
+}
+export function evaluateStage(_rule, stages, target, history, today) {
+    if (target.isTerminal) {
+        return { fire: false, reason: "target_terminal_state" };
+    }
+    const sentHistory = history.filter((h) => h.status === "sent");
+    const stage = pickActiveStage(stages, sentHistory.length);
+    if (!stage) {
+        return { fire: false, reason: "no_active_stage" };
+    }
+    const anchorDate = resolveAnchor(stage.anchor, target, history);
+    if (!anchorDate) {
+        return { fire: false, reason: "anchor_unresolved", stage };
+    }
+    if (!inWindow(today, anchorDate, stage)) {
+        return { fire: false, reason: "outside_window", stage };
+    }
+    const lastSent = sentHistory.reduce((acc, e) => {
+        const stamp = e.sentAt ?? e.scheduledFor;
+        return acc && acc > stamp ? acc : stamp;
+    }, null);
+    let daysUntilDue = null;
+    if (target.dueDate) {
+        daysUntilDue = daysBetweenUtc(new Date(`${target.dueDate}T00:00:00Z`), today);
+    }
+    if (!cadenceElapsed(today, lastSent, stage, daysUntilDue)) {
+        return { fire: false, reason: "cadence_not_elapsed", stage };
+    }
+    return { fire: true, stage, anchorDate, sendCountAtFire: sentHistory.length + 1 };
+}
+function parseTimeOfDayUtcMinutes(value) {
+    const [hh, mm] = value.split(":").map((part) => Number(part));
+    return (hh ?? 0) * 60 + (mm ?? 0);
+}
+export function applyQuietHours(now, stage, settings, recipientTimezone) {
+    if (!stage.respectQuietHours) {
+        return { scheduledAt: now, deferred: false };
+    }
+    const blackoutDates = settings.blackoutDates ?? [];
+    const skipWeekends = settings.skipWeekends ?? false;
+    const quiet = settings.quietHoursLocal;
+    const tz = recipientTimezone ?? quiet?.tz ?? "UTC";
+    const effectiveTz = tz === "recipient" ? "UTC" : tz;
+    let candidate = now;
+    for (let attempts = 0; attempts < 24; attempts += 1) {
+        const local = formatInTimeZone(candidate, effectiveTz);
+        const blackout = blackoutDates.includes(local.dateString);
+        const isWeekend = local.dayOfWeek === 0 || local.dayOfWeek === 6;
+        let inQuiet = false;
+        if (quiet) {
+            const startMin = parseTimeOfDayUtcMinutes(quiet.start);
+            const endMin = parseTimeOfDayUtcMinutes(quiet.end);
+            const nowMin = local.hour * 60 + local.minute;
+            inQuiet =
+                startMin <= endMin
+                    ? nowMin >= startMin && nowMin < endMin
+                    : nowMin >= startMin || nowMin < endMin;
+        }
+        if (!blackout && !(skipWeekends && isWeekend) && !inQuiet) {
+            return { scheduledAt: candidate, deferred: candidate !== now };
+        }
+        candidate = new Date(candidate.getTime() + 60 * 60 * 1000);
+    }
+    return { scheduledAt: candidate, deferred: true };
+}
+function formatInTimeZone(date, timeZone) {
+    const fmt = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        weekday: "short",
+        hour12: false,
+    });
+    const parts = Object.fromEntries(fmt.formatToParts(date).map((part) => [part.type, part.value]));
+    const dayLookup = {
+        Sun: 0,
+        Mon: 1,
+        Tue: 2,
+        Wed: 3,
+        Thu: 4,
+        Fri: 5,
+        Sat: 6,
+    };
+    return {
+        dateString: `${parts.year}-${parts.month}-${parts.day}`,
+        hour: Number(parts.hour ?? "0") % 24,
+        minute: Number(parts.minute ?? "0"),
+        dayOfWeek: dayLookup[parts.weekday ?? "Mon"] ?? 1,
+    };
+}
+export async function exceedsRecipientRateLimit(db, recipient, channel, settings, now) {
+    const limit = settings.recipientRateLimitPerDay;
+    if (limit == null || limit <= 0)
+        return false;
+    const since = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const [row] = await db
+        .select({ count: sql `count(*)::int` })
+        .from(notificationReminderRuns)
+        .where(and(eq(notificationReminderRuns.recipient, recipient), eq(notificationReminderRuns.status, "sent"), gte(notificationReminderRuns.processedAt, since), sql `${notificationReminderRuns.metadata}->>'channel' = ${channel}`));
+    return (row?.count ?? 0) >= limit;
+}
+export async function suppressedByGroup(db, recipient, suppressionGroup, settings, now) {
+    if (!recipient || !suppressionGroup)
+        return false;
+    const windowHours = settings.suppressionWindowHours ?? 24;
+    if (windowHours <= 0)
+        return false;
+    const since = new Date(now.getTime() - windowHours * 60 * 60 * 1000);
+    const [row] = await db
+        .select({ id: notificationReminderRuns.id })
+        .from(notificationReminderRuns)
+        .innerJoin(notificationReminderRules, eq(notificationReminderRuns.reminderRuleId, notificationReminderRules.id))
+        .where(and(eq(notificationReminderRuns.recipient, recipient), eq(notificationReminderRuns.status, "sent"), eq(notificationReminderRules.suppressionGroup, suppressionGroup), gte(notificationReminderRuns.processedAt, since)))
+        .limit(1);
+    return Boolean(row);
+}
+export async function loadHistory(db, reminderRuleId, targetId) {
+    const rows = await db
+        .select({
+        scheduledFor: notificationReminderRuns.scheduledFor,
+        processedAt: notificationReminderRuns.processedAt,
+        status: notificationReminderRuns.status,
+    })
+        .from(notificationReminderRuns)
+        .where(and(eq(notificationReminderRuns.reminderRuleId, reminderRuleId), eq(notificationReminderRuns.targetId, targetId)))
+        .orderBy(asc(notificationReminderRuns.scheduledFor));
+    return rows.map((row) => ({
+        scheduledFor: row.scheduledFor,
+        sentAt: row.status === "sent" ? row.processedAt : null,
+        status: row.status,
+    }));
+}
+/**
+ * Computes the date range a target's `due_date` (or `issue_date`) needs to
+ * fall in for any of the rule's stages to be inside their eligibility window
+ * today.
+ *
+ * From `inWindow`: today must satisfy
+ *   anchor + windowStartDays ≤ today ≤ anchor + windowEndDays
+ * Solving for anchor:
+ *   today − windowEndDays ≤ anchor ≤ today − windowStartDays
+ *
+ * Across all stages with anchor=`due_date`, we union the [start, end] ranges
+ * and use the resulting envelope as a SQL `BETWEEN` filter. Returns null when
+ * no stage is anchored on the requested column (e.g. all stages anchor on
+ * `departure_date`) — caller should skip the pushdown in that case.
+ */
+export function computeAnchorDateEnvelope(stages, today, anchor) {
+    const matching = stages.filter((s) => s.anchor === anchor);
+    if (matching.length === 0)
+        return null;
+    const todayStart = startOfUtcDay(today);
+    let from = Number.POSITIVE_INFINITY;
+    let to = Number.NEGATIVE_INFINITY;
+    for (const stage of matching) {
+        const fromDays = -stage.windowEndDays;
+        const toDays = -stage.windowStartDays;
+        if (fromDays < from)
+            from = fromDays;
+        if (toDays > to)
+            to = toDays;
+    }
+    return {
+        from: addUtcDays(todayStart, from).toISOString().slice(0, 10),
+        to: addUtcDays(todayStart, to).toISOString().slice(0, 10),
+    };
+}
+export async function fetchOpenPaymentScheduleTargets(db, envelopes = {}) {
+    const conditions = [
+        or(eq(bookingPaymentSchedules.status, "pending"), eq(bookingPaymentSchedules.status, "due")),
+    ];
+    if (envelopes.paymentScheduleDueDate) {
+        conditions.push(gte(bookingPaymentSchedules.dueDate, envelopes.paymentScheduleDueDate.from), lte(bookingPaymentSchedules.dueDate, envelopes.paymentScheduleDueDate.to));
+    }
+    const rows = await db
+        .select({
+        id: bookingPaymentSchedules.id,
+        bookingId: bookingPaymentSchedules.bookingId,
+        dueDate: bookingPaymentSchedules.dueDate,
+        status: bookingPaymentSchedules.status,
+        bookingCreatedAt: bookings.createdAt,
+        departureDate: bookings.startDate,
+    })
+        .from(bookingPaymentSchedules)
+        .leftJoin(bookings, eq(bookings.id, bookingPaymentSchedules.bookingId))
+        .where(and(...conditions));
+    return rows.map((row) => ({
+        id: row.id,
+        bookingId: row.bookingId,
+        dueDate: row.dueDate,
+        issuedAt: null,
+        departureDate: row.departureDate,
+        bookingCreatedAt: row.bookingCreatedAt ? row.bookingCreatedAt.toISOString() : null,
+        status: row.status,
+        isTerminal: row.status !== "pending" && row.status !== "due",
+    }));
+}
+export async function fetchOpenInvoiceTargets(db, envelopes = {}) {
+    const conditions = [
+        gt(invoices.balanceDueCents, 0),
+        or(eq(invoices.invoiceType, "invoice"), eq(invoices.invoiceType, "proforma")),
+        or(eq(invoices.status, "sent"), eq(invoices.status, "partially_paid"), eq(invoices.status, "overdue")),
+    ];
+    if (envelopes.invoiceDueDate) {
+        conditions.push(gte(invoices.dueDate, envelopes.invoiceDueDate.from), lte(invoices.dueDate, envelopes.invoiceDueDate.to));
+    }
+    if (envelopes.invoiceIssueDate) {
+        conditions.push(gte(invoices.issueDate, envelopes.invoiceIssueDate.from), lte(invoices.issueDate, envelopes.invoiceIssueDate.to));
+    }
+    const rows = await db
+        .select({
+        id: invoices.id,
+        bookingId: invoices.bookingId,
+        dueDate: invoices.dueDate,
+        issueDate: invoices.issueDate,
+        balanceDueCents: invoices.balanceDueCents,
+        invoiceType: invoices.invoiceType,
+        status: invoices.status,
+        bookingCreatedAt: bookings.createdAt,
+        departureDate: bookings.startDate,
+    })
+        .from(invoices)
+        .leftJoin(bookings, eq(bookings.id, invoices.bookingId))
+        .where(and(...conditions));
+    return rows.map((row) => ({
+        id: row.id,
+        bookingId: row.bookingId,
+        dueDate: row.dueDate,
+        issuedAt: row.issueDate,
+        departureDate: row.departureDate,
+        bookingCreatedAt: row.bookingCreatedAt ? row.bookingCreatedAt.toISOString() : null,
+        status: row.status,
+        isTerminal: row.balanceDueCents <= 0,
+    }));
+}
+/**
+ * Per-rule target fetch that pushes a date envelope into the WHERE when all
+ * relevant stages share an anchor we can SQL-filter on (`due_date` for both
+ * target types, `invoice_issued_at` for invoices). Other anchors fall through
+ * to the unfiltered fetch — they're expected to be rare and the in-app
+ * window check still rejects misses.
+ */
+export async function fetchTargetsForRule(db, rule, stages = [], today = new Date()) {
+    if (rule.targetType === "booking_payment_schedule") {
+        const dueEnv = computeAnchorDateEnvelope(stages, today, "due_date");
+        return fetchOpenPaymentScheduleTargets(db, dueEnv ? { paymentScheduleDueDate: dueEnv } : {});
+    }
+    if (rule.targetType === "invoice") {
+        const dueEnv = computeAnchorDateEnvelope(stages, today, "due_date");
+        const issueEnv = computeAnchorDateEnvelope(stages, today, "invoice_issued_at");
+        return fetchOpenInvoiceTargets(db, {
+            invoiceDueDate: dueEnv ?? undefined,
+            invoiceIssueDate: issueEnv ?? undefined,
+        });
+    }
+    return [];
+}
+export async function listActiveRulesByPriority(db) {
+    return db
+        .select()
+        .from(notificationReminderRules)
+        .where(eq(notificationReminderRules.status, "active"))
+        .orderBy(sql `${notificationReminderRules.priority} desc nulls last`, asc(notificationReminderRules.createdAt));
+}
+export async function previewReminders(db, options = {}) {
+    const now = options.now ?? new Date();
+    const today = startOfUtcDay(now);
+    const settings = await getNotificationSettings(db);
+    const allRules = await listActiveRulesByPriority(db);
+    const rules = options.ruleId ? allRules.filter((r) => r.id === options.ruleId) : allRules;
+    const rows = [];
+    for (const rule of rules) {
+        const stages = await listStagesForRule(db, rule.id);
+        if (stages.length === 0)
+            continue;
+        const targets = await fetchTargetsForRule(db, rule, stages, today);
+        const filteredTargets = options.targetId
+            ? targets.filter((t) => t.id === options.targetId)
+            : targets;
+        for (const target of filteredTargets) {
+            const history = await loadHistory(db, rule.id, target.id);
+            const decision = evaluateStage(rule, stages, target, history, today);
+            if (!decision.fire)
+                continue;
+            const { scheduledAt } = applyQuietHours(now, decision.stage, settings);
+            rows.push({
+                ruleId: rule.id,
+                ruleName: rule.name,
+                ruleSlug: rule.slug,
+                targetType: rule.targetType,
+                targetId: target.id,
+                bookingId: target.bookingId,
+                stageId: decision.stage.id,
+                stageName: decision.stage.name,
+                stageOrderIndex: decision.stage.orderIndex,
+                anchor: decision.stage.anchor,
+                anchorDate: decision.anchorDate.toISOString(),
+                scheduledAt: scheduledAt.toISOString(),
+                sendCountAtFire: decision.sendCountAtFire,
+                reasoning: `stage[${decision.stage.orderIndex}] anchor=${decision.stage.anchor} window=[${decision.stage.windowStartDays},${decision.stage.windowEndDays}] cadence=${decision.stage.cadenceKind}`,
+            });
+        }
+    }
+    return rows;
+}
+const _markUnusedImports = [lte]; // keep tree-shaking honest if helpers added later
+void _markUnusedImports;

package/dist/service-stages.d.ts

@@ -0,0 +1,23 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { z } from "zod";
+import { type NotificationReminderRuleStage, type NotificationReminderStageChannel, type NotificationSettings } from "./schema.js";
+import type { insertNotificationReminderRuleStageSchema, insertNotificationReminderStageChannelSchema, reorderReminderRuleStagesSchema, updateNotificationReminderRuleStageSchema, updateNotificationReminderStageChannelSchema, updateNotificationSettingsSchema } from "./validation.js";
+export type CreateReminderRuleStageInput = z.infer<typeof insertNotificationReminderRuleStageSchema>;
+export type UpdateReminderRuleStageInput = z.infer<typeof updateNotificationReminderRuleStageSchema>;
+export type CreateReminderStageChannelInput = z.infer<typeof insertNotificationReminderStageChannelSchema>;
+export type UpdateReminderStageChannelInput = z.infer<typeof updateNotificationReminderStageChannelSchema>;
+export type ReorderReminderRuleStagesInput = z.infer<typeof reorderReminderRuleStagesSchema>;
+export type UpdateNotificationSettingsInput = z.infer<typeof updateNotificationSettingsSchema>;
+export declare function listReminderRuleStages(db: PostgresJsDatabase, reminderRuleId: string): Promise<NotificationReminderRuleStage[]>;
+export declare function getReminderRuleStageById(db: PostgresJsDatabase, stageId: string): Promise<NotificationReminderRuleStage | null>;
+export declare function createReminderRuleStage(db: PostgresJsDatabase, reminderRuleId: string, input: CreateReminderRuleStageInput): Promise<NotificationReminderRuleStage>;
+export declare function updateReminderRuleStage(db: PostgresJsDatabase, stageId: string, input: UpdateReminderRuleStageInput): Promise<NotificationReminderRuleStage | null>;
+export declare function deleteReminderRuleStage(db: PostgresJsDatabase, stageId: string): Promise<boolean>;
+export declare function reorderReminderRuleStages(db: PostgresJsDatabase, reminderRuleId: string, input: ReorderReminderRuleStagesInput): Promise<NotificationReminderRuleStage[]>;
+export declare function listStageChannels(db: PostgresJsDatabase, stageId: string): Promise<NotificationReminderStageChannel[]>;
+export declare function createStageChannel(db: PostgresJsDatabase, stageId: string, input: CreateReminderStageChannelInput): Promise<NotificationReminderStageChannel>;
+export declare function updateStageChannel(db: PostgresJsDatabase, channelId: string, input: UpdateReminderStageChannelInput): Promise<NotificationReminderStageChannel | null>;
+export declare function deleteStageChannel(db: PostgresJsDatabase, channelId: string): Promise<boolean>;
+export declare function getNotificationSettingsRecord(db: PostgresJsDatabase, scope?: string): Promise<NotificationSettings>;
+export declare function upsertNotificationSettings(db: PostgresJsDatabase, input: UpdateNotificationSettingsInput): Promise<NotificationSettings>;
+//# sourceMappingURL=service-stages.d.ts.map

package/dist/service-stages.d.ts.map

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