feat: add opportunity workflows, delete routes, company sites, algorithms, and expanded test coverage

src/modules/algorithms/algo.coldThreshold.ts

@@ -0,0 +1,123 @@
+/**
+ * @module algo.coldThreshold
+ *
+ * Cold-Detection Algorithm
+ * ========================
+ *
+ * Determines whether an opportunity has stalled in a status long enough
+ * to be considered "cold". When an opportunity goes cold it is
+ * automatically moved to InternalReview, a system-generated activity is
+ * logged, and it is flagged for the internal review report.
+ *
+ * ## Thresholds (defaults)
+ *
+ * | Status          | Stall Threshold |
+ * |-----------------|-----------------|
+ * | QuoteSent       | 14 days         |
+ * | ConfirmedQuote  | 30 days         |
+ *
+ * Only these two statuses are eligible for cold detection. All other
+ * statuses return `cold: false`.
+ *
+ * ## How "last activity date" is determined
+ *
+ * The algorithm uses `lastActivityDate` — the most recent of:
+ *   - the latest activity's `dateStart`
+ *   - the opportunity's `cwLastUpdated`
+ *
+ * The caller is responsible for resolving this value before calling
+ * `checkColdStatus`.
+ */
+
+import type { OpportunityController } from "../../controllers/OpportunityController";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/** Stall thresholds in milliseconds, keyed by CW status ID. */
+export const COLD_THRESHOLDS: Record<number, { days: number; ms: number }> = {
+  /** QuoteSent — CW status ID 43, "03. Quote Sent" */
+  43: { days: 14, ms: 14 * 24 * 60 * 60 * 1000 },
+
+  /** ConfirmedQuote — CW status ID 57, "04. Confirmed Quote" */
+  57: { days: 30, ms: 30 * 24 * 60 * 60 * 1000 },
+};
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ColdCheckInput {
+  /** Current CW status ID of the opportunity. */
+  statusCwId: number | null;
+
+  /**
+   * The most recent meaningful date to measure staleness from.
+   * Typically the latest of the last activity dateStart or cwLastUpdated.
+   */
+  lastActivityDate: Date | null;
+
+  /** Override for "now" — useful for testing. Defaults to `new Date()`. */
+  now?: Date;
+}
+
+export interface ColdCheckResult {
+  /** Whether the opportunity is considered cold. */
+  cold: boolean;
+
+  /**
+   * Which threshold triggered the cold flag.
+   * `null` when `cold` is `false`.
+   */
+  triggeredBy: {
+    statusCwId: number;
+    statusName: string;
+    thresholdDays: number;
+    staleDays: number;
+  } | null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const STATUS_NAMES: Record<number, string> = {
+  43: "QuoteSent",
+  57: "ConfirmedQuote",
+};
+
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate whether an opportunity has exceeded its cold-stall threshold.
+ *
+ * @returns A `ColdCheckResult` indicating cold status and trigger metadata.
+ */
+export function checkColdStatus(input: ColdCheckInput): ColdCheckResult {
+  const NOT_COLD: ColdCheckResult = { cold: false, triggeredBy: null };
+
+  if (!input.statusCwId) return NOT_COLD;
+
+  const threshold = COLD_THRESHOLDS[input.statusCwId];
+  if (!threshold) return NOT_COLD;
+
+  if (!input.lastActivityDate) return NOT_COLD;
+
+  const now = input.now ?? new Date();
+  const elapsed = now.getTime() - input.lastActivityDate.getTime();
+
+  if (elapsed < threshold.ms) return NOT_COLD;
+
+  return {
+    cold: true,
+    triggeredBy: {
+      statusCwId: input.statusCwId,
+      statusName: STATUS_NAMES[input.statusCwId] ?? "Unknown",
+      thresholdDays: threshold.days,
+      staleDays: Math.floor(elapsed / (24 * 60 * 60 * 1000)),
+    },
+  };
+}

src/modules/algorithms/algo.followUpScheduler.ts

@@ -0,0 +1,97 @@
+/**
+ * @module algo.followUpScheduler
+ *
+ * Follow-Up Scheduling Algorithm
+ * ===============================
+ *
+ * Determines the due date for follow-up activities created by the
+ * opportunity workflow. The follow-up is always assigned to the user
+ * who triggered its creation.
+ *
+ * ## TODO — Calendar-aware scheduling
+ *
+ * This module currently uses a **dummy algorithm** that schedules the
+ * follow-up for the next business day at 10:00 AM local time.
+ *
+ * It needs to be replaced with an availability-aware algorithm that:
+ *   1. Reads the assigned user's calendar (Microsoft Graph / CW schedule).
+ *   2. Finds the earliest open slot of sufficient duration.
+ *   3. Respects company-wide blackout dates (holidays, company events).
+ *   4. Accounts for the user's working-hours preferences.
+ *
+ * Until that integration is complete, the simple "next business day"
+ * heuristic is used as a placeholder.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FollowUpScheduleInput {
+  /** The user who triggered the activity (follow-up is assigned to them). */
+  triggeredByUserId: string;
+
+  /** Optional override for "now" — useful for testing. */
+  now?: Date;
+}
+
+export interface FollowUpScheduleResult {
+  /** Suggested due date for the follow-up activity. */
+  dueDate: Date;
+
+  /** ISO string version for CW API payloads. */
+  dueDateIso: string;
+}
+
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
+/**
+ * Schedule a follow-up activity.
+ *
+ * Returns a suggested `dueDate` for the follow-up activity.
+ * Currently uses dummy logic: next business day at 10:00 AM.
+ *
+ * @param input - Scheduling parameters
+ * @returns The scheduled follow-up date
+ */
+export function scheduleFollowUp(
+  input: FollowUpScheduleInput,
+): FollowUpScheduleResult {
+  const now = input.now ?? new Date();
+  const dueDate = getNextBusinessDay(now);
+
+  // Set to 10:00 AM
+  dueDate.setHours(10, 0, 0, 0);
+
+  return {
+    dueDate,
+    dueDateIso: dueDate.toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the next business day (Mon–Fri) from the given date.
+ * If the given date is already a weekday before 10 AM, returns
+ * the NEXT business day (not the same day).
+ */
+function getNextBusinessDay(from: Date): Date {
+  const result = new Date(from);
+
+  // Always advance at least one day
+  result.setDate(result.getDate() + 1);
+
+  const day = result.getDay();
+
+  // Saturday → Monday (+2)
+  if (day === 6) result.setDate(result.getDate() + 2);
+  // Sunday → Monday (+1)
+  if (day === 0) result.setDate(result.getDate() + 1);
+
+  return result;
+}