/**
 * Firefox Relay API Client Module
 *
 * Provides a comprehensive TypeScript client for the Firefox Relay API,
 * with proper rate limiting, retry logic, error handling, and caching.
 *
 * Follows golden-standard programming practices for maximal reliability
 * and security.
 *
 * API Documentation References:
 * - https://docs.rs/ffrelay-api/latest/ffrelay_api/
 * - https://github.com/leo-proger/firefox-relay-api
 * - https://relay.firefox.com/api/v1/runtime_data
 */
import { z } from 'zod/v4';
import { Configuration } from '../config';
/**
 * Base error for Firefox Relay API operations
 */
export declare class FirefoxRelayError extends Error {
    readonly statusCode?: number | undefined;
    readonly responseData?: unknown | undefined;
    readonly cause?: Error | undefined;
    constructor(message: string, statusCode?: number | undefined, responseData?: unknown | undefined, cause?: Error | undefined);
}
/**
 * Authentication error
 */
export declare class AuthError extends FirefoxRelayError {
    constructor(message?: string);
}
/**
 * Rate limit error
 */
export declare class RateLimitError extends FirefoxRelayError {
    readonly retryAfter?: number | undefined;
    constructor(message?: string, retryAfter?: number | undefined);
}
/**
 * Validation error
 */
export declare class ValidationError extends FirefoxRelayError {
    readonly fieldErrors?: Record<string, string[]> | undefined;
    constructor(message: string, fieldErrors?: Record<string, string[]> | undefined);
}
/**
 * Not found error
 */
export declare class ResourceNotFoundError extends FirefoxRelayError {
    constructor(resourceType: string, identifier: string | number);
}
/**
 * Server error
 */
export declare class ServerError extends FirefoxRelayError {
    constructor(message?: string);
}
/**
 * Request options for API calls
 */
export interface RequestOptions {
    /**
     * Custom timeout in milliseconds
     */
    timeout?: number;
    /**
     * Number of retries on failure
     */
    retries?: number;
    /**
     * Custom headers
     */
    headers?: Record<string, string>;
    /**
     * Whether to skip rate limiting
     */
    skipRateLimit?: boolean;
}
/**
 * Rate limit status
 */
export interface RateLimitStatus {
    remaining: number;
    resetAt: Date;
    limited: boolean;
}
/**
 * Firefox Relay API Client
 *
 * Provides a high-level interface for interacting with the Firefox Relay API
 * with automatic authentication, rate limiting, and error handling.
 */
export declare class FirefoxRelayClient {
    private apiKey;
    private baseUrl;
    private config;
    private rateLimitState;
    /**
     * Create a new Firefox Relay API client
     *
     * @param apiKey - Firefox Relay API key
     * @param config - Configuration instance
     * @param baseUrl - Custom base URL for testing
     */
    constructor(apiKey: string, config?: Configuration, baseUrl?: string);
    /**
     * Get the current rate limit status
     */
    getRateLimitStatus(): RateLimitStatus;
    /**
     * Check and enforce rate limiting
     */
    private enforceRateLimit;
    /**
     * Make an HTTP request to the Firefox Relay API
     */
    private request;
    /**
     * Create a new random email relay address
     *
     * @param options - Creation options
     * @returns The created relay address
     */
    createRelayAddress(options?: {
        description?: string;
        enabled?: boolean;
        generatedFor?: string;
        blockListEmails?: boolean;
        usedOn?: string;
    }): Promise<{
        id: number;
        address: string;
        domain: string;
        fullAddress: string;
        enabled: boolean;
        description: string;
        generatedFor: string;
        blockListEmails: boolean;
        usedOn: string | null;
        maskType: string;
        createdAt: string;
        lastModifiedAt: string;
    }>;
    /**
     * List all relay addresses
     *
     * @returns Array of relay addresses
     */
    listRelayAddresses(): Promise<Array<{
        id: number;
        address: string;
        domain: string;
        fullAddress: string;
        enabled: boolean;
        description: string;
        generatedFor: string;
        blockListEmails: boolean;
        usedOn: string | null;
        maskType: string;
        createdAt: string;
        lastModifiedAt: string;
        lastUsedAt: string | null;
        numForwarded: number;
        numBlocked: number;
        numReplied: number;
        numSpam: number;
    }>>;
    /**
     * Get a specific relay address by ID
     *
     * @param id - Relay address ID
     * @returns The relay address
     */
    getRelayAddress(id: number): Promise<{
        id: number;
        address: string;
        domain: string;
        fullAddress: string;
        enabled: boolean;
        description: string;
        generatedFor: string;
        blockListEmails: boolean;
        usedOn: string | null;
        maskType: string;
        createdAt: string;
        lastModifiedAt: string;
        lastUsedAt: string | null;
        numForwarded: number;
        numBlocked: number;
        numReplied: number;
        numSpam: number;
    }>;
    /**
     * Update a relay address
     *
     * @param id - Relay address ID
     * @param updates - Fields to update
     * @returns The updated relay address
     */
    updateRelayAddress(id: number, updates: {
        description?: string;
        enabled?: boolean;
        blockListEmails?: boolean;
        usedOn?: string;
    }): Promise<{
        id: number;
        address: string;
        domain: string;
        fullAddress: string;
        enabled: boolean;
        description: string;
        generatedFor: string;
        blockListEmails: boolean;
        usedOn: string | null;
        maskType: string;
        createdAt: string;
        lastModifiedAt: string;
        lastUsedAt: string | null;
        numForwarded: number;
        numBlocked: number;
        numReplied: number;
        numSpam: number;
    }>;
    /**
     * Delete a relay address
     *
     * @param id - Relay address ID
     */
    deleteRelayAddress(id: number): Promise<void>;
    /**
     * Validate that an email address belongs to Firefox Relay
     *
     * @param email - Email address to validate
     * @returns True if the email is a Firefox Relay address
     */
    validateRelayAddress(email: string): boolean;
    /**
     * Get user profile information
     *
     * Note: This endpoint may require a premium account
     */
    getProfile(): Promise<{
        id: number;
        email: string;
        createdAt: string;
        subscription?: {
            type: string;
            status: string;
            startedAt: string;
            expiresAt: string;
        };
        usage?: {
            numRelayAddresses: number;
            numEmailsForwarded: number;
            numEmailsBlocked: number;
        };
    }>;
    /**
     * Get runtime data (public endpoint, no authentication required)
     *
     * This endpoint provides general information about Firefox Relay
     */
    getRuntimeData(): Promise<{
        version: string;
        featureFlags: Record<string, boolean>;
        relayCounts: {
            totalRelays: number;
            activeRelays: number;
        };
    }>;
    /**
     * Get API usage statistics
     */
    getApiStats(): {
        totalRequests: number;
        rateLimit: RateLimitStatus;
        lastRequestTime: Date | null;
    };
    /**
     * Reset API rate limit state
     */
    resetRateLimitState(): void;
    /**
     * Get the API key (redacted)
     */
    getApiKey(): string;
    /**
     * Check if the API key is valid by making a test request
     */
    validateApiKey(): Promise<boolean>;
}
/**
 * Get the singleton Firefox Relay client instance
 */
export declare function getClient(config?: Configuration): FirefoxRelayClient;
/**
 * Reset the singleton instance (useful for testing)
 */
export declare function resetClient(): void;
/**
 * Schema for validating relay address creation requests
 */
export declare const CreateRelayAddressSchema: z.ZodObject<{
    description: z.ZodOptional<z.ZodString>;
    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
    generatedFor: z.ZodOptional<z.ZodString>;
    blockListEmails: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
    usedOn: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
/**
 * Schema for validating relay address update requests
 */
export declare const UpdateRelayAddressSchema: z.ZodObject<{
    description: z.ZodOptional<z.ZodString>;
    enabled: z.ZodOptional<z.ZodBoolean>;
    blockListEmails: z.ZodOptional<z.ZodBoolean>;
    usedOn: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export default FirefoxRelayClient;
//# sourceMappingURL=index.d.ts.map