/**
 * @module correlation-id
 * Client-side correlation ID utilities for request tracking
 *
 * Correlation IDs enable distributed tracing across xBind agent operations,
 * making it easier to debug issues, track requests across microservices,
 * and correlate logs between client and server.
 *
 * Format: `req_{timestamp}_{random}`
 * Example: `req_1716234567890_a3f5c9d2`
 *
 * Usage:
 * ```typescript
 * import { generateCorrelationId, attachCorrelationId } from '@private.me/xbind';
 *
 * // Generate a new correlation ID
 * const id = generateCorrelationId();
 *
 * // Attach to request headers
 * const headers = attachCorrelationId(new Headers(), id);
 *
 * // Validate format
 * if (validateCorrelationId(id)) {
 *   console.log('Valid correlation ID');
 * }
 * ```
 */
/**
 * Correlation ID format specification
 */
export interface CorrelationIdSpec {
    /** Prefix (always 'req') */
    prefix: string;
    /** Unix timestamp in milliseconds */
    timestamp: number;
    /** Random hex string (8 characters) */
    random: string;
}
/**
 * Standard header name for correlation ID
 */
export declare const CORRELATION_ID_HEADER = "X-Correlation-ID";
/**
 * Alternative header names for compatibility
 */
export declare const CORRELATION_ID_ALIASES: readonly ["X-Request-ID", "X-Trace-ID", "X-Transaction-ID"];
/**
 * Generate a new correlation ID
 *
 * Format: `req_{timestamp}_{random}`
 * - `req`: Static prefix for identification
 * - `timestamp`: Unix timestamp in milliseconds (13 digits)
 * - `random`: 8-character hex string for uniqueness
 *
 * @returns New correlation ID string
 *
 * @example
 * ```typescript
 * const id = generateCorrelationId();
 * // => "req_1716234567890_a3f5c9d2"
 * ```
 */
export declare function generateCorrelationId(): string;
/**
 * Validate correlation ID format
 *
 * Checks if the provided string matches the expected correlation ID format.
 *
 * @param id - String to validate
 * @returns True if valid, false otherwise
 *
 * @example
 * ```typescript
 * validateCorrelationId('req_1716234567890_a3f5c9d2'); // => true
 * validateCorrelationId('invalid'); // => false
 * validateCorrelationId('req_123_abc'); // => false (wrong lengths)
 * ```
 */
export declare function validateCorrelationId(id: unknown): id is string;
/**
 * Parse correlation ID into components
 *
 * Extracts the timestamp and random components from a correlation ID.
 *
 * @param id - Correlation ID to parse
 * @returns Parsed components or null if invalid
 *
 * @example
 * ```typescript
 * const spec = parseCorrelationId('req_1716234567890_a3f5c9d2');
 * // => { prefix: 'req', timestamp: 1716234567890, random: 'a3f5c9d2' }
 * ```
 */
export declare function parseCorrelationId(id: string): CorrelationIdSpec | null;
/**
 * Attach correlation ID to request headers
 *
 * Adds the correlation ID to the X-Correlation-ID header.
 * If no ID is provided, generates a new one.
 * Compatible with both Headers API and plain objects.
 *
 * @param headers - Headers object or plain object
 * @param id - Correlation ID (generates new if not provided)
 * @returns Updated headers object
 *
 * @example
 * ```typescript
 * // With Headers API
 * const headers = new Headers();
 * attachCorrelationId(headers);
 *
 * // With plain object
 * const headers = { 'Content-Type': 'application/json' };
 * attachCorrelationId(headers, 'req_1716234567890_a3f5c9d2');
 *
 * // With existing correlation ID
 * const id = generateCorrelationId();
 * attachCorrelationId(headers, id);
 * ```
 */
export declare function attachCorrelationId<T extends Headers | Record<string, string>>(headers: T, id?: string): T;
/**
 * Extract correlation ID from request headers
 *
 * Checks the standard header and common aliases.
 *
 * @param headers - Headers object or plain object
 * @returns Correlation ID if found, undefined otherwise
 *
 * @example
 * ```typescript
 * const headers = new Headers({
 *   'X-Correlation-ID': 'req_1716234567890_a3f5c9d2'
 * });
 * const id = extractCorrelationId(headers);
 * // => 'req_1716234567890_a3f5c9d2'
 * ```
 */
export declare function extractCorrelationId(headers: Headers | Record<string, string>): string | undefined;
/**
 * Get or create correlation ID from headers
 *
 * Returns existing correlation ID from headers, or generates a new one if not found.
 * Does NOT modify the input headers.
 *
 * @param headers - Headers to check
 * @returns Existing or new correlation ID
 *
 * @example
 * ```typescript
 * const headers = new Headers();
 * const id = getOrCreateCorrelationId(headers);
 * // => Generates new ID if not found in headers
 * ```
 */
export declare function getOrCreateCorrelationId(headers?: Headers | Record<string, string>): string;
/**
 * Create a correlation ID from a timestamp
 *
 * Useful for testing or when you need deterministic IDs.
 *
 * @param timestamp - Unix timestamp in milliseconds
 * @param random - Optional random component (generates if not provided)
 * @returns Correlation ID
 *
 * @example
 * ```typescript
 * const id = createCorrelationIdFromTimestamp(1716234567890);
 * // => 'req_1716234567890_a3f5c9d2'
 *
 * const deterministicId = createCorrelationIdFromTimestamp(1716234567890, 'aaaaaaaa');
 * // => 'req_1716234567890_aaaaaaaa'
 * ```
 */
export declare function createCorrelationIdFromTimestamp(timestamp: number, random?: string): string;
/**
 * Calculate age of correlation ID in milliseconds
 *
 * @param id - Correlation ID
 * @returns Age in milliseconds, or null if invalid
 *
 * @example
 * ```typescript
 * const id = generateCorrelationId();
 * setTimeout(() => {
 *   const age = getCorrelationIdAge(id);
 *   console.log(`Request age: ${age}ms`);
 * }, 1000);
 * ```
 */
export declare function getCorrelationIdAge(id: string): number | null;
/**
 * Check if correlation ID is expired
 *
 * @param id - Correlation ID
 * @param maxAgeMs - Maximum age in milliseconds (default: 5 minutes)
 * @returns True if expired, false otherwise
 *
 * @example
 * ```typescript
 * const id = generateCorrelationId();
 * if (isCorrelationIdExpired(id, 60000)) {
 *   console.log('Request older than 1 minute');
 * }
 * ```
 */
export declare function isCorrelationIdExpired(id: string, maxAgeMs?: number): boolean;
/**
 * Middleware helper for Express/Koa-style frameworks
 *
 * Automatically attaches correlation ID to incoming requests.
 *
 * @example
 * ```typescript
 * import express from 'express';
 * import { correlationIdMiddleware } from '@private.me/xbind';
 *
 * const app = express();
 * app.use(correlationIdMiddleware());
 * ```
 */
export declare function correlationIdMiddleware(): (req: any, res: any, next: any) => void;
