Skip to main content
This page documents the core TypeScript interfaces and functions that power Redirect Trace. Use this reference when extending the code or understanding the internal architecture.

​
Interfaces

​
RedirectChain

Represents the complete result of tracing a URL through its redirect chain. 
interface RedirectChain {
  originalUrl: string;
  finalUrl: string;
  steps: RedirectStep[];
  totalRedirects: number;
  isComplete: boolean;
  error?: string;
}
​
originalUrl
string
required
The validated input URL that was traced. This URL has been processed by validateUrl() and may include protocol additions.
​
finalUrl
string
required
The last URL reached in the redirect chain. This is either the final destination or the URL where the trace stopped (due to limits or errors).
​
steps
RedirectStep[]
required
Array of all redirect steps encountered, in chronological order. Each step contains the URL, HTTP status, and response headers.
​
totalRedirects
number
required
Count of how many redirects occurred. A value of 0 means the URL didn’t redirect. Maximum value is determined by the maxRedirects preference.
​
isComplete
boolean
required
Indicates whether the trace completed successfully.
  • true: The trace reached a non-redirect status code (200, 404, etc.)
  • false: The trace stopped due to hitting maxRedirects limit or encountering an error
​
error
string
Error message if the trace failed. Only present when an error occurred. See troubleshooting for common error messages.

​
RedirectStep

Represents a single step in the redirect chain. 
interface RedirectStep {
  url: string;
  status: number;
  statusText: string;
  headers: Record<string, string>;
}
​
url
string
required
The URL that was requested for this step. This is the current location in the redirect chain.
​
status
number
required
HTTP status code returned by the server.Common codes:
  • 301: Permanent redirect
  • 302: Temporary redirect
  • 307: Temporary redirect (method preserved)
  • 308: Permanent redirect (method preserved)
  • 200: Success (final destination)
​
statusText
string
required
Human-readable status text corresponding to the status code (e.g., “Moved Permanently”, “Found”, “OK”).
​
headers
Record<string, string>
required
All HTTP response headers as key-value pairs. The location header contains the next URL in redirect responses (3xx status codes).
// Example headers
{
  "location": "https://example.com/new-path",
  "content-type": "text/html",
  "cache-control": "no-cache"
}

​
Preferences

Configuration interface for extension preferences. 
interface Preferences {
  maxRedirects: string;
  timeout: string;
}
​
maxRedirects
string
String representation of maximum redirects to follow. Parsed to integer with default "10".
​
timeout
string
String representation of timeout in milliseconds. Parsed to integer with default "5000".

​
Functions

​
followRedirects()

Traces a URL through its redirect chain and returns the complete analysis. 
async function followRedirects(url: string): Promise<RedirectChain>
​
url
string
required
The URL to trace. Can be with or without protocol (http/https). Will be validated and normalized.
​
returns
Promise<RedirectChain>
Promise that resolves to a RedirectChain object containing all trace results.
Behavior:
  1. Validates and normalizes the input URL using validateUrl()
  2. Makes HTTP requests with redirect: "manual" to prevent automatic following
  3. Collects each redirect step including status codes and headers
  4. Stops when:
    • A non-redirect status code is received (200, 404, etc.)
    • maxRedirects limit is reached
    • A timeout or network error occurs
    • No location header is present in a 3xx response
Request headers sent: 
{
  "User-Agent": "RedirectTrace-Raycast-Extension/1.0",
  "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  "Accept-Language": "en-US,en;q=0.9",
  "DNT": "1",
  "Connection": "keep-alive"
}

​
validateUrl()

Normalizes and validates URLs before tracing. 
function validateUrl(url: string): string
​
url
string
required
Raw URL input from user (may lack protocol or contain whitespace).
​
returns
string
Validated and normalized URL with protocol included.
Transformations:
  • Trims leading/trailing whitespace
  • Removes line breaks and tabs (\r, \n, \t)
  • Adds https:// protocol if missing
  • Returns empty string for empty input
Examples: 
validateUrl("example.com")           // "https://example.com"
validateUrl("http://example.com")    // "http://example.com"
validateUrl("  example.com\n")       // "https://example.com"
validateUrl("")                      // ""

​
cleanTrackingParams()

Removes tracking parameters from URLs to get clean destination URLs. 
function cleanTrackingParams(url: string): string
​
url
string
required
URL potentially containing tracking parameters.
​
returns
string
URL with tracking parameters removed. Falls back to original URL if parsing fails.
Removed parameters:
  • utm_source, utm_medium, utm_campaign, utm_term, utm_content
  • gclid, gclsrc, dclid, gbraid, wbraid
  • fbclid, fb_action_ids, fb_action_types, fb_ref, fb_source
  • mc_cid, mc_eid (MailChimp)
  • _hsenc, _hsmi (HubSpot)
  • vero_conv, vero_id (Vero)
  • mkt_tok (Marketo)
  • igshid, igsh (Instagram)
  • ref_src, ref_url, share, shared
  • _ga, _gl (Google Analytics)
  • s_cid, ncid (Adobe/Omniture)
  • pk_campaign, pk_kwd (Matomo)
Heuristic cleaning: Also removes parameters that match tracking patterns:
  • Long random strings (>20 chars) with alphanumeric values
  • Parameters starting with: track, trk, tid, cid, sid, campaign, etc.
  • Base64-encoded or URL-encoded data blobs
Examples: 
cleanTrackingParams("https://example.com/page?utm_source=email&id=123")
// "https://example.com/page?id=123"

cleanTrackingParams("https://example.com/page?fbclid=xyz123&gclid=abc456")
// "https://example.com/page"

​
Error handling

All functions handle errors gracefully:
  • followRedirects() returns a RedirectChain with error field populated
  • validateUrl() returns empty string for invalid input
  • cleanTrackingParams() returns original URL if parsing fails
See troubleshooting for specific error messages and solutions.

Build docs developers (and LLMs) love

Get started for freeTalk to us