node-autotask 0.12.0 → 0.13.0

package/docs/API.md

@@ -2608,7 +2608,9 @@ the plan change — a new registry op — is a minor at publish). One call
 returns the contract's reconciled P&L over a date window:
 
 - **`contracts.profitability(contractId, opts)` — the closed opts bag.**
-  `dateFrom`/`dateTo` are required (`YYYY-MM-DD`, `dateTo >= dateFrom`) and
+  `opts` itself is required (0.13.0 — the signature and the registry arg map
+  agree; a call without it is a pre-request `CONFIG_ERROR` naming the bag and
+  its `dateFrom`/`dateTo`). `dateFrom`/`dateTo` are required (`YYYY-MM-DD`, `dateTo >= dateFrom`) and
   the window is capped at 36 calendar months (the per-month windowing budget
   stays bounded; OQ1). `labourCostMethod` (default
   `billing_item_our_cost`; the closed 4-set
@@ -2625,34 +2627,62 @@ returns the contract's reconciled P&L over a date window:
   `ticketCategory` activity fold; `staleAfterDays` (default 30, integer `>=
   1`) is the open-stale horizon; `maxTicketsForJoin` (default 500, integer
   1..500) caps the ticket join set fed to the expenses + miscoding probe
-  (sorted, first N, the `N of M` note); `limit` (default 50, clamped 500) is
-  every part's `MaxRecords` + the capped lists. Validation collects the
+  (sorted, first N, the `N of M` note) and the time-referenced ticket ids;
+  `limit` (default 50, clamped 500) is
+  every part's `MaxRecords` + the capped lists; `includeRows` (default
+  false, boolean) selects the output shape (below). Validation collects the
   COMPLETE problem list and throws ONE typed `CONFIG_ERROR` pre-request —
   zero wire on any malformed bag (the refusal table is house style: every
   message names the key + the valid values).
-- **Wire plan: ≤18 bounded reads, zero mutating, all pre-existing ops.**
+- **Wire plan: ≤21 bounded reads, zero mutating, all pre-existing ops.**
   Issue order: contract `get` → customer `GET /V1.0/Companies/{companyID}` →
-  `ContractServices` / `ContractServiceUnits` / `ContractCharges` /
-  `ContractRoleCosts` / `ContractRates` / `BillingItems` queries → invoices
+  the Contracts `entityInformation/fields` read (the `contractType` LABEL —
+  verified on the ww29 sandbox 2026-10-16: 1 Time & Materials, 3 Fixed
+  Price, 4 Block Hours, 6 Retainer, 7 Recurring Service, 8 Per Ticket, 9
+  Umbrella; the folds still branch on `/block\s*hours?/i` and
+  `/time.*materials?/i` over the label, never an id; `contractCategory` is
+  ignored — all its values are inactive; an absent/0 type skips the read; an absent type, an
+  unlisted id or a catalog fault is `CONTRACT_TYPE_UNKNOWN`, surfaced in
+  `contract_type { id, label, absent? }`) → `ContractServices` / `ContractServiceUnits` (windowed on the period
+  `startDate`) / `ContractCharges` / `ContractRoleCosts` / `ContractRates`
+  queries → `ContractBlocks` query (Block Hours contracts only, by label;
+  skipped otherwise) → `BillingItems` query → invoices
   (fetch-by-ids on the distinct billed `invoiceID`s; skipped on none) →
-  `TimeEntries` query → in-window `Tickets` query (the activity population) →
-  the tickets `entityInformation/fields` metadata read (the open-status
-  picklist) → open `Tickets` query (`status in` the open set) → resources
-  (fetch-by-ids on the distinct time-row `resourceID`s; skipped on none) →
-  `ExpenseItems` query + the ONE extra bounded miscoding probe
-  (`TimeEntries` with `ticketID in join` + `or[contractID noteq, contractID
-  notExist]`; skipped on an empty ticket set) → `ConfigurationItems` query
-  (default-on) → `Subscriptions` query (CI join; skipped on no CIs). The
+  `TimeEntries` query → `Tickets` activity query (`or[ and[contractID,
+  createDate in window], id in <the ticket ids the in-window time
+  references> ]` — an older or closed ticket carrying this period's time is
+  fetched, never reported as unresolvable) → the tickets
+  `entityInformation/fields` metadata read (the open-status picklist) → open
+  `Tickets` query (`status in` the open set) → resources (fetch-by-ids on the
+  distinct time-row `resourceID`s; skipped on none) → `ExpenseItems` query +
+  the ONE extra bounded miscoding probe (`TimeEntries` with `ticketID in
+  join` + `or[contractID noteq, contractID notExist]`; the join is the
+  fetched tickets whose record says THIS contract; skipped on an empty set)
+  → `ConfigurationItems` query (`contractID` = the CIs this contract covers,
+  never the whole company; default-on) → `Subscriptions` query (CI join;
+  skipped on no CIs) → the Subscriptions `entityInformation/fields` read
+  (the `status` + `periodType` labels; only when subscriptions came back).
+  Every window filter is `gte dateFrom` + `lt` the day
+  after `dateTo` (a datetime field keeps the last day's later rows). All
+  windows and month buckets are UTC days: date-only fields (`itemDate`,
+  units `startDate`/`endDate`) come back as UTC midnight (`Z`), datetimes
+  (ticket `createDate`) as UTC instants, and bucketing slices the ISO
+  string — in a UTC+10/11 tenant a ticket created late local time buckets
+  one UTC day (possibly one month) earlier than its local date. The
   `time_entries.getPosted` / `getUnposted` endpoints are NEVER called (the
   pinned vendor 500 on AU03); posted/unposted derives from the
   `billingItems.timeEntryID` join (unposted = no billing item exists yet).
   The structural exclusions (`/Services/`, `/ExpenseReports/`,
   `/BillingCodes/` list reads, getPosted/getUnposted) are pinned by the
   recorded-request test. Baseline = 12 (a resolvable contract); the
-  typical busy contract = 17; the full fixture = 18. `wires: { issued,
-  budget: 18, note? }` rides the result as the honesty stamp (actual vs
-  budget).
-- **Per-month windowing (parts `billingItems` + `timeEntries`).** One
+  typical busy contract = 18; the full fixture = 20 (21 on a Block Hours
+  contract). `wires: { issued, requests, budget: 21, note? }` rides the
+  result as the honesty stamp: `issued` counts logical part reads (a
+  fetch-by-ids part counts once), `requests` the raw HTTP requests (its
+  chunk queries + per-id gets counted individually; a read-cache-served
+  contract `get` adds no request).
+- **Per-month windowing (parts `billingItems` + `timeEntries` +
+  `contractServiceUnits`).** One
   full-window page (`MaxRecords: limit`); when it comes back FULL with a
   live next cursor, the part re-queries PER CALENDAR MONTH intersecting the
   window (one page per month, the date field bounded to that month, in
@@ -2662,7 +2692,8 @@ returns the contract's reconciled P&L over a date window:
   higher limit`) — NO cursor walk (the house single-page rule; the composite
   owns its own windowing so per-month figures stay correct by construction).
   Every expansion read counts toward `wires.issued` (the note says why);
-  the 36-month cap bounds the worst case.
+  the 36-month cap bounds the worst case. A still-full month is also named
+  in that month's `coverage_gaps` (`<part>: truncated at limit N`).
 - **The cost-rate ladder (per time entry, zero extra wire).** Rung 1
   `billing_item.ourCost`: a LINE cost, not a rate — Σ the finite `>= 0`
   `ourCost` over the entry's billed lines (partial billing across months
@@ -2687,25 +2718,81 @@ returns the contract's reconciled P&L over a date window:
   is NOT a ladder rung (the customer billing rate — the wrong side of the
   P&L).
 - **Monthly P&L (one row per calendar month in the window).**
-  `revenue_invoiced` (Σ `extendedPrice` of the month's items on
-  non-voided invoices) · `revenue_voided_excluded` (Σ on voided invoices) ·
-  `revenue_expected` (Σ `service.unitPrice × units` of the units effective
-  in the month; `null` when the services/units basis is absent) ·
-  `revenue_expected_unbilled = max(0, expected − billed)` · `labour_hours`
-  (Σ raw `hoursWorked`) · `labour_cost { total, unresolvedHours,
-  rateSources }` (the per-month mirror of the ladder audit) ·
-  `tooling_cost { vendor, caller_supplied }` (vendor = Σ subscription
-  `periodCost` per active month in the window; `null` when the
-  subscriptions part is skipped; caller-supplied = the bag value, `0` when
-  absent) · `recurring_cost` (charges `billableAmount` + units `cost`,
-  when included) · `expense_cost` (Σ local-currency expense amounts) ·
-  `total_cost` · `profit = revenue_invoiced − total_cost` ·
-  `margin = profit / revenue_invoiced` when `> 0`, else `null` (the
-  division is refused, not zeroed) · `break_even_hours`
-  (`(total_cost − labour) / (Σcost / Σhours over resolved rows)`, `0` when
-  fixed `<= 0`, `null` with no resolved hours — including an empty month).
-  All amounts are the tenant's LOCAL currency fields
-  (`extendedPrice`, `expenseCurrencyExpenseAmount`).
+  `revenue_invoiced` (Σ the line revenue of the month's items on
+  non-voided invoices; line revenue = `internalCurrencyExtendedPrice`,
+  falling back to `extendedPrice`) · `revenue_by_type { recurring, labour,
+  charges, expenses, other }` (the invoiced split, keyed on the verified
+  `billingItemType` picklist: 1 Labor / 2 Labor Adjustment → labour, 3 Cost
+  → charges, 4 Expense → expenses, 5 Subscription → other, 6 Recurring
+  Service/Bundle → recurring, 7 Recurring Contract Setup Fee → charges, 8
+  Milestone → other; an absent/unknown type falls back to the line's FKs in
+  the order `timeEntryID` → labour, `expenseItemID` → expenses, a charge FK
+  → charges, a contract service/bundle/period/adjustment FK → recurring —
+  labour billed against a service carries `contractServiceID` too, verified)
+  ·
+  `revenue_voided_excluded` (Σ on voided invoices) ·
+  `revenue_posted_uninvoiced` (Σ on posted items with no invoice yet) ·
+  `revenue_unresolved_invoice` (Σ on items whose invoice could not be read
+  or was beyond the join cap — not recognized revenue, never silent: the
+  month's `coverage_gaps` names `invoices: N line(s) on unresolved
+  invoices`) · `revenue_expected` (Σ the period `internalCurrencyPrice`
+  (fallback `price`) of the service units whose
+  period STARTS in the month — a multi-month period is counted once, when
+  it bills; `null` when the services/units basis is absent or the units
+  part is `absent` — unknown, not 0. Unit `price`/`cost` are PERIOD totals
+  (units × per-unit, prorated for a partial period — verified: the type-6
+  recurring billing item has `itemDate` = the unit `startDate` and
+  `extendedPrice` = the unit `price`). Units are normally one month but can
+  span a year; the start-month attribution matches billing, so the monthly
+  figures are a billing-period (cash) view, NOT accrual — an annual unit
+  lands in its start month in one lump) ·
+  `revenue_expected_unbilled = max(0, expected − the month's invoiced
+  SERVICE lines)` (labour and charges never mask a missed recurring
+  invoice) · `unposted_time { entries, hours, hoursAbsent?, value, absent? }`
+  (billable time with no billing item yet — derived from the billing join,
+  never getPosted/getUnposted; `hours` = Σ `max(0, hoursToBill)`, or `null`
+  + `hoursAbsent: 'HOURS_TO_BILL_MISSING'` when any of the month's unposted
+  entries carries no numeric `hoursToBill` — unknown, never a summed 0; a
+  deliberate `hoursToBill: 0` stays 0; `value` = Σ `hoursToBill ×
+  internalCurrencyContractHourlyRate` (fallback `contractHourlyRate`) on
+  Time & Materials contracts only, else `null` + `absent:
+  'NOT_TIME_AND_MATERIALS_CONTRACT'`, `'CONTRACT_TYPE_UNKNOWN'`, or
+  `'NO_CONTRACT_RATE'` when a role has no contract rate, or
+  `'HOURS_TO_BILL_MISSING'` on a T&M contract when the hours are unknown) · `labour_hours`
+  (Σ `hoursWorked` over positive entries — the same rule as the cost) ·
+  `labour_cost { total, unresolvedHours, rateSources }` (the per-month
+  mirror of the ladder audit) · `tooling_cost { vendor, caller_supplied }`
+  (vendor = Σ `periodCost × the periodType monthly share` — by the tenant
+  `periodType` LABEL (monthly 1, quarterly 1/3, semi-annual 1/6,
+  annual/yearly 1/12); a One-Time subscription is never prorated: its
+  `periodCost` is booked whole in its `effectiveDate` month; when the
+  Subscriptions catalog read fails, the verified id maps apply (periodType
+  1 One-Time, 2 Monthly, 3 Quarterly, 4 Semi-Annual, 5 Yearly; status 1
+  Active, 2 Cancelled, 3 Inactive) and the note says so; an unrecognised
+  periodType is excluded and named; only Active subscriptions count —
+  Cancelled and Inactive are excluded — over the subscriptions on this
+  contract's CIs active in the month, REPORTED ONLY:
+  never folded into `total_cost`, since subscriptions bill outside the
+  contract; `null` when the subscriptions part is skipped/absent;
+  caller-supplied = the bag value, `0` when absent) · `recurring_cost`
+  (charge COST — `extendedCost`, falling back to `unitCost × unitQuantity`
+  when it is absent or 0 while a unit cost exists; never `billableAmount` —
+  plus the `cost` of the units starting in the month, when included) ·
+  `expense_cost` (Σ `internalCurrencyExpenseAmount`) · `total_cost` (labour
+  + caller-supplied tooling + recurring + expenses) · `profit =
+  revenue_invoiced − total_cost` · `margin = profit / revenue_invoiced`
+  when `> 0`, else `null` (the division is refused, not zeroed) ·
+  `break_even_hours` (the labour hours the invoiced revenue absorbs at the
+  average resolved cost rate before profit hits zero: `(revenue_invoiced −
+  non-labour cost) / (Σcost / Σhours over resolved rows)`; `0` when the
+  non-labour cost already exceeds revenue; `null` with no resolved hours or
+  a zero rate — including an empty month) · `coverage_gaps` (why the
+  month's figures may be incomplete: `<part>: absent (<code>)` /
+  `truncated at limit N` / `capped at limit N` over units, charges, role
+  costs, billing, time, expenses and subscriptions, plus the unresolved
+  invoice lines; `[]` = complete). The P&L is single-currency in the
+  INTERNAL currency (revenue and costs alike); money fields are emitted
+  rounded to cents.
 - **The 11 data-quality checks (always present, order-stable, `count: 0` =
   a passed check).** Typed `{ code, count, sample_ids }` warnings
   (`count` = the full in-memory/fetched-set count, never capped;
@@ -2721,11 +2808,13 @@ returns the contract's reconciled P&L over a date window:
   `missing_cost_rate` (the ladder's `missing` rows; the resource NOT_FOUND
   misses ride the note) · `recurring_cost_drift` (month-over-month beyond
   the 0.005 float dust; samples the charge/unit ids whose monthly
-  contribution changed) · `expected_unbilled_revenue` (expected >
-  billed + 0.005; the pure "expected with nothing billed" case carries the
-  EMPTY sample — that is the assertion) · `cross_contract_tickets` (the
+  contribution changed) · `expected_unbilled_revenue` (expected > the
+  invoiced service lines + 0.005; the pure "expected with nothing billed"
+  case carries the EMPTY sample — that is the assertion) ·
+  `cross_contract_tickets` (the
   ticket-side drift + the entry-side unresolvable set) ·
-  `open_stale_tickets` (`now − lastActivityDate > staleAfterDays`, `now` =
+  `open_stale_tickets` (this contract's tickets; `now − lastActivityDate >
+  staleAfterDays`, `now` =
   the run's wall clock stamped `period.asOf`; absent `lastActivityDate` is
   unknown, not zero) · `estimate_vs_actual` (both estimates prorated to the
   window — `estimate × overlapDays / termDays` over the contract term — and
@@ -2738,12 +2827,26 @@ returns the contract's reconciled P&L over a date window:
   never silently dropped) · `possible_miscoding` (the probe rows + the
   confirmed cross-contract entries, closed reason set
   `no_contract_on_entry` / `ticket_of_other_contract` /
-  `ticket_not_in_fetched_set`) · `open_renewal_items` (open tickets with
-  the stale-days detail, subscription expirations, the contract end, the
-  per-month `included_hours_burn` row). The probe rows are EXCLUDED from
-  the P&L folds (diagnostic — time not coded to this contract).
-- **Degradation (per part typed `ok` / `blind` / `skipped`; the op NEVER
-  fails the call on a degraded part).** Every tickets call is
+  `ticket_not_in_fetched_set`) · `open_renewal_items` (this contract's open
+  tickets with the stale-days detail, subscription expirations with the
+  prorated monthly cost, the contract end, one `included_hours_burn` row
+  per purchased hour block) · `included_hours` (Block Hours contracts only:
+  `{ value: { purchased, approved, remaining } }` from the `ContractBlocks`
+  `hours` vs the vendor `hoursApproved`; any other contract type is `{
+  value: null, absent: 'NOT_BLOCK_HOURS_CONTRACT' }`, an unresolvable type
+  `'CONTRACT_TYPE_UNKNOWN'` — service units are a
+  quantity, never read as hours, and retainers are dollar-denominated).
+  The probe rows are EXCLUDED from the P&L folds (diagnostic — time not
+  coded to this contract).
+- **Degradation (per part typed `ok` / `blind` / `skipped` / `absent`; the
+  op NEVER fails the call on a degraded part).** Only the contract read is
+  fatal (the root: `NOT_FOUND` — or any other fault on it — propagates).
+  A vendor fault on any bounded list part degrades that part to `status:
+  'absent'` + `absent: <the typed error code>` + the note (never a true
+  zero — no `emptyReason`), and every monthly row it feeds names it in
+  `coverage_gaps`; a non-404 fault on the customer read degrades to
+  `customer: null` + `parts.customer: 'absent'` + `customerAbsent: <code>`.
+  Every tickets call is
   `contractID`-filtered, so the pinned `unfiltered-blind` tickets class
   never stamps a filtered empty (a filtered 0 is a TRUE zero with the
   honest note); the 0-row parts carry the pinned
@@ -2758,6 +2861,34 @@ returns the contract's reconciled P&L over a date window:
   rows with the divisions refused (`margin: null`, `break_even_hours:
   null`, `tooling_cost.vendor: null`, `revenue_expected: null`), all 11
   warnings at `count: 0`, zero tool failure.
+- **Summary-first output (0.13.0).** By default each of the 16 per-part
+  containers (`contractServices` … `subscriptions`) is a
+  `ProfitabilityPartDigest`: every stamp (`status`, `capped`, `hasMore`,
+  `note`, `blindSurface`, `emptyReason`, `absent`) plus `rows_fetched` (the
+  row count), WITHOUT the raw `items` array. Every computed figure is
+  returned either way — `monthly` (incl. `coverage_gaps`), `contract_type`,
+  `included_hours`, `currency`, the activity/costliest-ticket/miscoding/
+  renewal folds, `data_quality_warnings`, `costRateResolution`, `parts`,
+  `wires` — as are the `contract` and `customer` records. `includeRows: true`
+  returns the full `ProfitabilityPart<T>` containers (the pre-0.13.0 shape,
+  `items` included, no `rows_fetched`); the wire is identical in both modes.
+  The part fields are typed `ProfitabilityPart<T> | ProfitabilityPartDigest`
+  (both exported from the package root with the other option/result types):
+  narrow with `'items' in part` before reading rows, e.g.
+  `const rows = 'items' in res.billingItems ? res.billingItems.items : [];`.
+  On the 2-month test fixture the serialised result is 8,657 bytes without
+  rows vs 15,060 with them (−43%); the fixture rows are trimmed to a few
+  fields, so real vendor rows over a 12-month window make the rows the bulk
+  of the payload and the saving much larger.
+- **0.12.1 corrections.** The 0.12.0 folds counted the charge
+  `billableAmount` (sell price) as recurring cost, read service `units` as
+  included hours, joined every company CI's subscriptions and added a
+  yearly `periodCost` every month, compared the expected recurring revenue
+  against all billed lines (labour included) and priced it at today's
+  `unitPrice`, read service units unwindowed, reported time on older
+  tickets as unresolvable, defined break-even without revenue, folded
+  expenses in their own currency, and threw on any bounded-part fault. The
+  bullets above are the corrected semantics.
 - **Registration surface.** The plan row (`capabilities.plan.json` →
   re-derived hash) carries `kind: 'helper'`, `helperBasis: 'composite'`,
   `effect: 'read'`, `dryRun: false`, the closed-bag `inputSchema` (the
@@ -2770,17 +2901,25 @@ returns the contract's reconciled P&L over a date window:
   subset is ticket/contact/company/resource/time_entry only).
 - **Test pins.** `test/resources/contracts.profitability.test.ts`: the
   hand-computed 2-month synthetic fixture (every figure derived from the
-  fixture rows; `wires.issued = 18` with the exact queue; every wire pinned
+  fixture rows; `wires.issued = 20` with the exact queue; every wire pinned
   in issue order; the structural exclusions + zero-mutating recorded paths;
   the ladder audit incl. the per-month `rateSources`; the 11 checks with
   exact counts/samples; the activity/highest-cost/miscoding/renewal folds;
   the per-month windowing (exact extra month queries, id-dedup, the
   still-full month note; `wires.issued` counts the expansion); the
   join-set/`limit` caps; the malformed-bag refusal table (one complete
-  problem list, zero wire); the contract NOT_FOUND).
+  problem list, zero wire); the contract NOT_FOUND; the summary-first pins
+  (the default digest = the full container minus `items` plus the
+  hand-counted `rows_fetched` per part, every computed figure equal across
+  modes, a non-boolean `includeRows` and a missing opts bag refused with
+  zero wire); the 0.12.1 pins: the
+  charge cost/period-type/line-type classifiers, the Block Hours
+  `contract_blocks` path, T&M unposted pricing + the time-referenced old
+  ticket, the exclusive window ends, the month-level `coverage_gaps`).
   `test/resources/profitability-degradation.test.ts`: the empty-tenant
   13-wire suite (every part degrades, zero tool failure), the dangling
-  customer FK, the resources blind-list get-fallback (rung 3 from the
+  customer FK, the non-404 customer fault (`absent`), a bounded-part fault
+  (`absent` + `coverage_gaps`, the call resolves), the resources blind-list get-fallback (rung 3 from the
   gets, the quirk note), the per-item invoice fault (retries off — the
   fault semantics are the pin, not the transport's 5xx budget), the
   fieldCatalog-fault open-pass skip, the status-helper sentinel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime dependencies. Built for building MCP servers and integrations.",
   "type": "module",
   "sideEffects": false,