@url-sanitize/core 1.0.0 → 2.0.1

package/README.md

@@ -5,16 +5,16 @@ Pure TypeScript implementation for removing tracking parameters and unwrapping t
 ## Install
 
 ```sh
-npm install @url-sanitize/core @url-sanitize/clearurls
+npm install @url-sanitize/core @url-sanitize/merged
 ```
 
 ## Usage
 
 ```ts
 import { compileSanitizer } from '@url-sanitize/core';
-import { clearurlsCatalog } from '@url-sanitize/clearurls';
+import { mergedCatalog } from '@url-sanitize/merged';
 
-const sanitize = compileSanitizer(clearurlsCatalog, {
+const sanitize = compileSanitizer(mergedCatalog, {
   stripReferralMarketing: false,
   unwrapRedirects: true,
   domainBlocking: false
@@ -38,7 +38,7 @@ type SanitizeResult =
 
 - Zero runtime dependencies.
 - Pure function; no I/O.
-- Catalog-agnostic: any source (ClearURLs, AdGuard, custom) that produces a `SanitizerCatalog` works.
+- Catalog-agnostic: any source (ClearURLs, AdGuard, Brave, Firefox, custom) that produces a `SanitizerCatalog` works.
 - Factory pattern (`compileSanitizer(catalog)`) — no module-level cache, no singletons.
 - Discriminated union return type — exhaustive `switch (result.kind)`.
 

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 type RuleSource = 'clearurls' | 'adguard' | 'brave' | 'firefox' | 'custom';
+type RedirectMatchPart = 'url' | 'pathname';
+type RedirectTargetEncoding = 'percent' | 'base64';
+type RedirectPrependScheme = 'http' | 'https';
 type SanitizerRule = {
     kind: 'strip-param';
     source: RuleSource;
     provider: string;
     urlPattern?: string;
     paramPattern: string;
+    valuePattern?: string;
     exceptions?: string[];
     isReferralMarketing?: boolean;
 } | {
@@ -22,6 +26,10 @@ type SanitizerRule = {
     urlPattern?: string;
     pattern: string;
     captureGroup: number;
+    matchPart?: RedirectMatchPart;
+    targetEncoding?: RedirectTargetEncoding;
+    prependScheme?: RedirectPrependScheme;
+    targetTemplate?: string;
     exceptions?: string[];
 } | {
     kind: 'block-domain';
@@ -150,6 +158,9 @@ declare const sanitizerCatalogJsonSchema: {
                         readonly paramPattern: {
                             readonly type: "string";
                         };
+                        readonly valuePattern: {
+                            readonly type: "string";
+                        };
                         readonly isReferralMarketing: {
                             readonly type: "boolean";
                         };
@@ -214,6 +225,18 @@ declare const sanitizerCatalogJsonSchema: {
                             readonly type: "integer";
                             readonly minimum: 0;
                         };
+                        readonly matchPart: {
+                            readonly enum: readonly ["url", "pathname"];
+                        };
+                        readonly targetEncoding: {
+                            readonly enum: readonly ["percent", "base64"];
+                        };
+                        readonly prependScheme: {
+                            readonly enum: readonly ["http", "https"];
+                        };
+                        readonly targetTemplate: {
+                            readonly type: "string";
+                        };
                         readonly source: {
                             readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
                         };
@@ -439,6 +462,9 @@ declare const urlSanitizeJsonSchemas: {
                             readonly paramPattern: {
                                 readonly type: "string";
                             };
+                            readonly valuePattern: {
+                                readonly type: "string";
+                            };
                             readonly isReferralMarketing: {
                                 readonly type: "boolean";
                             };
@@ -503,6 +529,18 @@ declare const urlSanitizeJsonSchemas: {
                                 readonly type: "integer";
                                 readonly minimum: 0;
                             };
+                            readonly matchPart: {
+                                readonly enum: readonly ["url", "pathname"];
+                            };
+                            readonly targetEncoding: {
+                                readonly enum: readonly ["percent", "base64"];
+                            };
+                            readonly prependScheme: {
+                                readonly enum: readonly ["http", "https"];
+                            };
+                            readonly targetTemplate: {
+                                readonly type: "string";
+                            };
                             readonly source: {
                                 readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
                             };
@@ -694,4 +732,4 @@ declare const urlSanitizeJsonSchemas: {
     };
 };
 
-export { type MatchedRule, type RuleSource, type SanitizeResult, type Sanitizer, type SanitizerCatalog, type SanitizerOptions, type SanitizerRule, compileSanitizer, defineCatalog, mergeCatalogs, sanitizeResultJsonSchema, sanitizerCatalogJsonSchema, sanitizerOptionsJsonSchema, urlSanitizeJsonSchemas };
+export { type MatchedRule, type RedirectMatchPart, type RedirectPrependScheme, type RedirectTargetEncoding, type RuleSource, type SanitizeResult, type Sanitizer, type SanitizerCatalog, type SanitizerOptions, type SanitizerRule, compileSanitizer, defineCatalog, mergeCatalogs, sanitizeResultJsonSchema, sanitizerCatalogJsonSchema, sanitizerOptionsJsonSchema, urlSanitizeJsonSchemas };

package/dist/index.js

@@ -40,6 +40,8 @@ function compileRule(rule) {
     case "strip-param": {
       const paramPattern = safeRegex(`^(?:${rule.paramPattern})$`, "i");
       if (!paramPattern) return null;
+      const valuePattern = rule.valuePattern ? safeRegex(`^(?:${rule.valuePattern})$`, "i") : null;
+      if (rule.valuePattern && !valuePattern) return null;
       const urlPattern = rule.urlPattern ? safeRegex(rule.urlPattern, "i") : null;
       if (rule.urlPattern && !urlPattern) return null;
       return {
@@ -48,6 +50,7 @@ function compileRule(rule) {
         provider: rule.provider,
         urlPattern,
         paramPattern,
+        valuePattern,
         exceptions: compileExceptions(rule.exceptions),
         isReferralMarketing: rule.isReferralMarketing ?? false
       };
@@ -79,6 +82,10 @@ function compileRule(rule) {
         urlPattern,
         pattern,
         captureGroup: rule.captureGroup,
+        matchPart: rule.matchPart ?? "url",
+        targetEncoding: rule.targetEncoding ?? "percent",
+        prependScheme: rule.prependScheme,
+        targetTemplate: rule.targetTemplate,
         exceptions: compileExceptions(rule.exceptions)
       };
     }
@@ -102,6 +109,29 @@ function safeDecode(value) {
     return value;
   }
 }
+function safeBase64Decode(value) {
+  try {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
+    const binary = globalThis.atob(padded);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function templateTarget(template, match) {
+  return template.replace(/\$([1-9])/g, (_, index) => match[Number(index)] ?? "");
+}
+function targetWithPrependedScheme(target, scheme) {
+  if (!scheme) return target;
+  try {
+    new URL(target);
+    return target;
+  } catch {
+    return `${scheme}://${target.replace(/^\/+/, "")}`;
+  }
+}
 function matchesAny(url, patterns) {
   return patterns.some((re) => re.test(url));
 }
@@ -148,10 +178,22 @@ function compileSanitizer(catalog, options = {}) {
         }
         case "unwrap-redirect": {
           if (!unwrapRedirects) continue;
-          const m = rule.pattern.exec(current);
-          const captured = m?.[rule.captureGroup];
+          let matchInput = current;
+          if (rule.matchPart === "pathname") {
+            try {
+              matchInput = new URL(current).pathname;
+            } catch {
+              continue;
+            }
+          }
+          const m = rule.pattern.exec(matchInput);
+          if (!m) continue;
+          const captured = rule.targetTemplate ? templateTarget(rule.targetTemplate, m) : m[rule.captureGroup];
           if (typeof captured === "string" && captured.length > 0) {
-            const target = safeDecode(captured);
+            const decodedTarget = rule.targetEncoding === "base64" ? safeBase64Decode(safeDecode(captured)) : safeDecode(captured);
+            if (!decodedTarget) continue;
+            const target = targetWithPrependedScheme(decodedTarget, rule.prependScheme);
+            if (!target) continue;
             try {
               const targetUrl = new URL(target);
               return {
@@ -185,8 +227,8 @@ function compileSanitizer(catalog, options = {}) {
           } catch {
             continue;
           }
-          const search = stripFromQueryString(urlObj.search, rule.paramPattern);
-          const hash = stripFromQueryString(urlObj.hash, rule.paramPattern);
+          const search = stripFromQueryString(urlObj.search, rule.paramPattern, rule.valuePattern);
+          const hash = stripFromQueryString(urlObj.hash, rule.paramPattern, rule.valuePattern);
           const removed = [...search.removed, ...hash.removed];
           if (removed.length === 0) continue;
           urlObj.search = search.result;
@@ -213,7 +255,7 @@ function compileSanitizer(catalog, options = {}) {
     };
   };
 }
-function stripFromQueryString(searchOrHash, paramPattern) {
+function stripFromQueryString(searchOrHash, paramPattern, valuePattern) {
   if (!searchOrHash) return { result: searchOrHash, removed: [] };
   const prefix = searchOrHash.charAt(0);
   const body = prefix === "?" || prefix === "#" ? searchOrHash.slice(1) : searchOrHash;
@@ -224,7 +266,8 @@ function stripFromQueryString(searchOrHash, paramPattern) {
   for (const pair of pairs) {
     const eqIdx = pair.indexOf("=");
     const name = eqIdx === -1 ? pair : pair.slice(0, eqIdx);
-    if (paramPattern.test(name)) {
+    const value = eqIdx === -1 ? "" : pair.slice(eqIdx + 1);
+    if (paramPattern.test(name) && (!valuePattern || valuePattern.test(value))) {
       removed.push(name);
     } else {
       kept.push(pair);
@@ -238,6 +281,9 @@ function stripFromQueryString(searchOrHash, paramPattern) {
 // src/schemas.ts
 var ruleSourceValues = ["clearurls", "adguard", "brave", "firefox", "custom"];
 var ruleKindValues = ["strip-param", "raw-replace", "unwrap-redirect", "block-domain"];
+var redirectMatchPartValues = ["url", "pathname"];
+var redirectTargetEncodingValues = ["percent", "base64"];
+var redirectPrependSchemeValues = ["http", "https"];
 var catalogSourceSchema = {
   type: "object",
   required: ["name"],
@@ -308,6 +354,7 @@ var sanitizerCatalogJsonSchema = {
               ...ruleBaseProperties,
               kind: { const: "strip-param" },
               paramPattern: { type: "string" },
+              valuePattern: { type: "string" },
               isReferralMarketing: { type: "boolean" }
             }
           },
@@ -330,7 +377,11 @@ var sanitizerCatalogJsonSchema = {
               ...ruleBaseProperties,
               kind: { const: "unwrap-redirect" },
               pattern: { type: "string" },
-              captureGroup: { type: "integer", minimum: 0 }
+              captureGroup: { type: "integer", minimum: 0 },
+              matchPart: { enum: redirectMatchPartValues },
+              targetEncoding: { enum: redirectTargetEncodingValues },
+              prependScheme: { enum: redirectPrependSchemeValues },
+              targetTemplate: { type: "string" }
             }
           },
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@url-sanitize/core",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "description": "Pure TypeScript library for removing tracking parameters and unwrapping tracking redirects.",
   "license": "MIT",
   "type": "module",