@z_06/relay-temp-mail 1.0.1 → 2.0.0

package/dist/index.d.cts

@@ -2,13 +2,124 @@
  * TypeScript type definitions for the relay-temp-mail package.
  *
  * These interfaces define the core data structures used throughout the package,
- * ensuring type safety when interacting with the Firefox Relay and CF temp email APIs.
+ * including the provider abstraction layer for extensible email alias and mail
+ * access providers.
  */
 /**
- * Configuration interface for initializing the RelayClient.
+ * Abstract interface for alias email providers.
  *
- * This interface contains all required authentication tokens and API URLs
- * needed to communicate with both Firefox Relay and CloudFlare temp email services.
+ * An alias provider creates and manages email aliases that forward to a real
+ * email address. Different providers (Firefox Relay, SimpleLogin, DuckDuckGo
+ * Email Protection, etc.) can implement this interface.
+ */
+interface AliasProvider {
+    /**
+     * Lists all email aliases managed by this provider.
+     *
+     * @returns Promise resolving to an array of RelayAlias objects
+     */
+    listAliases(): Promise<RelayAlias[]>;
+    /**
+     * Creates a new email alias.
+     *
+     * @returns Promise resolving to the newly created RelayAlias
+     */
+    createAlias(): Promise<RelayAlias>;
+    /**
+     * Deletes an email alias by its ID.
+     *
+     * @param id - The unique identifier of the alias to delete
+     */
+    deleteAlias(id: number): Promise<void>;
+}
+/**
+ * Abstract interface for mail access providers.
+ *
+ * A mail provider retrieves raw emails from a mailbox via API. Different
+ * providers (CF Temp Mail, IMAP, etc.) can implement this interface.
+ */
+interface MailProvider {
+    /**
+     * Retrieves emails from the mail provider.
+     *
+     * @param limit - Maximum number of emails to return
+     * @param offset - Pagination offset (0-indexed)
+     * @returns Promise resolving to an array of Email objects
+     */
+    getMails(limit: number, offset: number): Promise<Email[]>;
+}
+/**
+ * Configuration for the Firefox Relay alias provider.
+ */
+interface FirefoxRelayConfig {
+    /** Discriminant identifying this provider type */
+    type: 'firefox-relay';
+    /** CSRF token for Firefox Relay API authentication */
+    csrfToken: string;
+    /** Session ID for Firefox Relay API authentication */
+    sessionId: string;
+}
+/**
+ * Union type for all supported alias provider configurations.
+ *
+ * Currently only supports 'firefox-relay'. More providers (simplelogin,
+ * duckduckgo, etc.) can be added here in the future.
+ */
+type AliasProviderConfig = FirefoxRelayConfig;
+/**
+ * Configuration for the CloudFlare temp mail provider.
+ */
+interface CFTempMailConfig {
+    /** Discriminant identifying this provider type */
+    type: 'cf-temp-mail';
+    /** Base URL for the CloudFlare temp email API */
+    apiUrl: string;
+    /** Bearer token for CloudFlare temp email API authentication */
+    token: string;
+}
+/**
+ * Union type for all supported mail provider configurations.
+ *
+ * Currently only supports 'cf-temp-mail'. More providers (imap, pop3, etc.)
+ * can be added here in the future.
+ */
+type MailProviderConfig = CFTempMailConfig;
+/**
+ * Configuration interface for initializing the TempMailClient.
+ *
+ * Uses a provider-based architecture where alias and mail providers are
+ * specified by their type and provider-specific configuration. This allows
+ * the library to grow to support additional providers without breaking changes.
+ *
+ * @example
+ * ```typescript
+ * const client = new TempMailClient({
+ *   aliasProvider: {
+ *     type: 'firefox-relay',
+ *     csrfToken: '...',
+ *     sessionId: '...',
+ *   },
+ *   mailProvider: {
+ *     type: 'cf-temp-mail',
+ *     apiUrl: 'https://...',
+ *     token: '...',
+ *   },
+ *   timeout: 30000,
+ * });
+ * ```
+ */
+interface TempMailConfig {
+    /** Alias email provider configuration */
+    aliasProvider: AliasProviderConfig;
+    /** Mail access provider configuration */
+    mailProvider: MailProviderConfig;
+    /** Optional timeout for HTTP requests in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * @deprecated Use TempMailConfig instead. Will be removed in the next major version.
+ *
+ * Legacy configuration interface kept for backward compatibility.
  */
 interface RelayConfig {
     /** CSRF token for Firefox Relay API authentication */
@@ -23,13 +134,13 @@ interface RelayConfig {
     timeout?: number;
 }
 /**
- * Represents a Firefox Relay email alias.
+ * Represents an email alias.
  *
- * This interface maps to the JSON structure returned by the Firefox Relay API
+ * This interface maps to the JSON structure returned by alias providers
  * when listing or creating email aliases.
  *
- * Note: Property names use camelCase even though the API returns snake_case.
- * The package will handle the conversion internally.
+ * Note: Property names use camelCase even though the underlying API may
+ * return snake_case. The provider implementation handles the conversion.
  */
 interface RelayAlias {
     /** Unique identifier for the alias */
@@ -70,10 +181,10 @@ interface RelayAlias {
     usedOn?: string | null;
 }
 /**
- * Email object returned by the CloudFlare temp email API.
+ * Email object returned by mail providers.
  *
- * This interface represents the raw email data as returned from the CF API,
- * including the complete MIME message in the `raw` field.
+ * This interface represents the raw email data as returned from a mail
+ * provider, including the complete MIME message in the `raw` field.
  */
 interface Email {
     /** Unique identifier for the email */
@@ -95,17 +206,17 @@ interface Email {
  * Email object with parsed alias information.
  *
  * This interface extends the base Email interface and adds the parsed
- * Firefox Relay alias information extracted from the MIME content.
+ * alias information extracted from the MIME content.
  */
 interface ParsedEmail extends Email {
     /**
-     * The Firefox Relay alias that this email was sent to.
+     * The alias that this email was sent to.
      * This is extracted from the `raw` MIME content by parsing the `To:` header.
      */
     relayAlias?: string;
 }
 /**
- * Query options for listing Firefox Relay aliases.
+ * Query options for listing aliases.
  */
 interface ListAliasesOptions {
     /** Maximum number of aliases to return */
@@ -114,7 +225,7 @@ interface ListAliasesOptions {
     offset?: number;
 }
 /**
- * Query options for retrieving emails from the CF temp email API.
+ * Query options for retrieving emails from a mail provider.
  */
 interface GetEmailsOptions {
     /** Maximum number of emails to return */
@@ -237,81 +348,116 @@ declare class RateLimitError extends RelayTempMailError {
     constructor(message: string, response?: any);
 }
 
+declare class TempMailClient {
+    private readonly aliasProvider;
+    private readonly mailProvider;
+    private readonly parser;
+    constructor(config: TempMailConfig);
+    listAliases(): Promise<RelayAlias[]>;
+    createAlias(): Promise<RelayAlias>;
+    deleteAlias(id: number): Promise<void>;
+    getEmails(aliasAddress?: string, options?: GetEmailsOptions): Promise<ParsedEmail[]>;
+}
+/** @deprecated Use TempMailClient instead */
+declare const RelayClient: typeof TempMailClient;
+
 /**
- * Main client for the relay-temp-mail package.
+ * HTTP client utilities for the relay-temp-mail package.
  *
- * This module provides the RelayClient class which integrates all components
- * (CF API, Relay API, Parser) into a unified interface.
+ * This module provides a configurable HTTP client with timeout support,
+ * automatic retry logic, and proper error classification for API responses.
  */
-
 /**
- * Main client for interacting with Firefox Relay and CloudFlare temp email services.
- *
- * RelayClient integrates all components to provide a unified interface for:
- * - Managing Firefox Relay email aliases
- * - Retrieving and parsing emails from CloudFlare temp email API
- *
- * @example
- * ```typescript
- * const client = new RelayClient({
- *   csrfToken: '...',
- *   sessionId: '...',
- *   cfApiUrl: 'https://...',
- *   cfToken: '...',
- *   timeout: 30000
- * });
+ * Options for individual HTTP requests.
+ */
+interface RequestOptions {
+    /** Custom headers to include in the request */
+    headers?: Record<string, string>;
+    /** Request body (will be JSON serialized) */
+    body?: unknown;
+    /** Request timeout in milliseconds (overrides client default) */
+    timeout?: number;
+    /** Number of retries on failure (overrides client default) */
+    retries?: number;
+}
+/**
+ * HTTP client for making requests to the relay-temp-mail API.
  *
- * const aliases = await client.listAliases();
- * const emails = await client.getEmails('alias@mozmail.com', { limit: 10 });
- * ```
+ * Provides a configurable base URL with timeout, retry, and automatic
+ * JSON parsing capabilities.
  */
-declare class RelayClient {
-    private readonly relayApi;
-    private readonly cfApi;
-    private readonly parser;
+declare class HttpClient$1 {
+    private baseUrl;
+    private defaultTimeout;
+    private defaultRetries;
     /**
-     * Creates a new RelayClient instance.
+     * Creates a new HttpClient instance.
      *
-     * @param config - Configuration object containing authentication tokens and API URLs
+     * @param baseUrl - Base URL for all requests (e.g., 'https://api.example.com')
+     * @param defaultTimeout - Default timeout in milliseconds (default: 30000)
+     * @param defaultRetries - Default number of retries on failure (default: 0)
      */
-    constructor(config: RelayConfig);
+    constructor(baseUrl: string, defaultTimeout?: number, defaultRetries?: number);
     /**
-     * Lists all Firefox Relay email aliases.
+     * Makes an HTTP request to the specified path.
      *
-     * @returns Promise resolving to an array of RelayAlias objects
-     * @throws AuthError if authentication fails
-     * @throws NetworkError if there's a network problem
+     * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+     * @param path - API path (will be appended to baseUrl)
+     * @param options - Optional request configuration
+     * @returns Promise resolving to the parsed JSON response
      */
-    listAliases(): Promise<RelayAlias[]>;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
     /**
-     * Creates a new Firefox Relay email alias.
-     *
-     * @returns Promise resolving to the newly created RelayAlias
-     * @throws AuthError if authentication fails
-     * @throws NetworkError if there's a network problem
+     * Executes the actual HTTP request with timeout support.
      */
-    createAlias(): Promise<RelayAlias>;
+    private executeRequest;
     /**
-     * Deletes a Firefox Relay email alias.
-     *
-     * @param id - The ID of the alias to delete
-     * @throws AuthError if authentication fails
-     * @throws NotFoundError if the alias doesn't exist
-     * @throws NetworkError if there's a network problem
+     * Handles the HTTP response, parsing JSON and checking for errors.
      */
-    deleteAlias(id: number): Promise<void>;
+    private handleResponse;
     /**
-     * Retrieves and parses emails from the CloudFlare temp email API.
-     *
-     * If aliasAddress is provided, only emails sent to that address are returned.
-     *
-     * @param aliasAddress - Optional email address to filter by
-     * @param options - Query options for pagination
-     * @returns Promise resolving to an array of ParsedEmail objects
-     * @throws AuthError if authentication fails
-     * @throws NetworkError if there's a network problem
+     * Classifies an error based on the error type and HTTP response.
      */
-    getEmails(aliasAddress?: string, options?: GetEmailsOptions): Promise<ParsedEmail[]>;
+    private classifyError;
+    /**
+     * Determines if a request should be retried based on the error.
+     */
+    private shouldRetry;
+    /**
+     * Sleep for a specified duration.
+     */
+    private sleep;
+}
+
+declare class FirefoxRelayProvider implements AliasProvider {
+    private csrfToken;
+    private sessionId;
+    private httpClient;
+    constructor(csrfToken: string, sessionId: string, httpClient?: HttpClient$1);
+    private getAuthHeaders;
+    listAliases(): Promise<RelayAlias[]>;
+    createAlias(): Promise<RelayAlias>;
+    deleteAlias(id: number): Promise<void>;
+    private mapAliasResponse;
+}
+/** @deprecated Use FirefoxRelayProvider instead */
+declare const RelayAPIClient: typeof FirefoxRelayProvider;
+
+declare class CFTempMailProvider implements MailProvider {
+    private readonly apiUrl;
+    private readonly token;
+    private readonly httpClient;
+    constructor(apiUrl: string, token: string, httpClient?: HttpClient);
+    getMails(limit?: number, offset?: number): Promise<Email[]>;
+    private mapCFResponse;
+    private handleError;
+}
+/** @deprecated Use CFTempMailProvider instead */
+declare const CFEmailClient: typeof CFTempMailProvider;
+interface HttpClient {
+    get(url: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<unknown>;
 }
 
-export { AuthError, type CFMailsResponse, type CreateAliasResponse, type Email, type GetEmailsOptions, type ListAliasesOptions, NetworkError, NotFoundError, ParseError, type ParsedEmail, RateLimitError, type RelayAddressesResponse, type RelayAlias, RelayClient, type RelayConfig, RelayTempMailError };
+export { type AliasProvider, type AliasProviderConfig, AuthError, CFEmailClient, type CFMailsResponse, type CFTempMailConfig, CFTempMailProvider, type CreateAliasResponse, type Email, type FirefoxRelayConfig, FirefoxRelayProvider, type GetEmailsOptions, type ListAliasesOptions, type MailProvider, type MailProviderConfig, NetworkError, NotFoundError, ParseError, type ParsedEmail, RateLimitError, RelayAPIClient, type RelayAddressesResponse, type RelayAlias, RelayClient, type RelayConfig, RelayTempMailError, TempMailClient, type TempMailConfig };