@nuxtseo/protocol 0.1.0 → 0.1.1

package/dist/v1/research.js

@@ -3,6 +3,10 @@ import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnv
 export const researchSiteParamsSchema = schema.strictObject({
     siteId: schema.string().min(1),
 });
+const queryBooleanSchema = schema.union([
+    schema.boolean(),
+    schema.enum(['true', 'false', '1', '0']),
+]).transform(value => value === true || value === 'true' || value === '1');
 export const researchMetricsSchema = defineResponseObject({
     organicTraffic: schema.number().nullable(),
     totalKeywords: schema.number().nullable(),
@@ -109,6 +113,223 @@ export const storedResearchOverviewDataSchema = defineResponseObject({
     competitors: schema.array(researchCompetitorSchema.client),
 });
 export const storedResearchOverviewResponseSchema = defineSuccessEnvelope(storedResearchOverviewDataSchema);
+export const keywordResearchQuerySchema = schema.strictObject({
+    topic: schema.string().trim().min(2).max(200),
+    minVolume: schema.coerce.number().int().nonnegative().default(10),
+    maxVolume: schema.coerce.number().int().nonnegative().default(10_000),
+    minDifficulty: schema.coerce.number().min(0).max(100).default(0),
+    maxDifficulty: schema.coerce.number().min(0).max(100).default(60),
+    intent: schema.string().trim().min(1).optional(),
+    includeRelated: queryBooleanSchema.default(true),
+    verbose: queryBooleanSchema.default(false),
+    limit: schema.coerce.number().int().min(1).max(100).default(20),
+    locationCode: schema.coerce.number().int().positive().default(2840),
+}).superRefine((value, context) => {
+    if (value.maxVolume < value.minVolume)
+        context.addIssue({ code: 'custom', path: ['maxVolume'], message: 'maxVolume must be at least minVolume.' });
+    if (value.maxDifficulty < value.minDifficulty)
+        context.addIssue({ code: 'custom', path: ['maxDifficulty'], message: 'maxDifficulty must be at least minDifficulty.' });
+});
+const keywordTrendPointSchema = defineResponseObject({
+    year: schema.number().int(),
+    month: schema.number().int().min(1).max(12),
+    volume: schema.number().int().nonnegative(),
+});
+const liveKeywordSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    volume: schema.number().nullable(),
+    difficulty: schema.number().nullable(),
+    intent: schema.string().nullable(),
+    secondaryIntents: schema.array(schema.string()).nullable(),
+    cpc: schema.number().nullable(),
+    competition: schema.number().nullable(),
+    competitionLevel: schema.enum(['LOW', 'MEDIUM', 'HIGH']).nullable(),
+    lowBid: schema.number().nullable(),
+    highBid: schema.number().nullable(),
+    trend: schema.array(keywordTrendPointSchema.producer).nullable(),
+    serpFeatures: schema.array(schema.string()).nullable(),
+    backlinks: schema.number().nullable(),
+    referringDomains: schema.number().nullable(),
+});
+const serpFallbackResultSchema = defineResponseObject({
+    position: schema.number(),
+    title: schema.string(),
+    domain: schema.string(),
+    url: schema.string(),
+});
+const keywordResearchEvidenceProducerSchema = schema.discriminatedUnion('_tag', [
+    schema.strictObject({
+        _tag: schema.literal('no-provider'),
+        provider: schema.null(),
+        spend: schema.strictObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('cache'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.strictObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('live'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.strictObject({ key: schema.literal('dataforseo'), units: schema.literal(1) }),
+    }),
+]);
+const keywordResearchEvidenceClientSchema = schema.discriminatedUnion('_tag', [
+    schema.looseObject({
+        _tag: schema.literal('no-provider'),
+        provider: schema.null(),
+        spend: schema.looseObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('cache'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.looseObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('live'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.looseObject({ key: schema.literal('dataforseo'), units: schema.literal(1) }),
+    }),
+]);
+const keywordResearchDataSchema = defineResponseObject({
+    topic: schema.string().min(1),
+    keywords: schema.array(liveKeywordSchema.producer),
+    totalFound: schema.number().int().nonnegative(),
+    filters: schema.strictObject({
+        minVolume: schema.number(),
+        maxVolume: schema.number(),
+        minDifficulty: schema.number(),
+        maxDifficulty: schema.number(),
+        intent: schema.string().optional(),
+    }),
+    message: schema.string().optional(),
+    tip: schema.string().optional(),
+    serpFallback: schema.strictObject({
+        message: schema.string(),
+        topResults: schema.array(serpFallbackResultSchema.producer),
+        tip: schema.string(),
+    }).nullable().optional(),
+    evidence: keywordResearchEvidenceProducerSchema,
+}, {
+    topic: schema.string().min(1),
+    keywords: schema.array(liveKeywordSchema.client),
+    totalFound: schema.number().int().nonnegative(),
+    filters: schema.looseObject({
+        minVolume: schema.number(),
+        maxVolume: schema.number(),
+        minDifficulty: schema.number(),
+        maxDifficulty: schema.number(),
+        intent: schema.string().optional(),
+    }),
+    message: schema.string().optional(),
+    tip: schema.string().optional(),
+    serpFallback: schema.looseObject({
+        message: schema.string(),
+        topResults: schema.array(serpFallbackResultSchema.client),
+        tip: schema.string(),
+    }).nullable().optional(),
+    evidence: keywordResearchEvidenceClientSchema,
+});
+export const keywordResearchResponseSchema = defineSuccessEnvelope(keywordResearchDataSchema);
+export const serpResearchQuerySchema = schema.strictObject({
+    keyword: schema.string().trim().min(2).max(200),
+    depth: schema.coerce.number().int().min(1).max(20).default(10),
+    locationCode: schema.coerce.number().int().positive().default(2840),
+});
+const serpOrganicResultSchema = defineResponseObject({
+    position: schema.number(),
+    url: schema.string(),
+    title: schema.string(),
+    domain: schema.string(),
+    description: schema.string().optional(),
+});
+const serpResearchDataSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    depth: schema.number().int().min(1).max(20),
+    results: schema.array(serpOrganicResultSchema.producer),
+    serpFeatures: schema.array(schema.string()),
+    hasAiOverview: schema.boolean(),
+    hasFeaturedSnippet: schema.boolean(),
+    hasLocalPack: schema.boolean(),
+    hasPeopleAlsoAsk: schema.boolean(),
+    fetchedAt: schema.string().datetime(),
+    cached: schema.boolean(),
+}, {
+    keyword: schema.string().min(1),
+    depth: schema.number().int().min(1).max(20),
+    results: schema.array(serpOrganicResultSchema.client),
+    serpFeatures: schema.array(schema.string()),
+    hasAiOverview: schema.boolean(),
+    hasFeaturedSnippet: schema.boolean(),
+    hasLocalPack: schema.boolean(),
+    hasPeopleAlsoAsk: schema.boolean(),
+    fetchedAt: schema.string().datetime(),
+    cached: schema.boolean(),
+});
+export const serpResearchResponseSchema = defineSuccessEnvelope(serpResearchDataSchema);
+export const rankingsResearchQuerySchema = schema.strictObject({
+    domain: schema.string().trim().min(1).max(253),
+    limit: schema.coerce.number().int().min(1).max(100).default(50),
+    minPosition: schema.coerce.number().int().min(1).max(100).default(1),
+    maxPosition: schema.coerce.number().int().min(1).max(100).default(20),
+    locationCode: schema.coerce.number().int().positive().default(2840),
+    order: schema.enum(['position', 'traffic']).default('position'),
+}).superRefine((value, context) => {
+    if (value.maxPosition < value.minPosition)
+        context.addIssue({ code: 'custom', path: ['maxPosition'], message: 'maxPosition must be at least minPosition.' });
+});
+const rankingKeywordSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    position: schema.number(),
+    volume: schema.number(),
+    traffic: schema.number(),
+    url: schema.string(),
+    intent: schema.string().nullable().optional(),
+});
+const rankingPageSchema = defineResponseObject({
+    path: schema.string(),
+    traffic: schema.number(),
+    keywords: schema.number(),
+});
+const rankingMetricsSchema = defineResponseObject({
+    organicTraffic: schema.number(),
+    totalKeywords: schema.number(),
+    keywordFootprint: schema.strictObject({
+        score: schema.number().nullable(),
+        scale: schema.strictObject({ min: schema.literal(0), max: schema.literal(100) }),
+        provenance: schema.literal('local-keyword-count'),
+    }),
+    trafficValue: schema.number().nullable(),
+    topPages: schema.array(rankingPageSchema.producer),
+}, {
+    organicTraffic: schema.number(),
+    totalKeywords: schema.number(),
+    keywordFootprint: schema.looseObject({
+        score: schema.number().nullable(),
+        scale: schema.looseObject({ min: schema.literal(0), max: schema.literal(100) }),
+        provenance: schema.literal('local-keyword-count'),
+    }),
+    trafficValue: schema.number().nullable(),
+    topPages: schema.array(rankingPageSchema.client),
+});
+const rankingsResearchDataSchema = defineResponseObject({
+    domain: schema.string().min(1),
+    keywords: schema.array(rankingKeywordSchema.producer),
+    totalFound: schema.number().int().nonnegative(),
+    metrics: rankingMetricsSchema.producer.nullable(),
+    positionRange: schema.strictObject({ min: schema.number(), max: schema.number() }).optional(),
+    message: schema.string().optional(),
+    cached: schema.boolean(),
+}, {
+    domain: schema.string().min(1),
+    keywords: schema.array(rankingKeywordSchema.client),
+    totalFound: schema.number().int().nonnegative(),
+    metrics: rankingMetricsSchema.client.nullable(),
+    positionRange: schema.looseObject({ min: schema.number(), max: schema.number() }).optional(),
+    message: schema.string().optional(),
+    cached: schema.boolean(),
+});
+export const rankingsResearchResponseSchema = defineSuccessEnvelope(rankingsResearchDataSchema);
 export const storedResearchOverviewOperation = defineOperation({
     id: 'research.overview',
     method: 'GET',
@@ -166,9 +387,116 @@ export const storedResearchOverviewOperation = defineOperation({
             }],
     },
 });
+const liveResearchErrors = [
+    'invalid_request',
+    'unauthorized',
+    'auth_expired',
+    'forbidden',
+    'not_found',
+    'entitlement_required',
+    'quota_exhausted',
+    'provider_unavailable',
+    'conflict',
+    'rate_limited',
+    'contract_violation',
+    'internal_error',
+];
+const liveResearchSemantics = {
+    kind: 'query',
+    sideEffects: 'none',
+    retry: 'idempotent',
+    readConsistency: 'primary',
+};
+const liveResearchAuth = {
+    credentials: ['session', 'api_token'],
+    scopes: ['research:read'],
+    minimumRole: 'viewer',
+    ownership: 'site',
+};
+const liveResearchPolicy = {
+    rate: publicV1StandardRatePolicy,
+    idempotency: { _tag: 'none' },
+    entitlement: 'growth',
+    meter: { key: 'dataforseo', units: 1, charge: 'live-only' },
+};
+export const keywordResearchOperation = defineOperation({
+    id: 'research.keywords',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/research/keywords',
+    visibility: 'public',
+    semantics: liveResearchSemantics,
+    auth: liveResearchAuth,
+    request: { params: researchSiteParamsSchema, query: keywordResearchQuerySchema, headers: null, body: null },
+    responses: { 200: keywordResearchResponseSchema },
+    errors: liveResearchErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveResearchPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Research keyword ideas',
+        description: 'Returns keyword ideas with volume, difficulty, intent, cost data, and explicit provider execution and spend evidence. Local guidance and cached reads consume no units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { topic: 'nuxt seo', limit: 20 } },
+                response: { status: 200, body: { data: { topic: 'nuxt seo', keywords: [], totalFound: 0, filters: { minVolume: 10, maxVolume: 10000, minDifficulty: 0, maxDifficulty: 60 }, evidence: { _tag: 'live', provider: 'dataforseo', spend: { key: 'dataforseo', units: 1 } } }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } },
+            }],
+    },
+});
+export const serpResearchOperation = defineOperation({
+    id: 'research.serp',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/research/serp',
+    visibility: 'public',
+    semantics: liveResearchSemantics,
+    auth: liveResearchAuth,
+    request: { params: researchSiteParamsSchema, query: serpResearchQuerySchema, headers: null, body: null },
+    responses: { 200: serpResearchResponseSchema },
+    errors: liveResearchErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveResearchPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Analyze a Google SERP',
+        description: 'Returns one dated SERP snapshot and its result features. Cached reads consume no units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { keyword: 'nuxt seo', depth: 10 } },
+                response: { status: 200, body: { data: { keyword: 'nuxt seo', depth: 10, results: [], serpFeatures: [], hasAiOverview: false, hasFeaturedSnippet: false, hasLocalPack: false, hasPeopleAlsoAsk: false, fetchedAt: '2026-08-20T00:00:00.000Z', cached: false }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } },
+            }],
+    },
+});
+export const rankingsResearchOperation = defineOperation({
+    id: 'research.rankings',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/research/rankings',
+    visibility: 'public',
+    semantics: liveResearchSemantics,
+    auth: liveResearchAuth,
+    request: { params: researchSiteParamsSchema, query: rankingsResearchQuerySchema, headers: null, body: null },
+    responses: { 200: rankingsResearchResponseSchema },
+    errors: liveResearchErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveResearchPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Research domain rankings',
+        description: 'Returns current keyword rankings and domain metrics. Cached reads consume no units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { domain: 'nuxtseo.com', limit: 20 } },
+                response: { status: 200, body: { data: { domain: 'nuxtseo.com', keywords: [], totalFound: 0, metrics: null, positionRange: { min: 1, max: 20 }, cached: false }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } },
+            }],
+    },
+});
 export const researchV1Registry = defineRegistry({
     feature: 'research',
     operations: {
         overview: storedResearchOverviewOperation,
+        keywords: keywordResearchOperation,
+        serp: serpResearchOperation,
+        rankings: rankingsResearchOperation,
     },
 });