node-autotask 0.30.0 → 0.32.0

package/docs/API.md

@@ -300,7 +300,7 @@ drift payloads (the `operations.recovery` `candidateIds` refusal, the #13
 shape-drift marker info). A non-pinned surface gets no `details` at all
 (no speculation). On the MCP tools' served error payload, `details` is
 passed through verbatim (live-verified 2026-10-04: the W-D3 pointer note
-rides a real `time_entries.getPosted` vendor 500 on the wire) and the
+rides a real `time_entries.getPosted` vendor 500 on the wire; that 500 is gone since 0.32.0, the pointer-note mechanism is unchanged) and the
 deep-redacted `vendorError` body rides under a fixed key (issue #33: the
 vendor's own field-level failure text — what separates a deterministic
 zone wall from a transient outage) — a tool caller sees the same typed
@@ -2162,8 +2162,8 @@ so the answer to "why is this empty?" is data, not speculation:
   field" — 2026-10-06; creates succeeded 2026-10-21, pair not recorded); `authenticate.get` W2:
   designator-only;
   `time_entries.getPosted` / `time_entries.getUnposted` W-D3: this zone's
-  TimeEntry entity exposes no posted-state filter field — the working read
-  is `time_entries.postedWithin`, §11.13 — NO `emptyReason` on any pointer
+  TimeEntry entity has no `postedDate` — the ops derive posted state from the
+  `billing_items.timeEntryID` join instead (§11.13) — NO `emptyReason` on any pointer
   row, by design: a false reason would be worse than none).
 - **the closed kind set** — `EmptyReasonKind`
   (`'not-found' | 'blind-surface' | 'tenant-empty-for-user' |
@@ -2305,30 +2305,50 @@ 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.13 The posted/unposted wall (W-D3) + `postedWithin`, and drifted-create marker recovery (issues #10/#13)
-
-- **W-D3 (live, ww29, 2026-10-04, re-verified)** — this zone's TimeEntry
-  entity exposes **no posted-state filter field**: the vendor 500s
-  `postingStatus` (the G4-era wire), `postedDate` (the spec's field) and
-  `status` alike — a live field-existence oracle (only `dateWorked` /
-  `resourceID` / `ticketID` / `taskID` resolve as filter fields). Zones
-  honouring the published spec answer `getPosted` / `getUnposted`
-  (`postedDate` exist/notExist) normally; on such zones the 500 is the
-  TYPED known wall — the pinned `pointerNote` (§11.10) rides the error on
-  both the typed client and the served MCP payload, naming the working read.
-- **`time_entries.postedWithin(from, to, opts?)`** — the working posted-state
-  window read: an inclusive UTC `dateWorked` window (`from`/`to` are
-  `YYYY-MM-DD` date strings — the S1c guard forbids Date positionals), ONE
-  bounded query (`limit` 1-500, default 500 — the hard cap, issue #128: a
-  window with more than 500 matching rows needs `time_entries.query` with the
-  same `dateWorked` filter, its 2500-row walk cap) returning
-  `{ items, postedCount, unpostedCount, window }`; `opts.posted` narrows
-  (true = posted rows only, false = unposted rows only, omitted = both
-  counted in one pass) and `ticketID` / `resourceID` narrow further.
-  Live-verified on ww29 with data (25 unposted rows in-window, 0 posted;
-  re-verified 2026-10-06: 12 unposted rows in the 2026-10-01..06 window —
-  also the live evidence for the visibility class: unfiltered query 0 rows,
-  windowed read has data).
+### 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
+  has **no posted-state field**: time-entry reads carry no `postedDate` /
+  `postedOnTime` key, and `postedDate exist` / `notExist` filters fail with
+  `SERVER_ERROR: Unable to find postedDate in the TimeEntry Entity` (earlier
+  2026-10-04 oracle: `postingStatus` and `status` are rejected too; only
+  `dateWorked` / `resourceID` / `ticketID` / `taskID` resolve as filter
+  fields). `billingApprovalDateTime` exists on the entity but is not
+  populated on this tenant, so it cannot gate posted state. Earlier text claiming `postedWithin` was "live-verified" with "25
+  unposted rows, 0 posted" came from the defect itself: `postedDate` was never
+  present, so every row counted as unposted.
+- **Posted state is derived from `billing_items.timeEntryID`.** An entry is
+  posted when a billing item references it, for **every** entry read;
+  approval is not consulted. Live ww29 (week 2026-03-02..08): 1321 entries,
+  none with `billingApprovalDateTime`, yet 817 referenced by billing items —
+  so an approval-gated join would call everything unposted. No `postedDate`
+  condition is ever sent. The join is one `BillingItems` query per 250 ids;
+  the entry read is capped at 500, so a call costs at most 1 read + 2 joins
+  and a window with more than 500 entries returns the first 500 with
+  `hasMore` / `truncated` true. A 429 or vendor fault propagates as a typed
+  error. The API user therefore needs BillingItems read permission; a permission fault propagates as a typed error.
+- **`time_entries.getPosted(opts?)` / `getUnposted(opts?)`** — `opts` is
+  `{ limit?, ticketID?, dateFrom?, dateTo? }` (`dateFrom`/`dateTo`:
+  inclusive `dateWorked` days, `YYYY-MM-DD`, never tz-shifted). They return
+  `{ items, hasMore, window, approvedCount, unapprovedCount }` (a breaking
+  change from the bare `TimeEntry[]`, 0.32.0): `getPosted` items are entries
+  a billing item references; `getUnposted` items are entries none references.
+  `approvedCount` / `unapprovedCount` are informational (items with / without
+  `billingApprovalDateTime`) and are **not** posted state. `window` echoes the
+  bounds (`null` for a bound not given); `hasMore` true means the result is
+  partial (entry read capped, or a join page truncated — unconfirmed entries
+  are withheld, never called unposted). `dateFrom`/`dateTo` are optional, but a call without dates reads the tenant's first 500 time entries (effectively the oldest): a near-empty, misleading slice with `hasMore` true — pass a window.
+- **`time_entries.postedWithin(from, to, opts?)`** — an inclusive UTC
+  `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
+  `{ items, postedCount, unpostedCount, window, 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` /
+  `resourceID` narrow the read. Live evidence for the visibility class
+  (unfiltered query 0 rows, windowed read has data) from 2026-10-06 still
+  stands; the posted/unposted split from that period does not.
 - **`truncated` + the `dateWorkedWindow` alias + `tz` (issue #66)** — the
   result is now `{ items, postedCount, unpostedCount, window, truncated }`:
   `truncated` is true when the bounded read came back with a live
@@ -3029,13 +3049,17 @@ additive, and mirrors the family:
     fields, not the invoice date).
 - **The zone contract (shared)** — `opts.tz` takes an explicit IANA zone
   (e.g. `'Australia/Sydney'`); OMITTED `tz` = UTC, the current behaviour
-  bit-for-bit (the regression pin). With a zone, the window's calendar
-  day/period is computed in that zone's LOCAL calendar and converted to UTC
-  for the wire (vendor filter values stay second-precision UTC ISO) — for
-  `billing_items` and `invoices`. The `time_entries` family is DATE-ONLY
-  (`dateWorked` is stored at 00:00 UTC): the zone picks the calendar DATES and
-  the wire bounds are whole UTC days of them; explicit `from`/`to` days are never
-  shifted (0.24.0; a zone-converted instant window picked the wrong day behind UTC). DST is
+  bit-for-bit (the regression pin). All three families are DATE-ONLY
+  (`dateWorked`, `itemDate`, `invoiceDateTime` are stored at T00:00:00Z): the
+  zone picks which calendar DATES a relative window means (what today / last
+  full month is in that zone) and the wire bounds are whole UTC days of them
+  (second-precision UTC ISO); explicit `from`/`to` days are never shifted and
+  `tz` is only validated. `time_entries` has worked this way since 0.24.0;
+  `billing_items` and `invoices` since 0.32.0 (behaviour change: before, a zone
+  behind UTC, e.g. America/New_York, sent a zone-converted instant window that
+  dropped the first day and added an extra day; zones ahead of UTC returned the
+  right rows by accident). A zone-converted instant window picks the wrong day
+  behind UTC. DST is
   handled by inverting local midnights to UTC instants (a local day that
   gains or loses an hour still pins both boundaries to its TRUE midnights —
   never clock-hour arithmetic); `last24h` is rolling (`now − 24h → now`)
@@ -3290,8 +3314,9 @@ returns the contract's reconciled P&L over a date window:
   (ticket `createDate`) as UTC instants, and bucketing slices the ISO
   string — in a UTC+10/11 tenant a ticket created late local time buckets
   one UTC day (possibly one month) earlier than its local date. The
-  `time_entries.getPosted` / `getUnposted` endpoints are NEVER called (the
-  pinned vendor 500 on AU03); posted/unposted derives from the
+  `time_entries.getPosted` / `getUnposted` ops are NEVER called (the
+  profitability fold already holds the billing items, so the join is
+  in-memory with no extra wire); posted/unposted derives from the
   `billingItems.timeEntryID` join (unposted = no billing item exists yet).
   The structural exclusions (`/Services/`, `/ExpenseReports/`,
   `/BillingCodes/` list reads, getPosted/getUnposted) are pinned by the

package/package.json

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