@zeropress/preview-data-validator 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,10 @@
 # @zeropress/preview-data-validator
 
-Shared validation core for ZeroPress preview data v0.2.
+![npm](https://img.shields.io/npm/v/%40zeropress%2Fpreview-data-validator)
+![license](https://img.shields.io/npm/l/%40zeropress%2Fpreview-data-validator)
+![node](https://img.shields.io/node/v/%40zeropress%2Fpreview-data-validator)
+
+Shared validation core for ZeroPress preview data v0.3.
 
 This package is the canonical runtime contract for preview payloads consumed by:
 
@@ -27,7 +31,7 @@ import {
 Schema export:
 
 ```js
-import schemaUrl from '@zeropress/preview-data-validator/preview-data.v0.2.schema.json';
+import schemaUrl from '@zeropress/preview-data-validator/preview-data.v0.3.schema.json';
 ```
 
 ## API

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@zeropress/preview-data-validator",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared ZeroPress preview data validation core",
   "type": "module",
   "license": "MIT",
   "exports": {
     ".": "./src/index.js",
-    "./preview-data.v0.2.schema.json": "./src/preview-data.v0.2.schema.json"
+    "./preview-data.v0.2.schema.json": "./src/preview-data.v0.2.schema.json",
+    "./preview-data.v0.3.schema.json": "./src/preview-data.v0.3.schema.json"
   },
   "types": "./src/index.d.ts",
   "files": [

package/src/index.d.ts

@@ -61,24 +61,28 @@ export interface PreviewTagData {
   postCount: number;
 }
 
-export interface PreviewRouteBlocks {
+export interface PreviewPaginatedRouteData {
+  path: string;
+  page: number;
+  totalPages: number;
   posts: string;
   pagination: string;
-  categories?: string;
-  tags?: string;
 }
 
-export interface PreviewCategoryRouteData {
+export interface PreviewIndexRouteData extends PreviewPaginatedRouteData {
+  categories: string;
+  tags: string;
+}
+
+export interface PreviewArchiveRouteData extends PreviewPaginatedRouteData {}
+
+export interface PreviewCategoryRouteData extends PreviewPaginatedRouteData {
   slug: string;
-  posts: string;
-  pagination: string;
   categories?: string;
 }
 
-export interface PreviewTagRouteData {
+export interface PreviewTagRouteData extends PreviewPaginatedRouteData {
   slug: string;
-  posts: string;
-  pagination: string;
   tags?: string;
 }
 
@@ -90,17 +94,14 @@ export interface PreviewContentData {
 }
 
 export interface PreviewRoutesData {
-  index: PreviewRouteBlocks & {
-    categories: string;
-    tags: string;
-  };
-  archive: PreviewRouteBlocks;
+  index: PreviewIndexRouteData[];
+  archive: PreviewArchiveRouteData[];
   categories: PreviewCategoryRouteData[];
   tags: PreviewTagRouteData[];
 }
 
-export interface PreviewDataV02 {
-  version: '0.2';
+export interface PreviewDataV03 {
+  version: '0.3';
   generator: string;
   generated_at: string;
   site: PreviewSiteData;
@@ -114,8 +115,8 @@ export interface PreviewDataValidationResult {
   warnings: ValidationIssue[];
 }
 
-export const PREVIEW_DATA_VERSION: '0.2';
+export const PREVIEW_DATA_VERSION: '0.3';
 
 export function validatePreviewData(data: unknown): PreviewDataValidationResult;
 export function assertPreviewData<T>(data: T): T;
-export function isPreviewData(data: unknown): data is PreviewDataV02;
+export function isPreviewData(data: unknown): data is PreviewDataV03;

package/src/index.js

@@ -1,4 +1,4 @@
-export const PREVIEW_DATA_VERSION = '0.2';
+export const PREVIEW_DATA_VERSION = '0.3';
 
 export function validatePreviewData(data) {
   const errors = [];
@@ -6,7 +6,7 @@ export function validatePreviewData(data) {
   validateClosedObject(data, '', errors, ['version', 'generator', 'generated_at', 'site', 'content', 'routes']);
 
   if (!errors.length) {
-    validateLiteral(data.version, '0.2', 'version', 'INVALID_VERSION', errors);
+    validateLiteral(data.version, PREVIEW_DATA_VERSION, 'version', 'INVALID_VERSION', errors);
     validateNonEmptyString(data.generator, 'generator', 'INVALID_GENERATOR', errors);
     validateDateTimeString(data.generated_at, 'generated_at', 'INVALID_GENERATED_AT', errors);
 
@@ -86,13 +86,11 @@ function validateRoutes(routes, path, errors) {
     return;
   }
 
-  validateRouteBlocks(routes.index, `${path}.index`, errors, {
-    requiredKeys: ['posts', 'pagination', 'categories', 'tags'],
-    allowKeys: ['posts', 'pagination', 'categories', 'tags'],
+  validateArray(routes.index, `${path}.index`, 'INVALID_INDEX_ROUTES', errors, (entry, index) => {
+    validateIndexRoute(entry, `${path}.index[${index}]`, errors);
   });
-  validateRouteBlocks(routes.archive, `${path}.archive`, errors, {
-    requiredKeys: ['posts', 'pagination'],
-    allowKeys: ['posts', 'pagination', 'categories', 'tags'],
+  validateArray(routes.archive, `${path}.archive`, 'INVALID_ARCHIVE_ROUTES', errors, (entry, index) => {
+    validateArchiveRoute(entry, `${path}.archive[${index}]`, errors);
   });
   validateArray(routes.categories, `${path}.categories`, 'INVALID_CATEGORY_ROUTES', errors, (entry, index) => {
     validateCategoryRoute(entry, `${path}.categories[${index}]`, errors);
@@ -192,48 +190,61 @@ function validatePreviewTag(tag, path, errors) {
   validateInteger(tag.postCount, `${path}.postCount`, 'INVALID_TAG_POST_COUNT', errors, { minimum: 0 });
 }
 
-function validateCategoryRoute(route, path, errors) {
-  validateClosedObject(route, path, errors, ['slug', 'posts', 'pagination', 'categories']);
-  if (!isObject(route)) {
-    return;
-  }
+function validateIndexRoute(route, path, errors) {
+  validatePaginatedRoute(route, path, errors, {
+    allowedKeys: ['path', 'page', 'totalPages', 'posts', 'pagination', 'categories', 'tags'],
+    requiredKeys: ['path', 'page', 'totalPages', 'posts', 'pagination', 'categories', 'tags'],
+    routeCodePrefix: 'INDEX_ROUTE',
+  });
+}
 
-  validateNonEmptyString(route.slug, `${path}.slug`, 'INVALID_CATEGORY_ROUTE_SLUG', errors);
-  validateString(route.posts, `${path}.posts`, 'INVALID_CATEGORY_ROUTE_POSTS', errors);
-  validateString(route.pagination, `${path}.pagination`, 'INVALID_CATEGORY_ROUTE_PAGINATION', errors);
-  if (route.categories !== undefined) {
-    validateString(route.categories, `${path}.categories`, 'INVALID_CATEGORY_ROUTE_CATEGORIES', errors);
-  }
+function validateArchiveRoute(route, path, errors) {
+  validatePaginatedRoute(route, path, errors, {
+    allowedKeys: ['path', 'page', 'totalPages', 'posts', 'pagination'],
+    requiredKeys: ['path', 'page', 'totalPages', 'posts', 'pagination'],
+    routeCodePrefix: 'ARCHIVE_ROUTE',
+  });
+}
+
+function validateCategoryRoute(route, path, errors) {
+  validatePaginatedRoute(route, path, errors, {
+    allowedKeys: ['path', 'page', 'totalPages', 'slug', 'posts', 'pagination', 'categories'],
+    requiredKeys: ['path', 'page', 'totalPages', 'slug', 'posts', 'pagination'],
+    routeCodePrefix: 'CATEGORY_ROUTE',
+  });
 }
 
 function validateTagRoute(route, path, errors) {
-  validateClosedObject(route, path, errors, ['slug', 'posts', 'pagination', 'tags']);
+  validatePaginatedRoute(route, path, errors, {
+    allowedKeys: ['path', 'page', 'totalPages', 'slug', 'posts', 'pagination', 'tags'],
+    requiredKeys: ['path', 'page', 'totalPages', 'slug', 'posts', 'pagination'],
+    routeCodePrefix: 'TAG_ROUTE',
+  });
+}
+
+function validatePaginatedRoute(route, path, errors, options) {
+  validateClosedObject(route, path, errors, options.allowedKeys);
   if (!isObject(route)) {
     return;
   }
 
-  validateNonEmptyString(route.slug, `${path}.slug`, 'INVALID_TAG_ROUTE_SLUG', errors);
-  validateString(route.posts, `${path}.posts`, 'INVALID_TAG_ROUTE_POSTS', errors);
-  validateString(route.pagination, `${path}.pagination`, 'INVALID_TAG_ROUTE_PAGINATION', errors);
-  if (route.tags !== undefined) {
-    validateString(route.tags, `${path}.tags`, 'INVALID_TAG_ROUTE_TAGS', errors);
-  }
-}
+  validateNonEmptyString(route.path, `${path}.path`, `INVALID_${options.routeCodePrefix}_PATH`, errors);
+  validateInteger(route.page, `${path}.page`, `INVALID_${options.routeCodePrefix}_PAGE`, errors, { minimum: 1 });
+  validateInteger(route.totalPages, `${path}.totalPages`, `INVALID_${options.routeCodePrefix}_TOTAL_PAGES`, errors, { minimum: 1 });
+  validateString(route.posts, `${path}.posts`, `INVALID_${options.routeCodePrefix}_POSTS`, errors);
+  validateString(route.pagination, `${path}.pagination`, `INVALID_${options.routeCodePrefix}_PAGINATION`, errors);
 
-function validateRouteBlocks(blocks, path, errors, options) {
-  validateClosedObject(blocks, path, errors, options.allowKeys);
-  if (!isObject(blocks)) {
-    return;
+  if ('slug' in route) {
+    validateNonEmptyString(route.slug, `${path}.slug`, `INVALID_${options.routeCodePrefix}_SLUG`, errors);
   }
-
-  for (const key of options.requiredKeys) {
-    validateString(blocks[key], `${path}.${key}`, `INVALID_ROUTE_${key.toUpperCase()}`, errors);
+  if (route.categories !== undefined) {
+    validateString(route.categories, `${path}.categories`, `INVALID_${options.routeCodePrefix}_CATEGORIES`, errors);
   }
-
-  for (const key of options.allowKeys) {
-    if (blocks[key] !== undefined) {
-      validateString(blocks[key], `${path}.${key}`, `INVALID_ROUTE_${key.toUpperCase()}`, errors);
-    }
+  if (route.tags !== undefined) {
+    validateString(route.tags, `${path}.tags`, `INVALID_${options.routeCodePrefix}_TAGS`, errors);
+  }
+  if (Number.isInteger(route.page) && Number.isInteger(route.totalPages) && route.page > route.totalPages) {
+    errors.push(issue(`INVALID_${options.routeCodePrefix}_PAGE`, `${path}.page`, 'Page cannot exceed totalPages'));
   }
 }
 
@@ -267,12 +278,10 @@ function validateClosedObject(value, path, errors, allowedKeys) {
 
 function isOptionalKey(path, key) {
   if (path === 'site') return key === 'logo' || key === 'social';
-  if (path.endsWith('.index')) return false;
-  if (path.endsWith('.archive')) return key === 'categories' || key === 'tags';
-  if (path.includes('categories[')) return key === 'categories';
-  if (path.includes('tags[')) return key === 'tags';
-  if (path.includes('.posts[')) return key === 'author_avatar' || key === 'featured_image';
-  if (path.includes('.categories[')) return key === 'description';
+  if (path.startsWith('content.posts[')) return key === 'author_avatar' || key === 'featured_image';
+  if (path.startsWith('content.categories[')) return key === 'description';
+  if (path.startsWith('routes.categories[')) return key === 'categories';
+  if (path.startsWith('routes.tags[')) return key === 'tags';
   return false;
 }
 
@@ -282,9 +291,9 @@ function validateObject(value, path, code, errors) {
   }
 }
 
-function validateLiteral(value, expected, path, code, errors) {
-  if (value !== expected) {
-    errors.push(issue(code, path, `Expected '${expected}'`));
+function validateLiteral(value, literal, path, code, errors) {
+  if (value !== literal) {
+    errors.push(issue(code, path, `Expected literal value "${literal}"`));
   }
 }
 
@@ -305,8 +314,9 @@ function validateInteger(value, path, code, errors, options = {}) {
     errors.push(issue(code, path, 'Expected an integer'));
     return;
   }
+
   if (options.minimum !== undefined && value < options.minimum) {
-    errors.push(issue(code, path, `Expected an integer >= ${options.minimum}`));
+    errors.push(issue(code, path, `Expected integer >= ${options.minimum}`));
   }
 }
 
@@ -316,35 +326,31 @@ function validateEnum(value, path, code, errors, allowedValues) {
   }
 }
 
-function validateUri(value, path, code, errors) {
+function validateDateTimeString(value, path, code, errors) {
   if (typeof value !== 'string' || value.trim() === '') {
-    errors.push(issue(code, path, 'Expected a URI string'));
+    errors.push(issue(code, path, 'Expected a date-time string'));
     return;
   }
 
-  try {
-    new URL(value);
-  } catch {
-    errors.push(issue(code, path, 'Expected a valid URI'));
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    errors.push(issue(code, path, 'Expected a valid date-time string'));
   }
 }
 
-function validateDateTimeString(value, path, code, errors) {
+function validateUri(value, path, code, errors) {
   if (typeof value !== 'string' || value.trim() === '') {
-    errors.push(issue(code, path, 'Expected an ISO date-time string'));
+    errors.push(issue(code, path, 'Expected a URI string'));
     return;
   }
 
-  const parsed = Date.parse(value);
-  if (Number.isNaN(parsed)) {
-    errors.push(issue(code, path, 'Expected a valid ISO date-time string'));
+  try {
+    new URL(value);
+  } catch {
+    errors.push(issue(code, path, 'Expected a valid URI'));
   }
 }
 
-function isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 function issue(code, path, message) {
   return {
     code,
@@ -353,3 +359,7 @@ function issue(code, path, message) {
     severity: 'error',
   };
 }
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/preview-data.v0.3.schema.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zeropress.dev/schemas/preview-data.v0.3.schema.json",
+  "title": "ZeroPress Theme Preview Data v0.3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generator", "generated_at", "site", "content", "routes"],
+  "properties": {
+    "version": {
+      "const": "0.3"
+    },
+    "generator": {
+      "type": "string",
+      "minLength": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "site": {
+      "$ref": "#/$defs/site"
+    },
+    "content": {
+      "$ref": "#/$defs/content"
+    },
+    "routes": {
+      "$ref": "#/$defs/routes"
+    }
+  },
+  "$defs": {
+    "site": {
+      "type": "object",
+      "required": ["title", "description", "url", "language"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "url": { "type": "string", "format": "uri" },
+        "language": { "type": "string", "minLength": 2 },
+        "logo": { "type": "string", "format": "uri" },
+        "social": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "previewPost": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "public_id",
+        "title",
+        "slug",
+        "html",
+        "excerpt",
+        "published_at",
+        "updated_at",
+        "published_at_iso",
+        "updated_at_iso",
+        "reading_time",
+        "author_name",
+        "categories_html",
+        "tags_html",
+        "comments_html",
+        "status"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "public_id": { "type": "integer", "minimum": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "minLength": 1 },
+        "html": { "type": "string" },
+        "excerpt": { "type": "string" },
+        "published_at": { "type": "string" },
+        "updated_at": { "type": "string" },
+        "published_at_iso": { "type": "string", "format": "date-time" },
+        "updated_at_iso": { "type": "string", "format": "date-time" },
+        "reading_time": { "type": "string", "minLength": 1 },
+        "author_name": { "type": "string", "minLength": 1 },
+        "author_avatar": { "type": "string", "format": "uri" },
+        "featured_image": { "type": "string", "format": "uri" },
+        "categories_html": { "type": "string" },
+        "tags_html": { "type": "string" },
+        "comments_html": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["published", "draft"]
+        }
+      }
+    },
+    "previewPage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "slug", "html", "status"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "minLength": 1 },
+        "html": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["published", "draft"]
+        }
+      }
+    },
+    "previewCategory": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "slug", "postCount"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "postCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "previewTag": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "slug", "postCount"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "minLength": 1 },
+        "postCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "content": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["posts", "pages", "categories", "tags"],
+      "properties": {
+        "posts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/previewPost" }
+        },
+        "pages": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/previewPage" }
+        },
+        "categories": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/previewCategory" }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/previewTag" }
+        }
+      }
+    },
+    "paginatedRouteBase": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "page", "totalPages", "posts", "pagination"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "page": { "type": "integer", "minimum": 1 },
+        "totalPages": { "type": "integer", "minimum": 1 },
+        "posts": { "type": "string" },
+        "pagination": { "type": "string" },
+        "categories": { "type": "string" },
+        "tags": { "type": "string" },
+        "slug": { "type": "string", "minLength": 1 }
+      }
+    },
+    "indexRoute": {
+      "allOf": [
+        { "$ref": "#/$defs/paginatedRouteBase" },
+        { "required": ["path", "page", "totalPages", "posts", "pagination", "categories", "tags"] }
+      ]
+    },
+    "archiveRoute": {
+      "allOf": [
+        { "$ref": "#/$defs/paginatedRouteBase" },
+        { "required": ["path", "page", "totalPages", "posts", "pagination"] }
+      ]
+    },
+    "categoryRoute": {
+      "allOf": [
+        { "$ref": "#/$defs/paginatedRouteBase" },
+        { "required": ["path", "page", "totalPages", "slug", "posts", "pagination"] }
+      ]
+    },
+    "tagRoute": {
+      "allOf": [
+        { "$ref": "#/$defs/paginatedRouteBase" },
+        { "required": ["path", "page", "totalPages", "slug", "posts", "pagination"] }
+      ]
+    },
+    "routes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["index", "archive", "categories", "tags"],
+      "properties": {
+        "index": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/indexRoute" }
+        },
+        "archive": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/archiveRoute" }
+        },
+        "categories": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/categoryRoute" }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/tagRoute" }
+        }
+      }
+    }
+  }
+}