@opsrev/acculynx-cli 1.15.0 → 1.17.0

package/README.md

@@ -140,6 +140,34 @@ JOB_ID=$(acculynx jobs list --limit 1 | jq -r '.[0].id')
 acculynx jobs get "$JOB_ID" | jq .
 ```
 
+### Monitoring scans: payments with strict coverage
+
+Scan every job in a set of milestones and fetch each one's received payments in
+one process, with a coverage line a script can check:
+
+```bash
+acculynx jobs scan --milestones Approved,Completed,Invoiced \
+  --enrich payments --strict --format jsonl --out payments.jsonl
+```
+
+Each job line carries `payments`: the job's full received-payment objects
+(`id`, `from`, `amount`, `paymentDate`, `checkNumber`, `notes`, …). The last
+line is the coverage receipt:
+
+```json
+{"type":"coverage","scanned":299,"serverCount":299,"complete":true,"pageError":null,"enrichErrors":0}
+```
+
+- `--strict` (implied by `--enrich payments`) treats any pagination anomaly
+  (changing total, duplicate job IDs, overfull or malformed pages) as a partial
+  scan. Partial scans exit 3 and report `complete: false`. Never treat them as
+  a full inventory.
+- A per-job payments failure doesn't abort the scan. It appears in that job's
+  `errors` (`{"jobId", "source": "payments", "message"}`) and counts toward
+  `enrichErrors`, so retry just those jobs with `acculynx jobs payments <id>`.
+- Without `--strict` and without `payments`, `jsonl` output is unchanged: job
+  lines only.
+
 ## Development
 
 ```bash
@@ -159,3 +187,36 @@ npm run dev -- jobs list --limit 5
 ## License
 
 MIT
+
+### Private marketing evidence from a native scan
+
+Operators preparing approval-date reconciliation can preserve exact source
+fields without parsing the rounded human digest:
+
+```bash
+acculynx jobs scan --start-date 2026-07-01 --end-date 2026-09-04 --date-filter-type ModifiedDate --enrich dates,financials --format marketing-evidence
+```
+
+This emits one `acculynx-marketing-evidence/v1` JSON object. It is **private
+operator evidence** containing full job IDs and individual values; do not post
+it in a vendor/customer channel. It excludes contacts, addresses, names,
+notes, documents, unrelated financials and raw provider error bodies.
+`--out` and other enrichers are rejected before reading. Redirect stdout only
+into an appropriately protected operator workspace if retaining the artifact.
+This format does not alter downstream agents' command allowlists or authorize
+them to export records.
+
+The receipt distinguishes query completeness from enrichment completeness.
+Strict pagination requires a numeric stable total, advancing offsets and unique
+job IDs. Exit 3 means partial evidence; never publish it as a complete result.
+Full source dates are preserved without timezone conversion, repeated approval
+milestones remain separate, and current approved value is represented in exact
+cents. Missing/invalid values and dates remain null with issue codes.
+
+This is not an approval cohort, an original-acquisition attribution, a complete
+lead-delivery inventory or historical revenue. ModifiedDate is a candidate
+filter; confirm historical and unassigned/dead-lead coverage separately. Review
+source date semantics, repeated approvals, transfers and current-versus-original
+contract value before producing normalized results. A large historical scan
+reads history and financials for each candidate; bootstrap it separately from
+short daily marketing jobs, then validate an incremental refresh strategy.

package/dist/{chunk-MQDU6DIH.js → chunk-STEYTGZE.js}

@@ -179,6 +179,9 @@ async function paginate(client, path, params, limit = DEFAULT_LIMIT) {
     if (data.items.length < DEFAULT_PAGE_SIZE) {
       break;
     }
+    if (typeof data.count === "number" && pageStartIndex + DEFAULT_PAGE_SIZE >= data.count) {
+      break;
+    }
     pageStartIndex += DEFAULT_PAGE_SIZE;
   }
   return results;

package/dist/index.js

@@ -40,7 +40,7 @@ import {
   resolveTradeTypeIds,
   resolveWorkTypeId,
   usersList
-} from "./chunk-MQDU6DIH.js";
+} from "./chunk-STEYTGZE.js";
 
 // src/index.ts
 import { createRequire } from "module";
@@ -59,7 +59,7 @@ import { writeFileSync } from "fs";
 
 // src/ops/scan.ts
 var PAGE_SIZE = 25;
-async function scanJobs(client, filters) {
+async function scanJobs(client, filters, options = {}) {
   const params = { includes: "contact", sortBy: "CreatedDate" };
   if (filters.startDate) params.startDate = filters.startDate;
   if (filters.endDate) params.endDate = filters.endDate;
@@ -70,6 +70,7 @@ async function scanJobs(client, filters) {
   let serverCount;
   let pageError;
   let pageStartIndex = 0;
+  const seen = /* @__PURE__ */ new Set();
   while (true) {
     let data;
     try {
@@ -82,6 +83,42 @@ async function scanJobs(client, filters) {
       pageError = error instanceof Error ? error.message : String(error);
       break;
     }
+    if (options.strict) {
+      const page = data;
+      if (page === null || typeof page !== "object") {
+        pageError = "invalid_page";
+        break;
+      }
+      if (!Number.isSafeInteger(page.count) || page.count < 0 || !Array.isArray(page.items) || page.items.length > PAGE_SIZE || page.pageStartIndex !== pageStartIndex) {
+        pageError = "invalid_page";
+        break;
+      }
+      if (serverCount !== void 0 && serverCount !== page.count) {
+        pageError = "changing_inventory";
+        break;
+      }
+      let invalidId = false;
+      for (const item of page.items) {
+        const id = item !== null && typeof item === "object" ? item.id : void 0;
+        if (typeof id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(id) || seen.has(id)) {
+          invalidId = true;
+          break;
+        }
+        seen.add(id);
+      }
+      if (invalidId) {
+        pageError = "duplicate_or_missing_job_id";
+        break;
+      }
+      if (fetched.length + page.items.length > page.count) {
+        pageError = "count_mismatch";
+        break;
+      }
+      if (pageStartIndex >= 5e4) {
+        pageError = "page_limit";
+        break;
+      }
+    }
     if (serverCount === void 0 && typeof data.count === "number") serverCount = data.count;
     const items = Array.isArray(data.items) ? data.items : [];
     fetched.push(...items);
@@ -102,7 +139,7 @@ async function scanJobs(client, filters) {
   });
   return { jobs, scanned: fetched.length, serverCount, complete, ...pageError ? { pageError } : {} };
 }
-var ENRICHERS = ["financials", "reps", "dates", "messages"];
+var ENRICHERS = ["financials", "reps", "dates", "messages", "payments"];
 var asRecord = (v) => v !== null && typeof v === "object" ? v : {};
 async function defaultLoadMessagesTool() {
   const { createRequire: createRequire2 } = await import("module");
@@ -148,7 +185,8 @@ async function enrichJobs(client, jobs, enrich, concurrency = 5, deps = {}) {
           entry.reps = reps;
         } else if (source === "dates") {
           const m = asRecord(await jobMilestones(client, jobId));
-          entry.dates = (m.items ?? []).map((i) => ({
+          if (!Array.isArray(m.items) || m.items.some((i) => i === null || typeof i !== "object")) throw new Error("invalid_milestone_history");
+          entry.dates = m.items.map((i) => ({
             name: String(i.name ?? ""),
             date: String(i.date ?? "")
           }));
@@ -163,6 +201,12 @@ async function enrichJobs(client, jobs, enrich, concurrency = 5, deps = {}) {
             by: String(msg.createdBy ?? ""),
             text: String(msg.message ?? "").replace(/\s+/g, " ").trim().slice(0, 200)
           }));
+        } else if (source === "payments") {
+          const received = asRecord(asRecord(await jobPayments(client, jobId)).receivedPayments);
+          if (!Array.isArray(received.payments) || received.payments.some((p) => p === null || typeof p !== "object")) {
+            throw new Error("invalid_payments");
+          }
+          entry.payments = received.payments;
         }
       } catch (error) {
         entry.errors.push({ jobId, source, message: error instanceof Error ? error.message : String(error) });
@@ -250,7 +294,7 @@ function jobLine(entry, enrich) {
   const date = mmdd(job.milestoneDate);
   let line = `${id8} | ${name} \u2014 ${street}, ${city} | ${milestone} ${date}`;
   const erroredSources = new Set(entry.errors.map((e) => e.source));
-  for (const source of ["reps", "financials", "dates"]) {
+  for (const source of ["reps", "financials", "dates", "payments"]) {
     if (!enrich.includes(source)) continue;
     if (erroredSources.has(source)) {
       line += ` | ERR:${source}`;
@@ -267,6 +311,10 @@ function jobLine(entry, enrich) {
     } else if (source === "dates") {
       const approved = entry.dates?.find((d) => d.name === "Approved");
       line += ` | appr\u2019d ${approved ? mmdd(approved.date) : "-"}`;
+    } else if (source === "payments") {
+      const payments = entry.payments ?? [];
+      const total = payments.reduce((sum, p) => sum + (typeof p.amount === "number" ? p.amount : 0), 0);
+      line += ` | paid ${money(total)} (${payments.length})`;
     }
   }
   return line;
@@ -293,8 +341,79 @@ function formatScanDigest(report) {
   }
   return lines.join("\n");
 }
-function formatScanJsonl(report) {
-  return report.jobs.map((j) => JSON.stringify(j)).join("\n");
+function coverageLine(report) {
+  return JSON.stringify({
+    type: "coverage",
+    scanned: report.scanned,
+    serverCount: report.serverCount ?? null,
+    complete: report.complete,
+    pageError: report.pageError ?? null,
+    enrichErrors: report.jobs.reduce((sum, j) => sum + j.errors.length, 0)
+  });
+}
+function formatScanJsonl(report, options = {}) {
+  const lines = report.jobs.map((j) => JSON.stringify(j));
+  if (options.receipt) lines.push(coverageLine(report));
+  return lines.join("\n");
+}
+
+// src/ops/scan-marketing.ts
+function marketingEvidence(report, capturedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+  const ids = /* @__PURE__ */ new Set();
+  let uniqueIds = true;
+  const jobs = report.jobs.map((entry) => {
+    const issues = [];
+    const id = typeof entry.job.id === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(entry.job.id) ? entry.job.id : null;
+    if (!id) issues.push("invalid_job_id");
+    else if (ids.has(id)) {
+      uniqueIds = false;
+      issues.push("duplicate_job_id");
+    } else ids.add(id);
+    const date = (value2, field) => {
+      if (typeof value2 === "string" && /^\d{4}-\d{2}-\d{2}(?:T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:0\d|1[0-4]):[0-5]\d))?$/.test(value2) && Number.isFinite(Date.parse(value2)) && (/* @__PURE__ */ new Date(value2.slice(0, 10) + "T00:00:00Z")).toISOString().slice(0, 10) === value2.slice(0, 10)) return value2;
+      issues.push("invalid_" + field);
+      return null;
+    };
+    const label = (value2) => typeof value2 === "string" && value2.length > 0 && value2.length <= 200 ? value2 : null;
+    const failed = new Set(entry.errors.map((e) => e.source));
+    for (const source of ["financials", "dates"]) if (failed.has(source)) issues.push(source + "_read_failed");
+    let approvedValueCents = null;
+    const value = entry.financials?.approvedJobValue;
+    if (!failed.has("financials") && typeof value === "number" && Number.isFinite(value) && value >= 0 && Number.isSafeInteger(Math.round(value * 100)) && Math.abs(value * 100 - Math.round(value * 100)) <= 1e-6) approvedValueCents = Math.round(value * 100);
+    else issues.push("approved_value_unavailable");
+    let milestones = null;
+    if (!failed.has("dates") && Array.isArray(entry.dates)) {
+      milestones = entry.dates.map((d) => {
+        const name = label(d.name);
+        if (!name) issues.push("invalid_milestone_name");
+        return { name, sourceDate: date(d.date, "milestone_date") };
+      });
+    } else issues.push("milestone_history_unavailable");
+    return {
+      id,
+      createdDate: date(entry.job.createdDate, "created_date"),
+      modifiedDate: date(entry.job.modifiedDate, "modified_date"),
+      currentMilestone: label(entry.job.currentMilestone),
+      workType: label(record(entry.job.workType).name),
+      tradeTypes: Array.isArray(entry.job.tradeTypes) ? entry.job.tradeTypes.map((t) => label(record(t).name)).filter((v) => v !== null) : [],
+      milestones,
+      currentApprovedValueCents: approvedValueCents,
+      issues: [...new Set(issues)]
+    };
+  });
+  const queryComplete = report.complete && Number.isSafeInteger(report.serverCount) && report.serverCount >= 0 && report.scanned === report.serverCount && uniqueIds && jobs.every((j) => j.id !== null);
+  const enrichmentComplete = report.enrich.includes("dates") && report.enrich.includes("financials") && jobs.every((j) => j.issues.length === 0);
+  return {
+    schemaVersion: "acculynx-marketing-evidence/v1",
+    capturedAt,
+    filters: report.filters,
+    coverage: { scanned: report.scanned, serverCount: report.serverCount ?? null, emitted: jobs.length, queryComplete, enrichmentComplete, pageReadFailed: Boolean(report.pageError) },
+    // Query coverage is never a claim about historical approval or acquisition.
+    isApprovalCohort: false,
+    isFullLeadInventory: false,
+    jobs
+  };
 }
 
 // src/commands/jobs.ts
@@ -318,7 +437,7 @@ 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").option("--format <fmt>", "digest or jsonl", "digest").option("--out <path>", "Also write full jsonl to this file").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').action(async (opts) => {
     const enrich = String(opts.enrich ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     const badEnricher = enrich.find((e) => !ENRICHERS.includes(e));
     if (badEnricher) {
@@ -326,8 +445,13 @@ function registerJobsCommands(parentCmd, getClient2) {
       process.exitCode = 2;
       return;
     }
-    if (opts.format !== "digest" && opts.format !== "jsonl") {
-      console.error("Unknown --format (valid: digest, jsonl)");
+    if (!["digest", "jsonl", "marketing-evidence"].includes(opts.format)) {
+      console.error("Unknown --format (valid: digest, jsonl, marketing-evidence)");
+      process.exitCode = 2;
+      return;
+    }
+    if (opts.format === "marketing-evidence" && (opts.out || !enrich.includes("dates") || !enrich.includes("financials") || enrich.some((e) => e !== "dates" && e !== "financials"))) {
+      console.error("marketing-evidence requires --enrich dates,financials and forbids --out or other enrichers");
       process.exitCode = 2;
       return;
     }
@@ -339,14 +463,17 @@ function registerJobsCommands(parentCmd, getClient2) {
       assignment: opts.assignment,
       tradeType: opts.tradeType.length ? opts.tradeType : void 0
     };
-    const result = await scanJobs(getClient2(), filters);
+    const strict = Boolean(opts.strict) || opts.format === "marketing-evidence" || enrich.includes("payments");
+    const result = await scanJobs(getClient2(), filters, { strict });
     const enrichedJobs = await enrichJobs(getClient2(), result.jobs, enrich);
     const report = { filters, enrich, jobs: enrichedJobs, scanned: result.scanned, serverCount: result.serverCount, complete: result.complete, ...result.pageError ? { pageError: result.pageError } : {} };
-    console.log(opts.format === "jsonl" ? formatScanJsonl(report) : formatScanDigest(report));
-    if (!result.complete) process.exitCode = 3;
+    const evidence = opts.format === "marketing-evidence" ? marketingEvidence(report) : null;
+    const jsonl = formatScanJsonl(report, { receipt: strict });
+    console.log(evidence ? JSON.stringify(evidence) : opts.format === "jsonl" ? jsonl : formatScanDigest(report));
+    if (!result.complete || evidence && (!evidence.coverage.queryComplete || !evidence.coverage.enrichmentComplete)) process.exitCode = 3;
     if (opts.out) {
       try {
-        writeFileSync(opts.out, formatScanJsonl(report) + "\n");
+        writeFileSync(opts.out, jsonl + "\n");
       } catch (error) {
         console.error(`out: FAILED - ${error instanceof Error ? error.message : String(error)}`);
       }

package/dist/mcp.js

@@ -38,7 +38,7 @@ import {
   resolveTradeTypeIds,
   resolveWorkTypeId,
   usersList
-} from "./chunk-MQDU6DIH.js";
+} from "./chunk-STEYTGZE.js";
 
 // src/mcp.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsrev/acculynx-cli",
-  "version": "1.15.0",
+  "version": "1.17.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",