/**
 * CVLogger — Generic structured logging module for the CareerVivid CLI.
 *
 * Design goals:
 *  - Zero-friction: never throws, never blocks the user — fire-and-forget
 *  - Extensible: one logger per command/feature, sessionId for event correlation
 *  - Dual-sink: (1) remote POST to cliLog Cloud Function, (2) local JSONL fallback
 *  - Buffered: batched remote flushes to minimize network calls
 *
 * Usage:
 *   import { createLogger } from "../lib/logger.js";
 *   const log = createLogger("interview", { sessionId, apiKey, version: pkg.version });
 *   log.info("session_start", { role, numQuestions });
 *   log.error("connection_error", err, { phase: "websocket_open" });
 *   await log.dispose(); // flush before process exit
 *
 * Extending to new features — no changes to this file needed:
 *   const agentLog = createLogger("agent", { apiKey, version });
 *   const resumeLog = createLogger("resume", { sessionId: resumeId, apiKey, version });
 */
export type LogLevel = "debug" | "info" | "warn" | "error";
export interface LogEvent {
    /** Severity level */
    level: LogLevel;
    /** Feature area: "interview" | "agent" | "resume" | ... */
    feature: string;
    /** Machine-readable event name: "session_start" | "billing_complete" | ... */
    event: string;
    /** Optional session/entity correlation ID */
    sessionId?: string;
    /** Arbitrary serializable metadata */
    metadata?: Record<string, unknown>;
    /** Error message (when level === "error") */
    errorMessage?: string;
    /** Error stack trace (when level === "error") */
    errorStack?: string;
    /** ISO 8601 timestamp from the client */
    clientTime: string;
    /** CLI package.json version */
    cliVersion: string;
}
export declare class CVLogger {
    private readonly _feature;
    private _sessionId;
    private readonly _flushUrl;
    private readonly _apiKey;
    private readonly _cliVersion;
    private readonly _localLogDir;
    private _buffer;
    private _flushing;
    private _disposed;
    private _flushTimer;
    private static readonly FLUSH_INTERVAL_MS;
    private static readonly FLUSH_BUFFER_SIZE;
    constructor(opts: {
        feature: string;
        sessionId?: string;
        flushUrl: string;
        apiKey?: string;
        cliVersion: string;
        localLogDir?: string;
    });
    /** Informational event. */
    info(event: string, metadata?: Record<string, unknown>): void;
    /** Warning event. */
    warn(event: string, metadata?: Record<string, unknown>): void;
    /**
     * Error event. Accepts Error objects or any thrown value.
     * Serializes the error — never rethrows.
     */
    error(event: string, err?: unknown, metadata?: Record<string, unknown>): void;
    /**
     * Record a numeric metric (latency, token count, credit charge, etc.)
     * Stored as an "info" event with metricName + metricValue in metadata.
     */
    metric(name: string, value: number, metadata?: Record<string, unknown>): void;
    /**
     * Update the sessionId after construction.
     * Use when the sessionId isn't available until after an async call.
     */
    setSessionId(sessionId: string): void;
    /**
     * Flush buffered events to the remote endpoint.
     * Safe to call multiple times — idempotent. Never throws.
     */
    flush(): Promise<void>;
    /**
     * Dispose: stop auto-flush timer + flush remaining events.
     * Always call before the command exits (use try/finally).
     */
    dispose(): Promise<void>;
    private _push;
    private _writeLocal;
}
/**
 * Create a feature-scoped logger. Pass this around; call dispose() at the end.
 *
 * @param feature   "interview" | "agent" | "resume" | "jobs" | etc.
 * @param opts.sessionId  Correlation ID (interview sessionId, resumeId, …)
 * @param opts.apiKey     CareerVivid cv_live_ key (for remote attribution)
 * @param opts.version    CLI version from package.json
 */
export declare function createLogger(feature: string, opts?: {
    sessionId?: string;
    apiKey?: string;
    version?: string;
}): CVLogger;
//# sourceMappingURL=logger.d.ts.map