dymo-api 1.2.29 → 1.2.31

package/dist/esm/lib/resilience/index.js

@@ -0,0 +1,131 @@
+class RateLimitManager {
+    constructor() {
+        this.tracker = {};
+    }
+    static getInstance() {
+        if (!RateLimitManager.instance)
+            RateLimitManager.instance = new RateLimitManager();
+        return RateLimitManager.instance;
+    }
+    ;
+    updateRateLimit(clientId, headers) {
+        if (!this.tracker[clientId])
+            this.tracker[clientId] = {};
+        const limitInfo = this.tracker[clientId];
+        if (headers["x-ratelimit-limit-requests"])
+            limitInfo.limit = parseInt(headers["x-ratelimit-limit-requests"]);
+        if (headers["x-ratelimit-remaining-requests"])
+            limitInfo.remaining = parseInt(headers["x-ratelimit-remaining-requests"]);
+        if (headers["x-ratelimit-reset-requests"])
+            limitInfo.resetTime = headers["x-ratelimit-reset-requests"];
+        if (headers["retry-after"])
+            limitInfo.retryAfter = parseInt(headers["retry-after"]);
+        limitInfo.lastUpdated = Date.now();
+    }
+    ;
+    isRateLimited(clientId) {
+        const limitInfo = this.tracker[clientId];
+        return limitInfo?.remaining !== undefined && limitInfo.remaining <= 0;
+    }
+    ;
+    getRetryAfter(clientId) {
+        return this.tracker[clientId]?.retryAfter;
+    }
+    ;
+    clearExpiredLimits() {
+        const now = Date.now();
+        Object.keys(this.tracker).forEach(clientId => {
+            const limitInfo = this.tracker[clientId];
+            if (limitInfo.lastUpdated && (now - limitInfo.lastUpdated) > 300000)
+                delete this.tracker[clientId];
+        });
+    }
+    ;
+}
+;
+export class ResilienceManager {
+    constructor(config = {}, clientId = "default") {
+        this.config = {
+            fallbackEnabled: config.fallbackEnabled ?? false,
+            retryAttempts: Math.max(0, config.retryAttempts ?? 2), // Number of additional retries
+            retryDelay: Math.max(0, config.retryDelay ?? 1000)
+        };
+        this.clientId = clientId;
+        this.rateLimitManager = RateLimitManager.getInstance();
+    }
+    ;
+    async executeWithResilience(axiosClient, requestConfig, fallbackData) {
+        let lastError;
+        const totalAttempts = 1 + this.config.retryAttempts; // 1 normal + N retries
+        // Clean up expired rate limits periodically
+        this.rateLimitManager.clearExpiredLimits();
+        // Check if client is currently rate limited
+        if (this.rateLimitManager.isRateLimited(this.clientId)) {
+            const retryAfter = this.rateLimitManager.getRetryAfter(this.clientId);
+            if (retryAfter) {
+                console.warn(`[Dymo API] Client ${this.clientId} is rate limited. Waiting ${retryAfter} seconds...`);
+                await this.sleep(retryAfter * 1000);
+            }
+        }
+        for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+            try {
+                const response = await axiosClient.request(requestConfig);
+                // Update rate limit tracking
+                this.rateLimitManager.updateRateLimit(this.clientId, response.headers);
+                // Check for rate limiting
+                if (response.status === 429) {
+                    const retryAfter = this.rateLimitManager.getRetryAfter(this.clientId);
+                    if (retryAfter) {
+                        console.warn(`[Dymo API] Rate limited. Waiting ${retryAfter} seconds (no retries)`);
+                        await this.sleep(retryAfter * 1000);
+                    }
+                    throw new Error(`Rate limited (429) - not retrying`);
+                }
+                return response.data;
+            }
+            catch (error) {
+                lastError = error;
+                let shouldRetry = this.shouldRetry(error);
+                const isLastAttempt = attempt === totalAttempts;
+                // Don't retry on rate limiting (429)
+                if (error.response?.status === 429)
+                    shouldRetry = false;
+                if (!shouldRetry || isLastAttempt) {
+                    if (this.config.fallbackEnabled && fallbackData) {
+                        console.warn(`[Dymo API] Request failed after ${attempt} attempts. Using fallback data.`);
+                        return fallbackData;
+                    }
+                    throw error;
+                }
+                const delay = this.config.retryDelay * Math.pow(2, attempt - 1);
+                console.warn(`[Dymo API] Attempt ${attempt} failed. Retrying in ${delay}ms...`);
+                await this.sleep(delay);
+            }
+        }
+        throw lastError;
+    }
+    ;
+    shouldRetry(error) {
+        const statusCode = error.response?.status;
+        const isNetworkError = !error.response && error.code !== "ECONNABORTED";
+        const isServerError = statusCode && statusCode >= 500;
+        // Retry on: network errors, server errors (5xx)
+        // DON'T retry on: rate limiting (429) - handled separately
+        // DON'T retry on: client errors (4xx except 429)
+        return isNetworkError || isServerError;
+    }
+    ;
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    ;
+    getConfig() {
+        return { ...this.config };
+    }
+    ;
+    getClientId() {
+        return this.clientId;
+    }
+    ;
+}
+;

package/dist/types/dymo-api.d.ts

@@ -6,30 +6,35 @@ declare class DymoAPI {
     private rules;
     private baseUrl;
     private axiosClient;
+    private resilienceManager;
     /**
-     * @param {Object} options - Options to create the DymoAPI instance.
-     * @param {string} [options.rootApiKey] - The root API key.
-     * @param {string} [options.apiKey] - The API key.
-     * @param {string} [options.baseUrl] - Whether to use a local server instead of the cloud server.
-     * @param {Object} [options.serverEmailConfig] - The server email config.
-     * @description
-     * This is the main class to interact with the Dymo API. It should be
-     * instantiated with the root API key and the API key. The root API key is
-     * used to fetch the tokens and the API key is used to authenticate the
-     * requests.
-     * @example
-     * const dymoApi = new DymoAPI({
-     *     rootApiKey: "6bfb7675-6b69-4f8d-9f43-5a6f7f02c6c5",
-     *     apiKey: "dm_4c8b7675-6b69-4f8d-9f43-5a6f7f02c6c5"
-     * });
-     */
-    constructor({ rootApiKey, apiKey, baseUrl, serverEmailConfig, rules }?: {
+         * @param {Object} options - Options to create the DymoAPI instance.
+         * @param {string} [options.rootApiKey] - The root API key.
+         * @param {string} [options.apiKey] - The API key.
+         * @param {string} [options.baseUrl] - Whether to use a local server instead of the cloud server.
+         * @param {Object} [options.serverEmailConfig] - The server email config.
+         * @param {Object} [options.rules] - The rules.
+         * @param {Object} [options.resilience] - The resilience config.
+         * @description
+         * This is the main class to interact with the Dymo API. It should be
+         * instantiated with the root API key and the API key. The root API key is
+         * used to fetch the tokens and the API key is used to authenticate the
+         * requests. Requests are retried once by default with exponential backoff.
+         * @example
+         * const dymoApi = new DymoAPI({
+         *     rootApiKey: "6bfb7675-6b69-4f8d-9f43-5a6f7f02c6c5",
+         *     apiKey: "dm_4c8b7675-6b69-4f8d-9f43-5a6f7f02c6c5"
+         * });
+         */
+    constructor({ rootApiKey, apiKey, baseUrl, serverEmailConfig, rules, resilience }?: {
         rootApiKey?: string | null;
         apiKey?: string | null;
         baseUrl?: string;
         serverEmailConfig?: Interfaces.ServerEmailConfig;
         rules?: Interfaces.Rules;
+        resilience?: Interfaces.ResilienceConfig;
     });
+    private getEmailPlugins;
     /**
      * Validates the given data against the configured validation settings.
      *

package/dist/types/lib/resilience/fallback.d.ts

@@ -0,0 +1,26 @@
+export declare class FallbackDataGenerator {
+    static generateFallbackData<T>(method: string, inputData?: any): T;
+    private static validateURL;
+    private static validateEmail;
+    private static validateDomain;
+    private static validateCreditCard;
+    private static validateIP;
+    private static validatePhone;
+    private static validateWallet;
+    private static validateIBAN;
+    private static extractDomain;
+    private static generateDataValidationAnalysis;
+    private static generateEmailValidatorResponse;
+    private static generateEmailDataAnalysis;
+    private static generateIPValidatorResponse;
+    private static generateIPDataAnalysis;
+    private static generatePhoneValidatorResponse;
+    private static generatePhoneDataAnalysis;
+    private static generateHTTPRequest;
+    private static generateEmailStatus;
+    private static generateSRNSummary;
+    private static generateExtractWithTextly;
+    private static generatePrayerTimes;
+    private static generateSatinizedInputAnalysis;
+    private static generatePasswordValidationResult;
+}

package/dist/types/lib/resilience/index.d.ts

@@ -0,0 +1,13 @@
+import { ResilienceConfig } from "../types/interfaces";
+import { AxiosInstance, AxiosRequestConfig } from "axios";
+export declare class ResilienceManager {
+    private config;
+    private clientId;
+    private rateLimitManager;
+    constructor(config?: ResilienceConfig, clientId?: string);
+    executeWithResilience<T>(axiosClient: AxiosInstance, requestConfig: AxiosRequestConfig, fallbackData?: T): Promise<T>;
+    private shouldRetry;
+    private sleep;
+    getConfig(): Required<ResilienceConfig>;
+    getClientId(): string;
+}

package/dist/types/lib/types/data-verifier.d.ts

@@ -1,5 +1,5 @@
 import { MxRecord } from "dns";
-import { Email, Phone, CreditCard } from "./primitives";
+import { Email, Phone, CreditCard, Char } from "./primitives";
 export type VerifyPlugins = "blocklist" | "gravatar" | "compromiseDetector" | "mxRecords" | "nsfw" | "reputation" | "riskScore" | "torNetwork" | "typosquatting" | "urlShortener";
 export type ReputationPlugin = "low" | "medium" | "high" | "very-high" | "education" | "governmental" | "unknown";
 export type TyposquattingPlugin = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
@@ -69,10 +69,10 @@ export type IPValidator = string;
  * @typedef {"FRAUD"|"INVALID"|"HIGH_RISK_SCORE"} NegativeIPRules
  *
  * @description
- * Values indicating why an email is considered negative.
+ * Values indicating why an IP is considered negative.
  * ⚠️ TOR_NETWORK and HIGH_RISK_SCORE are premium features.
  */
-export type NegativeIPRules = "FRAUD" | "INVALID" | "TOR_NETWORK" | "HIGH_RISK_SCORE" | `COUNTRY:${string}${string}`;
+export type NegativeIPRules = "FRAUD" | "INVALID" | "TOR_NETWORK" | "HIGH_RISK_SCORE" | `COUNTRY:${Char}${Char}`;
 export type PhoneValidator = Phone;
 /**
  * @typedef {"FRAUD"|"INVALID"|"HIGH_RISK_SCORE"} NegativePhoneRules
@@ -80,7 +80,7 @@ export type PhoneValidator = Phone;
  * @description
  * Values indicating why an phone is considered negative.
  */
-export type NegativePhoneRules = "FRAUD" | "INVALID" | "HIGH_RISK_SCORE";
+export type NegativePhoneRules = "FRAUD" | "INVALID" | "HIGH_RISK_SCORE" | `COUNTRY:${Char}${Char}`;
 export type NegativeSensitiveInfoRules = "EMAIL" | "PHONE" | "CREDIT_CARD" | "URL" | "DOMAIN" | "IP" | "WALLET" | "USER_AGENT";
 /**
  * Response returned by the email validator.

package/dist/types/lib/types/interfaces.d.ts

@@ -162,6 +162,21 @@ export interface ExtractWithTextly {
         [key: string]: JsonSchemaProperty;
     };
 }
+export interface RateLimitInfo {
+    limit?: number;
+    remaining?: number;
+    resetTime?: string;
+    retryAfter?: number;
+    lastUpdated?: number;
+}
+export interface RateLimitTracker {
+    [clientId: string]: RateLimitInfo;
+}
+export interface ResilienceConfig {
+    fallbackEnabled?: boolean;
+    retryAttempts?: number;
+    retryDelay?: number;
+}
 export * from "./rules";
 export * from "./primitives";
 export * from "./data-verifier";

package/dist/types/lib/types/primitives.d.ts

@@ -1,5 +1,6 @@
 export type Email = `${string}@${string}.${string}` | string;
 type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+export type Char = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z";
 export type Phone = {
     /** The country code of the phone number. */
     iso: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dymo-api",
-  "version": "1.2.29",
+  "version": "1.2.31",
   "description": "Flow system for Dymo API.",
   "main": "dist/cjs/dymo-api.js",
   "module": "dist/esm/dymo-api.js",