node-autotask 0.39.4 → 0.41.0

package/dist/base-CVx2VMSj.d.cts

@@ -0,0 +1,103 @@
+/**
+ * AutotaskError hierarchy (ARCHITECTURE section 10).
+ *
+ * Every error carries the structured contract: `code` (stable SCREAMING_SNAKE
+ * machine code), `category`, `retryable`, plus `operation`, `httpStatus`,
+ * `vendorError` (the vendor payload under a documented key, deep-redacted —
+ * the INV-A1 hotfix), `resourceIds` (the LEGACY unlabeled id list — the
+ * stamp sites name records of several vendor entities and say nothing about
+ * which; every SDK stamp site that sets it also sets `details.idRefs`, the
+ * labeled `{ entity, id }` companion — issue #116),
+ * `suggestedAction` (deterministic next step only), `correlationId` and `url`.
+ *
+ * `item: null` on a single GET (HTTP 200) is a NOT FOUND, not a success — the
+ * vendor's not-found signal (G1 envelope.md). The vendor documents no error
+ * bodies; the shape `{ errors: [{ message, field?, code? }] }` is pinned from
+ * the node's errorHandler and parsed defensively here.
+ */
+type ErrorCategory = 'auth' | 'not_found' | 'validation' | 'conflict' | 'rate_limit' | 'server' | 'network' | 'timeout' | 'resolution' | 'policy';
+/**
+ * A labeled id reference (issue #116). The legacy `resourceIds` field reads
+ * as Autotask **Resource** (staff) ids, but the special ops stamp ids of
+ * many other entities into it (ticket / company / contact / billing-code /
+ * the failed record's own id on a generic `get`), unlabeled — so feeding an
+ * error's `resourceIds` to `operations.expandResourceNames` (whose only wire
+ * verb is `GET /V1.0/Resources/{id}`) resolves a colliding non-staff id to
+ * an unrelated person's name. Every SDK stamp site that sets `resourceIds`
+ * now also sets `details.idRefs` — the same ids, each labeled with the vendor entity
+ * it identifies — so consumers can resolve against the entity the error
+ * actually names instead of parsing the message.
+ *
+ * `entity` is the vendor entity name (singular snake_case — `company`,
+ * `ticket`, `contact`, `billing_code`, `resource`, ...; the de-pluralized
+ * vendor table name — the same word the error message uses; the SDK
+ * resource key is the same word plural). `resource` (staff) is the ONLY
+ * entity `operations.expandResourceNames` resolves — a ref of any other
+ * entity must NOT be fed to it.
+ */
+interface ErrorIdRef {
+    /** The vendor entity the id identifies (singular snake_case, e.g. `company`, `ticket`, `resource` = staff). */
+    entity: string;
+    /** The value that addresses the record at that entity's endpoint: the
+     *  vendor id (a safe integer, or the canonical integer-string form) —
+     *  except `resource_time_off_balances.getByYear`, where the endpoint's
+     *  path key is the YEAR (the vendor defines no record-id read for this
+     *  entity). */
+    id: number | string;
+}
+interface AutotaskErrorOptions {
+    code?: string;
+    category?: ErrorCategory;
+    operation?: string;
+    httpStatus?: number;
+    vendorError?: unknown;
+    /**
+     * The ids the error is about. LEGACY, unlabeled: reads as Resource
+     * (staff) ids but the stamp sites name records of several entities
+     * (issue #116). Kept for compatibility; the labeled form rides on
+     * `details.idRefs` (`ErrorIdRef[]`) and is what consumers should use.
+     * The pairing above is a guarantee of the SDK stamp sites — an error you
+     * construct yourself may set `resourceIds` without `details.idRefs`.
+     */
+    resourceIds?: (number | string)[];
+    suggestedAction?: string;
+    correlationId?: string;
+    retryable?: boolean;
+    url?: string;
+    /**
+     * The structured, deterministic extras that ride on the error WITHOUT
+     * changing its contract: issue #9 — the recovery refusals' payload
+     * (`{ resource, reason/note, ... }` on DELETE_BOUNDARY /
+     * MARKER_UNSAFE_ID / RECOVERY_TRUNCATED); issue #14 — `emptyReason`
+     * (the typed reason a miss / drift carries — { kind, note, authority,
+     * remedy }) and `pointerNote` (the known-unusable-op pointer sentence);
+     * issue #116 — `idRefs` (`ErrorIdRef[]`, the labeled `{ entity, id }`
+     * companion of the legacy `resourceIds` — every SDK stamp site that sets
+     * `resourceIds` also sets it). Additive only — the status, code, message
+     * and retryability are never derived from it.
+     */
+    details?: Record<string, unknown>;
+}
+declare class AutotaskError extends Error {
+    code: string;
+    category: ErrorCategory;
+    operation?: string;
+    httpStatus?: number;
+    vendorError?: unknown;
+    /** Legacy unlabeled id list (issue #116) — see `AutotaskErrorOptions.resourceIds`; the labeled companion rides on `details.idRefs`. */
+    resourceIds?: (number | string)[];
+    suggestedAction?: string;
+    correlationId?: string;
+    retryable: boolean;
+    url?: string;
+    /** Issue #9/#14: the additive structured extras (recovery refusal payload; emptyReason / pointerNote) — never changes the error contract. */
+    details?: Record<string, unknown>;
+    constructor(message: string, options?: AutotaskErrorOptions);
+}
+declare class AutotaskConfigError extends AutotaskError {
+    constructor(message: string, options?: AutotaskErrorOptions);
+}
+/** Type guard for the hierarchy. */
+declare function isAutotaskError(err: unknown): err is AutotaskError;
+
+export { AutotaskError as A, type ErrorCategory as E, type AutotaskErrorOptions as a, AutotaskConfigError as b, type ErrorIdRef as c, isAutotaskError as i };

package/dist/base-CVx2VMSj.d.ts

@@ -0,0 +1,103 @@
+/**
+ * AutotaskError hierarchy (ARCHITECTURE section 10).
+ *
+ * Every error carries the structured contract: `code` (stable SCREAMING_SNAKE
+ * machine code), `category`, `retryable`, plus `operation`, `httpStatus`,
+ * `vendorError` (the vendor payload under a documented key, deep-redacted —
+ * the INV-A1 hotfix), `resourceIds` (the LEGACY unlabeled id list — the
+ * stamp sites name records of several vendor entities and say nothing about
+ * which; every SDK stamp site that sets it also sets `details.idRefs`, the
+ * labeled `{ entity, id }` companion — issue #116),
+ * `suggestedAction` (deterministic next step only), `correlationId` and `url`.
+ *
+ * `item: null` on a single GET (HTTP 200) is a NOT FOUND, not a success — the
+ * vendor's not-found signal (G1 envelope.md). The vendor documents no error
+ * bodies; the shape `{ errors: [{ message, field?, code? }] }` is pinned from
+ * the node's errorHandler and parsed defensively here.
+ */
+type ErrorCategory = 'auth' | 'not_found' | 'validation' | 'conflict' | 'rate_limit' | 'server' | 'network' | 'timeout' | 'resolution' | 'policy';
+/**
+ * A labeled id reference (issue #116). The legacy `resourceIds` field reads
+ * as Autotask **Resource** (staff) ids, but the special ops stamp ids of
+ * many other entities into it (ticket / company / contact / billing-code /
+ * the failed record's own id on a generic `get`), unlabeled — so feeding an
+ * error's `resourceIds` to `operations.expandResourceNames` (whose only wire
+ * verb is `GET /V1.0/Resources/{id}`) resolves a colliding non-staff id to
+ * an unrelated person's name. Every SDK stamp site that sets `resourceIds`
+ * now also sets `details.idRefs` — the same ids, each labeled with the vendor entity
+ * it identifies — so consumers can resolve against the entity the error
+ * actually names instead of parsing the message.
+ *
+ * `entity` is the vendor entity name (singular snake_case — `company`,
+ * `ticket`, `contact`, `billing_code`, `resource`, ...; the de-pluralized
+ * vendor table name — the same word the error message uses; the SDK
+ * resource key is the same word plural). `resource` (staff) is the ONLY
+ * entity `operations.expandResourceNames` resolves — a ref of any other
+ * entity must NOT be fed to it.
+ */
+interface ErrorIdRef {
+    /** The vendor entity the id identifies (singular snake_case, e.g. `company`, `ticket`, `resource` = staff). */
+    entity: string;
+    /** The value that addresses the record at that entity's endpoint: the
+     *  vendor id (a safe integer, or the canonical integer-string form) —
+     *  except `resource_time_off_balances.getByYear`, where the endpoint's
+     *  path key is the YEAR (the vendor defines no record-id read for this
+     *  entity). */
+    id: number | string;
+}
+interface AutotaskErrorOptions {
+    code?: string;
+    category?: ErrorCategory;
+    operation?: string;
+    httpStatus?: number;
+    vendorError?: unknown;
+    /**
+     * The ids the error is about. LEGACY, unlabeled: reads as Resource
+     * (staff) ids but the stamp sites name records of several entities
+     * (issue #116). Kept for compatibility; the labeled form rides on
+     * `details.idRefs` (`ErrorIdRef[]`) and is what consumers should use.
+     * The pairing above is a guarantee of the SDK stamp sites — an error you
+     * construct yourself may set `resourceIds` without `details.idRefs`.
+     */
+    resourceIds?: (number | string)[];
+    suggestedAction?: string;
+    correlationId?: string;
+    retryable?: boolean;
+    url?: string;
+    /**
+     * The structured, deterministic extras that ride on the error WITHOUT
+     * changing its contract: issue #9 — the recovery refusals' payload
+     * (`{ resource, reason/note, ... }` on DELETE_BOUNDARY /
+     * MARKER_UNSAFE_ID / RECOVERY_TRUNCATED); issue #14 — `emptyReason`
+     * (the typed reason a miss / drift carries — { kind, note, authority,
+     * remedy }) and `pointerNote` (the known-unusable-op pointer sentence);
+     * issue #116 — `idRefs` (`ErrorIdRef[]`, the labeled `{ entity, id }`
+     * companion of the legacy `resourceIds` — every SDK stamp site that sets
+     * `resourceIds` also sets it). Additive only — the status, code, message
+     * and retryability are never derived from it.
+     */
+    details?: Record<string, unknown>;
+}
+declare class AutotaskError extends Error {
+    code: string;
+    category: ErrorCategory;
+    operation?: string;
+    httpStatus?: number;
+    vendorError?: unknown;
+    /** Legacy unlabeled id list (issue #116) — see `AutotaskErrorOptions.resourceIds`; the labeled companion rides on `details.idRefs`. */
+    resourceIds?: (number | string)[];
+    suggestedAction?: string;
+    correlationId?: string;
+    retryable: boolean;
+    url?: string;
+    /** Issue #9/#14: the additive structured extras (recovery refusal payload; emptyReason / pointerNote) — never changes the error contract. */
+    details?: Record<string, unknown>;
+    constructor(message: string, options?: AutotaskErrorOptions);
+}
+declare class AutotaskConfigError extends AutotaskError {
+    constructor(message: string, options?: AutotaskErrorOptions);
+}
+/** Type guard for the hierarchy. */
+declare function isAutotaskError(err: unknown): err is AutotaskError;
+
+export { AutotaskError as A, type ErrorCategory as E, type AutotaskErrorOptions as a, AutotaskConfigError as b, type ErrorIdRef as c, isAutotaskError as i };

package/dist/capabilities.cjs

@@ -2,9 +2,9 @@
 
 
 
-var _chunkVR6RYXTDcjs = require('./chunk-VR6RYXTD.cjs');
+var _chunkMJ6J74F3cjs = require('./chunk-MJ6J74F3.cjs');
 
 
 
 
-exports.CAPABILITIES = _chunkVR6RYXTDcjs.CAPABILITIES; exports.CAPABILITY_GROUPS = _chunkVR6RYXTDcjs.CAPABILITY_GROUPS; exports.CAPABILITY_PLAN_HASHES = _chunkVR6RYXTDcjs.CAPABILITY_PLAN_HASHES;
+exports.CAPABILITIES = _chunkMJ6J74F3cjs.CAPABILITIES; exports.CAPABILITY_GROUPS = _chunkMJ6J74F3cjs.CAPABILITY_GROUPS; exports.CAPABILITY_PLAN_HASHES = _chunkMJ6J74F3cjs.CAPABILITY_PLAN_HASHES;

package/dist/capabilities.js

@@ -2,7 +2,7 @@ import {
   CAPABILITIES,
   CAPABILITY_GROUPS,
   CAPABILITY_PLAN_HASHES
-} from "./chunk-GDSCYY2G.js";
+} from "./chunk-ZVSSAULC.js";
 export {
   CAPABILITIES,
   CAPABILITY_GROUPS,