fix: remove nested .git folders, re-add as normal directories

api/src/modules/algorithms/algo.coldThreshold.ts

@@ -0,0 +1,102 @@
+/**
+ * @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 {
+  // Bypassed — always returns not-cold until cold-stall feature is ready
+  return { cold: false, triggeredBy: null };
+}

api/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;
+}

api/src/modules/algorithms/computeCacheTTL.ts

@@ -0,0 +1,168 @@
+/**
+ * @module computeCacheTTL
+ *
+ * Adaptive Cache TTL Algorithm
+ * ============================
+ *
+ * Determines how long a cached record should live before it must be
+ * re-fetched from the upstream source (e.g. ConnectWise API).
+ *
+ * The algorithm prioritises freshness for records that are actively
+ * being worked on, while avoiding unnecessary API calls for stale or
+ * inactive data.
+ *
+ * ## Spec
+ *
+ * | # | Condition                                                        | TTL (ms) | TTL (human) | Rationale                                                          |
+ * |---|------------------------------------------------------------------|----------|-------------|--------------------------------------------------------------------|
+ * | 1 | `closedFlag` is `true`                                           | `null`   | Do not cache| Closed records are rarely accessed; caching wastes memory.         |
+ * | 2 | `expectedCloseDate` OR `lastUpdated` is within the last **5 days**| 60 000   | 60 seconds  | High-activity window — data changes frequently and must stay fresh.|
+ * | 3 | `expectedCloseDate` OR `lastUpdated` is within the last **14 days**| 90 000  | 90 seconds  | Moderate activity — still relevant, but changes less often.        |
+ * | 4 | Everything else (older than 14 days)                             | 900 000  | 15 minutes  | Low activity — safe to serve from cache for longer.                |
+ *
+ * ## Evaluation order
+ *
+ * Rules are evaluated **top-to-bottom**; the first matching rule wins.
+ * Rule 2 (5-day window) is a subset of Rule 3 (14-day window), so it
+ * must be checked first.
+ *
+ * ## Inputs
+ *
+ * | Field              | Type             | Description                                                        |
+ * |--------------------|------------------|--------------------------------------------------------------------|
+ * | `closedFlag`       | `boolean`        | Whether the record is closed / inactive.                           |
+ * | `expectedCloseDate`| `Date \| null`   | The projected close date (future-looking relevance signal).        |
+ * | `lastUpdated`      | `Date \| null`   | The last time the upstream record was modified (backward-looking). |
+ * | `now`              | `Date` (optional)| Override for the current timestamp; defaults to `new Date()`.      |
+ *
+ * ## Output
+ *
+ * Returns `number | null`:
+ * - A positive integer representing the TTL in **milliseconds**, or
+ * - `null` when the record should **not** be cached at all.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { computeCacheTTL } from "../modules/algorithms/computeCacheTTL";
+ *
+ * const ttl = computeCacheTTL({
+ *   closedFlag: opportunity.closedFlag,
+ *   expectedCloseDate: opportunity.expectedCloseDate,
+ *   lastUpdated: opportunity.cwLastUpdated,
+ * });
+ *
+ * if (ttl !== null) {
+ *   await redis.set(key, serialised, "PX", ttl);
+ * }
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** 60 seconds – TTL for high-activity records (within 5 days).
+ *  Must exceed the 30-second background refresh interval so the cache
+ *  stays warm between cycles. */
+export const TTL_HIGH_ACTIVITY = 60_000;
+
+/** 90 seconds – TTL for moderate-activity records (within 14 days). */
+export const TTL_MODERATE_ACTIVITY = 90_000;
+
+/** 15 minutes – TTL for low-activity / stale records. */
+export const TTL_LOW_ACTIVITY = 900_000;
+
+/** 30 days in milliseconds. */
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** 5 days in milliseconds. */
+const FIVE_DAYS_MS = 5 * 24 * 60 * 60 * 1000;
+
+/** 14 days in milliseconds. */
+const FOURTEEN_DAYS_MS = 14 * 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Input type
+// ---------------------------------------------------------------------------
+
+export interface CacheTTLInput {
+  /** Whether the record is closed / inactive. */
+  closedFlag: boolean;
+  /** When the record was closed — used for recently-closed caching (within 30 days). */
+  closedDate: Date | null;
+  /** The projected close date — serves as a forward-looking relevance signal. */
+  expectedCloseDate: Date | null;
+  /** The date the upstream record was last modified — backward-looking signal. */
+  lastUpdated: Date | null;
+  /**
+   * Override for the current timestamp.
+   * Useful for deterministic testing. Defaults to `new Date()`.
+   */
+  now?: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Algorithm
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the cache TTL for a record based on its activity signals.
+ *
+ * @param input - The record's activity signals. See {@link CacheTTLInput}.
+ * @returns The TTL in milliseconds, or `null` if the record should not be cached.
+ *
+ * @see Module-level JSDoc for the full spec table and evaluation rules.
+ */
+export function computeCacheTTL(input: CacheTTLInput): number | null {
+  const {
+    closedFlag,
+    closedDate,
+    expectedCloseDate,
+    lastUpdated,
+    now = new Date(),
+  } = input;
+
+  const nowMs = now.getTime();
+
+  /**
+   * Check whether a date falls within a window around `now`.
+   *
+   * "Within" means the date is between `now - windowMs` and `now + windowMs`,
+   * allowing both past updates and future-scheduled dates to qualify.
+   */
+  const isWithinWindow = (date: Date | null, windowMs: number): boolean => {
+    if (!date) return false;
+    const diff = Math.abs(nowMs - date.getTime());
+    return diff <= windowMs;
+  };
+
+  // Rule 1 — Closed records
+  if (closedFlag) {
+    // Rule 1b — Recently closed (within 30 days) → cache at low-activity TTL
+    if (isWithinWindow(closedDate, THIRTY_DAYS_MS)) {
+      return TTL_LOW_ACTIVITY;
+    }
+    // Rule 1a — Closed longer than 30 days → do not cache
+    return null;
+  }
+
+  // Rule 2 — High activity (5 days)
+  if (
+    isWithinWindow(expectedCloseDate, FIVE_DAYS_MS) ||
+    isWithinWindow(lastUpdated, FIVE_DAYS_MS)
+  ) {
+    return TTL_HIGH_ACTIVITY;
+  }
+
+  // Rule 3 — Moderate activity (14 days)
+  if (
+    isWithinWindow(expectedCloseDate, FOURTEEN_DAYS_MS) ||
+    isWithinWindow(lastUpdated, FOURTEEN_DAYS_MS)
+  ) {
+    return TTL_MODERATE_ACTIVITY;
+  }
+
+  // Rule 4 — Low activity / stale
+  return TTL_LOW_ACTIVITY;
+}

api/src/modules/algorithms/computeProductsCacheTTL.ts

@@ -0,0 +1,116 @@
+/**
+ * @module computeProductsCacheTTL
+ *
+ * Adaptive Cache TTL for Opportunity Products
+ * ============================================
+ *
+ * Determines how long products (forecast items) should be cached in
+ * Redis before being re-fetched from ConnectWise.
+ *
+ * Products have unique caching rules compared to notes or contacts
+ * because they are typically finalised before a deal closes and do not
+ * change once the opportunity reaches a terminal status.
+ *
+ * ## Spec
+ *
+ * | # | Condition                                                                    | TTL (ms)   | TTL (human) | Rationale                                                                             |
+ * |---|------------------------------------------------------------------------------|------------|-------------|---------------------------------------------------------------------------------------|
+ * | 1 | Status is **Won**, **Lost**, **Pending Won**, or **Pending Lost**            | `null`     | No cache    | Products on terminal / near-terminal opps are static; no need to keep them warm.      |
+ * | 2 | Opportunity is **not cacheable** (main cache TTL is `null`)                  | `null`     | No cache    | If the opp itself is evicted, sub-resources follow suit.                              |
+ * | 3 | `lastUpdated` is within the last **3 days**                                  | 15 000     | 15 seconds  | Actively-worked deals — products are being edited and need near-real-time freshness.  |
+ * | 4 | Everything else                                                              | 1 200 000  | 20 minutes  | Lazy on-demand cache: fetched when requested, expires after 20 min without refresh.   |
+ *
+ * ## Evaluation order
+ *
+ * Rules are evaluated top-to-bottom; the first matching rule wins.
+ *
+ * ## Inputs
+ *
+ * Extends {@link CacheTTLInput} from `computeCacheTTL` with an
+ * additional `statusCwId` field used to identify terminal statuses.
+ *
+ * ## Output
+ *
+ * Returns `number | null`:
+ * - Positive integer = TTL in **milliseconds**.
+ * - `null` = do **not** cache.
+ */
+
+import type { CacheTTLInput } from "./computeCacheTTL";
+import { computeCacheTTL } from "./computeCacheTTL";
+import { QUOTE_STATUSES } from "../../types/QuoteStatuses";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** 45 seconds — TTL for hot products (opportunity updated within 3 days).
+ *  Must exceed the 30-second background refresh interval so the cache
+ *  stays warm between cycles. */
+export const PRODUCTS_TTL_HOT = 45_000;
+
+/** 20 minutes — TTL for on-demand product cache (lazy fallback). */
+export const PRODUCTS_TTL_LAZY = 1_200_000;
+
+/** 3 days in milliseconds. */
+const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
+
+/**
+ * Set of all CW status IDs that map to a Won or Lost canonical status.
+ *
+ * Built at module load from {@link QUOTE_STATUSES} so it stays in sync
+ * with any future status additions.
+ */
+export const WON_LOST_STATUS_IDS: ReadonlySet<number> = new Set(
+  QUOTE_STATUSES.filter((s) => s.wonFlag || s.lostFlag).flatMap((s) => [
+    s.id,
+    ...s.optimaEquivalency,
+  ]),
+);
+
+// ---------------------------------------------------------------------------
+// Input type
+// ---------------------------------------------------------------------------
+
+export interface ProductsCacheTTLInput extends CacheTTLInput {
+  /** The CW status ID of the opportunity. */
+  statusCwId: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Algorithm
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the cache TTL for an opportunity's products.
+ *
+ * @param input - The opportunity's activity signals plus status ID.
+ * @returns TTL in milliseconds, or `null` if products should not be cached.
+ */
+export function computeProductsCacheTTL(
+  input: ProductsCacheTTLInput,
+): number | null {
+  const { statusCwId, lastUpdated, now = new Date() } = input;
+
+  // Rule 1 — Terminal statuses: Won / Lost / Pending Won / Pending Lost
+  if (statusCwId !== null && WON_LOST_STATUS_IDS.has(statusCwId)) {
+    return null;
+  }
+
+  // Rule 2 — If the opportunity itself is not cacheable, skip products too
+  const mainTTL = computeCacheTTL(input);
+  if (mainTTL === null) {
+    return null;
+  }
+
+  // Rule 3 — Hot: updated within the last 3 days
+  if (lastUpdated) {
+    const diff = Math.abs(now.getTime() - lastUpdated.getTime());
+    if (diff <= THREE_DAYS_MS) {
+      return PRODUCTS_TTL_HOT;
+    }
+  }
+
+  // Rule 4 — Lazy fallback
+  return PRODUCTS_TTL_LAZY;
+}

api/src/modules/algorithms/computeSubResourceCacheTTL.ts

@@ -0,0 +1,118 @@
+/**
+ * @module computeSubResourceCacheTTL
+ *
+ * Adaptive Cache TTL for Opportunity Sub-Resources
+ * =================================================
+ *
+ * Determines how long cached sub-resource data (notes, contacts) should
+ * live before being re-fetched from ConnectWise.
+ *
+ * Sub-resources change less frequently than the opportunity record itself
+ * or its activity feed, so TTLs are longer than the primary cache. The
+ * same activity-signal heuristics are used (expected close date, last
+ * updated, closed status) but with relaxed durations.
+ *
+ * ## Spec
+ *
+ * | # | Condition                                                         | TTL (ms) | TTL (human) | Rationale                                                          |
+ * |---|-------------------------------------------------------------------|----------|-------------|--------------------------------------------------------------------|
+ * | 1 | `closedFlag` is `true` AND closed > 30 days ago                   | `null`   | Do not cache| Old closed records are rarely accessed.                            |
+ * | 1b| `closedFlag` is `true` AND closed within 30 days                  | 300 000  | 5 minutes   | Recently-closed records may still be viewed occasionally.          |
+ * | 2 | `expectedCloseDate` OR `lastUpdated` within **5 days**            | 60 000   | 60 seconds  | Active deals — contacts/notes may still change.                    |
+ * | 3 | `expectedCloseDate` OR `lastUpdated` within **14 days**           | 120 000  | 2 minutes   | Moderate activity — less likely to change.                         |
+ * | 4 | Everything else (older than 14 days)                              | 300 000  | 5 minutes   | Low activity — safe to cache longer.                               |
+ *
+ * ## Evaluation order
+ *
+ * Rules are evaluated top-to-bottom; the first matching rule wins.
+ *
+ * ## Inputs
+ *
+ * Uses the same {@link CacheTTLInput} interface as `computeCacheTTL`.
+ *
+ * ## Output
+ *
+ * Returns `number | null`:
+ * - Positive integer = TTL in **milliseconds**.
+ * - `null` = do **not** cache.
+ */
+
+import type { CacheTTLInput } from "./computeCacheTTL";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** 60 seconds — TTL for high-activity sub-resources (within 5 days). */
+export const SUB_TTL_HIGH_ACTIVITY = 60_000;
+
+/** 2 minutes — TTL for moderate-activity sub-resources (within 14 days). */
+export const SUB_TTL_MODERATE_ACTIVITY = 120_000;
+
+/** 5 minutes — TTL for low-activity / stale sub-resources. */
+export const SUB_TTL_LOW_ACTIVITY = 300_000;
+
+/** 30 days in milliseconds. */
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** 5 days in milliseconds. */
+const FIVE_DAYS_MS = 5 * 24 * 60 * 60 * 1000;
+
+/** 14 days in milliseconds. */
+const FOURTEEN_DAYS_MS = 14 * 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Algorithm
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the cache TTL for an opportunity sub-resource (notes, contacts).
+ *
+ * @param input - The opportunity's activity signals. See {@link CacheTTLInput}.
+ * @returns The TTL in milliseconds, or `null` if the data should not be cached.
+ */
+export function computeSubResourceCacheTTL(
+  input: CacheTTLInput,
+): number | null {
+  const {
+    closedFlag,
+    closedDate,
+    expectedCloseDate,
+    lastUpdated,
+    now = new Date(),
+  } = input;
+
+  const nowMs = now.getTime();
+
+  const isWithinWindow = (date: Date | null, windowMs: number): boolean => {
+    if (!date) return false;
+    return Math.abs(nowMs - date.getTime()) <= windowMs;
+  };
+
+  // Rule 1 — Closed records
+  if (closedFlag) {
+    if (isWithinWindow(closedDate, THIRTY_DAYS_MS)) {
+      return SUB_TTL_LOW_ACTIVITY;
+    }
+    return null;
+  }
+
+  // Rule 2 — High activity (5 days)
+  if (
+    isWithinWindow(expectedCloseDate, FIVE_DAYS_MS) ||
+    isWithinWindow(lastUpdated, FIVE_DAYS_MS)
+  ) {
+    return SUB_TTL_HIGH_ACTIVITY;
+  }
+
+  // Rule 3 — Moderate activity (14 days)
+  if (
+    isWithinWindow(expectedCloseDate, FOURTEEN_DAYS_MS) ||
+    isWithinWindow(lastUpdated, FOURTEEN_DAYS_MS)
+  ) {
+    return SUB_TTL_MODERATE_ACTIVITY;
+  }
+
+  // Rule 4 — Low activity / stale
+  return SUB_TTL_LOW_ACTIVITY;
+}