@z_06/relay-temp-mail 1.0.0

package/dist/index.cjs

@@ -0,0 +1,613 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthError: () => AuthError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  ParseError: () => ParseError,
+  RateLimitError: () => RateLimitError,
+  RelayClient: () => RelayClient,
+  RelayTempMailError: () => RelayTempMailError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var RelayTempMailError = class extends Error {
+  /**
+   * 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, code, statusCode, response) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = statusCode;
+    this.response = response;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var NetworkError = class extends RelayTempMailError {
+  constructor(message, response) {
+    super(message, "NETWORK_ERROR", void 0, response);
+    this.code = "NETWORK_ERROR";
+  }
+};
+var AuthError = class extends RelayTempMailError {
+  constructor(message, statusCode, response) {
+    super(message, "AUTH_ERROR", statusCode, response);
+    this.code = "AUTH_ERROR";
+  }
+};
+var NotFoundError = class extends RelayTempMailError {
+  constructor(message, response) {
+    super(message, "NOT_FOUND", 404, response);
+    this.code = "NOT_FOUND";
+  }
+};
+var ParseError = class extends RelayTempMailError {
+  constructor(message, response) {
+    super(message, "PARSE_ERROR", void 0, response);
+    this.code = "PARSE_ERROR";
+  }
+};
+var RateLimitError = class extends RelayTempMailError {
+  constructor(message, response) {
+    super(message, "RATE_LIMIT_ERROR", 429, response);
+    this.code = "RATE_LIMIT_ERROR";
+  }
+};
+
+// src/cf-api.ts
+var DefaultHttpClient = class {
+  async get(url, options) {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: options?.headers
+    });
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw new RelayTempMailError(
+        `HTTP ${response.status}: ${errorBody}`,
+        "HTTP_ERROR",
+        response.status,
+        errorBody
+      );
+    }
+    return response.json();
+  }
+};
+var CFEmailClient = class {
+  /**
+   * Creates a new CFEmailClient instance.
+   *
+   * @param apiUrl - Base URL for the CF temp email API
+   * @param token - Bearer token for authentication
+   * @param httpClient - Optional HTTP client (defaults to fetch-based implementation)
+   */
+  constructor(apiUrl, token, httpClient) {
+    this.apiUrl = apiUrl;
+    this.token = token;
+    this.httpClient = httpClient ?? new DefaultHttpClient();
+  }
+  /**
+   * Retrieves emails from the CF temp email API.
+   *
+   * @param limit - Maximum number of emails to return (default: 20)
+   * @param offset - Pagination offset (default: 0)
+   * @returns Promise resolving to an array of Email objects
+   * @throws AuthError if authentication fails
+   * @throws NetworkError if there's a network problem
+   * @throws NotFoundError if the endpoint doesn't exist
+   * @throws RateLimitError if rate limited
+   */
+  async getMails(limit = 20, offset = 0) {
+    const url = new URL(`${this.apiUrl}/api/mails`);
+    url.searchParams.set("limit", String(limit));
+    url.searchParams.set("offset", String(offset));
+    const headers = {
+      "Authorization": `Bearer ${this.token}`
+    };
+    try {
+      const response = await this.httpClient.get(url.toString(), { headers });
+      return this.mapCFResponse(response);
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Maps the raw CF API response to the Email interface.
+   *
+   * Converts snake_case property names to camelCase.
+   *
+   * @param response - Raw response from CF API
+   * @returns Array of Email objects
+   */
+  mapCFResponse(response) {
+    return response.results.map((item) => ({
+      id: item.id,
+      messageId: item.message_id,
+      source: item.source,
+      address: item.address,
+      raw: item.raw,
+      metadata: item.metadata,
+      createdAt: item.created_at
+    }));
+  }
+  /**
+   * Handles errors from HTTP requests.
+   *
+   * Maps HTTP errors to appropriate error classes.
+   *
+   * @param error - The caught error
+   * @returns Appropriate RelayTempMailError subclass
+   */
+  handleError(error) {
+    if (error instanceof RelayTempMailError) {
+      const statusCode = error.statusCode;
+      if (statusCode === 401 || statusCode === 403) {
+        return new AuthError(error.message, statusCode, error.response);
+      }
+      if (statusCode === 404) {
+        return new NotFoundError(error.message, error.response);
+      }
+      if (statusCode === 429) {
+        return new RateLimitError(error.message, error.response);
+      }
+      return error;
+    }
+    if (error instanceof TypeError && error.message.includes("fetch")) {
+      return new NetworkError(error.message);
+    }
+    if (error instanceof Error) {
+      return new NetworkError(error.message);
+    }
+    return new RelayTempMailError(
+      "Unknown error occurred",
+      "UNKNOWN_ERROR",
+      void 0,
+      error
+    );
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  /**
+   * Creates a new HttpClient instance.
+   *
+   * @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(baseUrl, defaultTimeout = 3e4, defaultRetries = 0) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.defaultTimeout = defaultTimeout;
+    this.defaultRetries = defaultRetries;
+  }
+  /**
+   * Makes an HTTP request to the specified path.
+   *
+   * @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
+   */
+  async request(method, path, options = {}) {
+    const timeout = options.timeout ?? this.defaultTimeout;
+    const retries = options.retries ?? this.defaultRetries;
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const response = await this.executeRequest(method, path, options, timeout);
+        return await this.handleResponse(response);
+      } catch (error) {
+        lastError = error;
+        if (attempt < retries && this.shouldRetry(error)) {
+          const delay = 1e3 * Math.pow(2, attempt);
+          await this.sleep(delay);
+          continue;
+        }
+        if (error instanceof RelayTempMailError) {
+          throw error;
+        }
+        throw this.classifyError(error);
+      }
+    }
+    throw lastError || new NetworkError("Request failed");
+  }
+  /**
+   * Executes the actual HTTP request with timeout support.
+   */
+  async executeRequest(method, path, options, timeout) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const fetchOptions = {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...options.headers
+        },
+        signal: controller.signal
+      };
+      if (options.body !== void 0) {
+        fetchOptions.body = JSON.stringify(options.body);
+      }
+      const response = await fetch(url, fetchOptions);
+      return response;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Handles the HTTP response, parsing JSON and checking for errors.
+   */
+  async handleResponse(response) {
+    if (!response.ok) {
+      throw this.classifyError(new Error(`HTTP ${response.status}`), response);
+    }
+    const text = await response.text();
+    if (!text) {
+      return {};
+    }
+    return JSON.parse(text);
+  }
+  /**
+   * Classifies an error based on the error type and HTTP response.
+   */
+  classifyError(error, response) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return new NetworkError("Request timed out");
+    }
+    if (error instanceof TypeError && error.message.includes("fetch")) {
+      return new NetworkError("Network request failed");
+    }
+    if (error instanceof Error && error.message.includes("Failed to fetch")) {
+      return new NetworkError("Network request failed");
+    }
+    if (response) {
+      const status = response.status;
+      if (status === 401 || status === 403) {
+        return new AuthError(
+          `Authentication failed: ${response.statusText}`,
+          status
+        );
+      }
+      if (status === 404) {
+        return new NotFoundError(`Resource not found: ${response.statusText}`);
+      }
+      if (status === 429) {
+        return new RateLimitError(
+          `Rate limit exceeded: ${response.statusText}`
+        );
+      }
+      if (status >= 500) {
+        return new NetworkError(
+          `Server error: ${response.statusText}`,
+          status
+        );
+      }
+    }
+    if (error instanceof Error) {
+      return new RelayTempMailError(
+        error.message,
+        "REQUEST_ERROR",
+        response?.status
+      );
+    }
+    return new RelayTempMailError("Unknown error occurred", "UNKNOWN_ERROR");
+  }
+  /**
+   * Determines if a request should be retried based on the error.
+   */
+  shouldRetry(error) {
+    if (error instanceof NetworkError) {
+      return true;
+    }
+    if (error instanceof RelayTempMailError && error.statusCode) {
+      return error.statusCode >= 500;
+    }
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        return true;
+      }
+      if (error instanceof TypeError && error.message.includes("fetch")) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Sleep for a specified duration.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/parser.ts
+var MOZMAIL_PATTERN = /[a-zA-Z0-9]+@mozmail\.com/g;
+var ENCODED_WORD_PATTERN = /=\?([^?]+)\?([BbQq])\?([^?]*)\?=/g;
+var EmailParser = class {
+  parseEmail(raw) {
+    const headers = this.parseHeaders(raw);
+    const toHeader = headers.get("to") || "";
+    const fromHeader = headers.get("from") || "";
+    const messageIdHeader = headers.get("message-id") || "";
+    const relayAlias = this.extractRelayAlias(raw);
+    return {
+      id: 0,
+      messageId: this.extractMessageId(messageIdHeader),
+      source: this.extractEmailAddress(fromHeader),
+      address: this.extractEmailAddress(toHeader),
+      raw,
+      metadata: null,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      relayAlias: relayAlias || void 0
+    };
+  }
+  extractRelayAlias(raw) {
+    try {
+      const headers = this.parseHeaders(raw);
+      const toHeader = headers.get("to");
+      if (!toHeader) return null;
+      const decodedTo = this.decodeHeader(toHeader);
+      const matches = decodedTo.match(MOZMAIL_PATTERN);
+      return matches && matches.length > 0 ? matches[0].toLowerCase() : null;
+    } catch {
+      return null;
+    }
+  }
+  parseHeaders(raw) {
+    const headers = /* @__PURE__ */ new Map();
+    const headerEnd = raw.indexOf("\r\n\r\n");
+    const headerSection = headerEnd === -1 ? raw : raw.substring(0, headerEnd);
+    const lines = headerSection.split(/\r?\n/);
+    let currentHeader = null;
+    let currentValue = "";
+    for (const line of lines) {
+      if (/^\s/.test(line)) {
+        if (currentHeader) currentValue += " " + line.trim();
+      } else {
+        if (currentHeader) headers.set(currentHeader, currentValue);
+        const colonIndex = line.indexOf(":");
+        if (colonIndex > 0) {
+          currentHeader = line.substring(0, colonIndex).toLowerCase().trim();
+          currentValue = line.substring(colonIndex + 1).trim();
+        } else {
+          currentHeader = null;
+          currentValue = "";
+        }
+      }
+    }
+    if (currentHeader) headers.set(currentHeader, currentValue);
+    return headers;
+  }
+  decodeHeader(value) {
+    return value.replace(ENCODED_WORD_PATTERN, (_, charset, encoding, encoded) => {
+      try {
+        if (encoding.toUpperCase() === "Q") {
+          return this.decodeQuotedPrintable(encoded);
+        } else if (encoding.toUpperCase() === "B") {
+          return this.decodeBase64(encoded);
+        }
+        return encoded;
+      } catch {
+        return encoded;
+      }
+    });
+  }
+  decodeQuotedPrintable(encoded) {
+    let decoded = encoded.replace(/_/g, " ");
+    decoded = decoded.replace(
+      /=([0-9A-Fa-f]{2})/g,
+      (_, hex) => String.fromCharCode(parseInt(hex, 16))
+    );
+    return decoded;
+  }
+  decodeBase64(encoded) {
+    return Buffer.from(encoded, "base64").toString("utf-8");
+  }
+  extractEmailAddress(headerValue) {
+    if (!headerValue) return "";
+    const decoded = this.decodeHeader(headerValue);
+    const bracketMatch = decoded.match(/<([^>]+)>/);
+    if (bracketMatch) return bracketMatch[1].trim().toLowerCase();
+    const emailMatch = decoded.match(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/);
+    return emailMatch ? emailMatch[0].toLowerCase() : decoded.trim().toLowerCase();
+  }
+  extractMessageId(headerValue) {
+    if (!headerValue) return `<generated-${Date.now()}@relay-temp-mail>`;
+    const cleaned = headerValue.replace(/[<>]/g, "").trim();
+    return `<${cleaned}>`;
+  }
+};
+
+// src/relay-api.ts
+var RelayAPIClient = class {
+  constructor(csrfToken, sessionId, httpClient) {
+    this.csrfToken = csrfToken;
+    this.sessionId = sessionId;
+    this.httpClient = httpClient ?? new HttpClient("https://relay.firefox.com");
+  }
+  getAuthHeaders() {
+    return {
+      "Origin": "https://relay.firefox.com",
+      "Referer": "https://relay.firefox.com/accounts/profile/?",
+      "Accept": "application/json",
+      "X-CSRFToken": this.csrfToken,
+      "Cookie": `sessionid=${this.sessionId}; csrftoken=${this.csrfToken}`
+    };
+  }
+  async getAliases() {
+    const response = await this.httpClient.request(
+      "GET",
+      "/api/v1/relayaddresses/",
+      { headers: this.getAuthHeaders() }
+    );
+    return response.map((item) => this.mapAliasResponse(item));
+  }
+  async createAlias() {
+    const response = await this.httpClient.request(
+      "POST",
+      "/api/v1/relayaddresses/",
+      {
+        headers: this.getAuthHeaders(),
+        body: { enabled: true }
+      }
+    );
+    return this.mapAliasResponse(response);
+  }
+  async deleteAlias(id) {
+    await this.httpClient.request(
+      "DELETE",
+      `/api/v1/relayaddresses/${id}/`,
+      { headers: this.getAuthHeaders() }
+    );
+  }
+  mapAliasResponse(data) {
+    return {
+      id: data.id,
+      address: data.address,
+      fullAddress: data.full_address,
+      enabled: data.enabled,
+      createdAt: data.created_at,
+      domain: data.domain,
+      maskType: data.mask_type,
+      description: data.description,
+      numForwarded: data.num_forwarded,
+      numBlocked: data.num_blocked,
+      lastModifiedAt: data.last_modified_at,
+      lastUsedAt: data.last_used_at,
+      numLevelOneTrackersBlocked: data.num_level_one_trackers_blocked,
+      numReplied: data.num_replied,
+      numSpam: data.num_spam,
+      blockListEmails: data.block_list_emails,
+      generatedFor: data.generated_for,
+      usedOn: data.used_on
+    };
+  }
+};
+
+// src/client.ts
+var RelayClient = class {
+  /**
+   * Creates a new RelayClient instance.
+   *
+   * @param config - Configuration object containing authentication tokens and API URLs
+   */
+  constructor(config) {
+    const timeout = config.timeout ?? 3e4;
+    const relayHttpClient = new HttpClient("https://relay.firefox.com", timeout);
+    this.relayApi = new RelayAPIClient(
+      config.csrfToken,
+      config.sessionId,
+      relayHttpClient
+    );
+    this.cfApi = new CFEmailClient(config.cfApiUrl, config.cfToken);
+    this.parser = new EmailParser();
+  }
+  /**
+   * 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
+   */
+  async listAliases() {
+    return this.relayApi.getAliases();
+  }
+  /**
+   * 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
+   */
+  async createAlias() {
+    return this.relayApi.createAlias();
+  }
+  /**
+   * 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
+   */
+  async deleteAlias(id) {
+    return this.relayApi.deleteAlias(id);
+  }
+  /**
+   * 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
+   */
+  async getEmails(aliasAddress, options) {
+    const limit = options?.limit ?? 20;
+    const offset = options?.offset ?? 0;
+    const emails = await this.cfApi.getMails(limit, offset);
+    const parsedEmails = emails.map((email) => {
+      const parsed = this.parser.parseEmail(email.raw);
+      return {
+        ...parsed,
+        id: email.id,
+        messageId: email.messageId,
+        source: email.source,
+        address: email.address,
+        createdAt: email.createdAt,
+        metadata: email.metadata
+      };
+    });
+    if (aliasAddress) {
+      const normalizedAlias = aliasAddress.toLowerCase();
+      return parsedEmails.filter(
+        (email) => email.relayAlias?.toLowerCase() === normalizedAlias
+      );
+    }
+    return parsedEmails;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthError,
+  NetworkError,
+  NotFoundError,
+  ParseError,
+  RateLimitError,
+  RelayClient,
+  RelayTempMailError
+});
+//# sourceMappingURL=index.cjs.map