feat(links): support optional UTM parameters on short links

Lets users attach utm_source / utm_medium / utm_campaign / utm_term /
utm_content to a short link as structured fields instead of baking them
into the destination URL by hand. UTMs are merged into link.url at
redirect time, preserving any pre-existing query string and overwriting
conflicting UTMs (the structured field is the source of truth).

The form's UTM section is collapsed by default and auto-expands when
editing a link that already has any UTM value set. An empty-string-to-
null Zod transform keeps the DB free of meaningless empty strings.

Adds Redis cache invalidation in createLink/updateLink/deleteLink so
edits to url/slug/UTMs take effect immediately instead of waiting for
the 24h redirect-cache TTL — including a defensive del in createLink
to guard against slug-reuse-after-hard-delete poisoning the cache.

Author: anvme

prisma/migrations/21_add_link_utm_parameters/migration.sql

@@ -0,0 +1,7 @@
+-- AlterTable
+ALTER TABLE "link"
+ADD COLUMN     "utm_source" VARCHAR(255),
+ADD COLUMN     "utm_medium" VARCHAR(255),
+ADD COLUMN     "utm_campaign" VARCHAR(255),
+ADD COLUMN     "utm_term" VARCHAR(255),
+ADD COLUMN     "utm_content" VARCHAR(255);

prisma/schema.prisma

@@ -287,15 +287,20 @@ model Revenue {
 }
 
 model Link {
-  id        String    @id() @map("link_id") @db.Uuid
-  name      String    @db.VarChar(100)
-  url       String    @db.VarChar(500)
-  slug      String    @unique() @db.VarChar(100)
-  userId    String?   @map("user_id") @db.Uuid
-  teamId    String?   @map("team_id") @db.Uuid
-  createdAt DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)
-  updatedAt DateTime? @updatedAt @map("updated_at") @db.Timestamptz(6)
-  deletedAt DateTime? @map("deleted_at") @db.Timestamptz(6)
+  id          String    @id() @map("link_id") @db.Uuid
+  name        String    @db.VarChar(100)
+  url         String    @db.VarChar(500)
+  slug        String    @unique() @db.VarChar(100)
+  utmSource   String?   @map("utm_source") @db.VarChar(255)
+  utmMedium   String?   @map("utm_medium") @db.VarChar(255)
+  utmCampaign String?   @map("utm_campaign") @db.VarChar(255)
+  utmTerm     String?   @map("utm_term") @db.VarChar(255)
+  utmContent  String?   @map("utm_content") @db.VarChar(255)
+  userId      String?   @map("user_id") @db.Uuid
+  teamId      String?   @map("team_id") @db.Uuid
+  createdAt   DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt   DateTime? @updatedAt @map("updated_at") @db.Timestamptz(6)
+  deletedAt   DateTime? @map("deleted_at") @db.Timestamptz(6)
 
   user User? @relation("user", fields: [userId], references: [id])
   team Team? @relation(fields: [teamId], references: [id])

src/app/(collect)/q/[slug]/route.ts

@@ -5,6 +5,7 @@ import { POST } from '@/app/api/send/route';
 import type { Link } from '@/generated/prisma/client';
 import redis from '@/lib/redis';
 import { notFound } from '@/lib/response';
+import { appendQueryParams } from '@/lib/url';
 import { findLink } from '@/queries/prisma';
 
 export async function GET(request: Request, { params }: { params: Promise<{ slug: string }> }) {
@@ -59,5 +60,13 @@ export async function GET(request: Request, { params }: { params: Promise<{ slug
 
   await POST(req);
 
-  return NextResponse.redirect(link.url);
+  const target = appendQueryParams(link.url, {
+    utm_source: link.utmSource,
+    utm_medium: link.utmMedium,
+    utm_campaign: link.utmCampaign,
+    utm_term: link.utmTerm,
+    utm_content: link.utmContent,
+  });
+
+  return NextResponse.redirect(target);
 }

src/app/(main)/links/LinkEditForm.tsx

@@ -11,10 +11,10 @@ import {
   Row,
   TextField,
 } from '@umami/react-zen';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { useConfig, useLinkQuery, useMessages } from '@/components/hooks';
 import { useUpdateQuery } from '@/components/hooks/queries/useUpdateQuery';
-import { RefreshCw } from '@/components/icons';
+import { ChevronDown, RefreshCw } from '@/components/icons';
 import { LINKS_URL } from '@/lib/constants';
 import { getRandomChars } from '@/lib/generate';
 import { isValidUrl } from '@/lib/url';
@@ -46,6 +46,20 @@ export function LinkEditForm({
   const hostUrl = linksUrl || LINKS_URL;
   const { data, isLoading } = useLinkQuery(linkId);
   const [defaultSlug] = useState(generateId());
+  const [utmExpanded, setUtmExpanded] = useState(false);
+
+  useEffect(() => {
+    if (
+      data &&
+      (data.utmSource ||
+        data.utmMedium ||
+        data.utmCampaign ||
+        data.utmTerm ||
+        data.utmContent)
+    ) {
+      setUtmExpanded(true);
+    }
+  }, [data]);
 
   const handleSubmit = async (data: any) => {
     await mutateAsync(data, {
@@ -93,6 +107,38 @@ export function LinkEditForm({
               <TextField placeholder="https://example.com" autoComplete="off" />
             </FormField>
 
+            <Column gap="2">
+              <Button
+                variant="quiet"
+                onPress={() => setUtmExpanded(v => !v)}
+                style={{ alignSelf: 'flex-start' }}
+              >
+                <Icon rotate={utmExpanded ? 180 : 0}>
+                  <ChevronDown />
+                </Icon>
+                {t(labels.utm)}
+              </Button>
+              {utmExpanded && (
+                <>
+                  <FormField label={t(labels.utmSource)} name="utmSource">
+                    <TextField autoComplete="off" maxLength={255} />
+                  </FormField>
+                  <FormField label={t(labels.utmMedium)} name="utmMedium">
+                    <TextField autoComplete="off" maxLength={255} />
+                  </FormField>
+                  <FormField label={t(labels.utmCampaign)} name="utmCampaign">
+                    <TextField autoComplete="off" maxLength={255} />
+                  </FormField>
+                  <FormField label={t(labels.utmTerm)} name="utmTerm">
+                    <TextField autoComplete="off" maxLength={255} />
+                  </FormField>
+                  <FormField label={t(labels.utmContent)} name="utmContent">
+                    <TextField autoComplete="off" maxLength={255} />
+                  </FormField>
+                </>
+              )}
+            </Column>
+
             {cloudMode ? (
               <FormField
                 name="slug"

src/app/api/links/[linkId]/route.ts

@@ -22,11 +22,23 @@ export async function GET(request: Request, { params }: { params: Promise<{ link
   return json(website);
 }
 
+const utmField = z
+  .string()
+  .max(255)
+  .transform(v => (v === '' ? null : v))
+  .nullable()
+  .optional();
+
 export async function POST(request: Request, { params }: { params: Promise<{ linkId: string }> }) {
   const schema = z.object({
     name: z.string().optional(),
     url: z.string().optional(),
     slug: z.string().min(8).optional(),
+    utmSource: utmField,
+    utmMedium: utmField,
+    utmCampaign: utmField,
+    utmTerm: utmField,
+    utmContent: utmField,
   });
 
   const { auth, body, error } = await parseRequest(request, schema);
@@ -36,14 +48,23 @@ export async function POST(request: Request, { params }: { params: Promise<{ lin
   }
 
   const { linkId } = await params;
-  const { name, url, slug } = body;
+  const { name, url, slug, utmSource, utmMedium, utmCampaign, utmTerm, utmContent } = body;
 
   if (!(await canUpdateLink(auth, linkId))) {
     return unauthorized();
   }
 
   try {
-    const result = await updateLink(linkId, { name, url, slug });
+    const result = await updateLink(linkId, {
+      name,
+      url,
+      slug,
+      utmSource,
+      utmMedium,
+      utmCampaign,
+      utmTerm,
+      utmContent,
+    });
 
     return Response.json(result);
   } catch (e: any) {

src/app/api/links/route.ts

@@ -26,13 +26,25 @@ export async function GET(request: Request) {
   return json(links);
 }
 
+const utmField = z
+  .string()
+  .max(255)
+  .transform(v => (v === '' ? null : v))
+  .nullable()
+  .optional();
+
 export async function POST(request: Request) {
   const schema = z.object({
     name: z.string().max(100),
     url: z.string().max(500),
     slug: z.string().max(100),
     teamId: z.string().nullable().optional(),
     id: z.uuid().nullable().optional(),
+    utmSource: utmField,
+    utmMedium: utmField,
+    utmCampaign: utmField,
+    utmTerm: utmField,
+    utmContent: utmField,
   });
 
   const { auth, body, error } = await parseRequest(request, schema);
@@ -41,7 +53,8 @@ export async function POST(request: Request) {
     return error();
   }
 
-  const { id, name, url, slug, teamId } = body;
+  const { id, name, url, slug, teamId, utmSource, utmMedium, utmCampaign, utmTerm, utmContent } =
+    body;
 
   if ((teamId && !(await canCreateTeamWebsite(auth, teamId))) || !(await canCreateWebsite(auth))) {
     return unauthorized();
@@ -53,6 +66,11 @@ export async function POST(request: Request) {
     url,
     slug,
     teamId,
+    utmSource,
+    utmMedium,
+    utmCampaign,
+    utmTerm,
+    utmContent,
   };
 
   if (!teamId) {

src/lib/url.ts

@@ -47,3 +47,19 @@ export function isValidUrl(url: string) {
     return false;
   }
 }
+
+export function appendQueryParams(
+  url: string,
+  params: Record<string, string | null | undefined>,
+): string {
+  const entries = Object.entries(params).filter(([, v]) => v != null && v !== '');
+  if (entries.length === 0) return url;
+
+  try {
+    const u = new URL(url);
+    for (const [k, v] of entries) u.searchParams.set(k, v as string);
+    return u.toString();
+  } catch {
+    return url;
+  }
+}

src/queries/prisma/link.ts

@@ -1,5 +1,6 @@
 import type { Prisma } from '@/generated/prisma/client';
 import prisma from '@/lib/prisma';
+import redis from '@/lib/redis';
 import { sanitizeSortFilters } from '@/lib/sort';
 import type { QueryFilters } from '@/lib/types';
 
@@ -58,13 +59,50 @@ export async function getTeamLinks(teamId: string, filters?: QueryFilters) {
 }
 
 export async function createLink(data: Prisma.LinkUncheckedCreateInput) {
-  return prisma.client.link.create({ data });
+  const result = await prisma.client.link.create({ data });
+
+  // Defensive: a slug may be reused after a hard-delete and the redirect cache
+  // for that slug can still hold the old link's URL for up to 24h.
+  if (redis.enabled && result.slug) {
+    await redis.client.del(`link:${result.slug}`);
+  }
+
+  return result;
 }
 
 export async function updateLink(linkId: string, data: any) {
-  return prisma.client.link.update({ where: { id: linkId }, data });
+  const before = redis.enabled
+    ? await prisma.client.link.findUnique({
+        where: { id: linkId },
+        select: { slug: true },
+      })
+    : null;
+
+  const result = await prisma.client.link.update({ where: { id: linkId }, data });
+
+  if (redis.enabled) {
+    if (before?.slug) await redis.client.del(`link:${before.slug}`);
+    if (result.slug && result.slug !== before?.slug) {
+      await redis.client.del(`link:${result.slug}`);
+    }
+  }
+
+  return result;
 }
 
 export async function deleteLink(linkId: string) {
-  return prisma.client.link.delete({ where: { id: linkId } });
+  const before = redis.enabled
+    ? await prisma.client.link.findUnique({
+        where: { id: linkId },
+        select: { slug: true },
+      })
+    : null;
+
+  const result = await prisma.client.link.delete({ where: { id: linkId } });
+
+  if (redis.enabled && before?.slug) {
+    await redis.client.del(`link:${before.slug}`);
+  }
+
+  return result;
 }