node-autotask 0.34.0 → 0.37.0

package/dist/operations/index.js

@@ -3,8 +3,13 @@ import {
   AutotaskError,
   BLIND_SURFACE_INVENTORY,
   BOUNDED_QUERY_MAX_LIMIT,
+  BillingCodesResource,
+  BillingItemsResource,
+  CHARGE_LINE_FKS,
   CREATE_GUIDANCE,
+  CompaniesResource,
   ConfirmationRequiredError,
+  ContractsResource,
   DELETE_BOUNDARY_NOTES,
   DeleteBoundaryError,
   ENTITY_TYPE_TO_RESOURCE,
@@ -14,40 +19,55 @@ import {
   FETCH_MANY_MAX_ITEMS,
   FIELD_CACHE_KINDS,
   FIELD_CATALOG_HONESTY_NOTE,
+  InvoicesResource,
   MARKER_FIELDS,
   MAX_FIELD_CATALOG_WIRE,
   MODEL_DATE_FIELDS,
   MODEL_FIELD_SETS,
   MarkerUnsafeIdError,
   NotFoundError,
+  OrganizationalLevel1sResource,
+  OrganizationalLevel2sResource,
+  OrganizationalLevelAssociationsResource,
   PICKLIST_VALUE_NOT_SERVED_NOTE,
+  PROFITABILITY_MAX_WINDOW_MONTHS,
   REACHABILITY_PROBE_DEFAULTS,
   RELATIONSHIP_MAP,
   RELATIONSHIP_ZONE,
   RecoveryTruncatedError,
+  ResourcesResource,
+  SERVICE_LINE_FKS,
+  TimeEntriesResource,
   UI_LINK_ENTITIES,
   WORKFLOW_RESOURCES,
+  billingLineType,
   buildFilter,
   buildUiLink,
   camelKey,
   clampPageSize,
+  dayAfter,
   effectiveRequiredFields,
   expandResourceNames,
   fetchByIds,
   fetchMany,
   fieldCatalog,
+  internalAmount,
   isAutotaskError,
+  isDateYMD,
   isEnumerableResource,
   isRecord,
+  monthsInWindow,
+  num,
   parseIdentifier,
+  readPicklists,
   resourceForEntityType,
   uiLink,
   validateFetchManyItems,
   validateQueryFieldNames
-} from "../chunk-EZKM4HQ6.js";
+} from "../chunk-CH2WXTYD.js";
 import {
   CAPABILITIES
-} from "../chunk-4MUBUSTL.js";
+} from "../chunk-KQ6HMBB4.js";
 
 // src/operations/searchAcrossResources.ts
 var DEFAULT_LIMIT = 25;
@@ -233,7 +253,7 @@ var QUERY_RESOURCE_KEYS = (() => {
 })();
 var AGGREGATE_OPT_KEYS = ["groupBy", "sum", "top", "limit"];
 var OP_RE = /^([a-z0-9_]+)\.query$/;
-function num(v) {
+function num2(v) {
   return typeof v === "number" && Number.isFinite(v) ? v : 0;
 }
 function parseOperationKey(operation, problems) {
@@ -398,7 +418,7 @@ function foldGroups(items, v) {
     }
     g.count += 1;
     if (g.sums !== void 0) {
-      for (const f of v.sum) g.sums[f] = (g.sums[f] ?? 0) + num(item[f]);
+      for (const f of v.sum) g.sums[f] = (g.sums[f] ?? 0) + num2(item[f]);
     }
   }
   return [...groups.values()].sort((a, b) => b.count - a.count || (a.keyOrder < b.keyOrder ? -1 : a.keyOrder > b.keyOrder ? 1 : 0));
@@ -437,6 +457,674 @@ async function aggregate(client, operation, filter, opts = {}) {
   return result;
 }
 
+// src/operations/revenueRollup.ts
+var OP = "operations.revenueRollup";
+var PAGE = 500;
+var CONCURRENCY = 3;
+var DEFAULT_BUDGET = 90;
+var DEFAULT_BUDGET_NON_CHARGEABLE = 150;
+var BUDGET_CAP = 200;
+var TOP_MAX = 100;
+var SCOPE_IDS_MAX = 100;
+var TENANT_HOURLY_LIMIT = 1e4;
+var DEFAULT_GROUP_BY = ["vertical", "contractType"];
+var DEFAULT_CONTRACT_TYPE_RE = /^\s*(recurring|fixed)\b/i;
+var CONTRACTS_PATH = "/V1.0/Contracts";
+var COMPANIES_PATH = "/V1.0/Companies";
+var BILLING_ITEMS_PATH = "/V1.0/BillingItems";
+var LINE_TYPE_FIELDS = ["billingItemType", "timeEntryID", "expenseItemID", ...CHARGE_LINE_FKS, ...SERVICE_LINE_FKS];
+var isLabour = (line) => billingLineType(line) === "labour";
+function picklistKey(c, dim, path, field, raw, missing) {
+  const id = num(raw);
+  if (id === 0) return { id: null, label: missing };
+  const label = c.labels[path]?.get(field)?.get(id);
+  if (label === void 0) {
+    c.unlabelled.add(`${dim}: ${field} value ${id} has no label on the live ${path} picklist (id-only)`);
+    return { id };
+  }
+  return { id, label };
+}
+var DIMENSIONS = {
+  vertical: {
+    joins: { companies: ["marketSegmentID"] },
+    picklist: COMPANIES_PATH,
+    key: (c) => picklistKey(c, "vertical", COMPANIES_PATH, "marketSegmentID", c.company?.["marketSegmentID"], "unassigned")
+  },
+  contractType: {
+    key: (c) => picklistKey(c, "contractType", CONTRACTS_PATH, "contractType", c.contract["contractType"], "none")
+  },
+  contractCategory: {
+    key: (c) => picklistKey(c, "contractCategory", CONTRACTS_PATH, "contractCategory", c.contract["contractCategory"], "uncategorised")
+  },
+  company: {
+    joins: { companies: ["companyName"] },
+    key: (c) => ({ id: num(c.line["companyID"]), name: String(c.company?.["companyName"] ?? "") })
+  },
+  month: {
+    key: (c) => ({ id: c.invoice.month })
+  },
+  billingItemKind: {
+    lineFields: LINE_TYPE_FIELDS,
+    picklist: BILLING_ITEMS_PATH,
+    key: (c) => num(c.line["billingItemType"]) === 0 ? { id: billingLineType(c.line), label: billingLineType(c.line) } : picklistKey(c, "billingItemKind", BILLING_ITEMS_PATH, "billingItemType", c.line["billingItemType"], "other")
+  },
+  contract: {
+    joins: { contracts: ["contractName"] },
+    key: (c) => ({ id: num(c.line["contractID"]), name: String(c.contract["contractName"] ?? "") })
+  },
+  // Per line (no contract-pointer fallback): association → level2 (the Line of Business, `name`) + level1 (the division).
+  lineOfBusiness: {
+    lineFields: ["organizationalLevelAssociationID"],
+    joins: { organizationalLevelAssociations: [], organizationalLevel1s: [], organizationalLevel2s: [] },
+    unresolved: "unresolvedAssociations",
+    key: (c) => {
+      const id = num(c.line["organizationalLevelAssociationID"]);
+      if (id === 0) return { id: null, label: "no LOB assigned" };
+      const a = c.joined.organizationalLevelAssociations.get(id);
+      const l1 = c.joined.organizationalLevel1s.get(num(a?.["organizationalLevel1ID"]));
+      const l2 = c.joined.organizationalLevel2s.get(num(a?.["organizationalLevel2ID"]));
+      if (l1 === void 0 || l2 === void 0) return "unresolvedAssociations";
+      return { id, name: String(l2["name"] ?? ""), division: String(l1["name"] ?? "") };
+    }
+  },
+  // Labour lines only; a non-labour line (or a labour line with no time entry, e.g. an adjustment) is "n/a".
+  resource: {
+    lineFields: LINE_TYPE_FIELDS,
+    joins: { timeEntries: [], resources: [] },
+    unresolved: "unresolvedTimeEntries",
+    key: (c) => {
+      const te = num(c.line["timeEntryID"]);
+      if (!isLabour(c.line) || te === 0) return { id: null, label: "n/a" };
+      const id = num(c.joined.timeEntries.get(te)?.["resourceID"]);
+      const r = c.joined.resources.get(id);
+      if (r === void 0) return "unresolvedTimeEntries";
+      return { id, name: `${String(r["firstName"] ?? "")} ${String(r["lastName"] ?? "")}`.trim() };
+    }
+  },
+  billingCode: {
+    lineFields: ["billingCodeID"],
+    joins: { billingCodes: [] },
+    unresolved: "unresolvedBillingCodes",
+    key: (c) => {
+      const id = num(c.line["billingCodeID"]);
+      if (id === 0) return { id: null, label: "none" };
+      const b = c.joined.billingCodes.get(id);
+      return b === void 0 ? "unresolvedBillingCodes" : { id, name: String(b["name"] ?? "") };
+    }
+  }
+};
+var fk = (rows, field) => [...rows].map((r) => num(r[field]));
+var ONE_CHUNK = (idChunks) => Math.min(1, idChunks);
+var JOINS = {
+  contracts: {
+    make: (http) => new ContractsResource(http, PAGE),
+    fields: ["id", "contractType", "contractCategory"],
+    ids: (lines) => fk(lines, "contractID")
+  },
+  companies: {
+    make: (http) => new CompaniesResource(http, PAGE),
+    fields: ["id"],
+    ids: (lines) => fk(lines, "companyID")
+  },
+  organizationalLevelAssociations: {
+    make: (http) => new OrganizationalLevelAssociationsResource(http, PAGE),
+    fields: ["id", "organizationalLevel1ID", "organizationalLevel2ID"],
+    ids: (lines) => fk(lines, "organizationalLevelAssociationID")
+  },
+  organizationalLevel1s: {
+    make: (http) => new OrganizationalLevel1sResource(http, PAGE),
+    fields: ["id", "name"],
+    ids: (_, j) => fk(j["organizationalLevelAssociations"].values(), "organizationalLevel1ID"),
+    chunks: ONE_CHUNK
+  },
+  organizationalLevel2s: {
+    make: (http) => new OrganizationalLevel2sResource(http, PAGE),
+    fields: ["id", "name"],
+    ids: (_, j) => fk(j["organizationalLevelAssociations"].values(), "organizationalLevel2ID"),
+    chunks: ONE_CHUNK
+  },
+  timeEntries: {
+    make: (http) => new TimeEntriesResource(http, PAGE),
+    fields: ["id", "resourceID"],
+    ids: (lines) => fk(lines.filter(isLabour), "timeEntryID"),
+    // One time entry per labour line: the line count is the upper bound (labour share unknown pre-walk).
+    chunks: (_, lines) => pages(lines)
+  },
+  resources: {
+    make: (http, client) => new ResourcesResource(http, client.config, PAGE),
+    fields: ["id", "firstName", "lastName"],
+    ids: (_, j) => fk(j["timeEntries"].values(), "resourceID"),
+    chunks: ONE_CHUNK
+  },
+  billingCodes: {
+    make: (http) => new BillingCodesResource(http, PAGE),
+    fields: ["id", "name"],
+    ids: (lines) => fk(lines, "billingCodeID")
+  }
+};
+var LINE_FIELDS = ["id", "invoiceID", "companyID", "contractID", "totalAmount", "internalCurrencyTotalAmount", "extendedPrice", "internalCurrencyExtendedPrice"];
+var OPT_KEYS = ["companyIDs", "ownerResourceID", "contractIDs", "tenantWide", "dateFrom", "dateTo", "contractTypes", "contractCategories", "groupBy", "top", "maxVendorCalls", "includeNonChargeable"];
+var NC_LINE_FIELDS = ["nonBillable", "quantity", ...LINE_TYPE_FIELDS];
+var SCOPE_KEYS = ["companyIDs", "ownerResourceID", "contractIDs", "tenantWide"];
+var isPosInt = (v) => Number.isSafeInteger(v) && v > 0;
+function checkIdList(name, v, problems) {
+  if (!Array.isArray(v) || v.length === 0 || v.length > SCOPE_IDS_MAX || !v.every(isPosInt)) {
+    problems.push(`${name} must be a non-empty array of at most ${SCOPE_IDS_MAX} positive integer ids`);
+    return void 0;
+  }
+  return [...new Set(v)].sort((a, b) => a - b);
+}
+function checkSelector(name, v, problems) {
+  if (v === void 0) return void 0;
+  if (!Array.isArray(v) || v.length === 0 || !v.every((x) => isPosInt(x) || typeof x === "string" && x.trim() !== "")) {
+    problems.push(`${name} must be a non-empty array of picklist ids or labels`);
+    return void 0;
+  }
+  return v;
+}
+function checkInt(name, v, def, max, problems) {
+  if (v === void 0) return def;
+  if (!Number.isInteger(v) || v < 1 || v > max) {
+    problems.push(`${name} must be an integer 1..${max} (got ${String(v)})`);
+    return def;
+  }
+  return v;
+}
+function validate(opts) {
+  if (typeof opts !== "object" || opts === null || Array.isArray(opts)) {
+    throw new AutotaskConfigError("revenueRollup: opts must be the options object { <scope>, dateFrom, dateTo, ... } (zero wire was issued)", { operation: OP });
+  }
+  const o = opts;
+  const problems = [];
+  for (const k of Object.keys(o)) if (!OPT_KEYS.includes(k)) problems.push(`unknown opts key "${k}" \u2014 the bag is closed: ${OPT_KEYS.join(", ")}`);
+  const given = SCOPE_KEYS.filter((k) => o[k] !== void 0);
+  if (given.length !== 1) {
+    problems.push(given.length === 0 ? "a scope is required: exactly one of companyIDs, ownerResourceID, contractIDs, or tenantWide: true" : `exactly one scope key is allowed (got ${given.join(", ")})`);
+  }
+  const scopeKind = given[0] ?? "tenantWide";
+  let scopeIds;
+  if (given.length === 1) {
+    if (scopeKind === "companyIDs" || scopeKind === "contractIDs") scopeIds = checkIdList(scopeKind, o[scopeKind], problems);
+    if (scopeKind === "ownerResourceID" && !isPosInt(o.ownerResourceID)) problems.push("ownerResourceID must be a positive integer resource id");
+    if (scopeKind === "tenantWide" && o.tenantWide !== true) problems.push("tenantWide must be exactly true");
+  }
+  const { dateFrom, dateTo } = o;
+  if (!isDateYMD(dateFrom) || !isDateYMD(dateTo)) {
+    problems.push("dateFrom and dateTo are both required as YYYY-MM-DD (the window is inclusive, whole UTC days)");
+  } else if (dateFrom > dateTo) {
+    problems.push(`dateFrom ${dateFrom} is after dateTo ${dateTo}`);
+  } else if (monthsInWindow(dateFrom, dateTo) > PROFITABILITY_MAX_WINDOW_MONTHS) {
+    problems.push(`the window spans ${monthsInWindow(dateFrom, dateTo)} months; the cap is ${PROFITABILITY_MAX_WINDOW_MONTHS}`);
+  }
+  let groupBy = [...DEFAULT_GROUP_BY];
+  if (o.groupBy !== void 0) {
+    const g = o.groupBy;
+    if (!Array.isArray(g) || g.length === 0 || new Set(g).size !== g.length) {
+      problems.push(`groupBy must be a non-empty array of distinct dimensions: ${Object.keys(DIMENSIONS).join(", ")}`);
+    } else {
+      for (const d of g) if (!Object.hasOwn(DIMENSIONS, d)) problems.push(`unknown groupBy dimension "${String(d)}" \u2014 the dimensions are: ${Object.keys(DIMENSIONS).join(", ")}`);
+      groupBy = g;
+    }
+  }
+  const v = {
+    dateFrom,
+    dateTo,
+    scopeKind,
+    scopeIds,
+    ownerResourceID: scopeKind === "ownerResourceID" ? o.ownerResourceID : void 0,
+    contractTypes: checkSelector("contractTypes", o.contractTypes, problems),
+    contractCategories: checkSelector("contractCategories", o.contractCategories, problems),
+    groupBy,
+    top: checkInt("top", o.top, TOP_MAX, TOP_MAX, problems),
+    budget: checkInt("maxVendorCalls", o.maxVendorCalls, o.includeNonChargeable === true ? DEFAULT_BUDGET_NON_CHARGEABLE : DEFAULT_BUDGET, BUDGET_CAP, problems),
+    nonChargeable: o.includeNonChargeable === true
+  };
+  if (o.includeNonChargeable !== void 0 && typeof o.includeNonChargeable !== "boolean") problems.push("includeNonChargeable must be a boolean");
+  if (problems.length > 0) {
+    throw new AutotaskConfigError(`revenueRollup: ${problems.length} problem(s) found pre-request (zero wire was issued)
+- ${problems.join("\n- ")}`, { operation: OP });
+  }
+  return v;
+}
+function resolveSelector(name, sel, values) {
+  const out = /* @__PURE__ */ new Map();
+  const misses = [];
+  for (const s of sel) {
+    const hits = typeof s === "number" ? values.has(s) ? [s] : [] : [...values].filter(([, l]) => l.trim().toLowerCase() === s.trim().toLowerCase()).map(([id]) => id);
+    if (hits.length === 0) misses.push(JSON.stringify(s));
+    for (const h of hits) out.set(h, values.get(h));
+  }
+  if (misses.length > 0) throw unmatched(name, `${misses.join(", ")} matched no live value`, values);
+  return out;
+}
+function unmatched(name, what, values) {
+  const live = [...values].map(([id, l]) => `${id} ${l}`).join("; ") || "(the picklist serves no values)";
+  return new AutotaskConfigError(`revenueRollup: ${name}: ${what}. Live values (id label): ${live}`, {
+    operation: OP,
+    suggestedAction: `Pass ${name} as ids or exact labels from the live list.`
+  });
+}
+var sortedRecord = (m) => Object.fromEntries([...m].sort((a, b) => a[0] - b[0]).map(([id, l]) => [String(id), l]));
+var chunk = (a) => {
+  const out = [];
+  for (let i = 0; i < a.length; i += PAGE) out.push(a.slice(i, i + PAGE));
+  return out;
+};
+var byId = (rows) => [...new Map(rows.map((r) => [num(r["id"]), r])).values()];
+var cents = (v) => Math.round(num(v) * 100);
+var revC = (line) => cents(internalAmount(line, "internalCurrencyTotalAmount", "totalAmount"));
+var extC = (line) => cents(internalAmount(line, "internalCurrencyExtendedPrice", "extendedPrice"));
+var INTERNAL_FIELDS = ["internalCurrencyTotalAmount", "internalCurrencyExtendedPrice"];
+var lacksInternal = (line) => INTERNAL_FIELDS.some((k) => !Number.isFinite(line[k]));
+var money = (c) => c / 100;
+var pages = (n) => Math.ceil(n / PAGE);
+async function collect(res, filter, includeFields) {
+  const out = [];
+  for await (const r of res.query({ filter, includeFields, maxRecords: PAGE })) out.push(r);
+  return out;
+}
+function blindCount() {
+  return new AutotaskError("revenueRollup: a gate count came back blind (unknown, not zero); the roll-up cannot be sized", {
+    code: "INVALID_RESPONSE",
+    category: "server",
+    operation: OP,
+    details: { reason: "blind_count" },
+    suggestedAction: "Check the API user can see invoices and billing items (operations.blindSurfaces), then retry."
+  });
+}
+function countMismatch(what, streamed, counted, rows) {
+  const rowNote = rows !== void 0 && rows !== streamed ? ` (${rows} rows)` : "";
+  return new AutotaskError(`revenueRollup: the ${what} stream returned ${streamed} distinct ids${rowNote} but the gate count was ${counted} (the data changed mid-walk or a page dropped rows); the fold was discarded`, {
+    code: "INVALID_RESPONSE",
+    category: "server",
+    operation: OP,
+    details: { reason: "count_mismatch", stream: what, streamed, counted },
+    suggestedAction: "Retry the call."
+  });
+}
+function budgetError(message, details, suggestedAction) {
+  return new AutotaskError(message, { code: "BUDGET_EXCEEDED", category: "policy", operation: OP, details, suggestedAction });
+}
+function lastMonthsFrom(dateTo, months) {
+  return new Date(Date.UTC(Number(dateTo.slice(0, 4)), Number(dateTo.slice(5, 7)) - months, 1)).toISOString().slice(0, 10);
+}
+async function revenueRollup(client, opts) {
+  const v = validate(opts);
+  const raw = client.http;
+  let calls = 0;
+  let estimate = 0;
+  const sizingMin = [.../* @__PURE__ */ new Set([CONTRACTS_PATH, ...v.groupBy.flatMap((d) => DIMENSIONS[d].picklist ? [DIMENSIONS[d].picklist] : [])])].length + (v.scopeKind === "ownerResourceID" ? 1 : 0) + 2 + (v.nonChargeable ? 1 : 0);
+  const http = Object.create(raw);
+  http.request = (o) => {
+    if (calls >= v.budget && estimate === 0) {
+      throw budgetError(
+        `revenueRollup: the vendor-call budget of ${v.budget} is below the sizing overhead (labels, scope and count calls: at least ${sizingMin} for this call); the roll-up could not be sized and no stream was read. Retry with a higher maxVendorCalls (cap ${BUDGET_CAP}); the refusal then names the full estimate.`,
+        { phase: "estimate", estimate: sizingMin, budget: v.budget, vendorCalls: calls, suggestions: [{ maxVendorCalls: sizingMin }] },
+        `Pass maxVendorCalls >= ${sizingMin} (cap ${BUDGET_CAP}).`
+      );
+    }
+    if (calls >= v.budget) {
+      throw budgetError(
+        `revenueRollup: the vendor-call budget of ${v.budget} was exhausted mid-walk (pre-walk estimate ${estimate}); the partial fold was discarded. Retry with a higher maxVendorCalls (cap ${BUDGET_CAP}) or a shorter window / a scope.`,
+        { phase: "walk", budget: v.budget, vendorCalls: calls, estimate },
+        `Pass maxVendorCalls > ${v.budget} (cap ${BUDGET_CAP}), a later dateFrom, or a scope.`
+      );
+    }
+    calls += 1;
+    return raw.request(o);
+  };
+  const groupDims = v.groupBy.map((d) => DIMENSIONS[d]);
+  const paths = [.../* @__PURE__ */ new Set([CONTRACTS_PATH, ...groupDims.flatMap((d) => d.picklist ? [d.picklist] : [])])];
+  const labels = {};
+  for (const p of paths) labels[p] = await readPicklists(http, p, OP);
+  const contractLabels = labels[CONTRACTS_PATH];
+  const typeValues = contractLabels.get("contractType") ?? /* @__PURE__ */ new Map();
+  const inTypes = v.contractTypes ? resolveSelector("contractTypes", v.contractTypes, typeValues) : new Map([...typeValues].filter(([, l]) => DEFAULT_CONTRACT_TYPE_RE.test(l)));
+  if (inTypes.size === 0) throw unmatched("contractTypes", "no live contract type label starts with 'Recurring' or 'Fixed' (the default)", typeValues);
+  const inCategories = v.contractCategories ? resolveSelector("contractCategories", v.contractCategories, contractLabels.get("contractCategory") ?? /* @__PURE__ */ new Map()) : void 0;
+  let scopeIds = v.scopeIds;
+  if (v.scopeKind === "ownerResourceID") {
+    const owned = /* @__PURE__ */ new Set();
+    for await (const c of new CompaniesResource(http, PAGE).query({ filter: [{ field: "ownerResourceID", op: "eq", value: v.ownerResourceID }], includeFields: ["id"], maxRecords: PAGE })) {
+      const id = num(c.id);
+      if (id > 0) owned.add(id);
+      if (owned.size > SCOPE_IDS_MAX) break;
+    }
+    scopeIds = [...owned].sort((a, b) => a - b);
+    if (scopeIds.length === 0 || scopeIds.length > SCOPE_IDS_MAX) {
+      throw new AutotaskConfigError(
+        `revenueRollup: ownerResourceID ${v.ownerResourceID} resolves to ${scopeIds.length > SCOPE_IDS_MAX ? `more than ${SCOPE_IDS_MAX}` : 0} companies (companies.query; 1..${SCOPE_IDS_MAX} supported)`,
+        { operation: OP, suggestedAction: "Pass companyIDs explicitly, or tenantWide: true." }
+      );
+    }
+  }
+  const scopeCond = scopeIds === void 0 ? [] : [{ field: v.scopeKind === "contractIDs" ? "contractID" : "companyID", op: "in", value: scopeIds }];
+  const invoices = new InvoicesResource(http, PAGE);
+  const billingItems = new BillingItemsResource(http, PAGE);
+  const windowOn = (field) => [{ field, op: "gte", value: v.dateFrom }, { field, op: "lt", value: dayAfter(v.dateTo) }];
+  const invoiceFilter = (voided2) => [...windowOn("invoiceDateTime"), { field: "isVoided", op: "eq", value: voided2 }];
+  const withVoided = v.scopeKind !== "contractIDs";
+  const voidedFilter = [...invoiceFilter(true), ...scopeIds !== void 0 && withVoided ? [{ field: "companyID", op: "in", value: scopeIds }] : []];
+  const nInvoices = await invoices.count({ filter: invoiceFilter(false) });
+  const nLines = await billingItems.count({ filter: [...windowOn("itemDate"), { field: "invoiceID", op: "exist" }, ...scopeCond] });
+  const uninvoicedFilter = [{ field: "invoiceID", op: "notExist" }, ...windowOn("itemDate"), ...scopeCond];
+  const nUninvoiced = v.nonChargeable ? await billingItems.count({ filter: uninvoicedFilter }) : 0;
+  if (typeof nInvoices !== "number" || typeof nLines !== "number" || typeof nUninvoiced !== "number") throw blindCount();
+  const joinsNeeded = Object.keys(JOINS).filter((j) => j === "contracts" || groupDims.some((d) => d.joins?.[j]));
+  const chunks = pages(nInvoices);
+  const linePages = chunks + Math.max(0, pages(nLines) - 1) + chunks;
+  const uninvoicedPages = v.nonChargeable ? Math.max(1, pages(nUninvoiced)) : 0;
+  const idChunks = pages(Math.min(nLines + nUninvoiced, nInvoices));
+  const joinChunks = joinsNeeded.reduce((s, j) => {
+    const spec = JOINS[j];
+    return s + ("chunks" in spec ? spec.chunks(idChunks, nLines + nUninvoiced) : idChunks);
+  }, 0);
+  const fixed = calls + (withVoided ? 1 : 0);
+  estimate = fixed + Math.max(1, chunks) + linePages + uninvoicedPages + joinChunks;
+  if (estimate > v.budget) throw refusal(v, estimate, fixed, scopeIds, joinsNeeded.length);
+  const invoiceRows = await collect(invoices, invoiceFilter(false), ["id", "invoiceTotal", "invoiceDateTime", "companyID"]);
+  const invoiceById = /* @__PURE__ */ new Map();
+  for (const r of invoiceRows) {
+    invoiceById.set(num(r["id"]), { total: cents(r["invoiceTotal"]), month: String(r["invoiceDateTime"] ?? "").slice(0, 7), companyID: num(r["companyID"]) });
+  }
+  if (invoiceById.size !== nInvoices) throw countMismatch("invoice", invoiceById.size, nInvoices, invoiceRows.length);
+  const voided = withVoided ? byId(await collect(invoices, voidedFilter, ["id", "invoiceTotal"])) : void 0;
+  const lineFields = [.../* @__PURE__ */ new Set([...LINE_FIELDS, ...groupDims.flatMap((d) => d.lineFields ?? []), ...v.nonChargeable ? NC_LINE_FIELDS : []])];
+  const ids = [...invoiceById.keys()].sort((a, b) => a - b);
+  const lines = (await client.batch(async (c) => {
+    const filter = [{ field: "invoiceID", op: "in", value: c }, ...scopeCond];
+    const n = await billingItems.count({ filter });
+    if (typeof n !== "number") throw blindCount();
+    const rows = byId(await collect(billingItems, filter, lineFields));
+    if (rows.length !== n) throw countMismatch("line", rows.length, n);
+    return rows;
+  }, chunk(ids), { concurrency: CONCURRENCY })).flat();
+  const orphan = lines.find((l) => !invoiceById.has(num(l["invoiceID"])));
+  if (orphan !== void 0) {
+    throw new AutotaskError(`revenueRollup: billing line ${num(orphan["id"])} belongs to invoice ${num(orphan["invoiceID"])}, which is not among the ${invoiceById.size} streamed invoices; the fold was discarded`, {
+      code: "INVALID_RESPONSE",
+      category: "server",
+      operation: OP,
+      details: { reason: "orphan_line", lineID: num(orphan["id"]), invoiceID: num(orphan["invoiceID"]) },
+      suggestedAction: "Retry the call."
+    });
+  }
+  const uninvoiced = v.nonChargeable ? byId(await collect(billingItems, uninvoicedFilter, [...lineFields, "itemDate"])) : [];
+  if (v.nonChargeable && uninvoiced.length !== nUninvoiced) throw countMismatch("uninvoiced line", uninvoiced.length, nUninvoiced);
+  const all = uninvoiced.length > 0 ? [...lines, ...uninvoiced] : lines;
+  const joined = Object.fromEntries(Object.keys(JOINS).map((j) => [j, /* @__PURE__ */ new Map()]));
+  for (const j of joinsNeeded) {
+    const spec = JOINS[j];
+    const res = spec.make(http, client);
+    const fields = [.../* @__PURE__ */ new Set([...spec.fields, ...groupDims.flatMap((d) => d.joins?.[j] ?? [])])];
+    const want = [...new Set(spec.ids(all, joined))].filter((id) => id > 0).sort((a, b) => a - b);
+    const rows = await client.batch((c) => collect(res, [{ field: "id", op: "in", value: c }], fields), chunk(want), { concurrency: CONCURRENCY });
+    for (const r of rows.flat()) joined[j].set(num(r["id"]), r);
+  }
+  return fold(v, { invoiceById, voided, lines, uninvoiced, joined, labels, inTypes, inCategories, scopeIds, calls, estimate });
+}
+function refusal(v, estimate, fixed, scopeIds, joinCount) {
+  const months = monthsInWindow(v.dateFrom, v.dateTo);
+  const variable = estimate - fixed;
+  const fitMonths = Math.floor((v.budget - fixed) * months / variable);
+  const suggestions = [];
+  const text = [];
+  let unestimated = false;
+  const suggest = (s, t, estimated = false) => {
+    suggestions.push(s);
+    text.push(t);
+    if (!estimated) unestimated = true;
+  };
+  if (estimate <= BUDGET_CAP) suggest({ maxVendorCalls: estimate }, `maxVendorCalls: ${estimate} (cap ${BUDGET_CAP})`, true);
+  if (fitMonths >= 1 && fitMonths < months) {
+    const dateFrom = lastMonthsFrom(v.dateTo, fitMonths);
+    const est = fixed + Math.ceil(variable * fitMonths / months);
+    suggest({ dateFrom, estimate: est }, `dateFrom: '${dateFrom}' (est. ${est})`, true);
+  }
+  if (v.scopeKind === "tenantWide") suggest({ companyIDs: "[...]" }, "companyIDs: [...] (or ownerResourceID)");
+  if (estimate > BUDGET_CAP) {
+    if (v.nonChargeable) suggest({ includeNonChargeable: false }, "includeNonChargeable: false");
+    if (joinCount > 1) suggest({ groupBy: ["contractType"] }, "groupBy: ['contractType'] (fewer dimensions, fewer id-fetch calls)");
+    if (v.scopeKind === "companyIDs" || v.scopeKind === "ownerResourceID") suggest({ contractIDs: "[...]" }, "contractIDs: [...] (one call per group of contracts)");
+    const n = (scopeIds ?? []).length;
+    if (v.scopeKind === "companyIDs" && n > 1) suggest({ companyIDs: "[...]" }, "a shorter companyIDs list (one call per part)");
+    if (v.scopeKind === "ownerResourceID" && n > 1) suggest({ companyIDs: "[...]" }, "companyIDs: a subset of the owner's companies (one call per part)");
+    if (v.scopeKind === "contractIDs" && n > 1) suggest({ contractIDs: "[...]" }, "a shorter contractIDs list (one call per part)");
+  }
+  if (suggestions.length === 0) suggest({ maxVendorCalls: BUDGET_CAP }, `maxVendorCalls: ${BUDGET_CAP} (the cap; the estimate ${estimate} is above it, so this call will be refused at this estimate even at the cap; no narrower shape exists for this scope and window)`, true);
+  const caveat = unestimated ? ". Narrowings without an estimate may still be refused: the invoice stream is tenant-wide in every scope, and the line stream costs at least one page and one count per chunk of 500 of those invoices, so a narrower scope or shape does not reduce that part" : "";
+  const scope = v.scopeKind === "tenantWide" ? "tenantWide" : `${v.scopeKind} ${(scopeIds ?? []).length} id(s)`;
+  return budgetError(
+    `revenueRollup: estimated ${estimate} vendor calls exceeds maxVendorCalls ${v.budget} (window ${v.dateFrom}..${v.dateTo}, ${scope}). Narrow with one of: ${text.join("; ")}${caveat}`,
+    { phase: "estimate", estimate, budget: v.budget, suggestions },
+    `Narrow with one of: ${text.join("; ")}${caveat}`
+  );
+}
+var amt = () => ({ amount: 0, lines: 0 });
+var nc = () => ({ contractCovered: { value: 0, hours: 0, lines: 0 }, nonBillable: { value: 0, hours: 0, lines: 0 } });
+var add = (a, c) => {
+  a.amount += c;
+  a.lines += 1;
+};
+var outAmt = (a) => ({ amount: money(a.amount), lines: a.lines });
+var outNc = (n) => {
+  const o = (k) => ({ value: money(n[k].value), hours: n[k].hours / 100, lines: n[k].lines });
+  return { contractCovered: o("contractCovered"), nonBillable: o("nonBillable") };
+};
+var outRecord = (r) => Object.fromEntries([...r].sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0).map(([k, a]) => [k, outAmt(a)]));
+function ncClass(line) {
+  if (line["nonBillable"] === true || line["nonBillable"] === 1) return "nonBillable";
+  return extC(line) > 0 && revC(line) === 0 ? "contractCovered" : void 0;
+}
+function ncAdd(n, k, line) {
+  n[k].value += extC(line);
+  if (isLabour(line)) n[k].hours += cents(line["quantity"]);
+  n[k].lines += 1;
+}
+function compareIds(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i] ?? null;
+    const y = b[i] ?? null;
+    if (x === y) continue;
+    if (x === null) return -1;
+    if (y === null) return 1;
+    if (typeof x === "number" && typeof y === "number") return x - y;
+    return String(x) < String(y) ? -1 : 1;
+  }
+  return 0;
+}
+function fold(v, f) {
+  const contractLabels = f.labels[CONTRACTS_PATH];
+  const bucketLabel = (field, fallback) => (t) => {
+    const values = contractLabels.get(field);
+    const l = values?.get(t);
+    if (l === void 0) return `${fallback} ${t}`;
+    return [...values.values()].filter((x) => x === l).length > 1 ? `${l} (${t})` : l;
+  };
+  const typeLabel = bucketLabel("contractType", "type");
+  const catLabel = bucketLabel("contractCategory", "category");
+  const needCompany = v.groupBy.some((d) => DIMENSIONS[d].joins?.companies);
+  const byLob = v.groupBy.includes("lineOfBusiness");
+  const unlabelled = /* @__PURE__ */ new Set();
+  const uncontracted = amt();
+  const unresolvedContracts = amt();
+  const unresolvedCompanies = amt();
+  const unresolvedJoins = new Map(v.groupBy.flatMap((d) => DIMENSIONS[d].unresolved ? [[DIMENSIONS[d].unresolved, amt()]] : []));
+  const unresolvedNc = amt();
+  const noPointer = amt();
+  const otherTypes = /* @__PURE__ */ new Map();
+  const otherCats = /* @__PURE__ */ new Map();
+  const cells = /* @__PURE__ */ new Map();
+  const allContracts = /* @__PURE__ */ new Set();
+  const lineTotals = /* @__PURE__ */ new Map();
+  const zeroTotal = amt();
+  const zeroIds = /* @__PURE__ */ new Set();
+  const locate = (line, invoice) => {
+    const contractID = num(line["contractID"]);
+    if (contractID === 0) return { bucket: uncontracted, unresolved: false };
+    const contract = f.joined.contracts.get(contractID);
+    if (contract === void 0) return { bucket: unresolvedContracts, unresolved: true };
+    const type = num(contract["contractType"]);
+    if (!f.inTypes.has(type)) return { bucket: slot(otherTypes, typeLabel(type)), unresolved: false };
+    const cat = num(contract["contractCategory"]);
+    if (f.inCategories !== void 0 && !f.inCategories.has(cat)) return { bucket: slot(otherCats, cat === 0 ? "uncategorised" : catLabel(cat)), unresolved: false };
+    const company = f.joined.companies.get(num(line["companyID"]));
+    if (needCompany && company === void 0) return { bucket: unresolvedCompanies, unresolved: true };
+    const ctx = { line, invoice, contract, company, joined: f.joined, labels: f.labels, unlabelled };
+    const keys = {};
+    const ids = [];
+    for (const d of v.groupBy) {
+      const k = DIMENSIONS[d].key(ctx);
+      if (typeof k === "string") return { bucket: unresolvedJoins.get(k), unresolved: true };
+      keys[d] = k;
+      ids.push(k.id);
+    }
+    const id = JSON.stringify(ids);
+    let cell = cells.get(id);
+    if (cell === void 0) {
+      cell = { keys, ids, revenue: 0, credits: 0, creditLines: 0, included: 0, contracts: /* @__PURE__ */ new Set(), items: 0, nc: nc() };
+      cells.set(id, cell);
+    }
+    return { cell };
+  };
+  for (const line of f.lines) {
+    const invoiceID = num(line["invoiceID"]);
+    const invoice = f.invoiceById.get(invoiceID);
+    lineTotals.set(invoiceID, (lineTotals.get(invoiceID) ?? 0) + cents(line["totalAmount"]));
+    const c = revC(line);
+    if (invoice.total === 0) {
+      add(zeroTotal, c);
+      zeroIds.add(invoiceID);
+    }
+    const at = locate(line, invoice);
+    if (!("cell" in at)) {
+      add(at.bucket, c);
+      if (at.unresolved && v.nonChargeable && ncClass(line)) add(unresolvedNc, extC(line));
+      continue;
+    }
+    const cell = at.cell;
+    cell.revenue += c;
+    if (c < 0) {
+      cell.credits += c;
+      cell.creditLines += 1;
+    }
+    cell.included += extC(line) - c;
+    cell.contracts.add(num(line["contractID"]));
+    cell.items += 1;
+    allContracts.add(num(line["contractID"]));
+    if (byLob && cell.keys.lineOfBusiness.id === null) add(noPointer, c);
+    const k = v.nonChargeable ? ncClass(line) : void 0;
+    if (k) ncAdd(cell.nc, k, line);
+  }
+  for (const line of f.uninvoiced) {
+    const k = ncClass(line);
+    if (!k) continue;
+    const at = locate(line, { total: 0, month: String(line["itemDate"] ?? "").slice(0, 7), companyID: num(line["companyID"]) });
+    if ("cell" in at) ncAdd(at.cell.nc, k, line);
+    else if (at.unresolved) add(unresolvedNc, extC(line));
+  }
+  const sorted = [...cells.values()].sort((a, b) => b.revenue - a.revenue || compareIds(a.ids, b.ids));
+  const kept = sorted.slice(0, v.top);
+  const cut = sorted.slice(v.top);
+  const sum = (k) => sorted.reduce((s, x) => s + x[k], 0);
+  const ncTotal = nc();
+  for (const x of sorted) for (const k of ["contractCovered", "nonBillable"]) for (const m of ["value", "hours", "lines"]) ncTotal[k][m] += x.nc[k][m];
+  const reconciled = v.scopeKind === "contractIDs" ? [] : [...f.invoiceById].filter(([, inv]) => v.scopeKind === "tenantWide" || f.scopeIds.includes(inv.companyID));
+  let headerTotal = 0;
+  let lineTotal = 0;
+  let mismatched = 0;
+  for (const [id, inv] of reconciled) {
+    const lt = lineTotals.get(id) ?? 0;
+    headerTotal += inv.total;
+    lineTotal += lt;
+    if (lt !== inv.total) mismatched += 1;
+  }
+  const blindSurfaces2 = [...unlabelled].sort();
+  const noInternal = [...f.lines, ...f.uninvoiced].filter(lacksInternal).length;
+  if (noInternal > 0) blindSurfaces2.push(`billing_items: ${noInternal} line(s) without internalCurrencyTotalAmount / internalCurrencyExtendedPrice; their local-currency totalAmount / extendedPrice was used instead`);
+  if (unresolvedCompanies.lines > 0) blindSurfaces2.push("companies.query: some line companies were not returned by the id-in fetch (the companies list surface can be blind to companies the API user does not own); their lines are in coverage.excluded.unresolvedCompanies");
+  if (v.scopeKind === "ownerResourceID") blindSurfaces2.push("companies.query: ownerResourceID was resolved through the companies list surface, which can be blind to companies the API user does not own; a company it hides is missing from the scope and its revenue is not counted (scope.ids lists the companies that were resolved)");
+  const notes = [
+    "basis: invoice date (invoiceDateTime) as whole UTC days; voided invoices excluded; revenue = internalCurrencyTotalAmount (ex-tax, internal currency); includedValue is informational and never in revenue",
+    "prepaid block-hour / retainer contracts: revenue is the billed purchase"
+  ];
+  notes.push("coverage.zeroTotalInvoices is informational: its lines are also folded into rows / the excluded buckets, so it is not part of coverage.excluded (revenue + the excluded line buckets reconcile to the whole)");
+  if (v.scopeKind === "contractIDs") {
+    notes.push("reconciliation is not run for a contractIDs scope (only the scoped contracts' lines are fetched)");
+    notes.push("coverage.excluded.voidedInvoices is omitted for a contractIDs scope: an invoice header cannot be attributed to a contract (zeroTotalInvoices counts the zero-total invoices carrying a scoped line)");
+  } else if (v.scopeKind !== "tenantWide") {
+    notes.push("scope applies to the line's companyID; reconciliation, voidedInvoices and the zero-total count cover the invoices whose header company is in scope (zero-total also counts an invoice carrying an in-scope line; a mismatch can mean a line billed to another company)");
+  }
+  if (v.nonChargeable) {
+    notes.push("nonChargeable is never added to revenue: contractCovered = billable lines with internalCurrencyExtendedPrice > 0 and internalCurrencyTotalAmount = 0, nonBillable = nonBillable lines; value = \u03A3 internalCurrencyExtendedPrice, hours = \u03A3 quantity on labour lines (Labor and Labor Adjustment). Invoiced lines are keyed on the invoice date; uninvoiced lines (invoiceID notExist) have no invoice date, so they are windowed and month-keyed on itemDate (whole UTC days). Uninvoiced lines outside the contract-type/category scope or uncontracted are not counted.");
+  }
+  for (const [id, inv] of f.invoiceById) {
+    if (inv.total === 0 && (v.scopeKind === "tenantWide" || v.scopeKind !== "contractIDs" && f.scopeIds.includes(inv.companyID))) zeroIds.add(id);
+  }
+  const result = {
+    window: { dateFrom: v.dateFrom, dateTo: v.dateTo, basis: "invoiceDate" },
+    scope: {
+      kind: v.scopeKind,
+      ...v.ownerResourceID !== void 0 ? { ownerResourceID: v.ownerResourceID } : {},
+      ...f.scopeIds !== void 0 ? { ids: f.scopeIds } : {}
+    },
+    groupBy: v.groupBy,
+    top: v.top,
+    rows: kept.map((x) => ({
+      keys: x.keys,
+      revenue: money(x.revenue),
+      credits: { amount: money(x.credits), lines: x.creditLines },
+      includedValue: money(x.included),
+      contracts: x.contracts.size,
+      items: x.items,
+      ...v.nonChargeable ? { nonChargeable: outNc(x.nc) } : {}
+    })),
+    ...cut.length > 0 ? { rowsTruncated: { rows: cut.length, revenue: money(cut.reduce((s, x) => s + x.revenue, 0)) } } : {},
+    totals: {
+      revenue: money(sum("revenue")),
+      credits: money(sum("credits")),
+      includedValue: money(sum("included")),
+      contracts: allContracts.size,
+      items: sum("items"),
+      ...v.nonChargeable ? { nonChargeable: outNc(ncTotal) } : {}
+    },
+    coverage: {
+      vendorCalls: f.calls,
+      budget: v.budget,
+      estimate: f.estimate,
+      tenantHourlyShare: `${(f.calls / TENANT_HOURLY_LIMIT * 100).toFixed(2)}% of ${TENANT_HOURLY_LIMIT.toLocaleString("en-US")}/h`,
+      contractTypeMap: sortedRecord(f.inTypes),
+      ...f.inCategories !== void 0 ? { contractCategoryMap: sortedRecord(f.inCategories) } : {},
+      reconciliation: { headerTotal: money(headerTotal), lineTotal: money(lineTotal), delta: money(lineTotal - headerTotal), invoicesChecked: reconciled.length, invoicesMismatched: mismatched },
+      zeroTotalInvoices: { count: zeroIds.size, ...outAmt(zeroTotal) },
+      excluded: {
+        ...f.voided !== void 0 ? { voidedInvoices: { count: f.voided.length, headerAmount: money(f.voided.reduce((s, r) => s + cents(r["invoiceTotal"]), 0)) } } : {},
+        uncontracted: outAmt(uncontracted),
+        otherContractTypes: outRecord(otherTypes),
+        otherContractCategories: outRecord(otherCats),
+        unresolvedContracts: outAmt(unresolvedContracts),
+        unresolvedCompanies: outAmt(unresolvedCompanies),
+        ...Object.fromEntries([...unresolvedJoins].map(([k, a]) => [k, outAmt(a)])),
+        ...v.nonChargeable ? { unresolvedNonChargeable: outAmt(unresolvedNc) } : {}
+      },
+      ...byLob ? {
+        lineOfBusiness: {
+          noPointer: outAmt(noPointer),
+          note: `LOB figures are floors: lines without a pointer are shown separately (the "no LOB assigned" row, id null). LOB is per billing line (no contract fallback), so a row's contracts = contracts with at least one line in that LOB, and per-LOB contract counts can sum to more than totals.contracts.`
+        }
+      } : {},
+      blindSurfaces: blindSurfaces2,
+      notes
+    }
+  };
+  return result;
+}
+function slot(m, k) {
+  const a = m.get(k) ?? amt();
+  m.set(k, a);
+  return a;
+}
+
 // src/operations/relationshipMap.ts
 async function relationshipMap(client, resourceKey) {
   void client;
@@ -1221,7 +1909,7 @@ function unknownKeysRefusal(raw, validKeys, subject, operation) {
 
 // src/operations/invoke/registry.ts
 var RECORDS = CAPABILITIES;
-var byId = new Map(RECORDS.map((r) => [r.id, r]));
+var byId2 = new Map(RECORDS.map((r) => [r.id, r]));
 
 // src/operations/invoke/dispatch.ts
 var INVOKE_MAX_INLINE_BYTES = 1024 * 1024;
@@ -1237,7 +1925,7 @@ function bufferResult(buf) {
   };
 }
 function resolveRecord(operation) {
-  const record = byId.get(operation);
+  const record = byId2.get(operation);
   if (record === void 0) {
     throw new AutotaskConfigError(
       `invoke: unknown operation "${operation}" \u2014 it is not in the capability registry`,
@@ -1297,6 +1985,8 @@ function operationsHolder(client) {
     // <resource>.query op via the house bounded walk and fold client-side
     // (truncation honesty: hasMore/totalScanned — no silent partial sums).
     aggregate: (operation, filter, opts) => aggregate(client, operation, filter, opts),
+    // Issue #234: revenue by dimension in one budgeted call (refuses over budget, never partial).
+    revenueRollup: (opts) => revenueRollup(client, opts),
     // Issue #59 PR-B: the bulk fetch by ids — query-first chunked `id in`
     // reads + the per-id `get` fallback (blind-surface-safe; per-item
     // typed outcomes reuse the fetchMany shapes).
@@ -1473,6 +2163,7 @@ export {
   relationshipMap,
   resolveAny,
   resourceForEntityType,
+  revenueRollup,
   searchAcrossResources,
   uiLink,
   unknownKeysRefusal,