import type { HTTPError } from './http-errors.js';
/**
 * RFC 7807 Problem Details object shape.
 * Represents a standard HTTP problem response.
 *
 * @see https://tools.ietf.org/html/rfc7807
 *
 * @example
 * ```ts
 * const problem: TProblemDetails = {
 *   type: 'https://example.com/problems/validation-error',
 *   title: 'Validation Failed',
 *   status: 422,
 *   detail: 'The request body did not match the schema.',
 *   code: 'VALIDATION_ERROR'
 * };
 * ```
 */
export interface TProblemDetails {
    /**
     * A URI reference [RFC3986] that identifies the problem type.
     * When dereferenced, it SHOULD provide human-readable documentation.
     * Recommended format: https://api.example.com/problems/<error-code>
     */
    type?: string;
    /**
     * A short, human-readable summary of the problem type.
     * Consumers MUST NOT automatically dereference the type URI.
     */
    title: string;
    /**
     * The HTTP status code ([RFC7231], Section 6) generated by the origin server.
     * Allows detection of stale cached problem details using ETag.
     */
    status: number;
    /**
     * A human-readable explanation specific to this occurrence of the problem.
     */
    detail?: string;
    /**
     * A URI reference that identifies the specific occurrence of the problem.
     * Distinguishes this problem from other occurrences of the same type.
     */
    instance?: string;
    /**
     * Org-specific extension: the machine-readable error code.
     * From `HTTPError.Code` / `HTTPError.Metadata.code`.
     */
    code?: string;
    /**
     * Org-specific extension: safe representation of the root cause error.
     * Contains only the cause error message; stack traces are never exposed.
     * Undefined if no cause was set.
     */
    cause?: string;
}
/**
 * Converts an HTTPError to an RFC 7807 Problem Details object.
 *
 * Maps HTTPError properties to standard RFC 7807 fields:
 * - `status` ← HTTPError.HTTPStatusCode
 * - `title` ← HTTPError.Code (formatted as human-readable title)
 * - `detail` ← HTTPError.message
 *
 * Org-standard extensions:
 * - `code` ← HTTPError.Code (machine-readable error identifier)
 * - `cause` ← Safe representation of HTTPError.Cause (message only, no stack traces)
 *
 * The `type` and `instance` fields are optional; implement per your API's documentation.
 *
 * **Security:** Only the cause error message is included; stack traces and internal
 * error details are never exposed in the output.
 *
 * @param error - The HTTPError instance to serialize
 * @returns A Problem Details object compliant with RFC 7807
 *
 * @example
 * ```ts
 * import { HTTPNotFoundError, ToProblemDetails } from '@pawells/http-common';
 *
 * try {
 *   throw new HTTPNotFoundError('User #42 not found');
 * } catch (error) {
 *   if (error instanceof HTTPNotFoundError) {
 *     const problem = ToProblemDetails(error);
 *     // {
 *     //   title: 'HTTP Not Found',
 *     //   status: 404,
 *     //   detail: 'User #42 not found',
 *     //   code: 'HTTP_NOT_FOUND'
 *     // }
 *     response.status(problem.status).json(problem);
 *   }
 * }
 * ```
 *
 * @example
 * ```ts
 * // Cause chaining
 * try {
 *   const user = await db.find(id);
 * } catch (dbError) {
 *   throw new HTTPInternalServerError('Database query failed', {
 *     cause: dbError
 *   });
 * }
 *
 * const error = new HTTPInternalServerError('Database query failed', {
 *   cause: new Error('Connection refused')
 * });
 *
 * const problem = ToProblemDetails(error);
 * // {
 * //   title: 'HTTP Internal Server Error',
 * //   status: 500,
 * //   detail: 'Database query failed',
 * //   code: 'HTTP_INTERNAL_SERVER_ERROR',
 * //   cause: 'Connection refused'
 * // }
 * ```
 */
export declare function ToProblemDetails(error: HTTPError): TProblemDetails;
//# sourceMappingURL=problem-details.d.ts.map