node-autotask 0.20.0 → 0.23.0

package/ARCHITECTURE.md

@@ -64,25 +64,28 @@ proves the mapping op-by-op.
 src/
   index.ts                 # Public API barrel (default + named exports)
   client.ts                # AutotaskClient — top-level facade; wires all resources + operations
-  config.ts                # AutotaskConfig, AutotaskClientOptions, zone catalog + zoneUrl(), validation, defaults
-  http.ts                  # HttpClient — fetch transport, URL/query building, POST/GET query switch,
-                           #   envelope unwrap helpers (pinned to the G1 envelopes)
+  config.ts                # barrel -> config/ (types, zones + zoneUrl(), defaults, profiles, resolve/validation)
+  http.ts                  # barrel -> http/ (HttpClient.ts = fetch transport; request-builders.ts = URL/query
+                           #   building + POST/GET switch; envelope.ts = unwrap helpers pinned to the G1
+                           #   envelopes; retry.ts, breaker-budget.ts, zone.ts, credentials.ts, body.ts, types.ts)
   auth.ts                  # 3-header auth (ApiIntegrationCode/UserName/Secret) + ImpersonationResourceId
                            #   + authenticate() token alternative; credential redaction list
-  errors.ts                # AutotaskError hierarchy + errorFromStatus + vendor error-body parsing
+  errors.ts                # barrel -> errors/ (base.ts hierarchy root, http.ts transport errors, mutation.ts,
+                           #   from-status.ts errorFromStatus, vendor-errors.ts vendor error-body parsing)
   pagination.ts            # Page<T>, cursor-follow walk (nextPageUrl), collectAll(), toArray()
   query.ts                 # Filter builder: 13 operators + and/or grouping, caps, GET<=2048 measurement
   logger.ts                # Logger interface + NoopLogger
-  utils.ts                 # assertRecord, deep-merge of params, identifier helpers, UDF flatten
+  utils/index.ts           # assertRecord, deep-merge of params, identifier helpers, UDF flatten
   capabilities.ts          # GENERATED capability registry (./capabilities) — never hand-edited
   operations/
     index.ts               # ./operations barrel
-    search-across.ts       # searchAcrossResources (cross-resource bounded text search)
-    resolve-any.ts         # resolveAny (cross-resource identifier resolution)
-    invoke.ts              # registry-driven invoke + write governor (G6; MCP projection consumer)
+    searchAcrossResources.ts  # cross-resource bounded text search
+    resolveAny.ts          # cross-resource identifier resolution
+    invoke.ts + invoke/    # registry-driven invoke + write governor (dispatch, validate, modes, wrappers, ...)
+    ...                    # aggregate, fetchMany, fetchByIds, recovery, relationshipMap, probeReachability, ...
   resources/
     index.ts               # Barrel for all resource classes + resources() accessor
-    base.ts                # BaseResource<T> — shared query/get/create/update/delete scaffolding,
+    base.ts + base/        # BaseResource<T> (base/BaseResource.ts; query/mutations/meta/helpers split) — shared query/get/create/update/delete scaffolding,
                            #   entityInfo ops, dry-run scaffolding, scan guards
     companies.ts           # CompaniesResource (top-level entity template — see §12.1)
     company_notes.ts       # CompanyNotesResource (parent-scoped child template — see §12.2)
@@ -99,12 +102,14 @@ src/
 test/
   __fixtures__/            # Mock JSON responses per resource (derived from api-docs.json definitions)
   client.test.ts           # AutotaskClient construction + wiring
-  http.test.ts             # transport, envelopes, error mapping, retries, POST/GET query switch
+  http/                    # one file per concern: transport, envelope, retry, query-builders, hardening,
+                           #   concurrency, logging, mutation-retry
   pagination.test.ts       # cursor-follow walk (nextPageUrl), 1000-page guard
   query.test.ts            # filter builder, caps, GET-length fallback
   config.test.ts           # zone/baseUrl/credentials/pageSize validation
   auth.test.ts             # header shape, impersonation, redaction
   errors.test.ts           # error hierarchy + vendor error-body parsing + item:null semantics
+                           #   (plus errors-*.test.ts and transport-*.test.ts concern files)
   operations/              # searchAcrossResources / resolveAny tests
   resources/
     companies.test.ts      # one spec-per-resource file, alongside each resource
@@ -273,7 +278,7 @@ shape only — deliberately.** Do not "fix" this without reading the reason:
 
 ## 6. Config, validation, and defaults
 
-### `config.ts`
+### `src/config/`
 ```ts
 export type ZoneName =
   | 'pre-release' | 'pre-release-uk' | 'limited-release' | 'limited-release-uk'
@@ -484,7 +489,7 @@ Vendor filter structure (swagger `Filter`, recursive):
 
 ---
 
-## 8. HTTP transport (`http.ts`)
+## 8. HTTP transport (`src/http/`)
 
 - Uses the **native global `fetch`** (native since Node 18; this package's floor is Node >= 24). **Zero runtime dependencies** across the
   whole package.
@@ -571,18 +576,18 @@ export interface RequestOptions {
    auto-unwrap — envelope unwrapping is an explicit per-call decision made by the resource
    layer using the helpers below, pinned to the G1 envelopes.
 10. **Redirects are never followed**: every request is sent with `redirect: 'manual'`
-    (`src/http.ts:911`; the zone-discovery call `:673` likewise, with the same comment). A
+    (`HttpClient.ts`; the zone-discovery call in `src/http/zone.ts` likewise, with the same comment). A
     `3xx` on a normal request cancels the body and throws immediately — no second request
     is made:
     - error: `ResponseRejectedError` with `code: 'REDIRECT_BLOCKED'`, `category: 'policy'`,
       `retryable: false`, `httpStatus` = the 3xx status, and `suggestedAction: 'Check the
-      configured zone/baseUrl; the API does not redirect.'` (`src/errors.ts:135` for the
-      class; the throw site is `src/http.ts:940`).
+      configured zone/baseUrl; the API does not redirect.'` (`ResponseRejectedError` in
+      `src/errors/http.ts`; the throw site is in `src/http/HttpClient.ts`).
     - why: **this SDK attaches credentials to every request**, and a native redirect
       follow re-sends those headers to the redirect target — even cross-origin. Wrapping
       the refusal in a typed error is deliberate (issue #27 shape).
     - the `Location` header is never read, so an attacker-supplied target cannot reach the
-      caller through the message (`test/http.test.ts:530` — "never follows redirects:
+      caller through the message (`test/http/hardening.test.ts` — "never follows redirects:
       sends redirect `'manual'` and refuses a 3xx without a second request" — pins exactly
       one wire call, `redirect: 'manual'`, `code: 'REDIRECT_BLOCKED'`, `retryable: false`,
       and no `evil.example` in the text). Shipped in v0.3.1 (`CHANGELOG.md`); the same
@@ -597,7 +602,7 @@ export interface RequestOptions {
       redirect resolved, and the skill's `manualRedirect` escape hatch (only for endpoints
       whose contract IS a redirect) does not apply here; the builder does not implement one.
 
-### Envelope unwrapping helpers (in `http.ts`, used by `BaseResource`)
+### Envelope unwrapping helpers (in `src/http/envelope.ts`, used by `BaseResource`)
 ```ts
 /** query: expects { items: T[], pageDetails: PagingModel }; validates both present. */
 export function unwrapItems<T>(body: unknown): { items: T[]; pageDetails: PagingModel };
@@ -669,7 +674,7 @@ export function withAuthHeaders(
 
 ---
 
-## 10. Error hierarchy (`errors.ts`)
+## 10. Error hierarchy (`src/errors/`)
 
 ```
 AutotaskError (base; extends Error)
@@ -1000,7 +1005,7 @@ export const NoopLogger: Logger = {};
 
 ## 16. Testing strategy
 
-- **HTTP layer (`http.test.ts`)**: mocked global `fetch` — URL construction, auth headers
+- **HTTP layer (`test/http/*.test.ts`)**: mocked global `fetch` — URL construction, auth headers
   (swagger casing + impersonation), POST/GET query switch (incl. 2048-char `QUERY_TOO_LONG`),
   envelope pass-through, per-envelope unwrap errors, error mapping per status (vendor error
   body formatting), retry/backoff on 429 with `Retry-After`, `Itgenatr005` as retryable
@@ -1022,7 +1027,7 @@ export const NoopLogger: Logger = {};
 - **Coverage gate** (vitest config): lines >= 90 / functions >= 90 / branches >= 80 /
   statements >= 90 (coordinator default from SCOPING F; node-hudu's 97/94/83/97 is the
   stretch target — ratchet at v0.2 once generated-resource tests settle).
-- **Additive-only surface proof**: `test/public-surface.test.ts` compares the live
+- **Additive-only surface proof**: `scripts/public-surface.mjs` (exercised by `test/scripts/generated-gates.test.ts`) compares the live
   exported surface against `test/__fixtures__/public-surface.json`, captured at the G3
   baseline. Removing a baseline name fails the suite; additions are reported, not failed.
 - **Capability gate**: `check-capabilities.mjs` ships with a committed negative fixture
@@ -1036,7 +1041,7 @@ Gates G3–G7 of `.run/CHECKLIST.md`; the per-batch loop never regenerates the w
 until G6 (mechanism in `.run/design/generator-design.md` §10):
 
 1. **G3 — Core + scaffold.** `package.json`/tsconfig/tsup/vitest/eslint; `logger.ts`,
-   `errors.ts`, `auth.ts`, `utils.ts` (no deps) → `config.ts` (+tests) → `http.ts`
+   `errors/`, `auth.ts`, `utils/` (no deps) → `config/` (+tests) → `http/`
    (+tests) → `pagination.ts`, `query.ts` (+tests) → `types/common.ts` →
    `resources/base.ts` → capture the public-surface fixture. Green:
    `npm run typecheck && npm test && npm run build`.
@@ -1258,3 +1263,21 @@ What it ships instead:
   `examples/mcp-server-http.ts` (SSE/streamable-HTTP transport). They are the reference
   implementations the future Autotask MCP server package is built from; the SDK itself
   remains MCP-import-free.
+
+### 19.6 Composite moves (issue #197)
+
+Some vendor entities accept an update of their parent field and silently keep the
+old value (live-probed on ww29: time entries and ticket charges; ticket notes DO
+move on a parent-scoped update). Where the entity can be deleted, a move is a
+composition on the shared engine (`special/_shared/move-engine.ts`): GET-only preview
+-> hard invariants -> twin check -> create (once) -> read-back compare -> source
+re-read -> delete (once), with rollback of the new record on any mismatch or drift.
+The engine returns only for `moved` / `moved_source_absent` / `moved_manual_delete`;
+every other outcome throws a typed `MoveRefusedError` carrying `details.status`
+(`failed` / `partial` / `unknown`). Entities the API cannot move or cannot finish
+deleting hand the person a `manualAction` with an `operations.uiLink` deep link
+(the record where ExecuteCommand supports it, else its parent ticket). The SDK
+authorises nothing (company scope and ownership are the caller's job) and stores
+nothing (the source snapshot is returned). A new resource joins by supplying a
+`MoveSpec` (copy set, invariants, verify list) and one plan row.
+

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-10-21
+
+The plan hash moves (MINOR) — plan-pinned consumers must re-pin. The 0.23.0 plan hash is `95746a69c86d…` (recorded in `scripts/published-plan-hashes.json` after publish).
+
+**W-A3 time-entry zone fact re-scoped (issue #195).** The 2026-10-06 note claimed the vendor "refuses ALL time-entry writes for this API-only user" (UNSATISFIABLE); live `time_entries.create` calls succeeded on 2026-10-21 (pair not recorded; two entries, read back, 1.0 h). The served wording (plan `pointerNotes` + `createGuidance` blocker message/remedy, the four time-entry tool-description overrides, `docs/API.md`) is now a (resource, role) pair-scoped wall: the pair selecting the API-only user's own resource was refused 2026-10-06. The authorised pair set has NOT been re-adjudicated by a live probe.
+- Single source: the wording lives in `capabilities.plan.json`, regenerated into `capabilities.json`, `src/capabilities.ts`, `src/relationships.ts` and the MCP/n8n manifests and catalog.
+- The plan records the success as `zoneFacts.resources.time_entries.liveWrites[]`; new gate clause 18 (`scripts/lib/checks/clause18-zone-fact-liveness.mjs`, test `test/scripts/zone-fact-liveness.test.ts`) fails when a plan zone fact (blocker message/remedy, pointer note) or an `MCP_TOOL_OVERRIDES.json` row asserts a wall (UNSATISFIABLE / refuses all, case-insensitive) stamped before a recorded successful live write of the same op.
+- `scripts/s13b-plan-patch.mjs` no longer writes `pointerNotes` (its archived copy would overwrite the re-stamped rows with older-dated text).
+- Invoke (#196): the query/count field-name refusal now embeds the entity's first 20 field names (`(and N more)` beyond that) in `err.message`, and its suggestedAction points at `operations.fieldCatalog` scoped with `resources: ["<entity>"]`; no extra wire. No plan-hash change.
+
+### Added (wave-1: #197, #198, #200, #201, #202)
+
+- Governed create-verify-delete moves (#197): `time_entries.moveToTicket` and `ticket_charges.moveToTicket` on a shared move engine, because the vendor accepts an update of `ticketID` but silently keeps the old value (live-probed). Dry-run-first (GET-only preview), `confirm` required, typed `MOVE_*` refusals (billed/approved/attachments/too old/twin/closed target), read-back compare, source re-read, rollback, results `moved` / `moved_source_absent` / `moved_manual_delete`, with a `manualAction` carrying an `operations.uiLink` deep link where a person must finish in the UI. New `MoveRefusedError`. Served hints now warn that `ticketID` does not persist on update and that deleting a time entry destroys its attachments; `ticket_notes` update documents that the scoped `ticketID` update moves a note. **Plan hash moves:** `bc4308db3dec…` → `95746a69c86d…` (MINOR; recorded after publish). Registry now 1216 ops / 853 tools.
+- `companies.fullProfile` per-part field projection and `locationLimit` (#200): `fields: { contacts: ['id','firstName'], openTickets: [...] }` serves only the listed fields for a listed part (`IncludeFields` on the wire, then picked client-side); unlisted parts and the no-`fields` call are unchanged. Unknown part key or field name is refused pre-request (zero wire). `locationLimit` (1-500, default 50) replaces the fixed locations cap and drives `locations.capped`. Additive, minor; the plan hash is unchanged (the registry record and generated artifacts carry the new bag keys).
+- `operations.uiLink` (#202): a pure, zero-wire meta op (plus the `buildUiLink` helper) that builds Autotask ExecuteCommand deep links for time entries, tickets (by id or ticket number), tasks, projects, companies, contacts, contracts and configuration items. The `ww<N>` UI host is derived from the client's `webservices<N>` base, never guessed (no link for `pre-release-de`/`-es` or custom hosts unless `host` is passed). Ids are positive safe integers, ticket numbers match `^T\d{8}\.\d{4}$`. **Plan hash moves** (new meta op row): `03a3bf610a85…` → `bc4308db3dec…` (MINOR; recorded after publish). Registry now 1214 ops / 851 tools.
+- `operations.searchAcrossResources` accepts an optional `totalLimit` (#201): caps matches across all resources; resources are searched in request order, each asked for `min(limit, remaining)`, later ones are not queried and are reported in `notSearched`, with `truncated`. Absent `totalLimit` the result is unchanged. `limit` is now documented as per-resource (the old header said "one limit budget"). Additive, minor.
+
+### Changed (wave-1: #198)
+
+- Positional-arity refusal text (#198): dropped the v0.2.0 history aside, and when the surplus arg is a plain object on an op that declares an options bag it adds "options go inside the single `<bag>` object". Message text only; no behaviour or plan change.
+
+## [0.22.0] - 2026-10-21
+
+**Plan `tests[].file` paths refreshed (issues #194, #189).** The plan hash moves (MINOR) — plan-pinned consumers must re-pin. 111 `operations[].tests[]` rows that named pre-split test files now name the file where their title lives; titles are unchanged and the drift gate still resolves by title, so there is no behavioural change.
+- Transport (#184, #190): the per-request deadline timer is now owned by one `try/finally` from the moment it is armed, so a cooldown or breaker refusal, or a throwing `logger.debug` / audit-body redaction, can no longer keep the event loop alive for `timeoutMs`; regression tests spy on `clearTimeout`.
+- Types (#191): the 24 `BaseResource` members that went `private` -> `protected` only to span the query/meta/mutations layers (`cachedGet`, `walkBounded`, `latestWalk`, `unwrapCreateOperation`, ...) are marked `@internal` and stripped from the published `.d.ts` (`stripInternal`); they are not public API and subclasses outside the package cannot rely on them.
+- Tooling (#187, #188, #189): the cache-write-invalidation static guard now scans every `boundedPart`/`readPart`/`windowedPart`/`expandByMonth` caller across all of `src/`; `derive-plan` finds BaseResource methods in `src/resources/base/{query,meta,mutations}.ts`; the test-title lookup ignores comments and `emit(`/`submit(` lookalikes, honours the injected `readFile`, and the capability gate fails a pinned title declared in more than one test file.
+
+- Capability gate (#185): plan `tests[]` rows are now resolved by title across `test/**` (the `file` field is informational); `staleCheck.testFiles`/`testHash` are dropped from the registry. Plan hash unchanged. Test files can be renamed/split freely; the six sprint-coded test files were split by concern.
+- Security (dependabot #182, #183): dev-scope lockfile bumps only — @modelcontextprotocol/server 2.2.0 → 2.3.0 (fixes GHSA-46jr-4wx8-v453, GHSA-jm63-cq47-j5jp, GHSA-rvq5-wwqv-78pq) and vite 8.3.1 → 8.3.4 (fixes GHSA-587h-7wmj-h5pm, GHSA-698v-4r3x-3vcv, GHSA-r825-w8mm-5pxw). No runtime surface change (the package has no runtime dependencies).
+
+## [0.21.0] - 2026-10-21
+
+**Structured bag properties, core ops in the catalog, op-key error text (issues #162, #163, #164, #177, #178, #179, #180, #181).** The plan hash moves to `baf3e855956e` (MINOR) — plan-pinned consumers must re-pin.
+- **Bag `properties` (#162).** every object-typed `inputSchema` arg whose prose declares a `{ key?: type (...) }` bag now also carries `properties: [{ name, type, optional, default? }]` (e.g. `companies.query` params: `limit` default 500, `fieldCheck` default true), derived from the same description text at generation time so the two cannot drift. Additive; the prose is unchanged.
+- **Core ops in `MCP_TOOL_CATALOG.catalog` (#163).** the 10 core-profile backing ops (`resources.whoAmI`, `version.get`, `threshold_information.get`, `operations.resolveAny`, `operations.searchAcrossResources`, `{companies,configuration_items,contacts,projects,tickets}.resolve`) are now catalog rows, flagged `core: true` (every row carries `core`); `counts.catalogRows` equals `registryOperations` (1213). `coreProfile` is unchanged.
+- **Property types (#177).** bag `properties` types are now real type expressions (`(number | string)[]` for `ticketIds`, `string` for the date strings, `'find' | 'delete'` for `operations.recovery` action); a test fails on any unrecognised type token.
+- **Literal defaults (#179).** string-literal enum defaults (`companies.unbilledWork` `source`/`rollup`, `contracts.profitability` `labourCostMethod`) and the `operations.fieldCatalog` `include` array default now appear in `properties[].default`; non-literal prose defaults (e.g. 'today') stay prose-only.
+- **Array defaults and bag keys (#180, #181).** `CapabilityArgSchema.properties[].default` is now typed `number | boolean | string | string[]` (also `BagProperty` and `capabilities.schema.json`, `default` allows an array of strings), so `operations.fieldCatalog` `include` default `['fields']` validates; `names` / `maxNameReads` (default false / 20) are now documented for `tickets.fullContext`, `companies.fullProfile` and `configuration_items.profile` and appear in their `properties`. A test checks every record's properties against the schema and every key of a named `*Options` interface against the record bag. `testHash` / `capabilities.json` served text moved.
+- **Served text (#178).** served capability descriptions, the plan and docs point at the op key `operations.resolveAny` instead of the tool name.
+- **Error text (#164).** the pre-request refusals of `operations.fetchMany` / `operations.expandResourceNames` for non-numeric string ids name the op key `operations.resolveAny`, not the tool name.
+
 ## [0.20.0] - 2026-10-20
 
 **Filter pre-validation, the latest-probe count cache, and the window/search/aggregate served-text corrections (issues #125, #127, #128, #129, #130, #131).** The plan hash moves to `f6a579e0b7a8` (MINOR) — plan-pinned consumers must re-pin.