@opsrev/acculynx-cli 1.16.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

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";
@@ -139,7 +139,7 @@ async function scanJobs(client, filters, options = {}) {
   });
   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");
@@ -201,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) });
@@ -288,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}`;
@@ -305,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;
@@ -331,8 +341,20 @@ 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
@@ -415,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, jsonl, or marketing-evidence (private operator data)", "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) {
@@ -441,15 +463,17 @@ function registerJobsCommands(parentCmd, getClient2) {
       assignment: opts.assignment,
       tradeType: opts.tradeType.length ? opts.tradeType : void 0
     };
-    const result = await scanJobs(getClient2(), filters, { strict: opts.format === "marketing-evidence" });
+    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 } : {} };
     const evidence = opts.format === "marketing-evidence" ? marketingEvidence(report) : null;
-    console.log(evidence ? JSON.stringify(evidence) : opts.format === "jsonl" ? formatScanJsonl(report) : formatScanDigest(report));
+    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.16.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",