@nuxtseo/protocol 0.2.1 → 0.4.0

package/dist/v1/performance.js

@@ -4,6 +4,19 @@ export const performanceSiteParamsSchema = schema.strictObject({
     siteId: schema.string().min(1),
 });
 const nullableMetricSchema = schema.number().nullable();
+/**
+ * A Lighthouse category score, 0 to 100, where a higher number is better.
+ * Used for `perf`, `a11y`, `bestPractices` and `seo`.
+ */
+const nullableScoreSchema = nullableMetricSchema;
+/** A measured duration in milliseconds. Used for `lcp` and `tbt`. */
+const nullableMillisecondsSchema = nullableMetricSchema;
+/**
+ * Cumulative Layout Shift, unitless, normally between 0 and about 1. A lower
+ * number is better. Reported at the same scale as Lighthouse reports it, so
+ * `0.1` is the "good" threshold, not `100`.
+ */
+const nullableLayoutShiftSchema = nullableMetricSchema;
 export const performanceScoreSummarySchema = defineResponseObject({
     median: nullableMetricSchema,
     worst: nullableMetricSchema,
@@ -37,6 +50,12 @@ export const performanceVitalSummarySchema = defineResponseObject({
         poor: schema.number().int().nonnegative(),
     }),
 });
+/**
+ * Medians across the Site's latest Scans. Units follow the field: `perf`,
+ * `a11y`, `bestPractices` and `seo` are scores from 0 to 100, `lcp` and `tbt`
+ * are milliseconds, and `cls` is the unitless Cumulative Layout Shift value.
+ * `statusCounts` counts Scans in the good, needs-improvement and poor bands.
+ */
 export const sitePerformanceHealthSchema = defineResponseObject({
     perf: performanceScoreSummarySchema.producer,
     a11y: performanceCategorySummarySchema.producer,
@@ -62,24 +81,24 @@ export const sitePerformanceScanSchema = defineResponseObject({
     scanId: schema.string().min(1),
     url: schema.string().url(),
     completedAt: schema.string().datetime().nullable(),
-    perf: nullableMetricSchema,
-    a11y: nullableMetricSchema,
-    bestPractices: nullableMetricSchema,
-    seo: nullableMetricSchema,
-    lcp: nullableMetricSchema,
-    tbt: nullableMetricSchema,
-    cls: nullableMetricSchema,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 }, {
     scanId: schema.string().min(1),
     url: schema.string().url(),
     completedAt: schema.string().datetime().nullable(),
-    perf: nullableMetricSchema,
-    a11y: nullableMetricSchema,
-    bestPractices: nullableMetricSchema,
-    seo: nullableMetricSchema,
-    lcp: nullableMetricSchema,
-    tbt: nullableMetricSchema,
-    cls: nullableMetricSchema,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 });
 export const sitePerformanceRouteSchema = defineResponseObject({
     pageId: schema.string().min(1),
@@ -87,26 +106,26 @@ export const sitePerformanceRouteSchema = defineResponseObject({
     url: schema.string().url(),
     latestScanId: schema.string().min(1).nullable(),
     completedAt: schema.string().datetime().nullable(),
-    perf: nullableMetricSchema,
-    a11y: nullableMetricSchema,
-    bestPractices: nullableMetricSchema,
-    seo: nullableMetricSchema,
-    lcp: nullableMetricSchema,
-    tbt: nullableMetricSchema,
-    cls: nullableMetricSchema,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 }, {
     pageId: schema.string().min(1),
     path: schema.string(),
     url: schema.string().url(),
     latestScanId: schema.string().min(1).nullable(),
     completedAt: schema.string().datetime().nullable(),
-    perf: nullableMetricSchema,
-    a11y: nullableMetricSchema,
-    bestPractices: nullableMetricSchema,
-    seo: nullableMetricSchema,
-    lcp: nullableMetricSchema,
-    tbt: nullableMetricSchema,
-    cls: nullableMetricSchema,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 });
 export const sitePerformanceOverviewDataSchema = defineResponseObject({
     health: sitePerformanceHealthSchema.producer.nullable(),
@@ -142,6 +161,7 @@ export const sitePerformanceOverviewOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',
@@ -175,7 +195,7 @@ export const sitePerformanceOverviewOperation = defineOperation({
                                 seo: { median: 98, worst: 94 },
                                 lcp: { median: 2200, worst: 4100, statusCounts: { good: 3, ni: 1, poor: 1 } },
                                 tbt: { median: 180, worst: 650, statusCounts: { good: 3, ni: 1, poor: 1 } },
-                                cls: { median: 80, worst: 260, statusCounts: { good: 4, ni: 0, poor: 1 } },
+                                cls: { median: 0.08, worst: 0.26, statusCounts: { good: 4, ni: 0, poor: 1 } },
                                 scannedPageCount: 5,
                                 lastScanAt: '2026-08-10T01:00:00.000Z',
                             },
@@ -276,6 +296,7 @@ export const fieldVitalsOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',
@@ -385,6 +406,7 @@ export const fieldVitalFindingsOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',
@@ -506,6 +528,7 @@ export const performanceScansOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',
@@ -592,6 +615,7 @@ export const monitoredPagesOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',
@@ -772,6 +796,7 @@ export const performanceScanDetailOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',

package/dist/v1/research.d.ts

@@ -599,7 +599,19 @@ declare const keywordResearchDataSchema: import("./core.js").CompatibleResponseS
         maxDifficulty: z.ZodNumber;
         intent: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     readonly message: z.ZodOptional<z.ZodString>;
+    /**
+     * A concrete next argument to try, when `message` names a fixable argument.
+     */
     readonly tip: z.ZodOptional<z.ZodString>;
     readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         message: z.ZodString;
@@ -667,7 +679,19 @@ declare const keywordResearchDataSchema: import("./core.js").CompatibleResponseS
         maxDifficulty: z.ZodNumber;
         intent: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>;
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     readonly message: z.ZodOptional<z.ZodString>;
+    /**
+     * A concrete next argument to try, when `message` names a fixable argument.
+     */
     readonly tip: z.ZodOptional<z.ZodString>;
     readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         message: z.ZodString;
@@ -737,7 +761,19 @@ export declare const keywordResearchResponseSchema: import("./core.js").Compatib
             maxDifficulty: z.ZodNumber;
             intent: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
+        /**
+         * Why a result set is empty, in one sentence for a person.
+         *
+         * The provider answers 200 with an empty list both when the argument was
+         * refused and when the argument was accepted but matched nothing. `message`
+         * is the only field that tells the two apart, so a caller that reads the list
+         * alone will misread a refusal as an absence of demand. Present only when the
+         * list is empty for a reason worth naming.
+         */
         readonly message: z.ZodOptional<z.ZodString>;
+        /**
+         * A concrete next argument to try, when `message` names a fixable argument.
+         */
         readonly tip: z.ZodOptional<z.ZodString>;
         readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             message: z.ZodString;
@@ -811,7 +847,19 @@ export declare const keywordResearchResponseSchema: import("./core.js").Compatib
             maxDifficulty: z.ZodNumber;
             intent: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>;
+        /**
+         * Why a result set is empty, in one sentence for a person.
+         *
+         * The provider answers 200 with an empty list both when the argument was
+         * refused and when the argument was accepted but matched nothing. `message`
+         * is the only field that tells the two apart, so a caller that reads the list
+         * alone will misread a refusal as an absence of demand. Present only when the
+         * list is empty for a reason worth naming.
+         */
         readonly message: z.ZodOptional<z.ZodString>;
+        /**
+         * A concrete next argument to try, when `message` names a fixable argument.
+         */
         readonly tip: z.ZodOptional<z.ZodString>;
         readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             message: z.ZodString;
@@ -982,6 +1030,15 @@ declare const rankingsResearchDataSchema: import("./core.js").CompatibleResponse
         min: z.ZodNumber;
         max: z.ZodNumber;
     }, z.core.$strict>>;
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     readonly message: z.ZodOptional<z.ZodString>;
     readonly cached: z.ZodBoolean;
 }, z.core.$strip>, z.ZodObject<{
@@ -1017,6 +1074,15 @@ declare const rankingsResearchDataSchema: import("./core.js").CompatibleResponse
         min: z.ZodNumber;
         max: z.ZodNumber;
     }, z.core.$loose>>;
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     readonly message: z.ZodOptional<z.ZodString>;
     readonly cached: z.ZodBoolean;
 }, z.core.$strip>>;
@@ -1054,6 +1120,15 @@ export declare const rankingsResearchResponseSchema: import("./core.js").Compati
             min: z.ZodNumber;
             max: z.ZodNumber;
         }, z.core.$strict>>;
+        /**
+         * Why a result set is empty, in one sentence for a person.
+         *
+         * The provider answers 200 with an empty list both when the argument was
+         * refused and when the argument was accepted but matched nothing. `message`
+         * is the only field that tells the two apart, so a caller that reads the list
+         * alone will misread a refusal as an absence of demand. Present only when the
+         * list is empty for a reason worth naming.
+         */
         readonly message: z.ZodOptional<z.ZodString>;
         readonly cached: z.ZodBoolean;
     }, z.core.$strip>;
@@ -1095,6 +1170,15 @@ export declare const rankingsResearchResponseSchema: import("./core.js").Compati
             min: z.ZodNumber;
             max: z.ZodNumber;
         }, z.core.$loose>>;
+        /**
+         * Why a result set is empty, in one sentence for a person.
+         *
+         * The provider answers 200 with an empty list both when the argument was
+         * refused and when the argument was accepted but matched nothing. `message`
+         * is the only field that tells the two apart, so a caller that reads the list
+         * alone will misread a refusal as an absence of demand. Present only when the
+         * list is empty for a reason worth naming.
+         */
         readonly message: z.ZodOptional<z.ZodString>;
         readonly cached: z.ZodBoolean;
     }, z.core.$strip>;
@@ -1315,7 +1399,7 @@ export declare const storedResearchOverviewOperation: {
             }, z.core.$loose>;
         }, z.core.$strip>>;
     };
-    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "contract_violation", "internal_error"];
+    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "contract_violation", "internal_error"];
     readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
         readonly error: z.ZodObject<{
             code: z.ZodEnum<{
@@ -1504,7 +1588,19 @@ export declare const keywordResearchOperation: {
                     maxDifficulty: z.ZodNumber;
                     intent: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>;
+                /**
+                 * Why a result set is empty, in one sentence for a person.
+                 *
+                 * The provider answers 200 with an empty list both when the argument was
+                 * refused and when the argument was accepted but matched nothing. `message`
+                 * is the only field that tells the two apart, so a caller that reads the list
+                 * alone will misread a refusal as an absence of demand. Present only when the
+                 * list is empty for a reason worth naming.
+                 */
                 readonly message: z.ZodOptional<z.ZodString>;
+                /**
+                 * A concrete next argument to try, when `message` names a fixable argument.
+                 */
                 readonly tip: z.ZodOptional<z.ZodString>;
                 readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                     message: z.ZodString;
@@ -1578,7 +1674,19 @@ export declare const keywordResearchOperation: {
                     maxDifficulty: z.ZodNumber;
                     intent: z.ZodOptional<z.ZodString>;
                 }, z.core.$loose>;
+                /**
+                 * Why a result set is empty, in one sentence for a person.
+                 *
+                 * The provider answers 200 with an empty list both when the argument was
+                 * refused and when the argument was accepted but matched nothing. `message`
+                 * is the only field that tells the two apart, so a caller that reads the list
+                 * alone will misread a refusal as an absence of demand. Present only when the
+                 * list is empty for a reason worth naming.
+                 */
                 readonly message: z.ZodOptional<z.ZodString>;
+                /**
+                 * A concrete next argument to try, when `message` names a fixable argument.
+                 */
                 readonly tip: z.ZodOptional<z.ZodString>;
                 readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                     message: z.ZodString;
@@ -1998,6 +2106,15 @@ export declare const rankingsResearchOperation: {
                     min: z.ZodNumber;
                     max: z.ZodNumber;
                 }, z.core.$strict>>;
+                /**
+                 * Why a result set is empty, in one sentence for a person.
+                 *
+                 * The provider answers 200 with an empty list both when the argument was
+                 * refused and when the argument was accepted but matched nothing. `message`
+                 * is the only field that tells the two apart, so a caller that reads the list
+                 * alone will misread a refusal as an absence of demand. Present only when the
+                 * list is empty for a reason worth naming.
+                 */
                 readonly message: z.ZodOptional<z.ZodString>;
                 readonly cached: z.ZodBoolean;
             }, z.core.$strip>;
@@ -2039,6 +2156,15 @@ export declare const rankingsResearchOperation: {
                     min: z.ZodNumber;
                     max: z.ZodNumber;
                 }, z.core.$loose>>;
+                /**
+                 * Why a result set is empty, in one sentence for a person.
+                 *
+                 * The provider answers 200 with an empty list both when the argument was
+                 * refused and when the argument was accepted but matched nothing. `message`
+                 * is the only field that tells the two apart, so a caller that reads the list
+                 * alone will misread a refusal as an absence of demand. Present only when the
+                 * list is empty for a reason worth naming.
+                 */
                 readonly message: z.ZodOptional<z.ZodString>;
                 readonly cached: z.ZodBoolean;
             }, z.core.$strip>;
@@ -3203,7 +3329,7 @@ export declare const researchV1Registry: import("./core.js").PublicV1Registry<{
                 }, z.core.$loose>;
             }, z.core.$strip>>;
         };
-        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "contract_violation", "internal_error"];
+        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "contract_violation", "internal_error"];
         readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
             readonly error: z.ZodObject<{
                 code: z.ZodEnum<{
@@ -3392,7 +3518,19 @@ export declare const researchV1Registry: import("./core.js").PublicV1Registry<{
                         maxDifficulty: z.ZodNumber;
                         intent: z.ZodOptional<z.ZodString>;
                     }, z.core.$strict>;
+                    /**
+                     * Why a result set is empty, in one sentence for a person.
+                     *
+                     * The provider answers 200 with an empty list both when the argument was
+                     * refused and when the argument was accepted but matched nothing. `message`
+                     * is the only field that tells the two apart, so a caller that reads the list
+                     * alone will misread a refusal as an absence of demand. Present only when the
+                     * list is empty for a reason worth naming.
+                     */
                     readonly message: z.ZodOptional<z.ZodString>;
+                    /**
+                     * A concrete next argument to try, when `message` names a fixable argument.
+                     */
                     readonly tip: z.ZodOptional<z.ZodString>;
                     readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                         message: z.ZodString;
@@ -3466,7 +3604,19 @@ export declare const researchV1Registry: import("./core.js").PublicV1Registry<{
                         maxDifficulty: z.ZodNumber;
                         intent: z.ZodOptional<z.ZodString>;
                     }, z.core.$loose>;
+                    /**
+                     * Why a result set is empty, in one sentence for a person.
+                     *
+                     * The provider answers 200 with an empty list both when the argument was
+                     * refused and when the argument was accepted but matched nothing. `message`
+                     * is the only field that tells the two apart, so a caller that reads the list
+                     * alone will misread a refusal as an absence of demand. Present only when the
+                     * list is empty for a reason worth naming.
+                     */
                     readonly message: z.ZodOptional<z.ZodString>;
+                    /**
+                     * A concrete next argument to try, when `message` names a fixable argument.
+                     */
                     readonly tip: z.ZodOptional<z.ZodString>;
                     readonly serpFallback: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                         message: z.ZodString;
@@ -3886,6 +4036,15 @@ export declare const researchV1Registry: import("./core.js").PublicV1Registry<{
                         min: z.ZodNumber;
                         max: z.ZodNumber;
                     }, z.core.$strict>>;
+                    /**
+                     * Why a result set is empty, in one sentence for a person.
+                     *
+                     * The provider answers 200 with an empty list both when the argument was
+                     * refused and when the argument was accepted but matched nothing. `message`
+                     * is the only field that tells the two apart, so a caller that reads the list
+                     * alone will misread a refusal as an absence of demand. Present only when the
+                     * list is empty for a reason worth naming.
+                     */
                     readonly message: z.ZodOptional<z.ZodString>;
                     readonly cached: z.ZodBoolean;
                 }, z.core.$strip>;
@@ -3927,6 +4086,15 @@ export declare const researchV1Registry: import("./core.js").PublicV1Registry<{
                         min: z.ZodNumber;
                         max: z.ZodNumber;
                     }, z.core.$loose>>;
+                    /**
+                     * Why a result set is empty, in one sentence for a person.
+                     *
+                     * The provider answers 200 with an empty list both when the argument was
+                     * refused and when the argument was accepted but matched nothing. `message`
+                     * is the only field that tells the two apart, so a caller that reads the list
+                     * alone will misread a refusal as an absence of demand. Present only when the
+                     * list is empty for a reason worth naming.
+                     */
                     readonly message: z.ZodOptional<z.ZodString>;
                     readonly cached: z.ZodBoolean;
                 }, z.core.$strip>;

package/dist/v1/research.js

@@ -202,7 +202,19 @@ const keywordResearchDataSchema = defineResponseObject({
         maxDifficulty: schema.number(),
         intent: schema.string().optional(),
     }),
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     message: schema.string().optional(),
+    /**
+     * A concrete next argument to try, when `message` names a fixable argument.
+     */
     tip: schema.string().optional(),
     serpFallback: schema.strictObject({
         message: schema.string(),
@@ -221,7 +233,19 @@ const keywordResearchDataSchema = defineResponseObject({
         maxDifficulty: schema.number(),
         intent: schema.string().optional(),
     }),
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     message: schema.string().optional(),
+    /**
+     * A concrete next argument to try, when `message` names a fixable argument.
+     */
     tip: schema.string().optional(),
     serpFallback: schema.looseObject({
         message: schema.string(),
@@ -318,6 +342,15 @@ const rankingsResearchDataSchema = defineResponseObject({
     totalFound: schema.number().int().nonnegative(),
     metrics: rankingMetricsSchema.producer.nullable(),
     positionRange: schema.strictObject({ min: schema.number(), max: schema.number() }).optional(),
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     message: schema.string().optional(),
     cached: schema.boolean(),
 }, {
@@ -326,6 +359,15 @@ const rankingsResearchDataSchema = defineResponseObject({
     totalFound: schema.number().int().nonnegative(),
     metrics: rankingMetricsSchema.client.nullable(),
     positionRange: schema.looseObject({ min: schema.number(), max: schema.number() }).optional(),
+    /**
+     * Why a result set is empty, in one sentence for a person.
+     *
+     * The provider answers 200 with an empty list both when the argument was
+     * refused and when the argument was accepted but matched nothing. `message`
+     * is the only field that tells the two apart, so a caller that reads the list
+     * alone will misread a refusal as an absence of demand. Present only when the
+     * list is empty for a reason worth naming.
+     */
     message: schema.string().optional(),
     cached: schema.boolean(),
 });
@@ -350,6 +392,7 @@ export const storedResearchOverviewOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',

package/dist/v1/sitemaps.d.ts

@@ -376,7 +376,7 @@ export declare const siteSitemapsListOperation: {
             }, z.core.$loose>;
         }, z.core.$strip>>;
     };
-    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
+    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
     readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
         readonly error: z.ZodObject<{
             code: z.ZodEnum<{
@@ -586,7 +586,7 @@ export declare const siteSitemapUrlsListOperation: {
             }, z.core.$loose>;
         }, z.core.$strip>>;
     };
-    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
+    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
     readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
         readonly error: z.ZodObject<{
             code: z.ZodEnum<{
@@ -762,7 +762,7 @@ export declare const siteSitemapActionCreateOperation: {
             }, z.core.$loose>;
         }, z.core.$strip>>;
     };
-    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
+    readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "provider_unavailable", "contract_violation", "internal_error", "entitlement_required"];
     readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
         readonly error: z.ZodObject<{
             code: z.ZodEnum<{
@@ -1012,7 +1012,7 @@ export declare const sitemapsV1Registry: import("./core.js").PublicV1Registry<{
                 }, z.core.$loose>;
             }, z.core.$strip>>;
         };
-        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
+        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
         readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
             readonly error: z.ZodObject<{
                 code: z.ZodEnum<{
@@ -1222,7 +1222,7 @@ export declare const sitemapsV1Registry: import("./core.js").PublicV1Registry<{
                 }, z.core.$loose>;
             }, z.core.$strip>>;
         };
-        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
+        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
         readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
             readonly error: z.ZodObject<{
                 code: z.ZodEnum<{
@@ -1398,7 +1398,7 @@ export declare const sitemapsV1Registry: import("./core.js").PublicV1Registry<{
                 }, z.core.$loose>;
             }, z.core.$strip>>;
         };
-        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "rate_limited", "provider_unavailable", "contract_violation", "internal_error"];
+        readonly errors: readonly ["invalid_request", "unauthorized", "auth_expired", "forbidden", "not_found", "conflict", "rate_limited", "provider_unavailable", "contract_violation", "internal_error", "entitlement_required"];
         readonly errorResponse: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
             readonly error: z.ZodObject<{
                 code: z.ZodEnum<{

package/dist/v1/sitemaps.js

@@ -26,6 +26,7 @@ const readErrors = [
     'auth_expired',
     'forbidden',
     'not_found',
+    'conflict',
     'rate_limited',
     'provider_unavailable',
     'contract_violation',
@@ -157,7 +158,7 @@ export const siteSitemapActionCreateOperation = defineOperation({
     },
     request: { params: siteSitemapParamsSchema, query: null, headers: null, body: siteSitemapActionBodySchema },
     responses: { 200: siteSitemapActionResponseSchema },
-    errors: readErrors,
+    errors: [...readErrors, 'entitlement_required'],
     errorResponse: publicV1ErrorEnvelope,
     resources: {
         reads: [{ type: 'site.sitemaps', idFrom: 'params.siteId' }],