@nuxtseo/protocol 0.2.1 → 0.3.0

package/dist/v1/backlinks.js

@@ -1,5 +1,5 @@
 import { z as schema } from 'zod';
-import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1BooleanFlag, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1BooleanFlag, publicV1ErrorEnvelope, publicV1PageSchema, publicV1StandardRatePolicy, } from './core.js';
 export const backlinksSiteParamsSchema = schema.strictObject({
     siteId: schema.string().min(1),
 });
@@ -38,12 +38,19 @@ export const recoverableBacklinkSchema = defineResponseObject({
     lastSeenAt: schema.string().datetime().nullable(),
 });
 export const recoverableBacklinksDataSchema = defineResponseObject({
+    /**
+     * Deprecated alias of `rows`. Kept for one minor version, then removed.
+     */
     items: schema.array(recoverableBacklinkSchema.producer),
+    rows: schema.array(recoverableBacklinkSchema.producer),
+    page: publicV1PageSchema.producer,
     total: schema.number().int().nonnegative(),
     limit: schema.number().int().positive(),
     offset: schema.number().int().nonnegative(),
 }, {
     items: schema.array(recoverableBacklinkSchema.client),
+    rows: schema.array(recoverableBacklinkSchema.client).optional(),
+    page: publicV1PageSchema.client.optional(),
     total: schema.number().int().nonnegative(),
     limit: schema.number().int().positive(),
     offset: schema.number().int().nonnegative(),
@@ -108,6 +115,20 @@ export const recoverableBacklinksOperation = defineOperation({
                                     firstSeenAt: '2026-02-09T20:43:50.000Z',
                                     lastSeenAt: '2026-07-17T04:40:07.000Z',
                                 }],
+                            rows: [{
+                                    id: 'bl_01JXYZ',
+                                    destinationUrl: 'https://example.com/docs/utils',
+                                    referringUrl: 'https://news.example/posts/seo',
+                                    referringDomain: 'news.example',
+                                    anchor: 'Read the full documentation',
+                                    destinationStatus: 404,
+                                    domainRank: 529,
+                                    pageRank: 55,
+                                    dofollow: true,
+                                    firstSeenAt: '2026-02-09T20:43:50.000Z',
+                                    lastSeenAt: '2026-07-17T04:40:07.000Z',
+                                }],
+                            page: { total: 1, limit: 100, offset: 0, hasMore: false },
                             total: 1,
                             limit: 100,
                             offset: 0,
@@ -150,10 +171,23 @@ export const mentionSchema = defineResponseObject({
     publishedAt: schema.string().datetime().nullable(),
 });
 export const mentionsDataSchema = defineResponseObject({
+    /**
+     * Deprecated alias of `rows`. Kept for one minor version, then removed.
+     */
     items: schema.array(mentionSchema.producer),
+    rows: schema.array(mentionSchema.producer),
+    page: publicV1PageSchema.producer,
+    /**
+     * The whole result set, not this page. The response carried no total and no
+     * `hasMore`, so a caller could not tell a full page from the last page.
+     */
+    total: schema.number().int().nonnegative(),
     limit: schema.number().int().positive(),
 }, {
     items: schema.array(mentionSchema.client),
+    rows: schema.array(mentionSchema.client).optional(),
+    page: publicV1PageSchema.client.optional(),
+    total: schema.number().int().nonnegative().optional(),
     limit: schema.number().int().positive(),
 });
 export const mentionsResponseSchema = defineSuccessEnvelope(mentionsDataSchema);
@@ -217,6 +251,22 @@ export const mentionsListOperation = defineOperation({
                                     domainRank: 812,
                                     publishedAt: '2026-08-01T09:12:00.000Z',
                                 }],
+                            rows: [{
+                                    id: 'mn_01JXYZ',
+                                    source: 'hackernews',
+                                    url: 'https://news.ycombinator.com/item?id=1',
+                                    domain: 'news.ycombinator.com',
+                                    title: 'Show HN: a sitemap module',
+                                    snippet: 'We moved to example.com last week',
+                                    author: 'Ada Lovelace',
+                                    authorHandle: 'ada',
+                                    engagement: 142,
+                                    sentiment: 'positive',
+                                    domainRank: 812,
+                                    publishedAt: '2026-08-01T09:12:00.000Z',
+                                }],
+                            page: { total: 1, limit: 100, offset: 0, hasMore: false },
+                            total: 1,
                             limit: 100,
                         },
                         meta: { requestId: 'req_01JXYZ', version: '1.0' },

package/dist/v1/content.d.ts

@@ -442,6 +442,9 @@ export declare const contentBriefResourceSchema: import("./core.js").CompatibleR
     readonly markedWrittenAt: z.ZodNullable<z.ZodISODateTime>;
 }, z.core.$strip>>;
 export declare const contentBriefListDataSchema: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
+    /**
+     * Deprecated alias of `rows`. Kept for one minor version, then removed.
+     */
     readonly briefs: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         siteId: z.ZodString;
@@ -461,6 +464,25 @@ export declare const contentBriefListDataSchema: import("./core.js").CompatibleR
         markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
         updatedAt: z.ZodNullable<z.ZodISODateTime>;
     }, z.core.$strip>>;
+    readonly rows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        siteId: z.ZodString;
+        keyword: z.ZodString;
+        status: z.ZodEnum<{
+            archived: "archived";
+            failed: "failed";
+            published: "published";
+            queued: "queued";
+            ready: "ready";
+            researching: "researching";
+            stale: "stale";
+            written: "written";
+        }>;
+        error: z.ZodNullable<z.ZodString>;
+        generatedAt: z.ZodNullable<z.ZodISODateTime>;
+        markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
     readonly page: z.ZodObject<{
         total: z.ZodNumber;
         limit: z.ZodNumber;
@@ -487,6 +509,25 @@ export declare const contentBriefListDataSchema: import("./core.js").CompatibleR
         markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
         updatedAt: z.ZodNullable<z.ZodISODateTime>;
     }, z.core.$strip>>;
+    readonly rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        siteId: z.ZodString;
+        keyword: z.ZodString;
+        status: z.ZodEnum<{
+            archived: "archived";
+            failed: "failed";
+            published: "published";
+            queued: "queued";
+            ready: "ready";
+            researching: "researching";
+            stale: "stale";
+            written: "written";
+        }>;
+        error: z.ZodNullable<z.ZodString>;
+        generatedAt: z.ZodNullable<z.ZodISODateTime>;
+        markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>>;
     readonly page: z.ZodObject<{
         total: z.ZodNumber;
         limit: z.ZodNumber;
@@ -651,6 +692,9 @@ export declare const contentBriefCreateDataSchema: import("./core.js").Compatibl
 }, z.core.$strip>>;
 export declare const contentBriefListResponseSchema: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
     data: z.ZodObject<{
+        /**
+         * Deprecated alias of `rows`. Kept for one minor version, then removed.
+         */
         readonly briefs: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             siteId: z.ZodString;
@@ -670,6 +714,25 @@ export declare const contentBriefListResponseSchema: import("./core.js").Compati
             markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
             updatedAt: z.ZodNullable<z.ZodISODateTime>;
         }, z.core.$strip>>;
+        readonly rows: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            siteId: z.ZodString;
+            keyword: z.ZodString;
+            status: z.ZodEnum<{
+                archived: "archived";
+                failed: "failed";
+                published: "published";
+                queued: "queued";
+                ready: "ready";
+                researching: "researching";
+                stale: "stale";
+                written: "written";
+            }>;
+            error: z.ZodNullable<z.ZodString>;
+            generatedAt: z.ZodNullable<z.ZodISODateTime>;
+            markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+            updatedAt: z.ZodNullable<z.ZodISODateTime>;
+        }, z.core.$strip>>;
         readonly page: z.ZodObject<{
             total: z.ZodNumber;
             limit: z.ZodNumber;
@@ -702,6 +765,25 @@ export declare const contentBriefListResponseSchema: import("./core.js").Compati
             markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
             updatedAt: z.ZodNullable<z.ZodISODateTime>;
         }, z.core.$strip>>;
+        readonly rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            siteId: z.ZodString;
+            keyword: z.ZodString;
+            status: z.ZodEnum<{
+                archived: "archived";
+                failed: "failed";
+                published: "published";
+                queued: "queued";
+                ready: "ready";
+                researching: "researching";
+                stale: "stale";
+                written: "written";
+            }>;
+            error: z.ZodNullable<z.ZodString>;
+            generatedAt: z.ZodNullable<z.ZodISODateTime>;
+            markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+            updatedAt: z.ZodNullable<z.ZodISODateTime>;
+        }, z.core.$strip>>>;
         readonly page: z.ZodObject<{
             total: z.ZodNumber;
             limit: z.ZodNumber;
@@ -1096,6 +1178,9 @@ export declare const contentBriefListOperation: {
     readonly responses: {
         readonly 200: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
             data: z.ZodObject<{
+                /**
+                 * Deprecated alias of `rows`. Kept for one minor version, then removed.
+                 */
                 readonly briefs: z.ZodArray<z.ZodObject<{
                     id: z.ZodString;
                     siteId: z.ZodString;
@@ -1115,6 +1200,25 @@ export declare const contentBriefListOperation: {
                     markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
                     updatedAt: z.ZodNullable<z.ZodISODateTime>;
                 }, z.core.$strip>>;
+                readonly rows: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    siteId: z.ZodString;
+                    keyword: z.ZodString;
+                    status: z.ZodEnum<{
+                        archived: "archived";
+                        failed: "failed";
+                        published: "published";
+                        queued: "queued";
+                        ready: "ready";
+                        researching: "researching";
+                        stale: "stale";
+                        written: "written";
+                    }>;
+                    error: z.ZodNullable<z.ZodString>;
+                    generatedAt: z.ZodNullable<z.ZodISODateTime>;
+                    markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+                    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+                }, z.core.$strip>>;
                 readonly page: z.ZodObject<{
                     total: z.ZodNumber;
                     limit: z.ZodNumber;
@@ -1147,6 +1251,25 @@ export declare const contentBriefListOperation: {
                     markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
                     updatedAt: z.ZodNullable<z.ZodISODateTime>;
                 }, z.core.$strip>>;
+                readonly rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    siteId: z.ZodString;
+                    keyword: z.ZodString;
+                    status: z.ZodEnum<{
+                        archived: "archived";
+                        failed: "failed";
+                        published: "published";
+                        queued: "queued";
+                        ready: "ready";
+                        researching: "researching";
+                        stale: "stale";
+                        written: "written";
+                    }>;
+                    error: z.ZodNullable<z.ZodString>;
+                    generatedAt: z.ZodNullable<z.ZodISODateTime>;
+                    markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+                    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+                }, z.core.$strip>>>;
                 readonly page: z.ZodObject<{
                     total: z.ZodNumber;
                     limit: z.ZodNumber;
@@ -1258,6 +1381,16 @@ export declare const contentBriefListOperation: {
                             readonly markedPublishedAt: null;
                             readonly updatedAt: '2026-08-10T00:00:00.000Z';
                         }];
+                        readonly rows: readonly [{
+                            readonly id: 'brief_01JXYZ';
+                            readonly siteId: 'site_01JXYZ';
+                            readonly keyword: 'nuxt seo';
+                            readonly status: 'ready';
+                            readonly error: null;
+                            readonly generatedAt: '2026-08-10T00:00:00.000Z';
+                            readonly markedPublishedAt: null;
+                            readonly updatedAt: '2026-08-10T00:00:00.000Z';
+                        }];
                         readonly page: {
                             readonly total: 1;
                             readonly limit: 25;
@@ -1940,6 +2073,9 @@ export declare const contentV1Registry: import("./core.js").PublicV1Registry<{
         readonly responses: {
             readonly 200: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
                 data: z.ZodObject<{
+                    /**
+                     * Deprecated alias of `rows`. Kept for one minor version, then removed.
+                     */
                     readonly briefs: z.ZodArray<z.ZodObject<{
                         id: z.ZodString;
                         siteId: z.ZodString;
@@ -1959,6 +2095,25 @@ export declare const contentV1Registry: import("./core.js").PublicV1Registry<{
                         markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
                         updatedAt: z.ZodNullable<z.ZodISODateTime>;
                     }, z.core.$strip>>;
+                    readonly rows: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        siteId: z.ZodString;
+                        keyword: z.ZodString;
+                        status: z.ZodEnum<{
+                            archived: "archived";
+                            failed: "failed";
+                            published: "published";
+                            queued: "queued";
+                            ready: "ready";
+                            researching: "researching";
+                            stale: "stale";
+                            written: "written";
+                        }>;
+                        error: z.ZodNullable<z.ZodString>;
+                        generatedAt: z.ZodNullable<z.ZodISODateTime>;
+                        markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+                        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+                    }, z.core.$strip>>;
                     readonly page: z.ZodObject<{
                         total: z.ZodNumber;
                         limit: z.ZodNumber;
@@ -1991,6 +2146,25 @@ export declare const contentV1Registry: import("./core.js").PublicV1Registry<{
                         markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
                         updatedAt: z.ZodNullable<z.ZodISODateTime>;
                     }, z.core.$strip>>;
+                    readonly rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        siteId: z.ZodString;
+                        keyword: z.ZodString;
+                        status: z.ZodEnum<{
+                            archived: "archived";
+                            failed: "failed";
+                            published: "published";
+                            queued: "queued";
+                            ready: "ready";
+                            researching: "researching";
+                            stale: "stale";
+                            written: "written";
+                        }>;
+                        error: z.ZodNullable<z.ZodString>;
+                        generatedAt: z.ZodNullable<z.ZodISODateTime>;
+                        markedPublishedAt: z.ZodNullable<z.ZodISODateTime>;
+                        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+                    }, z.core.$strip>>>;
                     readonly page: z.ZodObject<{
                         total: z.ZodNumber;
                         limit: z.ZodNumber;
@@ -2102,6 +2276,16 @@ export declare const contentV1Registry: import("./core.js").PublicV1Registry<{
                                 readonly markedPublishedAt: null;
                                 readonly updatedAt: '2026-08-10T00:00:00.000Z';
                             }];
+                            readonly rows: readonly [{
+                                readonly id: 'brief_01JXYZ';
+                                readonly siteId: 'site_01JXYZ';
+                                readonly keyword: 'nuxt seo';
+                                readonly status: 'ready';
+                                readonly error: null;
+                                readonly generatedAt: '2026-08-10T00:00:00.000Z';
+                                readonly markedPublishedAt: null;
+                                readonly updatedAt: '2026-08-10T00:00:00.000Z';
+                            }];
                             readonly page: {
                                 readonly total: 1;
                                 readonly limit: 25;

package/dist/v1/content.js

@@ -123,10 +123,15 @@ const contentBriefPageShape = {
 };
 const contentBriefPageSchema = defineResponseObject(contentBriefPageShape);
 export const contentBriefListDataSchema = defineResponseObject({
+    /**
+     * Deprecated alias of `rows`. Kept for one minor version, then removed.
+     */
     briefs: schema.array(contentBriefSummarySchema.producer),
+    rows: schema.array(contentBriefSummarySchema.producer),
     page: contentBriefPageSchema.producer,
 }, {
     briefs: schema.array(contentBriefSummarySchema.client),
+    rows: schema.array(contentBriefSummarySchema.client).optional(),
     page: contentBriefPageSchema.client,
 });
 export const contentBriefCreateDataSchema = defineResponseObject({
@@ -198,6 +203,16 @@ export const contentBriefListOperation = defineOperation({
                                     markedPublishedAt: null,
                                     updatedAt: '2026-08-10T00:00:00.000Z',
                                 }],
+                            rows: [{
+                                    id: 'brief_01JXYZ',
+                                    siteId: 'site_01JXYZ',
+                                    keyword: 'nuxt seo',
+                                    status: 'ready',
+                                    error: null,
+                                    generatedAt: '2026-08-10T00:00:00.000Z',
+                                    markedPublishedAt: null,
+                                    updatedAt: '2026-08-10T00:00:00.000Z',
+                                }],
                             page: { total: 1, limit: 25, offset: 0, hasMore: false },
                         },
                         meta: { requestId: 'req_01JXYZ', version: '1.0' },

package/dist/v1/core.d.ts

@@ -234,6 +234,55 @@ export declare const publicV1ErrorClientSchema: z.ZodObject<{
     retryable: z.ZodBoolean;
     details: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$loose>;
+/**
+ * One page of a list response.
+ *
+ * Every list operation answers `data.rows` plus `data.page`. One envelope means
+ * a caller reads any list the same way, instead of guessing between `rows`,
+ * `items`, `sites`, `actions`, `briefs` and `clusters`.
+ *
+ * `total` counts the whole result set, not this page. `limit` is the page size
+ * the operation applied, and is 0 when the operation returned no page at all.
+ * `offset` is the index of the first row in `rows`. `hasMore` states whether a
+ * further request returns more rows.
+ *
+ * A producer must emit `rows` and `page`. A client treats both as optional, so
+ * a client newer than the deployed server still parses its answers. Read the
+ * domain key when `rows` is absent.
+ */
+export declare const publicV1PageSchema: CompatibleResponseSchema<z.ZodObject<{
+    readonly total: z.ZodNumber;
+    readonly limit: z.ZodNumber;
+    readonly offset: z.ZodNumber;
+    readonly hasMore: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    readonly total: z.ZodNumber;
+    readonly limit: z.ZodNumber;
+    readonly offset: z.ZodNumber;
+    readonly hasMore: z.ZodBoolean;
+}, z.core.$strip>>;
+/**
+ * Builds the `page` object of a list response, so every operation derives
+ * `hasMore` the same way.
+ *
+ * `total` counts the whole result set. `rowCount` is the number of rows in this
+ * answer. Pass `limit` when a further request can return more rows. If the
+ * operation answers one response only, leave `limit` out: `limit` then reports
+ * the rows returned and `hasMore` is false, even when a display cap holds fewer
+ * rows than `total`. A `hasMore` that no request can act on sends a caller into
+ * a paging loop that never ends.
+ */
+export declare function publicV1Page(input: {
+    total: number;
+    rowCount: number;
+    limit?: number;
+    offset?: number;
+}): {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+};
 export declare const publicV1ErrorEnvelope: CompatibleResponseSchema<z.ZodObject<{
     readonly error: z.ZodObject<{
         code: z.ZodEnum<{

package/dist/v1/core.js

@@ -347,6 +347,45 @@ export const publicV1ErrorClientSchema = z.looseObject({
     retryable: z.boolean(),
     details: publicV1ErrorDetailsSchema,
 });
+/**
+ * One page of a list response.
+ *
+ * Every list operation answers `data.rows` plus `data.page`. One envelope means
+ * a caller reads any list the same way, instead of guessing between `rows`,
+ * `items`, `sites`, `actions`, `briefs` and `clusters`.
+ *
+ * `total` counts the whole result set, not this page. `limit` is the page size
+ * the operation applied, and is 0 when the operation returned no page at all.
+ * `offset` is the index of the first row in `rows`. `hasMore` states whether a
+ * further request returns more rows.
+ *
+ * A producer must emit `rows` and `page`. A client treats both as optional, so
+ * a client newer than the deployed server still parses its answers. Read the
+ * domain key when `rows` is absent.
+ */
+export const publicV1PageSchema = defineResponseObject({
+    total: z.number().int().nonnegative(),
+    limit: z.number().int().nonnegative(),
+    offset: z.number().int().nonnegative(),
+    hasMore: z.boolean(),
+});
+/**
+ * Builds the `page` object of a list response, so every operation derives
+ * `hasMore` the same way.
+ *
+ * `total` counts the whole result set. `rowCount` is the number of rows in this
+ * answer. Pass `limit` when a further request can return more rows. If the
+ * operation answers one response only, leave `limit` out: `limit` then reports
+ * the rows returned and `hasMore` is false, even when a display cap holds fewer
+ * rows than `total`. A `hasMore` that no request can act on sends a caller into
+ * a paging loop that never ends.
+ */
+export function publicV1Page(input) {
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? input.rowCount;
+    const pages = input.limit !== undefined;
+    return { total: input.total, limit, offset, hasMore: pages && offset + input.rowCount < input.total };
+}
 export const publicV1ErrorEnvelope = defineResponseObject({ error: publicV1ErrorProducerSchema }, { error: publicV1ErrorClientSchema });
 export const publicV1MetaProducerSchema = z.strictObject({
     requestId: z.string().min(1),