@iann29/rastro 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/client/index.js

@@ -1,7 +1,12 @@
 import { mutationGeneric, paginationOptsValidator, paginationResultValidator, queryGeneric, } from "convex/server";
-import { v } from "convex/values";
-import { eventPropertiesValidator, eventTypeValidator, funnelStepValidator, goalMatchTypeValidator, ingestContextValidator, ingestResultValidator, trackerEventValidator, } from "../component/validators.js";
-export { eventPropertiesValidator, eventTypeValidator, funnelStepValidator, goalMatchTypeValidator, ingestContextValidator, ingestResultValidator, trackerEventValidator, };
+import { ConvexError, v } from "convex/values";
+import { eventPropertiesValidator, eventTypeValidator, funnelStepValidator, goalMatchTypeValidator, ingestContextValidator, ingestResultValidator, trackerEventValidator, vitalMetricValidator, } from "../component/validators.js";
+import { createFederatedAnalyticsConnectionAuthorizer, createFederatedAnalyticsManifest, FEDERATED_ANALYTICS_CONFIGURE_PERMISSION, FEDERATED_ANALYTICS_CONNECTOR_MANIFEST, FEDERATED_ANALYTICS_READ_PERMISSION, federatedAnalyticsConnectionStatusValidator, federatedAnalyticsManifestValidator, federatedSiteSummaryValidator, } from "./federation.js";
+export { eventPropertiesValidator, eventTypeValidator, funnelStepValidator, goalMatchTypeValidator, ingestContextValidator, ingestResultValidator, trackerEventValidator, vitalMetricValidator, };
+export { VITAL_METRICS, VITAL_THRESHOLDS } from "../component/vitals.js";
+export { normalizeRoute } from "../component/sanitize.js";
+export { localDayStart, nextLocalDayStart, previousLocalDayStart, } from "../component/localTime.js";
+export { effectiveFederatedPermissions, FEDERATED_ANALYTICS_CLAIMS, FEDERATED_ANALYTICS_CONFIGURE_FUNCTIONS, FEDERATED_ANALYTICS_CONFIGURE_PERMISSION, FEDERATED_ANALYTICS_CONNECTOR_MANIFEST, FEDERATED_ANALYTICS_ERROR_CODES, FEDERATED_ANALYTICS_PERMISSIONS, FEDERATED_ANALYTICS_READ_PERMISSION, FEDERATED_ANALYTICS_REQUIRED_CAPABILITIES, FEDERATED_ANALYTICS_REQUIRED_FUNCTIONS, federatedAnalyticsPermissionValidator, } from "./federation.js";
 export class Rastro {
     component;
     constructor(component) {
@@ -16,6 +21,10 @@ export class Rastro {
     getSite(ctx, siteId) {
         return ctx.runQuery(this.component.sites.get, { siteId });
     }
+    /** The calendar days a site's daily overview answers in; see `sites.localDays`. */
+    localDays(ctx, siteId) {
+        return ctx.runQuery(this.component.sites.localDays, { siteId });
+    }
     listSites(ctx, args) {
         return ctx.runQuery(this.component.sites.listByOwner, args);
     }
@@ -25,6 +34,9 @@ export class Rastro {
     trackConversion(ctx, args) {
         return ctx.runMutation(this.component.ingest.trackConversion, args);
     }
+    linkVisitor(ctx, args) {
+        return ctx.runMutation(this.component.visitors.link, args);
+    }
     overview(ctx, args) {
         return ctx.runQuery(this.component.reports.overview, args);
     }
@@ -52,6 +64,12 @@ export class Rastro {
     affiliatesReport(ctx, args) {
         return ctx.runQuery(this.component.reports.affiliatesReport, args);
     }
+    vitalsReport(ctx, args) {
+        return ctx.runQuery(this.component.reports.vitalsReport, args);
+    }
+    siteMap(ctx, args) {
+        return ctx.runQuery(this.component.reports.siteMap, args);
+    }
     upsertGoal(ctx, args) {
         return ctx.runMutation(this.component.goals.upsert, args);
     }
@@ -77,11 +95,29 @@ export class Rastro {
         return ctx.runQuery(this.component.affiliates.list, { siteId });
     }
     removeAffiliate(ctx, siteId, affiliateId) {
-        return ctx.runMutation(this.component.affiliates.remove, { siteId, affiliateId });
+        return ctx.runMutation(this.component.affiliates.remove, {
+            siteId,
+            affiliateId,
+        });
     }
     cleanup(ctx, args) {
         return ctx.runMutation(this.component.retention.cleanup, args);
     }
+    dataCoverage(ctx, args) {
+        return ctx.runQuery(this.component.reports.dataCoverage, args);
+    }
+    setRetentionPolicy(ctx, args) {
+        return ctx.runMutation(this.component.retention.setPolicy, args);
+    }
+    disableRetentionPolicy(ctx, siteId) {
+        return ctx.runMutation(this.component.retention.disablePolicy, { siteId });
+    }
+    retentionStatus(ctx, siteId) {
+        return ctx.runQuery(this.component.retention.status, { siteId });
+    }
+    runRetentionPolicy(ctx, args) {
+        return ctx.runMutation(this.component.retention.runPolicy, args);
+    }
 }
 const hostSiteValidator = v.object({
     _id: v.string(),
@@ -111,6 +147,7 @@ const hostSessionValidator = v.object({
     utmSource: v.optional(v.string()),
     utmMedium: v.optional(v.string()),
     utmCampaign: v.optional(v.string()),
+    visitorKey: v.optional(v.string()),
     country: v.optional(v.string()),
     city: v.optional(v.string()),
     latitude: v.optional(v.number()),
@@ -176,6 +213,8 @@ const hostLiveVisitorValidator = v.object({
     device: v.string(),
     pageviewCount: v.number(),
     eventCount: v.number(),
+    previousPath: v.optional(v.string()),
+    movedAt: v.optional(v.number()),
 });
 const hostConversionValidator = v.object({
     _id: v.string(),
@@ -206,12 +245,67 @@ const hostMetricTotalsValidator = v.object({
     visitors: v.number(),
     conversions: v.number(),
     revenueCents: v.number(),
+    durationMs: v.number(),
+    continuedSessions: v.number(),
+    newVisitors: v.number(),
 });
 const hostTopItemValidator = v.object({
     value: v.string(),
     count: v.number(),
     revenueCents: v.number(),
 });
+const hostCoverageValidator = v.object({
+    state: v.union(v.literal("complete"), v.literal("partial"), v.literal("retained"), v.literal("unavailable")),
+    generation: v.union(v.number(), v.null()),
+    availableFrom: v.union(v.number(), v.null()),
+    availableThrough: v.union(v.number(), v.null()),
+    retainedBefore: v.union(v.number(), v.null()),
+});
+const hostRangeSemanticsValidator = v.object({
+    from: v.number(),
+    to: v.number(),
+    boundary: v.literal("inclusive"),
+    // "UTC", or the site timezone whose calendar days a daily overview used.
+    timezone: v.string(),
+});
+const hostReportMetadataValidator = v.object({
+    basis: v.union(v.literal("dailyRollup"), v.literal("boundedLegacy")),
+    coverage: hostCoverageValidator,
+    range: hostRangeSemanticsValidator,
+});
+const hostDataCoverageValidator = v.object({
+    siteId: v.string(),
+    from: v.number(),
+    to: v.number(),
+    datasets: v.array(v.object({
+        dataset: v.union(v.literal("overviewHour"), v.literal("overviewDay"), v.literal("overviewLocalDay"), v.literal("events"), v.literal("sessions"), v.literal("conversions"), v.literal("goals"), v.literal("funnels"), v.literal("affiliates"), v.literal("vitals"), v.literal("siteMap")),
+        coverage: hostCoverageValidator,
+    })),
+});
+const retentionKindValidator = v.union(v.literal("events"), v.literal("sessions"), v.literal("conversions"), v.literal("goalCompletions"), v.literal("aggregateHour"), v.literal("aggregateDay"), v.literal("funnelProgress"), v.literal("funnelSteps"), v.literal("affiliateStats"), v.literal("goalRollups"), v.literal("funnelRollups"), v.literal("affiliateRollups"), v.literal("vitalRollups"), v.literal("siteMapRollups"), v.literal("attributions"), v.literal("liveSessions"), v.literal("ingestWindows"), v.literal("siteIngestWindows"));
+const hostRetentionPolicyValidator = v.object({
+    eventsDays: v.number(),
+    sessionsDays: v.number(),
+    conversionsDays: v.number(),
+    aggregatesDays: v.number(),
+    reportsDays: v.number(),
+});
+const hostRetentionStatusValidator = v.object({
+    policy: v.union(hostRetentionPolicyValidator.extend({ updatedAt: v.number() }), v.null()),
+    jobs: v.array(v.object({
+        kind: v.string(),
+        before: v.number(),
+        status: v.union(v.literal("pending"), v.literal("running"), v.literal("complete")),
+        deleted: v.number(),
+        scheduledAt: v.union(v.number(), v.null()),
+        updatedAt: v.number(),
+    })),
+    backlog: v.number(),
+});
+// See the component's breakdownBasisValidator: a breakdown's `count` is
+// pageviews (pages) or sessions (every other dimension) once the range is
+// fully covered by those counters, and raw event volume before that.
+const hostBreakdownBasisValidator = v.union(v.literal("pageviews"), v.literal("sessions"), v.literal("eventVolume"));
 const hostOverviewValidator = v.object({
     from: v.number(),
     to: v.number(),
@@ -220,12 +314,41 @@ const hostOverviewValidator = v.object({
     totals: hostMetricTotalsValidator,
     timeSeries: v.array(hostMetricTotalsValidator.extend({ timestamp: v.number() })),
     topSources: v.array(hostTopItemValidator),
+    topCampaigns: v.array(hostTopItemValidator),
     topPages: v.array(hostTopItemValidator),
     topCountries: v.array(hostTopItemValidator),
     topDevices: v.array(hostTopItemValidator),
     topBrowsers: v.array(hostTopItemValidator),
     topEvents: v.array(hostTopItemValidator),
     topGoals: v.array(hostTopItemValidator),
+    metadata: v.object({
+        visitors: v.object({
+            basis: v.union(v.literal("estimatedUnique"), v.literal("bucketOccurrences")),
+            exact: v.boolean(),
+            legacyIncomplete: v.boolean(),
+            sketchVersion: v.union(v.number(), v.null()),
+            precision: v.union(v.number(), v.null()),
+        }),
+        breakdowns: v.object({
+            topSources: hostBreakdownBasisValidator,
+            topCampaigns: hostBreakdownBasisValidator,
+            topPages: hostBreakdownBasisValidator,
+            topCountries: hostBreakdownBasisValidator,
+            topDevices: hostBreakdownBasisValidator,
+            topBrowsers: hostBreakdownBasisValidator,
+            topEvents: v.literal("eventVolume"),
+            topGoals: v.literal("goalCompletionVolume"),
+        }),
+        engagement: v.union(v.literal("counted"), v.literal("unavailable")),
+        coverage: hostCoverageValidator,
+        range: hostRangeSemanticsValidator,
+        features: v.object({
+            sessionReplay: v.literal("unsupported"),
+            errorInsights: v.literal("unsupported"),
+            outboundLinks: v.literal("eventVolume"),
+            botDetection: v.literal("userAgent"),
+        }),
+    }),
 });
 const hostGoalValidator = v.object({
     _id: v.string(),
@@ -265,12 +388,22 @@ const hostAffiliateValidator = v.object({
     updatedAt: v.number(),
 });
 const hostGoalsReportValidator = v.object({
-    goals: v.array(hostGoalValidator.extend({ completions: v.number(), valueCents: v.number() })),
+    goals: v.array(hostGoalValidator.extend({
+        completions: v.number(),
+        valueCents: v.number(),
+    })),
     truncated: v.boolean(),
+    metadata: hostReportMetadataValidator,
 });
 const hostFunnelsReportValidator = v.array(hostFunnelValidator.extend({
-    stepsReport: v.array(v.object({ step: v.number(), name: v.string(), entrants: v.number(), completions: v.number() })),
+    stepsReport: v.array(v.object({
+        step: v.number(),
+        name: v.string(),
+        entrants: v.number(),
+        completions: v.number(),
+    })),
     truncated: v.boolean(),
+    metadata: hostReportMetadataValidator,
 }));
 const hostAffiliatesReportValidator = v.object({
     affiliates: v.array(hostAffiliateValidator.extend({
@@ -281,6 +414,65 @@ const hostAffiliatesReportValidator = v.object({
         commissionCents: v.number(),
     })),
     truncated: v.boolean(),
+    metadata: hostReportMetadataValidator.extend({
+        uniqueVisitors: v.object({
+            basis: v.union(v.literal("estimatedUnique"), v.literal("exactLegacy")),
+            exact: v.boolean(),
+        }),
+    }),
+});
+const hostVitalStatsValidator = v.object({
+    count: v.number(),
+    p75: v.number(),
+    average: v.number(),
+    good: v.number(),
+    needsImprovement: v.number(),
+    poor: v.number(),
+});
+const hostVitalsReportValidator = v.object({
+    metrics: v.array(hostVitalStatsValidator.extend({
+        metric: vitalMetricValidator,
+        devices: v.array(hostVitalStatsValidator.extend({ device: v.string() })),
+        pages: v.array(hostVitalStatsValidator.extend({ page: v.string() })),
+        timeSeries: v.array(v.object({
+            timestamp: v.number(),
+            count: v.number(),
+            p75: v.number(),
+        })),
+    })),
+    truncated: v.boolean(),
+    metadata: hostReportMetadataValidator,
+});
+const hostSiteMapValidator = v.object({
+    from: v.number(),
+    to: v.number(),
+    window: v.union(v.object({ from: v.number(), to: v.number() }), v.null()),
+    routes: v.array(v.object({
+        route: v.string(),
+        pageviews: v.number(),
+        visitors: v.number(),
+        entries: v.number(),
+        exits: v.number(),
+        bounces: v.number(),
+        transitionsIn: v.number(),
+        transitionsOut: v.number(),
+        dwellMs: v.number(),
+        dwellSamples: v.number(),
+        daily: v.array(v.object({ bucketStart: v.number(), pageviews: v.number() })),
+    })),
+    transitions: v.array(v.object({ from: v.string(), to: v.string(), count: v.number() })),
+    truncated: v.object({ routes: v.boolean(), transitions: v.boolean() }),
+    metadata: hostReportMetadataValidator.extend({
+        visitors: v.object({
+            basis: v.literal("estimatedUnique"),
+            exact: v.boolean(),
+        }),
+        limits: v.object({
+            routesPerDay: v.number(),
+            transitionSlots: v.number(),
+            rows: v.number(),
+        }),
+    }),
 });
 export function exposeAnalyticsApi(component, options) {
     const rastro = new Rastro(component);
@@ -297,7 +489,11 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: v.string(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "site.create", siteIds: [], ownerId: args.ownerId });
+                await options.authorize(ctx, {
+                    operation: "site.create",
+                    siteIds: [],
+                    ownerId: args.ownerId,
+                });
                 return await rastro.createSite(ctx, args);
             },
         }),
@@ -313,7 +509,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: v.null(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "site.update", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "site.update",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.updateSite(ctx, args);
             },
         }),
@@ -321,7 +520,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string() },
             returns: v.union(hostSiteValidator, v.null()),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "site.get", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "site.get",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.getSite(ctx, args.siteId);
             },
         }),
@@ -329,7 +531,11 @@ export function exposeAnalyticsApi(component, options) {
             args: { ownerId: v.string(), limit: v.optional(v.number()) },
             returns: v.array(hostSiteValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "site.list", siteIds: [], ownerId: args.ownerId });
+                await options.authorize(ctx, {
+                    operation: "site.list",
+                    siteIds: [],
+                    ownerId: args.ownerId,
+                });
                 return await rastro.listSites(ctx, args);
             },
         }),
@@ -342,7 +548,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: ingestResultValidator,
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "ingest", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "ingest",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.ingest(ctx, args);
             },
         }),
@@ -361,10 +570,28 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: ingestResultValidator,
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "conversion.track", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "conversion.track",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.trackConversion(ctx, args);
             },
         }),
+        linkVisitor: mutationGeneric({
+            args: {
+                siteId: v.string(),
+                visitorId: v.string(),
+                previousVisitorId: v.string(),
+            },
+            returns: v.object({ linked: v.boolean(), aliasCount: v.number() }),
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "visitor.link",
+                    siteIds: [args.siteId],
+                });
+                return await rastro.linkVisitor(ctx, args);
+            },
+        }),
         overview: queryGeneric({
             args: {
                 siteIds: v.array(v.string()),
@@ -374,7 +601,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: hostOverviewValidator,
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.overview", siteIds: args.siteIds });
+                await options.authorize(ctx, {
+                    operation: "report.overview",
+                    siteIds: args.siteIds,
+                });
                 return await rastro.overview(ctx, args);
             },
         }),
@@ -386,7 +616,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: v.array(hostLiveVisitorValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.live", siteIds: args.siteIds });
+                await options.authorize(ctx, {
+                    operation: "report.live",
+                    siteIds: args.siteIds,
+                });
                 return await rastro.liveVisitors(ctx, args);
             },
         }),
@@ -399,7 +632,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: paginationResultValidator(hostSessionValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.sessions", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "report.sessions",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.listSessions(ctx, args);
             },
         }),
@@ -413,7 +649,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: paginationResultValidator(hostEventValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.sessionJourney", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "report.sessionJourney",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.sessionJourney(ctx, args);
             },
         }),
@@ -426,7 +665,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: paginationResultValidator(hostConversionValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.conversions", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "report.conversions",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.listConversions(ctx, args);
             },
         }),
@@ -440,7 +682,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: v.array(hostEventValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.visitorJourney", siteIds: args.siteIds });
+                await options.authorize(ctx, {
+                    operation: "report.visitorJourney",
+                    siteIds: args.siteIds,
+                });
                 return await rastro.visitorJourney(ctx, args);
             },
         }),
@@ -448,7 +693,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string(), from: v.number(), to: v.number() },
             returns: hostGoalsReportValidator,
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.goals", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "report.goals",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.goalsReport(ctx, args);
             },
         }),
@@ -456,7 +704,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string(), from: v.number(), to: v.number() },
             returns: hostFunnelsReportValidator,
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.funnels", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "report.funnels",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.funnelsReport(ctx, args);
             },
         }),
@@ -464,10 +715,102 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string(), from: v.number(), to: v.number() },
             returns: hostAffiliatesReportValidator,
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "report.affiliates", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "report.affiliates",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.affiliatesReport(ctx, args);
             },
         }),
+        vitalsReport: queryGeneric({
+            args: { siteId: v.string(), from: v.number(), to: v.number() },
+            returns: hostVitalsReportValidator,
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "report.vitals",
+                    siteIds: [args.siteId],
+                });
+                return await rastro.vitalsReport(ctx, args);
+            },
+        }),
+        siteMap: queryGeneric({
+            args: {
+                siteIds: v.array(v.string()),
+                from: v.number(),
+                to: v.number(),
+            },
+            returns: hostSiteMapValidator,
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "report.siteMap",
+                    siteIds: args.siteIds,
+                });
+                return await rastro.siteMap(ctx, args);
+            },
+        }),
+        dataCoverage: queryGeneric({
+            args: { siteId: v.string(), from: v.number(), to: v.number() },
+            returns: hostDataCoverageValidator,
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "coverage.read",
+                    siteIds: [args.siteId],
+                });
+                return await rastro.dataCoverage(ctx, args);
+            },
+        }),
+        retentionStatus: queryGeneric({
+            args: { siteId: v.string() },
+            returns: hostRetentionStatusValidator,
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "retention.status",
+                    siteIds: [args.siteId],
+                });
+                return await rastro.retentionStatus(ctx, args.siteId);
+            },
+        }),
+        setRetentionPolicy: mutationGeneric({
+            args: { siteId: v.string(), ...hostRetentionPolicyValidator.fields },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "retention.policy",
+                    siteIds: [args.siteId],
+                });
+                return await rastro.setRetentionPolicy(ctx, args);
+            },
+        }),
+        disableRetentionPolicy: mutationGeneric({
+            args: { siteId: v.string() },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "retention.policy",
+                    siteIds: [args.siteId],
+                });
+                return await rastro.disableRetentionPolicy(ctx, args.siteId);
+            },
+        }),
+        runRetentionPolicy: mutationGeneric({
+            args: {
+                siteId: v.string(),
+                kind: retentionKindValidator,
+                batchSize: v.optional(v.number()),
+            },
+            returns: v.object({
+                deleted: v.number(),
+                hasMore: v.boolean(),
+                before: v.number(),
+            }),
+            handler: async (ctx, args) => {
+                await options.authorize(ctx, {
+                    operation: "retention.policy",
+                    siteIds: [args.siteId],
+                });
+                return await rastro.runRetentionPolicy(ctx, args);
+            },
+        }),
         upsertGoal: mutationGeneric({
             args: {
                 siteId: v.string(),
@@ -481,7 +824,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: v.string(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "goal.upsert", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "goal.upsert",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.upsertGoal(ctx, args);
             },
         }),
@@ -489,7 +835,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string() },
             returns: v.array(hostGoalValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "goal.list", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "goal.list",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.listGoals(ctx, args.siteId);
             },
         }),
@@ -497,7 +846,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string(), goalId: v.string() },
             returns: v.null(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "goal.remove", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "goal.remove",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.removeGoal(ctx, args.siteId, args.goalId);
             },
         }),
@@ -513,7 +865,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: v.string(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "funnel.upsert", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "funnel.upsert",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.upsertFunnel(ctx, args);
             },
         }),
@@ -521,7 +876,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string() },
             returns: v.array(hostFunnelValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "funnel.list", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "funnel.list",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.listFunnels(ctx, args.siteId);
             },
         }),
@@ -529,7 +887,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string(), funnelId: v.string() },
             returns: v.null(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "funnel.remove", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "funnel.remove",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.removeFunnel(ctx, args.siteId, args.funnelId);
             },
         }),
@@ -545,7 +906,10 @@ export function exposeAnalyticsApi(component, options) {
             },
             returns: v.string(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "affiliate.upsert", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "affiliate.upsert",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.upsertAffiliate(ctx, args);
             },
         }),
@@ -553,7 +917,10 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string() },
             returns: v.array(hostAffiliateValidator),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "affiliate.list", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "affiliate.list",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.listAffiliates(ctx, args.siteId);
             },
         }),
@@ -561,30 +928,195 @@ export function exposeAnalyticsApi(component, options) {
             args: { siteId: v.string(), affiliateId: v.string() },
             returns: v.null(),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "affiliate.remove", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "affiliate.remove",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.removeAffiliate(ctx, args.siteId, args.affiliateId);
             },
         }),
         cleanupAnalytics: mutationGeneric({
             args: {
                 siteId: v.string(),
-                kind: v.union(v.literal("events"), v.literal("sessions"), v.literal("conversions"), v.literal("goalCompletions"), v.literal("aggregateHour"), v.literal("aggregateDay"), v.literal("funnelProgress"), v.literal("funnelSteps"), v.literal("affiliateStats"), v.literal("attributions"), v.literal("liveSessions"), v.literal("ingestWindows"), v.literal("siteIngestWindows")),
+                kind: v.union(v.literal("events"), v.literal("sessions"), v.literal("conversions"), v.literal("goalCompletions"), v.literal("aggregateHour"), v.literal("aggregateDay"), v.literal("funnelProgress"), v.literal("funnelSteps"), v.literal("affiliateStats"), v.literal("goalRollups"), v.literal("funnelRollups"), v.literal("affiliateRollups"), v.literal("vitalRollups"), v.literal("attributions"), v.literal("liveSessions"), v.literal("ingestWindows"), v.literal("siteIngestWindows")),
                 before: v.number(),
                 batchSize: v.optional(v.number()),
             },
-            returns: v.object({ deleted: v.number(), hasMore: v.boolean() }),
+            returns: v.object({
+                deleted: v.number(),
+                hasMore: v.boolean(),
+                before: v.number(),
+            }),
             handler: async (ctx, args) => {
-                await options.authorize(ctx, { operation: "retention.cleanup", siteIds: [args.siteId] });
+                await options.authorize(ctx, {
+                    operation: "retention.cleanup",
+                    siteIds: [args.siteId],
+                });
                 return await rastro.cleanup(ctx, args);
             },
         }),
     };
 }
+/**
+ * The federated operations that change a site, and so run only with the
+ * configure permission on both the token and the host's grant. Everything else
+ * on the federated surface is a read.
+ */
+const FEDERATED_CONFIGURE_OPERATIONS = new Set([
+    "site.update",
+    "goal.upsert",
+    "goal.list",
+    "goal.remove",
+    "funnel.upsert",
+    "funnel.list",
+    "funnel.remove",
+    "affiliate.upsert",
+    "affiliate.list",
+    "affiliate.remove",
+    "retention.policy",
+    "retention.status",
+]);
+const federatedSiteSettingsValidator = v.object({
+    siteId: v.string(),
+    name: v.string(),
+    domains: v.array(v.string()),
+    timezone: v.union(v.string(), v.null()),
+    currency: v.string(),
+    cookieless: v.boolean(),
+});
+/**
+ * Exposes the reactive read surface a federated Rastro dashboard subscribes to,
+ * plus the configuration functions behind the `configure` capability, which
+ * run only when the token and the host's grant both carry the configure
+ * permission.
+ */
+export function exposeFederatedAnalyticsApi(component, options) {
+    const authorizeConnection = createFederatedAnalyticsConnectionAuthorizer(options);
+    const requiredPermission = (operation) => FEDERATED_CONFIGURE_OPERATIONS.has(operation)
+        ? FEDERATED_ANALYTICS_CONFIGURE_PERMISSION
+        : FEDERATED_ANALYTICS_READ_PERMISSION;
+    const api = exposeAnalyticsApi(component, {
+        authorize: async (ctx, request) => {
+            await authorizeConnection(ctx, request.siteIds, requiredPermission(request.operation));
+        },
+    });
+    const rastro = new Rastro(component);
+    return {
+        manifest: queryGeneric({
+            args: {},
+            returns: federatedAnalyticsManifestValidator,
+            handler: () => createFederatedAnalyticsManifest(),
+        }),
+        connectionStatus: queryGeneric({
+            args: {},
+            returns: federatedAnalyticsConnectionStatusValidator,
+            handler: async (ctx) => {
+                const connection = await authorizeConnection(ctx);
+                return {
+                    status: "connected",
+                    protocolVersion: FEDERATED_ANALYTICS_CONNECTOR_MANIFEST.protocolVersion,
+                    capabilities: [
+                        ...FEDERATED_ANALYTICS_CONNECTOR_MANIFEST.capabilities,
+                    ],
+                    permissions: connection.effectivePermissions,
+                    siteCount: connection.siteIds.length,
+                };
+            },
+        }),
+        listSites: queryGeneric({
+            args: {},
+            returns: v.array(federatedSiteSummaryValidator),
+            handler: async (ctx) => {
+                const connection = await authorizeConnection(ctx);
+                const summaries = [];
+                for (const siteId of connection.siteIds) {
+                    const site = await rastro.getSite(ctx, siteId);
+                    if (!site)
+                        continue;
+                    summaries.push({
+                        siteId: site._id,
+                        name: site.name,
+                        currency: site.currency ?? "USD",
+                        timezone: site.timezone ?? null,
+                        cookieless: site.cookieless,
+                        localDays: await rastro.localDays(ctx, siteId),
+                    });
+                }
+                return summaries;
+            },
+        }),
+        overview: api.overview,
+        liveVisitors: api.liveVisitors,
+        listSessions: api.listSessions,
+        sessionJourney: api.sessionJourney,
+        listConversions: api.listConversions,
+        visitorJourney: api.visitorJourney,
+        goalsReport: api.goalsReport,
+        funnelsReport: api.funnelsReport,
+        affiliatesReport: api.affiliatesReport,
+        vitalsReport: api.vitalsReport,
+        siteMap: api.siteMap,
+        dataCoverage: api.dataCoverage,
+        // The configure surface. `listSites` stays redacted for every reader; the
+        // domains a site accepts are shown only to a connection allowed to change
+        // them, and the site's currency is reported here because the ledger
+        // forbids changing it after the first conversion is accounted.
+        siteSettings: queryGeneric({
+            args: { siteId: v.string() },
+            returns: federatedSiteSettingsValidator,
+            handler: async (ctx, args) => {
+                await authorizeConnection(ctx, [args.siteId], FEDERATED_ANALYTICS_CONFIGURE_PERMISSION);
+                const site = await rastro.getSite(ctx, args.siteId);
+                if (!site) {
+                    throw new ConvexError({
+                        code: "NOT_FOUND",
+                        message: "site not found",
+                        details: null,
+                    });
+                }
+                return {
+                    siteId: site._id,
+                    name: site.name,
+                    domains: site.domains,
+                    timezone: site.timezone ?? null,
+                    currency: site.currency ?? "USD",
+                    cookieless: site.cookieless,
+                };
+            },
+        }),
+        updateSite: mutationGeneric({
+            args: {
+                siteId: v.string(),
+                name: v.optional(v.string()),
+                domains: v.optional(v.array(v.string())),
+                timezone: v.optional(v.union(v.string(), v.null())),
+            },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                await authorizeConnection(ctx, [args.siteId], FEDERATED_ANALYTICS_CONFIGURE_PERMISSION);
+                return await rastro.updateSite(ctx, args);
+            },
+        }),
+        listGoals: api.listGoals,
+        upsertGoal: api.upsertGoal,
+        removeGoal: api.removeGoal,
+        listFunnels: api.listFunnels,
+        upsertFunnel: api.upsertFunnel,
+        removeFunnel: api.removeFunnel,
+        listAffiliates: api.listAffiliates,
+        upsertAffiliate: api.upsertAffiliate,
+        removeAffiliate: api.removeAffiliate,
+        retentionStatus: api.retentionStatus,
+        setRetentionPolicy: api.setRetentionPolicy,
+        disableRetentionPolicy: api.disableRetentionPolicy,
+    };
+}
 export function componentHttpPaths(prefix = "/rastro/") {
     const normalized = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
     return {
         events: `${normalized}/events`,
         tracker: `${normalized}/tracker.js`,
+        vitals: `${normalized}/vitals.js`,
         health: `${normalized}/health`,
     };
 }