node-autotask 0.11.0 → 0.12.0

package/dist/{chunk-CJONZQ7E.js → chunk-MY7ZSXY3.js}

@@ -4,6 +4,9 @@ import {
   BLIND_SURFACE_STAMPS,
   BaseResource,
   ConflictError,
+  EMPTY_REASON_STAMPS,
+  FETCH_BY_IDS_CHUNK_SIZE,
+  FETCH_BY_IDS_MAX_ITEMS,
   NotFoundError,
   RELATIONSHIP_MAP,
   ResolutionError,
@@ -30,10 +33,10 @@ import {
   unwrapItem,
   unwrapItems,
   unwrapOperation
-} from "./chunk-LNRN45XS.js";
+} from "./chunk-GD4JRPYF.js";
 import {
   CAPABILITIES
-} from "./chunk-7L23FDQW.js";
+} from "./chunk-4A6XLQHE.js";
 
 // src/resources/appointments.ts
 var AppointmentsResource = class extends BaseResource {
@@ -4534,6 +4537,1068 @@ var ContractServiceUnitsResource = class extends BaseResource {
   }
 };
 
+// src/resources/special/contracts.ts
+var PROFITABILITY_OPT_KEYS = [
+  "dateFrom",
+  "dateTo",
+  "labourCostMethod",
+  "labourRatePerHour",
+  "includeRecurringCosts",
+  "includeUnbilledRevenue",
+  "externalMonthlyCosts",
+  "groupByActivity",
+  "staleAfterDays",
+  "maxTicketsForJoin",
+  "limit"
+];
+var LABOUR_METHOD_SET = [
+  "billing_item_our_cost",
+  "contract_role_cost",
+  "resource_internal_cost",
+  "provided"
+];
+var PROFITABILITY_MAX_WINDOW_MONTHS = 36;
+var RECURRING_DRIFT_EPSILON = 5e-3;
+var ESTIMATE_DEVIATION_THRESHOLD_PCT = 10;
+var CLOSED_STATUS_LABEL_RE = /resolved|completed|cancelled|canceled|closed|deleted/i;
+var PROFITABILITY_WIRE_BUDGET = 18;
+var DATE_RE2 = /^\d{4}-\d{2}-\d{2}$/;
+function num2(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+function isDateYMD2(v) {
+  return typeof v === "string" && DATE_RE2.test(v) && !Number.isNaN(Date.parse(v));
+}
+function monthsInWindow(dateFrom, dateTo) {
+  const a = `${dateFrom.slice(0, 7)}`;
+  const b = `${dateTo.slice(0, 7)}`;
+  if (a > b) return 0;
+  const ay = Number(a.slice(0, 4));
+  const am = Number(a.slice(5, 7));
+  const by = Number(b.slice(0, 4));
+  const bm = Number(b.slice(5, 7));
+  return (by - ay) * 12 + (bm - am) + 1;
+}
+function monthsBetween(dateFrom, dateTo) {
+  const out = [];
+  let y = Number(dateFrom.slice(0, 4));
+  let m = Number(dateFrom.slice(5, 7));
+  const end = dateTo.slice(0, 7);
+  for (; ; ) {
+    const tag = `${y}-${String(m).padStart(2, "0")}`;
+    out.push(tag);
+    if (tag === end) break;
+    m += 1;
+    if (m === 13) {
+      m = 1;
+      y += 1;
+    }
+    if (out.length > 500) break;
+  }
+  return out;
+}
+function monthBounds(month, dateFrom, dateTo) {
+  const y = Number(month.slice(0, 4));
+  const m = Number(month.slice(5, 7));
+  const first = `${month}-01`;
+  const lastOfMonth = new Date(Date.UTC(y, m, 0)).getUTCDate();
+  const rawEnd = `${month}-${String(lastOfMonth).padStart(2, "0")}`;
+  return {
+    start: first > dateFrom ? first : dateFrom,
+    end: rawEnd < dateTo ? rawEnd : dateTo
+  };
+}
+function dateToDay(v) {
+  if (typeof v !== "string" || v.length < 10) return null;
+  const d = Date.parse(v.slice(0, 10));
+  return Number.isNaN(d) ? null : Math.floor(d / 864e5);
+}
+function validateProfitabilityOptions(contractId, opts) {
+  if (opts === void 0 || (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
+    throw new AutotaskConfigError(
+      `profitability: opts must be the options object (got ${opts === void 0 ? "undefined" : Array.isArray(opts) ? "an array" : typeof opts})`,
+      { operation: "contracts.profitability" }
+    );
+  }
+  const problems = [];
+  for (const key of Object.keys(opts)) {
+    if (!PROFITABILITY_OPT_KEYS.includes(key)) {
+      problems.push(
+        `unknown opts key "${key}" \u2014 the bag is closed: ${PROFITABILITY_OPT_KEYS.join(", ")}`
+      );
+    }
+  }
+  if (!isDateYMD2(opts.dateFrom)) problems.push(`dateFrom is required (YYYY-MM-DD) (got ${String(opts.dateFrom)})`);
+  if (!isDateYMD2(opts.dateTo)) problems.push(`dateTo is required (YYYY-MM-DD) (got ${String(opts.dateTo)})`);
+  if (isDateYMD2(opts.dateFrom) && isDateYMD2(opts.dateTo) && opts.dateTo < opts.dateFrom) {
+    problems.push(`dateTo must be >= dateFrom (got ${opts.dateTo})`);
+  }
+  if (isDateYMD2(opts.dateFrom) && isDateYMD2(opts.dateTo) && opts.dateTo >= opts.dateFrom) {
+    const months = monthsInWindow(opts.dateFrom, opts.dateTo);
+    if (months > PROFITABILITY_MAX_WINDOW_MONTHS) {
+      problems.push(
+        `window must span at most ${PROFITABILITY_MAX_WINDOW_MONTHS} months (the per-month windowing budget stays bounded; got ${months} months)`
+      );
+    }
+  }
+  const method = opts.labourCostMethod ?? "billing_item_our_cost";
+  if (!LABOUR_METHOD_SET.includes(method)) {
+    problems.push(`labourCostMethod must be one of: ${LABOUR_METHOD_SET.join(", ")} (got ${String(opts.labourCostMethod)})`);
+  }
+  let rate = null;
+  if (opts.labourRatePerHour !== void 0) {
+    if (typeof opts.labourRatePerHour !== "number" || !Number.isFinite(opts.labourRatePerHour) || opts.labourRatePerHour < 0) {
+      problems.push(`labourRatePerHour must be a finite number >= 0 (got ${String(opts.labourRatePerHour)})`);
+    } else {
+      rate = opts.labourRatePerHour;
+    }
+  }
+  if (method === "provided" && rate === null) {
+    problems.push(`labourRatePerHour is required (finite number >= 0) when labourCostMethod is "provided" (got ${String(opts.labourRatePerHour)})`);
+  }
+  for (const key of ["includeRecurringCosts", "includeUnbilledRevenue", "groupByActivity"]) {
+    const v = opts[key];
+    if (v !== void 0 && typeof v !== "boolean") problems.push(`${key} must be a boolean (got ${String(v)})`);
+  }
+  if (opts.externalMonthlyCosts !== void 0) {
+    const emc = opts.externalMonthlyCosts;
+    if (!Array.isArray(emc)) {
+      problems.push("externalMonthlyCosts must be an array of finite numbers >= 0, indexed by month from dateFrom (got a non-array)");
+    } else {
+      const max = isDateYMD2(opts.dateFrom) && isDateYMD2(opts.dateTo) && opts.dateTo >= opts.dateFrom ? monthsInWindow(opts.dateFrom, opts.dateTo) : Infinity;
+      for (let i = 0; i < emc.length; i++) {
+        const v = emc[i];
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+          problems.push(`externalMonthlyCosts[${i}] must be a finite number >= 0 (got ${String(v)})`);
+        }
+      }
+      if (emc.length > max) {
+        problems.push(`externalMonthlyCosts must be an array of finite numbers >= 0, indexed by month from dateFrom, with at most ${max} entries (got ${emc.length})`);
+      }
+    }
+  }
+  const stale = opts.staleAfterDays ?? 30;
+  if (!Number.isInteger(stale) || stale < 1) problems.push(`staleAfterDays must be an integer >= 1 (got ${String(opts.staleAfterDays)})`);
+  const mtj = opts.maxTicketsForJoin ?? 500;
+  if (!Number.isInteger(mtj) || mtj < 1 || mtj > 500) {
+    problems.push(`maxTicketsForJoin must be an integer 1..500 (the in-filter cap; got ${String(opts.maxTicketsForJoin)})`);
+  }
+  let limit = 50;
+  if (opts.limit !== void 0) {
+    if (!Number.isInteger(opts.limit) || opts.limit < 1) {
+      problems.push(`limit must be an integer >= 1 (got ${String(opts.limit)})`);
+    } else {
+      limit = Math.min(opts.limit, 500);
+    }
+  }
+  try {
+    parseIdentifier(contractId, "contractId");
+  } catch (err) {
+    problems.push(err instanceof AutotaskError ? err.message : "contractId must be a vendor numeric id");
+  }
+  if (problems.length > 0) {
+    throw new AutotaskConfigError(
+      `profitability: ${problems.length} problem(s) found pre-request (zero wire was issued)
+- ` + problems.join("\n- "),
+      { operation: "contracts.profitability" }
+    );
+  }
+  return {
+    dateFrom: opts.dateFrom,
+    dateTo: opts.dateTo,
+    method,
+    labourRatePerHour: rate,
+    includeRecurringCosts: opts.includeRecurringCosts ?? true,
+    includeUnbilledRevenue: opts.includeUnbilledRevenue ?? true,
+    externalMonthlyCosts: Array.isArray(opts.externalMonthlyCosts) ? [...opts.externalMonthlyCosts] : [],
+    groupByActivity: opts.groupByActivity ?? true,
+    staleAfterDays: stale,
+    maxTicketsForJoin: mtj,
+    limit
+  };
+}
+async function boundedPart2(http, path, conditions, limit, operation, includeFields) {
+  const body = { MaxRecords: limit, filter: conditions };
+  if (includeFields !== void 0) body.IncludeFields = includeFields;
+  const res = await http.request({
+    method: "POST",
+    idempotent: true,
+    path,
+    body,
+    operation
+  });
+  const { items, pageDetails } = unwrapItems(res, operation);
+  const capped = items.length >= limit;
+  return { items, capped, hasMore: capped && pageDetails.nextPageUrl != null };
+}
+function capJoinSet2(ids, cap) {
+  const sorted = [...new Set(ids)].sort((a, b) => a - b);
+  if (sorted.length <= cap) return { ids: sorted, truncated: false, total: sorted.length };
+  return { ids: sorted.slice(0, cap), truncated: true, total: sorted.length };
+}
+async function fetchByIdsPart(http, entityPath, ids, fields, operation) {
+  const unique = [...new Set(ids)].sort((a, b) => a - b);
+  const byKey = /* @__PURE__ */ new Map();
+  const misses = [];
+  const notes = [];
+  for (let c = 0; c < unique.length; c += FETCH_BY_IDS_CHUNK_SIZE) {
+    const chunk = unique.slice(c, c + FETCH_BY_IDS_CHUNK_SIZE);
+    const chunkKeys = new Set(chunk);
+    try {
+      const body = {
+        MaxRecords: FETCH_BY_IDS_CHUNK_SIZE,
+        filter: [{ field: "id", op: "in", value: chunk }],
+        IncludeFields: fields
+      };
+      const res = await http.request({ method: "POST", idempotent: true, path: `${entityPath}/query`, body, operation });
+      const { items: rows } = unwrapItems(res, operation);
+      for (const row of rows) {
+        const k = num2(row.id);
+        if (k > 0 && chunkKeys.has(k)) byKey.set(k, row);
+      }
+    } catch (err) {
+      const code = err instanceof AutotaskError ? err.code : "SERVER_ERROR";
+      for (const k of chunk) {
+        if (!byKey.has(k) && !misses.some((m) => m.id === k)) misses.push({ id: k, code, message: err instanceof Error ? err.message : String(err) });
+      }
+    }
+  }
+  const queryMissed = unique.filter((k) => !byKey.has(k) && !misses.some((m) => m.id === k));
+  for (const k of queryMissed) {
+    try {
+      const res = await http.request({ method: "GET", path: `${entityPath}/${k}`, operation });
+      byKey.set(k, unwrapItem(res, k, operation));
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        misses.push({ id: k, code: "NOT_FOUND", message: err.message });
+      } else if (err instanceof AutotaskError) {
+        misses.push({ id: k, code: err.code, message: err.message });
+      } else {
+        misses.push({ id: k, code: "SERVER_ERROR", message: err instanceof Error ? err.message : String(err) });
+      }
+    }
+  }
+  const items = unique.map((k) => byKey.get(k)).filter((r) => r !== void 0);
+  const gotByQuery = unique.length - queryMissed.length;
+  if (queryMissed.length > 0 && gotByQuery === 0 && byKey.size > 0) {
+    notes.push(
+      `the chunk \`id in\` query returned 0 rows for ${byKey.size} id(s) \u2014 the per-id get fallback resolved them (the list-scoping quirk: get-by-id is the authority)`
+    );
+  }
+  const foundIds = new Set(byKey.keys());
+  if (misses.length > 0) {
+    const byCode = /* @__PURE__ */ new Map();
+    for (const m of misses) byCode.set(m.code, (byCode.get(m.code) ?? 0) + 1);
+    notes.push(`${misses.length} id(s) unreadable: ${[...byCode.entries()].map(([code, n]) => `${n} \xD7 ${code}`).join(", ")} (per-item typed misses \u2014 the rest resolved)`);
+  }
+  return { items, foundIds, misses, notes };
+}
+function ladderFrom(ctx) {
+  const rungs = [];
+  const push = (s) => rungs.push(s);
+  switch (ctx.method) {
+    case "billing_item_our_cost":
+      push("billing_item.ourCost");
+      push("contract_role_costs.rate");
+      push("resource.internalCost");
+      break;
+    case "contract_role_cost":
+      push("contract_role_costs.rate");
+      push("resource.internalCost");
+      break;
+    case "resource_internal_cost":
+      push("resource.internalCost");
+      break;
+    case "provided":
+      break;
+  }
+  if (ctx.rate !== null) push("provided");
+  return rungs;
+}
+function hoursOf(entry) {
+  const h = entry["hoursWorked"];
+  return typeof h === "number" && Number.isFinite(h) && h > 0 ? h : 0;
+}
+function resolveLabour(entry, ctx) {
+  const id = num2(entry["id"]);
+  const hours = hoursOf(entry);
+  for (const rung of ladderFrom(ctx)) {
+    if (rung === "billing_item.ourCost") {
+      const items = ctx.billedByEntryId.get(id) ?? [];
+      const costs = items.map((i) => i["ourCost"]).filter((v) => typeof v === "number" && Number.isFinite(v) && v >= 0);
+      if (costs.length > 0) {
+        return {
+          source: "billing_item.ourCost",
+          cost: costs.reduce((a, b) => a + b, 0),
+          rate: null,
+          evidence: { billingItemIds: items.map((i) => num2(i["id"])) }
+        };
+      }
+      continue;
+    }
+    if (rung === "contract_role_costs.rate") {
+      const resId = num2(entry["resourceID"]);
+      const roleId = num2(entry["roleID"]);
+      const row = resId > 0 && roleId > 0 ? ctx.roleCostByResourceRole.get(`${resId}:${roleId}`) ?? ctx.roleCostByRole.get(roleId) : roleId > 0 ? ctx.roleCostByRole.get(roleId) : void 0;
+      const rate = row ? row["rate"] : void 0;
+      if (row !== void 0 && typeof rate === "number" && Number.isFinite(rate) && rate >= 0) {
+        const matched = row !== void 0 && resId > 0 && roleId > 0 && ctx.roleCostByResourceRole.get(`${resId}:${roleId}`) !== void 0 ? "resource+role" : "role";
+        return { source: "contract_role_costs.rate", cost: rate * hours, rate, evidence: { contractRoleCostId: num2(row["id"]), matched } };
+      }
+      continue;
+    }
+    if (rung === "resource.internalCost") {
+      const resId = num2(entry["resourceID"]);
+      const r = resId > 0 ? ctx.resourcesById.get(resId) : void 0;
+      const ic = r ? r["internalCost"] : void 0;
+      if (r !== void 0 && typeof ic === "number" && Number.isFinite(ic) && ic >= 0) {
+        return { source: "resource.internalCost", cost: ic * hours, rate: ic, evidence: { resourceId: resId } };
+      }
+      continue;
+    }
+    if (rung === "provided" && ctx.rate !== null) {
+      return { source: "provided", cost: ctx.rate * hours, rate: ctx.rate, evidence: {} };
+    }
+  }
+  return { source: "missing", cost: null, rate: null, evidence: {} };
+}
+async function expandByMonth(http, path, fullWindowCond, limit, operation, fields, dateField, dateFrom, dateTo, wires) {
+  const months = monthsBetween(dateFrom, dateTo);
+  const seen = /* @__PURE__ */ new Set();
+  const all = [];
+  const cappedMonths = [];
+  const fullMonths = [];
+  for (const m of months) {
+    const b = monthBounds(m, dateFrom, dateTo);
+    const cond = [
+      ...fullWindowCond.filter((c) => c.field !== dateField),
+      { field: dateField, op: "gte", value: b.start },
+      { field: dateField, op: "lte", value: b.end }
+    ];
+    const page = await boundedPart2(http, path, cond, limit, operation, fields);
+    wires.issued += 1;
+    for (const row of page.items) {
+      const k = num2(row["id"]);
+      if (seen.has(k)) continue;
+      seen.add(k);
+      all.push(row);
+    }
+    if (page.capped) cappedMonths.push(m);
+    if (page.capped && page.hasMore) fullMonths.push(m);
+  }
+  const partNote = `per-month windowing fired: ${months.length} month read(s) added after the full-window page carried a live cursor (no cursor walk \u2014 the single-page house rule)` + (fullMonths.length > 0 ? ` | month ${fullMonths.join(", ")} hit the limit of ${limit} \u2014 figures cover the returned rows only; widen with a narrower window or higher limit` : "");
+  wires.note = (wires.note ? wires.note + " | " : "") + partNote;
+  return { items: all, capped: cappedMonths.length > 0, hasMore: fullMonths.length > 0, note: partNote, status: "ok" };
+}
+function fmtHours(h) {
+  const r = Math.round(h * 100) / 100;
+  return String(r);
+}
+function fmtNum(v) {
+  const r = Math.round(v * 100) / 100;
+  return String(r);
+}
+function pctOrNa(r) {
+  return r === null ? "n/a" : `${Math.round(r * 1e3) / 10}%`;
+}
+function dedupeSortCap(ids, limit) {
+  return [...new Set(ids)].sort((a, b) => Number(a) - Number(b)).slice(0, limit);
+}
+async function profitability(resource, contractId, opts, http) {
+  const v = validateProfitabilityOptions(contractId, opts ?? {});
+  const OP2 = "contracts.profitability";
+  const id = parseIdentifier(contractId, "contractId");
+  const idNum = typeof id === "number" ? id : Number(id);
+  const wires = { issued: 0, budget: PROFITABILITY_WIRE_BUDGET };
+  const asOf = (/* @__PURE__ */ new Date()).toISOString();
+  const asOfMs = Date.parse(asOf);
+  const skipPart = (note) => ({ items: [], capped: false, hasMore: false, status: "skipped", note });
+  const stampPart = (key, raw, conditions, extraNotes) => {
+    const st = unbilledWorkPartStatus(key, conditions, raw.items);
+    return {
+      items: raw.items,
+      capped: raw.capped,
+      hasMore: raw.hasMore,
+      status: st.status,
+      blindSurface: st.blindSurface,
+      note: [st.note, ...extraNotes ?? []].filter(Boolean).join(" | ") || void 0,
+      emptyReason: raw.items.length === 0 && st.status === "ok" ? EMPTY_REASON_STAMPS[key]?.query : void 0
+    };
+  };
+  const contract = await resource.get(id);
+  wires.issued += 1;
+  const contractRow = contract;
+  const companyID = num2(contractRow["companyID"]);
+  let customer = null;
+  let customerStatus = "skipped";
+  if (companyID > 0) {
+    try {
+      const res = await http.request({
+        method: "GET",
+        path: `/V1.0/Companies/${companyID}`,
+        operation: OP2
+      });
+      const item = unwrapItem(res, companyID, OP2);
+      customer = item ?? null;
+      customerStatus = "ok";
+    } catch (err) {
+      if (!(err instanceof NotFoundError)) throw err;
+    }
+    wires.issued += 1;
+  }
+  const servicesCond = [{ field: "contractID", op: "eq", value: id }];
+  const servicesRaw = await boundedPart2(http, "/V1.0/ContractServices/query", servicesCond, v.limit, OP2, ["id", "serviceID", "unitPrice", "unitCost", "internalCurrencyUnitPrice", "internalDescription"]);
+  wires.issued += 1;
+  const unitsCond = [{ field: "contractID", op: "eq", value: id }];
+  const unitsRaw = await boundedPart2(http, "/V1.0/ContractServiceUnits/query", unitsCond, v.limit, OP2, ["id", "contractServiceID", "serviceID", "units", "price", "cost", "internalCurrencyPrice", "startDate", "endDate", "approveAndPostDate"]);
+  wires.issued += 1;
+  let chargesPart;
+  let charges = [];
+  let chargesCond = [];
+  if (v.includeRecurringCosts) {
+    chargesCond = [{ field: "contractID", op: "eq", value: id }, { field: "datePurchased", op: "gte", value: v.dateFrom }, { field: "datePurchased", op: "lte", value: v.dateTo }];
+    const raw = await boundedPart2(http, "/V1.0/ContractCharges/query", chargesCond, v.limit, OP2, ["id", "chargeType", "billableAmount", "extendedCost", "unitCost", "unitPrice", "unitQuantity", "datePurchased", "isBilled", "status", "contractServiceID"]);
+    wires.issued += 1;
+    charges = raw.items;
+    chargesPart = stampPart("contract_charges", raw, chargesCond);
+  } else {
+    chargesPart = skipPart("skipped: includeRecurringCosts is false (zero wire)");
+  }
+  const roleCostsCond = [{ field: "contractID", op: "eq", value: id }];
+  const roleCostsRaw = await boundedPart2(http, "/V1.0/ContractRoleCosts/query", roleCostsCond, v.limit, OP2, ["id", "rate", "resourceID", "roleID"]);
+  wires.issued += 1;
+  const ratesCond = [{ field: "contractID", op: "eq", value: id }];
+  const ratesRaw = await boundedPart2(http, "/V1.0/ContractRates/query", ratesCond, v.limit, OP2, ["id", "roleID", "contractHourlyRate", "internalCurrencyContractHourlyRate"]);
+  wires.issued += 1;
+  const billingCond = () => [{ field: "contractID", op: "eq", value: id }, { field: "itemDate", op: "gte", value: v.dateFrom }, { field: "itemDate", op: "lte", value: v.dateTo }];
+  const billingFields = ["id", "invoiceID", "timeEntryID", "ticketID", "ourCost", "quantity", "rate", "extendedPrice", "itemDate", "postedDate", "nonBillable", "billingCodeID", "billingItemType"];
+  const billingFirst = await boundedPart2(http, "/V1.0/BillingItems/query", billingCond(), v.limit, OP2, billingFields);
+  wires.issued += 1;
+  let billingItems;
+  let billingRows = [];
+  if (!billingFirst.hasMore) {
+    const st = unbilledWorkPartStatus("billing_items", billingCond(), billingFirst.items);
+    billingRows = billingFirst.items;
+    billingItems = { items: billingFirst.items, capped: billingFirst.capped, hasMore: false, status: st.status, blindSurface: st.blindSurface, note: st.note, emptyReason: billingFirst.items.length === 0 && st.status === "ok" ? EMPTY_REASON_STAMPS.billing_items?.query : void 0 };
+  } else {
+    const wp = await expandByMonth(http, "/V1.0/BillingItems/query", billingCond(), v.limit, OP2, billingFields, "itemDate", v.dateFrom, v.dateTo, wires);
+    billingRows = wp.items;
+    billingItems = { ...wp, items: wp.items, note: wp.note };
+  }
+  const invoiceIds = [...new Set(billingRows.map((b) => num2(b["invoiceID"])).filter((n) => n > 0))];
+  let invoicesPart;
+  let invoices = [];
+  if (invoiceIds.length === 0) {
+    invoicesPart = skipPart("skipped: the billing part has no invoiceIDs (zero wire)");
+  } else {
+    const capped = capJoinSet2(invoiceIds, FETCH_BY_IDS_MAX_ITEMS);
+    if (capped.truncated) wires.note = (wires.note ? wires.note + " | " : "") + `invoiceJoinTruncated: the join set is capped at ${FETCH_BY_IDS_MAX_ITEMS} of ${capped.total} invoice ids (the fetch-by-ids cap) \u2014 the figures cover the returned set only`;
+    const fb = await fetchByIdsPart(http, "/V1.0/Invoices", capped.ids, ["id", "invoiceNumber", "invoiceTotal", "paidDate", "isVoided", "dueDate"], OP2);
+    wires.issued += 1;
+    invoices = fb.items;
+    invoicesPart = { items: fb.items, capped: capped.truncated, hasMore: capped.truncated, status: "ok", note: fb.notes.join(" | ") || void 0 };
+  }
+  const timeCond = () => [{ field: "contractID", op: "eq", value: id }, { field: "dateWorked", op: "gte", value: v.dateFrom }, { field: "dateWorked", op: "lte", value: v.dateTo }];
+  const timeFields = ["id", "ticketID", "taskID", "resourceID", "roleID", "hoursWorked", "hoursToBill", "dateWorked", "startDateTime", "endDateTime", "isNonBillable", "timeEntryType", "billingCodeID", "createDateTime"];
+  const timeFirst = await boundedPart2(http, "/V1.0/TimeEntries/query", timeCond(), v.limit, OP2, timeFields);
+  wires.issued += 1;
+  let timeEntries;
+  let entries = [];
+  if (!timeFirst.hasMore) {
+    const st = unbilledWorkPartStatus("time_entries", timeCond(), timeFirst.items);
+    entries = timeFirst.items;
+    timeEntries = { items: timeFirst.items, capped: timeFirst.capped, hasMore: false, status: st.status, blindSurface: st.blindSurface, note: st.note, emptyReason: timeFirst.items.length === 0 && st.status === "ok" ? EMPTY_REASON_STAMPS.time_entries?.query : void 0 };
+  } else {
+    const wp = await expandByMonth(http, "/V1.0/TimeEntries/query", timeCond(), v.limit, OP2, timeFields, "dateWorked", v.dateFrom, v.dateTo, wires);
+    entries = wp.items;
+    timeEntries = { ...wp, items: wp.items, note: wp.note };
+  }
+  const ticketFields = ["id", "ticketNumber", "title", "status", "ticketCategory", "contractID", "createDate", "resolvedDateTime", "completedDate", "lastActivityDate", "dueDateTime"];
+  const ticketsActCond = [{ field: "contractID", op: "eq", value: id }, { field: "createDate", op: "gte", value: v.dateFrom }, { field: "createDate", op: "lte", value: v.dateTo }];
+  const ticketsActRaw = await boundedPart2(http, "/V1.0/Tickets/query", ticketsActCond, v.limit, OP2, ticketFields);
+  wires.issued += 1;
+  let openStatusSet = null;
+  let statusNote;
+  try {
+    const res = await http.request({ method: "GET", path: "/V1.0/Tickets/entityInformation/fields", operation: OP2 });
+    wires.issued += 1;
+    const body = typeof res === "object" && res !== null ? res : {};
+    const fields = Array.isArray(body["fields"]) ? body["fields"] : [];
+    const statusRow = fields.find((f) => f["name"] === "status" && f["isPickList"] === true);
+    const values = statusRow && Array.isArray(statusRow["picklistValues"]) ? statusRow["picklistValues"] : [];
+    if (values.length === 0) {
+      statusNote = "the tickets.status picklist is not exposed to this API user \u2014 the open-status labels are unavailable";
+    } else {
+      const open = values.filter((p) => typeof p["value"] === "string" && !CLOSED_STATUS_LABEL_RE.test(String(p["label"] ?? ""))).map((p) => Number.parseInt(String(p["value"]), 10)).filter((n) => Number.isFinite(n));
+      if (open.length === 0) {
+        statusNote = "every tickets.status picklist label is closed-class \u2014 no open statuses exist in this tenant";
+      } else {
+        openStatusSet = new Set(open);
+      }
+    }
+  } catch (err) {
+    wires.issued += 1;
+    statusNote = `the tickets.status field catalog read failed (${err instanceof AutotaskError ? err.code : "SERVER_ERROR"}: ${err instanceof Error ? err.message : String(err)}) \u2014 the open-status labels are unavailable`;
+  }
+  let ticketsOpenPart;
+  let openTickets = [];
+  if (openStatusSet === null) {
+    ticketsOpenPart = skipPart(`skipped: ${statusNote} (zero wire)`);
+  } else {
+    const openCond = [{ field: "contractID", op: "eq", value: id }, { field: "status", op: "in", value: [...openStatusSet] }];
+    const raw = await boundedPart2(http, "/V1.0/Tickets/query", openCond, v.limit, OP2, ticketFields);
+    wires.issued += 1;
+    openTickets = raw.items;
+    ticketsOpenPart = stampPart("tickets", raw, openCond, ["openStatusHeuristic: true (the open set is the tenant picklist minus the closed-class labels)"]);
+  }
+  const resourceIds = [...new Set(entries.map((t) => num2(t["resourceID"])).filter((n) => n > 0))];
+  let resourcesPart;
+  let resources = [];
+  const resourceMissIds = /* @__PURE__ */ new Set();
+  if (resourceIds.length === 0) {
+    resourcesPart = skipPart("skipped: the time part has no resourceIDs (zero wire)");
+  } else {
+    const capped = capJoinSet2(resourceIds, FETCH_BY_IDS_MAX_ITEMS);
+    if (capped.truncated) wires.note = (wires.note ? wires.note + " | " : "") + `resourceJoinTruncated: the join set is capped at ${FETCH_BY_IDS_MAX_ITEMS} of ${capped.total} resource ids (the fetch-by-ids cap) \u2014 the figures cover the returned set only`;
+    const fb = await fetchByIdsPart(http, "/V1.0/Resources", capped.ids, ["id", "internalCost", "firstName", "lastName", "isActive", "userType"], OP2);
+    wires.issued += 1;
+    resources = fb.items;
+    for (const m of fb.misses) if (m.code === "NOT_FOUND") resourceMissIds.add(m.id);
+    resourcesPart = { items: fb.items, capped: capped.truncated, hasMore: capped.truncated, status: "ok", note: fb.notes.join(" | ") || void 0 };
+  }
+  const fetchedTickets = /* @__PURE__ */ new Map();
+  for (const t of [...ticketsActRaw.items, ...openTickets]) {
+    const k = num2(t["id"]);
+    if (k > 0 && !fetchedTickets.has(k)) fetchedTickets.set(k, t);
+  }
+  const ticketJoin = capJoinSet2([...fetchedTickets.keys()], v.maxTicketsForJoin);
+  const joinNote = ticketJoin.truncated ? `the ticket join set is capped at ${v.maxTicketsForJoin} of ${ticketJoin.total} ids \u2014 the expenses + the miscoding probe cover the returned join set only` : void 0;
+  let expensesPart;
+  let expenses = [];
+  if (ticketJoin.ids.length === 0) {
+    expensesPart = skipPart("skipped: the contract has no fetched tickets to join against (an empty join set is NOT evidence of no expenses \u2014 zero wire)");
+  } else {
+    const expCond = [{ field: "ticketID", op: "in", value: ticketJoin.ids }, { field: "expenseDate", op: "gte", value: v.dateFrom }, { field: "expenseDate", op: "lte", value: v.dateTo }];
+    const raw = await boundedPart2(http, "/V1.0/ExpenseItems/query", expCond, v.limit, OP2, ["id", "expenseDate", "expenseCategory", "paymentType", "expenseCurrencyExpenseAmount", "internalCurrencyExpenseAmount", "ticketID"]);
+    wires.issued += 1;
+    expenses = raw.items;
+    expensesPart = stampPart("expense_items", raw, expCond, joinNote === void 0 ? void 0 : [joinNote]);
+  }
+  let probePart;
+  let probeRows = [];
+  if (ticketJoin.ids.length === 0) {
+    probePart = skipPart("skipped: the contract has no fetched tickets to probe against (zero wire) \u2014 check 1 (miscoded_time_out) is not evaluable");
+  } else {
+    const probeCond = [
+      { field: "ticketID", op: "in", value: ticketJoin.ids },
+      { op: "or", items: [{ field: "contractID", op: "noteq", value: id }, { field: "contractID", op: "notExist" }] },
+      { field: "dateWorked", op: "gte", value: v.dateFrom },
+      { field: "dateWorked", op: "lte", value: v.dateTo }
+    ];
+    const raw = await boundedPart2(http, "/V1.0/TimeEntries/query", probeCond, v.limit, OP2, ["id", "ticketID", "contractID", "resourceID", "hoursWorked", "dateWorked"]);
+    wires.issued += 1;
+    probeRows = raw.items;
+    probePart = stampPart("time_entries", raw, probeCond, joinNote === void 0 ? void 0 : [joinNote]);
+  }
+  let configurationItemsPart;
+  let cis = [];
+  let ciCond = [];
+  if (!v.includeRecurringCosts) {
+    configurationItemsPart = skipPart("skipped: includeRecurringCosts is false (zero wire)");
+  } else if (companyID <= 0) {
+    configurationItemsPart = skipPart("skipped: the contract carries no companyID \u2014 the CI join has no root (zero wire)");
+  } else {
+    ciCond = [{ field: "companyID", op: "eq", value: companyID }];
+    const raw = await boundedPart2(http, "/V1.0/ConfigurationItems/query", ciCond, v.limit, OP2, ["id", "configurationItemName", "status"]);
+    wires.issued += 1;
+    cis = raw.items;
+    configurationItemsPart = stampPart("configuration_items", raw, ciCond);
+  }
+  let subscriptionsPart;
+  let subscriptions = [];
+  if (cis.length === 0) {
+    subscriptionsPart = skipPart("skipped: the CI join found no configuration items \u2014 the subscriptions part is not evaluable (zero wire)");
+  } else {
+    const ciIds = capJoinSet2(cis.map((c) => num2(c["id"])).filter((n) => n > 0), FETCH_BY_IDS_MAX_ITEMS);
+    const subCond = [{ field: "configurationItemID", op: "in", value: ciIds.ids }];
+    const raw = await boundedPart2(http, "/V1.0/Subscriptions/query", subCond, v.limit, OP2, ["id", "subscriptionName", "configurationItemID", "periodCost", "periodPrice", "periodType", "effectiveDate", "expirationDate", "status", "totalCost"]);
+    wires.issued += 1;
+    subscriptions = raw.items;
+    subscriptionsPart = stampPart("subscriptions", raw, subCond);
+  }
+  const servicesPart = stampPart("contract_services", servicesRaw, servicesCond);
+  const unitsPart = stampPart("contract_service_units", unitsRaw, unitsCond);
+  const roleCostsPart = stampPart("contract_role_costs", roleCostsRaw, roleCostsCond);
+  const ratesPart = stampPart("contract_rates", ratesRaw, ratesCond);
+  const ticketsActivityPart = stampPart("tickets", ticketsActRaw, ticketsActCond, ticketsActRaw.hasMore ? [`${fetchedTickets.size} ticket(s) returned of possibly more \u2014 the checks cover the returned set only`] : void 0);
+  const billedByEntryId = /* @__PURE__ */ new Map();
+  for (const b of billingRows) {
+    const te = num2(b["timeEntryID"]);
+    if (te <= 0) continue;
+    const arr = billedByEntryId.get(te) ?? [];
+    arr.push(b);
+    billedByEntryId.set(te, arr);
+  }
+  const roleCostByResourceRole = /* @__PURE__ */ new Map();
+  const roleCostByRole = /* @__PURE__ */ new Map();
+  for (const rc of roleCostsRaw.items) {
+    const resId = num2(rc["resourceID"]);
+    const roleId = num2(rc["roleID"]);
+    if (resId > 0 && roleId > 0) roleCostByResourceRole.set(`${resId}:${roleId}`, rc);
+    else if (roleId > 0) roleCostByRole.set(roleId, rc);
+  }
+  const resourcesById = new Map(resources.map((r) => [num2(r["id"]), r]));
+  const ladderCtx = { method: v.method, rate: v.labourRatePerHour, billedByEntryId, roleCostByResourceRole, roleCostByRole, resourcesById, resourceMissIds };
+  const entryResolution = /* @__PURE__ */ new Map();
+  for (const e of entries) entryResolution.set(num2(e["id"]), resolveLabour(e, ladderCtx));
+  const activeRungs = ladderFrom(ladderCtx);
+  const sources = {};
+  for (const rung of activeRungs) sources[rung] = { entries: 0, hours: 0, cost: 0 };
+  sources.missing = { entries: 0, hours: 0, cost: 0 };
+  const resolutionNotes = [];
+  if (v.method === "billing_item_our_cost") {
+    const noItems = entries.filter((e) => !billedByEntryId.has(num2(e["id"]))).length;
+    if (noItems > 0) resolutionNotes.push(`${noItems} ${noItems === 1 ? "entry" : "entries"} had no billing item (non-billable or unposted) \u2014 rung 1 not usable`);
+  }
+  for (const resId of [...resourceMissIds].sort((a, b) => a - b)) {
+    const n = entries.filter((e) => num2(e["resourceID"]) === resId).length;
+    resolutionNotes.push(`resource ${resId} unreadable (fetchByIds NOT_FOUND) \u2014 rung 3 unavailable for ${n} ${n === 1 ? "entry" : "entries"}`);
+  }
+  for (const e of entries) {
+    const r = entryResolution.get(num2(e["id"]));
+    const bucket = sources[r.source] ?? sources.missing;
+    bucket.entries += 1;
+    bucket.hours += hoursOf(e);
+    bucket.cost += r.cost ?? 0;
+  }
+  const unresolvedHours = sources.missing.hours;
+  if (unresolvedHours > 0) resolutionNotes.push(`${fmtHours(unresolvedHours)} hours unresolved (missing rate) \u2014 total_cost is a lower bound`);
+  const costRateResolution = { method: v.method, sources, unresolvedHours, notes: resolutionNotes };
+  const months = monthsBetween(v.dateFrom, v.dateTo);
+  const monthOf = (date) => typeof date === "string" && DATE_RE2.test(`${date}`.slice(0, 10)) ? date.slice(0, 7) : null;
+  const inMonth = (date, m) => monthOf(date) === m;
+  const unitEffectiveIn = (unit, m) => {
+    const s = monthOf(unit["startDate"]);
+    const e = monthOf(unit["endDate"]);
+    return (s === null || s <= m) && (e === null || e >= m);
+  };
+  const serviceById = new Map(servicesRaw.items.map((s) => [num2(s["id"]), s]));
+  const expectedBasis = servicesRaw.items.length > 0 || unitsRaw.items.length > 0;
+  const expectedIn = (m) => {
+    let total = 0;
+    for (const u of unitsRaw.items) {
+      if (!unitEffectiveIn(u, m)) continue;
+      const svc = serviceById.get(num2(u["contractServiceID"]));
+      if (svc === void 0) continue;
+      total += num2(svc["unitPrice"]) * num2(u["units"]);
+    }
+    return total;
+  };
+  const recurringIn = (m) => {
+    if (!v.includeRecurringCosts) return 0;
+    let total = 0;
+    for (const c of charges) if (inMonth(c["datePurchased"], m)) total += num2(c["billableAmount"]);
+    for (const u of unitsRaw.items) if (unitEffectiveIn(u, m)) total += num2(u["cost"]);
+    return total;
+  };
+  const invoicesById = new Map(invoices.map((i) => [num2(i["id"]), i]));
+  const monthly = [];
+  for (let mi = 0; mi < months.length; mi++) {
+    const m = months[mi];
+    const mBilling = billingRows.filter((b) => inMonth(b["itemDate"], m));
+    let revenueInvoiced = 0;
+    let revenueVoided = 0;
+    const billedItemIds = [];
+    for (const b of mBilling) {
+      const invId = num2(b["invoiceID"]);
+      const inv = invId > 0 ? invoicesById.get(invId) : void 0;
+      if (inv === void 0) continue;
+      if (inv["isVoided"] === true) revenueVoided += num2(b["extendedPrice"]);
+      else {
+        revenueInvoiced += num2(b["extendedPrice"]);
+        billedItemIds.push(num2(b["id"]));
+      }
+    }
+    const expected = v.includeUnbilledRevenue && expectedBasis ? expectedIn(m) : null;
+    const expectedUnbilled = expected === null ? 0 : Math.max(0, expected - revenueInvoiced);
+    const mEntries = entries.filter((e) => inMonth(e["dateWorked"], m));
+    let labourHours = 0;
+    let labourTotal = 0;
+    let unresolved = 0;
+    const rateSources = {};
+    for (const rung of activeRungs) rateSources[rung] = { entries: 0, hours: 0, cost: 0 };
+    rateSources.missing = { entries: 0, hours: 0, cost: 0 };
+    for (const e of mEntries) {
+      const r = entryResolution.get(num2(e["id"]));
+      labourHours += num2(e["hoursWorked"]);
+      const bucket = rateSources[r.source];
+      bucket.entries += 1;
+      bucket.hours += hoursOf(e);
+      bucket.cost += r.cost ?? 0;
+      if (r.source === "missing") unresolved += hoursOf(e);
+      else labourTotal += r.cost ?? 0;
+    }
+    let toolingVendor = subscriptionsPart.status === "skipped" ? null : 0;
+    if (toolingVendor !== null) {
+      for (const s of subscriptions) {
+        const eff = monthOf(s["effectiveDate"]) ?? "0000-00";
+        const exp = monthOf(s["expirationDate"]) ?? "9999-99";
+        if (eff <= m && m <= exp) toolingVendor += num2(s["periodCost"]);
+      }
+    }
+    const callerSupplied = v.externalMonthlyCosts[mi] ?? 0;
+    const recurring = recurringIn(m);
+    let expenseCost = 0;
+    for (const x of expenses) if (inMonth(x["expenseDate"], m)) expenseCost += num2(x["expenseCurrencyExpenseAmount"]);
+    const totalCost = labourTotal + (toolingVendor ?? 0) + callerSupplied + recurring + expenseCost;
+    const profit = revenueInvoiced - totalCost;
+    const margin = revenueInvoiced > 0 ? profit / revenueInvoiced : null;
+    const fixed = totalCost - labourTotal;
+    const resolvedHours = mEntries.filter((e) => entryResolution.get(num2(e["id"])).source !== "missing").reduce((a, e) => a + hoursOf(e), 0);
+    const breakEven = resolvedHours > 0 ? fixed <= 0 ? 0 : fixed / (labourTotal / resolvedHours) : null;
+    monthly.push({
+      month: m,
+      revenue_invoiced: revenueInvoiced,
+      revenue_voided_excluded: revenueVoided,
+      revenue_expected: expected,
+      revenue_expected_unbilled: expectedUnbilled,
+      labour_hours: labourHours,
+      labour_cost: { total: labourTotal, unresolvedHours: unresolved, rateSources },
+      tooling_cost: { vendor: toolingVendor, caller_supplied: callerSupplied },
+      recurring_cost: recurring,
+      expense_cost: expenseCost,
+      total_cost: totalCost,
+      profit,
+      margin,
+      break_even_hours: breakEven
+    });
+  }
+  const warnings = [];
+  warnings.push({
+    code: "miscoded_time_out",
+    count: probeRows.length,
+    sample_ids: dedupeSortCap(probeRows.map((p) => num2(p["id"])), v.limit)
+  });
+  const crossTimeEntries = entries.filter((e) => {
+    const t = num2(e["ticketID"]);
+    if (t <= 0) return false;
+    const ticket = fetchedTickets.get(t);
+    return ticket !== void 0 && num2(ticket["contractID"]) !== idNum;
+  });
+  warnings.push({ code: "cross_contract_ticket_time", count: crossTimeEntries.length, sample_ids: dedupeSortCap(crossTimeEntries.map((e) => num2(e["id"])), v.limit) });
+  const tupleGroups = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const key = [String(num2(e["resourceID"])), String(e["dateWorked"] ?? ""), String(num2(e["ticketID"])), String(e["hoursWorked"] ?? "")].join("|");
+    const arr = tupleGroups.get(key) ?? [];
+    arr.push(e);
+    tupleGroups.set(key, arr);
+  }
+  const dupAll = [];
+  const dupSample = [];
+  for (const group of tupleGroups.values()) {
+    if (group.length < 2) continue;
+    const sorted = [...group].sort((a, b) => num2(a["id"]) - num2(b["id"]));
+    for (const e of sorted) dupAll.push(num2(e["id"]));
+    for (const e of sorted.slice(1)) dupSample.push(num2(e["id"]));
+  }
+  warnings.push({ code: "duplicate_entries", count: dupAll.length, sample_ids: dedupeSortCap(dupSample, v.limit) });
+  const zeroHours = entries.filter((e) => {
+    const h = e["hoursWorked"];
+    return !(typeof h === "number" && Number.isFinite(h) && h > 0);
+  });
+  warnings.push({ code: "zero_negative_hours", count: zeroHours.length, sample_ids: dedupeSortCap(zeroHours.map((e) => num2(e["id"])), v.limit) });
+  const outPeriod = entries.filter((e) => {
+    const t = num2(e["ticketID"]);
+    if (t <= 0) return false;
+    const ticket = fetchedTickets.get(t);
+    if (ticket === void 0) return false;
+    const dW = dateToDay(e["dateWorked"]);
+    if (dW === null) return false;
+    const created = dateToDay(ticket["createDate"]);
+    if (created !== null && dW < created) return true;
+    const ends = [dateToDay(ticket["resolvedDateTime"]), dateToDay(ticket["completedDate"])].filter((d) => d !== null);
+    if (ends.length > 0 && dW > Math.min(...ends)) return true;
+    return false;
+  });
+  warnings.push({ code: "time_outside_ticket_period", count: outPeriod.length, sample_ids: dedupeSortCap(outPeriod.map((e) => num2(e["id"])), v.limit) });
+  const missingRate = entries.filter((e) => entryResolution.get(num2(e["id"])).source === "missing");
+  warnings.push({ code: "missing_cost_rate", count: missingRate.length, sample_ids: dedupeSortCap(missingRate.map((e) => num2(e["id"])), v.limit) });
+  let driftCount = 0;
+  const driftIds = /* @__PURE__ */ new Set();
+  if (v.includeRecurringCosts) {
+    for (let i = 1; i < months.length; i++) {
+      const r1 = recurringIn(months[i]);
+      const r0 = recurringIn(months[i - 1]);
+      if (r1 <= 0 || r0 <= 0 || Math.abs(r1 - r0) <= RECURRING_DRIFT_EPSILON) continue;
+      driftCount += 1;
+      const mA = months[i - 1];
+      const mB = months[i];
+      for (const c of charges) {
+        const cA = inMonth(c["datePurchased"], mA) ? num2(c["billableAmount"]) : 0;
+        const cB = inMonth(c["datePurchased"], mB) ? num2(c["billableAmount"]) : 0;
+        if (Math.abs(cB - cA) > 0) driftIds.add(num2(c["id"]));
+      }
+      for (const u of unitsRaw.items) {
+        const cA = unitEffectiveIn(u, mA) ? num2(u["cost"]) : 0;
+        const cB = unitEffectiveIn(u, mB) ? num2(u["cost"]) : 0;
+        if (Math.abs(cB - cA) > 0) driftIds.add(num2(u["id"]));
+      }
+    }
+  }
+  warnings.push({ code: "recurring_cost_drift", count: driftCount, sample_ids: dedupeSortCap([...driftIds], v.limit) });
+  let expectedUnbilledCount = 0;
+  const expectedUnbilledSamples = [];
+  if (v.includeUnbilledRevenue) {
+    for (let mi = 0; mi < months.length; mi++) {
+      const m = months[mi];
+      const expected = expectedBasis ? expectedIn(m) : null;
+      if (expected === null) continue;
+      const mBilling = billingRows.filter((b) => inMonth(b["itemDate"], m));
+      let billed = 0;
+      const ids = [];
+      for (const b of mBilling) {
+        const invId = num2(b["invoiceID"]);
+        const inv = invId > 0 ? invoicesById.get(invId) : void 0;
+        if (inv === void 0 || inv["isVoided"] === true) continue;
+        billed += num2(b["extendedPrice"]);
+        ids.push(num2(b["id"]));
+      }
+      if (expected > billed + 5e-3) {
+        expectedUnbilledCount += 1;
+        for (const i of ids) expectedUnbilledSamples.push(i);
+      }
+    }
+  }
+  warnings.push({ code: "expected_unbilled_revenue", count: expectedUnbilledCount, sample_ids: dedupeSortCap(expectedUnbilledSamples, v.limit) });
+  const driftTickets = [...fetchedTickets.values()].filter((t) => num2(t["contractID"]) !== idNum);
+  const unresolvedRefs = entries.filter((e) => num2(e["ticketID"]) > 0 && !fetchedTickets.has(num2(e["ticketID"])));
+  warnings.push({
+    code: "cross_contract_tickets",
+    count: driftTickets.length + unresolvedRefs.length,
+    sample_ids: dedupeSortCap([...driftTickets.map((t) => num2(t["id"])), ...unresolvedRefs.map((e) => num2(e["id"]))], v.limit)
+  });
+  const stale = [];
+  if (openStatusSet !== null) {
+    for (const t of fetchedTickets.values()) {
+      const status = t["status"];
+      if (typeof status !== "number" || !openStatusSet.has(status)) continue;
+      const lastDay = dateToDay(t["lastActivityDate"]);
+      if (lastDay === null) continue;
+      const days = asOfMs / 864e5 - lastDay;
+      if (days > v.staleAfterDays) stale.push(num2(t["id"]));
+    }
+  }
+  warnings.push({ code: "open_stale_tickets", count: stale.length, sample_ids: dedupeSortCap(stale, v.limit) });
+  let estimateCount = 0;
+  const estimateSample = [];
+  let estimateNote;
+  {
+    const actualRevenue = monthly.reduce((a, r) => a + r.revenue_invoiced, 0);
+    const actualCost = monthly.reduce((a, r) => a + r.total_cost, 0);
+    const termStart = dateToDay(contractRow["startDate"]);
+    const termEnd = dateToDay(contractRow["endDate"]);
+    const fromDay = dateToDay(v.dateFrom);
+    const toDay = dateToDay(v.dateTo);
+    if (termStart !== null && termEnd !== null && fromDay !== null && toDay !== null) {
+      const overlapStart = Math.max(termStart, fromDay);
+      const overlapEnd = Math.min(termEnd, toDay);
+      const termDays = termEnd - termStart + 1;
+      const overlapDays = overlapEnd >= overlapStart ? overlapEnd - overlapStart + 1 : 0;
+      if (termDays > 0 && overlapDays > 0) {
+        const frac = overlapDays / termDays;
+        const estRev = num2(contractRow["estimatedRevenue"]);
+        const estCost = num2(contractRow["estimatedCost"]);
+        const devRev = estRev > 0 ? Math.abs(actualRevenue - estRev * frac) / (estRev * frac) : null;
+        const devCost = estCost > 0 ? Math.abs(actualCost - estCost * frac) / (estCost * frac) : null;
+        if (devRev !== null && devRev > ESTIMATE_DEVIATION_THRESHOLD_PCT / 100 || devCost !== null && devCost > ESTIMATE_DEVIATION_THRESHOLD_PCT / 100) {
+          estimateCount = 1;
+          estimateSample.push(idNum);
+        }
+        estimateNote = `estimate vs actual (window-prorated ${overlapDays}/${termDays} days): revenue ${pctOrNa(devRev)} deviation (actual ${fmtNum(actualRevenue)} vs prorated ${fmtNum(estRev * frac)}), cost ${pctOrNa(devCost)} deviation (actual ${fmtNum(actualCost)} vs prorated ${fmtNum(estCost * frac)})`;
+      }
+    }
+  }
+  warnings.push({ code: "estimate_vs_actual", count: estimateCount, sample_ids: estimateSample, ...estimateCount === 1 && estimateNote !== void 0 ? { note: estimateNote } : {} });
+  const entriesByTicket = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const t = num2(e["ticketID"]);
+    if (t <= 0) continue;
+    const arr = entriesByTicket.get(t) ?? [];
+    arr.push(e);
+    entriesByTicket.set(t, arr);
+  }
+  const expenseByTicket = /* @__PURE__ */ new Map();
+  for (const x of expenses) {
+    const t = num2(x["ticketID"]);
+    if (t <= 0) continue;
+    expenseByTicket.set(t, (expenseByTicket.get(t) ?? 0) + num2(x["expenseCurrencyExpenseAmount"]));
+  }
+  const ticketCost = (t) => {
+    const tid = num2(t["id"]);
+    const es = entriesByTicket.get(tid) ?? [];
+    let cost = expenseByTicket.get(tid) ?? 0;
+    for (const e of es) cost += entryResolution.get(num2(e["id"])).cost ?? 0;
+    return cost;
+  };
+  const ticketHours = (t) => (entriesByTicket.get(num2(t["id"])) ?? []).reduce((a, e) => a + num2(e["hoursWorked"]), 0);
+  const allTickets = [...fetchedTickets.values()];
+  const activityCategories = [];
+  if (v.groupByActivity) {
+    const byCat = /* @__PURE__ */ new Map();
+    for (const t of allTickets) {
+      const cat = num2(t["ticketCategory"]) > 0 ? num2(t["ticketCategory"]) : null;
+      const arr = byCat.get(cat) ?? [];
+      arr.push(t);
+      byCat.set(cat, arr);
+    }
+    for (const [cat, tickets] of byCat) {
+      let entryCount = 0;
+      let hours = 0;
+      let cost = 0;
+      for (const t of tickets) {
+        const es = entriesByTicket.get(num2(t["id"])) ?? [];
+        entryCount += es.length;
+        hours += es.reduce((a, e) => a + num2(e["hoursWorked"]), 0);
+        cost += ticketCost(t);
+      }
+      activityCategories.push({
+        ticketCategory: cat,
+        ticketCount: tickets.length,
+        entryCount,
+        hours,
+        cost,
+        sample_ticketNumbers: dedupeSortCap(tickets.map((t) => num2(t["ticketNumber"])).filter((n) => n > 0), v.limit)
+      });
+    }
+    activityCategories.sort((a, b) => b.cost - a.cost || (a.ticketCategory === null ? 1 : b.ticketCategory === null ? -1 : (a.ticketCategory ?? 0) - (b.ticketCategory ?? 0)));
+  }
+  const highestCostTickets = allTickets.map((t) => ({
+    ticketId: num2(t["id"]),
+    ticketNumber: num2(t["ticketNumber"]) > 0 ? num2(t["ticketNumber"]) : null,
+    title: typeof t["title"] === "string" ? t["title"] : "",
+    status: typeof t["status"] === "number" ? t["status"] : null,
+    hours: ticketHours(t),
+    cost: ticketCost(t),
+    lastActivityDate: typeof t["lastActivityDate"] === "string" ? t["lastActivityDate"] : null
+  })).sort((a, b) => b.cost - a.cost || a.ticketId - b.ticketId).slice(0, v.limit);
+  const miscoding = /* @__PURE__ */ new Map();
+  const putMiscoding = (e, reason) => {
+    const eid = num2(e["id"]);
+    if (eid <= 0 || miscoding.has(eid)) return;
+    const c = num2(e["contractID"]);
+    miscoding.set(eid, { entryId: eid, reason, ticketId: num2(e["ticketID"]) > 0 ? num2(e["ticketID"]) : null, contractId: c > 0 ? c : null, hours: num2(e["hoursWorked"]) });
+  };
+  for (const p of probeRows) putMiscoding(p, num2(p["contractID"]) > 0 ? "ticket_of_other_contract" : "no_contract_on_entry");
+  for (const e of crossTimeEntries) putMiscoding(e, "ticket_of_other_contract");
+  for (const e of unresolvedRefs) putMiscoding(e, "ticket_not_in_fetched_set");
+  const possibleMiscoding = [...miscoding.values()].sort((a, b) => a.entryId - b.entryId).slice(0, v.limit);
+  const openRenewal = [];
+  if (openStatusSet !== null) {
+    for (const t of allTickets) {
+      const status = t["status"];
+      if (typeof status !== "number" || !openStatusSet.has(status)) continue;
+      const last = t["lastActivityDate"];
+      const lastDay = typeof last === "string" ? (asOfMs - Date.parse(last.slice(0, 10))) / 864e5 : null;
+      const staleDays = lastDay !== null && lastDay > v.staleAfterDays ? Math.floor(lastDay) : null;
+      openRenewal.push({
+        kind: "ticket",
+        id: num2(t["id"]),
+        label: typeof t["title"] === "string" && t["title"] !== "" ? t["title"] : `ticket ${num2(t["ticketNumber"]) > 0 ? num2(t["ticketNumber"]) : num2(t["id"])}`,
+        date: typeof last === "string" ? last.slice(0, 10) : null,
+        detail: staleDays !== null ? `open \u2014 stale ${staleDays} days (last activity)` : "open"
+      });
+    }
+  }
+  for (const s of subscriptions) {
+    openRenewal.push({
+      kind: "subscription",
+      id: num2(s["id"]),
+      label: typeof s["subscriptionName"] === "string" && s["subscriptionName"] !== "" ? s["subscriptionName"] : `subscription ${num2(s["id"])}`,
+      date: typeof s["expirationDate"] === "string" ? s["expirationDate"].slice(0, 10) : null,
+      detail: `periodType: ${typeof s["periodType"] === "string" && s["periodType"] !== "" ? s["periodType"] : "unknown"} (period cost ${fmtNum(num2(s["periodCost"]))})`
+    });
+  }
+  const contractEndDay = dateToDay(contractRow["endDate"]);
+  if (contractEndDay !== null) {
+    openRenewal.push({
+      kind: "contract_end",
+      id: idNum,
+      label: typeof contractRow["contractName"] === "string" && contractRow["contractName"] !== "" ? contractRow["contractName"] : `contract ${idNum}`,
+      date: String(contractRow["endDate"]).slice(0, 10),
+      detail: `the contract ends ${String(contractRow["endDate"]).slice(0, 10)}`
+    });
+  }
+  for (let mi = 0; mi < months.length; mi++) {
+    const m = months[mi];
+    let included = 0;
+    for (const u of unitsRaw.items) if (unitEffectiveIn(u, m)) included += num2(u["units"]);
+    const worked = monthly[mi].labour_hours;
+    if (included === 0 && worked === 0) continue;
+    const left = included - worked;
+    const my = Number(m.slice(0, 4));
+    const mm = Number(m.slice(5, 7));
+    const lastDay = new Date(Date.UTC(my, mm, 0)).getUTCDate();
+    openRenewal.push({
+      kind: "included_hours_burn",
+      id: null,
+      label: `included hours ${m}`,
+      date: `${m}-${String(lastDay).padStart(2, "0")}`,
+      detail: `${fmtHours(worked)} h worked vs ${fmtHours(included)} h included (${left >= 0 ? `${fmtHours(left)} h left` : `${fmtHours(Math.abs(left))} h over`})`
+    });
+  }
+  return {
+    contract,
+    customer,
+    period: { dateFrom: v.dateFrom, dateTo: v.dateTo, months, asOf },
+    currency: {
+      companyCurrencyID: customer && typeof customer["currencyID"] === "number" ? customer["currencyID"] : null,
+      note: "amounts are the vendor LOCAL-currency fields (the customer company currency is the context stamp); the internalCurrency* variants are NOT mixed in (v1 \u2014 a cross-currency tenant needs a follow-up op or bag key)"
+    },
+    monthly,
+    activity_categories: activityCategories,
+    highest_cost_tickets: highestCostTickets,
+    possible_miscoding: possibleMiscoding,
+    open_renewal_items: openRenewal,
+    data_quality_warnings: warnings,
+    costRateResolution,
+    parts: {
+      contract: "ok",
+      customer: customerStatus,
+      contractServices: servicesPart.status,
+      contractServiceUnits: unitsPart.status,
+      contractCharges: chargesPart.status,
+      contractRoleCosts: roleCostsPart.status,
+      contractRates: ratesPart.status,
+      billingItems: billingItems.status,
+      invoices: invoicesPart.status,
+      timeEntries: timeEntries.status,
+      ticketsActivity: ticketsActivityPart.status,
+      ticketsOpen: ticketsOpenPart.status,
+      resources: resourcesPart.status,
+      expenses: expensesPart.status,
+      miscodingProbe: probePart.status,
+      configurationItems: configurationItemsPart.status,
+      subscriptions: subscriptionsPart.status
+    },
+    contractServices: servicesPart,
+    contractServiceUnits: unitsPart,
+    contractCharges: chargesPart,
+    contractRoleCosts: roleCostsPart,
+    contractRates: ratesPart,
+    billingItems,
+    invoices: invoicesPart,
+    timeEntries,
+    ticketsActivity: ticketsActivityPart,
+    ticketsOpen: ticketsOpenPart,
+    resources: resourcesPart,
+    expenses: expensesPart,
+    miscodingProbe: probePart,
+    configurationItems: configurationItemsPart,
+    subscriptions: subscriptionsPart,
+    wires: { issued: wires.issued, budget: wires.budget, note: wires.note }
+  };
+}
+
 // src/resources/contracts.ts
 var ContractsResource = class extends BaseResource {
   constructor(http, pageSize) {
@@ -4599,6 +5664,10 @@ var ContractsResource = class extends BaseResource {
   async search(query, opts) {
     return this.searchBase(query, opts);
   }
+  /** Node-parity special op (hand-written in src/resources/special/contracts.ts). */
+  profitability(id, opts) {
+    return profitability(this, id, opts, this.http);
+  }
 };
 
 // src/resources/contract_ticket_purchases.ts
@@ -9083,11 +10152,11 @@ async function slaHealthCheck(_resource, id, opts = {}, http) {
   );
   const slas = rows.map((row) => {
     const bool = (v) => typeof v === "boolean" ? v : null;
-    const num2 = (v) => typeof v === "number" ? v : null;
+    const num3 = (v) => typeof v === "number" ? v : null;
     const milestones = [
-      { name: "firstResponse", met: bool(row.isFirstResponseMet), elapsedHours: num2(row.firstResponseElapsedHours) },
-      { name: "resolution", met: bool(row.isResolutionMet), elapsedHours: num2(row.resolutionElapsedHours) },
-      { name: "resolutionPlan", met: bool(row.isResolutionPlanMet), elapsedHours: num2(row.resolutionPlanElapsedHours) }
+      { name: "firstResponse", met: bool(row.isFirstResponseMet), elapsedHours: num3(row.firstResponseElapsedHours) },
+      { name: "resolution", met: bool(row.isResolutionMet), elapsedHours: num3(row.resolutionElapsedHours) },
+      { name: "resolutionPlan", met: bool(row.isResolutionPlanMet), elapsedHours: num3(row.resolutionPlanElapsedHours) }
     ];
     return { id: Number(row.id), name: row.serviceLevelAgreementName ?? null, milestones };
   });