@beignet/core/dist/server/hooks/error-reporting.d.ts

Core framework primitives for Beignet

/**
 * Error reporting hook utilities for @beignet/core/server
 */
import type { HttpContractConfig } from "../../contracts/index.js";
import type { ErrorReporterPort, ErrorReportOptions } from "../../error-reporting/index.js";
import type { HttpRequestLike, ServerCaughtErrorHook, ServerHook } from "../types.js";
type MaybePromise<T> = T | Promise<T>;
/**
 * Minimal context shape used by `createErrorReportingHooks(...)`.
 */
export type ErrorReportingContext = {
    ports?: {
        errorReporter?: ErrorReporterPort;
    };
    requestId?: string;
    traceId?: string;
    spanId?: string;
    parentSpanId?: string;
    traceparent?: string;
    actor?: {
        type?: string;
        id?: string;
    };
    tenant?: {
        id?: string;
    };
};
/**
 * Arguments passed to error reporting hook callbacks.
 */
export type ErrorReportingHookArgs<Ctx> = Parameters<ServerCaughtErrorHook<Ctx>>[0];
/**
 * Error reporter resolver accepted by `createErrorReportingHooks(...)`.
 */
export type ErrorReporterResolver<Ctx> = (args: ErrorReportingHookArgs<Ctx>) => MaybePromise<ErrorReporterPort | undefined>;
/**
 * Options accepted by `createErrorReportingHooks(...)`.
 */
export interface ErrorReportingHooksOptions<Ctx> {
    /**
     * Reporter to use instead of `ctx.ports.errorReporter`.
     */
    reporter?: ErrorReporterPort | ErrorReporterResolver<Ctx>;
    /**
     * Decide whether a caught error should be captured. The default reports
     * unexpected failures and skips expected catalog/auth/validation outcomes.
     */
    shouldReport?: (args: ErrorReportingHookArgs<Ctx>) => MaybePromise<boolean>;
    /**
     * Additional capture options. These are merged over Beignet's request,
     * actor, tenant, contract, and trace metadata.
     */
    reportOptions?: ErrorReportOptions | ((args: ErrorReportingHookArgs<Ctx>) => MaybePromise<ErrorReportOptions>);
    /**
     * Maximum time allowed for reporting preparation, capture, and failure
     * observation. Each phase is bounded independently. Set to `false` only for
     * intentionally unbounded reporters.
     *
     * @default 1000
     */
    timeoutMs?: number | false;
    /**
     * Observer for reporter failures. Reporter failures are otherwise ignored so
     * error reporting cannot change the HTTP response.
     */
    onReporterError?: (args: {
        error: unknown;
        reportingError: unknown;
        ctx?: Ctx;
        req: HttpRequestLike;
        contract: HttpContractConfig;
    }) => MaybePromise<void>;
}
/**
 * Create server hooks that capture unexpected HTTP request failures through
 * `ctx.ports.errorReporter`.
 *
 * The hook observes `onCaughtError`, never maps responses, and ignores capture
 * failures by default so reporting cannot affect request handling.
 */
export declare function createErrorReportingHooks<Ctx extends ErrorReportingContext = ErrorReportingContext>(config?: ErrorReportingHooksOptions<Ctx>): ServerHook<Ctx>;
/**
 * Default filter for HTTP error reporting.
 */
export declare function shouldReportServerError(error: unknown): boolean;
export {};
//# sourceMappingURL=error-reporting.d.ts.map