@nuxtseo/protocol 0.1.0

package/dist/v1/gsc.js

@@ -0,0 +1,583 @@
+import { canonicalDifferenceKindSchema, gscdumpAnalysisPresetSchema, gscdumpIndexingTransitionFieldSchema, gscdumpTotalsSchema, indexingIssueSchema, } from '@gscdump/contracts';
+import { z as schema } from 'zod';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const searchConsoleSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const searchAnalyticsViewSchema = schema.enum([
+    'pages',
+    'keywords',
+    'countries',
+    'devices',
+    'timeseries',
+    'page-detail',
+    'keyword-detail',
+    'analysis',
+]);
+const periodSchema = schema.enum(['7d', '28d', '3m', '6m', '12m']);
+const pageUrlSchema = schema.string().refine(value => value.startsWith('/') || URL.canParse(value), 'Expected an absolute URL or a site-relative path starting with /.');
+export const searchAnalyticsQuerySchema = schema.strictObject({
+    view: searchAnalyticsViewSchema,
+    period: periodSchema.default('28d'),
+    limit: schema.coerce.number().int().min(1).max(100).default(25),
+    page: schema.coerce.number().int().min(1).default(1),
+    search: schema.string().optional(),
+    sort: schema.enum(['clicks', 'impressions', 'ctr', 'position']).default('clicks'),
+    sortDir: schema.enum(['asc', 'desc']).default('desc'),
+    filter: schema.enum(['top-level', 'new', 'lost', 'improving', 'declining']).optional(),
+    pageUrl: pageUrlSchema.optional(),
+    keyword: schema.string().min(1).optional(),
+    preset: gscdumpAnalysisPresetSchema.optional(),
+    brandTerms: schema.string().optional(),
+    minClicks: schema.coerce.number().optional(),
+    maxClicks: schema.coerce.number().optional(),
+    minImpressions: schema.coerce.number().optional(),
+    maxImpressions: schema.coerce.number().optional(),
+    minPosition: schema.coerce.number().optional(),
+    maxPosition: schema.coerce.number().optional(),
+    maxCtr: schema.coerce.number().min(0).max(1).optional(),
+}).superRefine((value, context) => {
+    if (value.view === 'page-detail' && !value.pageUrl)
+        context.addIssue({ code: 'custom', path: ['pageUrl'], message: 'pageUrl is required for page-detail.' });
+    if (value.view === 'keyword-detail' && !value.keyword)
+        context.addIssue({ code: 'custom', path: ['keyword'], message: 'keyword is required for keyword-detail.' });
+    if (value.view === 'analysis' && !value.preset)
+        context.addIssue({ code: 'custom', path: ['preset'], message: 'preset is required for analysis.' });
+    if (value.view === 'analysis'
+        && (value.preset === 'brand-only' || value.preset === 'non-brand')
+        && !value.brandTerms?.trim()) {
+        context.addIssue({ code: 'custom', path: ['brandTerms'], message: 'brandTerms is required for brand analysis.' });
+    }
+});
+const totalsSchema = defineResponseObject(gscdumpTotalsSchema.shape, gscdumpTotalsSchema.shape);
+const representedTotalsSchema = defineResponseObject({ clicks: schema.number(), impressions: schema.number() }, { clicks: schema.number(), impressions: schema.number() });
+const pageRowSchema = defineResponseObject({
+    url: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+    keyword: schema.string().nullable(),
+    prevClicks: schema.number().optional(),
+    prevPos: schema.number().optional(),
+    change: schema.number().nullable(),
+});
+const keywordRowSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+    topPage: schema.string().nullable(),
+    prevClicks: schema.number().optional(),
+    prevPos: schema.number().optional(),
+    change: schema.number().nullable(),
+});
+const countryRowSchema = defineResponseObject({
+    country: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+    prevClicks: schema.number().optional(),
+    change: schema.number().nullable(),
+});
+const deviceRowSchema = defineResponseObject({
+    device: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+});
+function breakdownSchema(view, row) {
+    return defineResponseObject({
+        site: schema.string().min(1),
+        type: schema.literal(view),
+        period: periodSchema,
+        total: schema.number().int().nonnegative(),
+        totals: totalsSchema.producer.nullable(),
+        totalsScope: schema.string().min(1),
+        representedTotals: representedTotalsSchema.producer,
+        representedTotalsScope: schema.string().min(1),
+        rows: schema.array(row.producer),
+    }, {
+        site: schema.string().min(1),
+        type: schema.literal(view),
+        period: periodSchema,
+        total: schema.number().int().nonnegative(),
+        totals: totalsSchema.client.nullable(),
+        totalsScope: schema.string().min(1),
+        representedTotals: representedTotalsSchema.client,
+        representedTotalsScope: schema.string().min(1),
+        rows: schema.array(row.client),
+    });
+}
+const pagesDataSchema = breakdownSchema('pages', pageRowSchema);
+const keywordsDataSchema = breakdownSchema('keywords', keywordRowSchema);
+const countriesDataSchema = breakdownSchema('countries', countryRowSchema);
+const devicesDataSchema = breakdownSchema('devices', deviceRowSchema);
+const dailyRowSchema = defineResponseObject({
+    date: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+});
+const timeseriesDataSchema = defineResponseObject({
+    site: schema.string().min(1),
+    type: schema.literal('timeseries'),
+    period: periodSchema,
+    totals: totalsSchema.producer.nullable(),
+    prevTotals: totalsSchema.producer.nullable(),
+    daily: schema.array(dailyRowSchema.producer),
+}, {
+    site: schema.string().min(1),
+    type: schema.literal('timeseries'),
+    period: periodSchema,
+    totals: totalsSchema.client.nullable(),
+    prevTotals: totalsSchema.client.nullable(),
+    daily: schema.array(dailyRowSchema.client),
+});
+const pageDetailRowSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+    prevClicks: schema.number().optional(),
+    prevPos: schema.number().optional(),
+});
+const pageDetailDataSchema = defineResponseObject({
+    site: schema.string().min(1),
+    type: schema.literal('page-detail'),
+    pageUrl: pageUrlSchema,
+    period: periodSchema,
+    totals: totalsSchema.producer.nullable(),
+    rows: schema.array(pageDetailRowSchema.producer),
+}, {
+    site: schema.string().min(1),
+    type: schema.literal('page-detail'),
+    pageUrl: pageUrlSchema,
+    period: periodSchema,
+    totals: totalsSchema.client.nullable(),
+    rows: schema.array(pageDetailRowSchema.client),
+});
+const keywordDetailRowSchema = defineResponseObject({
+    page: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+    prevClicks: schema.number().optional(),
+    prevPos: schema.number().optional(),
+});
+const keywordDetailDataSchema = defineResponseObject({
+    site: schema.string().min(1),
+    type: schema.literal('keyword-detail'),
+    keyword: schema.string().min(1),
+    period: periodSchema,
+    totals: totalsSchema.producer.nullable(),
+    rows: schema.array(keywordDetailRowSchema.producer),
+}, {
+    site: schema.string().min(1),
+    type: schema.literal('keyword-detail'),
+    keyword: schema.string().min(1),
+    period: periodSchema,
+    totals: totalsSchema.client.nullable(),
+    rows: schema.array(keywordDetailRowSchema.client),
+});
+const analysisPrimitiveSchema = schema.union([schema.string(), schema.number(), schema.boolean(), schema.null()]);
+const analysisRowSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    clicks: schema.number(),
+    impressions: schema.number(),
+    ctr: schema.number(),
+    pos: schema.number(),
+    page: schema.string().optional(),
+    prevClicks: schema.number().optional(),
+    prevPos: schema.number().optional(),
+    potentialClicks: schema.number().optional(),
+    opportunityScore: schema.number().optional(),
+    clicksChange: schema.number().optional(),
+    posChange: schema.number().optional(),
+    decayPct: schema.number().optional(),
+    missedClicks: schema.number().optional(),
+});
+const analysisDataSchema = defineResponseObject({
+    site: schema.string().min(1),
+    type: schema.literal('analysis'),
+    preset: gscdumpAnalysisPresetSchema,
+    description: schema.string().min(1),
+    criteria: schema.record(schema.string(), schema.union([schema.string(), schema.number(), schema.null()])),
+    period: periodSchema,
+    total: schema.number().int().nonnegative(),
+    summary: schema.record(schema.string(), analysisPrimitiveSchema).nullable(),
+    rows: schema.array(analysisRowSchema.producer),
+}, {
+    site: schema.string().min(1),
+    type: schema.literal('analysis'),
+    preset: gscdumpAnalysisPresetSchema,
+    description: schema.string().min(1),
+    criteria: schema.record(schema.string(), schema.union([schema.string(), schema.number(), schema.null()])),
+    period: periodSchema,
+    total: schema.number().int().nonnegative(),
+    summary: schema.record(schema.string(), analysisPrimitiveSchema).nullable(),
+    rows: schema.array(analysisRowSchema.client),
+});
+export const searchAnalyticsDataSchema = {
+    producer: schema.discriminatedUnion('type', [
+        pagesDataSchema.producer,
+        keywordsDataSchema.producer,
+        countriesDataSchema.producer,
+        devicesDataSchema.producer,
+        timeseriesDataSchema.producer,
+        pageDetailDataSchema.producer,
+        keywordDetailDataSchema.producer,
+        analysisDataSchema.producer,
+    ]),
+    client: schema.discriminatedUnion('type', [
+        pagesDataSchema.client,
+        keywordsDataSchema.client,
+        countriesDataSchema.client,
+        devicesDataSchema.client,
+        timeseriesDataSchema.client,
+        pageDetailDataSchema.client,
+        keywordDetailDataSchema.client,
+        analysisDataSchema.client,
+    ]),
+};
+export const searchAnalyticsResponseSchema = defineSuccessEnvelope(searchAnalyticsDataSchema);
+const searchStatusDataSchema = defineResponseObject({
+    site: schema.string().min(1),
+    connected: schema.literal(true),
+    syncStatus: schema.string().min(1),
+    progress: schema.strictObject({
+        percent: schema.number().min(0).max(100),
+        succeeded: schema.number().int().nonnegative(),
+        failed: schema.number().int().nonnegative(),
+        terminal: schema.number().int().nonnegative(),
+        pending: schema.number().int().nonnegative(),
+        total: schema.number().int().nonnegative(),
+    }),
+    dateRange: schema.strictObject({ oldest: schema.string().nullable(), newest: schema.string().nullable() }),
+    lastSyncAt: schema.string().datetime().nullable(),
+    isSyncing: schema.boolean(),
+    hasData: schema.boolean(),
+    completion: schema.strictObject({
+        jobsTerminal: schema.boolean(),
+        dateCoverageComplete: schema.boolean(),
+        missingDays: schema.number().int().nonnegative(),
+    }),
+    daysSynced: schema.number().int().nonnegative(),
+    daysAvailable: schema.number().int().nonnegative(),
+}, {
+    site: schema.string().min(1),
+    connected: schema.literal(true),
+    syncStatus: schema.string().min(1),
+    progress: schema.looseObject({
+        percent: schema.number().min(0).max(100),
+        succeeded: schema.number().int().nonnegative(),
+        failed: schema.number().int().nonnegative(),
+        terminal: schema.number().int().nonnegative(),
+        pending: schema.number().int().nonnegative(),
+        total: schema.number().int().nonnegative(),
+    }),
+    dateRange: schema.looseObject({ oldest: schema.string().nullable(), newest: schema.string().nullable() }),
+    lastSyncAt: schema.string().datetime().nullable(),
+    isSyncing: schema.boolean(),
+    hasData: schema.boolean(),
+    completion: schema.looseObject({
+        jobsTerminal: schema.boolean(),
+        dateCoverageComplete: schema.boolean(),
+        missingDays: schema.number().int().nonnegative(),
+    }),
+    daysSynced: schema.number().int().nonnegative(),
+    daysAvailable: schema.number().int().nonnegative(),
+});
+export const searchStatusResponseSchema = defineSuccessEnvelope(searchStatusDataSchema);
+export const indexingDiagnosticsQuerySchema = schema.strictObject({
+    view: schema.enum(['summary', 'urls']).default('summary'),
+    issue: schema.string().min(1).optional(),
+    status: schema.enum(['indexed', 'not_indexed', 'pending']).optional(),
+    limit: schema.coerce.number().int().min(1).max(500).default(50),
+    offset: schema.coerce.number().int().min(0).default(0),
+});
+const issueSchema = defineResponseObject(indexingIssueSchema.shape, indexingIssueSchema.shape);
+const diagnosticsSummaryDataSchema = defineResponseObject({
+    view: schema.literal('summary'),
+    totalUrls: schema.number().int().nonnegative(),
+    indexed: schema.number().int().nonnegative(),
+    asOf: schema.string().datetime().nullable(),
+    issues: schema.array(issueSchema.producer),
+}, {
+    view: schema.literal('summary'),
+    totalUrls: schema.number().int().nonnegative(),
+    indexed: schema.number().int().nonnegative(),
+    asOf: schema.string().datetime().nullable(),
+    issues: schema.array(issueSchema.client),
+});
+const diagnosticsUrlSchema = defineResponseObject({
+    url: schema.string().min(1),
+    verdict: schema.string().nullable(),
+    coverageState: schema.string().nullable(),
+    indexingState: schema.string().nullable(),
+    userCanonical: schema.string().nullable(),
+    googleCanonical: schema.string().nullable(),
+    lastCrawlTime: schema.string().nullable(),
+    lastCheckedAt: schema.string().datetime(),
+});
+const diagnosticsUrlsDataSchema = defineResponseObject({
+    view: schema.literal('urls'),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+    hasMore: schema.boolean(),
+    urls: schema.array(diagnosticsUrlSchema.producer),
+}, {
+    view: schema.literal('urls'),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+    hasMore: schema.boolean(),
+    urls: schema.array(diagnosticsUrlSchema.client),
+});
+export const indexingDiagnosticsDataSchema = {
+    producer: schema.discriminatedUnion('view', [diagnosticsSummaryDataSchema.producer, diagnosticsUrlsDataSchema.producer]),
+    client: schema.discriminatedUnion('view', [diagnosticsSummaryDataSchema.client, diagnosticsUrlsDataSchema.client]),
+};
+export const indexingDiagnosticsResponseSchema = defineSuccessEnvelope(indexingDiagnosticsDataSchema);
+export const indexingHistoryQuerySchema = schema.strictObject({
+    url: pageUrlSchema.optional(),
+    field: gscdumpIndexingTransitionFieldSchema.optional(),
+    days: schema.coerce.number().int().min(1).max(730).default(180),
+});
+const markerSchema = defineResponseObject({
+    day: schema.string().date(),
+    label: schema.string().min(1),
+    source: schema.enum(['release', 'annotation']),
+});
+const causeSchema = {
+    producer: schema.discriminatedUnion('_tag', [
+        schema.strictObject({ _tag: schema.literal('sole-candidate'), marker: markerSchema.producer }),
+        schema.strictObject({ _tag: schema.literal('ambiguous'), markers: schema.array(markerSchema.producer) }),
+        schema.strictObject({ _tag: schema.literal('no-known-change') }),
+    ]),
+    client: schema.discriminatedUnion('_tag', [
+        schema.looseObject({ _tag: schema.literal('sole-candidate'), marker: markerSchema.client }),
+        schema.looseObject({ _tag: schema.literal('ambiguous'), markers: schema.array(markerSchema.client) }),
+        schema.looseObject({ _tag: schema.literal('no-known-change') }),
+    ]),
+};
+const historyChangeSchema = defineResponseObject({
+    url: schema.string().min(1),
+    field: gscdumpIndexingTransitionFieldSchema,
+    fromValue: schema.string().nullable(),
+    toValue: schema.string().nullable(),
+    afterDay: schema.string().date(),
+    beforeDay: schema.string().date(),
+    observedOverDays: schema.number().int().nonnegative(),
+    cause: causeSchema.producer,
+}, {
+    url: schema.string().min(1),
+    field: gscdumpIndexingTransitionFieldSchema,
+    fromValue: schema.string().nullable(),
+    toValue: schema.string().nullable(),
+    afterDay: schema.string().date(),
+    beforeDay: schema.string().date(),
+    observedOverDays: schema.number().int().nonnegative(),
+    cause: causeSchema.client,
+});
+const historyScopeSchema = {
+    producer: schema.discriminatedUnion('_tag', [
+        schema.strictObject({ _tag: schema.literal('url'), url: schema.string().min(1) }),
+        schema.strictObject({ _tag: schema.literal('site'), field: gscdumpIndexingTransitionFieldSchema }),
+    ]),
+    client: schema.discriminatedUnion('_tag', [
+        schema.looseObject({ _tag: schema.literal('url'), url: schema.string().min(1) }),
+        schema.looseObject({ _tag: schema.literal('site'), field: gscdumpIndexingTransitionFieldSchema }),
+    ]),
+};
+const unchangedSchema = defineResponseObject({
+    observations: schema.number().int().nonnegative().nullable(),
+    firstObservedDay: schema.string().date().nullable(),
+    lastObservedDay: schema.string().date().nullable(),
+});
+export const indexingHistoryDataSchema = defineResponseObject({
+    scope: historyScopeSchema.producer,
+    startDate: schema.string().date(),
+    endDate: schema.string().date(),
+    complete: schema.boolean(),
+    resolvedUrl: schema.string().nullable(),
+    unchanged: unchangedSchema.producer.nullable(),
+    changes: schema.array(historyChangeSchema.producer),
+}, {
+    scope: historyScopeSchema.client,
+    startDate: schema.string().date(),
+    endDate: schema.string().date(),
+    complete: schema.boolean(),
+    resolvedUrl: schema.string().nullable(),
+    unchanged: unchangedSchema.client.nullable(),
+    changes: schema.array(historyChangeSchema.client),
+});
+export const indexingHistoryResponseSchema = defineSuccessEnvelope(indexingHistoryDataSchema);
+export const urlInspectionQuerySchema = schema.strictObject({ url: pageUrlSchema });
+const inspectedSchema = defineResponseObject({
+    _tag: schema.literal('inspected'),
+    requestedUrl: schema.string().min(1),
+    inspectedUrl: schema.string().min(1),
+    verdict: schema.string().nullable(),
+    coverageState: schema.string().nullable(),
+    indexingState: schema.string().nullable(),
+    robotsTxtState: schema.string().nullable(),
+    pageFetchState: schema.string().nullable(),
+    lastCrawlTime: schema.string().nullable(),
+    crawledAs: schema.string().nullable(),
+    userCanonical: schema.string().nullable(),
+    googleCanonical: schema.string().nullable(),
+    canonicalisedAway: schema.boolean(),
+    canonicalMismatchKind: canonicalDifferenceKindSchema,
+    sitemaps: schema.array(schema.string()),
+    referringUrls: schema.array(schema.string()),
+    inspectionResultLink: schema.string().nullable(),
+    lastCheckedAt: schema.string().datetime(),
+    firstCheckedAt: schema.string().datetime().nullable(),
+    checkCount: schema.number().int().nonnegative().nullable(),
+});
+const retainedEvidenceSchema = defineResponseObject({
+    _tag: schema.literal('retained-evidence'),
+    requestedUrl: schema.string().min(1),
+    evidenceUrl: schema.string().min(1),
+    issueType: schema.string().min(1),
+    label: schema.string().nullable(),
+    coverageState: schema.string().nullable(),
+    userCanonical: schema.string().nullable(),
+    googleCanonical: schema.string().nullable(),
+    canonicalisedAway: schema.boolean(),
+    observedAt: schema.string().datetime(),
+    lastSeenAt: schema.string().datetime().nullable(),
+});
+const noInspectionDataSchema = defineResponseObject({
+    _tag: schema.literal('no-inspection-data'),
+    requestedUrl: schema.string().min(1),
+});
+export const urlInspectionDataSchema = {
+    producer: schema.discriminatedUnion('_tag', [inspectedSchema.producer, retainedEvidenceSchema.producer, noInspectionDataSchema.producer]),
+    client: schema.discriminatedUnion('_tag', [inspectedSchema.client, retainedEvidenceSchema.client, noInspectionDataSchema.client]),
+};
+export const urlInspectionResponseSchema = defineSuccessEnvelope(urlInspectionDataSchema);
+const readErrors = [
+    'invalid_request',
+    'unauthorized',
+    'auth_expired',
+    'forbidden',
+    'not_found',
+    'entitlement_required',
+    'stale_evidence',
+    'rate_limited',
+    'provider_unavailable',
+    'conflict',
+    'contract_violation',
+    'internal_error',
+];
+const common = {
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'replica-ok' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['sites:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    errors: readErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    policy: { rate: publicV1StandardRatePolicy, idempotency: { _tag: 'none' }, entitlement: null, meter: null },
+    lifecycle: { introduced: '1.0.0' },
+};
+export const searchAnalyticsQueryOperation = defineOperation({
+    ...common,
+    id: 'sites.search.analytics.query',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/search/analytics',
+    request: { params: searchConsoleSiteParamsSchema, query: searchAnalyticsQuerySchema, headers: null, body: null },
+    responses: { 200: searchAnalyticsResponseSchema },
+    resources: { reads: [{ type: 'site.analytics', idFrom: 'params.siteId' }], changes: [] },
+    docs: {
+        summary: 'Query Site search analytics',
+        description: 'Returns a bounded Search Console breakdown, trend, detail, or opportunity analysis for one NuxtSEO Site.',
+        tags: ['Sites', 'Search'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { view: 'keywords' } },
+                response: { status: 200, body: { data: { site: 'https://example.com', type: 'keywords', period: '28d', total: 1, totals: { clicks: 12, impressions: 100, ctr: 0.12, position: 4 }, totalsScope: 'full upstream query population', representedTotals: { clicks: 12, impressions: 100 }, representedTotalsScope: 'returned rows', rows: [{ keyword: 'nuxt seo', clicks: 12, impressions: 100, ctr: 0.12, pos: 4, topPage: 'https://example.com/docs', change: 2 }] }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } },
+            }],
+    },
+});
+export const searchStatusReadOperation = defineOperation({
+    ...common,
+    id: 'sites.search.status.read',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/search/status',
+    request: { params: searchConsoleSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: searchStatusResponseSchema },
+    resources: { reads: [{ type: 'site.identity', idFrom: 'params.siteId' }], changes: [] },
+    docs: {
+        summary: 'Read Site search status',
+        description: 'Returns aggregate Search Console synchronization reach for the credential authoritatively bound to the Site Team.',
+        tags: ['Sites', 'Search'],
+        examples: [{ request: { params: { siteId: 'site_01JXYZ' } }, response: { status: 200, body: { data: { site: 'https://example.com', connected: true, syncStatus: 'synced', progress: { percent: 100, succeeded: 4, failed: 0, terminal: 4, pending: 0, total: 4 }, dateRange: { oldest: '2026-01-01', newest: '2026-08-09' }, lastSyncAt: '2026-08-10T00:00:00.000Z', isSyncing: false, hasData: true, completion: { jobsTerminal: true, dateCoverageComplete: true, missingDays: 0 }, daysSynced: 221, daysAvailable: 221 }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } } }],
+    },
+});
+export const indexingDiagnosticsReadOperation = defineOperation({
+    ...common,
+    id: 'sites.search.indexing.diagnostics.read',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/search/indexing/diagnostics',
+    request: { params: searchConsoleSiteParamsSchema, query: indexingDiagnosticsQuerySchema, headers: null, body: null },
+    responses: { 200: indexingDiagnosticsResponseSchema },
+    resources: { reads: [{ type: 'site.page', idFrom: 'params.siteId' }], changes: [] },
+    docs: {
+        summary: 'Diagnose Site indexing',
+        description: 'Returns indexed coverage and issue counts, or one filtered page of affected URLs, from retained Search Console evidence.',
+        tags: ['Sites', 'Search', 'Indexing'],
+        examples: [{ request: { params: { siteId: 'site_01JXYZ' }, query: { view: 'summary' } }, response: { status: 200, body: { data: { view: 'summary', totalUrls: 100, indexed: 92, asOf: '2026-08-10T00:00:00.000Z', issues: [] }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } } }],
+    },
+});
+export const indexingHistoryReadOperation = defineOperation({
+    ...common,
+    id: 'sites.search.indexing.history.read',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/search/indexing/history',
+    request: { params: searchConsoleSiteParamsSchema, query: indexingHistoryQuerySchema, headers: null, body: null },
+    responses: { 200: indexingHistoryResponseSchema },
+    resources: { reads: [{ type: 'site.page', idFrom: 'params.siteId' }], changes: [] },
+    docs: {
+        summary: 'Read Site indexing history',
+        description: 'Returns retained indexing changes as observation windows, preserving uncertainty and candidate deploy correlation.',
+        tags: ['Sites', 'Search', 'Indexing'],
+        examples: [{ request: { params: { siteId: 'site_01JXYZ' }, query: { field: 'coverageState', days: 90 } }, response: { status: 200, body: { data: { scope: { _tag: 'site', field: 'coverageState' }, startDate: '2026-05-12', endDate: '2026-08-10', complete: true, resolvedUrl: null, unchanged: null, changes: [] }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } } }],
+    },
+});
+export const urlInspectionReadOperation = defineOperation({
+    ...common,
+    id: 'sites.search.indexing.inspection.read',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/search/indexing/inspection',
+    request: { params: searchConsoleSiteParamsSchema, query: urlInspectionQuerySchema, headers: null, body: null },
+    responses: { 200: urlInspectionResponseSchema },
+    resources: { reads: [{ type: 'site.page', idFrom: 'params.siteId' }], changes: [] },
+    docs: {
+        summary: 'Inspect one indexed URL',
+        description: 'Returns the latest retained URL Inspection result, dated local evidence, or an explicit no-data state for one Site URL.',
+        tags: ['Sites', 'Search', 'Indexing'],
+        examples: [{ request: { params: { siteId: 'site_01JXYZ' }, query: { url: '/docs' } }, response: { status: 200, body: { data: { _tag: 'no-inspection-data', requestedUrl: 'https://example.com/docs' }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } } }],
+    },
+});
+export const searchV1Registry = defineRegistry({
+    feature: 'sites',
+    operations: {
+        queryAnalytics: searchAnalyticsQueryOperation,
+        readStatus: searchStatusReadOperation,
+        readIndexingDiagnostics: indexingDiagnosticsReadOperation,
+        readIndexingHistory: indexingHistoryReadOperation,
+        readUrlInspection: urlInspectionReadOperation,
+    },
+});

package/dist/v1/index.d.ts

@@ -0,0 +1,49 @@
+import type { PublicV1ProtocolLike } from './core.js';
+import { accountV1Registry } from './account.js';
+import { actionsV1Registry } from './actions.js';
+import { analyticsV1Registry } from './analytics.js';
+import { auditV1Registry } from './audit.js';
+import { backlinksV1Registry, mentionsV1Registry } from './backlinks.js';
+import { contentV1Registry } from './content.js';
+import { publicV1ErrorEnvelope } from './core.js';
+import { searchV1Registry } from './gsc.js';
+import { pagesV1Registry } from './pages.js';
+import { performanceV1Registry } from './performance.js';
+import { researchV1Registry } from './research.js';
+import { sitemapsV1Registry } from './sitemaps.js';
+import { sitesV1Registry } from './sites.js';
+export * from './account.js';
+export * from './actions.js';
+export * from './analytics.js';
+export * from './audit.js';
+export * from './backlinks.js';
+export * from './content.js';
+export * from './core.js';
+export * from './documents.js';
+export * from './gsc.js';
+export * from './pages.js';
+export * from './performance.js';
+export * from './research.js';
+export * from './sitemaps.js';
+export * from './sites.js';
+export interface PublicV1Protocol extends Omit<PublicV1ProtocolLike, 'registries' | 'schemas'> {
+    registries: {
+        readonly account: typeof accountV1Registry;
+        readonly actions: typeof actionsV1Registry;
+        readonly analytics: typeof analyticsV1Registry;
+        readonly audit: typeof auditV1Registry;
+        readonly backlinks: typeof backlinksV1Registry;
+        readonly mentions: typeof mentionsV1Registry;
+        readonly content: typeof contentV1Registry;
+        readonly page: typeof pagesV1Registry;
+        readonly performance: typeof performanceV1Registry;
+        readonly research: typeof researchV1Registry;
+        readonly search: typeof searchV1Registry;
+        readonly sites: typeof sitesV1Registry;
+        readonly sitemaps: typeof sitemapsV1Registry;
+    };
+    schemas: {
+        readonly errorEnvelope: typeof publicV1ErrorEnvelope;
+    };
+}
+export declare function createPublicV1Protocol(): PublicV1Protocol;

package/dist/v1/index.js

@@ -0,0 +1,52 @@
+import { accountV1Registry } from './account.js';
+import { actionsV1Registry } from './actions.js';
+import { analyticsV1Registry } from './analytics.js';
+import { auditV1Registry } from './audit.js';
+import { backlinksV1Registry, mentionsV1Registry } from './backlinks.js';
+import { contentV1Registry } from './content.js';
+import { defineProtocol, PUBLIC_V1_VERSION, publicV1ErrorEnvelope } from './core.js';
+import { searchV1Registry } from './gsc.js';
+import { pagesV1Registry } from './pages.js';
+import { performanceV1Registry } from './performance.js';
+import { researchV1Registry } from './research.js';
+import { sitemapsV1Registry } from './sitemaps.js';
+import { sitesV1Registry } from './sites.js';
+export * from './account.js';
+export * from './actions.js';
+export * from './analytics.js';
+export * from './audit.js';
+export * from './backlinks.js';
+export * from './content.js';
+export * from './core.js';
+export * from './documents.js';
+export * from './gsc.js';
+export * from './pages.js';
+export * from './performance.js';
+export * from './research.js';
+export * from './sitemaps.js';
+export * from './sites.js';
+export function createPublicV1Protocol() {
+    const protocol = {
+        version: PUBLIC_V1_VERSION,
+        registries: {
+            account: accountV1Registry,
+            actions: actionsV1Registry,
+            analytics: analyticsV1Registry,
+            audit: auditV1Registry,
+            backlinks: backlinksV1Registry,
+            mentions: mentionsV1Registry,
+            content: contentV1Registry,
+            page: pagesV1Registry,
+            performance: performanceV1Registry,
+            research: researchV1Registry,
+            search: searchV1Registry,
+            sites: sitesV1Registry,
+            sitemaps: sitemapsV1Registry,
+        },
+        schemas: {
+            errorEnvelope: publicV1ErrorEnvelope,
+        },
+    };
+    defineProtocol(protocol);
+    return protocol;
+}