feat: Redis opportunity cache, CW API retry/logging, adaptive TTLs

- Add Redis-backed opportunity cache with background refresh (30s interval)
- Fix concurrency bug: use lazy thunks instead of eager promises for batching
- Add withCwRetry utility with exponential backoff for transient CW errors
- Add adaptive TTL algorithms (primary, sub-resource, products) based on opportunity activity
- Add include query param on GET /sales/opportunities/:id (notes,contacts,products)
- Add opt-in CW API logger (LOG_CW_API env var) with timestamped files in cw-api-logs/
- Add debug-scripts/analyze-cw-calls.py for API call analysis
- Add computeSubResourceCacheTTL and computeProductsCacheTTL algorithms with tests
- Increase CW API timeout from 15s to 30s
- Unblock cache refresh from startup chain (remove await)
- Prioritize recently updated opportunities in refresh cycle
- Add CACHING.md documentation
- Update API_ROUTES.md with caching details and include param
- Update copilot instructions to require CACHING.md sync
- Add dev:log script for CW API call logging during development

src/api/sales/[id]/addProduct.ts

@@ -53,7 +53,7 @@ export default createRoute(
       ),
     );
 
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
     const created = await item.addProducts(gatedItems);
 
     const isBatch = Array.isArray(body);

src/api/sales/[id]/contacts.ts

@@ -10,7 +10,7 @@ export default createRoute(
   ["/opportunities/:identifier/contacts"],
   async (c) => {
     const identifier = c.req.param("identifier");
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
 
     const data = await item.fetchContacts();
 

src/api/sales/[id]/createNote.ts

@@ -21,7 +21,7 @@ export default createRoute(
 
     const data = schema.parse(body);
 
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
     const user = c.get("user");
 
     const created = await item.addNote(data.text, user.login, {

src/api/sales/[id]/deleteNote.ts

@@ -20,7 +20,7 @@ export default createRoute(
         message: "Note ID must be a number",
       });
 
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
     await item.deleteNote(noteId);
 
     const response = apiResponse.successful(

src/api/sales/[id]/fetch.ts

@@ -5,12 +5,19 @@ import { ContentfulStatusCode } from "hono/utils/http-status";
 import { authMiddleware } from "../../middleware/authorization";
 import { processObjectValuePerms } from "../../../modules/permission-utils/processObjectPermissions";
 
-/* GET /v1/sales/opportunities/:identifier */
+/* GET /v1/sales/opportunities/:identifier?include=notes,contacts,products */
 export default createRoute(
   "get",
   ["/opportunities/:identifier"],
   async (c) => {
     const identifier = c.req.param("identifier");
+    const includeParam = c.req.query("include") ?? "";
+    const includes = new Set(
+      includeParam
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean),
+    );
 
     const item = await opportunities.fetchItem(identifier);
 
@@ -23,6 +30,30 @@ export default createRoute(
       c.get("user"),
     );
 
+    // Fetch requested sub-resources in parallel
+    const subResourcePromises: Record<string, Promise<any>> = {};
+    if (includes.has("notes")) {
+      subResourcePromises.notes = item.fetchNotes();
+    }
+    if (includes.has("contacts")) {
+      subResourcePromises.contacts = item.fetchContacts();
+    }
+    if (includes.has("products")) {
+      subResourcePromises.products = item
+        .fetchProducts()
+        .then((products) => products.map((p) => p.toJson()));
+    }
+
+    const keys = Object.keys(subResourcePromises);
+    if (keys.length > 0) {
+      const results = await Promise.all(
+        keys.map((k) => subResourcePromises[k]),
+      );
+      keys.forEach((k, i) => {
+        (gatedData as any)[k] = results[i];
+      });
+    }
+
     const response = apiResponse.successful(
       "Opportunity fetched successfully!",
       gatedData,

src/api/sales/[id]/fetchNote.ts

@@ -20,7 +20,7 @@ export default createRoute(
         message: "Note ID must be a number",
       });
 
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
     const data = await item.fetchNote(noteId);
 
     const response = apiResponse.successful(

src/api/sales/[id]/notes.ts

@@ -10,7 +10,7 @@ export default createRoute(
   ["/opportunities/:identifier/notes"],
   async (c) => {
     const identifier = c.req.param("identifier");
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
 
     const data = await item.fetchNotes();
 

src/api/sales/[id]/products.ts

@@ -10,7 +10,7 @@ export default createRoute(
   ["/opportunities/:identifier/products"],
   async (c) => {
     const identifier = c.req.param("identifier");
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
 
     const data = await item.fetchProducts();
 

src/api/sales/[id]/resequenceProducts.ts

@@ -21,7 +21,7 @@ export default createRoute(
 
     const { orderedIds } = schema.parse(body);
 
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
     const updated = await item.resequenceProducts(orderedIds);
 
     const response = apiResponse.successful(

src/api/sales/[id]/updateNote.ts

@@ -35,7 +35,7 @@ export default createRoute(
 
     const data = schema.parse(body);
 
-    const item = await opportunities.fetchItem(identifier);
+    const item = await opportunities.fetchRecord(identifier);
     const updated = await item.updateNote(noteId, data);
 
     const response = apiResponse.successful(