@sudowealth/schwab-api/dist/src/auth/token-refresh-tracer.d.ts

TypeScript client for Charles Schwab API with OAuth support, market data, trading functionality, and complete type safety

import { type TokenData } from './types';
/**
 * Options for token refresh tracing
 */
interface TokenRefreshTracerOptions {
    /**
     * Whether to include the raw HTTP responses in the trace
     * WARNING: This will include sensitive token data
     * @default false
     */
    includeRawResponses?: boolean;
    /**
     * Custom callback function for handling trace events
     * If provided, logs will be sent to this function instead of console
     */
    tracerCallback?: ((event: TokenRefreshTraceEvent) => void) | undefined;
    /**
     * Add additional context information to trace events
     */
    additionalContext?: Record<string, any>;
    /**
     * Maximum number of events to keep in history
     * @default 10
     */
    maxHistorySize?: number;
}
/**
 * Types of token refresh trace events
 */
declare enum TokenRefreshEventType {
    REFRESH_STARTED = "refresh_started",
    REFRESH_HTTP_REQUEST = "refresh_http_request",
    REFRESH_HTTP_RESPONSE = "refresh_http_response",
    REFRESH_SUCCEEDED = "refresh_succeeded",
    REFRESH_FAILED = "refresh_failed",
    TOKEN_VALIDATION = "token_validation",
    TOKEN_USED = "token_used",
    TOKEN_SAVE = "token_save",
    TOKEN_LOAD = "token_load"
}
/**
 * Token refresh trace event structure
 */
interface TokenRefreshTraceEvent {
    /**
     * Unique ID for the refresh operation
     */
    refreshId: string;
    /**
     * Timestamp when the event occurred
     */
    timestamp: string;
    /**
     * Type of trace event
     */
    eventType: TokenRefreshEventType;
    /**
     * Additional details specific to the event type
     */
    details: {
        /**
         * For HTTP requests: URL, method, headers (sanitized)
         * For HTTP responses: status, headers, partial body (sanitized)
         * For token events: token status (sanitized)
         */
        [key: string]: any;
    };
    /**
     * Error information if applicable
     */
    error?: {
        message: string;
        name: string;
        stack?: string;
        code?: string;
        status?: number;
    };
    /**
     * Additional context information
     */
    context?: Record<string, any>;
}
/**
 * Singleton token refresh tracer class
 * Provides detailed tracing of token refresh operations
 */
export declare class TokenRefreshTracer {
    private static instance;
    private options;
    private traceHistory;
    private activeRefreshId;
    private constructor();
    /**
     * Get the singleton instance of the tracer
     */
    static getInstance(options?: TokenRefreshTracerOptions): TokenRefreshTracer;
    /**
     * Update tracer options
     */
    updateOptions(options: Partial<TokenRefreshTracerOptions>): void;
    /**
     * Start tracing a new token refresh operation
     */
    startRefreshTrace(): string;
    /**
     * Record an HTTP request for token refresh
     */
    recordRefreshRequest(refreshId: string | null, url: string, method: string, headers: Record<string, string>, body?: any): void;
    /**
     * Record an HTTP response from token refresh
     */
    recordRefreshResponse(refreshId: string | null, status: number, headers: Record<string, string>, body: any): void;
    /**
     * Record successful token refresh
     */
    recordRefreshSuccess(refreshId: string | null, tokenData: Partial<TokenData>): void;
    /**
     * Record failed token refresh
     */
    recordRefreshFailure(refreshId: string | null, error: Error | unknown): void;
    /**
     * Record token validation event
     */
    recordTokenValidation(isValid: boolean, tokenData: Partial<TokenData>, reason?: string): void;
    /**
     * Record token being used for an API request
     */
    recordTokenUsed(url: string, method: string, tokenSegment: string): void;
    /**
     * Record token save operation
     */
    recordTokenSave(success: boolean, error?: Error | unknown): void;
    /**
     * Record token load operation
     */
    recordTokenLoad(success: boolean, result?: {
        hasTokens: boolean;
    }, error?: Error | unknown): void;
    /**
     * Get the trace history
     */
    getTraceHistory(): TokenRefreshTraceEvent[];
    /**
     * Clear the trace history
     */
    clearTraceHistory(): void;
    /**
     * Get detailed report of the most recent token refresh
     */
    getLatestRefreshReport(): {
        events: TokenRefreshTraceEvent[];
        summary: {
            refreshId: string;
            startTime: string;
            endTime: string;
            duration: number;
            success: boolean;
            httpRequestCount: number;
            statusCode?: number;
            errorMessage?: string;
        } | null;
    };
    /**
     * Private method to record a trace event
     */
    private recordEvent;
    /**
     * Helper to sanitize headers for logging
     */
    private sanitizeHeaders;
}
export {};