node-autotask 0.26.0 → 0.28.0

package/N8N_MCP_MANIFEST.md

@@ -1,6 +1,6 @@
 # N8N MCP Manifest — node-autotask (consumer projection)
 
-<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-25T12:41:37.955Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-26T07:54:09.279Z — do not hand-edit. -->
 
 The n8n CONSUMER projection of the capability registry: the canonical source for what the
 n8n-side MCP tools must expose. The SDK is canonical — this is a projection of it, never a
@@ -23,7 +23,7 @@ user's n8n instances; PROD is read-only for any verification).
 
 | tool | mode | entity | readOnlyHint | destructiveHint | idempotentHint | openWorldHint | operations |
 |------|------|--------|--------------|-----------------|----------------|---------------|------------|
-| `autotask_ticket` | read | ticket | true | false | true | true | 14 |
+| `autotask_ticket` | read | ticket | true | false | true | true | 16 |
 | `autotask_ticket_write` | write | ticket | false | false | false | true | 4 |
 | `autotask_contact` | read | contact | true | false | true | true | 10 |
 | `autotask_contact_write` | write | contact | false | false | false | true | 4 |
@@ -36,16 +36,17 @@ user's n8n instances; PROD is read-only for any verification).
 | `autotask_resource` | read | resource | true | false | true | true | 9 |
 | `autotask_resource_write` | write | resource | false | false | false | true | 2 |
 | `autotask_timeEntry` | read | timeEntry | true | false | true | true | 24 |
-| `autotask_timeEntry_write` | write | timeEntry | false | false | false | true | 4 |
+| `autotask_timeEntry_write` | write | timeEntry | false | false | false | true | 5 |
 
 ### `autotask_ticket` (read — ticket)
 
-> Read ticket records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for tickets: count: Count ticket records matching a JSON filter. | findByTicketNumber: Find a ticket by its ticketNumber. | fullContext: Get the full context of one ticket in a single call: the ticket, its company, contact, assigned resource and project, plus its notes, time entries, attachment metadata and (opt-in) histories — every part separately reported. | get: Get one Ticket by id. | getContext: Get a ticket with its primary context records in one call. | getEntityInfo: Get the Ticket capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Ticket field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the Ticket user-defined-field catalog. | query: Query Ticket records with a JSON filter. | resolve: Resolve a Ticket from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (title — exact match only). Returns the Ticket record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search ticket records by text (a vendor contains filter on title only — the vendor exposes no free-text search and no matched-field reporting). | slaHealthCheck: Run the SLA health check for a ticket (numeric ticket id). | summary: Get a one-call summary of a ticket (numeric ticket id). | timeline: Get the event timeline of a ticket (numeric ticket id).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read ticket records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for tickets: count: Count ticket records matching a JSON filter. | findByTicketNumber: Find a ticket by its ticketNumber. | forResource: List the tickets a resource is assigned to — as primary owner, as a secondary resource, or both — de-duplicated, with the four reconciling counts and an optional open-only filter that uses the tenant's own closed-status set. | fullContext: Get the full context of one ticket in a single call: the ticket, its company, contact, assigned resource and project, plus its notes, time entries, attachment metadata and (opt-in) histories — every part separately reported. | get: Get one Ticket by id. | getContext: Get a ticket with its primary context records in one call. | getEntityInfo: Get the Ticket capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Ticket field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the Ticket user-defined-field catalog. | query: Query Ticket records with a JSON filter. | resolve: Resolve a Ticket from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (title — exact match only). Returns the Ticket record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search ticket records by text (a vendor contains filter on title only — the vendor exposes no free-text search and no matched-field reporting). | slaHealthCheck: Run the SLA health check for a ticket (numeric ticket id). | statusSemantics: Report the ticket status picklist and the ids this SDK treats as CLOSED for the caller's tenant, with the provenance of that set (read from the tenant's picklist, or the documented assumed fallback). | summary: Get a one-call summary of a ticket (numeric ticket id). | timeline: Get the event timeline of a ticket (numeric ticket id).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
 | `tickets.count` | count | read | — | none | Count ticket records matching a JSON filter. |
 | `tickets.findByTicketNumber` | findByTicketNumber | read | — | value | Find a ticket by its ticketNumber. |
+| `tickets.forResource` | forResource | read | — | resourceID | List the tickets a resource is assigned to — as primary owner, as a secondary resource, or both — de-duplicated, with the four reconciling counts and an optional open-only filter that uses the tenant's own closed-status set. |
 | `tickets.fullContext` | fullContext | read | — | id | Get the full context of one ticket in a single call: the ticket, its company, contact, assigned resource and project, plus its notes, time entries, attachment metadata and (opt-in) histories — every part separately reported. |
 | `tickets.get` | get | read | — | id | Get one Ticket by id. |
 | `tickets.getContext` | getContext | read | — | id | Get a ticket with its primary context records in one call. |
@@ -56,6 +57,7 @@ user's n8n instances; PROD is read-only for any verification).
 | `tickets.resolve` | resolve | read | — | identifier | Resolve a Ticket from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (title — exact match only). Returns the Ticket record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). |
 | `tickets.search` | search | read | — | query | Search ticket records by text (a vendor contains filter on title only — the vendor exposes no free-text search and no matched-field reporting). Bounded: limit default 25, max 500. |
 | `tickets.slaHealthCheck` | slaHealthCheck | read | — | id | Run the SLA health check for a ticket (numeric ticket id). |
+| `tickets.statusSemantics` | statusSemantics | read | — | none | Report the ticket status picklist and the ids this SDK treats as CLOSED for the caller's tenant, with the provenance of that set (read from the tenant's picklist, or the documented assumed fallback). |
 | `tickets.summary` | summary | read | — | id | Get a one-call summary of a ticket (numeric ticket id). |
 | `tickets.timeline` | timeline | read | — | id | Get the event timeline of a ticket (numeric ticket id). |
 
@@ -245,12 +247,13 @@ Tool input: {"operation":{"type":"string","enum":["transferOwnership","update"]}
 
 ### `autotask_timeEntry_write` (write — timeEntry)
 
-> Write timeEntry records (mode: write — the registry operations with effect=write for time_entries: create, createForResource, createIfNotExists, update). Writes are dry-run first: dry_run defaults to true — the request is validated against the registry inputSchema and a DryRunResult envelope is returned; the mutating request is never issued unless the caller passes confirm (the n8n-side handler must force dry-run unless confirm is present, mirroring the SDK governor). Destructive operations are refused without the confirm flag — confirm must equal the operation key exactly (the deliberate act is the call). The n8n consumer surface excludes destructive operations by curation default (excludeDestructive); they remain available on the canonical SDK server (autotask_delete / per-op tools). By curation default (excludeDestructive) no destructive operation is included; destructive capability remains on the canonical SDK server surface. Per-operation required arguments: create [data]; createForResource [resourceID, params]; createIfNotExists [data]; update [id, data]. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Write timeEntry records (mode: write — the registry operations with effect=write for time_entries: approve, create, createForResource, createIfNotExists, update). Writes are dry-run first: dry_run defaults to true — the request is validated against the registry inputSchema and a DryRunResult envelope is returned; the mutating request is never issued unless the caller passes confirm (the n8n-side handler must force dry-run unless confirm is present, mirroring the SDK governor). Destructive operations are refused without the confirm flag — confirm must equal the operation key exactly (the deliberate act is the call). The n8n consumer surface excludes destructive operations by curation default (excludeDestructive); they remain available on the canonical SDK server (autotask_delete / per-op tools). By curation default (excludeDestructive) no destructive operation is included; destructive capability remains on the canonical SDK server surface. Per-operation required arguments: approve [id]; create [data]; createForResource [resourceID, params]; createIfNotExists [data]; update [id, data]. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
-Tool input: {"operation":{"type":"string","enum":["create","createForResource","createIfNotExists","update"]},"data":{"type":"object","ref":"time_entries body (see types)"},"resourceID":{"type":"number | string"},"params":{"type":"object — the smart-create params: { internallAllocationCodeID?: number (pin the internal linkage code), ticketID?: number, taskID?: number, roleID?: number (pin the task/ticket roleID — vendor-validated as an allocation code), dateWorked?: UTC YYYY-MM-DD, startDateTime?: UTC ISO, endDateTime?: UTC ISO, hoursWorked?: number, + any other vendor TimeEntry field } (exactly one linkage pin; none → the default internal linkage with the node-resolved code)"},"id":{"type":"number | string"},"dry_run":{"type":"boolean","default":true,"note":"true (the default) = the pinned DryRunResult envelope; the mutating request is never issued. The handler must force dry-run unless confirm is present."},"confirm":{"type":"string","note":"The operation key (e.g. \"tickets.create\") — its presence lifts the dry run. For destructive/approval-gated operations confirm must equal the operation key exactly; the call is refused pre-request without it."}} (required: operation)
+Tool input: {"operation":{"type":"string","enum":["approve","create","createForResource","createIfNotExists","update"]},"id":{"type":"number | string"},"data":{"type":"object","ref":"time_entries body (see types)"},"resourceID":{"type":"number | string"},"params":{"type":"object — the smart-create params: { internallAllocationCodeID?: number (pin the internal linkage code), ticketID?: number, taskID?: number, roleID?: number (pin the task/ticket roleID — vendor-validated as an allocation code), dateWorked?: UTC YYYY-MM-DD, startDateTime?: UTC ISO, endDateTime?: UTC ISO, hoursWorked?: number, + any other vendor TimeEntry field } (exactly one linkage pin; none → the default internal linkage with the node-resolved code)"},"dry_run":{"type":"boolean","default":true,"note":"true (the default) = the pinned DryRunResult envelope; the mutating request is never issued. The handler must force dry-run unless confirm is present."},"confirm":{"type":"string","note":"The operation key (e.g. \"tickets.create\") — its presence lifts the dry run. For destructive/approval-gated operations confirm must equal the operation key exactly; the call is refused pre-request without it."}} (required: operation)
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
+| `time_entries.approve` | approve | write | — | id | Approve a time entry (the REST-only approval path): create the BillingItemApprovalLevels record, apply the vendor-documented follow-up update of BillingApprovalDateTime + BillingApprovalResourceID, then read the entry back and report whether the vendor accepted it. Dry-run first (dry_run). |
 | `time_entries.create` | create | write | — | data | Create a time entry. Dry-run first (dry_run). |
 | `time_entries.createForResource` | createForResource | write | — | resourceID, params | Create a time entry for a resource with the allocation-code dependency resolved by the node: it verifies the resource is active, honours the caller's linkage pin (else the default internal linkage), resolves an EXISTING active allocation code applicable to the resource (never creates one — the API user cannot), and posts the vendor-valid body. Dry-run first (dry_run). |
 | `time_entries.createIfNotExists` | createIfNotExists | write | — | data | Create a TimeEntry. Dry-run first (dry_run). |
@@ -271,19 +274,19 @@ only via a recorded change to `n8n-mcp.curation.json`.
 
 ## Stats
 
-- registryRecords: 1225
+- registryRecords: 1277
 - curatedEntities: 7
 - includedEntities: 7
 - readTools: 7
 - writeTools: 7
 - totalTools: 14
-- readOperations: 85
-- writeOperations: 21
+- readOperations: 87
+- writeOperations: 22
 - approvalGatedWrites: 2
 - destructiveExcluded: 4
 
 ## Meta
 
-- generatedAt: 2026-10-25T12:41:37.955Z
-- capabilitiesHash: 670d40c8ba7a05acde7fa679e17c67d3a99a26d3ed07f934d219a5ec2c31cfab
+- generatedAt: 2026-10-26T07:54:09.279Z
+- capabilitiesHash: 246ea3a90022972a2a63bc2131ba631b47a664f7f2c000c4f08dc0b380d5ebfa
 - curationHash: e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b

package/README.md

@@ -4,7 +4,7 @@ Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime
 dependencies. Built for building MCP servers and integrations.
 
 The SDK is also the **deterministic execution layer for agents** (ARCHITECTURE
-section 19): a generated capability registry (1214 operations across the 121-entity
+section 19): a generated capability registry (1275 operations across the 121-entity
 MVP set), a mechanical MCP substrate (registry → manifest → overrides → core tier +
 catalog meta-tool), and a write governor (dry-run-first, destructive
 confirmation). The SDK boundary also redacts response field values — the
@@ -288,7 +288,9 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    destructive ones; the plan-derived `untrustedFields` read tools additionally
    carry the untrusted-content sentence + the field list as the `x-untrusted`
    output-schema extension (issue #1 — externally-sourced free text is
-   marker-wrapped in the projection; the SDK primitives stay raw).
+   marker-wrapped in the projection; the SDK primitives stay raw); the
+   cross-resource tools carry `["*"]` rather than the union (the per-resource
+   lists are the authority, and the served surface has a hard token budget).
 3. **Overrides** — [`MCP_TOOL_OVERRIDES.json`](./MCP_TOOL_OVERRIDES.json): the ONLY
    place a curation delta may live (`{ tool, field, newValue, reason }`); silent
    divergence between projection and curation is a defect; the delta file is reviewed
@@ -344,10 +346,10 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    governor place: `src/operations/invoke.ts`).
 
    **Harness approval policy (recommended).** Require approval on every tool
-   whose MCP annotation is `readOnlyHint !== true` — today exactly **256
-   tools**: the 254 dedicated write/delete tools (198 `effect=write` + 56
+   whose MCP annotation is `readOnlyHint !== true` — today exactly **267
+   tools**: the 265 dedicated write/delete tools (209 `effect=write` + 56
    `effect=destructive`, every one of them has a dedicated tool) +
-   `autotask_write` + `autotask_delete`. The remaining **608 tools** (the 595
+   `autotask_write` + `autotask_delete`. The remaining **631 tools** (the 618
    dedicated read tools + the 10 core read tools + `autotask_read` +
    `autotask_catalog` + `autotask_describe`) all carry `readOnlyHint: true`
    and are safe ungated: every op they can route is `effect=read` (zero
@@ -359,7 +361,7 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    `contacts.moveToCompany`, `resources.transferOwnership`) require the same
    confirm inside `autotask_write`. Migration: `autotask_invoke` is REPLACED
    by `autotask_read`/`autotask_write`/`autotask_delete` — update harness
-   config (approve the 256 above) and remove any `autotask_invoke` entry. The
+   config (approve the 267 above) and remove any `autotask_invoke` entry. The
    rule is derivable from the registry `effect` column (and the mode tools'
    fixed annotations) — it never needs a hand-maintained name list.
 
@@ -413,7 +415,7 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    source.
 
 7. **Agent QoL surface (the stage-12 issue wave, live-verified on ww29)** —
-   the zero-wire planning reads `operations.blindSurfaces` (the 116-surface
+   the zero-wire planning reads `operations.blindSurfaces` (the 124-surface
    blind/data inventory) and `operations.createGuidance` (per-child zone
    facts with verbatim vendor evidence), the bounded live
    `operations.probeReachability` sweep (confirm-gated, over-cap refuses),
@@ -453,7 +455,7 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
 ## Partial-update merge (collectionUpdate resources)
 
 The vendor's top-level **collection PUT** validates the **FULL model**: a partial body is
-rejected with a 500 `Missing Required Field`. This applies to the **40 top-level update ops**
+rejected with a 500 `Missing Required Field`. This applies to the **45 top-level update ops**
 whose spec defines no item-path write (the `collectionUpdate` class — the flag is derived from
 `api-docs.json` by the shared `scripts/lib/collection-update.mjs`, stamped into both the
 generated resource config and the registry record's `metadata.collectionUpdate`, and pinned by
@@ -519,7 +521,7 @@ node-parity paths the vendored swagger lacks, all UNVERIFIED-live this run), and
 | `npm run capabilities:check` | `scripts/check-capabilities.mjs` — the batch gate (missing/incomplete/stale records → exit 1) |
 | `npm run public-surface` | `scripts/public-surface.mjs` — capture (`--write`) / verify the public API surface baseline; default mode fails on unannounced removals, **and** checks the BUILT surface: every tsup entry has a matching `exports` key (and vice versa), every declared target was emitted and loads (ESM+CJS), and no runtime dependency leaks into `dist` |
 | `npm run live-smoke` | `scripts/live-smoke.mjs` — read-only live smoke: 5 vendor probes (5-6 wire calls worst case: 4 GET + 1 bounded query that may walk a 2nd, empty page) + a zero-network shape guard; `--dry` prints the plan with no calls (DRY-RUN-ONLY verdict, exit 0); live via `AUTOTASK_*` env — missing/partial credentials hard-fail exit 2 |
-| `npm run live-coverage` | `scripts/live-coverage.mjs` — the live coverage sweep over all 1217 registry ops (`--dry`: full call plan, no calls; live: bounded reads for real, mutations `dryRun: true` only — zero mutating requests, every governor-gated row (the 54 delete dry-runs included) routed through invoke with `confirm`; budget <= 1161 plan-honest / <= 1315 wire-honest worst case) |
+| `npm run live-coverage` | `scripts/live-coverage.mjs` — the live coverage sweep over all 1275 registry ops (`--dry`: full call plan, no calls; live: bounded reads for real, mutations `dryRun: true` only — zero mutating requests, every governor-gated row (the 54 delete dry-runs included) routed through invoke with `confirm`; budget <= 1161 plan-honest / <= 1315 wire-honest worst case) |
 | `npm run mcp:project` | `scripts/project-mcp-tools.mjs` — mechanical MCP projection → `MCP_TOOL_MANIFEST.md` (`:check` verifies) |
 | `npm run n8n:project` / `n8n:project:check` | `scripts/project-n8n-mcp.mjs` — the n8n consumer projection from the SAME registry → `N8N_MCP_MANIFEST.json`/`.md` (`--check` rebuilds and diffs; the gate is wired into `verify`) |
 | `npm run catalog:build` / `catalog:check` | `scripts/build-tool-catalog.mjs` — the catalog meta-tool row data → `MCP_TOOL_CATALOG.json` + mechanical CORE profile (`--check` verifies drift) |