@nuxtseo/protocol 0.1.0

package/dist/analytics-codecs/capabilities.js

@@ -0,0 +1,76 @@
+const COUNTS = ['sessions', 'users', 'pageviews'];
+const ALL_DIMENSIONS = ['page', 'hostname', 'source', 'medium', 'campaign', 'country', 'region', 'city', 'deviceCategory', 'browser', 'operatingSystem'];
+// Dimensions every provider EXCEPT Cloudflare can break down (CF RUM has only a
+// referrer host + country, no UTM tuple, no region/city).
+const NON_CF_DIMENSIONS = ALL_DIMENSIONS;
+export const ANALYTICS_CAPABILITIES = {
+    ga4: {
+        aggregateMetrics: ['sessions', 'users', 'pageviews', 'conversions', 'keyEvents', 'engagementRate', 'bounceRate', 'avgSessionDuration'],
+        seriesMetrics: COUNTS,
+        breakdownDimensions: ALL_DIMENSIONS,
+        breakdownMetrics: COUNTS,
+        quality: 'engagementRate',
+        webVitals: false,
+        keyEvents: true,
+    },
+    cloudflare: {
+        // CF Web Analytics serves only pageviews + visits; `users` mirrors sessions.
+        aggregateMetrics: ['sessions', 'users', 'pageviews'],
+        seriesMetrics: ['sessions', 'pageviews'],
+        breakdownDimensions: ['page', 'hostname', 'source', 'country', 'deviceCategory', 'browser', 'operatingSystem'],
+        breakdownMetrics: COUNTS,
+        quality: null,
+        webVitals: true,
+        keyEvents: false,
+    },
+    posthog: {
+        aggregateMetrics: ['sessions', 'users', 'pageviews'],
+        seriesMetrics: COUNTS,
+        breakdownDimensions: NON_CF_DIMENSIONS,
+        breakdownMetrics: COUNTS,
+        quality: null,
+        webVitals: true,
+        keyEvents: false,
+    },
+    umami: {
+        // `keyEvents` = custom-event occurrences (umami.track), fetched separately.
+        aggregateMetrics: ['sessions', 'users', 'pageviews', 'bounceRate', 'avgSessionDuration', 'keyEvents'],
+        // `/pageviews` emits only pageviews + sessions series (no per-day visitors).
+        seriesMetrics: ['sessions', 'pageviews'],
+        // No UTM medium/campaign breakdown on the Cloud API.
+        breakdownDimensions: ['page', 'hostname', 'source', 'country', 'region', 'city', 'deviceCategory', 'browser', 'operatingSystem'],
+        // `/metrics` returns a visitor count only — pageviews/sessions per row N/A.
+        breakdownMetrics: ['users'],
+        quality: 'bounceRate',
+        webVitals: false,
+        keyEvents: true,
+    },
+    plausible: {
+        // `keyEvents` = goal conversions (the `events` metric on `event:goal`).
+        aggregateMetrics: ['sessions', 'users', 'pageviews', 'keyEvents', 'bounceRate', 'avgSessionDuration'],
+        seriesMetrics: COUNTS,
+        breakdownDimensions: NON_CF_DIMENSIONS,
+        breakdownMetrics: COUNTS,
+        quality: 'bounceRate',
+        webVitals: false,
+        keyEvents: true,
+    },
+};
+export function getAnalyticsCapabilities(provider) {
+    return provider && provider in ANALYTICS_CAPABILITIES
+        ? ANALYTICS_CAPABILITIES[provider]
+        : 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 function resolveBreakdownMetric(provider, preferred) {
+    const cap = getAnalyticsCapabilities(provider);
+    if (!cap || cap.breakdownMetrics.includes(preferred))
+        return preferred;
+    return cap.breakdownMetrics[0] ?? preferred;
+}

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

@@ -0,0 +1,3 @@
+export * from './analytics-row.js';
+export * from './analytics-web-vitals.js';
+export * from './capabilities.js';

package/dist/analytics-codecs/index.js

@@ -0,0 +1,3 @@
+export * from './analytics-row.js';
+export * from './analytics-web-vitals.js';
+export * from './capabilities.js';

package/dist/cli-pairing.d.ts

@@ -0,0 +1,67 @@
+import type { z } from 'zod';
+export declare const CLI_PAIRING_START_PATH: '/api/cli/pair/start';
+export declare const CLI_PAIRING_POLL_PATH: '/api/cli/pair/poll';
+/** How long a pairing request stays approvable. */
+export declare const CLI_PAIRING_TTL_MS = 600000;
+/** Cadence the CLI must respect. The server rejects a faster caller. */
+export declare const CLI_PAIRING_POLL_INTERVAL_MS = 2000;
+/** Backstop against a hostile client hammering one pairing ID. */
+export declare const CLI_PAIRING_MAX_POLLS = 400;
+export declare const cliPairingStartRequestSchema: z.ZodObject<{
+    clientName: z.ZodString;
+    clientVersion: z.ZodOptional<z.ZodString>;
+    hostname: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const cliPairingStartResponseSchema: z.ZodObject<{
+    pairingId: z.ZodString;
+    pairingCode: z.ZodString;
+    pollSecret: z.ZodString;
+    verificationUrl: z.ZodString;
+    expiresAt: z.ZodString;
+    pollIntervalMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const cliPairingPollRequestSchema: z.ZodObject<{
+    pairingId: z.ZodString;
+    pollSecret: z.ZodString;
+}, z.core.$strict>;
+export declare const cliPairingApprovedSchema: z.ZodObject<{
+    status: z.ZodLiteral<"approved">;
+    token: z.ZodString;
+    teamId: z.ZodString;
+    teamName: z.ZodNullable<z.ZodString>;
+    role: z.ZodEnum<{
+        admin: "admin";
+        editor: "editor";
+        viewer: "viewer";
+    }>;
+    last4: z.ZodString;
+}, z.core.$strict>;
+export declare const cliPairingPollResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"pending">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"denied">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"expired">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"claimed">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"slow_down">;
+    retryAfterMs: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"approved">;
+    token: z.ZodString;
+    teamId: z.ZodString;
+    teamName: z.ZodNullable<z.ZodString>;
+    role: z.ZodEnum<{
+        admin: "admin";
+        editor: "editor";
+        viewer: "viewer";
+    }>;
+    last4: z.ZodString;
+}, z.core.$strict>], "status">;
+export type CliPairingStartRequest = z.infer<typeof cliPairingStartRequestSchema>;
+export type CliPairingStartResponse = z.infer<typeof cliPairingStartResponseSchema>;
+export type CliPairingPollRequest = z.infer<typeof cliPairingPollRequestSchema>;
+export type CliPairingPollResponse = z.infer<typeof cliPairingPollResponseSchema>;
+export type CliPairingApproved = z.infer<typeof cliPairingApprovedSchema>;
+export type CliPairingStatus = CliPairingPollResponse['status'];

package/dist/cli-pairing.js

@@ -0,0 +1,52 @@
+// CLI browser pairing wire format.
+//
+// This is deliberately NOT a public v1 operation. A v1 operation must declare at
+// least one credential (`assertOperation` in ./v1/core.ts), and every /api/v1
+// route is asserted to answer 401 without one. Pairing runs before the CLI holds
+// any credential, so it lives on its own unauthenticated routes and carries its
+// own schemas. Both the server routes and the CLI validate against these, so the
+// format still has a single owner.
+import { z as schema } from 'zod';
+export const CLI_PAIRING_START_PATH = '/api/cli/pair/start';
+export const CLI_PAIRING_POLL_PATH = '/api/cli/pair/poll';
+/** How long a pairing request stays approvable. */
+export const CLI_PAIRING_TTL_MS = 600_000;
+/** Cadence the CLI must respect. The server rejects a faster caller. */
+export const CLI_PAIRING_POLL_INTERVAL_MS = 2_000;
+/** Backstop against a hostile client hammering one pairing ID. */
+export const CLI_PAIRING_MAX_POLLS = 400;
+export const cliPairingStartRequestSchema = schema.strictObject({
+    clientName: schema.string().min(1).max(60),
+    clientVersion: schema.string().min(1).max(40).optional(),
+    hostname: schema.string().min(1).max(120).optional(),
+});
+export const cliPairingStartResponseSchema = schema.strictObject({
+    pairingId: schema.string().min(1),
+    /** Shown by the CLI and again on the approval page so the user can compare. */
+    pairingCode: schema.string().min(1),
+    /** Held only by the CLI. The server stores a hash. */
+    pollSecret: schema.string().min(1),
+    verificationUrl: schema.string().min(1),
+    expiresAt: schema.string().min(1),
+    pollIntervalMs: schema.number().int().positive(),
+});
+export const cliPairingPollRequestSchema = schema.strictObject({
+    pairingId: schema.string().min(1),
+    pollSecret: schema.string().min(1),
+});
+export const cliPairingApprovedSchema = schema.strictObject({
+    status: schema.literal('approved'),
+    token: schema.string().min(1),
+    teamId: schema.string().min(1),
+    teamName: schema.string().min(1).nullable(),
+    role: schema.enum(['admin', 'editor', 'viewer']),
+    last4: schema.string().min(1),
+});
+export const cliPairingPollResponseSchema = schema.discriminatedUnion('status', [
+    schema.strictObject({ status: schema.literal('pending') }),
+    schema.strictObject({ status: schema.literal('denied') }),
+    schema.strictObject({ status: schema.literal('expired') }),
+    schema.strictObject({ status: schema.literal('claimed') }),
+    schema.strictObject({ status: schema.literal('slow_down'), retryAfterMs: schema.number().int().positive() }),
+    cliPairingApprovedSchema,
+]);

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './v1/index.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './v1/index.js';