import { BaseError } from '@pawells/typescript-common';
import { z } from 'zod/v4';
/**
 * Extended error metadata for Keycloak authentication errors.
 *
 * Adds Keycloak-specific error codes and context to the base error metadata.
 */
export declare const KEYCLOAK_ERROR_METADATA_SCHEMA: z.ZodObject<{
    code: z.ZodOptional<z.ZodString>;
    cause: z.ZodOptional<z.ZodCustom<Error, Error>>;
    keycloakCode: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
/**
 * Error metadata type for KeycloakAuthError.
 *
 * Extends base error metadata with optional Keycloak-specific error codes.
 * Used to provide structured error context when Keycloak authentication or
 * configuration failures occur.
 *
 * @example
 * ```typescript
 * const metadata: TKeycloakErrorMetadata = {
 *   code: 'KEYCLOAK_CONFIG_INVALID',
 *   keycloakCode: 'INVALID_CLIENT_SECRET',
 *   cause: originalError
 * };
 * ```
 */
export type TKeycloakErrorMetadata = z.infer<typeof KEYCLOAK_ERROR_METADATA_SCHEMA>;
/**
 * Asserts that metadata conforms to the Keycloak error metadata schema.
 *
 * @param metadata - The metadata object to validate
 * @throws {z.ZodError} If metadata fails validation
 */
export declare function AssertKeycloakErrorMetadata(metadata: unknown): asserts metadata is TKeycloakErrorMetadata;
/**
 * Validates that metadata conforms to the Keycloak error metadata schema.
 *
 * @param metadata - The metadata object to validate
 * @returns `true` if metadata is valid, `false` otherwise
 */
export declare function ValidateKeycloakErrorMetadata(metadata: unknown): boolean;
/**
 * Keycloak authentication error.
 *
 * Raised when Keycloak module initialization fails (invalid configuration) or
 * when token validation encounters a fatal error (e.g., JWKS initialization failure).
 *
 * Extends BaseError with a machine-readable `code` and optional `cause` chain for
 * error propagation. Keycloak-specific error codes are prefixed with `KEYCLOAK_`.
 *
 * @example
 * ```typescript
 * try {
 *   // Failed to load JWKS
 *   throw new KeycloakAuthError('Failed to initialize JWKS set', {
 *     code: 'KEYCLOAK_JWKS_INIT_FAILED',
 *     cause: originalError
 *   });
 * } catch (error) {
 *   if (error instanceof KeycloakAuthError) {
 *     console.log(error.Code); // 'KEYCLOAK_JWKS_INIT_FAILED'
 *     console.log(error.Cause); // originalError
 *   }
 * }
 * ```
 */
export declare class KeycloakAuthError<TMetadata extends TKeycloakErrorMetadata = TKeycloakErrorMetadata> extends BaseError<TMetadata> {
    /**
     * Keycloak-specific error code (optional, for additional context).
     *
     * Examples: `'INVALID_CLIENT_SECRET'`, `'INVALID_REALM'`, `'INVALID_AUTH_URL'`
     *
     * @returns The Keycloak error code from metadata, or `undefined` if not set
     *
     * @example
     * ```ts
     * const error = new KeycloakAuthError('Config failed', {
     *   code: 'KEYCLOAK_CONFIG_INVALID',
     *   keycloakCode: 'INVALID_CLIENT_SECRET'
     * });
     * console.log(error.KeycloakCode); // 'INVALID_CLIENT_SECRET'
     * ```
     */
    get KeycloakCode(): string | undefined;
    /**
     * Creates a new KeycloakAuthError.
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with code and cause chain
     * @throws {z.ZodError} If metadata fails validation against KEYCLOAK_ERROR_METADATA_SCHEMA
     *
     * @example
     * ```ts
     * const error = new KeycloakAuthError('Invalid configuration', {
     *   code: 'KEYCLOAK_CONFIG_INVALID',
     *   keycloakCode: 'INVALID_CLIENT_SECRET',
     *   cause: new Error('clientSecret is required for online mode')
     * });
     * ```
     */
    constructor(message: string, metadata?: TKeycloakErrorMetadata);
}
//# sourceMappingURL=keycloak.error.d.ts.map