node-autotask 0.16.0 → 0.18.0

package/dist/{chunk-NB254T3F.js → chunk-HXOWEYV3.js}

@@ -24,6 +24,7 @@ import {
   decodeFileData,
   formatVendorDetail,
   isAutotaskError,
+  mergeDetails,
   mergePartialBody,
   parseIdentifier,
   parseVendorErrors,
@@ -33,10 +34,10 @@ import {
   unwrapItem,
   unwrapItems,
   unwrapOperation
-} from "./chunk-U6JUHHMB.js";
+} from "./chunk-VYUZZIEE.js";
 import {
   CAPABILITIES
-} from "./chunk-JIDR3NPV.js";
+} from "./chunk-VV2UUW2J.js";
 
 // src/resources/appointments.ts
 var AppointmentsResource = class extends BaseResource {
@@ -1102,13 +1103,13 @@ async function upsertByName(resource, companyName, params, opts, http) {
   if (ownerBody === null || !("item" in ownerBody) || ownerBody.item === null || ownerBody.item === void 0) {
     throw new CompanyResourceInvalidError(
       `upsertByName: owner resource ${owner} was not found (resources.get returned item: null \u2014 the resources table is blind to this API user; get is the authority)`,
-      { resourceIds: [owner], operation: OP_UPSERT_NAME, category: "not_found", suggestedAction: "Pass a known active non-API-only resource id (e.g. a ticket assignedResourceID via tickets.fullContext)." }
+      { resourceIds: [owner], details: { idRefs: [{ entity: "resource", id: owner }] }, operation: OP_UPSERT_NAME, category: "not_found", suggestedAction: "Pass a known active non-API-only resource id (e.g. a ticket assignedResourceID via tickets.fullContext)." }
     );
   }
   if (ownerBody.item.isActive !== true) {
     throw new CompanyResourceInvalidError(
       `upsertByName: owner resource ${owner} is not active (isActive !== true) \u2014 the vendor requires an active NON-API-only owner`,
-      { resourceIds: [owner], operation: OP_UPSERT_NAME, suggestedAction: "Activate the resource or pass an active non-API-only one." }
+      { resourceIds: [owner], details: { idRefs: [{ entity: "resource", id: owner }] }, operation: OP_UPSERT_NAME, suggestedAction: "Activate the resource or pass an active non-API-only one." }
     );
   }
   let merges = 0;
@@ -1145,7 +1146,8 @@ async function upsertByName(resource, companyName, params, opts, http) {
           operation: OP_UPSERT_NAME,
           httpStatus: err.httpStatus,
           vendorError: err.vendorError,
-          resourceIds: [owner]
+          resourceIds: [owner],
+          details: { idRefs: [{ entity: "resource", id: owner }] }
         }
       );
     }
@@ -2443,7 +2445,7 @@ async function moveConfigurationItem(_resource, sourceId, opts, http) {
     if (current !== opts.lastModifiedDate) {
       throw new StaleObjectError(
         `moveConfigurationItem: source item ${numericSource} was modified since the snapshot (expected lastModifiedDate ${opts.lastModifiedDate}, current ${current ?? "unknown"})`,
-        { operation: "configuration_items.moveConfigurationItem", resourceIds: [numericSource] }
+        { operation: "configuration_items.moveConfigurationItem", resourceIds: [numericSource], details: { idRefs: [{ entity: "configuration_item", id: numericSource }] } }
       );
     }
   }
@@ -2496,7 +2498,7 @@ function profilePartLimit2(value, name) {
   }
   return n;
 }
-async function contextFetchPart(http, entityPath, referenceId) {
+async function contextFetchPart(http, entityPath, referenceId, entity) {
   if (typeof referenceId !== "number" || !Number.isSafeInteger(referenceId) || referenceId < 0) {
     return null;
   }
@@ -2508,10 +2510,10 @@ async function contextFetchPart(http, entityPath, referenceId) {
     });
     const body = res;
     if (body === null || !("item" in body)) {
-      throw new NotFoundError(`context part not found (unexpected envelope shape)`, { resourceIds: [referenceId] });
+      throw new NotFoundError(`context part not found (unexpected envelope shape)`, { resourceIds: [referenceId], details: { idRefs: [{ entity, id: referenceId }] } });
     }
     if (body.item === null || body.item === void 0) {
-      throw new NotFoundError("context part not found", { resourceIds: [referenceId] });
+      throw new NotFoundError("context part not found", { resourceIds: [referenceId], details: { idRefs: [{ entity, id: referenceId }] } });
     }
     return body.item;
   } catch (err) {
@@ -2534,8 +2536,8 @@ async function profile(resource, id, opts = {}, http) {
   const relatedLimit = profilePartLimit2(opts.relatedLimit, "relatedLimit");
   const ci = await resource.get(id);
   const root = ci;
-  const type = await contextFetchPart(http, "/V1.0/ConfigurationItemTypes", root["configurationItemType"]);
-  const category = await contextFetchPart(http, "/V1.0/ConfigurationItemCategories", root["configurationItemCategoryID"]);
+  const type = await contextFetchPart(http, "/V1.0/ConfigurationItemTypes", root["configurationItemType"], "configuration_item_type");
+  const category = await contextFetchPart(http, "/V1.0/ConfigurationItemCategories", root["configurationItemCategoryID"], "configuration_item_category");
   const notes = await ciScopedQuery(http, "/V1.0/ConfigurationItemNotes/query", id, noteLimit);
   const relatedItems = await ciScopedQuery(http, "/V1.0/ConfigurationItemRelatedItems/query", id, relatedLimit);
   const associations = await ciScopedQuery(http, "/V1.0/ConfigurationItemBillingProductAssociations/query", id, PROFILE_PART_LIMIT2);
@@ -3026,7 +3028,7 @@ async function moveToCompany(_resource, sourceContactId, destinationCompanyId, o
     if (current !== opts.lastModifiedDate) {
       throw new StaleObjectError(
         `moveToCompany: source contact ${sourceId} was modified since the snapshot (expected lastModifiedDate ${opts.lastModifiedDate}, current ${typeof current === "string" ? current : "unknown"})`,
-        { operation: "contacts.moveToCompany", resourceIds: [sourceId, destId] }
+        { operation: "contacts.moveToCompany", resourceIds: [sourceId, destId], details: { idRefs: [{ entity: "contact", id: sourceId }, { entity: "company", id: destId }] } }
       );
     }
   }
@@ -3051,7 +3053,7 @@ async function moveToCompany(_resource, sourceContactId, destinationCompanyId, o
     if (clash !== void 0) {
       throw new ConflictError(
         `Contact email "${email}" already exists under company ${destId} (contact ${String(clash.id)}); aborting the move`,
-        { resourceIds: [sourceId, destId] }
+        { resourceIds: [sourceId, destId], details: { idRefs: [{ entity: "contact", id: sourceId }, { entity: "company", id: destId }] } }
       );
     }
   }
@@ -3155,7 +3157,7 @@ async function upsertByEmail(resource, companyID, email, extra, opts, http) {
   if (parentBody === null || !("item" in parentBody) || parentBody.item === null || parentBody.item === void 0) {
     throw new CompanyNotFoundError(
       `upsertByEmail: company ${cid} was not found (companies.get returned item: null \u2014 the companies count/query surface is blind to this API user; get is the authority)`,
-      { resourceIds: [cid], operation: OP_UPSERT_EMAIL }
+      { resourceIds: [cid], details: { idRefs: [{ entity: "company", id: cid }] }, operation: OP_UPSERT_EMAIL }
     );
   }
   const q = await resource.queryBounded({
@@ -3244,7 +3246,8 @@ async function upsertByEmail(resource, companyID, email, extra, opts, http) {
           operation: OP_UPSERT_EMAIL,
           httpStatus: err.httpStatus,
           vendorError: err.vendorError,
-          resourceIds: [cid]
+          resourceIds: [cid],
+          details: { idRefs: [{ entity: "company", id: cid }] }
         }
       );
     }
@@ -4814,7 +4817,7 @@ function capJoinSet2(ids, cap) {
   if (sorted.length <= cap) return { ids: sorted, truncated: false, total: sorted.length };
   return { ids: sorted.slice(0, cap), truncated: true, total: sorted.length };
 }
-async function fetchByIdsPart(http, entityPath, ids, fields, operation) {
+async function fetchByIdsPart(http, entityPath, ids, fields, operation, entity) {
   const unique = [...new Set(ids)].sort((a, b) => a - b);
   const byKey = /* @__PURE__ */ new Map();
   const misses = [];
@@ -4845,7 +4848,7 @@ async function fetchByIdsPart(http, entityPath, ids, fields, operation) {
   for (const k of queryMissed) {
     try {
       const res = await http.request({ method: "GET", path: `${entityPath}/${k}`, operation });
-      byKey.set(k, unwrapItem(res, k, operation));
+      byKey.set(k, unwrapItem(res, k, operation, entity));
     } catch (err) {
       if (err instanceof NotFoundError) {
         misses.push({ id: k, code: "NOT_FOUND", message: err.message });
@@ -5051,7 +5054,7 @@ async function profitability(resource, contractId, opts, rawHttp) {
         path: `/V1.0/Companies/${companyID}`,
         operation: OP2
       });
-      const item = unwrapItem(res, companyID, OP2);
+      const item = unwrapItem(res, companyID, OP2, "company");
       customer = item ?? null;
       customerStatus = "ok";
     } catch (err) {
@@ -5118,7 +5121,7 @@ async function profitability(resource, contractId, opts, rawHttp) {
   } else {
     const capped = capJoinSet2(invoiceIds, FETCH_BY_IDS_MAX_ITEMS);
     if (capped.truncated) wires.note = (wires.note ? wires.note + " | " : "") + `invoiceJoinTruncated: the join set is capped at ${FETCH_BY_IDS_MAX_ITEMS} of ${capped.total} invoice ids (the fetch-by-ids cap) \u2014 the figures cover the returned set only`;
-    const fb = await fetchByIdsPart(http, "/V1.0/Invoices", capped.ids, ["id", "invoiceNumber", "invoiceTotal", "paidDate", "isVoided", "dueDate"], OP2);
+    const fb = await fetchByIdsPart(http, "/V1.0/Invoices", capped.ids, ["id", "invoiceNumber", "invoiceTotal", "paidDate", "isVoided", "dueDate"], OP2, "invoice");
     wires.issued += 1;
     invoices = fb.items;
     invoicesPart = { items: fb.items, capped: capped.truncated, hasMore: capped.truncated, status: "ok", note: fb.notes.join(" | ") || void 0 };
@@ -5170,7 +5173,7 @@ async function profitability(resource, contractId, opts, rawHttp) {
   } else {
     const capped = capJoinSet2(resourceIds, FETCH_BY_IDS_MAX_ITEMS);
     if (capped.truncated) wires.note = (wires.note ? wires.note + " | " : "") + `resourceJoinTruncated: the join set is capped at ${FETCH_BY_IDS_MAX_ITEMS} of ${capped.total} resource ids (the fetch-by-ids cap) \u2014 the figures cover the returned set only`;
-    const fb = await fetchByIdsPart(http, "/V1.0/Resources", capped.ids, ["id", "internalCost", "firstName", "lastName", "isActive", "userType"], OP2);
+    const fb = await fetchByIdsPart(http, "/V1.0/Resources", capped.ids, ["id", "internalCost", "firstName", "lastName", "isActive", "userType"], OP2, "resource");
     wires.issued += 1;
     resources = fb.items;
     for (const m of fb.misses) if (m.code === "NOT_FOUND") resourceMissIds.add(m.id);
@@ -6583,7 +6586,7 @@ async function markup(_resource, id, format, http) {
   if (body === null || typeof body !== "object" || typeof body.invoiceMarkup !== "string") {
     throw new AutotaskError(
       `Expected the InvoiceMarkupResultModel envelope { invoiceMarkup: string } for invoice ${numericId}; got a different shape`,
-      { code: "INVALID_RESPONSE", category: "server", resourceIds: [numericId] }
+      { code: "INVALID_RESPONSE", category: "server", resourceIds: [numericId], details: { idRefs: [{ entity: "invoice", id: numericId }] } }
     );
   }
   return body.invoiceMarkup;
@@ -8044,7 +8047,7 @@ async function whoAmI(_resource, userName, http) {
     const ids = matches.map((m) => m.id).filter((id) => typeof id === "number");
     throw new ResolutionError(
       `whoAmI: "${value}" is ambiguous (matched ${matches.length} resources)`,
-      { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids }
+      { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids, details: { idRefs: ids.map((cid) => ({ entity: "resource", id: cid })) } }
     );
   }
   return matches[0];
@@ -8066,7 +8069,7 @@ async function transferOwnership(_resource, companyIds, destinationResourceId, h
         operation: "resources.transferOwnership",
         maxRetries: opts?.maxRetries
       });
-      const company = unwrapItem(res, id);
+      const company = unwrapItem(res, id, void 0, "company");
       const current = typeof company.ownerResourceID === "number" ? company.ownerResourceID : null;
       changes.push({ id, fromOwnerResourceID: current, toOwnerResourceID: destination });
       if (!dryRun) {
@@ -8083,6 +8086,7 @@ async function transferOwnership(_resource, companyIds, destinationResourceId, h
     } catch (err) {
       if (!dryRun && err instanceof AutotaskError) {
         err.resourceIds = [id];
+        err.details = mergeDetails(err.details, { idRefs: [{ entity: "company", id }] });
         err.suggestedAction = `Partial transfer: ${applied.length} of ${ids.length} companies were re-owned (ids: ${applied.join(", ") || "none"}); id ${id} failed. Re-run transferOwnership for the remaining ids (from ${id} on).`;
       }
       throw err;
@@ -8306,7 +8310,7 @@ async function getByYear(_resource, resourceId, year, http) {
     path: `/V1.0/Resources/${numericResource}/TimeOffBalances/${year}`,
     operation: "resource_time_off_balances.getByYear"
   });
-  return unwrapItem(res, year, "resource_time_off_balances.getByYear");
+  return unwrapItem(res, year, "resource_time_off_balances.getByYear", "resource_time_off_balance");
 }
 
 // src/resources/resource_time_off_balances.ts
@@ -10228,9 +10232,9 @@ async function fetchTicket(http, id, operation) {
   });
   const body = res;
   if (body === null || !("item" in body)) {
-    throw new NotFoundError(`Ticket ${id} not found (unexpected envelope shape)`, { resourceIds: [id] });
+    throw new NotFoundError(`Ticket ${id} not found (unexpected envelope shape)`, { resourceIds: [id], details: { idRefs: [{ entity: "ticket", id }] } });
   }
-  if (body.item === null || body.item === void 0) throw new NotFoundError(`Ticket ${id} not found`, { resourceIds: [id] });
+  if (body.item === null || body.item === void 0) throw new NotFoundError(`Ticket ${id} not found`, { resourceIds: [id], details: { idRefs: [{ entity: "ticket", id }] } });
   return body.item;
 }
 async function ticketQueryItems(http, path, filter, maxRecords, operation) {
@@ -10611,13 +10615,13 @@ async function openWithNoteAndAssign(resource, params, note, assign, opts, http)
     if (rec === null) {
       throw new TicketResourceInvalidError(
         `openWithNoteAndAssign: assignee resource ${assignee} was not found (resources.get returned item: null \u2014 the resources table is blind to the API user; get is the authority)`,
-        { resourceIds: [rid], operation: OP_OPEN, category: "not_found", suggestedAction: "Resolve the resource id (a ticket assignedResourceID via tickets.fullContext) and retry." }
+        { resourceIds: [rid], details: { idRefs: [{ entity: "resource", id: rid }] }, operation: OP_OPEN, category: "not_found", suggestedAction: "Resolve the resource id (a ticket assignedResourceID via tickets.fullContext) and retry." }
       );
     }
     if (rec.isActive !== true) {
       throw new TicketResourceInvalidError(
         `openWithNoteAndAssign: assignee resource ${assignee} is not active (isActive !== true) \u2014 the vendor would reject the assignment`,
-        { resourceIds: [rid], operation: OP_OPEN, suggestedAction: "Activate the resource or assign an active one." }
+        { resourceIds: [rid], details: { idRefs: [{ entity: "resource", id: rid }] }, operation: OP_OPEN, suggestedAction: "Activate the resource or assign an active one." }
       );
     }
   }
@@ -10698,7 +10702,8 @@ async function openWithNoteAndAssign(resource, params, note, assign, opts, http)
           operation: OP_OPEN,
           httpStatus: isAutotaskError(err) ? err.httpStatus : void 0,
           vendorError: isAutotaskError(err) ? err.vendorError : void 0,
-          resourceIds: [companyID]
+          resourceIds: [companyID],
+          details: { idRefs: [{ entity: "company", id: companyID }] }
         }
       );
     }
@@ -10719,7 +10724,7 @@ async function openWithNoteAndAssign(resource, params, note, assign, opts, http)
     try {
       const current = await fetchItemUnredacted(http, `/V1.0/Tickets/${ticketId}`, OP_OPEN, { maxRetries: opts.maxRetries });
       if (current === null) {
-        throw new NotFoundError(`openWithNoteAndAssign: ticket ${ticketId} vanished between the create and the assign merge read`, { operation: OP_OPEN, resourceIds: [ticketId] });
+        throw new NotFoundError(`openWithNoteAndAssign: ticket ${ticketId} vanished between the create and the assign merge read`, { operation: OP_OPEN, resourceIds: [ticketId], details: { idRefs: [{ entity: "ticket", id: ticketId }] } });
       }
       ticketNumber = typeof current.ticketNumber === "string" ? current.ticketNumber : null;
       const merged = mergePartialBody(current, { id: ticketId, assignedResourceID: assignee, assignedResourceRoleID: roleID });
@@ -10826,7 +10831,7 @@ async function changeStatus(resource, id, targetStatus, fields, opts, http) {
   }
   const current = await fetchItemUnredacted(http, `/V1.0/Tickets/${ticketId}`, OP_STATUS, { maxRetries: opts.maxRetries });
   if (current === null) {
-    throw new NotFoundError(`changeStatus: ticket ${ticketId} was not found (tickets.get returned item: null)`, { operation: OP_STATUS, resourceIds: [ticketId] });
+    throw new NotFoundError(`changeStatus: ticket ${ticketId} was not found (tickets.get returned item: null)`, { operation: OP_STATUS, resourceIds: [ticketId], details: { idRefs: [{ entity: "ticket", id: ticketId }] } });
   }
   const previousStatus = typeof current.status === "number" ? current.status : null;
   if (previousStatus === targetStatus) {
@@ -10869,7 +10874,7 @@ async function changeStatus(resource, id, targetStatus, fields, opts, http) {
         throw new StatusFieldsRequiredError(
           `changeStatus: status ${targetStatus} requires the field '${field}' and the live-discovered map has no proven-safe default for it \u2014 the op is safe-without-the-map (never a blind full update): supply the value in fields and retry`,
           { vendorFields: [field], currentStatus: previousStatus, targetStatus, currentValues: { [field]: current[field] ?? null } },
-          { operation: OP_STATUS, resourceIds: [ticketId] }
+          { operation: OP_STATUS, resourceIds: [ticketId], details: { idRefs: [{ entity: "ticket", id: ticketId }] } }
         );
       }
       mergeData[field] = safe;
@@ -10930,7 +10935,8 @@ async function changeStatus(resource, id, targetStatus, fields, opts, http) {
             operation: OP_STATUS,
             httpStatus: isAutotaskError(err) ? err.httpStatus : void 0,
             vendorError: isAutotaskError(err) ? err.vendorError : void 0,
-            resourceIds: [ticketId]
+            resourceIds: [ticketId],
+            details: { idRefs: [{ entity: "ticket", id: ticketId }] }
           }
         );
       }
@@ -10943,7 +10949,8 @@ async function changeStatus(resource, id, targetStatus, fields, opts, http) {
       code: "INVALID_RESPONSE",
       category: "server",
       operation: OP_STATUS,
-      resourceIds: [ticketId]
+      resourceIds: [ticketId],
+      details: { idRefs: [{ entity: "ticket", id: ticketId }] }
     });
   }
   const finalStatus = typeof verify.status === "number" ? verify.status : null;
@@ -10956,6 +10963,7 @@ async function changeStatus(resource, id, targetStatus, fields, opts, http) {
         httpStatus: 200,
         operation: OP_STATUS,
         resourceIds: [ticketId],
+        details: { idRefs: [{ entity: "ticket", id: ticketId }] },
         suggestedAction: "Re-run changeStatus (the merge re-reads the current record) or inspect the ticket (tickets.get)."
       }
     );
@@ -11405,7 +11413,7 @@ var NoApplicableAllocationCodeError = class extends AutotaskError {
       }
     );
     this.name = "NoApplicableAllocationCodeError";
-    this.details = details;
+    this.details = { ...details, idRefs: [{ entity: "resource", id: details.resourceID }] };
   }
 };
 async function boundedQuery(http, path, filter, totalCap, operation) {
@@ -11489,21 +11497,21 @@ async function resolveCode(http, family, familyLabel, pinnedId, departments, ope
       throw new AllocationCodeError(
         "NOT_FOUND",
         `Pinned allocation code ${pinnedId} was not found (billing_codes.get returned item: null)`,
-        { resourceIds: [pinnedId], operation, suggestedAction: `Resolve an existing ${familyLabel} allocation code id (billing_codes.query with a filter) and re-pin.` }
+        { resourceIds: [pinnedId], details: { idRefs: [{ entity: "billing_code", id: pinnedId }] }, operation, suggestedAction: `Resolve an existing ${familyLabel} allocation code id (billing_codes.query with a filter) and re-pin.` }
       );
     }
     if (rec.isActive !== true) {
       throw new AllocationCodeError(
         "INACTIVE",
         `Pinned allocation code ${pinnedId} (${typeof rec.name === "string" ? rec.name : "unknown name"}) is not active (isActive !== true)`,
-        { resourceIds: [pinnedId], operation, suggestedAction: "Activate the code in the tenant administration or pin an active one." }
+        { resourceIds: [pinnedId], details: { idRefs: [{ entity: "billing_code", id: pinnedId }] }, operation, suggestedAction: "Activate the code in the tenant administration or pin an active one." }
       );
     }
     if (rec.useType !== family) {
       throw new AllocationCodeError(
         "WRONG_TYPE",
         `Pinned allocation code ${pinnedId} is useType ${String(rec.useType ?? "unknown")}, not the ${familyLabel} family (useType ${family})`,
-        { resourceIds: [pinnedId], operation, suggestedAction: `Pin a code from the right family (billing_codes.query with useType eq ${family} + isActive eq true).` }
+        { resourceIds: [pinnedId], details: { idRefs: [{ entity: "billing_code", id: pinnedId }] }, operation, suggestedAction: `Pin a code from the right family (billing_codes.query with useType eq ${family} + isActive eq true).` }
       );
     }
     const dept = typeof rec.department === "number" ? rec.department : null;
@@ -11511,7 +11519,7 @@ async function resolveCode(http, family, familyLabel, pinnedId, departments, ope
       throw new AllocationCodeError(
         "NOT_APPLICABLE",
         `Pinned allocation code ${pinnedId} is scoped to department ${dept}, which is not among the resource's active role departments [${[...departments].sort((a, b) => a - b).join(", ")}] (and the code is not tenant-wide)`,
-        { resourceIds: [pinnedId], operation, suggestedAction: "Pin a tenant-wide (department null) code or one scoped to a resource department, or broaden the resource role assignments." }
+        { resourceIds: [pinnedId], details: { idRefs: [{ entity: "billing_code", id: pinnedId }] }, operation, suggestedAction: "Pin a tenant-wide (department null) code or one scoped to a resource department, or broaden the resource role assignments." }
       );
     }
     return rec;
@@ -11574,6 +11582,7 @@ async function createForResource(resource, resourceID, params, opts = {}, http)
   if (rec === null) {
     throw new ResourceInvalidError(`Resource ${rid} was not found \u2014 a time entry cannot attach to a missing resource`, {
       resourceIds: [rid],
+      details: { idRefs: [{ entity: "resource", id: rid }] },
       operation: OP,
       category: "not_found",
       suggestedAction: "Resolve the resource id (resources.get / resources.search) and retry."
@@ -11582,6 +11591,7 @@ async function createForResource(resource, resourceID, params, opts = {}, http)
   if (rec.isActive !== true) {
     throw new ResourceInvalidError(`Resource ${rid} is not active (isActive !== true) \u2014 the vendor would reject a time entry for an inactive resource`, {
       resourceIds: [rid],
+      details: { idRefs: [{ entity: "resource", id: rid }] },
       operation: OP,
       suggestedAction: "Activate the resource or pick an active one."
     });