email-scrubber-core/dist/cleaners/LinkCleaner.d.ts

A privacy-focused email sanitizer that removes trackers and cleans URLs, powered by the ClearURLs ruleset.

/**
 * Defines the structure for a provider's rules in the ClearURLs ruleset.
 */
interface ProviderRule {
    /**
     * A regex pattern to match against the full URL.
     */
    urlPattern: string;
    /**
     * An array of query parameter names to be removed completely.
     */
    rules: string[];
    /**
     * An array of regex patterns. If a URL matches one of these,
     * the provider rules will not be applied.
     */
    exceptions?: string[];
    /**
     * An array of query parameter names that contain the real destination URL.
     * If one of these is found, the cleaner will navigate to that URL.
     */
    redirections?: string[];
    /**
     * An array of query parameter names that are considered tracking referrals.
     * These are often removed.
     */
    referral?: string[];
}
/**
 * Defines the top-level structure of the ClearURLs JSON data.
 */
export interface ClearUrlRules {
    /**
     * A dictionary mapping a provider's identifier (often its domain) to its set of rules.
     */
    providers: {
        [domain: string]: ProviderRule;
    };
}
/**
 * Internal structure for cached provider data with compiled regex patterns.
 */
interface CachedProviderRule {
    urlPattern: RegExp | null;
    rules: RegExp | null;
    exceptions: RegExp | null;
    redirections: RegExp | null;
    referral: RegExp | null;
}
/**
 * A class for cleaning URLs by removing tracking parameters, based on the ClearURLs ruleset.
 * All regex patterns are compiled eagerly in the constructor for optimal runtime performance.
 */
export declare class LinkCleaner {
    private readonly rules;
    private readonly cachedProviders;
    /**
     * Creates an instance of the LinkCleaner.
     * @param rules The ClearURLs rules data.
     */
    constructor(rules: ClearUrlRules);
    /**
     * Gets a cached provider's rules.
     * @param provider The provider identifier to get rules for.
     * @returns The cached provider rule or null if not found.
     */
    private getProvider;
    /**
     * Compiles a provider's rules into cached regex patterns.
     * All patterns are compiled eagerly.
     * @param providerRules The raw provider rule.
     * @param provider The provider identifier for error reporting.
     * @returns Compiled provider rule with regex patterns.
     */
    private compileProvider;
    /**
     * Compiles a URL pattern regex, with error handling.
     * @param pattern The regex pattern string.
     * @param provider The provider identifier for error reporting.
     * @returns Compiled RegExp or null if invalid.
     */
    private compileUrlPattern;
    /**
     * Compiles an array of pattern strings into a single combined RegExp object.
     * @param patterns Array of regex pattern strings.
     * @param provider The provider identifier for error reporting.
     * @param fieldName The field name for error reporting.
     * @returns A single compiled RegExp object, or null if no patterns are provided.
     */
    private compileCombinedPattern;
    /**
     * Cleans a URL by removing tracking parameters and resolving redirection links.
     *
     * @param url The URL to be cleaned. It can be a string or a URL object.
     * @returns A cleaned URL object.
     */
    clean(url: string | URL): URL;
    /**
     * Finds the matching provider rule for a given URL.
     * @param urlObject The URL to find a provider for.
     * @returns The matching cached provider rule, or null if no provider matches.
     */
    findProvider(urlObject: URL): CachedProviderRule | null;
    /**
     * Removes unwanted query parameters from a URL based on a cached provider's rules.
     * @param urlObject The URL object to be modified.
     * @param cachedProvider The cached provider rule to apply.
     */
    private cleanParams;
    /**
     * Tests if a string matches a compiled regex pattern.
     * @param value The string to test.
     * @param pattern The compiled RegExp object.
     * @returns True if the string matches the pattern.
     */
    private matchesPattern;
}
export {};
//# sourceMappingURL=LinkCleaner.d.ts.map