@iann29/rastro 0.4.0 → 0.6.0

package/llms.txt

@@ -1,6 +1,6 @@
 # Amage Rastro
 
-> Privacy-first, real-time web analytics for Convex. Telemetry stays in each product's Convex or Synapse deployment; the central dashboard reads only an explicitly granted report surface, and configures a site only when its host's grant opts into the configure scope.
+> Real-time product and web analytics: identified people, journeys, conversions and retention on Convex. Telemetry stays in each product's Convex or Synapse deployment; the central dashboard reads only an explicitly granted report surface, and configures a site only when its host's grant opts into the configure scope.
 
 Canonical documentation: https://www.amagerastro.com/docs/
 Machine manifest: https://www.amagerastro.com/agent/manifest.json
@@ -16,6 +16,8 @@ Do not infer federation availability from this website, a dist-tag, or a source
 ## Architecture
 
 - Tracker and telemetry: browser -> customer HTTP-actions URL -> customer Rastro component.
+- The tracker is 2,999 bytes raw and 1,565 gzip. It sends the click-ID key **names** of the landing URL in `clid` (`gclid`, `fbclid`, `ttclid`…), at most eight, never a value, and the referrer as scheme and host, so an `android-app://<package>` referrer keeps its package.
+- Tracked links (0.5.0+): browser -> customer HTTP-actions URL `/rastro/l/<slug>` -> `302` (`Cache-Control: no-store`) to a destination on one of the site's domains, with `utm_source` (platform), `utm_medium` (channel), `utm_campaign` (campaign, or the slug) and `utm_content` (slug) appended; the destination's own query and `utm_*` keys stay. Unknown or disabled slug: `404`. Clicks count in four-shard daily counters; self-declared bots are redirected and counted apart.
 - Optional field Web Vitals (alpha.6+): a second browser module at `/rastro/vitals.js` reports LCP, CLS, INP, FCP, and TTFB to the same events endpoint, into bounded daily histograms; it needs the base tracker on the page.
 - Reactive dashboard reads: amagerastro.com browser -> customer functions URL -> `rastroFederation:*`.
 - Control plane: account, organization, connection metadata, short-lived token issuance, and revocation.
@@ -30,7 +32,8 @@ Do not infer federation availability from this website, a dist-tag, or a source
 - Resolve an indexed, authoritative local grant on every federated query.
 - Grant one through ten explicit site IDs. Never grant by owner-wide enumeration.
 - Use the canonical module name `convex/rastroFederation.ts`.
-- Expose only the manifest, connection status, site summaries, reports, journeys, conversions, affiliates, funnels, goals, web vitals, coverage, and the configure functions listed in the manifest; the configure functions run only when the token and the local grant both carry `analytics:configure`. A public link's token carries `analytics:public` alone and reaches only the manifest, connection status, site summaries, a redacted overview, redacted live visitors, and coverage, and only when the local grant lists `analytics:public`.
+- A host on 0.5.0 re-exports `listTrackedLinks`, `createTrackedLink`, `updateTrackedLink` and `deleteTrackedLink` from that module and reverifies, which advertises the optional `trackedLinks` capability; listing needs a reader, the other three need `analytics:configure`. A host that skips it keeps working without the capability.
+- Expose only the manifest, connection status, site summaries, reports, journeys, conversions, affiliates, funnels, goals, web vitals, coverage, tracked links, and the configure functions listed in the manifest; the configure functions run only when the token and the local grant both carry `analytics:configure`. A public link's token carries `analytics:public` alone and reaches only the manifest, connection status, site summaries, a redacted overview, redacted live visitors, and coverage, and only when the local grant lists `analytics:public`.
 - Use the functions URL as JWT audience and the HTTP-actions URL for tracker ingestion.
 - Rehearse on an explicit development target. Production changes require fresh operator consent.
 - Validate manifest, authenticated connection status, redacted site list, real ingestion, reactive live data, and local-first revocation.
@@ -55,6 +58,7 @@ Do not infer federation availability from this website, a dist-tag, or a source
 - Vitals report maximum: 90 complete UTC days; `vitals` is an optional capability that hosts before `alpha.6` do not advertise.
 - Site map maximum: 90 complete UTC days, read newest day first within 8,000 route rows; older days it could not read are declared as partial coverage. `siteMap` is an optional capability that hosts before `alpha.8` do not advertise, and its data starts at the first ingest after that upgrade.
 - Maximum live visitors: 500.
+- Tracked links: at most 200 per site; slugs are 3–32 lowercase letters, digits or hyphens, unique across the deployment; `listTrackedLinks` reports clicks and bots all time and over the 30 UTC days ending on the `now` it is given. `trackedLinks` is an optional capability that hosts before 0.5.0, and hosts that did not re-export the four functions, do not advertise.
 - Live window: the tracker sends a `leave` when the tab hides or the page unloads, retiring the visitor about ten seconds later; a shown tab or a bfcache return sends a heartbeat at once and revives them. The safety net without a goodbye is 90 seconds since the last event or heartbeat. `POST /rastro/events` re-anchors a batch whose `sentAt` is more than 30 seconds from server time, so a wrong device clock decides neither liveness nor hour buckets.
 - Maximum journey events: 500.
 - Token lifetime: 10 minutes, RS256. Every member's token carries `analytics:read`; owners and admins also carry `analytics:configure`, which the host honors only when the local grant lists it (`configure` is an optional capability that hosts before `alpha.11` do not advertise). A public link's token carries `analytics:public` alone, plus `rastro_site_ids` naming the link's sites; hosts before `0.1.0` reject it.
@@ -62,6 +66,7 @@ Do not infer federation availability from this website, a dist-tag, or a source
 ## Read semantics
 
 - Times are inclusive Unix epoch milliseconds in UTC.
+- Origin (0.5.0+): a session is classified once, on its first touch, into `platform` (about forty ids), `channel` (twelve, `direct` to `ai` plus `offline`) and `evidence`, the rule that decided it. Decision order, first match wins: declared `utm_source`, click-ID name, referrer host by whole label, in-app browser, affiliate `ref`; nothing at all is the only way to be `direct`. `overview.topPlatforms`, `topChannels` and `topEvidence` rank them beside `topSources`; a `topPlatforms` value is the bare platform id for its default channel and `platform@channel` otherwise. `dataCoverage`'s `origin` dataset says from when a site carries origins; older sessions are classified on read, marked `evidence: "legacy"`, and never enter the aggregates. `source` is unchanged.
 - Goal, funnel, and affiliate reports include read-only definitions plus aggregates. Configuration writes (goals, funnels, affiliates, a site's name/domains/timezone, retention) exist only in the configure scope and fail with `FEDERATION_CONFIGURE_FORBIDDEN` for a read-only token or grant; `listSites` never returns domains, only `siteSettings` does, to a connection allowed to change them.
 - A public token (`analytics:public`) gets `overview` with zero `conversions` and `revenueCents` and empty `topCampaigns`, `topMediums`, `topEvents`, and `topGoals`, `liveVisitors` with `visitorId` equal to `sessionId` and without `entryPath`, `returning`, `utmCampaign`, `affiliateSlug`, `conversionCount`, or `funnel`, and `FEDERATION_PUBLIC_FORBIDDEN` for sessions, journeys, conversions, goals, funnels, affiliates, vitals, the site map, and the configure scope.
 - Session and visitor journeys include bounded custom properties. Hosts must never place personal data or secrets in event properties.
@@ -71,3 +76,7 @@ Do not infer federation availability from this website, a dist-tag, or a source
 - `dataCoverage` echoes the authorized site ID but returns no event, visitor, or session IDs.
 - `vitalsReport` returns p75, averages, and exact good/needs-improvement/poor counts per metric, page, and device — never individual measurements.
 - `siteMap` returns per-route totals (pageviews, estimated visitors, entries, derived exits and bounces, time on page) and route-to-route transition counts, with numeric, UUID, and long hexadecimal segments collapsed to `:id` — never sessions, visitor IDs, or query strings. `liveVisitors` adds `previousPath` and `movedAt` when a visitor moves between routes, and since 0.1.0 the intent facts of the session — `entryPath`, `returning`, `utmCampaign`, `affiliateSlug`, `conversionCount`, and the furthest `funnel` step — which `visitorHeat` from the package turns into the dashboard's hot/warm/cold score.
+
+## People and identity (0.6.0+)
+
+Use the [identity guide](https://www.amagerastro.com/docs/reference/identity.md) for Better Auth, custom Convex auth and authenticated HTTP from other backends. `Rastro.identifyVisitorMutation` resolves the current user on the host; `identifyVisitorHttpAction` authorizes external servers. `getVisitorProfile` requires reader access and is advertised as `visitorProfiles`. `listPeople` adds the optional `people` directory with indexed name/email/ID prefix search and exact filters on project-defined string, number or boolean attributes. Existing profiles need the bounded host-authorized search backfill described in the guide. The browser applies the returned ID with `identify` and calls `reset` on logout.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@iann29/rastro",
-  "description": "Privacy-first, real-time web analytics for Convex: live visitor atlas, journeys, revenue, goals, funnels, affiliates, and a 1.1 KB tracker.",
+  "description": "Real-time product and web analytics for Convex: identified people, journeys, revenue, goals, funnels, affiliates, and a lightweight browser tracker.",
   "repository": "github:amageweb/amage-rastro",
   "homepage": "https://github.com/amageweb/amage-rastro#readme",
   "bugs": {
     "url": "https://github.com/amageweb/amage-rastro/issues"
   },
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -16,7 +16,7 @@
     "convex-component",
     "analytics",
     "realtime",
-    "privacy",
+    "product-analytics",
     "cookieless",
     "session-journey",
     "conversion-tracking",
@@ -46,6 +46,7 @@
     "typecheck": "tsc --noEmit && tsc -p control-plane && tsc -p control-plane/convex && tsc -p example/convex",
     "lint": "eslint .",
     "test": "vitest run --typecheck",
+    "test:layout": "playwright test -c control-plane/playwright.layout.config.ts",
     "test:watch": "vitest --typecheck --clearScreen false",
     "test:debug": "vitest --inspect-brk --no-file-parallelism",
     "test:coverage": "vitest run --coverage --coverage.reporter=text",
@@ -68,6 +69,7 @@
     "docs/federation.md",
     "docs/federation-setup.md",
     "docs/upgrading.md",
+    "docs/identity.md",
     "docs/benchmarks/*.md",
     "assets/rastro-live-atlas.png"
   ],

package/src/component/_generated/api.ts

@@ -24,12 +24,16 @@ import type * as identity from "../identity.js";
 import type * as ingest from "../ingest.js";
 import type * as live from "../live.js";
 import type * as localTime from "../localTime.js";
+import type * as origin from "../origin.js";
+import type * as people from "../people.js";
+import type * as platforms from "../platforms.js";
 import type * as reports from "../reports.js";
 import type * as retention from "../retention.js";
 import type * as rollupStore from "../rollupStore.js";
 import type * as rollups from "../rollups.js";
 import type * as sanitize from "../sanitize.js";
 import type * as sites from "../sites.js";
+import type * as trackedLinks from "../trackedLinks.js";
 import type * as useragent from "../useragent.js";
 import type * as validators from "../validators.js";
 import type * as visitors from "../visitors.js";
@@ -59,12 +63,16 @@ const fullApi: ApiFromModules<{
   ingest: typeof ingest;
   live: typeof live;
   localTime: typeof localTime;
+  origin: typeof origin;
+  people: typeof people;
+  platforms: typeof platforms;
   reports: typeof reports;
   retention: typeof retention;
   rollupStore: typeof rollupStore;
   rollups: typeof rollups;
   sanitize: typeof sanitize;
   sites: typeof sites;
+  trackedLinks: typeof trackedLinks;
   useragent: typeof useragent;
   validators: typeof validators;
   visitors: typeof visitors;

package/src/component/_generated/component.ts

@@ -183,6 +183,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             city?: string;
             country?: string;
             device?: string;
+            inApp?: string;
             latitude?: number;
             longitude?: number;
             os?: string;
@@ -190,6 +191,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           };
           events: Array<{
             affiliateSlug?: string;
+            clid?: Array<string>;
             currency?: string;
             eventId: string;
             href?: string;
@@ -239,6 +241,46 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Name
       >;
     };
+    people: {
+      backfillSearch: FunctionReference<
+        "mutation",
+        "internal",
+        { siteId: string },
+        { isDone: boolean; updated: number },
+        Name
+      >;
+      list: FunctionReference<
+        "query",
+        "internal",
+        {
+          filter?:
+            | { field: "name" | "email" | "visitorId"; prefix: string }
+            | {
+                field: "attribute";
+                key: string;
+                value: string | number | boolean;
+              };
+          paginationOpts: { cursor: string | null; numItems: number };
+          siteId: string;
+        },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{
+            _creationTime: number;
+            _id: string;
+            attributes?: Record<string, string | number | boolean>;
+            email?: string;
+            identifiedAt: number;
+            name?: string;
+            siteId: string;
+            updatedAt: number;
+            visitorId: string;
+          }>;
+        },
+        Name
+      >;
+    };
     reports: {
       affiliatesReport: FunctionReference<
         "query",
@@ -310,7 +352,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               | "funnels"
               | "affiliates"
               | "vitals"
-              | "siteMap";
+              | "siteMap"
+              | "origin";
           }>;
           from: number;
           siteId: string;
@@ -375,6 +418,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           affiliateId?: string;
           affiliateSlug?: string;
           browser: string;
+          channel?:
+            | "direct"
+            | "organic_search"
+            | "paid_search"
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "ai"
+            | "display"
+            | "referral"
+            | "offline";
           city?: string;
           conversionCount: number;
           country?: string;
@@ -383,6 +439,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           durationMs: number;
           entryPath: string;
           eventCount: number;
+          evidence?:
+            | "utm"
+            | "clickId"
+            | "referrer"
+            | "inApp"
+            | "affiliate"
+            | "none"
+            | "legacy";
           exitPath: string;
           lastSeenAt: number;
           latitude?: number;
@@ -390,6 +454,15 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           newVisitor?: boolean;
           os: string;
           pageviewCount: number;
+          platform?: string;
+          profile?: {
+            attributes?: Record<string, string | number | boolean>;
+            email?: string;
+            identifiedAt: number;
+            name?: string;
+            updatedAt: number;
+            visitorId: string;
+          };
           referrer?: string;
           revenueCents: number;
           sessionId: string;
@@ -513,6 +586,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             affiliateId?: string;
             affiliateSlug?: string;
             browser: string;
+            channel?:
+              | "direct"
+              | "organic_search"
+              | "paid_search"
+              | "organic_social"
+              | "paid_social"
+              | "messaging"
+              | "email"
+              | "affiliate"
+              | "ai"
+              | "display"
+              | "referral"
+              | "offline";
             city?: string;
             conversionCount: number;
             country?: string;
@@ -521,6 +607,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             durationMs: number;
             entryPath: string;
             eventCount: number;
+            evidence?:
+              | "utm"
+              | "clickId"
+              | "referrer"
+              | "inApp"
+              | "affiliate"
+              | "none"
+              | "legacy";
             exitPath: string;
             lastSeenAt: number;
             latitude?: number;
@@ -528,6 +622,15 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             newVisitor?: boolean;
             os: string;
             pageviewCount: number;
+            platform?: string;
+            profile?: {
+              attributes?: Record<string, string | number | boolean>;
+              email?: string;
+              identifiedAt: number;
+              name?: string;
+              updatedAt: number;
+              visitorId: string;
+            };
             referrer?: string;
             revenueCents: number;
             sessionId: string;
@@ -570,6 +673,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           pageviewCount: number;
           path: string;
           previousPath?: string;
+          profile?: {
+            attributes?: Record<string, string | number | boolean>;
+            email?: string;
+            identifiedAt: number;
+            name?: string;
+            updatedAt: number;
+            visitorId: string;
+          };
           returning?: boolean;
           sessionId: string;
           siteId: string;
@@ -597,13 +708,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             breakdowns: {
               topBrowsers: "pageviews" | "sessions" | "eventVolume";
               topCampaigns: "pageviews" | "sessions" | "eventVolume";
+              topChannels: "pageviews" | "sessions" | "eventVolume";
               topCountries: "pageviews" | "sessions" | "eventVolume";
               topDevices: "pageviews" | "sessions" | "eventVolume";
               topEvents: "eventVolume";
+              topEvidence: "pageviews" | "sessions" | "eventVolume";
               topGoals: "goalCompletionVolume";
               topMediums: "pageviews" | "sessions" | "eventVolume";
               topOutbound: "eventVolume";
               topPages: "pageviews" | "sessions" | "eventVolume";
+              topPlatforms: "pageviews" | "sessions" | "eventVolume";
               topSources: "pageviews" | "sessions" | "eventVolume";
             };
             coverage: {
@@ -661,6 +775,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number;
             value: string;
           }>;
+          topChannels: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
           topCountries: Array<{
             count: number;
             revenueCents: number;
@@ -676,6 +795,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number;
             value: string;
           }>;
+          topEvidence: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
           topGoals: Array<{
             count: number;
             revenueCents: number;
@@ -696,6 +820,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number;
             value: string;
           }>;
+          topPlatforms: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
           topSources: Array<{
             count: number;
             revenueCents: number;
@@ -1140,7 +1269,128 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Name
       >;
     };
+    trackedLinks: {
+      create: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          campaign?: string;
+          channel:
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "display"
+            | "referral"
+            | "offline";
+          createdBy: string;
+          destination: string;
+          platform: string;
+          siteId: string;
+          slug: string;
+        },
+        string,
+        Name
+      >;
+      list: FunctionReference<
+        "query",
+        "internal",
+        { now: number; siteId: string },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          bots: number;
+          botsLast30Days: number;
+          campaign?: string;
+          channel:
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "display"
+            | "referral"
+            | "offline";
+          clicks: number;
+          clicksLast30Days: number;
+          createdAt: number;
+          createdBy: string;
+          destination: string;
+          disabledAt?: number;
+          platform: string;
+          siteId: string;
+          slug: string;
+        }>,
+        Name
+      >;
+      remove: FunctionReference<
+        "mutation",
+        "internal",
+        { linkId: string; siteId: string },
+        null,
+        Name
+      >;
+      update: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          campaign?: string | null;
+          channel?:
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "display"
+            | "referral"
+            | "offline";
+          destination?: string;
+          disabled?: boolean;
+          linkId: string;
+          platform?: string;
+          siteId: string;
+        },
+        null,
+        Name
+      >;
+    };
     visitors: {
+      getProfile: FunctionReference<
+        "query",
+        "internal",
+        { siteId: string; visitorId: string },
+        {
+          attributes?: Record<string, string | number | boolean>;
+          email?: string;
+          identifiedAt: number;
+          name?: string;
+          updatedAt: number;
+          visitorId: string;
+        } | null,
+        Name
+      >;
+      identify: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          attributes?: Record<string, string | number | boolean | null>;
+          email?: string | null;
+          name?: string | null;
+          previousVisitorId?: string;
+          siteId: string;
+          visitorId: string;
+        },
+        {
+          attributes?: Record<string, string | number | boolean>;
+          email?: string;
+          identifiedAt: number;
+          name?: string;
+          updatedAt: number;
+          visitorId: string;
+        },
+        Name
+      >;
       link: FunctionReference<
         "mutation",
         "internal",

package/src/component/constants.ts

@@ -31,6 +31,13 @@ export const MAX_SITES_PER_OWNER = 100;
 export const MAX_GOALS_PER_SITE = 50;
 export const MAX_FUNNELS_PER_SITE = 20;
 export const MAX_AFFILIATES_PER_SITE = 100;
+export const MAX_TRACKED_LINKS_PER_SITE = 200;
+// A tracked link's clicks spread over this many counter rows, so a link that
+// goes viral writes at four times one document's rate. Four and not more
+// because every shard is read back: the list reads a link's all-time shards
+// plus its last 30 days, and a full site of 200 links must stay under the
+// 32,000 documents a query may read (see trackedLinks.ts).
+export const TRACKED_LINK_CLICK_SHARDS = 4;
 export const MAX_FUNNEL_STEPS = 10;
 export const MAX_PROPERTIES = 16;
 export const MAX_REPORT_SITES = 10;

package/src/component/coverage.ts

@@ -17,12 +17,14 @@ export async function ensureAnalyticsControl(
     // first ingest after the upgrade, with the same safety delay as rollups:
     // the site map rows, and the alpha.11 counters (pageviews and sessions
     // per dimension slot; duration, continued sessions and new visitors per
-    // bucket), and the 0.1.0 dimensions (utm_medium and outbound hosts).
+    // bucket), the 0.1.0 dimensions (utm_medium and outbound hosts), and
+    // the session origins (platform, channel and evidence).
     const stamps: {
       siteMapSince?: number;
       countersSince?: number;
       localDaySince?: number;
       dimensionsSince?: number;
+      originSince?: number;
     } = {};
     if (existing.siteMapSince === undefined) {
       stamps.siteMapSince = now + ROLLUP_SAFETY_DELAY_MS;
@@ -36,6 +38,9 @@ export async function ensureAnalyticsControl(
     if (existing.dimensionsSince === undefined) {
       stamps.dimensionsSince = now + ROLLUP_SAFETY_DELAY_MS;
     }
+    if (existing.originSince === undefined) {
+      stamps.originSince = now + ROLLUP_SAFETY_DELAY_MS;
+    }
     if (Object.keys(stamps).length === 0) return existing;
     await ctx.db.patch("analyticsCoverage", existing._id, {
       ...stamps,
@@ -51,6 +56,7 @@ export async function ensureAnalyticsControl(
     countersSince: now + ROLLUP_SAFETY_DELAY_MS,
     localDaySince: now + ROLLUP_SAFETY_DELAY_MS,
     dimensionsSince: now + ROLLUP_SAFETY_DELAY_MS,
+    originSince: now + ROLLUP_SAFETY_DELAY_MS,
     retained,
     updatedAt: now,
   };

package/src/component/http.ts

@@ -21,7 +21,9 @@ import {
 import { isPlainRecord } from "./guards.js";
 import { alignClock, sanitizeEvent } from "./sanitize.js";
 import { deriveClientKey, deriveVisitorKey, randomSecret } from "./identity.js";
-import { classifyClient, isKnownBot } from "./useragent.js";
+import { isTrackedLinkSlug, trackedLinkLocation } from "./trackedLinks.js";
+import { classifyClient, inAppPlatform, isKnownBot } from "./useragent.js";
+import { knownClickIds } from "./origin.js";
 import type { TrackerEvent } from "./validators.js";
 import {
   RASTRO_VERSION,
@@ -174,9 +176,11 @@ http.route({
             userAgent,
           })
         : undefined;
+    const inApp = inAppPlatform(userAgent);
     const context = {
       ...edgeGeo,
       ...classifyClient(userAgent, request.headers),
+      ...(inApp ? { inApp } : {}),
       ...(visitorKey ? { visitorKey } : {}),
     };
     // Origin is a browser control: any other sender writes the header it
@@ -304,6 +308,46 @@ http.route({
   ),
 });
 
+// A tracked link. The click is counted — as a bot when the agent says it is
+// one, so link unfurlers never inflate the clicks but still get the page — and
+// the visitor goes on with the link's utm_* appended. Unknown and disabled
+// slugs answer 404.
+http.route({
+  pathPrefix: "/l/",
+  method: "GET",
+  handler: httpAction(async (ctx, request) => {
+    const slug = (
+      new URL(request.url).pathname.split("/").filter(Boolean).pop() ?? ""
+    ).toLowerCase();
+    const link = isTrackedLinkSlug(slug)
+      ? await ctx.runMutation(internal.trackedLinks.recordClick, {
+          slug,
+          bot: isKnownBot(
+            (await readRequestMetadata(ctx)).userAgent ??
+              request.headers.get("user-agent") ??
+              "",
+          ),
+        })
+      : null;
+    if (!link) {
+      return new Response("Not found", {
+        status: 404,
+        headers: {
+          "Content-Type": "text/plain; charset=utf-8",
+          "Cache-Control": "no-store",
+        },
+      });
+    }
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: trackedLinkLocation(link),
+        "Cache-Control": "no-store",
+      },
+    });
+  }),
+});
+
 http.route({
   path: "/health",
   method: "GET",
@@ -434,6 +478,7 @@ function parseEvent(value: unknown): TrackerEvent {
     throw new Error("event is missing required fields");
   }
   const properties = parseProperties(value.properties);
+  const clid = parseClickIds(value.clid);
   return {
     eventId: value.eventId,
     sessionId: value.sessionId,
@@ -467,9 +512,19 @@ function parseEvent(value: unknown): TrackerEvent {
     ...(optionalNumber(value.value, "value") !== undefined
       ? { value: optionalNumber(value.value, "value") }
       : {}),
+    ...(clid ? { clid } : {}),
   };
 }
 
+/** Click-ID key names: unknown keys are dropped, never a reason to reject. */
+function parseClickIds(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.some((key) => typeof key !== "string")) {
+    throw new Error("clid must be an array of strings");
+  }
+  return knownClickIds(value as string[]);
+}
+
 function parseProperties(value: unknown): TrackerEvent["properties"] {
   if (value === undefined) return undefined;
   if (!isPlainRecord(value)) throw new Error("properties must be an object");