dsh-url-tools

URLs keep surfacing in Agent pipelines and automation scripts: landing pages caked in utm parameters, percent-encoded query fragments, chains of 301 redirects that land on an entirely different domain. dsh-url-tools folds all of that into a single url_tool with five actions—parse, clean, decode, encode, expand—so you stop scattering regexes and DevTools manual debugging across your codebase.

parse dissects any valid URL into scheme, host, port, pathname, search, hash, username and a structured params object where duplicate keys collapse into arrays, making routing lookups and log normalisation straightforward. clean strips only the tracking parameters you actually want gone—every utm_* variant plus fbclid, gclid, msclkid, mc_cid, mc_eid, yclid, and wickedid—while preserving business params like ref or gclsrc, and returns the removed keys deduplicated in first-seen order. decode and encode run decodeURIComponent and encodeURIComponent over the entire string, ideal for fragment-level encoding conversions. expand follows redirects manually: it prefers a HEAD request per hop, falls back to GET on failure, honours both absolute and relative Location values, caps at five hops with a ten-second timeout each, and returns the final URL, a per-hop status-code array, and a flag when the hop limit is reached.

The plugin ships with zero runtime dependencies, pure ESM, and no build step. Every exceptional path—bad arguments, invalid URLs, network timeouts, malformed percent-escapes—resolves to an ok: false plus error JSON object; it never throws. If you are wiring up web tools for an LLM Agent, building a URL-normalisation pipeline, or simply want one place to handle parsing, tracking-param cleanup, encoding, and redirect tracing, it is ready to use the moment you install it.