node-autotask 0.13.0 → 0.15.0

package/dist/{chunk-KB2ANVVR.cjs → chunk-Z7YT72SS.cjs}

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6;
 
-var _chunkCXXNONRPcjs = require('./chunk-CXXNONRP.cjs');
+var _chunkEWMG3HHUcjs = require('./chunk-EWMG3HHU.cjs');
 
 // src/auth.ts
 var AUTH_HEADERS = {
@@ -15188,6 +15188,7 @@ var HttpClient = (_class6 = class {
     );
     const auditBody = opts.body !== void 0 ? redactAuditBody(opts.body) : void 0;
     const retriable = _nullishCoalesce(opts.idempotent, () => ( IDEMPOTENT_METHODS.includes(method)));
+    const retriable5xx = _nullishCoalesce(opts.idempotent, () => ( method === "GET"));
     const expectBody = _nullishCoalesce(opts.expectBody, () => ( method !== "DELETE"));
     const ctx = { operation: opts.operation, url, correlationId };
     let lastStatus;
@@ -15313,7 +15314,7 @@ var HttpClient = (_class6 = class {
           this.release();
           if (signal.aborted || isAbortLike(err2)) throw interrupted();
           const delay = backoffDelay(attempt);
-          if (attempt < maxRetries && retriable && canWait(delay)) {
+          if (attempt < maxRetries && retriable5xx && canWait(delay)) {
             _optionalChain([this, 'access', _86 => _86.logger, 'access', _87 => _87.warn, 'optionalCall', _88 => _88(
               `[autotask] network error on ${method} ${opts.path}; retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`,
               correlationId
@@ -15384,7 +15385,7 @@ var HttpClient = (_class6 = class {
                 // The content-type is host-sourced (a host-supplied
                 // baseUrl can serve arbitrary HTML) — capped, never prose;
                 // the raw snippet rides details only.
-                suggestedAction: retriable ? `The zone answered with a non-JSON body (content-type: ${contentType.slice(0, 100)}); the zone is likely in a maintenance window \u2014 retry after the window, or verify baseUrl points at the REST API.` : `The zone answered a write with a non-JSON body (content-type: ${contentType.slice(0, 100)}); the request may have taken effect \u2014 verify the record before re-issuing (writes are never auto-retried).`
+                suggestedAction: retriable5xx ? `The zone answered with a non-JSON body (content-type: ${contentType.slice(0, 100)}); the zone is likely in a maintenance window \u2014 retry after the window, or verify baseUrl points at the REST API.` : `The zone answered a write with a non-JSON body (content-type: ${contentType.slice(0, 100)}); the request may have taken effect \u2014 verify the record before re-issuing (writes are never auto-retried).`
               }
             ) : new AutotaskError(`Invalid JSON response body for ${method} ${opts.path}`, {
               ...ctx,
@@ -15393,7 +15394,7 @@ var HttpClient = (_class6 = 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" && retriable && attempt < maxRetries) {
+            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);
               if (canWait(delay)) {
@@ -15425,7 +15426,7 @@ var HttpClient = (_class6 = class {
         }
         const deterministic500 = status >= 500 && isDeterministicVendor500(parseVendorErrors(body));
         const retryableStatus = status === 429 || status >= 500;
-        if (retryableStatus && !deterministic500 && attempt < maxRetries && retriable) {
+        if (retryableStatus && !deterministic500 && attempt < maxRetries && (status === 429 ? retriable : retriable5xx)) {
           const retryAfter = parseRetryAfter(res.headers.get("Retry-After"));
           const delay = retryAfter !== void 0 ? retryAfter * 1e3 : backoffDelay(attempt);
           if (canWait(delay)) {
@@ -15929,7 +15930,7 @@ function capabilitySets() {
   const fieldOps = /* @__PURE__ */ new Map();
   const udfOps = /* @__PURE__ */ new Map();
   const resources = /* @__PURE__ */ new Set();
-  for (const rec of _chunkCXXNONRPcjs.CAPABILITIES) {
+  for (const rec of _chunkEWMG3HHUcjs.CAPABILITIES) {
     if (rec.resource === "operations") continue;
     resources.add(rec.resource);
     if (rec.operation === "getFieldInfo") fieldOps.set(rec.resource, rec);
@@ -17458,13 +17459,14 @@ var BaseResource = class {
    * see the live record, and an unredacted body must not enter the
    * (redacted-view) read cache.
    */
-  async getGlobalUnredacted(id) {
+  async getGlobalUnredacted(id, readOpts) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.http.request({
       method: "GET",
       path: `${this.resourcePath}/${numeric}`,
       operation: `${this.config.key}.get`,
-      skipResponseRedaction: true
+      skipResponseRedaction: true,
+      maxRetries: _optionalChain([readOpts, 'optionalAccess', _167 => _167.maxRetries])
     });
     return unwrapItem(res, numeric, `${this.config.key}.get`);
   }
@@ -17476,13 +17478,14 @@ var BaseResource = class {
    * record's own current values: a redacted read would write literal
    * '[REDACTED]' markers into the fallback PUT (corruption on live records).
    */
-  async getScopedUnredacted(parentId, id) {
+  async getScopedUnredacted(parentId, id, readOpts) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.http.request({
       method: "GET",
       path: this.scopedItemPath(parentId, numeric),
       operation: `${this.config.key}.get`,
-      skipResponseRedaction: true
+      skipResponseRedaction: true,
+      maxRetries: _optionalChain([readOpts, 'optionalAccess', _168 => _168.maxRetries])
     });
     return unwrapItem(res, numeric, `${this.config.key}.get`);
   }
@@ -17544,7 +17547,8 @@ var BaseResource = class {
       method: "POST",
       path: this.resourcePath,
       body,
-      operation: `${this.config.key}.create`
+      operation: `${this.config.key}.create`,
+      maxRetries: opts.maxRetries
     });
     return this.unwrapCreateOperation(res, body, opts);
   }
@@ -17707,7 +17711,7 @@ var BaseResource = class {
       if (opts.raw !== true) {
         let current;
         try {
-          current = await this.getGlobalUnredacted(numeric);
+          current = await this.getGlobalUnredacted(numeric, { maxRetries: opts.maxRetries });
         } catch (err) {
           if (err instanceof NotFoundError) attachUpdateTargetMissReason(err, this.config.key);
           throw err;
@@ -17726,7 +17730,8 @@ var BaseResource = class {
         method: "PUT",
         path: collectionUpdate ? this.resourcePath : `${this.resourcePath}/${numeric}`,
         body,
-        operation
+        operation,
+        maxRetries: opts.maxRetries
       });
     } catch (err) {
       if (!this.putFallbackEligible(err)) throw err;
@@ -17734,7 +17739,7 @@ var BaseResource = class {
         throw this.putFallbackDeclined(err, route, false);
       }
       const merged = await this.putFallbackMergedBody(
-        () => this.getGlobalUnredacted(numeric),
+        () => this.getGlobalUnredacted(numeric, { maxRetries: opts.maxRetries }),
         body,
         numeric
       );
@@ -17744,7 +17749,8 @@ var BaseResource = class {
           method: "PUT",
           path: `${this.resourcePath}/${numeric}`,
           body: merged,
-          operation
+          operation,
+          maxRetries: opts.maxRetries
         });
       } catch (rerr) {
         if (this.putFallbackEligible(rerr)) throw this.putFallbackDeclined(rerr, route, true);
@@ -17758,12 +17764,13 @@ var BaseResource = class {
    *  (204 / empty body) is a valid vendor delete answer — synthesize the
    *  result from the path id (issue #25: the transport returns undefined
    *  for it; a non-blank wrong shape still throws via unwrapOperation). */
-  async deleteGlobal(id) {
+  async deleteGlobal(id, opts = {}) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.http.request({
       method: "DELETE",
       path: `${this.resourcePath}/${numeric}`,
-      operation: `${this.config.key}.delete`
+      operation: `${this.config.key}.delete`,
+      maxRetries: opts.maxRetries
     });
     return res === void 0 ? { id: numeric } : unwrapOperation(res, `${this.config.key}.delete`);
   }
@@ -17784,7 +17791,8 @@ var BaseResource = class {
       method: "POST",
       path: this.scopedCollectionPath(parentId),
       body,
-      operation: `${this.config.key}.create`
+      operation: `${this.config.key}.create`,
+      maxRetries: opts.maxRetries
     });
     return this.unwrapCreateOperation(res, body, opts);
   }
@@ -17792,7 +17800,7 @@ var BaseResource = class {
    *  Swagger documents put+patch on the scoped collection and has NO put/patch on
    *  the item path anywhere in the spec; the node strips the id from the path and
    *  PATCHes the collection, and the vendor keys the record by the id in the body. */
-  async updateScopedRaw(parentId, id, data) {
+  async updateScopedRaw(parentId, id, data, opts = {}) {
     const numeric = parseIdentifier(id, "id");
     const body = this.normalizeMutationBody(data);
     body.id = numeric;
@@ -17804,12 +17812,13 @@ var BaseResource = class {
         method: "PATCH",
         path,
         body,
-        operation
+        operation,
+        maxRetries: opts.maxRetries
       });
     } catch (err) {
       if (!this.putFallbackEligible(err)) throw err;
       const merged = await this.putFallbackMergedBody(
-        () => this.getScopedUnredacted(parentId, numeric),
+        () => this.getScopedUnredacted(parentId, numeric, { maxRetries: opts.maxRetries }),
         body,
         numeric
       );
@@ -17819,7 +17828,8 @@ var BaseResource = class {
           method: "PUT",
           path: `${path}/${numeric}`,
           body: merged,
-          operation
+          operation,
+          maxRetries: opts.maxRetries
         });
       } catch (rerr) {
         if (this.putFallbackEligible(rerr)) throw this.putFallbackDeclined(rerr, `PUT ${path}/${numeric}`, true);
@@ -17831,12 +17841,13 @@ var BaseResource = class {
   }
   /** Parent-scoped delete: `DELETE .../{parentId}/<Child>/{id}` → `{ id }`
    *  (a blank 2xx synthesizes `{ id }` from the path id — issue #25). */
-  async deleteScopedRaw(parentId, id) {
+  async deleteScopedRaw(parentId, id, opts = {}) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.http.request({
       method: "DELETE",
       path: this.scopedItemPath(parentId, id),
-      operation: `${this.config.key}.delete`
+      operation: `${this.config.key}.delete`,
+      maxRetries: opts.maxRetries
     });
     return res === void 0 ? { id: numeric } : unwrapOperation(res, `${this.config.key}.delete`);
   }
@@ -17844,12 +17855,13 @@ var BaseResource = class {
    * Attachment delete: the vendor returns the deleted attachment MODEL, not
    * OperationResultModel (G1 envelope.md) — pass it through typed.
    */
-  async deleteScopedModel(parentId, id) {
+  async deleteScopedModel(parentId, id, opts = {}) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.http.request({
       method: "DELETE",
       path: this.scopedItemPath(parentId, id),
-      operation: `${this.config.key}.delete`
+      operation: `${this.config.key}.delete`,
+      maxRetries: opts.maxRetries
     });
     if (res === void 0) return {};
     if (!isRecord2(res)) {
@@ -18132,7 +18144,7 @@ var BaseResource = class {
       current = parentId === void 0 ? await this.getGlobal(id, true) : this.config.attachmentGet ? await this.getScopedModel(parentId, id, true) : await this.getScopedRaw(parentId, id, true);
     } catch (err) {
       if (err instanceof NotFoundError) {
-        const updateReason = _optionalChain([EMPTY_REASON_STAMPS, 'access', _167 => _167[this.config.key], 'optionalAccess', _168 => _168.update]);
+        const updateReason = _optionalChain([EMPTY_REASON_STAMPS, 'access', _169 => _169[this.config.key], 'optionalAccess', _170 => _170.update]);
         checks.push({
           name: "current-record-exists",
           ok: false,
@@ -18290,12 +18302,12 @@ var BaseResource = class {
         return null;
       }
     }
-    const epoch = _optionalChain([cache, 'optionalAccess', _169 => _169.epoch]);
+    const epoch = _optionalChain([cache, 'optionalAccess', _171 => _171.epoch]);
     try {
       return await this.fetchRecordRaw(entityPath, referenceId);
     } catch (err) {
       if (err instanceof NotFoundError) {
-        _optionalChain([cache, 'optionalAccess', _170 => _170.set, 'call', _171 => _171(absentKey, CONTEXT_ABSENT_MARKER, RESOURCE_KEY_BY_PATH[entityPath], epoch)]);
+        _optionalChain([cache, 'optionalAccess', _172 => _172.set, 'call', _173 => _173(absentKey, CONTEXT_ABSENT_MARKER, RESOURCE_KEY_BY_PATH[entityPath], epoch)]);
         return null;
       }
       throw err;
@@ -18411,7 +18423,7 @@ var BaseResource = class {
   missDetail(operator, fields) {
     const key = this.config.key;
     const probe = fields.map((field) => ({ field, op: operator, value: "" }));
-    const blind = blindStampFor(_optionalChain([BLIND_SURFACE_STAMPS, 'access', _172 => _172[key], 'optionalAccess', _173 => _173.query]), probe);
+    const blind = blindStampFor(_optionalChain([BLIND_SURFACE_STAMPS, 'access', _174 => _174[key], 'optionalAccess', _175 => _175.query]), probe);
     const next = [];
     if (blind !== void 0) {
       next.push(`This surface is blind to records the API user does not own, so a miss is not proof of absence: ${blind.authority} returns the record when the id is known.`);

package/dist/{index-DbMKWnEX.d.cts → index-BXIwhAN4.d.cts}

@@ -823,7 +823,9 @@ interface AutotaskConfig {
     pageSize?: number;
     /** HTTP timeout in ms (whole-call budget). Default 30_000. */
     timeoutMs?: number;
-    /** Retry budget for idempotent requests on 429/5xx. Default 3 (0 disables). */
+    /**
+     * The client's retry budget (default 3; 0 disables auto-retry). Three legs, two rules (issues #105/#109): the 429 leg retries on the pre-#105 retriable set (GET/PUT/DELETE + idempotent-flagged calls); the 5xx/network leg and the non-JSON-2xx (#24) leg retry GET + idempotent-flagged calls only. A per-call override rides `InvokeOptions.maxRetries` / `MutationOpts.maxRetries`.
+     */
     maxRetries?: number;
     /** Optional request log sink. Default: no-op. */
     logger?: Logger;
@@ -1194,10 +1196,13 @@ interface RequestOptions {
     /** Per-request timeout override (default: config.timeoutMs). */
     timeoutMs?: number;
     /**
-     * INTERNAL (SDK-only, never a caller surface): per-request retry-budget
-     * override (default: config.maxRetries). Used by the doctor preflight
-     * (src/doctor.ts) to report failures fast — retries off, shortened
-     * timeout. Does not change the transport chain order.
+     * INTERNAL (SDK-only, never set by a caller on the transport directly):
+     * per-request retry-budget override (default: config.maxRetries). Carries
+     * the doctor preflight's fail-fast override (src/doctor.ts — retries off,
+     * shortened timeout) and the caller surfaces' per-call budget
+     * (InvokeOptions.maxRetries / MutationOpts.maxRetries, issue #105 — the
+     * resource layer threads it here; `0` = exactly one send). Does not change
+     * the transport chain order.
      */
     maxRetries?: number;
     /**
@@ -1212,7 +1217,15 @@ interface RequestOptions {
     expectBody?: boolean;
     /** Caller abort signal, combined with the deadline; aborting throws `AutotaskAbortError` (never retried). */
     signal?: AbortSignal;
-    /** Safe to retry on 429/5xx even though it is not GET/PUT/DELETE (e.g. the `/query` POST reads). Default: by method. */
+    /**
+     * Safe to retry even though the method is not GET (e.g. the `/query` POST
+     * reads; or a mutation whose payload is idempotent by construction — the
+     * issue #105 opt-back into the pre-#105 auto-retry). Default: by method —
+     * the 429 leg retries GET/PUT/DELETE (the pre-#105 rule, unchanged); the
+     * 5xx/network leg retries GET only (issue #105 — an unflagged mutation
+     * makes exactly one send there; a 429 on an unflagged POST/PATCH still
+     * surfaces at once, as before #105).
+     */
     idempotent?: boolean;
     /**
      * INTERNAL (SDK-only, never a caller surface): skip the INV-A1 response
@@ -1242,7 +1255,15 @@ interface RequestOptions {
      */
     bypassCircuitBreaker?: boolean;
 }
-/** Idempotent methods the transport may retry (POST/PATCH are never retried). */
+/**
+ * The legacy retriable method set (kept exported for the public-surface
+ * baseline): pre-#105 the transport auto-retried exactly these on 429/5xx,
+ * and #105 keeps this set as the 429 leg's rule (a 429 is a pre-processing
+ * refusal — the vendor never executed the call). Since issue #105 the
+ * 5xx/network leg is narrower — GET + explicitly idempotent-flagged calls;
+ * a mutation opts back into the pre-#105 auto-retry on both legs with
+ * `idempotent: true`.
+ */
 declare const IDEMPOTENT_METHODS: readonly string[];
 /**
  * Build the absolute request URL (base + path + query). Issue #54: the path
@@ -1884,6 +1905,21 @@ interface MutationOpts {
      * switch off).
      */
     raw?: boolean;
+    /**
+     * Issue #105: the per-call retry budget — it overrides the client's
+     * `maxRetries` for every request this mutation issues (its send and its
+     * auxiliary reads, e.g. the partial-update merge read). `0` = exactly one
+     * send per request, no auto-retry; omitted = the client's configured
+     * `maxRetries`. (Since #105 a mutation never auto-retries a 5xx or network
+     * error by default — the write-outcome is unknown once the body was
+     * written; a 429 is still retried per `Retry-After` on the pre-#105
+     * retriable set, GET/PUT/DELETE + flagged calls. The optional stale-object
+     * guard's verification read keeps the client budget. Compound ops
+     * (`time_entries.createForResource`, `companies.upsertByName`) apply the
+     * override to the op's mutation send only — their pre-wire resolution
+     * reads keep the client budget.)
+     */
+    maxRetries?: number;
 }
 /**
  * Issue #13: the create-path response-shape-drift recovery options
@@ -2168,7 +2204,9 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      * see the live record, and an unredacted body must not enter the
      * (redacted-view) read cache.
      */
-    protected getGlobalUnredacted(id: Identifier): Promise<T>;
+    protected getGlobalUnredacted(id: Identifier, readOpts?: {
+        maxRetries?: number;
+    }): Promise<T>;
     /**
      * Issue #34 fallback merge read: a FRESH parent-scoped single-record GET
      * that skips response redaction and is never cached (the same invariants
@@ -2177,7 +2215,9 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      * record's own current values: a redacted read would write literal
      * '[REDACTED]' markers into the fallback PUT (corruption on live records).
      */
-    protected getScopedUnredacted(parentId: Identifier, id: Identifier): Promise<T>;
+    protected getScopedUnredacted(parentId: Identifier, id: Identifier, readOpts?: {
+        maxRetries?: number;
+    }): Promise<T>;
     /** Parent-scoped `GET .../{parentId}/<Child>/{id}` → `{ item }` unwrapped. */
     protected getScopedRaw(parentId: Identifier, id: Identifier, fresh?: boolean): Promise<T>;
     /**
@@ -2271,7 +2311,7 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      *  (204 / empty body) is a valid vendor delete answer — synthesize the
      *  result from the path id (issue #25: the transport returns undefined
      *  for it; a non-blank wrong shape still throws via unwrapOperation). */
-    protected deleteGlobal(id: Identifier): Promise<OperationResult>;
+    protected deleteGlobal(id: Identifier, opts?: MutationOpts): Promise<OperationResult>;
     protected scopedCollectionPath(parentId: Identifier): string;
     protected scopedItemPath(parentId: Identifier, id: Identifier): string;
     /** Parent-scoped create: `POST .../{parentId}/<Child>` (issue #13: a drifted 2xx runs the bounded marker recovery where the plan pins a marker field). */
@@ -2280,15 +2320,15 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      *  Swagger documents put+patch on the scoped collection and has NO put/patch on
      *  the item path anywhere in the spec; the node strips the id from the path and
      *  PATCHes the collection, and the vendor keys the record by the id in the body. */
-    protected updateScopedRaw(parentId: Identifier, id: Identifier, data: TUpdate): Promise<OperationResult>;
+    protected updateScopedRaw(parentId: Identifier, id: Identifier, data: TUpdate, opts?: MutationOpts): Promise<OperationResult>;
     /** Parent-scoped delete: `DELETE .../{parentId}/<Child>/{id}` → `{ id }`
      *  (a blank 2xx synthesizes `{ id }` from the path id — issue #25). */
-    protected deleteScopedRaw(parentId: Identifier, id: Identifier): Promise<OperationResult>;
+    protected deleteScopedRaw(parentId: Identifier, id: Identifier, opts?: MutationOpts): Promise<OperationResult>;
     /**
      * Attachment delete: the vendor returns the deleted attachment MODEL, not
      * OperationResultModel (G1 envelope.md) — pass it through typed.
      */
-    protected deleteScopedModel(parentId: Identifier, id: Identifier): Promise<T>;
+    protected deleteScopedModel(parentId: Identifier, id: Identifier, opts?: MutationOpts): Promise<T>;
     /** `GET /V1.0/<E>/entityInformation` → `{ info }` unwrapped.
      *  Goes through the field cache when it is present (issue #80:
      *  default-on; `fieldCache: false` = the bit-for-bit uncached wire
@@ -3658,6 +3698,14 @@ interface MoveConfigurationItemOptions {
     /** The caller's snapshot of the source's lastModifiedDate; a mismatch
      *  throws STALE_OBJECT before the mutation. */
     lastModifiedDate?: string;
+    /**
+     * Issue #105: the per-call retry budget — overrides the client's
+     * `maxRetries` for every request the operation issues (the two
+     * pre-reads, the copy POST, the deactivate PUT). `0` = exactly one send
+     * per request, no auto-retry; omitted = the client's configured
+     * `maxRetries`.
+     */
+    maxRetries?: number;
 }
 interface MoveConfigurationItemResult {
     sourceId: Identifier;
@@ -6763,6 +6811,12 @@ declare class ResourceSkillsResource extends BaseResource<ResourceSkill, Resourc
 interface TransferOwnershipOptions {
     /** Default `true`: list the changes, issue no update. */
     dryRun?: boolean;
+    /**
+     * Issue #105: the per-call retry budget for the per-company PUTs. `0` =
+     * exactly one send per company, no auto-retry; omitted = the client's
+     * configured `maxRetries`.
+     */
+    maxRetries?: number;
 }
 interface OwnershipChange {
     /** The company id being re-owned. */

package/dist/{index-TuqNq3Ro.d.ts → index-M0qJIiRt.d.ts}

@@ -823,7 +823,9 @@ interface AutotaskConfig {
     pageSize?: number;
     /** HTTP timeout in ms (whole-call budget). Default 30_000. */
     timeoutMs?: number;
-    /** Retry budget for idempotent requests on 429/5xx. Default 3 (0 disables). */
+    /**
+     * The client's retry budget (default 3; 0 disables auto-retry). Three legs, two rules (issues #105/#109): the 429 leg retries on the pre-#105 retriable set (GET/PUT/DELETE + idempotent-flagged calls); the 5xx/network leg and the non-JSON-2xx (#24) leg retry GET + idempotent-flagged calls only. A per-call override rides `InvokeOptions.maxRetries` / `MutationOpts.maxRetries`.
+     */
     maxRetries?: number;
     /** Optional request log sink. Default: no-op. */
     logger?: Logger;
@@ -1194,10 +1196,13 @@ interface RequestOptions {
     /** Per-request timeout override (default: config.timeoutMs). */
     timeoutMs?: number;
     /**
-     * INTERNAL (SDK-only, never a caller surface): per-request retry-budget
-     * override (default: config.maxRetries). Used by the doctor preflight
-     * (src/doctor.ts) to report failures fast — retries off, shortened
-     * timeout. Does not change the transport chain order.
+     * INTERNAL (SDK-only, never set by a caller on the transport directly):
+     * per-request retry-budget override (default: config.maxRetries). Carries
+     * the doctor preflight's fail-fast override (src/doctor.ts — retries off,
+     * shortened timeout) and the caller surfaces' per-call budget
+     * (InvokeOptions.maxRetries / MutationOpts.maxRetries, issue #105 — the
+     * resource layer threads it here; `0` = exactly one send). Does not change
+     * the transport chain order.
      */
     maxRetries?: number;
     /**
@@ -1212,7 +1217,15 @@ interface RequestOptions {
     expectBody?: boolean;
     /** Caller abort signal, combined with the deadline; aborting throws `AutotaskAbortError` (never retried). */
     signal?: AbortSignal;
-    /** Safe to retry on 429/5xx even though it is not GET/PUT/DELETE (e.g. the `/query` POST reads). Default: by method. */
+    /**
+     * Safe to retry even though the method is not GET (e.g. the `/query` POST
+     * reads; or a mutation whose payload is idempotent by construction — the
+     * issue #105 opt-back into the pre-#105 auto-retry). Default: by method —
+     * the 429 leg retries GET/PUT/DELETE (the pre-#105 rule, unchanged); the
+     * 5xx/network leg retries GET only (issue #105 — an unflagged mutation
+     * makes exactly one send there; a 429 on an unflagged POST/PATCH still
+     * surfaces at once, as before #105).
+     */
     idempotent?: boolean;
     /**
      * INTERNAL (SDK-only, never a caller surface): skip the INV-A1 response
@@ -1242,7 +1255,15 @@ interface RequestOptions {
      */
     bypassCircuitBreaker?: boolean;
 }
-/** Idempotent methods the transport may retry (POST/PATCH are never retried). */
+/**
+ * The legacy retriable method set (kept exported for the public-surface
+ * baseline): pre-#105 the transport auto-retried exactly these on 429/5xx,
+ * and #105 keeps this set as the 429 leg's rule (a 429 is a pre-processing
+ * refusal — the vendor never executed the call). Since issue #105 the
+ * 5xx/network leg is narrower — GET + explicitly idempotent-flagged calls;
+ * a mutation opts back into the pre-#105 auto-retry on both legs with
+ * `idempotent: true`.
+ */
 declare const IDEMPOTENT_METHODS: readonly string[];
 /**
  * Build the absolute request URL (base + path + query). Issue #54: the path
@@ -1884,6 +1905,21 @@ interface MutationOpts {
      * switch off).
      */
     raw?: boolean;
+    /**
+     * Issue #105: the per-call retry budget — it overrides the client's
+     * `maxRetries` for every request this mutation issues (its send and its
+     * auxiliary reads, e.g. the partial-update merge read). `0` = exactly one
+     * send per request, no auto-retry; omitted = the client's configured
+     * `maxRetries`. (Since #105 a mutation never auto-retries a 5xx or network
+     * error by default — the write-outcome is unknown once the body was
+     * written; a 429 is still retried per `Retry-After` on the pre-#105
+     * retriable set, GET/PUT/DELETE + flagged calls. The optional stale-object
+     * guard's verification read keeps the client budget. Compound ops
+     * (`time_entries.createForResource`, `companies.upsertByName`) apply the
+     * override to the op's mutation send only — their pre-wire resolution
+     * reads keep the client budget.)
+     */
+    maxRetries?: number;
 }
 /**
  * Issue #13: the create-path response-shape-drift recovery options
@@ -2168,7 +2204,9 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      * see the live record, and an unredacted body must not enter the
      * (redacted-view) read cache.
      */
-    protected getGlobalUnredacted(id: Identifier): Promise<T>;
+    protected getGlobalUnredacted(id: Identifier, readOpts?: {
+        maxRetries?: number;
+    }): Promise<T>;
     /**
      * Issue #34 fallback merge read: a FRESH parent-scoped single-record GET
      * that skips response redaction and is never cached (the same invariants
@@ -2177,7 +2215,9 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      * record's own current values: a redacted read would write literal
      * '[REDACTED]' markers into the fallback PUT (corruption on live records).
      */
-    protected getScopedUnredacted(parentId: Identifier, id: Identifier): Promise<T>;
+    protected getScopedUnredacted(parentId: Identifier, id: Identifier, readOpts?: {
+        maxRetries?: number;
+    }): Promise<T>;
     /** Parent-scoped `GET .../{parentId}/<Child>/{id}` → `{ item }` unwrapped. */
     protected getScopedRaw(parentId: Identifier, id: Identifier, fresh?: boolean): Promise<T>;
     /**
@@ -2271,7 +2311,7 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      *  (204 / empty body) is a valid vendor delete answer — synthesize the
      *  result from the path id (issue #25: the transport returns undefined
      *  for it; a non-blank wrong shape still throws via unwrapOperation). */
-    protected deleteGlobal(id: Identifier): Promise<OperationResult>;
+    protected deleteGlobal(id: Identifier, opts?: MutationOpts): Promise<OperationResult>;
     protected scopedCollectionPath(parentId: Identifier): string;
     protected scopedItemPath(parentId: Identifier, id: Identifier): string;
     /** Parent-scoped create: `POST .../{parentId}/<Child>` (issue #13: a drifted 2xx runs the bounded marker recovery where the plan pins a marker field). */
@@ -2280,15 +2320,15 @@ declare abstract class BaseResource<T = Record<string, unknown>, TCreate = Recor
      *  Swagger documents put+patch on the scoped collection and has NO put/patch on
      *  the item path anywhere in the spec; the node strips the id from the path and
      *  PATCHes the collection, and the vendor keys the record by the id in the body. */
-    protected updateScopedRaw(parentId: Identifier, id: Identifier, data: TUpdate): Promise<OperationResult>;
+    protected updateScopedRaw(parentId: Identifier, id: Identifier, data: TUpdate, opts?: MutationOpts): Promise<OperationResult>;
     /** Parent-scoped delete: `DELETE .../{parentId}/<Child>/{id}` → `{ id }`
      *  (a blank 2xx synthesizes `{ id }` from the path id — issue #25). */
-    protected deleteScopedRaw(parentId: Identifier, id: Identifier): Promise<OperationResult>;
+    protected deleteScopedRaw(parentId: Identifier, id: Identifier, opts?: MutationOpts): Promise<OperationResult>;
     /**
      * Attachment delete: the vendor returns the deleted attachment MODEL, not
      * OperationResultModel (G1 envelope.md) — pass it through typed.
      */
-    protected deleteScopedModel(parentId: Identifier, id: Identifier): Promise<T>;
+    protected deleteScopedModel(parentId: Identifier, id: Identifier, opts?: MutationOpts): Promise<T>;
     /** `GET /V1.0/<E>/entityInformation` → `{ info }` unwrapped.
      *  Goes through the field cache when it is present (issue #80:
      *  default-on; `fieldCache: false` = the bit-for-bit uncached wire
@@ -3658,6 +3698,14 @@ interface MoveConfigurationItemOptions {
     /** The caller's snapshot of the source's lastModifiedDate; a mismatch
      *  throws STALE_OBJECT before the mutation. */
     lastModifiedDate?: string;
+    /**
+     * Issue #105: the per-call retry budget — overrides the client's
+     * `maxRetries` for every request the operation issues (the two
+     * pre-reads, the copy POST, the deactivate PUT). `0` = exactly one send
+     * per request, no auto-retry; omitted = the client's configured
+     * `maxRetries`.
+     */
+    maxRetries?: number;
 }
 interface MoveConfigurationItemResult {
     sourceId: Identifier;
@@ -6763,6 +6811,12 @@ declare class ResourceSkillsResource extends BaseResource<ResourceSkill, Resourc
 interface TransferOwnershipOptions {
     /** Default `true`: list the changes, issue no update. */
     dryRun?: boolean;
+    /**
+     * Issue #105: the per-call retry budget for the per-company PUTs. `0` =
+     * exactly one send per company, no auto-retry; omitted = the client's
+     * configured `maxRetries`.
+     */
+    maxRetries?: number;
 }
 interface OwnershipChange {
     /** The company id being re-owned. */