@ucptools/validator 1.0.0

package/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+UCP Profile Manager is a toolkit for validating and generating UCP (Universal Commerce Protocol) Business Profiles - an open standard enabling AI agents to discover, browse, and complete purchases on UCP-enabled merchants. The project includes a core library, REST API, CLI tools, web UI, and Apify actor integration.
+
+**Live deployment:** https://ucptools.dev
+
+## Commands
+
+```bash
+# Development
+npm run dev           # Watch mode Express server (tsx watch src/api/server.ts)
+npm run build         # TypeScript compilation
+npm start             # Production server (node dist/api/server.js)
+
+# Testing
+npm test              # Vitest tests (30s timeout, v8 coverage)
+
+# Linting
+npm run lint          # ESLint on src/**/*.ts
+
+# CLI tools
+npm run validate      # Run validator CLI (tsx src/cli/index.ts)
+npm run generate      # Run generator CLI (tsx src/cli/generate.ts)
+
+# Database (Drizzle + PostgreSQL)
+npm run db:generate   # Generate Drizzle schema
+npm run db:migrate    # Apply migrations
+npm run db:push       # Push schema to DB
+npm run db:studio     # Open Drizzle Studio
+```
+
+## Architecture
+
+### Core Library (`/src/`)
+
+**Validator (`/src/validator/`)** - Four validation levels:
+- `structural-validator.ts` - JSON structure, required fields, version format (YYYY-MM-DD)
+- `rules-validator.ts` - UCP compliance (namespace/origin binding, extension chains, HTTPS endpoints, signing keys)
+- `network-validator.ts` - Remote schema fetching/verification, self-describing schema validation
+- `sdk-validator.ts` - Integration with @ucp-js/sdk for official UCP compliance
+- `index.ts` - Orchestrator exposing `validateProfile()`, `validateRemote()`, `validateQuick()`, `validateJsonString()`
+
+**Generator (`/src/generator/`)** - Profile generation:
+- `profile-builder.ts` - `buildProfile()` for full profiles, `generateMinimalProfile()` for checkout-only
+- `key-generator.ts` - Ed25519/ES256 signing key generation (`generateSigningKeyPair()`)
+
+**Simulator (`/src/simulator/`)** - AI agent interaction simulation:
+- `agent-simulator.ts` - Tests real-world functionality: discovery flow, capability inspection, checkout simulation
+- Not just spec compliance - simulates actual agent workflows
+
+**Hosting (`/src/hosting/`)** - Platform-specific deployment configs:
+- `artifacts-generator.ts` - Generates installation artifacts for Nginx, Apache, Vercel, Netlify, Cloudflare Workers, S3+CloudFront
+
+### API & Deployment
+
+**Express API (`/src/api/server.ts`)** - REST endpoints:
+- `POST /v1/profiles/validate`, `/validate-quick`, `/validate-remote`, `/validate-json`
+- `POST /v1/profiles/generate`, `/generate-minimal`
+- `POST /v1/hosting/artifacts`
+
+**Vercel Serverless (`/api/`)** - Edge functions for ucptools.dev
+
+**Database (`/src/db/`)** - Drizzle ORM with PostgreSQL (Neon):
+- Schema: merchants (directory), benchmarkStats, benchmarkSummary
+- Service: `/src/services/directory.ts` - merchant CRUD, filtering, stats
+
+### Types (`/src/types/`)
+- `ucp-profile.ts` - UCP specification types
+- `validation.ts` - ValidationReport, ValidationIssue interfaces
+- `generator.ts` - Generator input/output types
+
+## Key Patterns
+
+**Validation Issue Structure:**
+```typescript
+{
+  severity: 'error' | 'warn' | 'info',
+  code: string,        // e.g., 'UCP_NS_ORIGIN_MISMATCH'
+  path: string,        // JSON path, e.g., '$.ucp.capabilities[0]'
+  message: string,
+  hint?: string        // Fix suggestion
+}
+```
+
+**Error Codes:** `UCP_MISSING_ROOT`, `UCP_MISSING_VERSION`, `UCP_INVALID_VERSION_FORMAT`, `UCP_NS_ORIGIN_MISMATCH`, `UCP_ORPHANED_EXTENSION`, `UCP_ENDPOINT_NOT_HTTPS`, `UCP_ENDPOINT_TRAILING_SLASH`, `UCP_MISSING_SIGNING_KEYS`, `UCP_SCHEMA_FETCH_FAILED`
+
+## Environment Variables
+
+```
+DATABASE_URL    # PostgreSQL connection string (Neon)
+NODE_ENV        # development | production
+PORT            # API port (default: 3000)
+LOG_LEVEL       # Pino log level (default: info)
+```
+
+## Tech Stack
+
+- **Runtime:** Node.js 20+, TypeScript 5.6, ES2022 target
+- **API:** Express 4.21
+- **Database:** PostgreSQL via @neondatabase/serverless, Drizzle ORM
+- **Validation:** AJV 8.17 (JSON Schema), Zod 3.23, @ucp-js/sdk 0.1
+- **Crypto:** jose (JWT/JWK), Ed25519 signing
+- **CLI:** Commander 12, Chalk 5
+- **Testing:** Vitest
+- **Deployment:** Vercel

package/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to @ucptools/validator
+
+Thank you for your interest in contributing to the UCP Validator! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. Check if the bug has already been reported in [Issues](https://github.com/Nolpak14/ucp-tools/issues)
+2. If not, create a new issue with:
+   - A clear, descriptive title
+   - Steps to reproduce the issue
+   - Expected vs actual behavior
+   - Your environment (Node.js version, OS)
+   - Sample UCP profile if applicable
+
+### Suggesting Features
+
+1. Check existing issues for similar suggestions
+2. Create a new issue with the `enhancement` label
+3. Describe the feature and its use case
+4. Explain how it benefits UCP profile validation/generation
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature-name`
+3. Make your changes
+4. Run tests: `npm test`
+5. Run linting: `npm run lint`
+6. Commit with a clear message describing your changes
+7. Push to your fork and submit a pull request
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/ucp-tools.git
+cd ucp-tools
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run in development mode
+npm run dev
+```
+
+## Project Structure
+
+```
+src/
+  types/        # TypeScript type definitions
+  validator/    # Validation logic (structural, rules, network, SDK)
+  generator/    # Profile and key generation
+  simulator/    # AI agent simulation
+  hosting/      # Deployment artifact generation
+  api/          # Express REST API
+  cli/          # Command-line tools
+  db/           # Database schema and services
+examples/       # Sample UCP profiles
+```
+
+## Coding Standards
+
+- Use TypeScript for all new code
+- Follow existing code style (enforced by ESLint)
+- Add JSDoc comments for public APIs
+- Write tests for new functionality
+- Keep functions focused and single-purpose
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run specific test file
+npm test -- src/validator/structural-validator.test.ts
+```
+
+## Validation Error Codes
+
+When adding new validation rules, follow the existing pattern:
+
+```typescript
+{
+  severity: 'error' | 'warn' | 'info',
+  code: 'UCP_YOUR_ERROR_CODE',  // Prefix with UCP_
+  path: '$.ucp.path.to.issue',   // JSON path format
+  message: 'Clear description of the issue',
+  hint: 'Suggestion to fix the issue'  // Optional
+}
+```
+
+## Questions?
+
+- Open an issue for general questions
+- Check [ucptools.dev](https://ucptools.dev) for documentation
+- Review the [UCP Specification](https://ucp.dev/specification/overview/)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UCP.tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @ucptools/validator
+
+[![npm version](https://img.shields.io/npm/v/@ucptools/validator)](https://www.npmjs.com/package/@ucptools/validator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Validate and generate UCP (Universal Commerce Protocol) Business Profiles** for AI-powered shopping agents like ChatGPT, Google AI Mode, and Copilot checkout.
+
+> **Try it online:** [ucptools.dev](https://ucptools.dev) - Free AI Commerce Readiness Checker
+
+---
+
+## What is UCP?
+
+The [Universal Commerce Protocol](https://ucp.dev) is an open standard enabling AI agents to discover, browse, and complete purchases on any UCP-enabled merchant. Google announced UCP on January 11, 2026, with support from Shopify, Target, Walmart, and 20+ ecosystem partners.
+
+This library helps you:
+- **Validate** your UCP profile for compliance
+- **Generate** properly formatted UCP profiles
+- **Verify** schemas and capability declarations
+
+---
+
+## Installation
+
+```bash
+npm install @ucptools/validator
+```
+
+---
+
+## Quick Start
+
+### Validate a Profile
+
+```typescript
+import { validateProfile, validateQuick, validateRemote } from '@ucptools/validator';
+
+// Validate a local profile object
+const report = await validateProfile(myProfile);
+console.log(report.ok ? 'Valid!' : 'Issues found:', report.issues);
+
+// Quick validation (no network calls)
+const quickReport = validateQuick(myProfile);
+
+// Validate a remote profile by domain
+const remoteReport = await validateRemote('example.com');
+```
+
+### Generate a Profile
+
+```typescript
+import { buildProfile, generateMinimalProfile } from '@ucptools/validator';
+
+// Generate a minimal profile (checkout only)
+const minimal = generateMinimalProfile({
+  endpoint: 'https://api.yourstore.com/ucp/v1',
+});
+
+// Generate a full profile
+const result = await buildProfile({
+  merchant: {
+    merchantId: 'store-123',
+    primaryDomain: 'yourstore.com',
+  },
+  transport: {
+    rest: { endpoint: 'https://api.yourstore.com/ucp/v1' },
+  },
+  capabilities: {
+    checkout: true,
+    order: true,
+    fulfillment: false,
+    discount: false,
+    product: false,
+    inventory: false,
+  },
+});
+
+console.log(result.profileJson);
+```
+
+### Generate Signing Keys
+
+```typescript
+import { generateSigningKeyPair } from '@ucptools/validator';
+
+// Generate Ed25519 key pair for Order capability
+const { publicKey, privateKey, kid } = await generateSigningKeyPair('Ed25519');
+```
+
+---
+
+## Validation Levels
+
+### 1. Structural Validation (Fast, Offline)
+- JSON structure verification
+- Required fields check
+- Version format validation (YYYY-MM-DD)
+
+### 2. UCP Rules Validation (Offline)
+- Namespace/origin binding (`dev.ucp.*` must use `ucp.dev` URLs)
+- Extension chain validation (no orphaned `extends`)
+- Endpoint rules (HTTPS, no trailing slash)
+- Signing keys requirement for Order capability
+
+### 3. Network Validation (Online)
+- Fetch and verify remote schemas
+- Self-describing schema validation
+- Schema/capability version matching
+
+---
+
+## Validation Report
+
+```typescript
+interface ValidationReport {
+  ok: boolean;                    // true if no errors
+  profile_url?: string;           // URL of validated profile
+  ucp_version?: string;           // UCP version from profile
+  issues: ValidationIssue[];      // Array of issues found
+  validated_at: string;           // ISO timestamp
+  validation_mode: ValidationMode;
+}
+
+interface ValidationIssue {
+  severity: 'error' | 'warn' | 'info';
+  code: string;                   // e.g., 'UCP_NS_ORIGIN_MISMATCH'
+  path: string;                   // JSON path, e.g., '$.ucp.capabilities[0]'
+  message: string;
+  hint?: string;                  // Suggestion to fix
+}
+```
+
+---
+
+## Error Codes
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| `UCP_MISSING_ROOT` | error | Missing `ucp` object at root |
+| `UCP_MISSING_VERSION` | error | Missing version field |
+| `UCP_INVALID_VERSION_FORMAT` | error | Version not in YYYY-MM-DD format |
+| `UCP_NS_ORIGIN_MISMATCH` | error | Schema URL doesn't match namespace origin |
+| `UCP_ORPHANED_EXTENSION` | error | Extends references non-existent capability |
+| `UCP_ENDPOINT_NOT_HTTPS` | error | Endpoint must use HTTPS |
+| `UCP_ENDPOINT_TRAILING_SLASH` | warn | Remove trailing slash from endpoint |
+| `UCP_MISSING_SIGNING_KEYS` | error | Order capability requires signing_keys |
+| `UCP_SCHEMA_FETCH_FAILED` | warn | Could not fetch remote schema |
+
+---
+
+## CLI Usage
+
+```bash
+# Validate a local file
+npx @ucptools/validator validate -f ucp.json
+
+# Validate a remote profile
+npx @ucptools/validator validate -r yourstore.com
+
+# Generate a minimal profile
+npx @ucptools/validator generate-minimal -e https://api.example.com/ucp/v1 -o ucp.json
+```
+
+---
+
+## Online Tool
+
+Don't want to install anything? Use our free online tool:
+
+**[ucptools.dev](https://ucptools.dev)** - AI Commerce Readiness Checker
+
+- Validates UCP profiles + Schema.org requirements
+- Generates UCP profiles with a simple form
+- Creates Schema.org snippets (MerchantReturnPolicy, shippingDetails)
+- Provides A-F grading and actionable recommendations
+
+---
+
+## Resources
+
+- [UCP Specification](https://ucp.dev/specification/overview/)
+- [UCP GitHub Repository](https://github.com/Universal-Commerce-Protocol/ucp)
+- [Google UCP Business Profile Guide](https://developers.google.com/merchant/ucp/guides/business-profile)
+- [UCP JavaScript SDK](https://github.com/Universal-Commerce-Protocol/js-sdk)
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+---
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  Built with love for the AI Commerce ecosystem<br>
+  <a href="https://ucptools.dev">ucptools.dev</a>
+</p>

package/api/analyze-feed.js

@@ -0,0 +1,140 @@
+/**
+ * Vercel Serverless Function: Product Feed Quality Analyzer
+ * POST /api/analyze-feed
+ *
+ * Analyzes product feed quality for AI agent visibility.
+ *
+ * Request body:
+ *   {
+ *     "url": "https://example.com/products",
+ *     "maxProducts": 50,
+ *     "includeProductDetails": true
+ *   }
+ *
+ * GET /api/analyze-feed?url=https://example.com/products
+ *   Quick analysis with default options.
+ */
+
+export default async function handler(req, res) {
+    // Handle CORS
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+        return res.status(200).end();
+    }
+
+    // Extract URL from query (GET) or body (POST)
+    let url;
+    let maxProducts = 50;
+    let includeProductDetails = true;
+
+    if (req.method === 'GET') {
+        url = req.query.url;
+        if (req.query.maxProducts) {
+            maxProducts = parseInt(req.query.maxProducts, 10);
+        }
+        if (req.query.includeProductDetails === 'false') {
+            includeProductDetails = false;
+        }
+    } else if (req.method === 'POST') {
+        const body = req.body || {};
+        url = body.url;
+        maxProducts = body.maxProducts || 50;
+        includeProductDetails = body.includeProductDetails !== false;
+    } else {
+        return res.status(405).json({
+            error: 'Method not allowed',
+            message: 'Use GET or POST to analyze a product feed',
+        });
+    }
+
+    // Validate URL
+    if (!url) {
+        return res.status(400).json({
+            error: 'Missing URL',
+            message: 'Please provide a URL to analyze',
+        });
+    }
+
+    try {
+        new URL(url);
+    } catch {
+        return res.status(400).json({
+            error: 'Invalid URL',
+            message: 'Please provide a valid URL',
+        });
+    }
+
+    // Validate maxProducts
+    if (maxProducts < 1 || maxProducts > 100) {
+        return res.status(400).json({
+            error: 'Invalid maxProducts',
+            message: 'maxProducts must be between 1 and 100',
+        });
+    }
+
+    try {
+        // Fetch the page content
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30000);
+
+        const response = await fetch(url, {
+            headers: {
+                'User-Agent': 'UCP-Tools Feed Analyzer/1.0 (https://ucp.day)',
+                'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+            },
+            signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+            return res.status(400).json({
+                error: 'Failed to fetch URL',
+                message: `Server returned ${response.status}: ${response.statusText}`,
+            });
+        }
+
+        const html = await response.text();
+
+        // Import and run the analyzer
+        const { analyzeProductFeedFromHtml } = await import('../src/feed-analyzer/index.js');
+
+        const result = analyzeProductFeedFromHtml(html, url, {
+            maxProducts,
+            includeProductDetails,
+        });
+
+        // Check if any products were found
+        if (result.productsFound === 0) {
+            return res.status(200).json({
+                success: true,
+                warning: 'No products found',
+                message: 'No Schema.org Product markup was found on this page. Make sure your page includes JSON-LD structured data with @type: "Product".',
+                ...result,
+            });
+        }
+
+        return res.status(200).json({
+            success: true,
+            ...result,
+        });
+
+    } catch (error) {
+        console.error('Feed analysis error:', error);
+
+        if (error.name === 'AbortError') {
+            return res.status(408).json({
+                error: 'Request timeout',
+                message: 'The request took too long. The target server may be slow or unresponsive.',
+            });
+        }
+
+        return res.status(500).json({
+            error: 'Analysis failed',
+            message: error.message || 'An unexpected error occurred',
+        });
+    }
+}