@nuxtseo/protocol 0.1.0

package/dist/analytics-codecs/analytics-row.d.ts

@@ -0,0 +1,265 @@
+import { z } from 'zod';
+export declare const analyticsProviderSchema: z.ZodEnum<{
+    cloudflare: "cloudflare";
+    ga4: "ga4";
+    plausible: "plausible";
+    posthog: "posthog";
+    umami: "umami";
+}>;
+export type AnalyticsProvider = z.infer<typeof analyticsProviderSchema>;
+/**
+ * Dimensions every provider can be asked to group by. `source`/`medium`/
+ *  `campaign` are the UTM-style traffic-attribution triple — a provider with no
+ *  analog for one of them (Cloudflare RUM has only a referrer host) resolves it
+ *  to an empty string rather than erroring, mirroring how metrics resolve to 0.
+ *  Provider-native dimensions with no cross-provider analog go through the
+ *  per-provider escape hatch on the query, not this enum.
+ */
+export declare const analyticsDimensionSchema: z.ZodEnum<{
+    browser: "browser";
+    campaign: "campaign";
+    city: "city";
+    country: "country";
+    date: "date";
+    deviceCategory: "deviceCategory";
+    hostname: "hostname";
+    medium: "medium";
+    operatingSystem: "operatingSystem";
+    page: "page";
+    region: "region";
+    source: "source";
+}>;
+export type AnalyticsDimension = z.infer<typeof analyticsDimensionSchema>;
+/**
+ * Metrics every provider maps onto. Cloudflare Web Analytics has no concept of
+ *  conversions/keyEvents; those resolve to 0 rather than erroring.
+ */
+export declare const analyticsMetricSchema: z.ZodEnum<{
+    avgSessionDuration: "avgSessionDuration";
+    bounceRate: "bounceRate";
+    conversions: "conversions";
+    engagementRate: "engagementRate";
+    keyEvents: "keyEvents";
+    pageviews: "pageviews";
+    sessions: "sessions";
+    users: "users";
+}>;
+export type AnalyticsMetric = z.infer<typeof analyticsMetricSchema>;
+/**
+ * Cloudflare-only RUM dimensions with no cross-provider analog. Kept out of the
+ * generic `analyticsDimensionSchema` (they would be dead weight on GA4); reached
+ * through the opt-in `cloudflare` escape hatch on the query and the row. The enum
+ * values are the raw Cloudflare RUM field names.
+ */
+export declare const cloudflareDimensionSchema: z.ZodEnum<{
+    bot: "bot";
+    deliveryType: "deliveryType";
+    navigationType: "navigationType";
+}>;
+export type CloudflareDimension = z.infer<typeof cloudflareDimensionSchema>;
+/** Query-side hatch — opt a provider into raw native dimensions/metrics. */
+export declare const cloudflareQueryHatchSchema: z.ZodObject<{
+    dimensions: z.ZodArray<z.ZodEnum<{
+        bot: "bot";
+        deliveryType: "deliveryType";
+        navigationType: "navigationType";
+    }>>;
+}, z.core.$strip>;
+export type CloudflareQueryHatch = z.infer<typeof cloudflareQueryHatchSchema>;
+export declare const ga4QueryHatchSchema: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metrics: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Ga4QueryHatch = z.infer<typeof ga4QueryHatchSchema>;
+export declare const posthogQueryHatchSchema: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type PosthogQueryHatch = z.infer<typeof posthogQueryHatchSchema>;
+/** Row-side hatch — raw native values grouped onto one result row. */
+export declare const cloudflareRowHatchSchema: z.ZodRecord<z.ZodEnum<{
+    bot: "bot";
+    deliveryType: "deliveryType";
+    navigationType: "navigationType";
+}> & z.core.$partial, z.ZodString>;
+export type CloudflareRowHatch = z.infer<typeof cloudflareRowHatchSchema>;
+export declare const ga4RowHatchSchema: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type Ga4RowHatch = z.infer<typeof ga4RowHatchSchema>;
+export declare const posthogRowHatchSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type PosthogRowHatch = z.infer<typeof posthogRowHatchSchema>;
+/**
+ * One grouped result: dimension values keyed by name, metric values keyed by
+ *  name. Partial records — a row only carries what its query asked for.
+ */
+export declare const analyticsRowSchema: z.ZodObject<{
+    dimensions: z.ZodRecord<z.ZodEnum<{
+        browser: "browser";
+        campaign: "campaign";
+        city: "city";
+        country: "country";
+        date: "date";
+        deviceCategory: "deviceCategory";
+        hostname: "hostname";
+        medium: "medium";
+        operatingSystem: "operatingSystem";
+        page: "page";
+        region: "region";
+        source: "source";
+    }> & z.core.$partial, z.ZodString>;
+    metrics: z.ZodRecord<z.ZodEnum<{
+        avgSessionDuration: "avgSessionDuration";
+        bounceRate: "bounceRate";
+        conversions: "conversions";
+        engagementRate: "engagementRate";
+        keyEvents: "keyEvents";
+        pageviews: "pageviews";
+        sessions: "sessions";
+        users: "users";
+    }> & z.core.$partial, z.ZodNumber>;
+    cloudflare: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bot: "bot";
+        deliveryType: "deliveryType";
+        navigationType: "navigationType";
+    }> & z.core.$partial, z.ZodString>>;
+    ga4: z.ZodOptional<z.ZodObject<{
+        dimensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>>;
+    posthog: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type AnalyticsRow = z.infer<typeof analyticsRowSchema>;
+/**
+ * Cross-provider filter operators. Kept to the set every provider can serve so
+ * a portable filter degrades predictably:
+ *  - `is` / `isNot` — exact-match (and its negation).
+ *  - `in` — match any of a value list.
+ *  - `contains` — substring match.
+ * Regex / OR-groups are intentionally absent: Cloudflare RUM can't express them,
+ * so they would not be portable. Reach for the per-provider escape hatch instead.
+ */
+export declare const analyticsFilterOpSchema: z.ZodEnum<{
+    contains: "contains";
+    in: "in";
+    is: "is";
+    isNot: "isNot";
+}>;
+export type AnalyticsFilterOp = z.infer<typeof analyticsFilterOpSchema>;
+/**
+ * One portable filter predicate over a generic dimension. Translated per
+ * provider (GA4 `dimensionFilter`, Cloudflare GraphQL filter keys, PostHog HogQL
+ * `WHERE`). A provider with no field for `dimension` drops the predicate rather
+ * than erroring — same graceful-degrade contract as dimensions resolving to `''`
+ * (e.g. Cloudflare RUM has no `medium`/`campaign`, so those filters are no-ops
+ * there). `value` is a single string for `is`/`isNot`/`contains` and a list for
+ * `in` (a bare string is accepted and treated as a one-element list).
+ */
+export declare const analyticsFilterSchema: z.ZodObject<{
+    dimension: z.ZodEnum<{
+        browser: "browser";
+        campaign: "campaign";
+        city: "city";
+        country: "country";
+        date: "date";
+        deviceCategory: "deviceCategory";
+        hostname: "hostname";
+        medium: "medium";
+        operatingSystem: "operatingSystem";
+        page: "page";
+        region: "region";
+        source: "source";
+    }>;
+    op: z.ZodEnum<{
+        contains: "contains";
+        in: "in";
+        is: "is";
+        isNot: "isNot";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    caseInsensitive: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AnalyticsFilter = z.input<typeof analyticsFilterSchema>;
+/**
+ * A provider-agnostic query. The provider client owns translation into GA4's
+ *  `runReport` body or Cloudflare's GraphQL document.
+ */
+export declare const analyticsQuerySchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        cloudflare: "cloudflare";
+        ga4: "ga4";
+        plausible: "plausible";
+        posthog: "posthog";
+        umami: "umami";
+    }>;
+    propertyId: z.ZodString;
+    dimensions: z.ZodArray<z.ZodEnum<{
+        browser: "browser";
+        campaign: "campaign";
+        city: "city";
+        country: "country";
+        date: "date";
+        deviceCategory: "deviceCategory";
+        hostname: "hostname";
+        medium: "medium";
+        operatingSystem: "operatingSystem";
+        page: "page";
+        region: "region";
+        source: "source";
+    }>>;
+    metrics: z.ZodArray<z.ZodEnum<{
+        avgSessionDuration: "avgSessionDuration";
+        bounceRate: "bounceRate";
+        conversions: "conversions";
+        engagementRate: "engagementRate";
+        keyEvents: "keyEvents";
+        pageviews: "pageviews";
+        sessions: "sessions";
+        users: "users";
+    }>>;
+    dateRange: z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    excludeBots: z.ZodDefault<z.ZodBoolean>;
+    filters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        dimension: z.ZodEnum<{
+            browser: "browser";
+            campaign: "campaign";
+            city: "city";
+            country: "country";
+            date: "date";
+            deviceCategory: "deviceCategory";
+            hostname: "hostname";
+            medium: "medium";
+            operatingSystem: "operatingSystem";
+            page: "page";
+            region: "region";
+            source: "source";
+        }>;
+        op: z.ZodEnum<{
+            contains: "contains";
+            in: "in";
+            is: "is";
+            isNot: "isNot";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+        caseInsensitive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    cloudflare: z.ZodOptional<z.ZodObject<{
+        dimensions: z.ZodArray<z.ZodEnum<{
+            bot: "bot";
+            deliveryType: "deliveryType";
+            navigationType: "navigationType";
+        }>>;
+    }, z.core.$strip>>;
+    ga4: z.ZodOptional<z.ZodObject<{
+        dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metrics: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    posthog: z.ZodOptional<z.ZodObject<{
+        dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AnalyticsQuery = z.input<typeof analyticsQuerySchema>;

package/dist/analytics-codecs/analytics-row.js

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+// The normalized, provider-agnostic data shape for Web Analytics. GA4 and
+// Cloudflare provider clients reshape their raw API responses onto `AnalyticsRow`.
+// Generic — carries no Pro or nuxtseo.com concepts. See ADR-0032 §2.
+export const analyticsProviderSchema = z.enum(['ga4', 'cloudflare', 'posthog', 'umami', 'plausible']);
+/**
+ * Dimensions every provider can be asked to group by. `source`/`medium`/
+ *  `campaign` are the UTM-style traffic-attribution triple — a provider with no
+ *  analog for one of them (Cloudflare RUM has only a referrer host) resolves it
+ *  to an empty string rather than erroring, mirroring how metrics resolve to 0.
+ *  Provider-native dimensions with no cross-provider analog go through the
+ *  per-provider escape hatch on the query, not this enum.
+ */
+export const analyticsDimensionSchema = z.enum([
+    'date',
+    'page',
+    'hostname',
+    'source',
+    'medium',
+    'campaign',
+    'country',
+    'region',
+    'city',
+    'deviceCategory',
+    'browser',
+    'operatingSystem',
+]);
+/**
+ * Metrics every provider maps onto. Cloudflare Web Analytics has no concept of
+ *  conversions/keyEvents; those resolve to 0 rather than erroring.
+ */
+export const analyticsMetricSchema = z.enum([
+    'sessions',
+    'users',
+    'pageviews',
+    'conversions',
+    'keyEvents',
+    'engagementRate',
+    'bounceRate',
+    'avgSessionDuration',
+]);
+/**
+ * Cloudflare-only RUM dimensions with no cross-provider analog. Kept out of the
+ * generic `analyticsDimensionSchema` (they would be dead weight on GA4); reached
+ * through the opt-in `cloudflare` escape hatch on the query and the row. The enum
+ * values are the raw Cloudflare RUM field names.
+ */
+export const cloudflareDimensionSchema = z.enum([
+    'navigationType',
+    'deliveryType',
+    'bot',
+]);
+// --- Provider escape hatches -----------------------------------------------
+//
+// Each provider may be opted into raw provider-native fields that have no
+// cross-provider analog. Field names are validated, never bare strings:
+//  - Cloudflare RUM dimensions are a closed enum (`cloudflareDimensionSchema`).
+//  - GA4 Data API names are word chars plus `:` — the `:` admits custom
+//    `customEvent:*` / `customUser:*` dimensions; the set is otherwise open.
+//  - PostHog hatch values are HogQL `$pageview` property expressions, dotted
+//    `$`-identifiers. The regex doubles as a HogQL injection guard, since the
+//    expression is interpolated into the generated SQL.
+const ga4FieldNameSchema = z.string().regex(/^[\w:]+$/, 'invalid GA4 field name');
+const posthogPropertyExprSchema = z.string().regex(/^[\w$.]+$/, 'invalid PostHog property expression');
+/** Query-side hatch — opt a provider into raw native dimensions/metrics. */
+export const cloudflareQueryHatchSchema = z.object({
+    dimensions: z.array(cloudflareDimensionSchema),
+});
+export const ga4QueryHatchSchema = z.object({
+    dimensions: z.array(ga4FieldNameSchema).optional(),
+    metrics: z.array(ga4FieldNameSchema).optional(),
+});
+export const posthogQueryHatchSchema = z.object({
+    dimensions: z.array(posthogPropertyExprSchema).optional(),
+});
+/** Row-side hatch — raw native values grouped onto one result row. */
+export const cloudflareRowHatchSchema = z.partialRecord(cloudflareDimensionSchema, z.string());
+export const ga4RowHatchSchema = z.object({
+    dimensions: z.record(ga4FieldNameSchema, z.string()).optional(),
+    metrics: z.record(ga4FieldNameSchema, z.number()).optional(),
+});
+export const posthogRowHatchSchema = z.record(posthogPropertyExprSchema, z.string());
+/**
+ * One grouped result: dimension values keyed by name, metric values keyed by
+ *  name. Partial records — a row only carries what its query asked for.
+ */
+export const analyticsRowSchema = z.object({
+    dimensions: z.partialRecord(analyticsDimensionSchema, z.string()),
+    metrics: z.partialRecord(analyticsMetricSchema, z.number()),
+    /**
+     * Raw provider-native values — present only when the query opted into a
+     *  provider escape hatch (`query.cloudflare` / `query.ga4` / `query.posthog`),
+     *  and only on rows from that provider. Keyed by the raw provider field name.
+     *  Cloudflare's keys are a closed enum; GA4's and PostHog's are open string
+     *  records because those providers expose unbounded (incl. custom) fields.
+     */
+    cloudflare: cloudflareRowHatchSchema.optional(),
+    ga4: ga4RowHatchSchema.optional(),
+    posthog: posthogRowHatchSchema.optional(),
+});
+/**
+ * Cross-provider filter operators. Kept to the set every provider can serve so
+ * a portable filter degrades predictably:
+ *  - `is` / `isNot` — exact-match (and its negation).
+ *  - `in` — match any of a value list.
+ *  - `contains` — substring match.
+ * Regex / OR-groups are intentionally absent: Cloudflare RUM can't express them,
+ * so they would not be portable. Reach for the per-provider escape hatch instead.
+ */
+export const analyticsFilterOpSchema = z.enum(['is', 'isNot', 'in', 'contains']);
+/**
+ * One portable filter predicate over a generic dimension. Translated per
+ * provider (GA4 `dimensionFilter`, Cloudflare GraphQL filter keys, PostHog HogQL
+ * `WHERE`). A provider with no field for `dimension` drops the predicate rather
+ * than erroring — same graceful-degrade contract as dimensions resolving to `''`
+ * (e.g. Cloudflare RUM has no `medium`/`campaign`, so those filters are no-ops
+ * there). `value` is a single string for `is`/`isNot`/`contains` and a list for
+ * `in` (a bare string is accepted and treated as a one-element list).
+ */
+export const analyticsFilterSchema = z.object({
+    dimension: analyticsDimensionSchema,
+    op: analyticsFilterOpSchema,
+    value: z.union([z.string(), z.array(z.string())]),
+    /**
+     * Match case-insensitively. Defaults true so cross-provider dimension values
+     * with inconsistent casing (e.g. PostHog `$device_type` is `Desktop`, GA4
+     * `deviceCategory` is `desktop`) match the same filter. Cloudflare RUM has no
+     * case-insensitive operator, so it is best-effort there.
+     */
+    caseInsensitive: z.boolean().default(true),
+});
+/**
+ * A provider-agnostic query. The provider client owns translation into GA4's
+ *  `runReport` body or Cloudflare's GraphQL document.
+ */
+export const analyticsQuerySchema = z.object({
+    provider: analyticsProviderSchema,
+    /** GA4 property id or Cloudflare Web Analytics site tag. */
+    propertyId: z.string().min(1),
+    dimensions: z.array(analyticsDimensionSchema),
+    metrics: z.array(analyticsMetricSchema).min(1),
+    dateRange: z.object({
+        from: z.string(), // ISO yyyy-mm-dd
+        to: z.string(),
+    }),
+    limit: z.number().int().positive().optional(),
+    /**
+     * Exclude automated traffic. Default true. Cloudflare applies a `bot: 0`
+     * filter; GA4 already excludes known bots from every report, so it is a
+     * no-op there.
+     */
+    excludeBots: z.boolean().default(true),
+    /**
+     * Portable dimension filters, ANDed together and applied on top of the date
+     * window + `excludeBots`. Each provider translates what it can and silently
+     * drops predicates over dimensions it has no field for (see
+     * `analyticsFilterSchema`). Empty by default (no filtering).
+     */
+    filters: z.array(analyticsFilterSchema).default([]),
+    /**
+     * Provider-specific escape hatches. Each opts the matching provider into raw
+     * provider-native fields with no cross-provider analog; the grouped values
+     * come back on the matching key of `AnalyticsRow`. A provider ignores hatches
+     * addressed to other providers.
+     *
+     * - `cloudflare` — Cloudflare-only RUM dimensions (closed enum).
+     * - `ga4` — raw GA4 Data API dimension/metric names, including custom
+     *   `customEvent:*` / `customUser:*` dimensions.
+     * - `posthog` — raw HogQL `$pageview` property expressions (e.g.
+     *   `properties.$browser_version`); validated as dotted identifiers.
+     */
+    cloudflare: cloudflareQueryHatchSchema.optional(),
+    ga4: ga4QueryHatchSchema.optional(),
+    posthog: posthogQueryHatchSchema.optional(),
+});

package/dist/analytics-codecs/analytics-web-vitals.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+export declare const analyticsWebVitalsRowSchema: z.ZodObject<{
+    date: z.ZodString;
+    lcpP75: z.ZodNullable<z.ZodNumber>;
+    inpP75: z.ZodNullable<z.ZodNumber>;
+    clsP75: z.ZodNullable<z.ZodNumber>;
+    lcpGood: z.ZodNumber;
+    lcpNeedsImprovement: z.ZodNumber;
+    lcpPoor: z.ZodNumber;
+    inpGood: z.ZodNumber;
+    inpNeedsImprovement: z.ZodNumber;
+    inpPoor: z.ZodNumber;
+    clsGood: z.ZodNumber;
+    clsNeedsImprovement: z.ZodNumber;
+    clsPoor: z.ZodNumber;
+}, z.core.$strip>;
+export type AnalyticsWebVitalsRow = z.infer<typeof analyticsWebVitalsRowSchema>;
+/** The three Core Web Vitals a RUM dataset attributes to a DOM element. */
+export declare const webVitalsMetricSchema: z.ZodEnum<{
+    cls: "cls";
+    inp: "inp";
+    lcp: "lcp";
+}>;
+export type WebVitalsMetric = z.infer<typeof webVitalsMetricSchema>;
+export declare const analyticsWebVitalsElementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    route: z.ZodString;
+    selector: z.ZodString;
+    p75: z.ZodNullable<z.ZodNumber>;
+    count: z.ZodNumber;
+    poorFraction: z.ZodNullable<z.ZodNumber>;
+    metric: z.ZodLiteral<"lcp">;
+    resource: z.ZodNullable<z.ZodString>;
+    fetchPriority: z.ZodNullable<z.ZodString>;
+    initiatorType: z.ZodNullable<z.ZodString>;
+    phases: z.ZodObject<{
+        timeToFirstByte: z.ZodNullable<z.ZodNumber>;
+        resourceLoadDelay: z.ZodNullable<z.ZodNumber>;
+        resourceLoadTime: z.ZodNullable<z.ZodNumber>;
+        elementRenderDelay: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    route: z.ZodString;
+    selector: z.ZodString;
+    p75: z.ZodNullable<z.ZodNumber>;
+    count: z.ZodNumber;
+    poorFraction: z.ZodNullable<z.ZodNumber>;
+    metric: z.ZodLiteral<"inp">;
+    actionName: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    route: z.ZodString;
+    selector: z.ZodString;
+    p75: z.ZodNullable<z.ZodNumber>;
+    count: z.ZodNumber;
+    poorFraction: z.ZodNullable<z.ZodNumber>;
+    metric: z.ZodLiteral<"cls">;
+}, z.core.$strip>], "metric">;
+export type AnalyticsWebVitalsElement = z.infer<typeof analyticsWebVitalsElementSchema>;

package/dist/analytics-codecs/analytics-web-vitals.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+// Field-data Core Web Vitals from a provider's RUM dataset (real users), one row
+// per day. Distinct from the traffic metrics in `analytics-row` — web vitals are
+// p75 quantiles + good/needs-improvement/poor distribution counts, not summable
+// counts. Only providers with a RUM web-vitals dataset emit these (Cloudflare).
+// The shape mirrors the Pro CrUX `CwvHistoryRow` so a consumer can drop it into
+// the existing Core Web Vitals surface as a fallback when CrUX has no data.
+export const analyticsWebVitalsRowSchema = z.object({
+    /** ISO `yyyy-mm-dd`. */
+    date: z.string(),
+    /** p75 — the headline CrUX-parity figure. Null when the metric has no samples. */
+    lcpP75: z.number().nullable(),
+    inpP75: z.number().nullable(),
+    clsP75: z.number().nullable(),
+    // Provider observations behind the good/needs-improvement/poor histogram.
+    // Adaptive-provider estimates are normalized to their effective sample size.
+    lcpGood: z.number(),
+    lcpNeedsImprovement: z.number(),
+    lcpPoor: z.number(),
+    inpGood: z.number(),
+    inpNeedsImprovement: z.number(),
+    inpPoor: z.number(),
+    clsGood: z.number(),
+    clsNeedsImprovement: z.number(),
+    clsPoor: z.number(),
+});
+/** The three Core Web Vitals a RUM dataset attributes to a DOM element. */
+export const webVitalsMetricSchema = z.enum(['lcp', 'inp', 'cls']);
+// Per-element field-CWV attribution — one DOM element behind a metric, from the
+// provider's RUM dataset, discriminated by `metric`. This is the "what to fix"
+// payload: `selector` is the element's DOM path, grep-able in the user's own
+// source. LCP additionally carries the resource + fetch-priority + phase split
+// (so a text-LCP vs image-LCP fix can be told apart); INP carries the interaction
+// action; CLS carries only the shifted element. `count` is a provider-sampled
+// estimate (Cloudflare adaptive sampling), never exact. Rank by severity and
+// label it as estimated.
+const elementBase = {
+    /** Page path where the element was observed (`requestPath`). */
+    route: z.string(),
+    /** DOM selector of the element — grep-able in the user's source. */
+    selector: z.string(),
+    /** p75: ms for lcp/inp, unitless for cls. Null when the group has no samples. */
+    p75: z.number().nullable(),
+    /** Sampled estimate of affected page views, not an exact count. */
+    count: z.number(),
+    /** poor / (good + ni + poor) for this element, or null when no distribution. */
+    poorFraction: z.number().nullable(),
+};
+export const analyticsWebVitalsElementSchema = z.discriminatedUnion('metric', [
+    z.object({
+        metric: z.literal('lcp'),
+        ...elementBase,
+        /** Host+path of the LCP resource. Null = text LCP (heading/paragraph). */
+        resource: z.string().nullable(),
+        /** `fetchpriority` the browser saw on the LCP element. Null when n/a. */
+        fetchPriority: z.string().nullable(),
+        initiatorType: z.string().nullable(),
+        /** The four LCP sub-phases (ms averages) — which one dominates names the fix. */
+        phases: z.object({
+            timeToFirstByte: z.number().nullable(),
+            resourceLoadDelay: z.number().nullable(),
+            resourceLoadTime: z.number().nullable(),
+            elementRenderDelay: z.number().nullable(),
+        }),
+    }),
+    z.object({
+        metric: z.literal('inp'),
+        ...elementBase,
+        /** Interaction type behind the delay (pointer/keyboard/…). */
+        actionName: z.string().nullable(),
+    }),
+    z.object({
+        metric: z.literal('cls'),
+        ...elementBase,
+    }),
+]);

package/dist/analytics-codecs/capabilities.d.ts

@@ -0,0 +1,35 @@
+import type { AnalyticsDimension, AnalyticsMetric, AnalyticsProvider } from './analytics-row.js';
+export interface AnalyticsCapabilities {
+    /** Aggregate (dimensionless) metrics that carry real data; others resolve to 0. */
+    aggregateMetrics: AnalyticsMetric[];
+    /**
+     * Count metrics with a real per-day series. A subset of `{sessions, users,
+     * pageviews}` — drives the chartable series. Cloudflare's `users` equals
+     * `sessions` (drop the duplicate); Umami has no per-day visitors series.
+     */
+    seriesMetrics: AnalyticsMetric[];
+    /** Dimensions with a real breakdown; others return an empty list. */
+    breakdownDimensions: AnalyticsDimension[];
+    /**
+     * Count metrics populated PER breakdown row. Umami's `/metrics` returns a
+     * visitor count only (`['users']`); everything else returns the full
+     * `{sessions, users, pageviews}`. Drives breakdown ranking + visible columns.
+     */
+    breakdownMetrics: AnalyticsMetric[];
+    /** The session-quality metric the provider reports, or null (neither). */
+    quality: 'engagementRate' | 'bounceRate' | null;
+    /** Field-data Core Web Vitals (RUM) dataset available (`queryWebVitals`). */
+    webVitals: boolean;
+    /** Key events / conversions available. */
+    keyEvents: boolean;
+}
+export declare const ANALYTICS_CAPABILITIES: Record<AnalyticsProvider, AnalyticsCapabilities>;
+export declare function getAnalyticsCapabilities(provider: string | null | undefined): AnalyticsCapabilities | null;
+/**
+ * The metric to rank/show a breakdown by. Returns `preferred` when the provider
+ * populates it per row (the common case: pages by pageviews, else sessions),
+ * otherwise the provider's single available breakdown metric — Umami serves a
+ * visitor count only, so every breakdown there ranks by `users`. An unknown
+ * provider keeps `preferred`.
+ */
+export declare function resolveBreakdownMetric(provider: string | null | undefined, preferred: AnalyticsMetric): AnalyticsMetric;