feat(links): UTM parameters + branded social-preview cards

[anvme]

Two new features for short links, committed separately so they review independently. Full rationale and design notes are in the commit messages.

1. UTM parameters (b3b65fc)
Optional utm_source/utm_medium/utm_campaign/utm_term/utm_content per link. Merged into the destination URL on click, preserving existing query strings; conflicting UTM keys are overwritten by the link-level value.

2. Branded social-preview cards (0942a22)
When a short link is shared on X, Facebook, LinkedIn, Slack, Discord, WhatsApp, Telegram, or iMessage, the platform crawler now receives an OG card from the Umami domain instead of being 307'd straight to the destination. Card content is auto-derived from the destination's OG tags at create/update time; per-field user override via a new "Customize preview" form section.

New direct dep: undici@^8.2.0 (for the SSRF-hardened Agent + connect.lookup APIs that aren't reachable through Node's global fetch).

Niche-language i18n strings (km-KH, my-MM, fo-FO, mn-MN, si-LK, ta-IN, bn-BD) are best-effort machine-assisted; happy to defer to native speakers.

Docs companion: umami-software/docs#24

[vercel]

@anvme is attempting to deploy a commit to the Umami Software Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Summary

This PR adds two features to the short-links system: UTM parameter injection (merged into the destination URL at redirect time) and branded social-preview cards (an OG HTML page is served to crawlers detected by user-agent, with metadata auto-fetched from the destination at create/update time via a deferred after() backfill).

• UTM parameters: five nullable fields added to the link table; appendQueryParams merges them into the redirect target using URLSearchParams.set (safe encoding); form expands on demand.
• OG preview cards: destination HTML is fetched server-side with an SSRF-hardened undici agent (safeLookup filters DNS results to public IPs only); metadata is written back via per-field updateMany guarded on url + *Manual: false so slow backfills can't clobber newer edits or manual overrides; bot detection gate in the slug route returns an escaped HTML card instead of a 307 for crawlers.
• Schema / validation: shared schemas.ts centralises utmField, ogTitleField, ogDescriptionField, and ogImageField (used by both create and update routes); ogImageField validates user-supplied image URLs against isPublicHttpUrl to block IP-literal private addresses.

Confidence Score: 5/5

The change is safe to merge. SSRF protection is layered (IP-literal validation at schema time + DNS-level filtering in safeLookup + undici ssrfAgent), HTML escaping in renderOgHtml is thorough, OG backfill races are guarded, and the two migrations are purely additive nullable columns.

All new server-side fetch paths go through the undici ssrfAgent with safeLookup filtering, the HTML card renderer escapes every user-controlled value, backfill writes are race-guarded with per-field updateMany conditions, and the two database migrations add only nullable columns with safe defaults. The two observations raised are minor code-hygiene points that do not affect runtime correctness or security.

No files require special attention. The og-preview route has a local isHttpUrl copy that should be replaced with the shared import from schemas.ts, and package.json would benefit from an explicit engines.node field to document the undici >=22.19.0 constraint, but neither blocks merging.

Important Files Changed

Filename	Overview
src/lib/og.ts	New SSRF-hardened OG metadata fetcher using undici with custom DNS lookup guard, body cap, redirect chain validation, and entity decoding. Well-structured with thorough edge-case handling.
src/lib/og-html.ts	New server-side HTML renderer for bot OG cards. All user-controlled values are HTML-escaped; CSP + meta robots prevent abuse. No issues found.
src/app/api/links/og-preview/route.ts	New live-preview endpoint. Auth-gated and SSRF-safe via fetchOgMetadata internals, but re-defines isHttpUrl locally instead of importing from schemas.ts.
src/app/api/links/schemas.ts	New shared Zod schema helpers for UTM and OG fields. Correctly extracted, ogImageField validates against isPublicHttpUrl (IP-literal guard).
src/queries/prisma/link.ts	applyOgIntent cleanly classifies intent synchronously; backfillOgMetadata is race-guarded via per-field updateMany with url+flag where-clause. Redis invalidation covers slug rename and delete.
src/app/(collect)/q/[slug]/route.ts	Bot-detection path correctly returns OG HTML before analytics recording; UTM parameters merged via appendQueryParams before the 307 redirect for real users.
src/app/(main)/links/LinkEditForm.tsx	OgUrlWatcher correctly debounces, aborts stale fetches, and avoids promoting auto values to manual on edit. dirtyFieldsRef gate prevents submitting untouched empty OG fields.
prisma/migrations/22_add_link_og_metadata/migration.sql	Additive nullable OG metadata columns plus three BOOLEAN columns with DEFAULT false. Safe, no backfill needed since all rows start in auto mode.

Sequence Diagram

sequenceDiagram
    participant Client
    participant SlugRoute as /q/[slug]
    participant APIRoute as /api/links
    participant PrismaLink as link.ts (Prisma)
    participant OgFetcher as og.ts (undici)
    participant Destination

    Client->>SlugRoute: "GET /q/{slug}"
    SlugRoute->>PrismaLink: findLink(slug)
    PrismaLink-->>SlugRoute: link row

    alt "Bot (isbot=true)"
        SlugRoute->>SlugRoute: renderOgHtml(link, baseOrigin, target)
        SlugRoute-->>Client: 200 OG HTML (meta refresh to target)
    else Real user
        SlugRoute->>SlugRoute: appendQueryParams(url, UTM fields)
        SlugRoute-->>Client: 307 Redirect to target+UTM
    end

    Note over APIRoute,OgFetcher: On link create/update
    Client->>APIRoute: POST /api/links
    APIRoute->>PrismaLink: createLink / updateLink
    PrismaLink->>PrismaLink: applyOgIntent (sync, sets Manual flags)
    PrismaLink-->>APIRoute: result + before snapshot
    APIRoute-->>Client: 200 (OG fields may be null initially)
    APIRoute->>PrismaLink: after() backfillOgMetadata
    PrismaLink->>OgFetcher: fetchOgMetadata(url)
    OgFetcher->>OgFetcher: safeLookup (DNS to public IPs only)
    OgFetcher->>Destination: GET (undici, 5s timeout, 1MB cap)
    Destination-->>OgFetcher: HTML
    OgFetcher-->>PrismaLink: title, description, image
    PrismaLink->>PrismaLink: "updateMany (guarded on url + Manual=false)"

Loading

_{Reviews (2): Last reviewed commit: "fix(links): defer OG fetch via after(), ..." | Re-trigger Greptile}