@nuxtseo/protocol 0.1.0

package/dist/v1/research.js

@@ -0,0 +1,174 @@
+import { z as schema } from 'zod';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const researchSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const researchMetricsSchema = defineResponseObject({
+    organicTraffic: schema.number().nullable(),
+    totalKeywords: schema.number().nullable(),
+    keywordFootprint: schema.number().nullable(),
+    trafficValue: schema.number().nullable(),
+}, {
+    organicTraffic: schema.number().nullable(),
+    totalKeywords: schema.number().nullable(),
+    keywordFootprint: schema.number().nullable(),
+    trafficValue: schema.number().nullable(),
+});
+export const researchRankingKeywordSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    position: schema.number().nullable(),
+    volume: schema.number().nullable(),
+    traffic: schema.number().nullable(),
+    url: schema.string().nullable(),
+    intent: schema.string().nullable(),
+}, {
+    keyword: schema.string().min(1),
+    position: schema.number().nullable(),
+    volume: schema.number().nullable(),
+    traffic: schema.number().nullable(),
+    url: schema.string().nullable(),
+    intent: schema.string().nullable(),
+});
+export const researchSharedKeywordSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    yourPosition: schema.number(),
+    theirPosition: schema.number(),
+    volume: schema.number(),
+}, {
+    keyword: schema.string().min(1),
+    yourPosition: schema.number(),
+    theirPosition: schema.number(),
+    volume: schema.number(),
+});
+export const researchHistoryPointSchema = defineResponseObject({
+    observedAt: schema.string().datetime().nullable(),
+    metrics: researchMetricsSchema.producer,
+}, {
+    observedAt: schema.string().datetime().nullable(),
+    metrics: researchMetricsSchema.client,
+});
+export const researchCompetitorSchema = defineResponseObject({
+    domain: schema.string().min(1),
+    discovery: schema.enum(['manual', 'automatic', 'unknown']),
+    metrics: researchMetricsSchema.producer,
+    topKeywords: schema.array(researchRankingKeywordSchema.producer),
+    sharedKeywords: schema.array(researchSharedKeywordSchema.producer),
+    keywordGaps: schema.array(researchRankingKeywordSchema.producer),
+    quickWins: schema.array(researchSharedKeywordSchema.producer),
+    history: schema.array(researchHistoryPointSchema.producer),
+    collectedAt: schema.string().datetime().nullable(),
+}, {
+    domain: schema.string().min(1),
+    discovery: schema.enum(['manual', 'automatic', 'unknown']),
+    metrics: researchMetricsSchema.client,
+    topKeywords: schema.array(researchRankingKeywordSchema.client),
+    sharedKeywords: schema.array(researchSharedKeywordSchema.client),
+    keywordGaps: schema.array(researchRankingKeywordSchema.client),
+    quickWins: schema.array(researchSharedKeywordSchema.client),
+    history: schema.array(researchHistoryPointSchema.client),
+    collectedAt: schema.string().datetime().nullable(),
+});
+export const researchSubjectSchema = defineResponseObject({
+    domain: schema.string().min(1),
+    metrics: researchMetricsSchema.producer,
+    history: schema.array(researchHistoryPointSchema.producer),
+    collectedAt: schema.string().datetime().nullable(),
+}, {
+    domain: schema.string().min(1),
+    metrics: researchMetricsSchema.client,
+    history: schema.array(researchHistoryPointSchema.client),
+    collectedAt: schema.string().datetime().nullable(),
+});
+export const storedResearchOverviewDataSchema = defineResponseObject({
+    evidence: schema.strictObject({
+        _tag: schema.literal('stored'),
+        provider: schema.literal('dataforseo'),
+        collectedAt: schema.string().datetime().nullable(),
+    }),
+    summary: schema.strictObject({
+        competitorCount: schema.number().int().nonnegative(),
+        quickWins: schema.number().int().nonnegative(),
+        totalSharedKeywords: schema.number().int().nonnegative(),
+        totalTrafficValue: schema.number().nonnegative(),
+    }),
+    subject: researchSubjectSchema.producer.nullable(),
+    competitors: schema.array(researchCompetitorSchema.producer),
+}, {
+    evidence: schema.looseObject({
+        _tag: schema.literal('stored'),
+        provider: schema.literal('dataforseo'),
+        collectedAt: schema.string().datetime().nullable(),
+    }),
+    summary: schema.looseObject({
+        competitorCount: schema.number().int().nonnegative(),
+        quickWins: schema.number().int().nonnegative(),
+        totalSharedKeywords: schema.number().int().nonnegative(),
+        totalTrafficValue: schema.number().nonnegative(),
+    }),
+    subject: researchSubjectSchema.client.nullable(),
+    competitors: schema.array(researchCompetitorSchema.client),
+});
+export const storedResearchOverviewResponseSchema = defineSuccessEnvelope(storedResearchOverviewDataSchema);
+export const storedResearchOverviewOperation = defineOperation({
+    id: 'research.overview',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/research',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['research:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: researchSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: storedResearchOverviewResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.research', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Get stored Site Research',
+        description: 'Returns retained competitor and keyword-gap evidence already collected for the Site. It never starts provider work and does not consume metered units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            evidence: { _tag: 'stored', provider: 'dataforseo', collectedAt: null },
+                            summary: { competitorCount: 0, quickWins: 0, totalSharedKeywords: 0, totalTrafficValue: 0 },
+                            subject: null,
+                            competitors: [],
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const researchV1Registry = defineRegistry({
+    feature: 'research',
+    operations: {
+        overview: storedResearchOverviewOperation,
+    },
+});