node-autotask 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.45.0] - 2026-11-01
+
+### Added
+
+- **#313:** bounded special ops for the five MCP-server composites (the server-side building moves into the SDK; the server keeps the registry entry + its untrusted marking):
+  - `contacts.fullProfile(id, opts?)` — the contact (two-stage root: a stage-1 query resolves the company FK, then the parent-scoped root read; a contact with no company FK is its own root and the `company` part degrades to `NO_FK`), plus the `company` and `open_tickets` parts (open = status not in the tenant's live closed-status set, one `noteq` leaf per closed id, with the `closedStatus` disclosure).
+  - `service_calls.fullProfile(id, opts?)` — the service call plus the `tickets` and `tasks` parts and `resource_assignments` (joined through the tasks part's task ids, the `in` filter capped at 100; no task ids degrade the part to `NO_TASKS`).
+  - `contracts.fullProfile(id, opts?)` — the contract plus the `services` and `billing_rules` parts, the `charges` part (the FIXED recent-50 through the count-anchored `latest` — the vendor has no sort parameter) and the `units` part (the fixed 50-row cap; no opts knobs for either).
+  - `resources.workload(id, opts?)` — the resource plus the `open_tickets` part (the `tickets.forResource` rows with the exact open `totals` from a second `countOnly` read beside them; a failed count read keeps the rows and says `totalsAbsent`), `task_assignments`, `task_details` (joined through the assignments' task ids; `NO_ASSIGNMENTS` when there are none), `time_off_balances` and `time_off_requests` parts.
+  - `quotes.withItems(id, opts?)` — the quote plus the `items` part (the `quoteID`-filtered bounded `quote_items.query`).
+  Every part read goes through the same registry seam (`operations.invokeRead`) the MCP server used, so the served shape is preserved field-for-field: `{ root, parts: { <name>: { value, absent?, closedStatus? } } }` — the server keeps its per-part untrusted marking on top. Each part degrades independently to `{ value: null, absent: <the typed code> }`; a missing root fails the call with the typed NOT_FOUND.
+
+### Breaking
+
+- **#289:** delete the low-consumer operations `fetchMany`, `probeReachability`, `blindSurfaces` and the `recovery` op — none has a server consumer (verified against iit-mcp-autotask origin/main c33985a: at most comment-only mentions; `fetchByIds` and `relationshipMap` remain, and the plan-level `blindSurfaces` data the served artifacts stamp from is untouched). `fetchMany` / `probeReachability` / `blindSurfaces` / `recovery` imports from `node-autotask/operations` break at compile time; the three issue-#9 error codes (`DELETE_BOUNDARY`, `MARKER_UNSAFE_ID`, `RECOVERY_TRUNCATED`) stay in the write-outcome taxonomy with no current SDK thrower. The primitive is one `git revert` of this change if ever wanted back.
+- **#291:** `operations.revenueRollup` `groupBy` no longer accepts `contractCategory`, `billingItemKind`, `resource` or `billingCode` — the dimensions are now `vertical`, `contractType`, `company`, `contract`, `month`, `lineOfBusiness` (the `contractCategories` filter option stays).
+- **#291:** `contracts.profitability` `dateFrom`/`dateTo` are now an optional pair: both omitted → the window defaults to the last full calendar month (UTC) and the result's `period` gains `defaulted: true` plus a note (month label + UTC basis); exactly one supplied → a typed `CONFIG_ERROR` pre-request (a half window is never sent); both supplied → the existing validation.
+- **#290:** the time-entry posted-state and date-window ops are consolidated into the single `time_entries.dateWorkedWindow(from, to, opts)` read. Removed: `time_entries.getPosted` / `time_entries.getUnposted` (the `state: 'posted' | 'unposted'` option replaces the state modes; the no-window forms are gone — read with no dateWorked filter through `time_entries.query`), `time_entries.postedWithin` (its boolean `posted` flag becomes `state`), and the eleven date-window ops plus `customRange` on `time_entries`, `billing_items` and `invoices` (the shared `dateWindow` machinery is deleted with them). The consolidated op keeps the inclusive window, the server-side `ticketID` / `resourceID` narrowings, the 500-row cap, cursor paging (`nextCursor` / `cursor`), the `countOnly` whole-window totals with the `maxVendorCalls` budget, and the posted/unposted split derived from `billing_items.timeEntryID`.
+- **#292:** special-op simplification. Dropped the internal `http` argument from the special-op functions (the client method binds it; `BaseResource.http` is now a public getter) and removed the per-module barrel re-export hop (`src/resources/special/<module>.ts` — imports now go to the module files directly). Deleted the unused write ops: `time_entries.approve` (the BillingItemApprovalLevels composite — the REST-only approval path stays raw: `billing_item_approval_levels.create` + the documented follow-up update), `time_entries.createForResource` (the allocation-code-aware smart create — resolve the allocation code via `billing_codes` and use raw `time_entries.create`), `tickets.openWithNoteAndAssign` (the create+note+assign composition — compose `tickets.create` + `ticket_notes.create` + the update), and `resources.transferOwnership` (bulk ownership re-own — raw `companies.update` of `ownerResourceID`). Cut the resource-specific find-or-create helpers as well: every `createIfNotExists` special op, `companies.upsertByName` and `contacts.upsertByEmail` — natural-key dedup stays a search-then-create composition; the generic base-resource `createIfNotExists` primitive and `CreateIfNotExistsResult` remain.
+
+### Changed
+
+- **#291:** the financial-reporting operations' shared machinery (call-budget counting wrapper, id-chunk fetch with per-chunk fault isolation, integer-cent fold, label resolution) is extracted into one tested module; the covered suites pass unchanged (behaviour byte-identical).
+
+### Removed
+
+- **#291:** the dead live-probe scripts under `scripts/live-probes/financial-reporting/`.
+
+## [0.44.0] - 2026-11-01
+
+The capability plan changed (staff resolution and read-contract updates), so this release needs a minor bump.
+
+### Breaking
+
+- **#350:** explicit `walk.maxRows` replaces the ordinary total cap instead of taking its minimum: `{ limit: 100, walk: { maxRows: 2500 } }` can return 2500 rows. Direct explicit walks now honor `names` and client `labels`; pass `names: false` for raw rows. Ordinary bounded query and latest behavior are unchanged.
+- **#351:** self-prefixed dotted UDFs are now refused rather than rewritten to a different tenant field. Use the literal undotted UDF name.
+- **#353:** `operations.resolveAny({ match: 'auto' })` now completes every exact lookup before falling back to the existing bounded cross-resource search. Only clean misses everywhere allow contains matching; exact hits, ambiguity, truncation and faults block fallback. The result identifies `matched: 'exact' | 'contains'` and carries the contains-search payload when used; `limit` is an integer 1..500 and can only narrow the configured resolution scan cap (at most 500); malformed limits refuse before lookup requests. The default exact-only behavior is unchanged.
+- **#354:** untrusted projection now fences nested UDF values and named string arrays, bounds deep/cyclic input and safely copies prototype-like keys. Hosts retain unsafe-character cleaning, length caps and provenance for formatted output; projection does not grant vendor strings any formatting exemption. An unstamped result containing UDF values can now return a projected copy instead of its original reference.
+
+### Added
+
+- **#353:** `operations.resolveStaff` resolves staff by id, email, username or full name. Text lookups require active staff and exclude API users identified by tenant labels unless opted in; numeric id lookups bypass those filters. Candidate limits, truncation and metadata availability are explicit. Text records honor the client’s existing `labels` setting, preserving expanded staff label siblings; projection fences both licenseTypeLabel and userTypeLabel. Numeric-id misses propagate NOT_FOUND; text misses return an empty matches list.
+
+### Fixed
+
+- **#350:** query `walk.maxRows` is the total returned-row cap, independently of the ordinary `limit`/page-size bound, so export-sized walks can return up to the requested total. Scope checks estimate the actual walk, and truncation remains true while a cursor or unserved rows remain. Explicit walks preserve the iterator’s per-vendor-page label budgets and avoid a second labeling pass; ordinary invoked queries keep their per-call budget.
+- **#351:** dotted UDF names, including self-prefixed aliases, are refused before metadata or vendor requests, preserving literal tenant UDF identity.
+- **#352:** self-resource prefixes are normalized consistently in query projection and aggregate group/sum fields, preserving date buckets and parent relations without mutating caller options.
+
 ## [0.43.0] - 2026-10-31
 
 ### Changed