node-autotask 0.33.0 → 0.34.0

package/dist/resources/index.js

@@ -136,9 +136,9 @@ import {
   VersionInformationResource,
   VersionResource,
   ZoneInformationResource
-} from "../chunk-5DS6F6GF.js";
-import "../chunk-MFDQHFGJ.js";
-import "../chunk-VKE56TTN.js";
+} from "../chunk-6ADFCU3I.js";
+import "../chunk-EZKM4HQ6.js";
+import "../chunk-4MUBUSTL.js";
 export {
   AppointmentsResource,
   AuthenticateResource,

package/docs/API.md

@@ -953,6 +953,31 @@ out entirely. `cache.store` is otherwise a plain advanced seam: a supplied
 `ReadCache` instance is used as-is, and `ttlMs` / `perResourceTtlMs` beside it
 refuse (the instance owns its TTLs).
 
+### Fresh single-record reads (`fresh: true`, issue #250)
+
+A write made ELSEWHERE (another process, the Autotask UI, a client with a
+private cache) does not void this client's read cache, so a read-back can be
+served a snapshot. Every single-record `get` takes a trailing per-call
+`{ fresh: true }` — `client.companies.get(id, { fresh: true })`, parent-scoped
+`client.companyAlerts.get(parentId, id, { fresh: true })` — which skips the
+cache LOOKUP, always issues the wire read and refreshes the entry with the
+response (the default, no option or `fresh: false`, is the unchanged cached
+read). Through the governed path pass `invokeRead(client, 'companies.get',
+[id], { fresh: true })`: `InvokeOptions.fresh` is honoured ONLY on a
+`<resource>.get` read; any other operation, a write, or a non-boolean value
+refuses pre-request (zero wire). It affects the one read only: it never clears
+other entries (unlike `http.readCache.clear()`).
+
+Stale-response safety: the read cache does not coalesce concurrent reads (every
+miss and every `fresh` call issues its own request), so a `fresh` read never
+joins a read that started before a write. A read in flight across a write
+through the same cache (including the pool's shared per-tenant cache, whose
+epoch the write bumps) has its late store discarded, so a pre-write response is
+never re-cached; the in-flight caller itself still receives the response it
+asked for. Not covered: a write on a client whose cache is private (pool
+`sharedReadCache: false`) is invisible to
+the other client's cache — use `fresh` there.
+
 ## 7. Operations surface (`./operations` subpath)
 
 Cross-resource helpers live in `src/operations/` (placement locked —
@@ -1484,7 +1509,14 @@ is closed when its label is complete, completed, closed, cancelled, canceled or
 resolved. When the catalog cannot be read, or carries no recognisable closed
 label, the historical id `5` stands in with `source: 'assumed'` and a `note`
 that says so. Passing `excludeStatusIds` reports those ids instead
-(`source: 'picklist'` — an explicit caller choice). No module outside this
+(`source: 'picklist'` — an explicit caller choice). `allowAssumed: false`
+(default `true`, behaviour unchanged) refuses the fallback: an unreadable
+catalog or one with no closed label throws an `AutotaskError` with code
+`STATUS_SEMANTICS_UNRESOLVED` instead of returning `[5]`; the same option is
+accepted by `tickets.forResource` and `companies.fullProfile`, and
+`companies.fullProfile` also takes `excludeStatusIds` (an operator pin reaches
+its `openTickets` part, with no catalog read). In `fullProfile` the throw comes
+at the `openTickets` read, after the company and the four other part reads. No module outside this
 resolver holds a status literal: the move engine's closed-target refusal,
 `companies.fullProfile`'s `openTickets` part and `tickets.forResource`'s
 `openOnly` all call it and carry the disclosure (`closedStatusIds` /
@@ -1499,16 +1531,37 @@ default `both`; the seam is `Tickets.assignedResourceID` for primary and the
 both `id in [...]`-chunked when the link set is large) unioned client-side —
 deliberately not the cross-field grouped `or`, whose live semantics are
 unverified. Result: `{ resourceID, scope, openOnly, tickets, primaryIds,
-secondaryIds, bothIds, counts, capped, unresolvedIds, closedStatus }`, newest
-first by `id` desc, each ticket projected to `id`, `ticketNumber`, `title`,
+secondaryIds, bothIds, counts, capped, unresolvedIds, closedStatus }`, ascending
+by `id`, each ticket projected to `id`, `ticketNumber`, `title`,
 `status`, `assignedResourceID`, `companyID`. `openOnly: true` applies the
 resolved open filter server-side (`status notIn` the closed ids, or a single
 `not-eq` leaf) and re-applies it client-side so a server that ignores the leaf
 cannot widen the answer; `closedStatus` carries the disclosure above.
 `limit` (1-500, default 100) caps the returned tickets — `capped: true` means
-the cap bit, and the link read is capped at 500 rows (`capped` also reflects
-that). `unresolvedIds` lists ids the ticket read did not return (deleted or
-invisible). `excludeStatusIds` overrides the closed set for this call.
+rows were actually left out (the primary read asks for `limit + 1` rows; exactly
+`limit` rows is not capped), and the link read is one 500-row page (`capped` is
+true when the vendor reports a further page; `countOnly` below pages further). `unresolvedIds` lists ids the
+ticket read did not return (deleted or invisible); under `openOnly`, tickets the
+open filter dropped because they are closed are NOT listed (one extra unfiltered
+id read per chunk tells them apart). `excludeStatusIds` overrides the closed set for this
+call.
+
+`countOnly: true` (issue #248) returns counts only, no ticket rows:
+`{ resourceID, scope, primary, secondary, both, open, capped, closedStatus }`
+(typed overloads: `countOnly: true` narrows the return type to
+`TicketsForResourceCountResult`). Every figure counts OPEN tickets (`openOnly`
+and `limit` do not apply). `primary` is the `tickets.count` path with the filter
+`assignedResourceID eq R` and the open leaf, so it equals that call;
+`secondary` is the de-duplicated count of open secondary ticket ids (the link
+table has no status, so the open filter is an ids-only `id in` read per 100
+link ids); `both` is the overlap and `open` the union
+(`primary + secondary - both`). The link read follows the vendor's next-page
+links (ids only, 500 per page) up to 20 pages, so the count is exact below
+10,000 links; `capped: true` means the cap was hit with pages remaining, so
+`secondary`, `both` and `open` may undercount; it is never a silent undercount.
+The secondary read re-applies the open filter client-side, and `limit` is not
+validated (it does not apply). With `scope` `primary`/`secondary` only that side is
+read and `both` is 0.
 
 ## 8. Resource surface (135 resources)
 
@@ -2238,38 +2291,84 @@ budget or guessing:
 
 ### 11.12 Zone-fact create guidance (issue #12)
 
-**`operations.createGuidance`** (`{ resources? }`) serves the plan's zone
-facts per child resource — ZERO vendor calls: the `createOp` key, the
-parent-scoping, the live-proven prefix, the `unproven` flag, and the
-blocker: `{ kind, message, vendorEvidence? }`. The backing plan table is the
-94-resource `zoneFacts.resources`; the 92 create-guidance rows (the 2
-remaining entries — `billing_codes` / `resources`, the blind no-create
-tables — carry zone quirks only) are drift-guarded by clause 15. The stage-11
-live write campaign's decoded knowledge: 92 create entities with the EXACT required-field sets and
-verbatim vendor error evidence (the 500 field-validation ladders, §11.6),
-the blind FK walls (`referenceField` naming the reference table that is
-blind for this API user — no valid id can be read back), and the 9th kind
-`unknown` for the wall-adjacent rows (e.g. `ticket_checklist_libraries`
-W-A7 drift — the 200 that is not the specced envelope). An agent that reads
-the row before its create attempt converts a multi-iteration vendor ladder
-into one predicted-failure-free attempt.
+**`operations.createGuidance`** (`{ resources?, kind? }`) serves the plan's zone
+facts per create op — ZERO vendor calls: the `createOp` key, the
+parent-scoping, the live-proven prefix, the `unproven` flag, the blocker
+`{ kind, message, remedy, referenceField?, unsatisfiableViaApi?, requires? }`,
+the exact vendor text in `vendorEvidence`, and the spec-derived
+`deleteBoundary`.
+
+**Row counts.** The backing plan table `zoneFacts.resources` has 99 entries;
+97 of them carry a `createGuidance` row — exactly one per plan create op, set
+equality guarded by clause 15 — and the other 2 (`billing_codes`,
+`resources`, the blind no-create tables) carry zone quirks only. Earlier
+revisions of this section quoted 92 or 94; the counts are 99 entries / 97 rows.
+`counts.total` is 97 and `counts.byKind` sums to it.
+
+**Model-facing by construction (issue #246).** `blocker.message` and
+`blocker.remedy` are written for the consumer of the guidance: they carry no
+campaign markers, branch names, W-codes, dates, tenant record ids or
+maintainer instructions. Anything of that kind that is worth keeping lives in
+`vendorEvidence` (entries prefixed `maintainer provenance`), next to the
+verbatim vendor text. Clause 15 fails the build when a message or remedy
+matches a provenance pattern. A consumer that renders a blocker can therefore
+serve `message`/`remedy` as they are.
+
+**Blocker kinds.** The closed set is `ok`, `blind-reference`, `blind-parent`,
+`picklist-unexposed`, `undocumented-ladder`, `resource-role-pair`,
+`delete-absent`, `non-mutable` and `unknown`.
+
+- `delete-absent` is **not** a create blocker. A resource with no vendor
+  DELETE created fine; that is the delete boundary (`deleteBoundary.available:
+  false`, plus the `metadata.deleteBoundary` stamp on the create op). The
+  eight rows that carried the kind (`tickets`, `companies`, `phases`,
+  `company_notes`, ...) are now kind `ok` with the boundary on
+  `deleteBoundary`; the kind is reserved (still accepted by the `kind` filter,
+  0 rows) and clause 15 fails a row that carries it.
+- `non-mutable` **is** a create blocker: the vendor refuses the create write
+  itself for the entity. No row carries it today.
+- `blind-reference` rows always name `referenceField` (the field whose
+  referenced table is blind for this API user), including the contract
+  billing-rule / exclusion / service / bundle rows.
+- `blocker.unsatisfiableViaApi: true` is the structured flag for creates the
+  API cannot satisfy for any input: exactly the `picklist-unexposed` rows (the
+  attachment `Type` picklist) and the `undocumented-ladder` row
+  (`opportunities`). Clause 15 holds the flag and the kind in step.
+
+**Where to read the company (issue #246).** Some resources have no `companyID`
+of their own. `row.parentCompany?: { via, resource, field }` says which parent
+record carries it: `tasks` serves `{ via: 'projectID', resource: 'projects',
+field: 'companyID' }` (read the project, then its `companyID`). The hint is
+derived from the vendored spec (a resource with no `companyID` whose scoping
+parent field points at a parent that has one) and clause 15 requires the plan
+row to equal that derivation, so it cannot drift. A resource with its own
+`companyID` carries no hint.
 
 **Which required set wins (issue #219 N4).** Three sources answer "what does
 this create really require", at different coverage: the live-proven prefix
-(92 rows — the fields a live create actually demanded, in vendor-demand
-order), the hand-authored zone set `createRequiredSet` (6 resources), and the
-vendor field catalog's `isRequired` (the spec opinion — wrong for 68 of the
-75 resources that carry a proven prefix). The precedence is FIXED:
-**live-proven > zone > spec**, and the source is named on the result.
-`effectiveRequiredFields(record, zoneFacts)` in `node-autotask/operations` is
-the only place in the SDK that compares the three; every
-`operations.createGuidance` row carries its result as
-`requiredFields: { fields, from: 'live-proven' | 'zone' | 'spec' }`
-(`contacts.create` → the four live-proven fields, not the empty spec list).
-A value-conditioned prefix (e.g. `contracts.create`'s type-1
-`estimatedRevenue`/`estimatedHours`/`estimatedCost`) is returned whole with
-`from: 'live-proven'` — the condition is typed on the row (see the next
-paragraph), so read it before treating the list as unconditional.
+(the fields a live create actually demanded, in vendor-demand order), the
+hand-authored zone set `createRequiredSet`, and the vendor field catalog's
+`isRequired` (the spec opinion, wrong for most resources that carry a proven
+prefix). The precedence is FIXED: **live-proven > zone > spec**, and the source
+is named on the result. `effectiveRequiredFields(record, zoneFacts)` in
+`node-autotask/operations` is the only place in the SDK that compares the
+three; every `operations.createGuidance` row carries its result as
+`requiredFields: { fields, from, unproven, conditional? }`
+(`contacts.create` returns the four live-proven fields, not the empty spec list).
+
+- `fields` is the **unconditional** set. A field the row gates on a picklist
+  value (`requiresByValue`) is removed from it: `contracts.create` returns
+  `status, contractType, contractName, startDate, endDate,
+  timeReportingRequiresStartAndStopTimes, companyID`, and
+  `estimatedRevenue` / `estimatedHours` / `estimatedCost` appear only in
+  `conditional` (contractType 1 needs all three, 3/4/6/8 need
+  `estimatedRevenue`). **Changed in 0.34.0:** the type-1 triple was previously
+  returned inside `fields`.
+- `conditional?` is the row's `requiresByValue`, copied as typed gates; it is
+  absent when the row declares none.
+- `unproven` is `true` when no live create is known to succeed with the set:
+  the plan row is unproven (the create still failed after the prefix), or the
+  set is only the vendor spec's opinion. It is additive on the result.
 
 **Structured create requirements (issue #219 N3).** The blocker channel is a
 CLASS of wall, not a statement of what the vendor wants; and the campaign
@@ -2305,6 +2404,32 @@ clause that stops this fact from being lost a second time. The create op's
 registry record carries the same typed block as `metadata.createRequirements`
 (the `autotask_describe` channel).
 
+### 11.12a Per-operation caveats (issue #249)
+
+An operation record may carry `metadata.caveats`, an optional list of
+structured facts about the operation itself, served wherever operation
+metadata is (the `autotask_describe` channel, `capabilities.json`,
+`node-autotask/capabilities`). One row shape over a CLOSED kind set:
+
+```ts
+{ kind: 'not-persisted'; fields?: string[]; note: string; remedyOp?: string }
+```
+
+- `not-persisted`: the op accepts the listed `fields` but the vendor does not
+  store them. `fields` is required for this kind; `remedyOp` names the plan
+  operation that does what this one cannot.
+- First rows: `time_entries.update` and `ticket_charges.update` declare
+  `{ kind: 'not-persisted', fields: ['ticketID'], remedyOp:
+  '<resource>.moveToTicket' }`.
+- The kind set is closed at build time: `scripts/generate-capabilities.mjs`
+  throws on an unknown kind or a malformed row, and gate clause 22 also checks
+  that every named field exists on the resource model and every `remedyOp` is
+  a plan operation.
+- Purely additive: `metadata.usage`, `metadata.pointerNote` and every other
+  served field are unchanged, and a record without caveats has no `caveats`
+  key. Unlike `pointerNote`, caveats ride the describe channel only (they are
+  not attached to error details).
+
 ### 11.13 Posted state from billing items (W-D3), `getPosted` / `getUnposted` / `postedWithin`, and drifted-create marker recovery (issues #10/#13/#237)
 
 - **W-D3 (live, ww29, re-verified 2026-10-27)** — this zone's TimeEntry entity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.33.0",
+  "version": "0.34.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,