node-autotask 0.15.0 → 0.17.0

package/dist/{chunk-CSA6QSV6.js → chunk-HC6YWPIY.js}

@@ -1,6 +1,6 @@
 import {
   CAPABILITIES
-} from "./chunk-JIDR3NPV.js";
+} from "./chunk-6SP6GJJR.js";
 
 // src/auth.ts
 var AUTH_HEADERS = {
@@ -171,6 +171,7 @@ var AutotaskError = class extends Error {
   operation;
   httpStatus;
   vendorError;
+  /** Legacy unlabeled id list (issue #116) — see `AutotaskErrorOptions.resourceIds`; the labeled companion rides on `details.idRefs`. */
   resourceIds;
   suggestedAction;
   correlationId;
@@ -1532,6 +1533,8 @@ var DEFAULT_PAGE_SIZE = 10;
 var MAX_PAGE_SIZE = 500;
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_MAINTENANCE_MAX_WAIT_MS = 36e5;
+var DEFAULT_MAINTENANCE_POLL_MS = 3e4;
 var DEFAULT_MAX_CONCURRENT = 10;
 var DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 var DEFAULT_MAX_SCAN_RECORDS = 500;
@@ -1689,6 +1692,14 @@ function resolveConfig(config) {
   if (!Number.isInteger(maxRetries) || maxRetries < 0) {
     throw new AutotaskConfigError("maxRetries must be a non-negative integer");
   }
+  const maintenanceMaxWaitMs = config.maintenanceMaxWaitMs ?? DEFAULT_MAINTENANCE_MAX_WAIT_MS;
+  if (!Number.isInteger(maintenanceMaxWaitMs) || maintenanceMaxWaitMs < 0) {
+    throw new AutotaskConfigError("maintenanceMaxWaitMs must be a non-negative integer");
+  }
+  const maintenancePollMs = config.maintenancePollMs ?? DEFAULT_MAINTENANCE_POLL_MS;
+  if (!Number.isInteger(maintenancePollMs) || maintenancePollMs <= 0) {
+    throw new AutotaskConfigError("maintenancePollMs must be a positive integer");
+  }
   const maxConcurrent = config.maxConcurrent ?? (agent ? AGENT_PROFILE.maxConcurrent : DEFAULT_MAX_CONCURRENT);
   if (!Number.isInteger(maxConcurrent) || maxConcurrent <= 0) {
     throw new AutotaskConfigError("maxConcurrent must be a positive integer");
@@ -1822,6 +1833,8 @@ function resolveConfig(config) {
     pageSize: pageSizeCapped,
     timeoutMs,
     maxRetries,
+    maintenanceMaxWaitMs,
+    maintenancePollMs,
     maxConcurrent,
     maxResponseBytes,
     logger,
@@ -14755,6 +14768,10 @@ function backoffDelay(attempt) {
   const exp = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
   return Math.floor(exp / 2 + Math.random() * (exp / 2));
 }
+function isMaintenancePage(err) {
+  const snippet = typeof err.details?.bodySnippet === "string" ? err.details.bodySnippet : "";
+  return /maintenance|temporarily unavailable|service unavailable|outage|downtime|down for/i.test(snippet);
+}
 function parseRetryAfter(value) {
   if (value === null || value.length === 0) return void 0;
   const trimmed = value.trim();
@@ -14851,6 +14868,9 @@ var HttpClient = class {
   update;
   auth;
   maxRetries;
+  /** Maintenance-window auto-retry budget + poll (issue #112 follow-up; see config). */
+  maintenanceMaxWaitMs;
+  maintenancePollMs;
   maxResponseBytes;
   perHour;
   /** The resolved profile (issue #4) — the agent profile changes the
@@ -14921,6 +14941,8 @@ var HttpClient = class {
       impersonationResourceId: config.impersonationResourceId
     };
     this.maxRetries = config.maxRetries;
+    this.maintenanceMaxWaitMs = config.maintenanceMaxWaitMs;
+    this.maintenancePollMs = config.maintenancePollMs;
     this.maxResponseBytes = config.maxResponseBytes;
     this.perHour = config.rateLimit?.perHour;
     this.tenantKey = buildTenantKey(config.userName, config.baseUrl);
@@ -15180,11 +15202,21 @@ var HttpClient = class {
     const correlationId = newCorrelationId();
     const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
     const maxRetries = opts.maxRetries ?? this.maxRetries;
+    const maintenanceMaxWaitMs = opts.maintenanceMaxWaitMs ?? this.maintenanceMaxWaitMs;
+    const maintenancePollMs = opts.maintenancePollMs ?? this.maintenancePollMs;
+    let firstMaintenanceAt;
+    let maintenanceWaits = 0;
     const started = Date.now();
-    const deadlineAt = started + timeoutMs;
+    let deadlineAt = started + timeoutMs;
     const callerSignal = opts.signal ?? ambientSignal.getStore();
+    const deadline = new AbortController();
+    let deadlineTimer = setTimeout(() => deadline.abort(), timeoutMs);
+    const armDeadline = (ms) => {
+      clearTimeout(deadlineTimer);
+      deadlineTimer = setTimeout(() => deadline.abort(), Math.max(0, ms));
+    };
     const signal = AbortSignal.any(
-      callerSignal === void 0 ? [AbortSignal.timeout(timeoutMs)] : [AbortSignal.timeout(timeoutMs), callerSignal]
+      callerSignal === void 0 ? [deadline.signal] : [deadline.signal, callerSignal]
     );
     const auditBody = opts.body !== void 0 ? redactAuditBody(opts.body) : void 0;
     const retriable = opts.idempotent ?? IDEMPOTENT_METHODS.includes(method);
@@ -15202,9 +15234,9 @@ var HttpClient = class {
       }
     };
     if (this.cooldownStore !== void 0 && !opts.bypassCooldown) {
-      const deadline = this.cooldownStore.get(this.tenantKey);
-      if (deadline !== void 0) {
-        const remainingMs = deadline - Date.now();
+      const deadline2 = this.cooldownStore.get(this.tenantKey);
+      if (deadline2 !== void 0) {
+        const remainingMs = deadline2 - Date.now();
         if (remainingMs > 0) {
           if (callerSignal?.aborted) throw interrupted();
           const seconds = Math.ceil(remainingMs / 1e3);
@@ -15394,6 +15426,23 @@ var HttpClient = class {
               httpStatus: status,
               suggestedAction: "The zone returned a non-JSON 2xx body; verify baseUrl points at the REST API."
             });
+            if (err2.code === "UNEXPECTED_CONTENT_TYPE" && maintenanceMaxWaitMs > 0 && isMaintenancePage(err2)) {
+              const now = Date.now();
+              firstMaintenanceAt ??= now;
+              const remaining = maintenanceMaxWaitMs - (now - firstMaintenanceAt);
+              if (remaining > 0) {
+                const wait = Math.min(maintenancePollMs, remaining);
+                maintenanceWaits += 1;
+                this.logger.warn?.(
+                  `[autotask] maintenance window on ${method} ${opts.path}; waiting ${Math.round(wait / 1e3)}s (retry ${maintenanceWaits}, up to ${Math.round(maintenanceMaxWaitMs / 6e4)} min)`,
+                  correlationId
+                );
+                deadlineAt = Date.now() + wait + timeoutMs;
+                armDeadline(deadlineAt - Date.now());
+                await pause(wait);
+                continue;
+              }
+            }
             if (err2.code === "UNEXPECTED_CONTENT_TYPE" && retriable5xx && attempt < maxRetries) {
               const retryAfter = parseRetryAfter(res.headers.get("Retry-After"));
               const delay = retryAfter !== void 0 ? retryAfter * 1e3 : backoffDelay(attempt);
@@ -15407,6 +15456,18 @@ var HttpClient = class {
                 continue;
               }
             }
+            if (maintenanceWaits > 0 && err2.code === "UNEXPECTED_CONTENT_TYPE") {
+              err2.details = {
+                ...err2.details ?? {},
+                maintenance: {
+                  waits: maintenanceWaits,
+                  waitedMs: Date.now() - (firstMaintenanceAt ?? Date.now()),
+                  maxWaitMs: maintenanceMaxWaitMs,
+                  exhausted: true
+                }
+              };
+              err2.suggestedAction = `The zone stayed in a maintenance window for ${Math.round(maintenanceMaxWaitMs / 6e4)} min \u2014 the SDK waited and retried ${maintenanceWaits} time(s) and gave up. Re-run after the window (typically under 30 min), or raise maintenanceMaxWaitMs.`;
+            }
             attachEmptyReasonDetails(err2);
             throw err2;
           }
@@ -15534,6 +15595,7 @@ var HttpClient = class {
       }
       throw err;
     } finally {
+      clearTimeout(deadlineTimer);
       if (!(method === "GET" || opts.idempotent === true)) {
         this.readCache?.clear();
         const nameOp = typeof opts.operation === "string" ? opts.operation : void 0;
@@ -15594,7 +15656,7 @@ function unwrapItems(body, operation) {
   }
   return { items: body.items, pageDetails: body.pageDetails };
 }
-function unwrapItem(body, id, operation) {
+function unwrapItem(body, id, operation, entity) {
   if (!isRecord2(body) || !("item" in body)) {
     throw new AutotaskError("Expected the item envelope { item }; got a different shape", {
       code: "INVALID_RESPONSE",
@@ -15610,6 +15672,7 @@ function unwrapItem(body, id, operation) {
       {
         httpStatus: 200,
         resourceIds: id !== void 0 ? [id] : void 0,
+        ...id !== void 0 && entity !== void 0 ? { details: { idRefs: [{ entity, id }] } } : {},
         operation,
         suggestedAction: "Verify the id, or resolve the record by name first."
       }
@@ -16930,6 +16993,19 @@ function decodeFileData(body) {
     { code: "INVALID_RESPONSE", category: "server" }
   );
 }
+var DEPLURAL_EXCEPTIONS = {
+  tag_aliase: "tag_alias"
+};
+function entityNameFromPath(resourcePath) {
+  const segment = resourcePath.slice(resourcePath.lastIndexOf("/") + 1);
+  const snake = segment.replace(/([A-Z])/g, (_m, c, i) => (i > 0 ? `_` : "") + c.toLowerCase()).replace(/_{2,}/g, "_");
+  if (snake.endsWith("ies")) return `${snake.slice(0, -3)}y`;
+  if (snake.endsWith("s")) {
+    const stripped = snake.slice(0, -1);
+    return DEPLURAL_EXCEPTIONS[stripped] ?? stripped;
+  }
+  return snake;
+}
 var BaseResource = class {
   http;
   config;
@@ -16939,6 +17015,10 @@ var BaseResource = class {
   get resourcePath() {
     return this.config.resourcePath;
   }
+  /** The vendor entity this resource's ids identify (issue #116 — the `details.idRefs` label, e.g. `company`). */
+  get entityName() {
+    return entityNameFromPath(this.resourcePath);
+  }
   /** Parent-scoped template (from the config); undefined for top-level resources. */
   get parentScopedPath() {
     return this.config.parentScopedPath;
@@ -17446,7 +17526,7 @@ var BaseResource = class {
   async getGlobal(id, fresh = false) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.cachedGet(`${this.resourcePath}/${numeric}`, `${this.config.key}.get`, fresh, this.config.key);
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /**
    * V2 merge read: a FRESH single-record GET that skips response redaction
@@ -17468,7 +17548,7 @@ var BaseResource = class {
       skipResponseRedaction: true,
       maxRetries: readOpts?.maxRetries
     });
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /**
    * Issue #34 fallback merge read: a FRESH parent-scoped single-record GET
@@ -17487,13 +17567,13 @@ var BaseResource = class {
       skipResponseRedaction: true,
       maxRetries: readOpts?.maxRetries
     });
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /** Parent-scoped `GET .../{parentId}/<Child>/{id}` → `{ item }` unwrapped. */
   async getScopedRaw(parentId, id, fresh = false) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.cachedGet(this.scopedItemPath(parentId, id), `${this.config.key}.get`, fresh, this.config.key);
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /**
    * Attachment single-read: the vendor answers the model DIRECTLY (swagger),
@@ -17503,23 +17583,23 @@ var BaseResource = class {
   async getScopedModel(parentId, id, fresh = false) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.cachedGet(this.scopedItemPath(parentId, id), `${this.config.key}.get`, fresh, this.config.key);
-    return this.unwrapModelLike(res, numeric);
+    return this.unwrapModelLike(res, numeric, this.entityName);
   }
-  unwrapModelLike(body, id) {
+  unwrapModelLike(body, id, entity) {
     if (!isRecord2(body)) {
       throw new AutotaskError(
         `Expected an attachment model (or { item } / { items }) envelope for ID ${id}; got a different shape`,
-        { code: "INVALID_RESPONSE", category: "server", resourceIds: [id] }
+        { code: "INVALID_RESPONSE", category: "server", resourceIds: [id], details: { idRefs: [{ entity, id }] } }
       );
     }
     if (Object.keys(body).length === 0) {
-      throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id] });
+      throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id], details: { idRefs: [{ entity, id }] } });
     }
-    if ("item" in body) return unwrapItem(body, id);
+    if ("item" in body) return unwrapItem(body, id, void 0, entity);
     if (Array.isArray(body.items)) {
       const first = body.items[0];
       if (first === null || first === void 0) {
-        throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id] });
+        throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id], details: { idRefs: [{ entity, id }] } });
       }
       return first;
     }
@@ -17867,7 +17947,7 @@ var BaseResource = class {
     if (!isRecord2(res)) {
       throw new AutotaskError(
         `Expected the deleted attachment model for ID ${numeric}; got a different shape`,
-        { code: "INVALID_RESPONSE", category: "server", resourceIds: [numeric] }
+        { code: "INVALID_RESPONSE", category: "server", resourceIds: [numeric], details: { idRefs: [{ entity: this.entityName, id: numeric }] } }
       );
     }
     return res;
@@ -18258,9 +18338,9 @@ var BaseResource = class {
     const resource = RESOURCE_KEY_BY_PATH[entityPath];
     const res = await this.cachedGet(`${entityPath}/${numeric}`, `${this.config.key}.fetchRecord`, fresh, resource);
     if (this.config.attachmentGet) {
-      return this.unwrapModelLike(res, numeric);
+      return this.unwrapModelLike(res, numeric, entityNameFromPath(entityPath));
     }
-    return unwrapItem(res, numeric, `${this.config.key}.fetchRecord`);
+    return unwrapItem(res, numeric, `${this.config.key}.fetchRecord`, entityNameFromPath(entityPath));
   }
   /**
    * `getContext` part fetch: a single-record read that degrades to `null`
@@ -18367,6 +18447,7 @@ var BaseResource = class {
         {
           code: "RESOLUTION_AMBIGUOUS",
           resourceIds: ids,
+          details: { idRefs: ids.map((cid) => ({ entity: this.entityName, id: cid })) },
           // issue #59 PR-B: the miss-channel pointer (the generic floor names
           // the resource's own search op — reachable only where searchFields
           // is non-empty, so the named op always exists here).
@@ -18503,7 +18584,7 @@ var BaseResource = class {
       const ids = matches.map((m) => m.id).filter((id) => typeof id === "number");
       throw new ResolutionError(
         `findBy${field}: "${value}" is ambiguous on ${this.config.key} (matched ${matches.length} records)`,
-        { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids }
+        { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids, details: { idRefs: ids.map((cid) => ({ entity: this.entityName, id: cid })) } }
       );
     }
     return matches[0];
@@ -18606,6 +18687,8 @@ export {
   MAX_PAGE_SIZE,
   DEFAULT_TIMEOUT_MS,
   DEFAULT_MAX_RETRIES,
+  DEFAULT_MAINTENANCE_MAX_WAIT_MS,
+  DEFAULT_MAINTENANCE_POLL_MS,
   DEFAULT_MAX_CONCURRENT,
   DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_MAX_SCAN_RECORDS,