@z_06/relay-temp-mail 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+/**
+ * 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.
+ */
+/**
+ * Configuration interface for initializing the RelayClient.
+ *
+ * This interface contains all required authentication tokens and API URLs
+ * needed to communicate with both Firefox Relay and CloudFlare temp email services.
+ */
+interface RelayConfig {
+    /** CSRF token for Firefox Relay API authentication */
+    csrfToken: string;
+    /** Session ID for Firefox Relay API authentication */
+    sessionId: string;
+    /** Base URL for the CloudFlare temp email API */
+    cfApiUrl: string;
+    /** Bearer token for CloudFlare temp email API authentication */
+    cfToken: string;
+    /** Optional timeout for HTTP requests in milliseconds */
+    timeout?: number;
+}
+/**
+ * Represents a Firefox Relay email alias.
+ *
+ * This interface maps to the JSON structure returned by the Firefox Relay API
+ * 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.
+ */
+interface RelayAlias {
+    /** Unique identifier for the alias */
+    id: number;
+    /** The alias username (part before @) */
+    address: string;
+    /** Complete email address including domain */
+    fullAddress: string;
+    /** Whether the alias is currently enabled for receiving emails */
+    enabled: boolean;
+    /** ISO timestamp when the alias was created */
+    createdAt: string;
+    /** Domain identifier (2 for mozmail.com) */
+    domain: number;
+    /** Type of alias generation (e.g., "random") */
+    maskType: string;
+    /** Optional description for the alias */
+    description?: string;
+    /** Number of emails forwarded through this alias */
+    numForwarded?: number;
+    /** Number of emails blocked by this alias */
+    numBlocked?: number;
+    /** Optional timestamp when alias was last modified */
+    lastModifiedAt?: string;
+    /** Optional timestamp when alias was last used */
+    lastUsedAt?: string | null;
+    /** Number of level one trackers blocked */
+    numLevelOneTrackersBlocked?: number;
+    /** Number of replies sent from this alias */
+    numReplied?: number;
+    /** Number of spam emails marked */
+    numSpam?: number;
+    /** Whether the alias blocks list emails */
+    blockListEmails?: boolean;
+    /** Service the alias was generated for (optional) */
+    generatedFor?: string;
+    /** Where the alias is used (optional) */
+    usedOn?: string | null;
+}
+/**
+ * Email object returned by the CloudFlare temp email API.
+ *
+ * This interface represents the raw email data as returned from the CF API,
+ * including the complete MIME message in the `raw` field.
+ */
+interface Email {
+    /** Unique identifier for the email */
+    id: number;
+    /** Original message ID from the email headers */
+    messageId: string;
+    /** Source email address that sent this email */
+    source: string;
+    /** Destination email address that received this email */
+    address: string;
+    /** Raw MIME content of the email */
+    raw: string;
+    /** Metadata associated with the email (can be any type) */
+    metadata: any | null;
+    /** ISO timestamp when the email was created/received */
+    createdAt: string;
+}
+/**
+ * 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.
+ */
+interface ParsedEmail extends Email {
+    /**
+     * The Firefox Relay 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.
+ */
+interface ListAliasesOptions {
+    /** Maximum number of aliases to return */
+    limit?: number;
+    /** Offset for pagination (0-indexed) */
+    offset?: number;
+}
+/**
+ * Query options for retrieving emails from the CF temp email API.
+ */
+interface GetEmailsOptions {
+    /** Maximum number of emails to return */
+    limit?: number;
+    /** Offset for pagination (0-indexed) */
+    offset?: number;
+}
+/**
+ * Response structure from the CloudFlare temp email API for listing emails.
+ *
+ * This matches the JSON structure returned by the `/api/mails` endpoint.
+ */
+interface CFMailsResponse {
+    /** Array of email objects */
+    results: Email[];
+    /** Total number of emails available (for pagination) */
+    count: number;
+}
+/**
+ * Response type for listing Firefox Relay aliases.
+ *
+ * The Firefox Relay API returns an array of alias objects directly.
+ */
+type RelayAddressesResponse = RelayAlias[];
+/**
+ * Response type for creating a new Firefox Relay alias.
+ *
+ * The Firefox Relay API returns a single alias object when creating a new alias.
+ */
+type CreateAliasResponse = RelayAlias;
+
+/**
+ * Custom error classes for the relay-temp-mail package.
+ *
+ * These errors provide structured error information including error codes,
+ * HTTP status codes, and response data for better error handling.
+ */
+/**
+ * Base error class for all relay-temp-mail errors.
+ *
+ * Extends the built-in Error class with additional context about the error,
+ * including an error code for programmatic error handling and optional
+ * response data from the API.
+ */
+declare class RelayTempMailError extends Error {
+    /**
+     * Machine-readable error code for programmatic error handling.
+     * Examples: 'NETWORK_ERROR', 'AUTH_ERROR', 'NOT_FOUND'
+     */
+    code: string;
+    /**
+     * HTTP status code associated with this error, if applicable.
+     */
+    statusCode?: number;
+    /**
+     * Raw response data from the API, if available.
+     */
+    response?: any;
+    /**
+     * Creates a new RelayTempMailError instance.
+     *
+     * @param message - Human-readable error message describing the error.
+     * @param code - Machine-readable error code (e.g., 'UNKNOWN_ERROR').
+     * @param statusCode - Optional HTTP status code associated with the error.
+     * @param response - Optional raw response data from the API.
+     */
+    constructor(message: string, code: string, statusCode?: number, response?: any);
+}
+/**
+ * Error for network-related failures.
+ *
+ * Thrown when there is a problem establishing or maintaining a network
+ * connection, such as DNS resolution failures, connection timeouts,
+ * or network unreachability.
+ */
+declare class NetworkError extends RelayTempMailError {
+    code: "NETWORK_ERROR";
+    constructor(message: string, response?: any);
+}
+/**
+ * Error for authentication and authorization failures.
+ *
+ * Thrown when API requests fail due to invalid or missing credentials
+ * (401) or when the authenticated user lacks permission for the
+ * requested operation (403).
+ */
+declare class AuthError extends RelayTempMailError {
+    code: "AUTH_ERROR";
+    constructor(message: string, statusCode?: number, response?: any);
+}
+/**
+ * Error for resource not found errors.
+ *
+ * Thrown when the requested resource does not exist (404 response),
+ * such as when trying to access a non-existent alias or email.
+ */
+declare class NotFoundError extends RelayTempMailError {
+    code: "NOT_FOUND";
+    constructor(message: string, response?: any);
+}
+/**
+ * Error for MIME message parsing failures.
+ *
+ * Thrown when there is an error parsing email MIME content,
+ * such as malformed headers or invalid message structure.
+ */
+declare class ParseError extends RelayTempMailError {
+    code: "PARSE_ERROR";
+    constructor(message: string, response?: any);
+}
+/**
+ * Error for rate limiting responses.
+ *
+ * Thrown when the API rate limit has been exceeded (429 response).
+ * The client should wait and retry the request after the indicated
+ * cooldown period.
+ */
+declare class RateLimitError extends RelayTempMailError {
+    code: "RATE_LIMIT_ERROR";
+    constructor(message: string, response?: any);
+}
+
+/**
+ * Main client 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.
+ */
+
+/**
+ * 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
+ * });
+ *
+ * const aliases = await client.listAliases();
+ * const emails = await client.getEmails('alias@mozmail.com', { limit: 10 });
+ * ```
+ */
+declare class RelayClient {
+    private readonly relayApi;
+    private readonly cfApi;
+    private readonly parser;
+    /**
+     * Creates a new RelayClient instance.
+     *
+     * @param config - Configuration object containing authentication tokens and API URLs
+     */
+    constructor(config: RelayConfig);
+    /**
+     * Lists all Firefox Relay email aliases.
+     *
+     * @returns Promise resolving to an array of RelayAlias objects
+     * @throws AuthError if authentication fails
+     * @throws NetworkError if there's a network problem
+     */
+    listAliases(): Promise<RelayAlias[]>;
+    /**
+     * 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
+     */
+    createAlias(): Promise<RelayAlias>;
+    /**
+     * 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
+     */
+    deleteAlias(id: number): Promise<void>;
+    /**
+     * 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
+     */
+    getEmails(aliasAddress?: string, options?: GetEmailsOptions): Promise<ParsedEmail[]>;
+}
+
+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 };