@nuxtseo/protocol 0.2.1 → 0.4.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(),
@@ -69,6 +76,7 @@ export const recoverableBacklinksOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',
@@ -108,6 +116,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 +172,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);
@@ -177,6 +212,7 @@ export const mentionsListOperation = defineOperation({
         'auth_expired',
         'forbidden',
         'not_found',
+        'conflict',
         'rate_limited',
         'contract_violation',
         'internal_error',
@@ -217,6 +253,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/core.d.ts

@@ -20,7 +20,7 @@ export declare const publicV1StandardRatePolicy: {
 export declare const PUBLIC_V1_FEATURES: readonly ['account', 'actions', 'analytics', 'audit', 'backlinks', 'content', 'mentions', 'page', 'research', 'sites', 'timeline'];
 export declare const PUBLIC_V1_METHODS: readonly ['DELETE', 'GET', 'PATCH', 'POST'];
 export declare const PUBLIC_V1_CREDENTIALS: readonly ['api_token', 'session'];
-export declare const PUBLIC_V1_SCOPES: readonly ['account:read', 'actions:read', 'actions:write', 'analytics:read', 'audit:read', 'content:read', 'content:write', 'feedback:write', 'page:read', 'page:write', 'research:read', 'research:write', 'sites:read', 'sites:write', 'timeline:read', 'timeline:write'];
+export declare const PUBLIC_V1_SCOPES: readonly ['account:read', 'actions:read', 'actions:write', 'analytics:read', 'audit:read', 'feedback:write', 'page:read', 'page:write', 'research:read', 'research:write', 'sites:read', 'sites:write', 'timeline:read', 'timeline:write'];
 export declare const PUBLIC_V1_ROLES: readonly ['viewer', 'member', 'admin', 'owner'];
 export declare const PUBLIC_V1_ERROR_CODES: readonly ['invalid_request', 'unauthorized', 'forbidden', 'not_found', 'site_ambiguous', 'auth_expired', 'entitlement_required', 'quota_exhausted', 'provider_unavailable', 'stale_evidence', 'conflict', 'rate_limited', 'contract_violation', 'internal_error'];
 export declare const PUBLIC_V1_ERROR_STATUS: {
@@ -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` 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

@@ -40,8 +40,6 @@ export const PUBLIC_V1_SCOPES = [
     'actions:write',
     'analytics:read',
     'audit:read',
-    'content:read',
-    'content:write',
     'feedback:write',
     'page:read',
     'page:write',
@@ -347,6 +345,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` 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),