@beignet/core/dist/error-reporting/index.d.ts

Core framework primitives for Beignet

/**
 * @beignet/core/error-reporting
 *
 * Provider-neutral error reporting primitives for Beignet applications.
 */
import { type RedactionOptions } from "../ports/redaction.js";
export { DEFAULT_ERROR_REPORTING_TIMEOUT_MS, ErrorReportingTimeoutError, } from "./internal.js";
type MaybePromise<T> = T | Promise<T>;
/**
 * JSON-compatible value accepted by error reporting context, tags, and extras.
 */
export type ErrorReportJsonValue = null | boolean | number | string | readonly ErrorReportJsonValue[] | {
    readonly [key: string]: ErrorReportJsonValue;
};
/**
 * Error severity level shared by common reporting providers.
 */
export type ErrorReportLevel = "fatal" | "error" | "warning" | "info" | "debug";
/**
 * User or actor attached to a reported error.
 */
export type ErrorReportUser = {
    id?: string;
    email?: string;
    username?: string;
    ipAddress?: string;
} & Record<string, ErrorReportJsonValue | undefined>;
/**
 * Provider-neutral structured context attached to a reported error.
 */
export type ErrorReportContext = Record<string, ErrorReportJsonValue | undefined>;
/**
 * Tags used for searching, grouping, and alert routing.
 */
export type ErrorReportTags = Record<string, string | number | boolean | null | undefined>;
/**
 * Options accepted by exception and message capture calls.
 */
export type ErrorReportOptions = {
    level?: ErrorReportLevel;
    user?: ErrorReportUser | null;
    tags?: ErrorReportTags;
    contexts?: Record<string, ErrorReportContext | undefined>;
    extra?: Record<string, ErrorReportJsonValue | undefined>;
    fingerprint?: readonly string[];
    mechanism?: string;
    handled?: boolean;
    requestId?: string;
    traceId?: string;
    spanId?: string;
    parentSpanId?: string;
    traceparent?: string;
};
/**
 * Arguments accepted by `tryReportException(...)`.
 */
export interface TryReportExceptionOptions {
    /** Reporter that owns the capture. Omit it to make reporting a no-op. */
    reporter?: ErrorReporterPort | ErrorReporterResolver;
    /** Original application or infrastructure error. */
    error: unknown;
    /** Structured metadata attached to the report. */
    reportOptions?: ErrorReportOptions;
    /**
     * Maximum time allowed for capture and, separately, the failure observer.
     * Set to `false` only when the reporting implementation is intentionally
     * unbounded.
     *
     * @default 1000
     */
    timeoutMs?: number | false;
    /**
     * Observer for reporter failures. Observer failures are also isolated.
     */
    onReporterError?: (args: {
        error: unknown;
        reportingError: unknown;
    }) => MaybePromise<void>;
}
/**
 * Result returned by a reporting provider after capture.
 */
export type ErrorReportResult = {
    id?: string;
};
/**
 * Flush options accepted by providers that buffer events.
 */
export type ErrorReporterFlushOptions = {
    timeoutMs?: number;
};
/**
 * App-facing error reporting port.
 */
export type ErrorReporterPort = {
    captureException(error: unknown, options?: ErrorReportOptions): Promise<ErrorReportResult>;
    captureMessage(message: string, options?: ErrorReportOptions): Promise<ErrorReportResult>;
    setUser(user: ErrorReportUser | null): MaybePromise<void>;
    setTags(tags: ErrorReportTags): MaybePromise<void>;
    setContext(name: string, context: ErrorReportContext | null): MaybePromise<void>;
    flush(options?: ErrorReporterFlushOptions): Promise<boolean>;
};
/** Lazy reporter resolver evaluated inside the best-effort capture deadline. */
export type ErrorReporterResolver = () => MaybePromise<ErrorReporterPort | undefined>;
/**
 * Captured exception stored by `createMemoryErrorReporter(...)`.
 */
export type MemoryReportedException = {
    type: "exception";
    error: unknown;
    options?: ErrorReportOptions;
    id: string;
};
/**
 * Captured message stored by `createMemoryErrorReporter(...)`.
 */
export type MemoryReportedMessage = {
    type: "message";
    message: string;
    options?: ErrorReportOptions;
    id: string;
};
/**
 * Captured report stored by `createMemoryErrorReporter(...)`.
 */
export type MemoryErrorReport = MemoryReportedException | MemoryReportedMessage;
/**
 * In-memory reporter state exposed for tests.
 */
export type MemoryErrorReporterPort = ErrorReporterPort & {
    reports: MemoryErrorReport[];
    user: ErrorReportUser | null;
    tags: ErrorReportTags;
    contexts: Map<string, ErrorReportContext>;
    reset(): void;
};
/**
 * Options accepted by `createMemoryErrorReporter(...)`.
 */
export type CreateMemoryErrorReporterOptions = {
    onCapture?: (report: MemoryErrorReport) => MaybePromise<void>;
};
/**
 * Create a no-op reporter for apps that want to bind the port without sending
 * events.
 */
export declare function createNoopErrorReporter(): ErrorReporterPort;
/**
 * Create an in-memory reporter for tests and local assertions.
 */
export declare function createMemoryErrorReporter(options?: CreateMemoryErrorReporterOptions): MemoryErrorReporterPort;
/**
 * Report an exception through any `ErrorReporterPort`.
 */
export declare function reportException(reporter: ErrorReporterPort, error: unknown, options?: ErrorReportOptions): Promise<ErrorReportResult>;
/**
 * Report a message through any `ErrorReporterPort`.
 */
export declare function reportMessage(reporter: ErrorReporterPort, message: string, options?: ErrorReportOptions): Promise<ErrorReportResult>;
/**
 * Best-effort exception capture for runtime boundaries.
 *
 * Missing reporters, reporter failures, and reporter-failure observer errors
 * resolve to `undefined` so diagnostics cannot replace application behavior.
 */
export declare function tryReportException(options: TryReportExceptionOptions): Promise<ErrorReportResult | undefined>;
/**
 * Redact structured error-report metadata with Beignet's shared sensitive-key
 * rules. The original exception is intentionally not part of this operation.
 */
export declare function redactErrorReportOptions(options: ErrorReportOptions, redactionOptions?: RedactionOptions): ErrorReportOptions;
//# sourceMappingURL=index.d.ts.map