@iann29/rastro 0.3.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 Privacy-first, real-time web analytics built as an isolated Convex component.
 
-Amage Rastro combines a 1.1 KB gzip browser tracker with reactive traffic
+Amage Rastro combines a 1.4 KB gzip browser tracker with reactive traffic
 metrics, a live visitor atlas, journey timelines, trusted payment attribution,
 goals, funnels, affiliates, and multi-site reports. Data and functions stay
 inside your Convex deployment.
@@ -42,7 +42,7 @@ capacity claim.
 
 | Capability                  | Implementation                                                                                            |
 | --------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Live visitor map            | Reactive live sessions with city-level coordinates, realtime departures, and a 90-second safety net       |
+| Live visitor map            | Reactive live sessions with city-level coordinates; hidden or closed tabs leave in 10 s, crashes in 90 s  |
 | Traffic analytics           | Sharded hour/day rollups, time series, top pages, sources, countries, devices, browsers, and events       |
 | Field Web Vitals            | Opt-in tracker module reporting LCP, CLS, INP, FCP, and TTFB into bounded per-page daily histograms       |
 | Site map                    | Daily per-route rollups: entries, derived exits and bounces, time on page, and route-to-route transitions |
@@ -54,8 +54,8 @@ capacity claim.
 | Automatic GeoIP             | Opt-in native request metadata plus IPinfo/IPWhois fallback; bounded quota and no raw-IP persistence      |
 | Auto-captured clicks        | Anchors, buttons, and `data-rastro-event` controls with a bounded visible label; outbound origin+path     |
 | Bot filtering               | Self-declared crawlers, unfurlers, monitors, HTTP libraries, and headless browsers rejected at ingestion  |
-| Cookieless mode             | No cookies: persistent pseudonymous visitor id in `localStorage`, per-tab session id in `sessionStorage`  |
-| Tiny tracker                | 2,132 bytes raw, 1,127 bytes gzip; the test suite enforces `< 1,280` bytes gzip                           |
+| Cookieless mode             | No cookies: pseudonymous visitor id in `localStorage`; sessions end after 30 idle minutes or a sign-in    |
+| Tiny tracker                | 2,594 bytes raw, 1,395 bytes gzip; the test suite enforces `< 1,400` bytes gzip                           |
 
 ## Quickstart
 
@@ -82,7 +82,7 @@ Never append `/rastro/tracker.js` to the functions URL.
 npm install @iann29/rastro
 ```
 
-The untagged npm `latest` channel is `0.3.0`. Pin the exact version in the host;
+The untagged npm `latest` channel is `0.5.0`. Pin the exact version in the host;
 the changelog and the upgrading guide say what each release changes.
 
 ### 2. Mount the component
@@ -203,6 +203,15 @@ data only when this opt-in is enabled and the runtime IP identifies a private
 immediate peer. Caller-supplied proxy or geographic headers are ignored when
 native metadata is absent or public.
 
+`RASTRO_CLIENT_RATE_LIMIT` is for load-test canaries only. Set to `off`, it
+lifts the per-client ingest budget (see
+[Operational limits](#operational-limits)), so a benchmark driver sending every
+request from one address is bounded by the per-site shards alone. Bind it like
+the others: `RASTRO_CLIENT_RATE_LIMIT: v.optional(v.literal("off"))` in
+`defineApp` and `RASTRO_CLIENT_RATE_LIMIT: app.env.RASTRO_CLIENT_RATE_LIMIT` in
+`app.use`, as the example host does. Leave it unset on every customer
+deployment.
+
 The lookup has a 1.5-second timeout and fails open: telemetry ingestion
 continues without location when the provider is unavailable. A session reserves
 its single lookup attempt atomically only after its initial event is persisted;
@@ -228,8 +237,9 @@ until it reloads.
 
 The tracker sends no client identification. Ingestion derives `browser`, `os`,
 and `device` from headers the browser attaches itself, and persists only those
-three normalized values; the raw `User-Agent` never reaches a mutation or a
-component table.
+three normalized values; it also reads the in-app browser's platform id
+(`instagram`, `facebook`, `tiktok`…) for the session's origin, below. The raw
+`User-Agent` never reaches a mutation or a component table.
 
 Chromium attaches the low-entropy `Sec-CH-UA`, `Sec-CH-UA-Mobile`, and
 `Sec-CH-UA-Platform` client hints to cross-origin requests from secure origins,
@@ -310,9 +320,11 @@ Do not call the authenticated example with a bare CLI command: without an
 explicit test identity, `ctx.auth.getUserIdentity()` correctly returns `null`.
 
 Allowed domains are checked at ingestion. Exact hosts and wildcard subdomains
-such as `*.example.com` are supported. `Origin` is an abuse signal, not
-authentication; Amage Rastro also enforces per-session and fixed-shard per-site
-event/byte budgets.
+such as `*.example.com` are supported. The `Origin` check is a browser control,
+not an anti-abuse one: a browser cannot forge the header, but any other sender
+writes the one it likes, and the site ID is in every page's source. Abuse is
+bounded by event and byte budgets per session, per client network, and per site
+(see [Operational limits](#operational-limits)).
 
 Domain entries are hostnames, not host-and-port pairs. Use `localhost` or a full
 origin such as `http://localhost:3000`; both normalize to the `localhost` host.
@@ -449,10 +461,12 @@ budget; add it only where you want performance data:
 ></script>
 ```
 
-The module shares the tracker's session identity through `sessionStorage`,
-accepts the same `data-endpoint` and `data-visitor` overrides, and works with or
-without the base tracker on the page. Measurements are attributed to the landing
-path of the page load, never to later SPA routes. Vitals feed only the
+The module derives the tracker's session and visitor ids by the same rule, from
+`sessionStorage` and `localStorage`, whichever script loads first, and accepts
+the same `data-endpoint` and `data-visitor` overrides. It needs the base tracker
+on the page: vitals annotate the session the tracker opened, and ingestion
+rejects them for a session it never saw. Measurements are attributed to the
+landing path of the page load, never to later SPA routes. Vitals feed only the
 `vitalsReport` histograms — analytics event counts, sessions, and live presence
 do not change. Browsers without an entry type simply skip that metric (Safari
 reports no LCP, CLS, or INP).
@@ -563,17 +577,115 @@ payload-bound by the site's financial ledger.
 
 The tracker reads `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, and
 `utm_content` from the landing URL, keeps them in `sessionStorage` for the rest
-of the session, and sends them as properties of every pageview; no other query
-parameter ever leaves the page. A session's `source` is the lowercase
-`utm_source` when present and the referrer host otherwise, so campaign traffic
-no longer reads as `direct`. `utmSource`, `utmMedium`, and `utmCampaign` stay on
-the session for journeys; `overview.topCampaigns` ranks `utm_campaign` and
-`overview.topMediums` the lowercase `utm_medium` next to `topSources`, by
-sessions once the range is covered by the counters. `overview.topOutbound` ranks
-the hosts outbound clicks reached — the host alone, never the path or query — by
-clicks. Both lists are recorded from `metadata.dimensionsSince` (each site's
-first ingest on 0.1.0 plus the rollup delay); a range that starts earlier ranks
-them from partial data, and the dashboard says so.
+of the tab — a later session the tab opens after a sign-in or 30 idle minutes
+keeps them too — and sends them as properties of every pageview. Besides those
+five, the only thing the landing URL ever yields is the **name** of a click-ID
+key it carried (below); no other query parameter, and no query value at all,
+ever leaves the page. A session's `source` is the lowercase `utm_source` when
+present and the referrer host otherwise, so campaign traffic no longer reads as
+`direct`. `utmSource`, `utmMedium`, and `utmCampaign` stay on the session for
+journeys; `overview.topCampaigns` ranks `utm_campaign` and `overview.topMediums`
+the lowercase `utm_medium` next to `topSources`, by sessions once the range is
+covered by the counters. `overview.topOutbound` ranks the hosts outbound clicks
+reached — the host alone, never the path or query — by clicks. Both lists are
+recorded from `metadata.dimensionsSince` (each site's first ingest on 0.1.0 plus
+the rollup delay); a range that starts earlier ranks them from partial data, and
+the dashboard says so.
+
+A session also keeps where it came from, classified once on its first touch and
+never guessed: `platform` (an id from a closed, versioned table of about forty —
+`instagram`, `google`, `whatsapp`, `chatgpt` — or `unknown` for a host or
+`utm_source` outside it, or `none`), `channel` (`direct`, `organic_search`,
+`paid_search`, `organic_social`, `paid_social`, `messaging`, `email`,
+`affiliate`, `ai`, `display`, `referral`, `offline`), and `evidence`, the rule
+that decided it. One rule decides and the next only runs when it did not:
+`utm_source` through the alias table, then click-ID names, then the referrer
+host by registrable domain, then the in-app browser, then an affiliate `ref`,
+which sets the channel and keeps the platform an earlier rule found. Hosts match
+by whole label, never by substring, so `l.instagram.com`, `instagram.com` and
+`com.instagram.android` are one platform while `docs.google.com` is not Google;
+`utm_medium` picks the channel from a closed table that also accepts the channel
+ids themselves, which is what a tracked link (below) emits, `offline` included.
+Nothing at all is `direct`, the only way to be direct, and a referrer on the
+site's own domains is an internal hop, never an origin. `overview.topPlatforms`,
+`topChannels` and `topEvidence` rank them beside `topSources`; a `topPlatforms`
+value is the platform id alone when the session arrived by that platform's
+default channel and `platform@channel` when it did not (`google@paid_search`),
+so one platform ranks once per channel it was reached by —
+`splitPlatformDimension` reads the pair back. `dataCoverage`'s `origin` dataset
+says from when a site carries them; sessions older than that are classified on
+read and marked `evidence: "legacy"`. `source` keeps the raw `utm_source` or
+host for the drill-down, exactly as before.
+
+The tracker reads the click-ID keys of its landing URL and sends them in `clid`:
+their **names** only (`fbclid`, `gclid`, `ttclid`, `mc_cid`…), never their
+values, so no advertising identifier leaves the page. It matches the same
+allowlist the server does, in the same ranking order, and sends at most eight;
+ingestion drops any name outside the allowlist and keeps at most eight of what
+is left. The referrer it sends is scheme and host, so a referrer of the form
+`android-app://<package>` keeps the package alone and the app that opened the
+link is a platform (`com.google.android.gm` is Gmail) instead of nothing.
+
+## Tracked links
+
+Some traffic arrives with nothing to read. A link tapped inside WhatsApp,
+Telegram, an SMS or a native e-mail app, or scanned from a QR code, opens with
+no referrer and no campaign, and any analytics tool files it as `direct`. A
+tracked link closes that gap: the dashboard's **Links** tab (or the host API)
+creates `/rastro/l/<slug>` for one place the link will be published, and every
+click lands on the site with that place in its `utm_*`.
+
+`GET /rastro/l/<slug>` answers `302` with `Cache-Control: no-store` to the
+link's destination, after appending:
+
+| Parameter      | Value                                                                                                               |
+| -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `utm_source`   | the platform: `instagram`, `whatsapp`, `qr`, or any id of 2–24 lowercase letters, digits or underscores             |
+| `utm_medium`   | the channel: `organic_social`, `paid_social`, `messaging`, `email`, `affiliate`, `display`, `referral` or `offline` |
+| `utm_campaign` | the campaign, or the slug when the link has none                                                                    |
+| `utm_content`  | the slug                                                                                                            |
+
+The destination's own query stays exactly as it was, and a `utm_*` key it
+already carries is never overridden. Unknown and disabled slugs answer `404` in
+plain text. The tracker needs nothing new: the landing reads the `utm_*` like
+any campaign link.
+
+- **Clicks and bots.** Each click lands in a daily counter spread over four
+  shards, so a link that goes viral never serializes on one document. A
+  self-declared bot, including the WhatsApp, Facebook and Telegram link
+  previews, is still redirected but counted under `bots`, never `clicks`.
+  `listTrackedLinks` reports both, all time and over the 30 UTC days ending on
+  the day of the `now` it is given.
+- **No open redirect.** A destination must be an absolute `http(s)` URL without
+  credentials on one of the site's domains (exact, or a `*.` pattern for
+  subdomains). The rule is checked when a link is created or changed and again
+  on every click, so a domain removed from the site stops redirecting at once.
+- **Slugs** are 3–32 lowercase letters, digits or hyphens, starting and ending
+  with a letter or digit, and unique across the deployment because the route
+  names no site. A site keeps at most 200 links. Deleting a link frees its slug
+  and removes its counters; disabling it keeps both.
+- **A short domain.** The route lives on the deployment's HTTP origin
+  (`https://<deployment>.convex.site/rastro/l/promo`). A host that wants a
+  presentable link serves that origin under a short domain of its own, such as
+  `go.example.com/rastro/l/promo`; nothing in the component changes.
+
+```ts
+await analytics.createTrackedLink(ctx, {
+  siteId,
+  slug: "bio-instagram",
+  destination: "https://www.example.com/promo",
+  platform: "instagram",
+  channel: "organic_social",
+  campaign: "spring-sale",
+  createdBy: userId, // an opaque id, never an e-mail address
+});
+```
+
+A federated dashboard reaches the same functions once the host re-exports
+`listTrackedLinks`, `createTrackedLink`, `updateTrackedLink`, and
+`deleteTrackedLink` from `convex/rastroFederation.ts`. The connection then
+advertises the `trackedLinks` capability: any reader lists the links, and
+changing them needs `analytics:configure`, like goals and affiliates.
 
 ## Identify visitors after signup
 
@@ -596,14 +708,16 @@ await analytics.linkVisitor(ctx, {
 ```
 
 `visitorJourney` for either id then returns one chronological journey; every
-event keeps the id it was recorded with. Links are idempotent, an anonymous id
-belongs to at most one identity, a linked id cannot be linked again, chains and
-identity merges are rejected, and an identity holds at most ten aliases. The
-tracker still sets no cookie: the host's own session identifies the account and
-the anonymous ids live in the browser's own storage (the visitor id in
-`localStorage`, the session id in `sessionStorage`). Linking anonymous history
-to an account turns it into personal data under the host's privacy policy;
-disclose it and offer an opt-out.
+event keeps the id it was recorded with. A session belongs to one identity: the
+first page rendered with the new `data-visitor` opens a new session in the same
+tab, carrying the referral and campaign over, and the link joins both sessions
+in the journey. Links are idempotent, an anonymous id belongs to at most one
+identity, a linked id cannot be linked again, chains and identity merges are
+rejected, and an identity holds at most ten aliases. The tracker still sets no
+cookie: the host's own session identifies the account and the anonymous ids live
+in the browser's own storage (the visitor id in `localStorage`, the session id
+in `sessionStorage`). Linking anonymous history to an account turns it into
+personal data under the host's privacy policy; disclose it and offer an opt-out.
 
 ## Attribute trusted payments
 
@@ -738,6 +852,8 @@ The `Rastro` class wraps the component boundary for host functions:
 - Configuration: `upsertGoal`, `listGoals`, `removeGoal`, `upsertFunnel`,
   `listFunnels`, `removeFunnel`, `upsertAffiliate`, `listAffiliates`,
   `removeAffiliate`
+- Tracked links: `createTrackedLink`, `updateTrackedLink`, `deleteTrackedLink`,
+  `listTrackedLinks`
 - Retention: `cleanup`, `setRetentionPolicy`, `disableRetentionPolicy`,
   `runRetentionPolicy`, `retentionStatus`
 
@@ -832,24 +948,50 @@ boundaries use different bucket alignment.
   never written by the ingestion transaction: a batch appends one document to
   the site's rollup queue and one leased fold job per site merges up to 200
   queued batches per run into the rows, so every rollup row has a single writer
-  and concurrent ingestion cannot conflict on it. Reports see a batch's rollups
-  a few hundred milliseconds after ingestion accepts it; a fold chain that dies
-  is restarted by the next batch once its 60-second lease lapses
-- Site ingress budget: 4,096 deterministic per-minute shards, each capped at 300
-  events and 512 KiB (1,228,800 admitted events/minute at uniform load)
-- Rate-window storage: one reusable row per active session and site shard
-- Live session timeout: a `leave` beacon on `pagehide` retires the visitor about
-  ten seconds after they leave and a back/forward-cache return revives them
-  immediately; the safety net for a browser that never says goodbye is 90
-  seconds since the last event or heartbeat (heartbeats fire every 20 seconds,
-  within background-tab throttling), with one bounded five-second expiry sweep
-  per site; legacy per-session jobs hand off to that sweep during the cutover
+  and concurrent ingestion cannot conflict on it. Runs are debounced: the first
+  batch schedules a run one second out, batches arriving while it is pending
+  neither write the lease nor schedule anything, and the chain keeps running
+  once a second until a run finds the queue empty. Reports see a batch's rollups
+  about a second after ingestion accepts it; a fold chain that dies is restarted
+  by the next batch once its 60-second lease lapses. A run that throws is rolled
+  back and retries its oldest batch alone; a batch that fails three runs in a
+  row is set aside as a logged dead letter (kept 30 days) so the rest of the
+  queue keeps folding
+- Session ingress budget: 120 events and 256 KiB per session per minute
+- Client ingress budget: 1,200 events and 2 MiB per site per minute from one
+  client network, an IPv4 address or an IPv6 /64. The window is keyed by the
+  salted daily hash behind anonymous visitor keys, never by the address, and
+  every visitor behind one office or carrier-grade NAT shares it. It applies
+  when `/rastro/health` reports `clientIpAvailable: true`;
+  `RASTRO_CLIENT_RATE_LIMIT=off` lifts it on a load-test canary
+- Site ingress budget: 256 deterministic per-minute shards, each capped at 1,500
+  events and 2 MiB, so a site admits at most 384,000 events and 512 MiB a
+  minute. Only evenly spread load (random session IDs) reaches that; a real peak
+  is uneven, and the realistic benchmark's ~100k events/minute tops out near
+  1,050 events in its hottest shard-minute
+- Rate-window storage: one reusable row per active session, client network and
+  UTC day, and site shard
+- Live session timeout: a `leave` beacon when the tab hides or the page unloads
+  retires the visitor about ten seconds later, and showing the tab again or a
+  back/forward-cache return revives them immediately; heartbeats fire every 20
+  seconds only while the tab is visible, so a hidden tab sends nothing; the
+  safety net for a browser that never says goodbye is 90 seconds since the last
+  event or heartbeat, with one bounded five-second expiry sweep per site; legacy
+  per-session jobs hand off to that sweep during the cutover
+- Session: one identity's visit in one tab; a new `data-visitor` or 30 minutes
+  without an event opens the next one, which starts with a pageview of the
+  current page
 - Clock alignment: the tracker and the vitals module stamp each batch with
   `sentAt`; when that clock is more than 30 seconds from the server's, every
   event in the batch is re-anchored by the offset before ingestion, so a visitor
   whose device clock is wrong still goes live and is filed under the right hour
-- Dashboard overview: up to ten sites and bounded report ranges
-- Hourly overview: up to 24 hours; wider ranges use daily buckets
+- Dashboard overview: up to ten sites. One overview reads at most 13,000
+  aggregate rows and a day holds 128 per site, so a daily range covers at most
+  101 days for one site, 50 for two, and 10 for ten; a wider range fails with
+  `LIMIT_EXCEEDED` naming its bound. A busy range that would cross the 8 MiB a
+  query may read fails with `REPORT_INCOMPLETE` first
+- Hourly overview: up to 24 hours (an hour holds 256 rows per site, so 16 hours
+  for three sites and 5 for ten); wider ranges use daily buckets
 - Retention cleanup: bounded batches. `setRetentionPolicy` automatically starts
   leased, persisted cleanup chains for every policy-managed dataset; interrupted
   attempts resume after lease expiry and stale generations cannot mutate the
@@ -888,7 +1030,8 @@ driver session pool is 4,096: at current speed the historical 2,048-session pool
 pushes single sessions past the documented 120 events/minute budget. Results
 came from one client process against the same non-production Synapse DEV
 deployment and site as the 2026-08-21 certification; they are engineering
-evidence, not a production SLA.
+evidence, not a production SLA. Because that one client process is one address,
+a certification canary now also sets `RASTRO_CLIENT_RATE_LIMIT=off`.
 
 Two caveats stand deliberately. The heavy row measured a store already holding
 the battery's own multi-million-event history; the 2026-08-22 fresh-store result
@@ -985,7 +1128,8 @@ deployments need no legacy-event migration.
 Amage Rastro's default tracker:
 
 - sets no cookies;
-- stores a pseudonymous session ID and referral slug in `sessionStorage`, and a
+- stores a pseudonymous session ID, the visitor ID it opened with, the time of
+  its last event, and the referral slug and campaign in `sessionStorage`, and a
   persistent pseudonymous visitor ID in `localStorage` — scoped to the site's
   origin, never shared across sites, gone when the visitor clears site data;
 - never persists raw visitor IP addresses in component tables;
@@ -1005,7 +1149,12 @@ Amage Rastro's default tracker:
   clicked link or button (at most 64 characters, replaced by `data-rastro-label`
   when present), and outbound link origins and pathnames (the overview ranks
   destinations by host alone);
-- strips query strings and fragments from stored paths and links.
+- strips query strings and fragments from stored paths and links; of the landing
+  query it keeps the five `utm_*` values and the bare **names** of the
+  advertising click-ID keys it recognizes (`fbclid`, `gclid`…), never a click-ID
+  value, and never any other parameter;
+- sends the referrer as scheme and host only — an `android-app://<package>`
+  included — never its path or query.
 
 The optional Web Vitals module inherits this contract: it reports at most five
 timing numbers per page load (milliseconds, or CLS scaled by 1000) against the

package/agent/integration.md

@@ -519,21 +519,25 @@ export const {
   retentionStatus,
   setRetentionPolicy,
   disableRetentionPolicy,
+  listTrackedLinks,
+  createTrackedLink,
+  updateTrackedLink,
+  deleteTrackedLink,
 } = federated;
 ```
 
 `manifest` is public static metadata. Every report function is read-only and
 requires both a valid JWT and a matching, non-revoked local grant. The functions
-from `siteSettings` down form the configure scope (optional capability
-`configure`, hosts from `alpha.11`): they additionally require
-`analytics:configure` on the token — the control plane claims it only for
-organization owners and admins — and in the grant's `permissions`, and fail with
-`FEDERATION_CONFIGURE_FORBIDDEN` otherwise. Export them even when every grant
-stays read only, so a later opt-in needs no host deploy; the dashboard never
-calls them for a read-only connection. The issuer falls back to the production
-control plane so the module compiles and pushes before the environment variable
-exists; tokens are still rejected until `auth.config.ts` trusts the same issuer,
-which needs both variables set and a push afterwards.
+from `siteSettings` to `disableRetentionPolicy` form the configure scope
+(optional capability `configure`, hosts from `alpha.11`): they additionally
+require `analytics:configure` on the token — the control plane claims it only
+for organization owners and admins — and in the grant's `permissions`, and fail
+with `FEDERATION_CONFIGURE_FORBIDDEN` otherwise. Export them even when every
+grant stays read only, so a later opt-in needs no host deploy; the dashboard
+never calls them for a read-only connection. The issuer falls back to the
+production control plane so the module compiles and pushes before the
+environment variable exists; tokens are still rejected until `auth.config.ts`
+trusts the same issuer, which needs both variables set and a push afterwards.
 
 A public link's token carries `analytics:public` instead of `analytics:read` and
 `rastro_site_ids` naming the link's sites. It runs only `manifest`,
@@ -587,6 +591,18 @@ the token and in the grant:
 | `setRetentionPolicy`     | `siteId` and five day counts between 1 and 3650              | Starts the recurring cleanup chains                                 |
 | `disableRetentionPolicy` | one `siteId`                                                 | Stops automatic cleanup; nothing is restored                        |
 
+Tracked links, behind the optional `trackedLinks` capability. Listing needs only
+a reader; the three writes require `analytics:configure` like the configure
+scope above. A host serves them by re-exporting the four functions; one that
+does not keeps working and advertises no `trackedLinks` capability.
+
+| Function            | Input summary                                                                   | Important output/behavior                                                 |
+| ------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `listTrackedLinks`  | one `siteId` and `now`                                                          | Definitions with clicks and bot hits, all time and over 30 UTC days       |
+| `createTrackedLink` | `siteId`, slug, destination, platform, channel, campaign, `createdBy`           | Returns the link ID; the destination must be on one of the site's domains |
+| `updateTrackedLink` | `siteId`, `linkId`, optional destination, platform, channel, campaign, disabled | Changes everything but the slug; a disabled link answers 404              |
+| `deleteTrackedLink` | `siteId`, `linkId`                                                              | Deletes the link, frees its slug, and purges its click counters           |
+
 The federated surface deliberately excludes ingestion, owner IDs, network IDs,
 and arbitrary host functions, and shows a site's domains only through
 `siteSettings` to a connection allowed to change them. Goal, funnel, and

package/agent/manifest.json

@@ -15,11 +15,11 @@
     "upgrading": "https://www.amagerastro.com/docs/reference/upgrading.md",
     "integrity": {
       "algorithm": "sha256",
-      "agent": "e26de56729dd0b474669d2b40292afb314224200da4e70f6dabd407ce7aea6e7",
-      "llms": "08e9581c9ee626642753db971e9c4da22d131ddb62870cca402d2e93ce4f7567",
+      "agent": "994ba7a57ada6238b9d8fdc3280e352c185c0a97772e627ee1bdc1afda1185cb",
+      "llms": "46fb9a206d2f41d30f72f80ac9764d30535d7d1d65afe475e03d72b075cf6359",
       "protocol": "f2be7e3db250824d0c1293eb31b2e4514ebed8b21fe4974d4f4797fd86abe04f",
       "setup": "bf2509a87a8eab9c047276b813f029bb2c9ddd58c0e54754432e3fef7891f3c9",
-      "upgrading": "a6ed4626b3502a60c646448bdd512ab63e148322e0855ba819a77478db987f8d"
+      "upgrading": "e675d73c3df963ad85aa918c3b4bd8acb74c9179940497bf034ff566fa513cc7"
     }
   },
   "controlPlane": {
@@ -85,7 +85,11 @@
       "removeAffiliate": "removeAffiliate",
       "retentionStatus": "retentionStatus",
       "setRetentionPolicy": "setRetentionPolicy",
-      "disableRetentionPolicy": "disableRetentionPolicy"
+      "disableRetentionPolicy": "disableRetentionPolicy",
+      "listTrackedLinks": "listTrackedLinks",
+      "createTrackedLink": "createTrackedLink",
+      "updateTrackedLink": "updateTrackedLink",
+      "deleteTrackedLink": "deleteTrackedLink"
     },
     "capabilities": [
       "siteSummaries",
@@ -104,7 +108,8 @@
       "vitals",
       "siteMap",
       "localDays",
-      "configure"
+      "configure",
+      "trackedLinks"
     ],
     "limits": {
       "maxSitesPerRequest": 10,

package/agent/manifest.schema.json

@@ -185,7 +185,11 @@
             "removeAffiliate",
             "retentionStatus",
             "setRetentionPolicy",
-            "disableRetentionPolicy"
+            "disableRetentionPolicy",
+            "listTrackedLinks",
+            "createTrackedLink",
+            "updateTrackedLink",
+            "deleteTrackedLink"
           ],
           "properties": {
             "manifest": { "const": "manifest" },
@@ -218,14 +222,18 @@
             "removeAffiliate": { "const": "removeAffiliate" },
             "retentionStatus": { "const": "retentionStatus" },
             "setRetentionPolicy": { "const": "setRetentionPolicy" },
-            "disableRetentionPolicy": { "const": "disableRetentionPolicy" }
+            "disableRetentionPolicy": { "const": "disableRetentionPolicy" },
+            "listTrackedLinks": { "const": "listTrackedLinks" },
+            "createTrackedLink": { "const": "createTrackedLink" },
+            "updateTrackedLink": { "const": "updateTrackedLink" },
+            "deleteTrackedLink": { "const": "deleteTrackedLink" }
           },
           "additionalProperties": false
         },
         "capabilities": {
           "type": "array",
-          "minItems": 15,
-          "maxItems": 17,
+          "minItems": 16,
+          "maxItems": 18,
           "uniqueItems": true,
           "items": {
             "enum": [
@@ -245,7 +253,8 @@
               "vitals",
               "siteMap",
               "localDays",
-              "configure"
+              "configure",
+              "trackedLinks"
             ]
           }
         },