npm package: @opencommerceprotocol/validator
Description: Open Commerce Protocol — Validation library and conformance tests
Latest version: 1.0.0

# @opencommerceprotocol/validator

Validation library for the [Open Commerce Protocol](https://opencommerceprotocol.org). Validates OCP manifests, product feeds, `robots.txt`, `llms.txt`, and scores `agent_notes` quality.

## Installation

```bash
npm install @opencommerceprotocol/validator
```

## `OCPValidator`

Validate a live site or a local directory.

```typescript
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`

```typescript
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`

```typescript
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

```typescript
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`

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

## `llms.txt` Validation

```typescript
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`

```typescript
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.

```typescript
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`

```typescript
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:

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