@nuxtseo/protocol 0.1.4 → 0.2.0

package/dist/v1/research.js

@@ -491,6 +491,177 @@ export const rankingsResearchOperation = defineOperation({
             }],
     },
 });
+// ---------------------------------------------------------------------------
+// Domain lookups — the `domain_info` MCP tool. These read arbitrary third-party
+// domains, so they carry the same Growth entitlement and DataForSEO meter as
+// the other live research operations, and the Site in the path is the billing
+// and authorization anchor rather than the subject.
+// ---------------------------------------------------------------------------
+/**
+ * One domain, never a list packed into one value. A comma is not legal in a
+ * hostname, so `?domains=a.com,b.com` can only be a caller who guessed the
+ * wrong list syntax. Accepting it verbatim handed `cleanDomain` a string it
+ * takes without complaint, and the caller got `results: []` and no error.
+ * Repeating the parameter is the only list form, and this rejects the other
+ * one loudly — the same way `metrics` on `page.vitals.findings` already does,
+ * because its members are an enum.
+ */
+const domainNameSchema = schema.string().trim().min(1).max(253).refine(value => !value.includes(','), { message: 'one domain per value; repeat the parameter for more than one' });
+export const domainTrafficQuerySchema = schema.strictObject({
+    domain: domainNameSchema,
+});
+export const domainAvailabilityQuerySchema = schema.strictObject({
+    domains: schema.union([
+        schema.array(domainNameSchema).min(1).max(10),
+        domainNameSchema.transform(one => [one]),
+    ]),
+});
+export const domainTrafficPageSchema = defineResponseObject({
+    path: schema.string(),
+    traffic: schema.number(),
+    keywords: schema.number(),
+}, {
+    path: schema.string(),
+    traffic: schema.number(),
+    keywords: schema.number(),
+});
+export const domainTrafficDataSchema = defineResponseObject({
+    domain: schema.string(),
+    monthlyTraffic: schema.number(),
+    trend: schema.enum(['growing', 'stable', 'declining']),
+    changePercent: schema.number(),
+    trafficValue: schema.number().nullable(),
+    keywordFootprint: schema.number().nullable(),
+    topPages: schema.array(domainTrafficPageSchema.producer),
+    topCountries: schema.array(schema.strictObject({
+        country: schema.string(),
+        percent: schema.number(),
+    })),
+    message: schema.string().nullable(),
+    evidence: keywordResearchEvidenceProducerSchema,
+}, {
+    domain: schema.string(),
+    monthlyTraffic: schema.number(),
+    trend: schema.enum(['growing', 'stable', 'declining']),
+    changePercent: schema.number(),
+    trafficValue: schema.number().nullable(),
+    keywordFootprint: schema.number().nullable(),
+    topPages: schema.array(domainTrafficPageSchema.client),
+    topCountries: schema.array(schema.looseObject({
+        country: schema.string(),
+        percent: schema.number(),
+    })),
+    message: schema.string().nullable(),
+    evidence: keywordResearchEvidenceClientSchema,
+});
+export const domainTrafficResponseSchema = defineSuccessEnvelope(domainTrafficDataSchema);
+export const domainTrafficOperation = defineOperation({
+    id: 'research.domain.traffic',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/research/domain-traffic',
+    visibility: 'public',
+    semantics: liveResearchSemantics,
+    auth: liveResearchAuth,
+    request: { params: researchSiteParamsSchema, query: domainTrafficQuerySchema, headers: null, body: null },
+    responses: { 200: domainTrafficResponseSchema },
+    errors: liveResearchErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveResearchPolicy,
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Estimate domain traffic',
+        description: 'Returns an estimate of one domain organic search traffic, its trend, its top pages and countries. The domain does not have to be one of your Sites, so this reads a competitor as readily as your own. Cached reads consume no units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { domain: 'nuxtseo.com' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            domain: 'nuxtseo.com',
+                            monthlyTraffic: 48200,
+                            trend: 'growing',
+                            changePercent: 12.4,
+                            trafficValue: 31200,
+                            keywordFootprint: 62,
+                            topPages: [{ path: '/docs/sitemap', traffic: 4100, keywords: 220 }],
+                            topCountries: [{ country: 'US', percent: 41.2 }],
+                            message: null,
+                            evidence: { _tag: 'live', provider: 'dataforseo', spend: { key: 'dataforseo', units: 1 } },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const domainStatusSchema = defineResponseObject({
+    domain: schema.string(),
+    available: schema.boolean(),
+    registrar: schema.string().nullable(),
+    expiration: schema.string().nullable(),
+    created: schema.string().nullable(),
+    note: schema.string().nullable(),
+}, {
+    domain: schema.string(),
+    available: schema.boolean(),
+    registrar: schema.string().nullable(),
+    expiration: schema.string().nullable(),
+    created: schema.string().nullable(),
+    note: schema.string().nullable(),
+});
+export const domainAvailabilityDataSchema = defineResponseObject({
+    results: schema.array(domainStatusSchema.producer),
+    message: schema.string().nullable(),
+    evidence: keywordResearchEvidenceProducerSchema,
+}, {
+    results: schema.array(domainStatusSchema.client),
+    message: schema.string().nullable(),
+    evidence: keywordResearchEvidenceClientSchema,
+});
+export const domainAvailabilityResponseSchema = defineSuccessEnvelope(domainAvailabilityDataSchema);
+export const domainAvailabilityOperation = defineOperation({
+    id: 'research.domain.availability',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/research/domain-availability',
+    visibility: 'public',
+    semantics: liveResearchSemantics,
+    auth: liveResearchAuth,
+    request: { params: researchSiteParamsSchema, query: domainAvailabilityQuerySchema, headers: null, body: null },
+    responses: { 200: domainAvailabilityResponseSchema },
+    errors: liveResearchErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveResearchPolicy,
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Check domain availability',
+        description: 'Returns the registration status of up to ten domains, with the registrar and expiry when the domain is taken. Repeat the domains parameter for each domain. Cached reads consume no units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { domains: ['example.com', 'example.dev'] } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            results: [{
+                                    domain: 'example.com',
+                                    available: false,
+                                    registrar: 'Example Registrar',
+                                    expiration: '2027-04-01',
+                                    created: '1995-08-14',
+                                    note: null,
+                                }],
+                            message: null,
+                            evidence: { _tag: 'live', provider: 'dataforseo', spend: { key: 'dataforseo', units: 1 } },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
 export const researchV1Registry = defineRegistry({
     feature: 'research',
     operations: {
@@ -498,5 +669,7 @@ export const researchV1Registry = defineRegistry({
         keywords: keywordResearchOperation,
         serp: serpResearchOperation,
         rankings: rankingsResearchOperation,
+        domainTraffic: domainTrafficOperation,
+        domainAvailability: domainAvailabilityOperation,
     },
 });