@fairmint/canton-node-sdk 0.0.238 → 0.0.240

package/build/src/core/http/HttpClient.js

@@ -6,7 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const errors_1 = require("../errors");
-/** Handles HTTP requests with authentication, logging, and error handling */
+const abort_1 = require("./abort");
+const request_retry_1 = require("./request-retry");
+const request_value_1 = require("./request-value");
+/** Handles HTTP requests with authentication, logging, cancellation, and explicit retry safety. */
 class HttpClient {
     constructor(logger, bearerTokenProvider) {
         this.retryConfig = { maxRetries: 3, delayMs: 6000 };
@@ -14,90 +17,286 @@ class HttpClient {
         this.bearerTokenProvider = bearerTokenProvider;
         this.logger = logger;
     }
+    /** Configure the default retry policy used only by requests classified as semantic reads. */
     setRetryConfig(config) {
-        this.retryConfig = config;
+        if (!Number.isInteger(config.maxRetries) || config.maxRetries < 0) {
+            throw new errors_1.ConfigurationError('HTTP maxRetries must be a non-negative integer');
+        }
+        if (!Number.isFinite(config.delayMs) || config.delayMs < 0) {
+            throw new errors_1.ConfigurationError('HTTP retry delayMs must be a non-negative finite number');
+        }
+        this.retryConfig = { ...config };
     }
-    async makeGetRequest(url, config = {}, _retryCount = 0) {
-        try {
-            const headers = await this.buildHeaders(config);
-            const response = await this.axiosInstance.get(url, { headers });
-            await this.logRequestResponse(url, { method: 'GET', headers }, response.data);
-            return response.data;
+    async makeGetRequest(url, config = {}, options = {}) {
+        return this.makeRequest('GET', url, undefined, config, options);
+    }
+    async makePostRequest(url, data, config = {}, options = {}) {
+        return this.makeRequest('POST', url, data, config, options);
+    }
+    async makeDeleteRequest(url, config = {}, options = {}) {
+        return this.makeRequest('DELETE', url, undefined, config, options);
+    }
+    async makePatchRequest(url, data, config = {}, options = {}) {
+        return this.makeRequest('PATCH', url, data, config, options);
+    }
+    async makeRequest(method, url, initialBody, config, options) {
+        // Snapshot every caller-owned option before the first asynchronous boundary. In particular, never let replacing an
+        // options signal or retry object while a token/hook is pending change the in-flight request contract.
+        const requestOptions = (0, request_retry_1.snapshotHttpRequestOptions)(options);
+        const requestConfig = Object.freeze({ ...config });
+        const { signal, retry: requestedRetry, requestSemantics: requestedSemantics, resolveReadAttemptUrl, } = requestOptions;
+        const requestSemantics = requestedSemantics ?? (method === 'GET' ? 'read' : 'mutation');
+        if (method === 'GET' && requestSemantics !== 'read') {
+            throw new errors_1.ConfigurationError('HTTP GET requests must use read semantics');
         }
-        catch (error) {
-            // Attempt up to 3 retries for transient errors
-            if (_retryCount < this.retryConfig.maxRetries && this.isRetryableError(error)) {
-                await this.logRequestResponse(url, { method: 'GET', retry: _retryCount + 1 }, `Retrying after error (attempt ${_retryCount + 1}/${this.retryConfig.maxRetries}): ${axios_1.default.isAxiosError(error) ? (error.response?.status ?? 'network error') : String(error)}`);
-                await this.sleep(this.retryConfig.delayMs);
-                return this.makeGetRequest(url, config, _retryCount + 1);
+        if (resolveReadAttemptUrl !== undefined && requestSemantics !== 'read') {
+            throw new errors_1.ConfigurationError('Endpoint failover is only supported for semantic reads');
+        }
+        const strategy = this.resolveRetryStrategy(requestSemantics, requestedRetry);
+        const maxAttempts = strategy.kind === 'none' ? 1 : strategy.maxAttempts;
+        this.validateMaxAttempts(maxAttempts);
+        const requiresImmutableBody = strategy.kind !== 'none';
+        let currentBody = this.cloneBody(initialBody);
+        let lastFailure;
+        const failedAttempts = [];
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            let attemptContext;
+            let attemptUrl = url;
+            let identifier;
+            try {
+                (0, abort_1.throwIfAborted)(signal);
+                if (attempt > 1 && strategy.kind === 'derived-body') {
+                    const priorFailure = lastFailure;
+                    if (!priorFailure) {
+                        throw new errors_1.ConfigurationError('Cannot derive a retry body without a failed request attempt');
+                    }
+                    const derivedBody = await (0, abort_1.awaitWithAbort)(async () => {
+                        const body = await strategy.deriveBody(priorFailure.retryContext);
+                        return body;
+                    }, signal);
+                    currentBody = this.cloneDerivedBody(derivedBody);
+                }
+                attemptContext = this.createAttemptContext(attempt, currentBody, failedAttempts, signal, requiresImmutableBody);
+                if (resolveReadAttemptUrl !== undefined) {
+                    const urlContext = Object.freeze({
+                        ...attemptContext,
+                        originalUrl: url,
+                    });
+                    const resolvedAttemptUrl = await (0, abort_1.awaitWithAbort)(async () => resolveReadAttemptUrl(urlContext), signal);
+                    if (typeof resolvedAttemptUrl !== 'string' || resolvedAttemptUrl.length === 0) {
+                        throw new errors_1.ConfigurationError('Read endpoint resolver must return a non-empty URL');
+                    }
+                    attemptUrl = resolvedAttemptUrl;
+                }
+                const getAttemptIdentifier = strategy.kind === 'none' ? undefined : strategy.getAttemptIdentifier;
+                identifier = getAttemptIdentifier
+                    ? this.redactAttemptIdentifier(await (0, abort_1.awaitWithAbort)(async () => {
+                        const attemptIdentifier = await getAttemptIdentifier(attemptContext);
+                        return attemptIdentifier;
+                    }, signal))
+                    : undefined;
+                const beforeAttempt = strategy.kind === 'none' ? undefined : strategy.beforeAttempt;
+                if (beforeAttempt) {
+                    await (0, abort_1.awaitWithAbort)(async () => {
+                        await beforeAttempt(attemptContext);
+                    }, signal);
+                }
+                (0, abort_1.throwIfAborted)(signal);
+            }
+            catch (preDispatchError) {
+                throw this.preservePriorAmbiguity(requestSemantics, method, attemptUrl, this.normalizeCallbackError(preDispatchError), failedAttempts);
             }
-            // Log the error response before throwing
-            if (axios_1.default.isAxiosError(error)) {
-                await this.logRequestResponse(url, { method: 'GET' }, error.response?.data ?? error.message);
+            let dispatched = false;
+            try {
+                const headers = await (0, abort_1.awaitWithAbort)(async () => {
+                    const builtHeaders = await this.buildHeaders(requestConfig);
+                    return builtHeaders;
+                }, signal);
+                (0, abort_1.throwIfAborted)(signal);
+                const requestBody = this.cloneBody(currentBody);
+                dispatched = true;
+                const response = await this.dispatchRequest(method, attemptUrl, requestBody, headers, signal);
+                this.observeLog(attemptUrl, method === 'GET' || method === 'DELETE' ? { method, headers } : { method, headers, data: requestBody }, response);
+                return response;
+            }
+            catch (rawError) {
+                if (this.isCanceledError(rawError) || (0, abort_1.isAbortError)(rawError)) {
+                    const abortError = (0, abort_1.createAbortError)(signal, rawError);
+                    if (requestSemantics === 'read' || (!dispatched && !this.hasAmbiguousAttempt(failedAttempts))) {
+                        throw abortError;
+                    }
+                    if (!dispatched) {
+                        throw this.toTerminalError(requestSemantics, method, attemptUrl, abortError, failedAttempts);
+                    }
+                    const canceledAttempt = Object.freeze({
+                        attempt,
+                        ...(identifier !== undefined ? { identifier } : {}),
+                        errorClassification: 'ambiguous-mutation-outcome',
+                        outcomeCertainty: 'ambiguous',
+                        retryable: false,
+                    });
+                    throw this.toTerminalError(requestSemantics, method, attemptUrl, abortError, [
+                        ...failedAttempts,
+                        canceledAttempt,
+                    ]);
+                }
+                const error = this.handleRequestError(rawError);
+                const retryable = this.isRetryableError(rawError);
+                const { errorClassification, outcomeCertainty } = this.classifyRequestError(requestSemantics, error, dispatched, retryable);
+                const summary = Object.freeze({
+                    attempt,
+                    ...(identifier !== undefined ? { identifier } : {}),
+                    errorClassification,
+                    outcomeCertainty,
+                    retryable,
+                });
+                const retryContext = Object.freeze({
+                    ...attemptContext,
+                    error,
+                    errorClassification,
+                    outcomeCertainty,
+                    retryable,
+                });
+                const failure = {
+                    error,
+                    retryContext,
+                    summary,
+                };
+                lastFailure = failure;
+                this.logFailedRequest(method, attemptUrl, currentBody, rawError);
+                let retryRequest;
+                try {
+                    retryRequest = await this.shouldRetry(strategy, failure, attempt, maxAttempts, requestSemantics, signal);
+                }
+                catch (retryHookError) {
+                    throw this.toTerminalError(requestSemantics, method, attemptUrl, this.normalizeCallbackError(retryHookError), [...failedAttempts, summary]);
+                }
+                if (retryRequest) {
+                    failedAttempts.push(summary);
+                    this.logRetry(method, attemptUrl, attempt, maxAttempts, summary, rawError);
+                    try {
+                        await this.waitForRetry(strategy, retryContext, signal);
+                    }
+                    catch (backoffError) {
+                        const normalizedBackoffError = this.normalizeCallbackError(backoffError);
+                        throw this.toTerminalError(requestSemantics, method, attemptUrl, normalizedBackoffError, failedAttempts);
+                    }
+                    continue;
+                }
+                throw this.toTerminalError(requestSemantics, method, attemptUrl, error, [...failedAttempts, summary]);
             }
-            throw this.handleRequestError(error);
         }
+        // The loop either returns or throws for every attempt.
+        throw new errors_1.ConfigurationError('HTTP retry loop completed without a response or error');
     }
-    async makePostRequest(url, data, config = {}, _retryCount = 0) {
-        try {
-            const headers = await this.buildHeaders(config);
-            const response = await this.axiosInstance.post(url, data, { headers });
-            await this.logRequestResponse(url, { method: 'POST', headers, data }, response.data);
-            return response.data;
-        }
-        catch (error) {
-            if (_retryCount < this.retryConfig.maxRetries && this.isRetryableError(error)) {
-                await this.logRequestResponse(url, { method: 'POST', retry: _retryCount + 1, data }, `Retrying after error (attempt ${_retryCount + 1}/${this.retryConfig.maxRetries}): ${axios_1.default.isAxiosError(error) ? (error.response?.status ?? 'network error') : String(error)}`);
-                await this.sleep(this.retryConfig.delayMs);
-                const retryData = this.prepareDataForRetry(data);
-                return this.makePostRequest(url, retryData, config, _retryCount + 1);
-            }
-            // Log the error response before throwing
-            if (axios_1.default.isAxiosError(error)) {
-                await this.logRequestResponse(url, { method: 'POST', data }, error.response?.data ?? error.message);
+    resolveRetryStrategy(requestSemantics, retry) {
+        if (retry) {
+            if (retry.kind === 'none')
+                return Object.freeze({ kind: 'none' });
+            if (retry.kind === 'exact-body')
+                return Object.freeze({ ...retry });
+            if (typeof retry.deriveBody !== 'function') {
+                throw new errors_1.ConfigurationError('HTTP derived-body retry requires a deriveBody function');
             }
-            throw this.handleRequestError(error);
+            return Object.freeze({ ...retry });
+        }
+        // Semantic reads retain transient retry behavior regardless of HTTP verb. Mutations must explicitly opt in because
+        // their server outcome may be unknown after a response is lost.
+        if (requestSemantics === 'read') {
+            return Object.freeze({
+                kind: 'exact-body',
+                maxAttempts: this.retryConfig.maxRetries + 1,
+                backoffMs: this.retryConfig.delayMs,
+            });
+        }
+        return Object.freeze({ kind: 'none' });
+    }
+    validateMaxAttempts(maxAttempts) {
+        if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+            throw new errors_1.ConfigurationError('HTTP retry maxAttempts must be a positive integer');
+        }
+    }
+    async shouldRetry(strategy, failure, attempt, maxAttempts, requestSemantics, signal) {
+        if (strategy.kind === 'none' || attempt >= maxAttempts)
+            return false;
+        const { shouldRetry } = strategy;
+        if (shouldRetry) {
+            return (0, abort_1.awaitWithAbort)(async () => {
+                const retry = await shouldRetry(failure.retryContext);
+                return retry;
+            }, signal);
         }
+        if (requestSemantics === 'read')
+            return failure.summary.retryable;
+        return failure.summary.outcomeCertainty !== 'ambiguous' && failure.summary.retryable;
     }
-    async makeDeleteRequest(url, config = {}, _retryCount = 0) {
+    async waitForRetry(strategy, context, signal) {
+        if (strategy.kind === 'none')
+            return;
+        const configuredBackoff = strategy.backoffMs ?? this.retryConfig.delayMs;
+        const delayMs = typeof configuredBackoff === 'function'
+            ? await (0, abort_1.awaitWithAbort)(async () => {
+                const backoff = await configuredBackoff(context);
+                return backoff;
+            }, signal)
+            : configuredBackoff;
+        if (!Number.isFinite(delayMs) || delayMs < 0) {
+            throw new errors_1.ConfigurationError('HTTP retry backoffMs must resolve to a non-negative finite number');
+        }
+        if (delayMs === 0) {
+            (0, abort_1.throwIfAborted)(signal);
+            return;
+        }
+        await this.abortableSleep(delayMs, signal);
+    }
+    createAttemptContext(attempt, body, previousAttempts, signal, immutableBody) {
+        const context = {
+            attempt,
+            body: immutableBody ? this.createReadonlyBody(body) : body,
+            previousAttempts: Object.freeze([...previousAttempts]),
+            ...(signal !== undefined ? { signal } : {}),
+        };
+        return Object.freeze(context);
+    }
+    createReadonlyBody(body) {
+        const cloned = this.cloneBody(body);
+        return (0, request_value_1.deepFreezeRequestValue)(cloned);
+    }
+    cloneBody(body) {
         try {
-            const headers = await this.buildHeaders(config);
-            const response = await this.axiosInstance.delete(url, { headers });
-            await this.logRequestResponse(url, { method: 'DELETE', headers }, response.data);
-            return response.data;
+            return (0, request_value_1.cloneRequestValue)(body);
         }
         catch (error) {
-            if (_retryCount < this.retryConfig.maxRetries && this.isRetryableError(error)) {
-                await this.logRequestResponse(url, { method: 'DELETE', retry: _retryCount + 1 }, `Retrying after error (attempt ${_retryCount + 1}/${this.retryConfig.maxRetries}): ${axios_1.default.isAxiosError(error) ? (error.response?.status ?? 'network error') : String(error)}`);
-                await this.sleep(this.retryConfig.delayMs);
-                return this.makeDeleteRequest(url, config, _retryCount + 1);
-            }
-            // Log the error response before throwing
-            if (axios_1.default.isAxiosError(error)) {
-                await this.logRequestResponse(url, { method: 'DELETE' }, error.response?.data ?? error.message);
-            }
-            throw this.handleRequestError(error);
+            throw new errors_1.ConfigurationError('HTTP request bodies must be structured-cloneable', {
+                cause: error instanceof Error ? error.message : 'unknown clone failure',
+            });
         }
     }
-    async makePatchRequest(url, data, config = {}, _retryCount = 0) {
+    /** Convert a deeply readonly callback result back into an isolated mutable transport snapshot. */
+    cloneDerivedBody(body) {
         try {
-            const headers = await this.buildHeaders(config);
-            const response = await this.axiosInstance.patch(url, data, { headers });
-            await this.logRequestResponse(url, { method: 'PATCH', headers, data }, response.data);
-            return response.data;
+            return (0, request_value_1.cloneRequestValue)(body);
         }
         catch (error) {
-            if (_retryCount < this.retryConfig.maxRetries && this.isRetryableError(error)) {
-                await this.logRequestResponse(url, { method: 'PATCH', retry: _retryCount + 1, data }, `Retrying after error (attempt ${_retryCount + 1}/${this.retryConfig.maxRetries}): ${axios_1.default.isAxiosError(error) ? (error.response?.status ?? 'network error') : String(error)}`);
-                await this.sleep(this.retryConfig.delayMs);
-                const retryData = this.prepareDataForRetry(data);
-                return this.makePatchRequest(url, retryData, config, _retryCount + 1);
-            }
-            // Log the error response before throwing
-            if (axios_1.default.isAxiosError(error)) {
-                await this.logRequestResponse(url, { method: 'PATCH', data }, error.response?.data ?? error.message);
-            }
-            throw this.handleRequestError(error);
+            throw new errors_1.ConfigurationError('Derived HTTP request bodies must be structured-cloneable', {
+                cause: error instanceof Error ? error.message : 'unknown clone failure',
+            });
+        }
+    }
+    async dispatchRequest(method, url, body, headers, signal) {
+        const axiosConfig = {
+            headers,
+            ...(signal !== undefined ? { signal } : {}),
+        };
+        switch (method) {
+            case 'GET':
+                return (await this.axiosInstance.get(url, axiosConfig)).data;
+            case 'POST':
+                return (await this.axiosInstance.post(url, body, axiosConfig)).data;
+            case 'DELETE':
+                return (await this.axiosInstance.delete(url, axiosConfig)).data;
+            case 'PATCH':
+                return (await this.axiosInstance.patch(url, body, axiosConfig)).data;
         }
     }
     async buildHeaders(config) {
@@ -119,12 +318,61 @@ class HttpClient {
         }
         return headers;
     }
-    async logRequestResponse(url, request, response) {
-        if (this.logger) {
-            await this.logger.logRequestResponse(url, request, response);
+    /** Invoke logging as a detached observer. Logger behavior can never affect request control flow. */
+    observeLog(url, request, response) {
+        if (!this.logger)
+            return;
+        try {
+            const requestSnapshot = this.createLogSnapshot(request, true);
+            const responseSnapshot = this.createLogSnapshot(response);
+            void Promise.resolve(this.logger.logRequestResponse(url, requestSnapshot, responseSnapshot)).catch(() => undefined);
+        }
+        catch {
+            // Logging is deliberately observational, including for synchronous logger failures.
+        }
+    }
+    /** Isolate logger-owned values so a custom logger cannot mutate request or response control-flow state. */
+    createLogSnapshot(value, redactRequestHeaders = false) {
+        try {
+            const snapshot = (0, request_value_1.cloneRequestValue)(value);
+            if (redactRequestHeaders)
+                this.redactSensitiveLogHeaders(snapshot);
+            return (0, request_value_1.deepFreezeRequestValue)(snapshot);
+        }
+        catch {
+            return '[log value unavailable]';
         }
     }
+    /** Remove credentials from logger-owned header snapshots without changing dispatch headers. */
+    redactSensitiveLogHeaders(request) {
+        if (typeof request !== 'object' || request === null || !('headers' in request))
+            return;
+        const { headers } = request;
+        if (typeof headers !== 'object' || headers === null)
+            return;
+        for (const headerName of Object.keys(headers)) {
+            const normalizedHeaderName = headerName.toLowerCase();
+            if (normalizedHeaderName === 'authorization' || normalizedHeaderName === 'proxy-authorization') {
+                Reflect.set(headers, headerName, '[REDACTED]');
+            }
+        }
+    }
+    logFailedRequest(method, url, body, error) {
+        if (!axios_1.default.isAxiosError(error))
+            return;
+        const request = method === 'GET' || method === 'DELETE' ? { method } : { method, data: body };
+        this.observeLog(url, request, error.response?.data ?? error.message);
+    }
+    logRetry(method, url, attempt, maxAttempts, summary, error) {
+        this.observeLog(url, {
+            method,
+            nextAttempt: attempt + 1,
+            ...(summary.identifier !== undefined ? { attemptIdentifier: summary.identifier } : {}),
+        }, `Retrying after ${summary.errorClassification} (next attempt ${attempt + 1}/${maxAttempts}): ${axios_1.default.isAxiosError(error) ? (error.response?.status ?? 'network error') : 'request error'}`);
+    }
     handleRequestError(error) {
+        if (error instanceof errors_1.CantonError)
+            return error;
         if (axios_1.default.isAxiosError(error)) {
             const status = error.response?.status;
             const data = (error.response?.data ?? {});
@@ -165,10 +413,7 @@ class HttpClient {
         }
         return new errors_1.NetworkError(`Request failed: ${error instanceof Error ? error.message : String(error)}`);
     }
-    /**
-     * Formats a context object into a summary string for error messages. Shows up to MAX_CONTEXT_KEYS keys with truncated
-     * values.
-     */
+    /** Formats a context object into a summary string. Shows up to MAX_CONTEXT_KEYS keys with truncated values. */
     formatContextSummary(contextObj) {
         const contextKeys = Object.keys(contextObj);
         if (contextKeys.length === 0) {
@@ -186,10 +431,7 @@ class HttpClient {
         })
             .join(', ');
     }
-    /**
-     * Safely converts a context value to a string representation. Handles null, undefined, strings, and objects (with
-     * circular reference protection).
-     */
+    /** Safely converts a context value to a string representation. */
     stringifyContextValue(v) {
         if (typeof v === 'string') {
             return v;
@@ -201,67 +443,97 @@ class HttpClient {
             return 'undefined';
         }
         try {
-            // JSON.stringify can return undefined for functions, Symbols, or objects with toJSON() returning undefined
             const result = JSON.stringify(v);
             return typeof result === 'string' ? result : '[Object]';
         }
         catch {
-            // Handle circular references, BigInt, or other non-serializable values
             return '[Object]';
         }
     }
-    /**
-     * Determines whether a request error is retryable. Retries on:
-     *
-     * - HTTP 404 (transient during Canton node restarts)
-     * - HTTP 5xx server errors
-     * - Network errors
-     * - Canton-specific transient errors: UNKNOWN_CONTRACT_SYNCHRONIZERS (400), SEQUENCER_BACKPRESSURE (409), HTTP 503
-     */
+    /** Return true for transport failures that the SDK has historically classified as transient. */
     isRetryableError(error) {
         if (axios_1.default.isAxiosError(error)) {
             const status = error.response?.status;
             const data = (error.response?.data ?? {});
             const code = typeof data['code'] === 'string' ? data['code'] : undefined;
-            // Retry on undefined status (network error)
-            if (status === undefined) {
+            if (status === undefined || status === 404 || (status >= 500 && status < 600))
                 return true;
-            }
-            // Retry on 404 - Canton nodes may return transient 404s during restarts
-            if (status === 404) {
-                return true;
-            }
-            // Retry on 5xx server errors
-            if (status >= 500 && status < 600) {
+            if (status === 400 && code === 'UNKNOWN_CONTRACT_SYNCHRONIZERS')
                 return true;
-            }
-            // Retry on Canton-specific transient errors
-            if (status === 400 && code === 'UNKNOWN_CONTRACT_SYNCHRONIZERS') {
+            if (status === 409 && code === 'SEQUENCER_BACKPRESSURE')
                 return true;
-            }
-            if (status === 409 && code === 'SEQUENCER_BACKPRESSURE') {
-                return true;
-            }
             return false;
         }
-        // Only retry non-Axios errors that are instances of NetworkError
         return error instanceof errors_1.NetworkError;
     }
-    /** Sleep for the specified number of milliseconds */
-    async sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    classifyRequestError(requestSemantics, error, dispatched, retryable) {
+        if (!dispatched) {
+            return { errorClassification: 'pre-dispatch-failure', outcomeCertainty: 'not-dispatched' };
+        }
+        if (requestSemantics === 'read') {
+            return {
+                errorClassification: retryable ? 'transient-read-failure' : 'definite-rejection',
+                outcomeCertainty: 'definite',
+            };
+        }
+        if ((0, errors_1.isDefiniteCantonMutationRejection)(error)) {
+            return { errorClassification: 'definite-rejection', outcomeCertainty: 'definite' };
+        }
+        return { errorClassification: 'ambiguous-mutation-outcome', outcomeCertainty: 'ambiguous' };
+    }
+    toTerminalError(requestSemantics, method, url, error, attempts) {
+        if (requestSemantics === 'read' || method === 'GET' || !this.hasAmbiguousAttempt(attempts)) {
+            return error;
+        }
+        const attemptIdentifiers = attempts.flatMap((attempt) => attempt.identifier === undefined ? [] : [attempt.identifier]);
+        return new errors_1.UnknownMutationOutcomeError({
+            method,
+            endpoint: this.redactEndpoint(url),
+            attempts: attempts.length,
+            ...(attemptIdentifiers.length > 0 ? { attemptIdentifiers } : {}),
+        }, error);
+    }
+    preservePriorAmbiguity(requestSemantics, method, url, error, previousAttempts) {
+        return this.toTerminalError(requestSemantics, method, url, error, previousAttempts);
     }
-    /**
-     * Prepares request data for retry by updating commandId fields to avoid duplicate command rejection. If the data
-     * contains a commandId field, appends a retry suffix with timestamp to make it unique.
-     */
-    prepareDataForRetry(data) {
-        if (data && typeof data === 'object' && 'commandId' in data) {
-            const originalCommandId = data.commandId;
-            const retryCommandId = `${originalCommandId}-retry`;
-            return { ...data, commandId: retryCommandId };
+    hasAmbiguousAttempt(attempts) {
+        return attempts.some((attempt) => attempt.outcomeCertainty === 'ambiguous');
+    }
+    normalizeCallbackError(error) {
+        return error instanceof Error ? error : new errors_1.NetworkError(`Request callback failed: ${String(error)}`);
+    }
+    redactEndpoint(url) {
+        try {
+            const parsed = new URL(url);
+            return `${parsed.origin}${parsed.pathname}`;
+        }
+        catch {
+            const queryIndex = url.search(/[?#]/u);
+            return queryIndex < 0 ? url : url.slice(0, queryIndex);
         }
-        return data;
+    }
+    redactAttemptIdentifier(identifier) {
+        if (identifier === undefined)
+            return undefined;
+        return identifier.slice(0, HttpClient.MAX_ATTEMPT_IDENTIFIER_LENGTH);
+    }
+    isCanceledError(error) {
+        return axios_1.default.isCancel(error) || (axios_1.default.isAxiosError(error) && error.code === 'ERR_CANCELED');
+    }
+    async abortableSleep(ms, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                reject((0, abort_1.createAbortError)(signal));
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
     }
 }
 exports.HttpClient = HttpClient;
@@ -269,4 +541,5 @@ exports.HttpClient = HttpClient;
 HttpClient.CAUSE_TRUNCATE_LENGTH = 200;
 HttpClient.CONTEXT_VALUE_TRUNCATE_LENGTH = 50;
 HttpClient.MAX_CONTEXT_KEYS = 3;
+HttpClient.MAX_ATTEMPT_IDENTIFIER_LENGTH = 200;
 //# sourceMappingURL=HttpClient.js.map