@url-sanitize/core 0.1.4 → 2.0.0

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,10 +38,29 @@ 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)`.
 
+## Custom catalogs
+
+```ts
+import { defineCatalog, mergeCatalogs, sanitizerCatalogJsonSchema } from '@url-sanitize/core';
+
+const custom = defineCatalog({
+  version: 'custom-1',
+  generatedAt: new Date().toISOString(),
+  sources: [{ name: 'custom' }],
+  rules: [{ kind: 'strip-param', source: 'custom', provider: 'local', paramPattern: 'utm_.+' }]
+});
+
+const merged = mergeCatalogs(custom);
+console.log(sanitizerCatalogJsonSchema.$id);
+```
+
+`mergeCatalogs()` preserves input order and concatenates sources/rules. It does
+not dedupe, reorder, or apply source precedence.
+
 ## License
 
 MIT.

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';
@@ -73,7 +81,655 @@ interface SanitizerOptions {
     domainBlocking?: boolean;
 }
 
+declare function defineCatalog(catalog: SanitizerCatalog): SanitizerCatalog;
+declare function mergeCatalogs(first: SanitizerCatalog, ...rest: SanitizerCatalog[]): SanitizerCatalog;
+
 type Sanitizer = (input: string) => SanitizeResult;
 declare function compileSanitizer(catalog: SanitizerCatalog, options?: SanitizerOptions): Sanitizer;
 
-export { type MatchedRule, type RuleSource, type SanitizeResult, type Sanitizer, type SanitizerCatalog, type SanitizerOptions, type SanitizerRule, compileSanitizer };
+declare const sanitizerOptionsJsonSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://url-sanitize.dev/schema/v1/options.json";
+    readonly title: "url-sanitize options";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly stripReferralMarketing: {
+            readonly type: "boolean";
+        };
+        readonly unwrapRedirects: {
+            readonly type: "boolean";
+        };
+        readonly domainBlocking: {
+            readonly type: "boolean";
+        };
+    };
+};
+declare const sanitizerCatalogJsonSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://url-sanitize.dev/schema/v1/catalog.json";
+    readonly title: "url-sanitize catalog";
+    readonly type: "object";
+    readonly required: readonly ["version", "generatedAt", "sources", "rules"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly version: {
+            readonly type: "string";
+        };
+        readonly generatedAt: {
+            readonly type: "string";
+        };
+        readonly sources: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["name"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly name: {
+                        readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                    };
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                    readonly hash: {
+                        readonly type: "string";
+                    };
+                    readonly license: {
+                        readonly type: "string";
+                    };
+                    readonly upstream: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly rules: {
+            readonly type: "array";
+            readonly items: {
+                readonly oneOf: readonly [{
+                    readonly type: "object";
+                    readonly required: readonly ["kind", "source", "provider", "paramPattern"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly const: "strip-param";
+                        };
+                        readonly paramPattern: {
+                            readonly type: "string";
+                        };
+                        readonly valuePattern: {
+                            readonly type: "string";
+                        };
+                        readonly isReferralMarketing: {
+                            readonly type: "boolean";
+                        };
+                        readonly source: {
+                            readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly urlPattern: {
+                            readonly type: "string";
+                        };
+                        readonly exceptions: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly required: readonly ["kind", "source", "provider", "pattern", "replacement"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly const: "raw-replace";
+                        };
+                        readonly pattern: {
+                            readonly type: "string";
+                        };
+                        readonly replacement: {
+                            readonly type: "string";
+                        };
+                        readonly source: {
+                            readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly urlPattern: {
+                            readonly type: "string";
+                        };
+                        readonly exceptions: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly required: readonly ["kind", "source", "provider", "pattern", "captureGroup"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly const: "unwrap-redirect";
+                        };
+                        readonly pattern: {
+                            readonly type: "string";
+                        };
+                        readonly captureGroup: {
+                            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"];
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly urlPattern: {
+                            readonly type: "string";
+                        };
+                        readonly exceptions: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly required: readonly ["kind", "source", "provider", "urlPattern"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly const: "block-domain";
+                        };
+                        readonly source: {
+                            readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly urlPattern: {
+                            readonly type: "string";
+                        };
+                        readonly exceptions: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                }];
+            };
+        };
+    };
+};
+declare const sanitizeResultJsonSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://url-sanitize.dev/schema/v1/result.json";
+    readonly title: "url-sanitize result";
+    readonly oneOf: readonly [{
+        readonly type: "object";
+        readonly required: readonly ["kind", "url"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly kind: {
+                readonly const: "unchanged";
+            };
+            readonly url: {
+                readonly type: "string";
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly required: readonly ["kind", "original", "url", "strippedParams", "matchedRules"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly kind: {
+                readonly const: "cleaned";
+            };
+            readonly original: {
+                readonly type: "string";
+            };
+            readonly url: {
+                readonly type: "string";
+            };
+            readonly strippedParams: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly matchedRules: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["source", "provider", "kind"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly source: {
+                            readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly kind: {
+                            readonly enum: readonly ["strip-param", "raw-replace", "unwrap-redirect", "block-domain"];
+                        };
+                        readonly detail: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly required: readonly ["kind", "original", "url", "via"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly kind: {
+                readonly const: "redirected";
+            };
+            readonly original: {
+                readonly type: "string";
+            };
+            readonly url: {
+                readonly type: "string";
+            };
+            readonly via: {
+                readonly type: "object";
+                readonly required: readonly ["source", "provider", "kind"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly source: {
+                        readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                    };
+                    readonly provider: {
+                        readonly type: "string";
+                    };
+                    readonly kind: {
+                        readonly enum: readonly ["strip-param", "raw-replace", "unwrap-redirect", "block-domain"];
+                    };
+                    readonly detail: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly required: readonly ["kind", "original", "via"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly kind: {
+                readonly const: "blocked";
+            };
+            readonly original: {
+                readonly type: "string";
+            };
+            readonly via: {
+                readonly type: "object";
+                readonly required: readonly ["source", "provider", "kind"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly source: {
+                        readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                    };
+                    readonly provider: {
+                        readonly type: "string";
+                    };
+                    readonly kind: {
+                        readonly enum: readonly ["strip-param", "raw-replace", "unwrap-redirect", "block-domain"];
+                    };
+                    readonly detail: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    }];
+};
+declare const urlSanitizeJsonSchemas: {
+    readonly catalog: {
+        readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+        readonly $id: "https://url-sanitize.dev/schema/v1/catalog.json";
+        readonly title: "url-sanitize catalog";
+        readonly type: "object";
+        readonly required: readonly ["version", "generatedAt", "sources", "rules"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly version: {
+                readonly type: "string";
+            };
+            readonly generatedAt: {
+                readonly type: "string";
+            };
+            readonly sources: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["name"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly name: {
+                            readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                        };
+                        readonly version: {
+                            readonly type: "string";
+                        };
+                        readonly hash: {
+                            readonly type: "string";
+                        };
+                        readonly license: {
+                            readonly type: "string";
+                        };
+                        readonly upstream: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly rules: {
+                readonly type: "array";
+                readonly items: {
+                    readonly oneOf: readonly [{
+                        readonly type: "object";
+                        readonly required: readonly ["kind", "source", "provider", "paramPattern"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "strip-param";
+                            };
+                            readonly paramPattern: {
+                                readonly type: "string";
+                            };
+                            readonly valuePattern: {
+                                readonly type: "string";
+                            };
+                            readonly isReferralMarketing: {
+                                readonly type: "boolean";
+                            };
+                            readonly source: {
+                                readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                            };
+                            readonly provider: {
+                                readonly type: "string";
+                            };
+                            readonly urlPattern: {
+                                readonly type: "string";
+                            };
+                            readonly exceptions: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    }, {
+                        readonly type: "object";
+                        readonly required: readonly ["kind", "source", "provider", "pattern", "replacement"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "raw-replace";
+                            };
+                            readonly pattern: {
+                                readonly type: "string";
+                            };
+                            readonly replacement: {
+                                readonly type: "string";
+                            };
+                            readonly source: {
+                                readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                            };
+                            readonly provider: {
+                                readonly type: "string";
+                            };
+                            readonly urlPattern: {
+                                readonly type: "string";
+                            };
+                            readonly exceptions: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    }, {
+                        readonly type: "object";
+                        readonly required: readonly ["kind", "source", "provider", "pattern", "captureGroup"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "unwrap-redirect";
+                            };
+                            readonly pattern: {
+                                readonly type: "string";
+                            };
+                            readonly captureGroup: {
+                                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"];
+                            };
+                            readonly provider: {
+                                readonly type: "string";
+                            };
+                            readonly urlPattern: {
+                                readonly type: "string";
+                            };
+                            readonly exceptions: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    }, {
+                        readonly type: "object";
+                        readonly required: readonly ["kind", "source", "provider", "urlPattern"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "block-domain";
+                            };
+                            readonly source: {
+                                readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                            };
+                            readonly provider: {
+                                readonly type: "string";
+                            };
+                            readonly urlPattern: {
+                                readonly type: "string";
+                            };
+                            readonly exceptions: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    }];
+                };
+            };
+        };
+    };
+    readonly options: {
+        readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+        readonly $id: "https://url-sanitize.dev/schema/v1/options.json";
+        readonly title: "url-sanitize options";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly stripReferralMarketing: {
+                readonly type: "boolean";
+            };
+            readonly unwrapRedirects: {
+                readonly type: "boolean";
+            };
+            readonly domainBlocking: {
+                readonly type: "boolean";
+            };
+        };
+    };
+    readonly result: {
+        readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+        readonly $id: "https://url-sanitize.dev/schema/v1/result.json";
+        readonly title: "url-sanitize result";
+        readonly oneOf: readonly [{
+            readonly type: "object";
+            readonly required: readonly ["kind", "url"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly const: "unchanged";
+                };
+                readonly url: {
+                    readonly type: "string";
+                };
+            };
+        }, {
+            readonly type: "object";
+            readonly required: readonly ["kind", "original", "url", "strippedParams", "matchedRules"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly const: "cleaned";
+                };
+                readonly original: {
+                    readonly type: "string";
+                };
+                readonly url: {
+                    readonly type: "string";
+                };
+                readonly strippedParams: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly matchedRules: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["source", "provider", "kind"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly source: {
+                                readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                            };
+                            readonly provider: {
+                                readonly type: "string";
+                            };
+                            readonly kind: {
+                                readonly enum: readonly ["strip-param", "raw-replace", "unwrap-redirect", "block-domain"];
+                            };
+                            readonly detail: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            readonly type: "object";
+            readonly required: readonly ["kind", "original", "url", "via"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly const: "redirected";
+                };
+                readonly original: {
+                    readonly type: "string";
+                };
+                readonly url: {
+                    readonly type: "string";
+                };
+                readonly via: {
+                    readonly type: "object";
+                    readonly required: readonly ["source", "provider", "kind"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly source: {
+                            readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly kind: {
+                            readonly enum: readonly ["strip-param", "raw-replace", "unwrap-redirect", "block-domain"];
+                        };
+                        readonly detail: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        }, {
+            readonly type: "object";
+            readonly required: readonly ["kind", "original", "via"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly const: "blocked";
+                };
+                readonly original: {
+                    readonly type: "string";
+                };
+                readonly via: {
+                    readonly type: "object";
+                    readonly required: readonly ["source", "provider", "kind"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly source: {
+                            readonly enum: readonly ["clearurls", "adguard", "brave", "firefox", "custom"];
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly kind: {
+                            readonly enum: readonly ["strip-param", "raw-replace", "unwrap-redirect", "block-domain"];
+                        };
+                        readonly detail: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        }];
+    };
+};
+
+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

@@ -1,3 +1,23 @@
+// src/catalog.ts
+function defineCatalog(catalog) {
+  return catalog;
+}
+function mergeCatalogs(first, ...rest) {
+  const catalogs = [first, ...rest];
+  return {
+    version: catalogs.length === 1 ? first.version : `merged(${catalogs.map((catalog) => catalog.version).join(",")})`,
+    generatedAt: latestGeneratedAt(catalogs),
+    sources: catalogs.flatMap((catalog) => catalog.sources.map((source) => ({ ...source }))),
+    rules: catalogs.flatMap((catalog) => catalog.rules.map(cloneRule))
+  };
+}
+function latestGeneratedAt(catalogs) {
+  return catalogs.map((catalog) => catalog.generatedAt).reduce((latest, generatedAt) => generatedAt > latest ? generatedAt : latest);
+}
+function cloneRule(rule) {
+  return rule.exceptions ? { ...rule, exceptions: [...rule.exceptions] } : { ...rule };
+}
+
 // src/sanitize.ts
 function safeRegex(pattern, flags = "") {
   try {
@@ -20,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 {
@@ -28,6 +50,7 @@ function compileRule(rule) {
         provider: rule.provider,
         urlPattern,
         paramPattern,
+        valuePattern,
         exceptions: compileExceptions(rule.exceptions),
         isReferralMarketing: rule.isReferralMarketing ?? false
       };
@@ -59,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)
       };
     }
@@ -82,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));
 }
@@ -128,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 {
@@ -165,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;
@@ -193,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;
@@ -204,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);
@@ -214,6 +277,193 @@ function stripFromQueryString(searchOrHash, paramPattern) {
   if (kept.length === 0) return { result: "", removed };
   return { result: prefix + kept.join("&"), removed };
 }
+
+// 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"],
+  additionalProperties: false,
+  properties: {
+    name: { enum: ruleSourceValues },
+    version: { type: "string" },
+    hash: { type: "string" },
+    license: { type: "string" },
+    upstream: { type: "string" }
+  }
+};
+var ruleBaseProperties = {
+  source: { enum: ruleSourceValues },
+  provider: { type: "string" },
+  urlPattern: { type: "string" },
+  exceptions: {
+    type: "array",
+    items: { type: "string" }
+  }
+};
+var matchedRuleSchema = {
+  type: "object",
+  required: ["source", "provider", "kind"],
+  additionalProperties: false,
+  properties: {
+    source: { enum: ruleSourceValues },
+    provider: { type: "string" },
+    kind: { enum: ruleKindValues },
+    detail: { type: "string" }
+  }
+};
+var sanitizerOptionsJsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://url-sanitize.dev/schema/v1/options.json",
+  title: "url-sanitize options",
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    stripReferralMarketing: { type: "boolean" },
+    unwrapRedirects: { type: "boolean" },
+    domainBlocking: { type: "boolean" }
+  }
+};
+var sanitizerCatalogJsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://url-sanitize.dev/schema/v1/catalog.json",
+  title: "url-sanitize catalog",
+  type: "object",
+  required: ["version", "generatedAt", "sources", "rules"],
+  additionalProperties: false,
+  properties: {
+    version: { type: "string" },
+    generatedAt: { type: "string" },
+    sources: {
+      type: "array",
+      items: catalogSourceSchema
+    },
+    rules: {
+      type: "array",
+      items: {
+        oneOf: [
+          {
+            type: "object",
+            required: ["kind", "source", "provider", "paramPattern"],
+            additionalProperties: false,
+            properties: {
+              ...ruleBaseProperties,
+              kind: { const: "strip-param" },
+              paramPattern: { type: "string" },
+              valuePattern: { type: "string" },
+              isReferralMarketing: { type: "boolean" }
+            }
+          },
+          {
+            type: "object",
+            required: ["kind", "source", "provider", "pattern", "replacement"],
+            additionalProperties: false,
+            properties: {
+              ...ruleBaseProperties,
+              kind: { const: "raw-replace" },
+              pattern: { type: "string" },
+              replacement: { type: "string" }
+            }
+          },
+          {
+            type: "object",
+            required: ["kind", "source", "provider", "pattern", "captureGroup"],
+            additionalProperties: false,
+            properties: {
+              ...ruleBaseProperties,
+              kind: { const: "unwrap-redirect" },
+              pattern: { type: "string" },
+              captureGroup: { type: "integer", minimum: 0 },
+              matchPart: { enum: redirectMatchPartValues },
+              targetEncoding: { enum: redirectTargetEncodingValues },
+              prependScheme: { enum: redirectPrependSchemeValues },
+              targetTemplate: { type: "string" }
+            }
+          },
+          {
+            type: "object",
+            required: ["kind", "source", "provider", "urlPattern"],
+            additionalProperties: false,
+            properties: {
+              ...ruleBaseProperties,
+              kind: { const: "block-domain" }
+            }
+          }
+        ]
+      }
+    }
+  }
+};
+var sanitizeResultJsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://url-sanitize.dev/schema/v1/result.json",
+  title: "url-sanitize result",
+  oneOf: [
+    {
+      type: "object",
+      required: ["kind", "url"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "unchanged" },
+        url: { type: "string" }
+      }
+    },
+    {
+      type: "object",
+      required: ["kind", "original", "url", "strippedParams", "matchedRules"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "cleaned" },
+        original: { type: "string" },
+        url: { type: "string" },
+        strippedParams: {
+          type: "array",
+          items: { type: "string" }
+        },
+        matchedRules: {
+          type: "array",
+          items: matchedRuleSchema
+        }
+      }
+    },
+    {
+      type: "object",
+      required: ["kind", "original", "url", "via"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "redirected" },
+        original: { type: "string" },
+        url: { type: "string" },
+        via: matchedRuleSchema
+      }
+    },
+    {
+      type: "object",
+      required: ["kind", "original", "via"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "blocked" },
+        original: { type: "string" },
+        via: matchedRuleSchema
+      }
+    }
+  ]
+};
+var urlSanitizeJsonSchemas = {
+  catalog: sanitizerCatalogJsonSchema,
+  options: sanitizerOptionsJsonSchema,
+  result: sanitizeResultJsonSchema
+};
 export {
-  compileSanitizer
+  compileSanitizer,
+  defineCatalog,
+  mergeCatalogs,
+  sanitizeResultJsonSchema,
+  sanitizerCatalogJsonSchema,
+  sanitizerOptionsJsonSchema,
+  urlSanitizeJsonSchemas
 };

package/package.json

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