/**
 * Copyright 2026 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { Span } from '@opentelemetry/api';
/**
 * System and network error codes mapped to CLIENT_CONNECTION_ERROR.
 */
export declare const connectionCodes: string[];
/**
 * System and client request error codes mapped to CLIENT_REQUEST_ERROR.
 */
export declare const requestCodes: string[];
/**
 * Stream and body error codes mapped to CLIENT_REQUEST_BODY_ERROR.
 */
export declare const requestBodyCodes: string[];
/**
 * Buffer error codes mapped to CLIENT_RESPONSE_DECODE_ERROR.
 */
export declare const decodeCodes: string[];
/**
 * Redirect error codes mapped to CLIENT_REDIRECT_ERROR.
 */
export declare const redirectCodes: string[];
/**
 * Generic class / constructor names that should be unwrapped to find more specific error causes.
 */
export declare const genericClasses: string[];
/**
 * Error codes indicating failures prior to network connection establishment.
 */
export declare const preConnectionCodes: string[];
/**
 * Maximum traversal depth for unwrapping nested error causes.
 */
export declare const DEPTH_TO_CHECK = 10;
/**
 * Decodes binary gRPC status details (`grpc-status-details-bin`) onto the error
 * object if present and not yet parsed.
 *
 * @param {unknown} e - The error to inspect and populate with parsed gRPC status details.
 */
export declare function ensureGrpcStatusDetailsParsed(e: unknown): void;
/**
 * Resolves google.rpc.ErrorInfo reason if present on the error or its cause chain.
 * Corresponds to Tier 1 in the error.type hierarchy.
 *
 * @param {unknown} e - The error to inspect.
 * @returns {string | undefined} The ErrorInfo reason string if found, or undefined.
 */
export declare function resolveErrorInfoReason(e: unknown): string | undefined;
/**
 * Resolves a server error code received from the backend service:
 * - For HTTP: The HTTP status code string (e.g. '400', '403', '503').
 * - For gRPC: The canonical gRPC status code name in uppercase (e.g. 'PERMISSION_DENIED', 'UNAVAILABLE').
 * Corresponds to Tier 2 in the error.type hierarchy.
 *
 * @param {unknown} e - The error to inspect.
 * @param {'grpc' | 'http'} rpcType - The RPC transport protocol.
 * @returns {string | undefined} The server error code string if the error came from the server, or undefined.
 */
export declare function resolveServerErrorCode(e: unknown, rpcType: 'grpc' | 'http'): string | undefined;
/**
 * Resolves client-side network and operational errors to standard CLIENT_* identifiers.
 * Corresponds to Tier 3 in the error.type hierarchy.
 *
 * @param {unknown} e - The error to inspect.
 * @returns {string | undefined} The standardized CLIENT_* error type if matched, or undefined.
 */
export declare function resolveClientNetworkOrOperationalError(e: unknown): string | undefined;
/**
 * Resolves a language-specific error type name (e.g. AbortError, TypeError, RangeError, CustomRpcError).
 * Generic wrapper types (Error, GoogleError, Object, DOMException) are excluded and unwrap e.cause.
 * Corresponds to Tier 4 in the error.type hierarchy.
 *
 * @param {unknown} e - The error to inspect.
 * @returns {string | undefined} The language-specific error class or name if found, or undefined.
 */
export declare function resolveLanguageSpecificErrorType(e: unknown): string | undefined;
/**
 * Resolves the OpenTelemetry `error.type` attribute according to the 5-tier hierarchy:
 * 1. google.rpc.ErrorInfo.reason
 * 2. Specific Server Error Code (HTTP status code or gRPC status name)
 * 3. Client-Side Network/Operational Errors (CLIENT_* standardized strings)
 * 4. Language-specific error type (e.g. AbortError, RangeError, TypeError, CustomRpcError)
 * 5. Internal Fallback ("INTERNAL")
 *
 * @param {unknown} e - The error to classify.
 * @param {'grpc' | 'http'} rpcType - The RPC transport protocol.
 * @returns {string} The resolved `error.type` value.
 */
export declare function resolveErrorType(e: unknown, rpcType: 'grpc' | 'http'): string;
/**
 * Resolves the exception type name for a failed call. Prefers specific
 * exception names (e.g. `AbortError`, `TimeoutError`, `TypeError`) and
 * constructor names over generic `Error`, falling back to `e.name` when
 * the constructor is generic or `DOMException`.
 *
 * @param {Error} e - The Error instance.
 * @returns {string} The resolved `exception.type` string.
 */
export declare function resolveExceptionType(e: Error): string;
/**
 * Resolves a Node system error code (e.g. `ECONNREFUSED`), checking the error
 * itself and any underlying cause attached by fallback wrapping.
 *
 * @param {unknown} e - The error to inspect.
 * @returns {string | undefined} The system error code string if present, or undefined.
 */
export declare function resolveSystemErrorCode(e: unknown): string | undefined;
/**
 * Resolves the canonical gRPC status name for a failed call. Status 0 (OK)
 * and codes outside the `Status` enum are treated as absent for failed calls.
 *
 * @param {unknown} e - The error to inspect.
 * @returns {string | undefined} The canonical gRPC status name if present, or undefined.
 */
export declare function resolveRpcStatusName(e: unknown): string | undefined;
/**
 * Reads the HTTP response status recorded on a fallback error.
 *
 * @param {unknown} e - The error to inspect.
 * @returns {number | undefined} The numeric HTTP status code if present, or undefined.
 */
export declare function resolveHttpStatusCode(e: unknown): number | undefined;
/**
 * Determines if a failure occurred on the client side before DNS resolution
 * or connection establishment.
 *
 * @param {unknown} e - The error to inspect.
 * @returns {boolean} True if the error occurred before connection establishment.
 */
export declare function isPreConnectionFailure(e: unknown): boolean;
/**
 * Resolves a human-readable description for non-Error throws, extracting
 * `message` if present or falling back to `String(e)`.
 *
 * @param {unknown} e - The non-Error value thrown or reported.
 * @returns {string} The resolved error message string.
 */
export declare function resolveErrorMessage(e: unknown): string;
/**
 * Determines whether a failure is a server-side error (i.e. a server response arrived),
 * excluding pre-connection failures, client network/operational errors, and aborts/timeouts.
 *
 * @param {unknown} e - The error to inspect.
 * @param {'grpc' | 'http'} rpcType - The RPC transport protocol.
 * @returns {boolean} True if a server error code was resolved for the transport.
 */
export declare function isServerSideError(e: unknown, rpcType: 'grpc' | 'http'): boolean;
/**
 * Safely converts a value to a JSON string without throwing exceptions on
 * circular references, BigInt values, or non-serializable properties.
 *
 * @param {unknown} value - The value to serialize.
 * @returns {string | undefined} The serialized JSON string, or undefined if `value` is undefined or unserializable.
 */
export declare function safeJsonStringify(value: unknown): string | undefined;
/**
 * Extracts and formats server-side error details (message, status details, and metadata)
 * attached by GFE/backend on server-side errors. Note that only `message` is used on
 * low level network `exception` span events (`exception.stacktrace` is not recorded on spans).
 *
 * @param {Error} e - The server Error instance.
 * @returns {{message: string; stacktrace?: string}} The resolved server message and formatted details string.
 */
export declare function resolveServerExceptionDetails(e: Error): {
    message: string;
    stacktrace?: string;
};
/**
 * Records an `exception` span event with `exception.type` (and `exception.message`
 * when `includeMessage` is true, such as on low level network attempt spans).
 *
 * @param {Span} span - The span on which to record the exception event.
 * @param {Error} e - The error instance.
 * @param {'grpc' | 'http'} rpcType - The RPC transport protocol.
 * @param {boolean} [includeMessage=false] - Whether to include `exception.message` on the event
 *   (true for low level network attempt spans, false for client request spans).
 */
export declare function recordExceptionEvent(span: Span, e: Error, rpcType: 'grpc' | 'http', includeMessage?: boolean): void;