@voyant-travel/notifications 0.111.7

package/dist/service-sequence-targets.js

@@ -0,0 +1,136 @@
+import { bookings } from "@voyant-travel/bookings/schema";
+import { bookingPaymentSchedules, invoices } from "@voyant-travel/finance";
+import { and, eq, gt, gte, inArray, lte, or } from "drizzle-orm";
+import { addUtcDays, startOfUtcDay } from "./service-shared.js";
+/**
+ * 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),
+    };
+}
+const PAYABLE_BOOKING_STATUSES = [
+    "on_hold",
+    "awaiting_payment",
+    "confirmed",
+    "in_progress",
+];
+export async function fetchOpenPaymentScheduleTargets(db, envelopes = {}) {
+    const conditions = [
+        or(eq(bookingPaymentSchedules.status, "pending"), eq(bookingPaymentSchedules.status, "due")),
+        inArray(bookings.status, PAYABLE_BOOKING_STATUSES),
+    ];
+    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, "issued"), 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 [];
+}

package/dist/service-sequence.d.ts

@@ -0,0 +1,68 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { type NotificationReminderRule, type NotificationReminderRuleStage, type NotificationReminderStageCadenceInterval, type NotificationReminderStageChannel, type NotificationSettings } from "./schema.js";
+export { computeAnchorDateEnvelope, type DateEnvelopes, fetchOpenInvoiceTargets, fetchOpenPaymentScheduleTargets, fetchTargetsForRule, } from "./service-sequence-targets.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[], attemptsSoFar: 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[]>;
+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":"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"}

package/dist/service-sequence.js

@@ -0,0 +1,316 @@
+import { and, asc, eq, gte, sql } from "drizzle-orm";
+import { notificationReminderRuleStages, notificationReminderRules, notificationReminderRuns, notificationReminderStageChannels, notificationSettings, } from "./schema.js";
+import { fetchTargetsForRule as fetchTargetsForSequenceRule } from "./service-sequence-targets.js";
+import { addUtcDays, startOfUtcDay } from "./service-shared.js";
+export { computeAnchorDateEnvelope, fetchOpenInvoiceTargets, fetchOpenPaymentScheduleTargets, fetchTargetsForRule, } from "./service-sequence-targets.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, attemptsSoFar) {
+    if (stages.length === 0)
+        return null;
+    let cumulative = 0;
+    for (const stage of stages) {
+        const cap = stage.maxSendsInStage ?? Number.POSITIVE_INFINITY;
+        if (attemptsSoFar < cumulative + cap) {
+            return stage;
+        }
+        cumulative += cap;
+    }
+    return null;
+}
+function isDeliveryAttempt(status) {
+    return (status === "queued" ||
+        status === "processing" ||
+        status === "sent" ||
+        status === "skipped" ||
+        status === "failed");
+}
+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 attemptHistory = history.filter((h) => isDeliveryAttempt(h.status));
+    const stage = pickActiveStage(stages, attemptHistory.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 lastAttempt = attemptHistory.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, lastAttempt, stage, daysUntilDue)) {
+        return { fire: false, reason: "cadence_not_elapsed", stage };
+    }
+    return { fire: true, stage, anchorDate, sendCountAtFire: attemptHistory.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), 
+    // agent-quality: raw-sql reviewed -- owner: notifications; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+    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,
+    }));
+}
+export async function listActiveRulesByPriority(db) {
+    return db
+        .select()
+        .from(notificationReminderRules)
+        .where(eq(notificationReminderRules.status, "active"))
+        .orderBy(
+    // agent-quality: raw-sql reviewed -- owner: notifications; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+    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 fetchTargetsForSequenceRule(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;
+}

package/dist/service-shared.d.ts

@@ -0,0 +1,107 @@
+import type { bookingPaymentSchedules } from "@voyant-travel/finance";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { SQLWrapper } from "drizzle-orm/sql";
+import type { z } from "zod";
+import type { notificationReminderRules } from "./schema.js";
+import type { NotificationAttachment, NotificationChannel, NotificationPayload, NotificationProvider, NotificationResult } from "./types.js";
+import type { bookingDocumentBundleItemSchema, insertNotificationReminderRuleSchema, insertNotificationTemplateSchema, notificationDeliveryListQuerySchema, notificationReminderRuleListQuerySchema, notificationReminderRunListQuerySchema, notificationReminderRunRecordSchema, notificationTemplateListQuerySchema, previewNotificationTemplateSchema, runDueRemindersSchema, sendBookingDocumentsNotificationSchema, sendInvoiceNotificationSchema, sendNotificationSchema, sendPaymentSessionNotificationSchema, updateNotificationReminderRuleSchema, updateNotificationTemplateSchema } from "./validation.js";
+export { normalizeNotificationTemplateData } from "./service-template-data.js";
+export type NotificationTemplateListQuery = z.infer<typeof notificationTemplateListQuerySchema>;
+export type NotificationDeliveryListQuery = z.infer<typeof notificationDeliveryListQuerySchema>;
+export type CreateNotificationTemplateInput = z.infer<typeof insertNotificationTemplateSchema>;
+export type UpdateNotificationTemplateInput = z.infer<typeof updateNotificationTemplateSchema>;
+export type SendNotificationInput = z.infer<typeof sendNotificationSchema>;
+export type NotificationReminderRuleListQuery = z.infer<typeof notificationReminderRuleListQuerySchema>;
+export type NotificationReminderRunListQuery = z.infer<typeof notificationReminderRunListQuerySchema>;
+export type NotificationReminderRunRecord = z.infer<typeof notificationReminderRunRecordSchema>;
+export type CreateNotificationReminderRuleInput = z.infer<typeof insertNotificationReminderRuleSchema>;
+export type UpdateNotificationReminderRuleInput = z.infer<typeof updateNotificationReminderRuleSchema>;
+export type RunDueRemindersInput = z.infer<typeof runDueRemindersSchema>;
+export type PreviewNotificationTemplateInput = z.infer<typeof previewNotificationTemplateSchema>;
+export type SendPaymentSessionNotificationInput = z.infer<typeof sendPaymentSessionNotificationSchema>;
+export type SendInvoiceNotificationInput = z.infer<typeof sendInvoiceNotificationSchema>;
+export type SendBookingDocumentsNotificationInput = z.infer<typeof sendBookingDocumentsNotificationSchema>;
+export type BookingDocumentBundleItem = z.infer<typeof bookingDocumentBundleItemSchema>;
+export type ReminderSweepResult = {
+    processed: number;
+    sent: number;
+    skipped: number;
+    failed: number;
+};
+export type ReminderQueueResult = {
+    processed: number;
+    queued: number;
+    skipped: number;
+    failed: number;
+};
+export type NotificationReminderRuleRow = typeof notificationReminderRules.$inferSelect;
+export type BookingPaymentScheduleRow = typeof bookingPaymentSchedules.$inferSelect;
+export declare class NotificationError extends Error {
+    constructor(message: string);
+}
+export interface NotificationService {
+    send(payload: NotificationPayload): Promise<NotificationResult>;
+    sendWith(providerName: string, payload: NotificationPayload): Promise<NotificationResult>;
+    getProvider(channel: NotificationChannel): NotificationProvider | undefined;
+    getProviderByName?(providerName: string): NotificationProvider | undefined;
+}
+export declare function createNotificationService(providers: ReadonlyArray<NotificationProvider>): NotificationService;
+export declare function summarizeNotificationAttachments(attachments: ReadonlyArray<NotificationAttachment> | null | undefined): {
+    filename: string;
+    path: string | null;
+    contentType: string | null;
+    disposition: "attachment" | "inline" | null;
+    contentId: string | null;
+}[];
+export declare function renderNotificationTemplate(template: string | null | undefined, data: Record<string, unknown>): string | null;
+export declare function previewNotificationTemplate(input: PreviewNotificationTemplateInput): {
+    channel: "email" | "sms";
+    provider: string | null;
+    fromAddress: string | null;
+    subject: string | null;
+    html: string | null;
+    text: string | null;
+};
+export declare function toTimestamp(value?: string | null): Date | null;
+export declare function startOfUtcDay(value: Date): Date;
+export declare function addUtcDays(value: Date, days: number): Date;
+export declare function toDateString(value: Date): string;
+export declare function buildReminderDedupeKey(ruleId: string, targetId: string, runDate: string): string;
+export declare function resolveReminderRecipient(booking: {
+    contactFirstName: string | null;
+    contactLastName: string | null;
+    contactEmail: string | null;
+    contactPhone: string | null;
+    contactPreferredLanguage: string | null;
+} | null, participants: Array<{
+    email: string | null;
+    isPrimary: boolean;
+    participantType: string;
+    firstName: string;
+    lastName: string;
+}>): {
+    email: string | null;
+    isPrimary: boolean;
+    participantType: string;
+    firstName: string;
+    lastName: string;
+} | null;
+export declare function listBookingNotificationParticipants(db: PostgresJsDatabase, bookingId: string): Promise<{
+    id: string;
+    firstName: string;
+    lastName: string;
+    email: string | null;
+    participantType: "traveler" | "other" | "occupant";
+    isPrimary: boolean;
+}[]>;
+export declare function listBookingNotificationItems(db: PostgresJsDatabase, bookingId: string): Promise<unknown[]>;
+export declare function paginate<T>(rowsPromise: Promise<T[]>, totalPromise: Promise<Array<{
+    total: number;
+}>>, limit: number, offset: number): Promise<{
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}>;
+export declare function buildWhereClause<T extends SQLWrapper>(conditions: Array<T | undefined>): import("drizzle-orm").SQL<unknown> | undefined;
+//# sourceMappingURL=service-shared.d.ts.map

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

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