node-autotask 0.43.0 → 0.44.0

package/docs/API.md

@@ -685,6 +685,22 @@ carry paging parameters.
   when the limit or the guard truncated the walk and more records exist past
   the stop point; `pageDetails.count` is never surfaced (it is the current
   page's record count — `<resource>.count` is the total).
+  - **`walk: { maxRows: N }` — an explicit export cap (issue #350).**
+    `N` is a positive integer and replaces the total `limit` cap, so
+    `{ walk: { maxRows: 10_000 } }` can return 10,000 rows. `limit` still
+    validates as 1..2500 (default 500) and only sizes pages in this mode:
+    `min(500, limit)`. `truncated` and `hasMore` are true when the final
+    page was sliced, a next cursor remains, or the 1000-page guard stopped
+    the walk, even below `maxRows`; an exhausted exact-cap result reports
+    false. No extra page is fetched to decide completeness. With no `walk`,
+    the ordinary cap and result shape remain unchanged (`truncated` is
+    omitted). `walk` and `latest` cannot be combined. Through `invoke`, the
+    unscoped-walk guard estimates the explicit `maxRows` cap independently
+    of `limit`; narrow the filter or pass `acknowledgeUnscoped: true` when
+    a large unscoped walk is intended. When names are enabled (per call or
+    by client labels), explicit walks apply the existing label budget per
+    fetched vendor page, matching the iterator; invoke does not label the
+    combined result again. Ordinary invoked queries keep their per-call budget.
   - **`latest: N` (issue #59) — the N highest-`id` rows without caller paging.**
     The vendor has NO sort parameter (the vendored spec's `QueryModel` is
     exactly `maxRecords` / `includeFields` / `filter`), so `latest` is a
@@ -780,23 +796,28 @@ Vendor filter structure (swagger `Filter`, recursive):
   `project.<field>` is resolved before the query: the parent entity is read
   (`IncludeFields: ['id']`, at most 300 rows) with the relation's conditions,
   and the leaves become `<relation>ID in [ids]`. Supported by `queryBounded`
-  (and the invoke `query` op), `count` and `operations.aggregate`; the raw
-  `query()`/`queryAll()` walks do not rewrite.
+  (and the invoke `query` op), `count`, `operations.aggregate`, and the raw
+  `query()`/`queryAll()` walks.
   - Inside an `and` (and at the top level) all leaves of one relation share ONE
     parent read; inside an `or` each relation leaf is its own read. Direct
     conditions are untouched and may be mixed freely.
   - No parent match: an `and` matches nothing; an `or` drops that branch. When
     the whole filter matches nothing the child call is not issued: `queryBounded`
     returns `{ items: [], fetched: 0, hasMore: false, pagesWalked: 0,
-    relationNote }`, `count` returns `0`, aggregate group/sum carries
+    relationNote }` (plus `truncated: false` for an explicit `walk`),
+    `count` returns `0`, aggregate group/sum carries
     `relationNote`.
   - More than 300 matching parents: typed `AutotaskConfigError`, child call not
     issued (a capped parent set would be vendor-ordered, so partial totals would
     be biased). Narrow the relation conditions (e.g. a ticket date or status).
   - Pre-request (zero wire): unknown relation, a parent field outside the
-    parent's vendored field set, multi-hop (`ticket.company.x`) and `udf: true`
-    relation leaves are refused. The invoke field-name check skips relation
+    parent's vendored field set and multi-hop (`ticket.company.x`) are
+    refused. The invoke field-name check skips relation
     leaves (they are checked against the parent instead).
+  - Any dotted `udf: true` field is refused before metadata, parent queries,
+    scope counts or child requests, including self prefixes and unknown
+    prefixes (issue #351). Use an undotted tenant UDF name with `udf: true`;
+    `fieldCheck: false` does not bypass this rule.
 
   ```ts
   // company 123's time in October, hours per ticket: 2 calls (tickets ids, then the walk)
@@ -829,11 +850,20 @@ Vendor filter structure (swagger `Filter`, recursive):
   the cap). A GET path exists (`{ via: 'get' }`) and the SDK measures the
   serialized GET URL — over 2048 it throws `QueryTooLongError` (never a
   silent degradation).
-- `includeFields` passes through vendor column selection; the SDK never
-  invents column selection — one exception: when `includeFields` is set the
-  SDK always appends `id` (the vendor omits `id` from a row unless it is
-  named in the selection, and every caller needs the id to act on the row —
-  issue #59).
+- **Own-field aliases (issue #352):** a single self prefix — the resource
+  key, or a relation name targeting that resource — is stripped from
+  ordinary filter fields, `includeFields`, and aggregate `groupBy` / `sum`.
+  On tickets, `ticket.title` and `tickets.title` mean `title`; on time
+  entries, `time_entries.hoursWorked` means `hoursWorked`, while
+  `ticket.companyID` remains a parent relation filter. Aggregate date
+  suffixes are preserved (`time_entries.dateWorked@month` becomes
+  `dateWorked@month`), and result keys use the canonical unprefixed names.
+  Foreign and multi-hop names are never converted into own-field aliases.
+  Projection normalization applies on the first page and every cursor
+  continuation, without mutating the caller's input.
+- `includeFields` selects vendor columns after own-field normalization; the
+  SDK always appends `id` when omitted (the vendor omits `id` unless it is
+  selected, and callers need it to act on the row — issue #59).
 
 ## 6. Mutation safety
 
@@ -962,7 +992,48 @@ candidates and the error code when a resource could not resolve (empty
 the primary text field, exact match only; with `resolution.scanOnMiss` the
 bounded client-scan re-check (and its truncation cap) applies per resource. Returns
 `{ identifier, results: [{ resource, value, resolutionCost, scanned,
-scanTruncated, candidates, error? }], matches }`.
+scanTruncated, candidates, error? }], matches, matched }`.
+
+`match` defaults to `'exact'`. With `match: 'auto'`, every requested
+resource finishes its exact lookup before a contains search can start. Only
+a clean miss everywhere permits the contains sweep; an exact hit,
+ambiguity, truncated scan, unsupported resolver or lookup error suppresses
+it. Numeric ids and digit strings never fall back to contains. Auth,
+rate-limit, server, network, timeout and policy faults propagate.
+
+The contains sweep defaults to the client’s `resolution.maxScanRecords`,
+capped at 500. Optional `limit` must be an integer 1..500 and can only
+narrow that configured cap; invalid values refuse before lookup wire.
+Exact lookup sizes are unchanged. A singleton below the cap resolves; multiple matches
+report candidate ids, and a cap-full result reports `scanTruncated: true`
+and `RESOLUTION_TRUNCATED`, even if the cap is one. `matched` reports
+`'exact'` or `'contains'`; only the latter includes the full sweep in
+`contains`, including an empty sweep.
+
+**`resolveStaff(client, identifier, opts?)`** looks up Autotask resources
+by exact email, userName or name. Text matches require `isActive: true`
+and exclude API users by default, using tenant picklist labels on
+`licenseType` / `userType` rather than fixed numeric values. Numeric ids
+fetch directly and bypass active/API-user exclusions. `emailOnly: true`
+treats even digit strings as email; `includeApiUsers: true` includes API
+users in text matches. Options form a closed plain-object bag: flags must be
+booleans when present and limit must be an integer 1..10. Unknown keys, nulls
+and malformed options refuse with CONFIG_ERROR before metadata or lookup wire.
+
+Returns `{ identifier, lookup: 'id' | 'text', matches: [{ record, apiUser?,
+licenseTypeLabel? }], matchedCount, truncated, metadataState }`. `limit`
+is 1..10 (default 10); the text lookup reads at most 50 records.
+`matchedCount` is after exclusions and before the candidate limit, and is
+a lower bound when truncated. A live cursor or a candidate-limit cut sets
+`truncated: true`; a truncated singleton never proves uniqueness. Text
+misses return an empty `matches`; a numeric miss propagates `NOT_FOUND`.
+`metadataState` is `ok` when API-user labels were found, `none` when labels
+exist without an API label, `absent` when no labels are exposed, or `error`
+when metadata could not be read. Lookup continues if metadata is
+unavailable, and API-user classification is omitted when unproven. Text
+records honor the existing client `labels` setting through the shared row-label
+pass; optional `names` reports incomplete label coverage. Numeric gets keep
+their ordinary record shape.
 
 ### 7.3 `invoke(client, operation, args?, opts?)` — the write governor
 
@@ -989,7 +1060,8 @@ the mode pinned (§7.4). The governor rules (pinned):
   `queryBounded`** (server-side pagination): ONE invoke call returns a
   bounded, complete-enough result — the vendor cursor walk happens inside
   the SDK; the caller passes `limit` as the TOTAL cap (default 500, max
-  2500) and never owns a stream. `queryAll` keeps its raw behavior (the
+  2500), or an independent `walk.maxRows` export cap (section 4), and never
+  owns a stream. `queryAll` keeps its raw behavior (the
   unbounded walk; the catalog text steers the caller away for normal work);
 - a query's `includeFields` NAMES and its `filter` condition FIELD NAMES are
   validated **pre-request** (issues #119b + #125): the authority is the
@@ -1059,25 +1131,9 @@ be cross-mode-refused.
   Pinned by the full-surface suite (`test/operations/invoke/modes.test.ts`:
   all 1281 ops × 3 modes, zero wire).
 
-**Harness approval policy (recommended).** Require approval on every tool
-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 **635 tools** (the 622 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
-mutating requests — pinned by the test inventory, §6 of the split design).
-Refined class for the highest-risk ops: the **57 tools with
-`destructiveHint: true`** (56 dedicated delete tools + `autotask_delete`)
-additionally require `confirm === <operation key>` even inside
-`autotask_delete`, and the 3 approval-gated writes
-(`configuration_items.moveConfigurationItem`, `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 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.
+<!-- BEGIN GENERATED:approval-policy -->
+**Harness approval policy (recommended).** Require approval on every tool 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 **636 tools** (the 623 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 mutating requests). Refined class for the highest-risk ops: the **57 tools with `destructiveHint: true`** (56 dedicated delete tools + `autotask_delete`) additionally require `confirm === <operation key>` even inside `autotask_delete`. The approval-gated writes (`configuration_items.moveConfigurationItem`, `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 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.
+<!-- END GENERATED:approval-policy -->
 
 ### 7.5 `recovery(client, input, opts?)` — the one-call recovery/cleanup op (issue #9)
 
@@ -1282,10 +1338,12 @@ wire):
   vendor casing via `operations.fieldCatalog`). An empty array / absent = the
   unfiltered call (the vendor-accepted no-filter shape rides the wire as
   `filter: []`; that is also the blind-predicate's stamp case).
-- **`groupBy` / `sum`** = exact vendor field names (validated against the
+- **`groupBy` / `sum`** = vendor field names, accepting the single own-field
+  prefix aliases of section 5 (normalized before validation and folding;
+  result keys are unprefixed). Names are validated against the
   resource's vendored field set pre-request — a hallucinated field is a shape
   error, not a silent fold-miss; the complete problem list in one typed error,
-  zero wire). Non-numeric/absent `sum` values contribute 0 (documented).
+  zero wire. Non-numeric/absent `sum` values contribute 0 (documented).
 - **`top`** (default 25, clamped 1..100) keeps the top-N groups (descending
   count; the deterministic group-key order breaks ties). **`limit`** (default
   2500 = the house `BOUNDED_QUERY_MAX_LIMIT`, clamped down to it) is the
@@ -1709,7 +1767,7 @@ const lob = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-0
 ## 8. Resource surface
 
 <!-- BEGIN GENERATED:api-per-entity -->
-Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page guarded), `queryBounded` (server-side pagination — one call walks the cursor until `limit` TOTAL records, default 500 / max 2500, with a `hasMore` flag; the MCP `query` surface, routed by `invoke`), `queryAll` (collect → `T[]` — the unbounded raw walk), `count`, `get` (id → record; `item: null` → `NotFoundError`), `create` / `update` / `delete` (where the vendor defines them — mutations take a `MutationOpts` bag: `{ dryRun, lastModifiedDate?, maxRetries? }` (issue #105: `maxRetries` overrides the configured retry budget for every request the mutation issues; `0` = exactly one send per request)), plus the helper floor where the plan declares it: `resolve` (all 121), `search` (40 — bounded contains on the resource text field), `getContext` (5 workflow resources), `findBy<Field>` (3), `createIfNotExists` (14). Entity metadata on every resource: `getEntityInfo`, `getFieldInfo`, `getUdfInfo` (UDF-capable 16). Parent-scoped children take `(parentId, id)` on the CRUD methods and require `parentId` on `createIfNotExists` (the scoped create POSTs the scoped collection; the dedup query stays global); `query`/`count`/`resolve`/`search` stay global (narrow with a `parentField` filter). Scoped `update` PATCHes the collection (the vendor keys the record by the id in the body).
+Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page guarded), `queryBounded` (server-side pagination — one call walks the cursor until the total cap: `limit` (default 500 / max 2500), or independent `walk.maxRows` for exports (pages stay `min(500, limit)`); `hasMore` reports incomplete walks, and explicit walks also carry `truncated`; the MCP `query` surface, routed by `invoke`), `queryAll` (collect → `T[]` — the unbounded raw walk), `count`, `get` (id → record; `item: null` → `NotFoundError`), `create` / `update` / `delete` (where the vendor defines them — mutations take a `MutationOpts` bag: `{ dryRun, lastModifiedDate?, maxRetries? }` (issue #105: `maxRetries` overrides the configured retry budget for every request the mutation issues; `0` = exactly one send per request)), plus the helper floor where the plan declares it: `resolve` (all 121), `search` (40 — bounded contains on the resource text field), `getContext` (5 workflow resources), `findBy<Field>` (3), `createIfNotExists` (14). Entity metadata on every resource: `getEntityInfo`, `getFieldInfo`, `getUdfInfo` (UDF-capable 16). Parent-scoped children take `(parentId, id)` on the CRUD methods and require `parentId` on `createIfNotExists` (the scoped create POSTs the scoped collection; the dedup query stays global); `query`/`count`/`resolve`/`search` stay global (narrow with a `parentField` filter). Scoped `update` PATCHes the collection (the vendor keys the record by the id in the body).
 
 | resource key | apiEntity | kind | tier | parent | standard ops present | special ops | mcpTool |
 |--------------|-----------|------|------|--------|----------------------|-------------|---------|
@@ -2678,7 +2736,8 @@ metadata is (the `autotask_describe` channel, `capabilities.json`,
   `dateWorked` window (`from`/`to` are `YYYY-MM-DD` date strings — the S1c
   guard forbids Date positionals), one bounded read (`limit` 1-500, default
   500 — the hard cap, issue #128: a larger window needs `time_entries.query`
-  with the same `dateWorked` filter, its 2500-row walk cap) returning
+  with the same `dateWorked` filter and a suitable `limit` or explicit
+  `walk.maxRows` cap, section 4) returning
   `{ items, postedCount, unpostedCount, window, nextCursor, unconfirmed, truncated }`; the counts come
   from the billing-item join (any billing item referencing the entry), `opts.posted` narrows client-side after the join
   (true = posted only, false = unposted only, omitted = both); the counts still split every entry read (before the narrowing), so `items.length` can differ from their sum and `ticketID` /
@@ -3381,8 +3440,9 @@ additive, and mirrors the family:
 - **Shape and wire** — each op is exactly ONE bounded query (`MaxRecords`
   1-500, default 500 — the hard cap, issue #128: a call without `limit` takes
   the first 500 rows in id order; a window with more than 500 matching rows
-  needs the bounded query op with the same date-window filter — its 2500-row
-  walk cap; the `itemDate` / `invoiceDateTime` `gte`/`lte` filter rides the
+  needs the bounded query op with the same date-window filter and a suitable
+  `limit` or explicit `walk.maxRows` cap (section 4); the `itemDate` /
+  `invoiceDateTime` `gte`/`lte` filter rides the
   wire), and the result is the plain `items[]` array — no counts
   (the time-entry family shape).
 
@@ -4011,6 +4071,35 @@ truncates first, then wraps) — so the explicit `… [+N chars truncated]`
 marker survives INSIDE the wrapped value and the closing marker is never
 cut off.
 
+**`sanitiseResult(client, result, operation)`** exposes that field projection
+as a zero-wire operations helper. Pass the registry key of the read that
+produced the result, for example `tickets.query`; an unknown key is a typed
+`CONFIG_ERROR`. It walks plain objects and arrays, wrapping strings in the
+operation's `metadata.untrustedFields`, including strings in arrays under
+those fields. `userDefinedFields[].value` strings are fenced even when the
+operation has no field stamp. Deeply nested containers are capped at 64
+levels with `[DEPTH]`.
+Inputs are never mutated, wrapping is idempotent, and non-string values
+and `[REDACTED]` pass through. SDK read primitives still return raw values.
+
+This helper supplies field/UDF fencing. The host retains text cleaning,
+free-text caps and trusted formatting exemptions; apply those policies in
+the host before projection where needed. The bounded-query `noteChars`
+option remains a separate SDK cap applied before wrapping.
+
+For hosts that need to clean or cap text before wrapping, the
+`node-autotask/untrusted` subpath exports
+`deepMarkUntrusted(value, fields, projector?)` and the callback type
+`UntrustedStringProjector = (text: string, target: object, key: string | number) => string`.
+The optional callback runs only for marked string values, including UDF
+values and strings in named arrays. `target` is the copied output
+container; `key` is its property name or array index, assigned after the
+callback returns. A host can record provenance in a `WeakMap` keyed by
+`target` and return the raw text, then clean, cap and wrap those marked
+values later. Containers exposed to the callback remain copies even if
+the callback returns unchanged text. Unmarked strings and non-string
+values do not invoke it; omitting the callback keeps the default wrapping.
+
 ## 13. Doctor preflight (issue #2)
 
 `runDoctor(client)` (section 1.10) runs the bounded, sequential preflight

package/examples/mcp/schemas.ts

@@ -160,6 +160,8 @@ export function hitsOutput(): z.ZodType {
 /** `resolveAny`: one outcome per requested resource; misses do not throw. */
 export function resolveAnyOutput(): z.ZodType {
   return z.object({
+    matched: z.enum(['exact', 'contains']),
+    contains: hitsOutput().optional(),
     identifier: z.union([z.string(), z.number()]),
     results: z.array(
       crossDataField('Per-resource outcome: value (compact or null), resolutionCost, scanned, candidates/error on a miss.'),

package/examples/mcp/tools-read.ts

@@ -84,7 +84,7 @@ export function registerReadTools({ server, client, dry, untrustedWrap }: ToolCo
   // R3 — find a record it cannot name.
   registerCoreRead(
     coreSpec('autotask_resolve_any')!,
-    z.object({ identifier: IDENTIFIER, resources: RESOURCES }),
+    z.object({ identifier: IDENTIFIER, resources: RESOURCES, match: z.enum(['exact', 'auto']).optional(), limit: z.number().int().min(1).max(500).optional() }),
     resolveAnyOutput,
     (v) => `${(v as { matches: string[] }).matches.length} resource(s) matched the identifier.`,
   );
@@ -163,6 +163,7 @@ export function projectUntrustedResult(opId: string, value: unknown, fields: rea
     case 'operations.resolveAny':
       return {
         ...v,
+        ...(v.contains === undefined ? {} : { contains: projectUntrustedResult('operations.searchAcrossResources', v.contains, fields) }),
         results: (Array.isArray(v.results) ? v.results : []).map((row) =>
           row !== null && typeof row === 'object' && !Array.isArray(row) && 'value' in row
             ? { ...(row as Record<string, unknown>), value: deepMarkUntrusted((row as Record<string, unknown>).value, fields) }
@@ -212,7 +213,7 @@ export async function coreReadCall(client: AutotaskClient, opId: string, args: R
     case 'threshold_information.get':
       return { model: await client.thresholdInformation.get() };
     case 'operations.resolveAny':
-      return resolveAny(client, args.identifier as number | string, { resources: args.resources as string[] | undefined });
+      return resolveAny(client, args.identifier as number | string, { resources: args.resources as string[] | undefined, match: args.match as 'exact' | 'auto' | undefined, limit: args.limit as number | undefined });
     case 'operations.searchAcrossResources':
       return searchAcrossResources(client, args.query as string, {
         resources: args.resources as string[] | undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.43.0",
+  "version": "0.44.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,
@@ -161,18 +161,19 @@
   },
   "homepage": "https://github.com/msoukhomlinov/node-autotask#readme",
   "devDependencies": {
-    "@eslint/js": "^9.17.0",
+    "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/server": "^2.2.0",
-    "@types/node": "^22.10.0",
-    "@vitest/coverage-v8": "^4.1.12",
-    "eslint": "^9.17.0",
-    "globals": "^15.14.0",
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0",
     "rimraf": "^6.0.1",
-    "tsup": "^8.3.0",
+    "tsup": "^9.0.0",
     "tsx": "^4.23.15",
-    "typescript": "^5.7.0",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.18.0",
-    "vitest": "^4.1.12",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
     "zod": "^4.4.3"
   },
   "overrides": {