@iann29/rastro 0.4.0 → 0.5.0

package/src/component/reports.ts

@@ -55,6 +55,8 @@ import {
   type RawJourneyEvent,
 } from "./eventStore.js";
 import { isPlainRecord } from "./guards.js";
+import { classifyOrigin } from "./origin.js";
+import { externalReferrer } from "./sanitize.js";
 import {
   affiliateFieldsValidator,
   eventFieldsValidator,
@@ -220,6 +222,11 @@ export const overview = query({
     topMediums: v.array(topItemValidator),
     // Destination hosts of outbound clicks, ranked by clicks.
     topOutbound: v.array(topItemValidator),
+    // The session's origin (origin.ts), ranked like sources: platform ids,
+    // channel ids, and the evidence that decided them.
+    topPlatforms: v.array(topItemValidator),
+    topChannels: v.array(topItemValidator),
+    topEvidence: v.array(topItemValidator),
     metadata: v.object({
       visitors: v.object({
         basis: v.union(
@@ -242,6 +249,9 @@ export const overview = query({
         topGoals: v.literal("goalCompletionVolume"),
         topMediums: breakdownBasisValidator,
         topOutbound: v.literal("eventVolume"),
+        topPlatforms: breakdownBasisValidator,
+        topChannels: breakdownBasisValidator,
+        topEvidence: breakdownBasisValidator,
       }),
       // Since when every site in the request records the medium and outbound
       // slots; null while one of them has not stamped it. A range that starts
@@ -536,6 +546,9 @@ export const overview = query({
       topGoals: top("goal", "eventVolume"),
       topMediums: top("medium", sessionBasis),
       topOutbound: top("outbound", "eventVolume"),
+      topPlatforms: top("platform", sessionBasis),
+      topChannels: top("channel", sessionBasis),
+      topEvidence: top("evidence", sessionBasis),
       metadata: {
         visitors: {
           basis: visitorBasis,
@@ -555,6 +568,9 @@ export const overview = query({
           topGoals: "goalCompletionVolume" as const,
           topMediums: sessionBasis,
           topOutbound: "eventVolume" as const,
+          topPlatforms: sessionBasis,
+          topChannels: sessionBasis,
+          topEvidence: sessionBasis,
         },
         dimensionsSince: controls.every(
           (control) => control?.dimensionsSince !== undefined,
@@ -948,6 +964,27 @@ async function readRouteRollups(
   return { rows, completeFrom: cutAt + DAY_MS };
 }
 
+type SessionRow = Omit<
+  Doc<"sessions">,
+  "geoLookupAttemptedAt" | "lastPageviewAt"
+>;
+
+/**
+ * A session recorded before origins existed, classified on read from what it
+ * kept (utm fields, referrer, affiliate) and marked `legacy`: it carries no
+ * click IDs or in-app signal, and it never enters the aggregates.
+ */
+function withOrigin(session: SessionRow, domains: string[]): SessionRow {
+  if (session.platform !== undefined) return session;
+  const origin = classifyOrigin({
+    utmSource: session.utmSource,
+    utmMedium: session.utmMedium,
+    referrer: externalReferrer(session.referrer, domains),
+    affiliate: session.affiliateSlug !== undefined,
+  });
+  return { ...session, ...origin, evidence: "legacy" };
+}
+
 /** Metadata for a selected session, independent of list pagination. */
 export const getSession = query({
   args: { siteId: v.id("sites"), sessionId: v.string() },
@@ -965,7 +1002,8 @@ export const getSession = query({
       lastPageviewAt: _pageview,
       ...result
     } = session;
-    return result;
+    const site = await ctx.db.get("sites", args.siteId);
+    return withOrigin(result, site?.domains ?? []);
   },
 });
 
@@ -1104,12 +1142,13 @@ export const listSessions = query({
           .take(take)),
       );
     }
+    const site = await ctx.db.get("sites", args.siteId);
     const publicRows = rows.map(
       ({
         geoLookupAttemptedAt: _attemptedAt,
         lastPageviewAt: _lastPageviewAt,
         ...row
-      }) => row,
+      }) => withOrigin(row, site?.domains ?? []),
     );
     return keysetPaginationResult(publicRows, pagination, (row) => ({
       timestamp: row.lastSeenAt,
@@ -1826,6 +1865,7 @@ const coverageDatasetValidator = v.union(
   v.literal("affiliates"),
   v.literal("vitals"),
   v.literal("siteMap"),
+  v.literal("origin"),
 );
 
 export const dataCoverage = query({
@@ -1859,6 +1899,7 @@ export const dataCoverage = query({
       "affiliates",
       "vitals",
       "siteMap",
+      "origin",
     ] as const;
     return {
       siteId: args.siteId,
@@ -2163,7 +2204,26 @@ async function datasetCoverageForRange(
   to: number,
 ) {
   if (dataset === "siteMap") {
-    return siteMapDatasetCoverage(ctx, siteId, from, to);
+    return stampedDatasetCoverage(
+      ctx,
+      siteId,
+      from,
+      to,
+      "siteMapSince",
+      siteMapCoverageDataset,
+    );
+  }
+  // Origins exist in sessions and aggregate slots from the site's stamp, and
+  // the overview reads them from the daily aggregates retention trims.
+  if (dataset === "origin") {
+    return stampedDatasetCoverage(
+      ctx,
+      siteId,
+      from,
+      to,
+      "originSince",
+      "overviewDay",
+    );
   }
   // Vitals have no legacy fallback source; the rollup either covers the range
   // or the coverage states say how much of it exists.
@@ -2205,23 +2265,26 @@ async function datasetCoverageForRange(
 }
 
 /**
- * The site map's coverage without reading its rows: it starts at the site's
- * `siteMapSince` and ends where retention cut it. The report itself may still
- * narrow the window when the range exceeds its row budget.
+ * A stamped dataset's coverage without reading its rows: it starts at the
+ * site's stamp (`siteMapSince`, `originSince`) and ends where retention cut
+ * it. The site map report may still narrow the window when the range exceeds
+ * its row budget.
  */
-async function siteMapDatasetCoverage(
+async function stampedDatasetCoverage(
   ctx: QueryCtx,
   siteId: Id<"sites">,
   from: number,
   to: number,
+  stamp: "siteMapSince" | "originSince",
+  retainedDataset: string,
 ) {
   const control = await ctx.db
     .query("analyticsCoverage")
     .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
     .unique();
-  const since = control?.siteMapSince ?? null;
+  const since = control?.[stamp] ?? null;
   const retainedBefore =
-    control?.retained.find((item) => item.dataset === siteMapCoverageDataset)
+    control?.retained.find((item) => item.dataset === retainedDataset)
       ?.before ?? null;
   const unavailable =
     since === null ||
@@ -2252,7 +2315,8 @@ type PublicCoverageDataset =
   | "funnels"
   | "affiliates"
   | "vitals"
-  | "siteMap";
+  | "siteMap"
+  | "origin";
 
 type CoverageSource =
   | "overviewHour"

package/src/component/sanitize.ts

@@ -10,6 +10,7 @@ import type {
   TrackerEvent,
 } from "./validators.js";
 import { isValidVitalValue, isVitalMetric } from "./vitals.js";
+import { isPlatform, knownClickIds } from "./origin.js";
 
 const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const SAFE_KEY = /^[A-Za-z][A-Za-z0-9_.-]{0,39}$/;
@@ -121,6 +122,27 @@ export function sanitizePublicUrl(value: string): string | undefined {
   }
 }
 
+const ANDROID_PACKAGE = /^[a-z][a-z0-9_]*(?:\.[a-z0-9_]+)+$/;
+
+/**
+ * A referrer as sanitizePublicUrl keeps it, or the Android app that opened
+ * the link: `android-app://<package>/…` keeps the package alone.
+ */
+function sanitizeReferrer(value: string): string | undefined {
+  const input = cleanString(value, 2048);
+  if (!input.toLowerCase().startsWith("android-app://")) {
+    return sanitizePublicUrl(input);
+  }
+  try {
+    const pkg = new URL(input).hostname.toLowerCase();
+    return pkg.length <= 120 && ANDROID_PACKAGE.test(pkg)
+      ? `android-app://${pkg}`
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * The host of a public URL the way the outbound dimension names it: lowercase,
  * without port, path, or query. A relative path has no host.
@@ -229,7 +251,7 @@ export function sanitizeEvent(event: TrackerEvent, now: number): TrackerEvent {
     referrer:
       event.referrer === undefined
         ? undefined
-        : sanitizePublicUrl(event.referrer),
+        : sanitizeReferrer(event.referrer),
     timestamp: Math.trunc(event.timestamp),
     sequence: event.sequence,
     target:
@@ -246,6 +268,7 @@ export function sanitizeEvent(event: TrackerEvent, now: number): TrackerEvent {
       event.type === "vital" && event.value !== undefined
         ? Math.round(event.value)
         : undefined,
+    clid: event.clid === undefined ? undefined : knownClickIds(event.clid),
   };
 }
 
@@ -353,6 +376,8 @@ export function sanitizeContext(
       context?.visitorKey && SAFE_OPAQUE_ID.test(context.visitorKey)
         ? cleanString(context.visitorKey, 128) || undefined
         : undefined,
+    inApp:
+      context?.inApp && isPlatform(context.inApp) ? context.inApp : undefined,
   };
 }
 
@@ -393,6 +418,19 @@ export function sourceFromReferrer(referrer: string | undefined): string {
   }
 }
 
+/**
+ * The referrer unless it is internal: a relative path or one of the site's
+ * own domains never names where a session came from.
+ */
+export function externalReferrer(
+  referrer: string | undefined,
+  domains: string[],
+): string | undefined {
+  if (!referrer || referrer.startsWith("/") || originAllowed(referrer, domains))
+    return undefined;
+  return referrer;
+}
+
 export function stableHash(value: string): number {
   let hash = 2_166_136_261;
   for (let index = 0; index < value.length; index += 1) {

package/src/component/schema.ts

@@ -8,6 +8,7 @@ import {
   goalFieldsValidator,
   sessionFieldsValidator,
   siteFieldsValidator,
+  trackedLinkFieldsValidator,
   visitorSketchValidator,
   vitalMetricValidator,
 } from "./validators.js";
@@ -268,6 +269,8 @@ export default defineSchema({
     localDaySince: v.optional(v.number()),
     // Since when the medium and outbound dimension slots are recorded.
     dimensionsSince: v.optional(v.number()),
+    // Since when sessions carry their origin and the origin slots exist.
+    originSince: v.optional(v.number()),
     retained: v.array(v.object({ dataset: v.string(), before: v.number() })),
     updatedAt: v.number(),
   }).index("by_siteId", ["siteId"]),
@@ -371,6 +374,21 @@ export default defineSchema({
     .index("by_siteId", ["siteId"])
     .index("by_siteId_and_slug", ["siteId", "slug"]),
 
+  // Unique by slug across the deployment: the redirect route names no site.
+  trackedLinks: defineTable(trackedLinkFieldsValidator)
+    .index("by_siteId", ["siteId"])
+    .index("by_slug", ["slug"]),
+
+  // One row per link, UTC day and shard, plus each shard's all-time row
+  // under dayStart 0 (see trackedLinks.ts).
+  trackedLinkClicks: defineTable({
+    linkId: v.id("trackedLinks"),
+    dayStart: v.number(),
+    shard: v.number(),
+    clicks: v.number(),
+    bots: v.number(),
+  }).index("by_linkId_and_dayStart_and_shard", ["linkId", "dayStart", "shard"]),
+
   visitorSecrets: defineTable({
     key: v.literal("current"),
     value: v.string(),

package/src/component/trackedLinks.ts

@@ -0,0 +1,384 @@
+import { v, type Infer } from "convex/values";
+import { internal } from "./_generated/api.js";
+import { internalMutation, mutation, query } from "./_generated/server.js";
+import {
+  DAY_MS,
+  MAX_TRACKED_LINKS_PER_SITE,
+  TRACKED_LINK_CLICK_SHARDS,
+} from "./constants.js";
+import { fail } from "./errors.js";
+import { cleanString, originAllowed, sanitizeOpaqueId } from "./sanitize.js";
+import {
+  trackedLinkChannelValidator,
+  trackedLinkFieldsValidator,
+} from "./validators.js";
+
+const SLUG = /^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/;
+const PLATFORM = /^[a-z0-9_]{2,24}$/;
+const MAX_DESTINATION_LENGTH = 2048;
+const MAX_CAMPAIGN_LENGTH = 64;
+const RECENT_DAYS = 30;
+// Each shard's all-time counter sits beside the daily ones under this day, so
+// a link's total is TRACKED_LINK_CLICK_SHARDS rows however long it has lived.
+const ALL_TIME = 0;
+const PURGE_BATCH = 500;
+
+type Channel = Infer<typeof trackedLinkChannelValidator>;
+
+const trackedLinkDocumentValidator = trackedLinkFieldsValidator.extend({
+  _id: v.id("trackedLinks"),
+  _creationTime: v.number(),
+});
+
+const redirectValidator = trackedLinkFieldsValidator.pick(
+  "slug",
+  "destination",
+  "platform",
+  "channel",
+  "campaign",
+);
+
+export function isTrackedLinkSlug(value: string): boolean {
+  return SLUG.test(value);
+}
+
+/**
+ * Where a click lands: the destination with the link's utm_* appended. A key
+ * the destination already carries wins, and its own query keeps its exact
+ * encoding because the tags are appended as text.
+ */
+export function trackedLinkLocation(
+  link: Infer<typeof redirectValidator>,
+): string {
+  const url = new URL(link.destination);
+  const utm: Array<[string, string]> = [
+    ["utm_source", link.platform],
+    ["utm_medium", link.channel],
+    ["utm_campaign", link.campaign ?? link.slug],
+    ["utm_content", link.slug],
+  ];
+  const tags = new URLSearchParams(
+    utm.filter(([key]) => !url.searchParams.has(key)),
+  ).toString();
+  if (tags) url.search = url.search ? `${url.search}&${tags}` : `?${tags}`;
+  return url.href;
+}
+
+function sanitizeLinkSlug(value: string): string {
+  const slug = value.trim().toLowerCase();
+  if (!isTrackedLinkSlug(slug)) {
+    fail(
+      "INVALID_ARGUMENT",
+      "slug must be 3 to 32 lowercase letters, digits or hyphens, starting and ending with a letter or digit",
+    );
+  }
+  return slug;
+}
+
+function sanitizePlatform(value: string): string {
+  const platform = value.trim().toLowerCase();
+  if (!PLATFORM.test(platform)) {
+    fail(
+      "INVALID_ARGUMENT",
+      "platform must be 2 to 24 lowercase letters, digits or underscores",
+    );
+  }
+  return platform;
+}
+
+function sanitizeCampaign(value: string | undefined): string | undefined {
+  return value === undefined
+    ? undefined
+    : cleanString(value, MAX_CAMPAIGN_LENGTH) || undefined;
+}
+
+// No open redirect: the destination is an absolute http(s) URL on one of the
+// site's own domains, the same rule the ingestion origin check applies.
+function sanitizeDestination(value: string, domains: string[]): string {
+  let url: URL | undefined;
+  try {
+    if (value.length <= MAX_DESTINATION_LENGTH) {
+      url = new URL(cleanString(value, MAX_DESTINATION_LENGTH));
+    }
+  } catch {
+    url = undefined;
+  }
+  if (
+    !url ||
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.username ||
+    url.password
+  ) {
+    fail(
+      "INVALID_ARGUMENT",
+      "destination must be an absolute http(s) URL without credentials",
+    );
+  }
+  if (!originAllowed(url.href, domains)) {
+    fail(
+      "INVALID_ARGUMENT",
+      "destination must be on one of the site's domains",
+    );
+  }
+  return url.href;
+}
+
+export const create = mutation({
+  args: {
+    siteId: v.id("sites"),
+    slug: v.string(),
+    destination: v.string(),
+    platform: v.string(),
+    channel: trackedLinkChannelValidator,
+    campaign: v.optional(v.string()),
+    createdBy: v.string(),
+  },
+  returns: v.id("trackedLinks"),
+  handler: async (ctx, args) => {
+    const site = await ctx.db.get("sites", args.siteId);
+    if (!site) fail("NOT_FOUND", "site not found");
+    const slug = sanitizeLinkSlug(args.slug);
+    const destination = sanitizeDestination(args.destination, site.domains);
+    const platform = sanitizePlatform(args.platform);
+    let createdBy: string;
+    try {
+      createdBy = sanitizeOpaqueId(args.createdBy, "createdBy");
+    } catch (error) {
+      fail(
+        "INVALID_ARGUMENT",
+        error instanceof Error ? error.message : "invalid createdBy",
+      );
+    }
+    const taken = await ctx.db
+      .query("trackedLinks")
+      .withIndex("by_slug", (range) => range.eq("slug", slug))
+      .unique();
+    if (taken) fail("CONFLICT", "another tracked link already uses this slug");
+    const links = await ctx.db
+      .query("trackedLinks")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .take(MAX_TRACKED_LINKS_PER_SITE);
+    if (links.length >= MAX_TRACKED_LINKS_PER_SITE) {
+      fail("LIMIT_EXCEEDED", "tracked link limit reached", {
+        limit: MAX_TRACKED_LINKS_PER_SITE,
+      });
+    }
+    return await ctx.db.insert("trackedLinks", {
+      siteId: args.siteId,
+      slug,
+      destination,
+      platform,
+      channel: args.channel,
+      campaign: sanitizeCampaign(args.campaign),
+      createdAt: Date.now(),
+      createdBy,
+    });
+  },
+});
+
+/** Everything but the slug, which every link already printed carries. */
+export const update = mutation({
+  args: {
+    siteId: v.id("sites"),
+    linkId: v.id("trackedLinks"),
+    destination: v.optional(v.string()),
+    platform: v.optional(v.string()),
+    channel: v.optional(trackedLinkChannelValidator),
+    campaign: v.optional(v.union(v.string(), v.null())),
+    disabled: v.optional(v.boolean()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const link = await ctx.db.get("trackedLinks", args.linkId);
+    if (!link || link.siteId !== args.siteId) {
+      fail("NOT_FOUND", "tracked link not found");
+    }
+    const patch: {
+      destination?: string;
+      platform?: string;
+      channel?: Channel;
+      campaign?: string;
+      disabledAt?: number;
+    } = {};
+    if (args.destination !== undefined) {
+      const site = await ctx.db.get("sites", args.siteId);
+      if (!site) fail("NOT_FOUND", "site not found");
+      patch.destination = sanitizeDestination(args.destination, site.domains);
+    }
+    if (args.platform !== undefined) {
+      patch.platform = sanitizePlatform(args.platform);
+    }
+    if (args.channel !== undefined) patch.channel = args.channel;
+    if (args.campaign !== undefined) {
+      patch.campaign = sanitizeCampaign(args.campaign ?? undefined);
+    }
+    if (args.disabled !== undefined) {
+      patch.disabledAt = args.disabled
+        ? (link.disabledAt ?? Date.now())
+        : undefined;
+    }
+    await ctx.db.patch("trackedLinks", args.linkId, patch);
+    return null;
+  },
+});
+
+export const remove = mutation({
+  args: { siteId: v.id("sites"), linkId: v.id("trackedLinks") },
+  returns: v.null(),
+  handler: async (ctx, args): Promise<null> => {
+    const link = await ctx.db.get("trackedLinks", args.linkId);
+    if (!link || link.siteId !== args.siteId) {
+      fail("NOT_FOUND", "tracked link not found");
+    }
+    await ctx.db.delete("trackedLinks", args.linkId);
+    await ctx.scheduler.runAfter(0, internal.trackedLinks.purgeClicks, {
+      linkId: args.linkId,
+    });
+    return null;
+  },
+});
+
+/**
+ * The site's links, newest first, with their clicks and bot hits: all time,
+ * and over the 30 UTC days ending on the day of `now`. The caller passes the
+ * clock so the subscription does not go stale.
+ */
+export const list = query({
+  args: { siteId: v.id("sites"), now: v.number() },
+  returns: v.array(
+    trackedLinkDocumentValidator.extend({
+      clicks: v.number(),
+      bots: v.number(),
+      clicksLast30Days: v.number(),
+      botsLast30Days: v.number(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    if (!Number.isSafeInteger(args.now) || args.now < RECENT_DAYS * DAY_MS) {
+      fail("INVALID_ARGUMENT", "now must be a Unix time in milliseconds");
+    }
+    const since =
+      Math.floor(args.now / DAY_MS) * DAY_MS - (RECENT_DAYS - 1) * DAY_MS;
+    const links = await ctx.db
+      .query("trackedLinks")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .order("desc")
+      .take(MAX_TRACKED_LINKS_PER_SITE);
+    const sum = (rows: Array<{ clicks: number; bots: number }>) =>
+      rows.reduce(
+        (total, row) => ({
+          clicks: total.clicks + row.clicks,
+          bots: total.bots + row.bots,
+        }),
+        { clicks: 0, bots: 0 },
+      );
+    // Up to 4 + 120 counter rows per link, so a full site of 200 links whose
+    // every link fills every shard every day reads about 24,800 rows, inside
+    // the 32,000 documents a query may read. Raising either cap needs a
+    // finished day's shards folded into one row first.
+    return await Promise.all(
+      links.map(async (link) => {
+        const total = sum(
+          await ctx.db
+            .query("trackedLinkClicks")
+            .withIndex("by_linkId_and_dayStart_and_shard", (range) =>
+              range.eq("linkId", link._id).eq("dayStart", ALL_TIME),
+            )
+            .take(TRACKED_LINK_CLICK_SHARDS),
+        );
+        const recent = sum(
+          await ctx.db
+            .query("trackedLinkClicks")
+            .withIndex("by_linkId_and_dayStart_and_shard", (range) =>
+              range
+                .eq("linkId", link._id)
+                .gte("dayStart", since)
+                .lt("dayStart", since + RECENT_DAYS * DAY_MS),
+            )
+            .take(RECENT_DAYS * TRACKED_LINK_CLICK_SHARDS),
+        );
+        return {
+          ...link,
+          clicks: total.clicks,
+          bots: total.bots,
+          clicksLast30Days: recent.clicks,
+          botsLast30Days: recent.bots,
+        };
+      }),
+    );
+  },
+});
+
+/**
+ * Counts one click on a live link and returns where it goes, or null for an
+ * unknown or disabled slug. Bots are counted apart and never as clicks. The
+ * destination is checked against the site's domains again, so a domain the
+ * site has since dropped stops redirecting.
+ */
+export const recordClick = internalMutation({
+  args: { slug: v.string(), bot: v.boolean() },
+  returns: v.union(redirectValidator, v.null()),
+  handler: async (ctx, args) => {
+    const link = await ctx.db
+      .query("trackedLinks")
+      .withIndex("by_slug", (range) => range.eq("slug", args.slug))
+      .unique();
+    if (!link || link.disabledAt !== undefined) return null;
+    const site = await ctx.db.get("sites", link.siteId);
+    if (!site || !originAllowed(link.destination, site.domains)) return null;
+    const now = Date.now();
+    const shard = Math.floor(Math.random() * TRACKED_LINK_CLICK_SHARDS);
+    for (const dayStart of [Math.floor(now / DAY_MS) * DAY_MS, ALL_TIME]) {
+      const row = await ctx.db
+        .query("trackedLinkClicks")
+        .withIndex("by_linkId_and_dayStart_and_shard", (range) =>
+          range
+            .eq("linkId", link._id)
+            .eq("dayStart", dayStart)
+            .eq("shard", shard),
+        )
+        .unique();
+      if (row) {
+        await ctx.db.patch(
+          "trackedLinkClicks",
+          row._id,
+          args.bot ? { bots: row.bots + 1 } : { clicks: row.clicks + 1 },
+        );
+      } else {
+        await ctx.db.insert("trackedLinkClicks", {
+          linkId: link._id,
+          dayStart,
+          shard,
+          clicks: args.bot ? 0 : 1,
+          bots: args.bot ? 1 : 0,
+        });
+      }
+    }
+    return {
+      slug: link.slug,
+      destination: link.destination,
+      platform: link.platform,
+      channel: link.channel,
+      ...(link.campaign === undefined ? {} : { campaign: link.campaign }),
+    };
+  },
+});
+
+/** Deletes a removed link's counters a batch at a time. */
+export const purgeClicks = internalMutation({
+  args: { linkId: v.id("trackedLinks") },
+  returns: v.null(),
+  handler: async (ctx, args): Promise<null> => {
+    const rows = await ctx.db
+      .query("trackedLinkClicks")
+      .withIndex("by_linkId_and_dayStart_and_shard", (range) =>
+        range.eq("linkId", args.linkId),
+      )
+      .take(PURGE_BATCH);
+    for (const row of rows) await ctx.db.delete("trackedLinkClicks", row._id);
+    if (rows.length === PURGE_BATCH) {
+      await ctx.scheduler.runAfter(0, internal.trackedLinks.purgeClicks, args);
+    }
+    return null;
+  },
+});