/**
 * OpenTelemetry instrumentation — drop-in tracing + metrics for the MP toolkit.
 *
 * # Why a subpath?
 *
 * `@opentelemetry/api` is an OPTIONAL peer dep. Consumers who don't use
 * OpenTelemetry don't pay the bundle cost. Consumers who DO use it import
 * from `@ar-agents/mercadopago/otel` and get instant instrumentation:
 * spans for every MP request, metrics for latency/errors/rate-limit
 * remaining, and proper context propagation to your downstream traces.
 *
 * # Setup
 *
 * 1. Install: `pnpm add @opentelemetry/api`
 * 2. Wire your tracer + meter at app boot (per OpenTelemetry standard).
 * 3. Pass the instrumented hooks to MercadoPagoClient:
 *
 *    ```ts
 *    import { MercadoPagoClient } from "@ar-agents/mercadopago";
 *    import { createOtelHooks } from "@ar-agents/mercadopago/otel";
 *
 *    const otel = createOtelHooks({ serviceName: "billing-bot" });
 *    const client = new MercadoPagoClient({
 *      accessToken: process.env.MP_ACCESS_TOKEN!,
 *      onCall: otel.onCall,
 *      traceContext: otel.traceContext,
 *    });
 *    ```
 *
 * # What gets instrumented
 *
 * - **Spans**: one span per MP request, named `mp.{method}.{path}` (e.g.,
 *   `mp.GET./v1/payments/123`). Includes attributes: status code,
 *   request_id, retried count, success bool, MP rate-limit remaining,
 *   circuit breaker state.
 * - **Metrics**: `mp.requests.duration` histogram (ms), `mp.requests.count`
 *   counter (labeled by success/method/path/status), `mp.rate_limit.remaining`
 *   gauge.
 *
 * # No-op fallback
 *
 * If `@opentelemetry/api` isn't installed at runtime, the hooks degrade to
 * no-ops gracefully (without throwing) so the toolkit remains importable
 * even without OTEL configured.
 */
interface OtelHooksOptions {
    /** Service name shown in trace UIs. Default "ar-agents-mercadopago". */
    serviceName?: string;
    /** Toolkit version (defaults to a static "0.10.x"). */
    version?: string;
    /**
     * Attributes added to every span/metric (e.g., environment, deployment_id).
     */
    attributes?: Record<string, string | number | boolean>;
}
/**
 * Build OpenTelemetry-aware hooks for `MercadoPagoClient`. Returns:
 *
 * - `onCall`: wires every request into traces + metrics
 * - `traceContext`: extracts active span context for traceparent propagation
 *
 * Both degrade to no-ops if `@opentelemetry/api` isn't installed.
 */
declare function createOtelHooks(opts?: OtelHooksOptions): {
    onCall: (event: {
        method: string;
        path: string;
        durationMs: number;
        httpStatus: number | null;
        retried: number;
        success: boolean;
        requestId?: string | null;
        rateLimit?: {
            remaining: number | null;
            resetSeconds: number | null;
        };
        circuitState?: "CLOSED" | "OPEN" | "HALF_OPEN";
        traceContext?: {
            traceId?: string;
            spanId?: string;
        };
    }) => void;
    traceContext: () => {
        traceId?: string;
        spanId?: string;
        traceFlags?: number;
    } | undefined;
};

export { type OtelHooksOptions, createOtelHooks };