node-autotask 0.39.3 → 0.40.0

package/docs/N8N-ADAPTER.md

@@ -2,7 +2,7 @@
 
 **Status:** v0.1.0 (the 121-entity MVP set). Generated tables are marked
 `GENERATED` and regenerated by `npm run docs:render` — two JSONs in
-(`.run/spec/n8n-mapping.json` × `capabilities.json`, plus the plan × the
+(`scripts/n8n-mapping.json` × `capabilities.json`, plus the plan × the
 vendored `api-docs.json` for the gap table), markdown table out. Do not
 hand-type the generated regions.
 
@@ -30,7 +30,7 @@ Autotask semantic is an SDK call.
 ## 2. Operation mapping — node resource → SDK operations
 
 <!-- BEGIN GENERATED:n8n-op-mapping -->
-Two sources in, markdown table out: the node repo (the ops column is re-derived from the `name: 'operation'` property options of each `resources/<dir>` dir — style A const or inline options; values of any other dropdown property, e.g. the timeEntries dateRange presets, are filter options and never ops) × `capabilities.json` (SDK operations per resource key, generated registry). `.run/spec/n8n-mapping.json` supplies the row set (node dir → apiEntity), the parent-scoped flag and the curated special ops. Standard node ops map to the SDK primitive of the same name (`getMany` → `queryAll`, the unbounded raw walk — the bounded MCP read is the `query` op, routed by `invoke` to `queryBounded`). A node special op maps to the SDK operation of the same name on the same resource when the registry has it; `—` = the node op has no SDK operation of its own (handled in the adjacent sections).
+Two sources in, markdown table out: the node repo (the ops column is re-derived from the `name: 'operation'` property options of each `resources/<dir>` dir — style A const or inline options; values of any other dropdown property, e.g. the timeEntries dateRange presets, are filter options and never ops) × `capabilities.json` (SDK operations per resource key, generated registry). `scripts/n8n-mapping.json` supplies the row set (node dir → apiEntity), the parent-scoped flag and the curated special ops. Standard node ops map to the SDK primitive of the same name (`getMany` → `queryAll`, the unbounded raw walk — the bounded MCP read is the `query` op, routed by `invoke` to `queryBounded`). A node special op maps to the SDK operation of the same name on the same resource when the registry has it; `—` = the node op has no SDK operation of its own (handled in the adjacent sections).
 
 | node dir | apiEntity | parent-scoped | node ops (opsImplemented) | node special ops | SDK methods (from the registry) |
 |----------|-----------|---------------|---------------------------|------------------|----------------------------------|
@@ -41,7 +41,7 @@ Two sources in, markdown table out: the node repo (the ops column is re-derived
 | `checklistLibraries` | ChecklistLibrary | no | create, update, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
 | `checklistLibraryChecklistItems` | ChecklistLibraryChecklistItem | yes | create, update, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
 | `classificationIcons` | ClassificationIcon | no | get, getMany, count | — | count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search |
-| `companies` | Company | no | create, update, get, getMany, count, searchByIdentity, searchByDomain | searchByDomain → `companies.searchByDomain`; searchByIdentity → `companies.searchByIdentity` | count, create, fullProfile, get, getContext, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, searchByDomain, searchByIdentity, unbilledWork, update, upsertByName |
+| `companies` | Company | no | create, update, get, getMany, count, searchByIdentity, searchByDomain | searchByDomain → `companies.searchByDomain`; searchByIdentity → `companies.searchByIdentity` | count, create, fullProfile, get, getContext, getEntityInfo, getFieldInfo, getUdfInfo, prepareCrmWrite, query, resolve, search, searchByDomain, searchByIdentity, unbilledWork, update, upsertByName |
 | `companyAlerts` | CompanyAlert | yes | create, update, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
 | `companyLocations` | CompanyLocation | yes | create, get, getMany, update, delete, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
 | `companyNotes` | CompanyNote | yes | create, update, get, getMany, count | — | count, create, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
@@ -82,7 +82,7 @@ Two sources in, markdown table out: the node repo (the ops column is re-derived
 | `contractServiceUnits` | ContractServiceUnit | yes | get, getMany, count | — | count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
 | `contractServices` | ContractService | yes | create, update, get, getMany, count, createIfNotExists | createIfNotExists → `contract_services.createIfNotExists` | count, create, createIfNotExists, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
 | `contractTicketPurchases` | ContractTicketPurchases | yes | create, update, get, getMany, count | — | count, create, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
-| `contracts` | Contract | no | create, update, get, getMany, count, createIfNotExists | createIfNotExists → `contracts.createIfNotExists` | count, create, createIfNotExists, get, getEntityInfo, getFieldInfo, getUdfInfo, profitability, query, resolve, search, update |
+| `contracts` | Contract | no | create, update, get, getMany, count, createIfNotExists | createIfNotExists → `contracts.createIfNotExists` | count, create, createIfNotExists, get, getEntityInfo, getFieldInfo, getUdfInfo, lineOfBusiness, profitability, query, resolve, search, update |
 | `countries` | Country | no | get, getMany, update, count | — | count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
 | `departments` | Department | no | count, create, get, getMany, update | — | count, create, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
 | `domainRegistrar` | DomainRegistrar | no | create, update, get, getMany, count | — | count, create, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
@@ -141,7 +141,7 @@ Two sources in, markdown table out: the node repo (the ops column is re-derived
 | `ticketCategories` | TicketCategory | no | get, getMany, update, count | — | count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
 | `ticketCategoryFieldDefaults` | TicketCategoryFieldDefault | yes | get, getMany, count | — | count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
 | `ticketChangeRequestApprovals` | TicketChangeRequestApproval | yes | create, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
-| `ticketCharges` | TicketCharge | yes | create, createIfNotExists, update, delete, get, getMany, count | createIfNotExists → `ticket_charges.createIfNotExists` | count, create, createIfNotExists, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
+| `ticketCharges` | TicketCharge | yes | create, createIfNotExists, update, delete, get, getMany, count | createIfNotExists → `ticket_charges.createIfNotExists` | count, create, createIfNotExists, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, moveToTicket, query, resolve, search, update |
 | `ticketChecklistItems` | TicketChecklistItem | yes | create, update, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
 | `ticketChecklistLibraries` | TicketChecklistLibrary | yes | create | — | attachToDocument, create, getEntityInfo, getFieldInfo, getUdfInfo, resolve |
 | `ticketHistories` | TicketHistory | no | get, getMany, count | — | count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
@@ -150,8 +150,8 @@ Two sources in, markdown table out: the node repo (the ops column is re-derived
 | `ticketNotes` | TicketNote | yes | create, update, get, getMany, count | — | count, create, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
 | `ticketSecondaryResources` | TicketSecondaryResource | yes | create, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
 | `ticketWebhooks` | TicketWebhook | yes | get, getMany, delete | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
-| `tickets` | Ticket | no | create, get, getMany, slaHealthCheck, summary, timeline, update, count | slaHealthCheck → `tickets.slaHealthCheck`; summary → `tickets.summary`; timeline → `tickets.timeline` | changeStatus, count, create, findByTicketNumber, fullContext, get, getContext, getEntityInfo, getFieldInfo, getUdfInfo, openWithNoteAndAssign, query, resolve, search, slaHealthCheck, summary, timeline, update |
-| `timeEntries` | TimeEntry | no | create, update, get, getMany, getPosted, getUnposted, delete, count, createIfNotExists | createIfNotExists → `time_entries.createIfNotExists`; customRange → `time_entries.customRange`; getPosted → `time_entries.getPosted`; getUnposted → `time_entries.getUnposted`; last14 → `time_entries.last14`; last24h → `time_entries.last24h`; last30 → `time_entries.last30`; last7 → `time_entries.last7`; last90 → `time_entries.last90`; lastFullFortnight → `time_entries.lastFullFortnight`; lastFullMonth → `time_entries.lastFullMonth`; lastFullQuarter → `time_entries.lastFullQuarter`; lastFullWeek → `time_entries.lastFullWeek`; today → `time_entries.today`; yesterday → `time_entries.yesterday` | count, create, createForResource, createIfNotExists, customRange, dateWorkedWindow, delete, get, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, postedWithin, query, resolve, today, update, yesterday |
+| `tickets` | Ticket | no | create, get, getMany, slaHealthCheck, summary, timeline, update, count | slaHealthCheck → `tickets.slaHealthCheck`; summary → `tickets.summary`; timeline → `tickets.timeline` | changeStatus, count, create, findByTicketNumber, forResource, fullContext, get, getContext, getEntityInfo, getFieldInfo, getUdfInfo, lineOfBusiness, openWithNoteAndAssign, query, resolve, search, slaHealthCheck, statusSemantics, summary, timeline, update |
+| `timeEntries` | TimeEntry | no | create, update, get, getMany, getPosted, getUnposted, delete, count, createIfNotExists | createIfNotExists → `time_entries.createIfNotExists`; customRange → `time_entries.customRange`; getPosted → `time_entries.getPosted`; getUnposted → `time_entries.getUnposted`; last14 → `time_entries.last14`; last24h → `time_entries.last24h`; last30 → `time_entries.last30`; last7 → `time_entries.last7`; last90 → `time_entries.last90`; lastFullFortnight → `time_entries.lastFullFortnight`; lastFullMonth → `time_entries.lastFullMonth`; lastFullQuarter → `time_entries.lastFullQuarter`; lastFullWeek → `time_entries.lastFullWeek`; today → `time_entries.today`; yesterday → `time_entries.yesterday` | approve, count, create, createForResource, createIfNotExists, customRange, dateWorkedWindow, delete, get, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, moveToTicket, postedWithin, query, recentTickets, resolve, today, update, yesterday |
 | `timeEntryAttachments` | TimeEntryAttachment | yes | create, getMany, count, download, delete | download → `time_entry_attachments.download` | count, create, delete, download, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
 | `timeOffRequests` | TimeOffRequest | no | get, getMany, count, approve, reject | approve → `time_off_requests.approve`; reject → `time_off_requests.reject` | approve, count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, reject, resolve |
 | `(none — NOT IMPLEMENTED in node)` | InventoryProduct (StockedItemsAdd/Remove/Transfer pseudo-entities) | yes |  | stockedItemsAdd → `inventory_products.stockedItemsAdd`; stockedItemsRemove → `inventory_products.stockedItemsRemove`; stockedItemsTransfer → `inventory_products.stockedItemsTransfer` | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, stockedItemsAdd, stockedItemsRemove, stockedItemsTransfer, update |

package/examples/mcp-server-http.ts

@@ -82,7 +82,7 @@ import { pipeline } from 'node:stream/promises';
 import type { ReadableStream as NodeReadableStream } from 'node:stream/web';
 import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
 import type { McpServerFactory } from '@modelcontextprotocol/server';
-import { AutotaskClient, type ZoneName } from 'node-autotask';
+import { AutotaskClient, type AutotaskConfig, type ZoneName } from 'node-autotask';
 import { createClientPool, type ClientPool } from 'node-autotask/pool';
 import { MCP_SERVER_OPTIONS, registerCoreTools, SERVER_INFO, effectForOperation } from './mcp-register.js';
 import { createStderrAuditSink } from './mcp-audit.js';
@@ -142,21 +142,21 @@ const client = GATEWAY || DRY
  * is shared between its requests, never across tenants), the user-visible
  * warning sink, and the shared audit sink.
  */
-const pool: ClientPool | undefined = GATEWAY
-  ? createClientPool({
-      factory: (config) =>
-        new AutotaskClient({
-          // Issue #4: the SAME env overrides apply to every pooled client —
-          // spread first, so the per-request tenant config and the pooled read
-          // cache (explicit) always win over the env (explicit > env > profile).
-          ...withEnvOverrides(),
-          ...config,
-          cache: { ttlMs: GATEWAY_CACHE_TTL_MS },
-          logger: { warn: (m: string) => console.error(m) },
-          onAudit: createStderrAuditSink({ resolveEffect: effectForOperation }),
-        }),
-    })
-  : undefined;
+const pool: ClientPool | undefined = GATEWAY ? createClientPool() : undefined;
+
+/** The pooled client's config: the tenant's credentials over the shared gateway settings. */
+function pooledConfig(creds: Parameters<typeof gatewayConfig>[0]): AutotaskConfig {
+  return {
+    // Issue #4: the SAME env overrides apply to every pooled client — spread
+    // first, so the per-request tenant config and the pooled read cache
+    // (explicit) always win over the env (explicit > env > profile).
+    ...withEnvOverrides(),
+    ...gatewayConfig(creds),
+    cache: { ttlMs: GATEWAY_CACHE_TTL_MS },
+    logger: { warn: (m: string) => console.error(m) },
+    onAudit: createStderrAuditSink({ resolveEffect: effectForOperation }),
+  };
+}
 
 /** The pooled client for one gateway request (null = DRY surface). */
 function gatewayClientFor(request: Request | undefined): { client: AutotaskClient | null; dry: boolean } {
@@ -165,7 +165,7 @@ function gatewayClientFor(request: Request | undefined): { client: AutotaskClien
   // re-parse (the same pure function) only selects the pooled client.
   const parsed = extractGatewayCredentials(request.headers);
   if ('status' in parsed) return { client: null, dry: true };
-  return { client: pool.get(gatewayConfig(parsed)), dry: false };
+  return { client: pool.get(pooledConfig(parsed)), dry: false };
 }
 
 /** One `McpServer` per HTTP request; the tool surface is global (same as stdio). */
@@ -208,7 +208,7 @@ async function fetchHandler(request: Request): Promise<Response> {
         headers: { 'content-type': 'text/plain; charset=utf-8' },
       });
     }
-    const gwClient = pool.get(gatewayConfig(parsed));
+    const gwClient = pool.get(pooledConfig(parsed));
     // Bounded warm-up: the tenant's probe is awaited for AT MOST
     // GATEWAY_WARMUP_BUDGET_MS (fixed), then the request proceeds without
     // it — a cold cache on a large tenant cannot push the call past the

package/package.json

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