@opencommerceprotocol/validator

Validation library for the Open Commerce Protocol. Validates OCP manifests, product feeds, robots.txt, llms.txt, and scores agent_notes quality.

Installation

npm install @opencommerceprotocol/validator

OCPValidator

Validate a live site or a local directory.

import { OCPValidator } from '@opencommerceprotocol/validator';

const validator = new OCPValidator();

// Validate a live site
const result = await validator.validateRemote('https://mystore.com');
console.log(`Score: ${result.score}/100`);
console.log(`Passed: ${result.passed}`);

// Validate a local directory (for CI/CD)
const localResult = await validator.validateLocal('./public');

SiteValidationResult

interface SiteValidationResult {
  url: string;
  passed: boolean;
  score: number;           // 0-100 overall score
  manifest?: ValidationResult;
  feed?: FeedValidationResult;
  robots?: RobotsTxtValidationResult;
  llmstxt?: LlmsTxtValidationResult;
  errors: ValidationError[];
  warnings: ValidationError[];
}

ValidationResult

interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationError[];
  data?: unknown;  // parsed manifest/product if valid
}

interface ValidationError {
  path: string;
  message: string;
  severity: 'error' | 'warning';
}

Robots.txt Validation

import { validateRobotsTxt, parseRobotsTxtForOcp } from '@opencommerceprotocol/validator';

const robotsContent = `
User-agent: *
Allow: /

OCP-Manifest: https://mystore.com/.well-known/ocp.json
`;

const result = validateRobotsTxt(robotsContent);
// { valid: true, hasOCPManifest: true, manifestUrl: 'https://...', errors: [] }

// Parse to extract OCP-specific info
const parsed = parseRobotsTxtForOcp(robotsContent);
// { manifestUrl: 'https://...', isAllowed: true }

RobotsTxtValidationResult

interface RobotsTxtValidationResult {
  valid: boolean;
  hasOCPManifest: boolean;
  manifestUrl?: string;
  errors: string[];
}

llms.txt Validation

import { validateLlmsTxt, parseLlmsTxtForOcp } from '@opencommerceprotocol/validator';

const llmsContent = `# My Store

> Sell products online

## Commerce

- Products: https://mystore.com/ocp/products.jsonl
- Manifest: https://mystore.com/.well-known/ocp.json
`;

const result = validateLlmsTxt(llmsContent);
// { valid: true, hasCommerceSection: true, errors: [] }

const parsed = parseLlmsTxtForOcp(llmsContent);
// { feedUrl: 'https://...', manifestUrl: 'https://...' }

LlmsTxtValidationResult

interface LlmsTxtValidationResult {
  valid: boolean;
  hasCommerceSection: boolean;
  errors: string[];
}

agent_notes Quality Scoring

Score the quality of a product's agent_notes field on a 0–100 scale.

import { scoreAgentNotes, validateAgentNotesBatch } from '@opencommerceprotocol/validator';

// Score a single product's agent_notes
const result = scoreAgentNotes(
  'Best-seller. Ideal for frequent flyers. 30-hour battery. Folds flat. Bluetooth 5.0.'
);
// {
//   score: 82,
//   dimensions: {
//     length: { score: 90, feedback: 'Good length' },
//     specificity: { score: 85, feedback: 'Contains specific details' },
//     actionability: { score: 75, feedback: 'Provides useful context' },
//     completeness: { score: 78, feedback: 'Covers key attributes' },
//   },
//   suggestions: ['Consider adding size/fit information'],
// }

// Batch score an entire product catalog
const products = [
  { id: 'prod-1', agent_notes: 'Great product with good features...' },
  { id: 'prod-2', agent_notes: undefined },
];
const batchResult = validateAgentNotesBatch(products);
// {
//   averageScore: 45,
//   coverage: 0.5,  // 50% of products have agent_notes
//   scores: [{ id: 'prod-1', score: 90 }, { id: 'prod-2', score: 0 }],
//   topIssues: ['50% of products are missing agent_notes'],
// }

AgentNotesQualityResult

interface AgentNotesQualityResult {
  score: number;     // 0-100
  dimensions: {
    length: { score: number; feedback: string };
    specificity: { score: number; feedback: string };
    actionability: { score: number; feedback: string };
    completeness: { score: number; feedback: string };
  };
  suggestions: string[];
}

interface AgentNotesBatchResult {
  averageScore: number;
  coverage: number;       // 0-1, fraction of products with agent_notes
  scores: Array<{ id: string; score: number }>;
  topIssues: string[];
}

Score Interpretation

| Score | Meaning | |-------|---------| | 80–100 | Excellent — agent-ready | | 60–79 | Good — minor improvements possible | | 40–59 | Fair — significant gaps | | 0–39 | Poor — needs major work |

CLI

For command-line validation, use the @opencommerceprotocol/cli package:

npx @opencommerceprotocol/cli validate https://mystore.com
npx @opencommerceprotocol/cli validate ./public  # local directory