@opsrev/acculynx-cli 1.17.0 → 1.18.0

package/README.md

@@ -140,6 +140,25 @@ JOB_ID=$(acculynx jobs list --limit 1 | jq -r '.[0].id')
 acculynx jobs get "$JOB_ID" | jq .
 ```
 
+### Prospect aging with complete readable rows
+
+```bash
+acculynx jobs scan --report prospect-aging --as-of 2026-10-20 --exclude-trade-type "Maintenance Program"
+```
+
+This bounded GET-only report ages **current** Prospect inventory by its full
+milestone date in America/New_York, with inclusive 0–30, 31–60, 61–90 and 91+
+calendar-day buckets. It is not a historical inventory snapshot. Exclusions use
+exact case-insensitive trade-type names; missing classification stays unknown.
+Every eligible row includes its full ID, date, age and separate approved/worksheet
+values in exact cents. Missing values remain unavailable rather than zero.
+
+Enumeration is strict and capped at 5,000 jobs before per-job financial reads.
+No history, payment, message or write requests are made. Invalid/incomplete
+inventory withholds totals and rows; missing dates or financial evidence make
+the result partial (exit 3). Incompatible filters and output modes fail before
+provider access (exit 2). Read long stdout through bounded process-log pages.
+
 ### Monitoring scans: payments with strict coverage
 
 Scan every job in a set of milestones and fetch each one's received payments in

package/dist/index.js

@@ -60,6 +60,8 @@ import { writeFileSync } from "fs";
 // src/ops/scan.ts
 var PAGE_SIZE = 25;
 async function scanJobs(client, filters, options = {}) {
+  if (options.maxJobs !== void 0 && (!Number.isSafeInteger(options.maxJobs) || options.maxJobs < 1))
+    throw new Error("maxJobs must be a positive integer");
   const params = { includes: "contact", sortBy: "CreatedDate" };
   if (filters.startDate) params.startDate = filters.startDate;
   if (filters.endDate) params.endDate = filters.endDate;
@@ -97,6 +99,11 @@ async function scanJobs(client, filters, options = {}) {
         pageError = "changing_inventory";
         break;
       }
+      if (options.maxJobs !== void 0 && page.count > options.maxJobs) {
+        serverCount = page.count;
+        pageError = "report_job_limit";
+        break;
+      }
       let invalidId = false;
       for (const item of page.items) {
         const id = item !== null && typeof item === "object" ? item.id : void 0;
@@ -416,6 +423,172 @@ function marketingEvidence(report, capturedAt = (/* @__PURE__ */ new Date()).toI
   };
 }
 
+// src/ops/scan-aging.ts
+var AGING_TIME_ZONE = "America/New_York";
+var MAX_AGING_JOBS = 5e3;
+var AGING_BUCKETS = ["0\u201330", "31\u201360", "61\u201390", "91+"];
+var clean = (v, max = 200) => typeof v === "string" ? v.replace(/[\u0000-\u001f\u007f|]/g, " ").replace(/\s+/g, " ").trim().slice(0, max) : "";
+var normalized = (v) => v.trim().replace(/\s+/g, " ").toLowerCase();
+function calendarDay(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number(value.slice(0, 4)) < 1e3) return null;
+  const time = Date.parse(value + "T00:00:00Z");
+  return Number.isFinite(time) && new Date(time).toISOString().slice(0, 10) === value ? value : null;
+}
+function milestoneDay(value) {
+  if (typeof value !== "string") return null;
+  if (calendarDay(value)) return value;
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) || !calendarDay(value.slice(0, 10))) return null;
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) return null;
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: AGING_TIME_ZONE,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(time);
+  const part = (type) => parts.find((p) => p.type === type).value;
+  return `${part("year")}-${part("month")}-${part("day")}`;
+}
+function agingClassification(job, exclusions) {
+  const types = job.tradeTypes;
+  if (!Array.isArray(types)) return exclusions.length ? "unknown" : "included";
+  const names = types.map((t) => t && typeof t === "object" ? t.name : void 0);
+  if (names.some((n) => typeof n === "string" && exclusions.some((e) => normalized(e) === normalized(n)))) return "excluded";
+  return exclusions.length && names.some((n) => typeof n !== "string" || !n.trim()) ? "unknown" : "included";
+}
+function amount(value, issues) {
+  if (value === null || value === void 0) return null;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    issues.push("invalid_financial_value");
+    return null;
+  }
+  const cents = Math.round(value * 100);
+  if (!Number.isSafeInteger(cents) || Math.abs(value * 100 - cents) > 1e-5) {
+    issues.push("invalid_financial_value");
+    return null;
+  }
+  return cents;
+}
+function row(entry, asOf, exclusions) {
+  const job = entry.job, issues = [];
+  const classification = agingClassification(job, exclusions);
+  const address = job.locationAddress && typeof job.locationAddress === "object" ? job.locationAddress : {};
+  const contacts = Array.isArray(job.contacts) ? job.contacts : [];
+  const primary = contacts.find((c) => c && c.isPrimary === true)?.contact;
+  const name = primary ? [clean(primary.firstName), clean(primary.lastName)].filter(Boolean).join(" ") : clean(job.jobName);
+  const result = {
+    id: String(job.id),
+    name: name || "\u2014",
+    address: [clean(address.street1), clean(address.city)].filter(Boolean).join(", ") || "\u2014",
+    milestoneDate: null,
+    ageDays: null,
+    bucket: null,
+    classification,
+    approvedCents: null,
+    worksheetCents: null,
+    issues
+  };
+  if (classification === "excluded") return result;
+  if (classification === "unknown") {
+    issues.push("unknown_trade_classification");
+    return result;
+  }
+  if (normalized(String(job.currentMilestone ?? "")) !== "prospect") issues.push("unexpected_milestone");
+  const day = milestoneDay(job.milestoneDate);
+  if (!day) issues.push("missing_or_invalid_milestone_date");
+  else if (day > asOf) issues.push("future_milestone_date");
+  else if (!issues.length) {
+    result.milestoneDate = day;
+    result.ageDays = Math.round((Date.parse(asOf + "T00:00:00Z") - Date.parse(day + "T00:00:00Z")) / 864e5);
+    const age = result.ageDays;
+    result.bucket = age <= 30 ? "0\u201330" : age <= 60 ? "31\u201360" : age <= 90 ? "61\u201390" : "91+";
+  }
+  if (entry.errors.some((e) => e.source === "financials") || !entry.financials) issues.push("financials_unavailable");
+  else {
+    result.approvedCents = amount(entry.financials.approvedJobValue, issues);
+    result.worksheetCents = amount(entry.financials.worksheetTotal, issues);
+    if (result.approvedCents === null && result.worksheetCents === null) issues.push("financial_values_unavailable");
+  }
+  result.issues = [...new Set(issues)];
+  return result;
+}
+function prospectAging(report, asOf, exclusions) {
+  if (!calendarDay(asOf)) throw new Error("--as-of must be a real YYYY-MM-DD date");
+  if (exclusions.length > 10 || exclusions.some((e) => !e.trim() || e.length > 100 || /[\r\n\u0000]/.test(e)))
+    throw new Error("Use at most ten nonempty trade-type exclusions of at most 100 characters");
+  const result = {
+    schema: "acculynx-prospect-aging/v1",
+    asOf,
+    timeZone: AGING_TIME_ZONE,
+    exclusions,
+    status: "partial",
+    scanned: report.scanned,
+    serverCount: report.serverCount ?? null,
+    issues: [],
+    counts: null,
+    rows: []
+  };
+  const ids = /* @__PURE__ */ new Set();
+  for (const { job } of report.jobs) {
+    if (typeof job.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(job.id) || ids.has(job.id))
+      result.issues.push("duplicate_or_missing_job_id");
+    else ids.add(job.id);
+  }
+  if (!report.complete || report.pageError || !Number.isSafeInteger(report.serverCount) || report.serverCount !== report.scanned || report.scanned !== report.jobs.length)
+    result.issues.push("incomplete_inventory");
+  if (report.jobs.length > MAX_AGING_JOBS) result.issues.push("report_job_limit");
+  if (result.issues.length) {
+    result.issues = [...new Set(result.issues)];
+    return result;
+  }
+  result.rows = report.jobs.map((e) => row(e, asOf, exclusions));
+  const counts = {
+    excluded: 0,
+    eligible: 0,
+    unknownClassification: 0,
+    unknownAge: 0,
+    buckets: Object.fromEntries(AGING_BUCKETS.map((b) => [b, 0]))
+  };
+  for (const r of result.rows) {
+    if (r.classification === "excluded") counts.excluded++;
+    else if (r.classification === "unknown") counts.unknownClassification++;
+    else {
+      counts.eligible++;
+      if (r.bucket) counts.buckets[r.bucket]++;
+      else counts.unknownAge++;
+    }
+  }
+  result.counts = counts;
+  result.status = result.rows.some((r) => r.issues.length) ? "partial" : "complete";
+  return result;
+}
+function formatProspectAging(report) {
+  const lines = [
+    `PROSPECT AGING ${report.status.toUpperCase()} \xB7 age as of ${report.asOf} (${report.timeZone})`,
+    "Current Prospect inventory; this is not a historical inventory snapshot.",
+    `jobs ${report.scanned}/${report.serverCount ?? "?"} (server count ${report.serverCount ?? "?"})`,
+    `Excluded trade types (exact names): ${report.exclusions.map((e) => clean(e)).join(", ") || "none"}`
+  ];
+  const c = report.counts;
+  if (!c) return [...lines, `Query unavailable or incomplete: ${report.issues.join(", ")}. No aging totals or rows are asserted.`].join("\n");
+  lines.push(
+    `Eligible ${c.eligible} \xB7 excluded ${c.excluded} \xB7 unknown classification ${c.unknownClassification}`,
+    ...AGING_BUCKETS.map((b) => `${b} days: ${c.buckets[b]}`),
+    `Unknown age: ${c.unknownAge}`,
+    "Approved recorded values and worksheet estimates are separate; neither is collected cash."
+  );
+  const money2 = (c2) => c2 === null ? "unavailable" : new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(c2 / 100);
+  for (const group of [...AGING_BUCKETS, "Unknown"]) {
+    const rows = report.rows.filter((r) => r.classification !== "excluded" && (group === "Unknown" ? !r.bucket : r.bucket === group));
+    if (!rows.length) continue;
+    lines.push(`
+${group} (${rows.length})`);
+    for (const r of rows) lines.push(`${r.id} | ${r.name} | ${r.address} | Prospect date ${r.milestoneDate ?? "unknown"} | age ${r.ageDays ?? "unknown"} | approved ${money2(r.approvedCents)} | estimate ${money2(r.worksheetCents)}${r.issues.length ? " | " + r.issues.join(", ") : ""}`);
+  }
+  lines.push(`Rows shown ${report.rows.filter((r) => r.classification !== "excluded").length}; excluded rows are omitted.`);
+  return lines.join("\n");
+}
+
 // src/commands/jobs.ts
 function collect(value, previous) {
   return [...previous, value];
@@ -437,7 +610,40 @@ function registerJobsCommands(parentCmd, getClient2) {
     });
     console.log(JSON.stringify(result));
   });
-  jobs.command("scan").description("Fetch ALL matching jobs and print a digest with a coverage receipt").option("--start-date <date>", "Start date (YYYY-MM-DD)").option("--end-date <date>", "End date (YYYY-MM-DD)").option("--date-filter-type <type>", "Date field to filter on").option("--milestones <milestones>", "Filter by milestones (comma-separated)").option("--assignment <type>", "Filter by assignment: assigned, unassigned").option("--trade-type <name>", "Client-side trade-type filter (repeatable)", collect, []).option("--enrich <list>", "Comma-separated: financials,reps,dates,messages,payments").option("--format <fmt>", "digest, jsonl, or marketing-evidence (private operator data)", "digest").option("--out <path>", "Also write full jsonl to this file").option("--strict", 'Strict coverage: any pagination anomaly makes the scan partial (exit 3), and jsonl output ends with a {"type":"coverage"} line. Implied by --enrich payments').action(async (opts) => {
+  jobs.command("scan").description("Fetch ALL matching jobs and print a digest with a coverage receipt").option("--start-date <date>", "Start date (YYYY-MM-DD)").option("--end-date <date>", "End date (YYYY-MM-DD)").option("--date-filter-type <type>", "Date field to filter on").option("--milestones <milestones>", "Filter by milestones (comma-separated)").option("--assignment <type>", "Filter by assignment: assigned, unassigned").option("--trade-type <name>", "Client-side trade-type filter (repeatable)", collect, []).option("--enrich <list>", "Comma-separated: financials,reps,dates,messages,payments").option("--format <fmt>", "digest, jsonl, or marketing-evidence (private operator data)", "digest").option("--out <path>", "Also write full jsonl to this file").option("--strict", 'Strict coverage: any pagination anomaly makes the scan partial (exit 3), and jsonl output ends with a {"type":"coverage"} line. Implied by --enrich payments').option("--report <name>", "Bounded readable report: prospect-aging").option("--as-of <date>", "Aging calendar date (YYYY-MM-DD), America/New_York").option("--exclude-trade-type <name>", "Exact trade-type name to exclude from prospect-aging (repeatable)", collect, []).action(async (opts) => {
+    if (opts.report || opts.asOf || opts.excludeTradeType.length) {
+      const enrichInput = String(opts.enrich ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+      if (opts.report !== "prospect-aging" || !calendarDay(String(opts.asOf ?? "")) || opts.out || opts.format !== "digest" || opts.tradeType.length || opts.startDate || opts.endDate || opts.dateFilterType || opts.assignment || opts.milestones && opts.milestones.toLowerCase() !== "prospect" || enrichInput.some((e) => !["financials"].includes(e))) {
+        console.error("prospect-aging requires --as-of YYYY-MM-DD and current Prospect inventory; format/out, date/assignment/include-trade filters and other enrichers are unavailable");
+        process.exitCode = 2;
+        return;
+      }
+      try {
+        prospectAging({ filters: {}, enrich: [], jobs: [], scanned: 0, serverCount: 0, complete: true }, opts.asOf, opts.excludeTradeType);
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : "Invalid aging options");
+        process.exitCode = 2;
+        return;
+      }
+      const filters2 = { milestones: "Prospect" };
+      const client = getClient2();
+      const result2 = await scanJobs(client, filters2, { strict: true, maxJobs: MAX_AGING_JOBS });
+      const selected = result2.complete ? result2.jobs.filter((j) => agingClassification(j, opts.excludeTradeType) === "included") : [];
+      const enriched = await enrichJobs(client, selected, ["financials"]);
+      const byId = new Map(enriched.map((e) => [e.job.id, e]));
+      const report2 = prospectAging({
+        filters: filters2,
+        enrich: ["financials"],
+        jobs: result2.jobs.map((job) => byId.get(job.id) ?? { job, errors: [] }),
+        scanned: result2.scanned,
+        serverCount: result2.serverCount,
+        complete: result2.complete,
+        pageError: result2.pageError
+      }, opts.asOf, opts.excludeTradeType);
+      console.log(formatProspectAging(report2));
+      if (report2.status !== "complete") process.exitCode = 3;
+      return;
+    }
     const enrich = String(opts.enrich ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     const badEnricher = enrich.find((e) => !ENRICHERS.includes(e));
     if (badEnricher) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsrev/acculynx-cli",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "AccuLynx MCP server & CLI — use the AccuLynx roofing CRM in Claude Desktop, Cursor, and any MCP client. Also a JSON CLI for scripts and AI agents.",
   "repository": {
     "type": "git",