@opsrev/acculynx-cli 1.14.0 → 1.16.0

package/README.md

@@ -159,3 +159,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/index.js

@@ -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,9 +139,16 @@ async function scanJobs(client, filters) {
   });
   return { jobs, scanned: fetched.length, serverCount, complete, ...pageError ? { pageError } : {} };
 }
-var ENRICHERS = ["financials", "reps", "dates"];
+var ENRICHERS = ["financials", "reps", "dates", "messages"];
 var asRecord = (v) => v !== null && typeof v === "object" ? v : {};
-async function enrichJobs(client, jobs, enrich, concurrency = 5) {
+async function defaultLoadMessagesTool() {
+  const { createRequire: createRequire2 } = await import("module");
+  const require3 = createRequire2(import.meta.url);
+  const resolved = require3.resolve("@opsrev/acculynx-cli-unofficial");
+  const mod = await import(resolved);
+  return mod.handleExtendedToolCall;
+}
+async function enrichJobs(client, jobs, enrich, concurrency = 5, deps = {}) {
   let userNames = /* @__PURE__ */ new Map();
   if (enrich.includes("reps")) {
     try {
@@ -114,6 +158,8 @@ async function enrichJobs(client, jobs, enrich, concurrency = 5) {
     }
   }
   const nameOf = (id) => userNames.get(String(id)) || String(id ?? "").slice(0, 8);
+  let messagesToolPromise = null;
+  const getMessagesTool = () => messagesToolPromise ??= (deps.loadMessagesTool ?? defaultLoadMessagesTool)();
   const out = jobs.map((job) => ({ job, errors: [] }));
   let next = 0;
   async function enrichOne(entry) {
@@ -139,10 +185,22 @@ async function enrichJobs(client, jobs, enrich, concurrency = 5) {
           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 ?? "")
           }));
+        } else if (source === "messages") {
+          const tool = await getMessagesTool();
+          const res = await tool({ name: "acculynx_jobs_messages", args: { jobId } });
+          const text = String(res.content?.[0]?.text ?? "");
+          if (res.isError) throw new Error(text.slice(0, 200) || "messages tool error");
+          const data = asRecord(JSON.parse(text || "{}"));
+          entry.messages = (data.messages ?? []).slice(0, 3).map((msg) => ({
+            date: String(msg.createdDate ?? ""),
+            by: String(msg.createdBy ?? ""),
+            text: String(msg.message ?? "").replace(/\s+/g, " ").trim().slice(0, 200)
+          }));
         }
       } catch (error) {
         entry.errors.push({ jobId, source, message: error instanceof Error ? error.message : String(error) });
@@ -211,6 +269,14 @@ function headerLine2(report) {
   }
   return line;
 }
+function messagesLine(entry, enrich) {
+  if (!enrich.includes("messages")) return null;
+  if (entry.errors.some((e) => e.source === "messages")) return "    note ERR:messages";
+  const m = entry.messages?.[0];
+  if (!m) return "    note: -";
+  const text = m.text.slice(0, 110) || "-";
+  return `    note ${mmdd(m.date)} ${m.by || "-"}: ${text}`;
+}
 function jobLine(entry, enrich) {
   const job = entry.job;
   const id8 = String(job.id ?? "").slice(0, 8);
@@ -245,11 +311,23 @@ function jobLine(entry, enrich) {
 }
 function formatScanDigest(report) {
   const lines = [headerLine1(report), headerLine2(report)];
-  for (const entry of report.jobs) lines.push(jobLine(entry, report.enrich));
+  for (const entry of report.jobs) {
+    lines.push(jobLine(entry, report.enrich));
+    const note = messagesLine(entry, report.enrich);
+    if (note !== null) lines.push(note);
+  }
   const allErrors = report.jobs.flatMap((j) => j.errors);
   if (allErrors.length > 0) {
     lines.push("errors:");
-    for (const e of allErrors) lines.push(`  ${e.jobId.slice(0, 8)} ${e.source}: ${e.message}`);
+    const groups = /* @__PURE__ */ new Map();
+    for (const e of allErrors) {
+      const key = `${e.source}: ${e.message}`;
+      const ids = groups.get(key) ?? [];
+      ids.push(e.jobId.slice(0, 8));
+      groups.set(key, ids);
+    }
+    for (const [key, ids] of groups)
+      lines.push(ids.length > 3 ? `  ${key} (${ids.length} jobs)` : `  ${ids.join(",")} ${key}`);
   }
   return lines.join("\n");
 }
@@ -257,6 +335,65 @@ function formatScanJsonl(report) {
   return report.jobs.map((j) => JSON.stringify(j)).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
 function collect(value, previous) {
   return [...previous, value];
@@ -278,7 +415,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").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").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) => {
     const enrich = String(opts.enrich ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     const badEnricher = enrich.find((e) => !ENRICHERS.includes(e));
     if (badEnricher) {
@@ -286,8 +423,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;
     }
@@ -299,11 +441,12 @@ function registerJobsCommands(parentCmd, getClient2) {
       assignment: opts.assignment,
       tradeType: opts.tradeType.length ? opts.tradeType : void 0
     };
-    const result = await scanJobs(getClient2(), filters);
+    const result = await scanJobs(getClient2(), filters, { strict: opts.format === "marketing-evidence" });
     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;
+    console.log(evidence ? JSON.stringify(evidence) : opts.format === "jsonl" ? formatScanJsonl(report) : 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");

package/package.json

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