UTM Campaign Link Preflight & Fix Pack

Private Apify Actor for marketing operators and agencies who need to check a batch of campaign links before an ad or newsletter send. It audits supplied URLs offline, identifies missing, empty, duplicate, mismatched, mixed-case, fragment-only, unknown, and macro-based UTM conditions, and prepares corrections only when the caller supplies an exact expected contract.

It is deliberately not a generic URL parser. It never visits a destination, resolves DNS, invokes an ad platform, or calls GA4. A READY result means only that this Actor found no unresolved contract finding; it does not prove reachability, tracking, attribution, acceptance, conversion, or ROI.

Input

Submit links with 1–1,000 unique IDs. An expected object is optional. When present it must contain nonempty utm_source, utm_medium, and utm_campaign; the four other canonical fields are optional. Values are exact and case-preserving. The Actor never invents or silently lowercases a value.

{"links":[{"id":"email_launch","url":"https://example.com/offer?sku=A%20B&utm_Source=Old&coupon=x%2By#details","expected":{"utm_source":"newsletter","utm_medium":"email","utm_campaign":"launch"}}]}

Only literal public-looking HTTP(S) URLs are accepted. URL credentials, local/private literal targets, malformed escaping, encoded controls, recognized credential fields, JWT-like values, private-key material, and bounded recognizable bearer/API-key forms are rejected. The credential-field policy runs before correction or output and applies to both query strings and fragments, including OAuth-style #key=value, SPA-style #/callback?key=value, and percent-encoded pairs.

Recognized field names are percent-decoded, stripped of separators, and compared case-insensitively. A fixed vocabulary covers ambiguous OAuth/session/signature names, while credential-family terms such as secret, password, credential, token, apiKey, privateKey, and accessKey are detected anywhere in the normalized name so provider prefixes and suffixes cannot bypass the policy. Consequently signed URLs containing fields such as X-Amz-Credential, X-Amz-Signature, X-Goog-Credential, GoogleAccessId, Policy, or Key-Pair-Id are blocked. This is deliberately conservative: credential-looking business names such as token_count, plus ambiguous fields named code, authCode, or policy, are rejected by default; use a non-credential-specific name such as coupon. Normal fields such as utm_source, sku, coupon, and campaign remain accepted and are preserved byte-for-byte during correction. The policy examines parameter names, not ordinary words in benign values. Detection is intentionally bounded, not universal: unknown secret formats or secrets placed under unknown field names may not be recognized, so users must remove credentials before submission.

Outputs

• OUTPUT: authoritative summary; the default dataset receives exactly one identical record for valid input.
• FIXED_LINKS.csv: private handoff with explicitly authorized proposed URLs.
• REVIEW_REQUIRED.csv: IDs and actionable finding codes.
• REPORT.JSON and REPORT.MD: URL-redacted diagnostics and hashes.
• MANIFEST.JSON: SHA-256 and byte length of the exact stored bytes for every other payload.

proposedUrl may be a partial safe correction while status remains REVIEW_REQUIRED; it must not be treated as send-ready until remainingIssues is empty. Audit-only links never receive invented fixes. Platform macros require manual review and block correction.

Local verification

npm ci --ignore-scripts
npm test
npm run typecheck
npm run build
AUTOMATON_CONTAINER_SMOKE=1 node dist/main.js

The smoke mode is selected only by AUTOMATON_CONTAINER_SMOKE=1; it runs a fixed in-memory three-row demo without network or storage. Production storage traffic is restricted to https://api.apify.com, with redirects disabled, a 30-second timeout, a 2 MiB response bound, and no retry.

See SUPPORT.md for the safe support template and SECURITY_REVIEW.md for the threat model.