@nuxtseo/protocol 0.5.4 → 0.5.5

package/dist/v1/research.js

@@ -193,6 +193,10 @@ const keywordResearchEvidenceClientSchema = schema.discriminatedUnion('_tag', [
 ]);
 const keywordResearchDataSchema = defineResponseObject({
     topic: schema.string().min(1),
+    topicMetrics: schema.array(schema.discriminatedUnion('_tag', [
+        schema.strictObject({ _tag: schema.literal('measured'), topic: schema.string().min(1), metrics: liveKeywordSchema.producer }),
+        schema.strictObject({ _tag: schema.literal('no-data'), topic: schema.string().min(1) }),
+    ])),
     keywords: schema.array(liveKeywordSchema.producer),
     totalFound: schema.number().int().nonnegative(),
     filters: schema.strictObject({
@@ -224,6 +228,10 @@ const keywordResearchDataSchema = defineResponseObject({
     evidence: keywordResearchEvidenceProducerSchema,
 }, {
     topic: schema.string().min(1),
+    topicMetrics: schema.array(schema.discriminatedUnion('_tag', [
+        schema.looseObject({ _tag: schema.literal('measured'), topic: schema.string().min(1), metrics: liveKeywordSchema.client }),
+        schema.looseObject({ _tag: schema.literal('no-data'), topic: schema.string().min(1) }),
+    ])),
     keywords: schema.array(liveKeywordSchema.client),
     totalFound: schema.number().int().nonnegative(),
     filters: schema.looseObject({
@@ -478,11 +486,11 @@ export const keywordResearchOperation = defineOperation({
     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.',
+        description: 'Returns exact metrics for each requested topic alongside filtered keyword ideas. Missing provider data stays explicit. 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' } } },
+                response: { status: 200, body: { data: { topic: 'nuxt seo', topicMetrics: [{ _tag: 'no-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' } } },
             }],
     },
 });
@@ -705,6 +713,112 @@ export const domainAvailabilityOperation = defineOperation({
             }],
     },
 });
+const trackedCompetitorSchema = schema.strictObject({
+    id: schema.string().min(1),
+    domain: schema.string().min(1),
+});
+export const competitorsListResponseSchema = defineSuccessEnvelope(defineResponseObject({
+    competitors: schema.array(trackedCompetitorSchema),
+}, {
+    competitors: schema.array(trackedCompetitorSchema),
+}));
+export const competitorAddResponseSchema = defineSuccessEnvelope(defineResponseObject({
+    competitor: trackedCompetitorSchema,
+    status: schema.literal('queued'),
+}, {
+    competitor: trackedCompetitorSchema,
+    status: schema.literal('queued'),
+}));
+export const competitorRemoveResponseSchema = defineSuccessEnvelope(defineResponseObject({
+    competitorId: schema.string().min(1),
+    deleted: schema.literal(true),
+}, {
+    competitorId: schema.string().min(1),
+    deleted: schema.literal(true),
+}));
+const competitorWriteAuth = {
+    credentials: ['session', 'api_token'],
+    scopes: ['research:write'],
+    minimumRole: 'member',
+    ownership: 'site',
+};
+const competitorResources = {
+    reads: [{ type: 'site.research', idFrom: 'params.siteId' }],
+    changes: [{ type: 'site.research', idFrom: 'params.siteId' }],
+};
+const competitorWriteErrors = liveResearchErrors;
+export const competitorsListOperation = defineOperation({
+    id: 'research.competitors.list',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/research/competitors',
+    visibility: 'public',
+    semantics: liveResearchSemantics,
+    auth: liveResearchAuth,
+    request: { params: researchSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: competitorsListResponseSchema },
+    errors: liveResearchErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: competitorResources.reads, changes: [] },
+    policy: { rate: publicV1StandardRatePolicy, idempotency: { _tag: 'none' }, entitlement: null, meter: null },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'List tracked competitors',
+        description: 'Returns competitors you added to this Site. Suggested competitors stay excluded. Reads start no provider work.',
+        tags: ['Research'],
+        examples: [{ request: { params: { siteId: 's_example' } }, response: { status: 200, body: {
+                        data: { competitors: [{ id: 'c_example', domain: 'rival.com' }] },
+                        meta: { requestId: 'req_example', version: '1.0' },
+                    } } }],
+    },
+});
+export const competitorAddOperation = defineOperation({
+    id: 'research.competitors.add',
+    method: 'POST',
+    path: '/api/v1/sites/{siteId}/research/competitors',
+    visibility: 'public',
+    semantics: { kind: 'mutation', sideEffects: 'state', retry: 'never', readConsistency: null },
+    auth: competitorWriteAuth,
+    request: { params: researchSiteParamsSchema, query: null, headers: null, body: schema.strictObject({ domain: schema.string().trim().min(1).max(2048) }) },
+    responses: { 200: competitorAddResponseSchema },
+    errors: competitorWriteErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: competitorResources,
+    policy: { rate: publicV1StandardRatePolicy, idempotency: { _tag: 'none' }, entitlement: 'growth', meter: { key: 'dataforseo', units: 1, charge: 'always' } },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Add one tracked competitor',
+        description: 'Queues analysis for one public domain you name. The existing Site and Team limits apply. Duplicate domains start no work.',
+        tags: ['Research'],
+        examples: [{ request: { params: { siteId: 's_example' }, body: { domain: 'rival.com' } }, response: { status: 200, body: {
+                        data: { competitor: { id: 'c_example', domain: 'rival.com' }, status: 'queued' },
+                        meta: { requestId: 'req_example', version: '1.0' },
+                    } } }],
+    },
+});
+export const competitorRemoveOperation = defineOperation({
+    id: 'research.competitors.remove',
+    method: 'DELETE',
+    path: '/api/v1/sites/{siteId}/research/competitors/{competitorId}',
+    visibility: 'public',
+    semantics: { kind: 'mutation', sideEffects: 'state', retry: 'never', readConsistency: null },
+    auth: competitorWriteAuth,
+    request: { params: researchSiteParamsSchema.extend({ competitorId: schema.string().min(1) }), query: null, headers: null, body: null },
+    responses: { 200: competitorRemoveResponseSchema },
+    errors: competitorWriteErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: competitorResources,
+    policy: { rate: publicV1StandardRatePolicy, idempotency: { _tag: 'none' }, entitlement: null, meter: null },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Remove one tracked competitor',
+        description: 'Removes a competitor from this Site using its listed id. Removal starts no provider work.',
+        tags: ['Research'],
+        examples: [{ request: { params: { siteId: 's_example', competitorId: 'c_example' } }, response: { status: 200, body: {
+                        data: { competitorId: 'c_example', deleted: true },
+                        meta: { requestId: 'req_example', version: '1.0' },
+                    } } }],
+    },
+});
 export const researchV1Registry = defineRegistry({
     feature: 'research',
     operations: {
@@ -714,5 +828,8 @@ export const researchV1Registry = defineRegistry({
         rankings: rankingsResearchOperation,
         domainTraffic: domainTrafficOperation,
         domainAvailability: domainAvailabilityOperation,
+        listCompetitors: competitorsListOperation,
+        addCompetitor: competitorAddOperation,
+        removeCompetitor: competitorRemoveOperation,
     },
 });