@nuxtseo/protocol 0.1.0

package/dist/v1/analytics.js

@@ -0,0 +1,296 @@
+import { z as schema } from 'zod';
+import { analyticsDimensionSchema, analyticsFilterSchema, analyticsProviderSchema } from '../analytics-codecs/index.js';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const analyticsViewSchema = schema.enum([
+    'performance',
+    'top-pages',
+    'source-medium',
+    'key-events',
+    'countries',
+    'devices',
+    'dimension',
+]);
+export const analyticsSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+    view: analyticsViewSchema,
+});
+function booleanQuerySchema(fallback) {
+    return schema
+        .union([schema.boolean(), schema.enum(['true', 'false'])])
+        .default(fallback)
+        .transform(value => value === true || value === 'true');
+}
+export const analyticsFiltersQuerySchema = schema.string().optional().transform((raw, context) => {
+    if (!raw)
+        return [];
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        context.addIssue({ code: 'custom', message: 'filters must be a JSON array' });
+        return schema.NEVER;
+    }
+    const parsed = schema.array(analyticsFilterSchema).safeParse(value);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues)
+            context.addIssue({ ...issue, path: ['filters', ...issue.path] });
+        return schema.NEVER;
+    }
+    return parsed.data;
+});
+export const analyticsReadQuerySchema = schema.strictObject({
+    period: schema.string().min(1).default('28d'),
+    compare: schema.enum(['previous', 'year', 'none']).default('previous'),
+    stableData: booleanQuerySchema(true),
+    filters: analyticsFiltersQuerySchema,
+    hostScope: booleanQuerySchema(true),
+    dimension: analyticsDimensionSchema.optional(),
+    performancePhase: schema.enum(['current', 'prior', 'full']).default('full'),
+    comparePrior: booleanQuerySchema(true),
+    fresh: booleanQuerySchema(false),
+});
+export const webAnalyticsDeltaSchema = defineResponseObject({
+    current: schema.number(),
+    prior: schema.number(),
+    absolute: schema.number(),
+    relative: schema.number(),
+}, {
+    current: schema.number(),
+    prior: schema.number(),
+    absolute: schema.number(),
+    relative: schema.number(),
+});
+export const webAnalyticsDailyRowSchema = defineResponseObject({
+    date: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+}, {
+    date: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+});
+export const webAnalyticsPerformanceDataSchema = defineResponseObject({
+    phase: schema.enum(['current', 'prior', 'full']),
+    sessions: webAnalyticsDeltaSchema.producer,
+    users: webAnalyticsDeltaSchema.producer,
+    pageviews: webAnalyticsDeltaSchema.producer,
+    engagementRate: webAnalyticsDeltaSchema.producer,
+    bounceRate: webAnalyticsDeltaSchema.producer,
+    keyEvents: webAnalyticsDeltaSchema.producer,
+    daily: schema.array(webAnalyticsDailyRowSchema.producer),
+    priorDaily: schema.array(webAnalyticsDailyRowSchema.producer),
+    dataFrom: schema.string().optional(),
+    provider: analyticsProviderSchema,
+}, {
+    phase: schema.enum(['current', 'prior', 'full']),
+    sessions: webAnalyticsDeltaSchema.client,
+    users: webAnalyticsDeltaSchema.client,
+    pageviews: webAnalyticsDeltaSchema.client,
+    engagementRate: webAnalyticsDeltaSchema.client,
+    bounceRate: webAnalyticsDeltaSchema.client,
+    keyEvents: webAnalyticsDeltaSchema.client,
+    daily: schema.array(webAnalyticsDailyRowSchema.client),
+    priorDaily: schema.array(webAnalyticsDailyRowSchema.client),
+    dataFrom: schema.string().optional(),
+    provider: analyticsProviderSchema,
+});
+const topPageRowSchema = defineResponseObject({
+    page: schema.string(),
+    pageviews: schema.number(),
+    sessions: schema.number(),
+    pageviewsDelta: webAnalyticsDeltaSchema.producer,
+}, {
+    page: schema.string(),
+    pageviews: schema.number(),
+    sessions: schema.number(),
+    pageviewsDelta: webAnalyticsDeltaSchema.client,
+});
+export const webAnalyticsTopPagesDataSchema = defineResponseObject({ provider: analyticsProviderSchema, rows: schema.array(topPageRowSchema.producer) }, { provider: analyticsProviderSchema, rows: schema.array(topPageRowSchema.client) });
+const sourceMediumRowSchema = defineResponseObject({
+    sessions: schema.number(),
+    sessionsDelta: webAnalyticsDeltaSchema.producer,
+    source: schema.string(),
+    users: schema.number(),
+}, {
+    sessions: schema.number(),
+    sessionsDelta: webAnalyticsDeltaSchema.client,
+    source: schema.string(),
+    users: schema.number(),
+});
+export const webAnalyticsSourceMediumDataSchema = defineResponseObject({ provider: analyticsProviderSchema, rows: schema.array(sourceMediumRowSchema.producer) }, { provider: analyticsProviderSchema, rows: schema.array(sourceMediumRowSchema.client) });
+const keyEventDailyRowSchema = defineResponseObject({ date: schema.string(), keyEvents: schema.number() }, { date: schema.string(), keyEvents: schema.number() });
+export const webAnalyticsKeyEventsDataSchema = defineResponseObject({
+    daily: schema.array(keyEventDailyRowSchema.producer).optional(),
+    provider: analyticsProviderSchema,
+    total: webAnalyticsDeltaSchema.producer,
+}, {
+    daily: schema.array(keyEventDailyRowSchema.client).optional(),
+    provider: analyticsProviderSchema,
+    total: webAnalyticsDeltaSchema.client,
+});
+const countryRowSchema = defineResponseObject({
+    country: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+    sessionsDelta: webAnalyticsDeltaSchema.producer,
+}, {
+    country: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+    sessionsDelta: webAnalyticsDeltaSchema.client,
+});
+export const webAnalyticsCountriesDataSchema = defineResponseObject({ provider: analyticsProviderSchema, rows: schema.array(countryRowSchema.producer) }, { provider: analyticsProviderSchema, rows: schema.array(countryRowSchema.client) });
+const deviceRowSchema = defineResponseObject({
+    device: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+    sessionsDelta: webAnalyticsDeltaSchema.producer,
+    share: schema.number(),
+}, {
+    device: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+    sessionsDelta: webAnalyticsDeltaSchema.client,
+    share: schema.number(),
+});
+export const webAnalyticsDevicesDataSchema = defineResponseObject({ provider: analyticsProviderSchema, rows: schema.array(deviceRowSchema.producer) }, { provider: analyticsProviderSchema, rows: schema.array(deviceRowSchema.client) });
+export const webAnalyticsByDimensionRowSchema = defineResponseObject({
+    label: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+    share: schema.number(),
+    delta: webAnalyticsDeltaSchema.producer,
+}, {
+    label: schema.string(),
+    sessions: schema.number(),
+    users: schema.number(),
+    pageviews: schema.number(),
+    share: schema.number(),
+    delta: webAnalyticsDeltaSchema.client,
+});
+export const webAnalyticsDimensionDataSchema = defineResponseObject({
+    provider: analyticsProviderSchema,
+    dimension: analyticsDimensionSchema,
+    rows: schema.array(webAnalyticsByDimensionRowSchema.producer),
+}, {
+    provider: analyticsProviderSchema,
+    dimension: analyticsDimensionSchema,
+    rows: schema.array(webAnalyticsByDimensionRowSchema.client),
+});
+export const analyticsSiteViewDataSchemas = {
+    'performance': webAnalyticsPerformanceDataSchema,
+    'top-pages': webAnalyticsTopPagesDataSchema,
+    'source-medium': webAnalyticsSourceMediumDataSchema,
+    'key-events': webAnalyticsKeyEventsDataSchema,
+    'countries': webAnalyticsCountriesDataSchema,
+    'devices': webAnalyticsDevicesDataSchema,
+    'dimension': webAnalyticsDimensionDataSchema,
+};
+export const analyticsSiteViewResponseSchemas = {
+    'performance': defineSuccessEnvelope(webAnalyticsPerformanceDataSchema),
+    'top-pages': defineSuccessEnvelope(webAnalyticsTopPagesDataSchema),
+    'source-medium': defineSuccessEnvelope(webAnalyticsSourceMediumDataSchema),
+    'key-events': defineSuccessEnvelope(webAnalyticsKeyEventsDataSchema),
+    'countries': defineSuccessEnvelope(webAnalyticsCountriesDataSchema),
+    'devices': defineSuccessEnvelope(webAnalyticsDevicesDataSchema),
+    'dimension': defineSuccessEnvelope(webAnalyticsDimensionDataSchema),
+};
+const responseSchemas = Object.values(analyticsSiteViewResponseSchemas);
+export const analyticsQueryResponseSchema = {
+    producer: schema.union(responseSchemas.map(response => response.producer)),
+    client: schema.union(responseSchemas.map(response => response.client)),
+};
+export const analyticsQueryOperation = defineOperation({
+    id: 'analytics.query',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/analytics/{view}',
+    visibility: 'public',
+    semantics: {
+        kind: 'query',
+        sideEffects: 'none',
+        retry: 'idempotent',
+        readConsistency: 'replica-ok',
+    },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['analytics:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: {
+        params: analyticsSiteParamsSchema,
+        query: analyticsReadQuerySchema,
+        headers: null,
+        body: null,
+    },
+    responses: { 200: analyticsQueryResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'entitlement_required',
+        'conflict',
+        'rate_limited',
+        'provider_unavailable',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.analytics', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: 'growth',
+        meter: null,
+    },
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Query Web Analytics',
+        description: 'Reads one provider-normalized Web Analytics Site Signal for an owned Site.',
+        tags: ['Web Analytics'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ', view: 'performance' },
+                    query: { period: '28d' },
+                },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            phase: 'full',
+                            sessions: { current: 120, prior: 100, absolute: 20, relative: 0.2 },
+                            users: { current: 90, prior: 80, absolute: 10, relative: 0.125 },
+                            pageviews: { current: 180, prior: 150, absolute: 30, relative: 0.2 },
+                            engagementRate: { current: 0.62, prior: 0.58, absolute: 0.04, relative: 0.0689655172 },
+                            bounceRate: { current: 0.38, prior: 0.42, absolute: -0.04, relative: -0.0952380952 },
+                            keyEvents: { current: 8, prior: 5, absolute: 3, relative: 0.6 },
+                            daily: [{ date: '2026-08-09', sessions: 12, users: 9, pageviews: 18 }],
+                            priorDaily: [{ date: '2026-07-12', sessions: 10, users: 8, pageviews: 15 }],
+                            dataFrom: '2026-08-09',
+                            provider: 'ga4',
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const analyticsV1Registry = defineRegistry({
+    feature: 'analytics',
+    operations: {
+        query: analyticsQueryOperation,
+    },
+});