@ucptools/validator 1.0.0

package/src/feed-analyzer/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Product Feed Quality Analyzer Module
+ * Deep analysis of product data quality for AI agent visibility
+ */
+
+export {
+    analyzeProductFeed,
+    analyzeProductFeedFromHtml,
+    analyzeProduct,
+    extractProductsFromHtml,
+    validateGtin,
+} from './feed-analyzer.js';
+
+export type {
+    ProductData,
+    ProductOffer,
+    ProductAnalysis,
+    QualityCheck,
+    FeedAnalysisResult,
+    FeedAnalysisInput,
+    CategoryScores,
+    Recommendation,
+    FeedSummary,
+    GtinValidation,
+    IssueSeverity,
+    CheckCategory,
+} from './types.js';
+
+export {
+    QUALITY_CHECKS,
+    VALID_AVAILABILITY_VALUES,
+    CATEGORY_WEIGHTS,
+    GRADE_THRESHOLDS,
+} from './types.js';

package/src/feed-analyzer/types.ts

@@ -0,0 +1,354 @@
+/**
+ * Product Feed Quality Analyzer Types
+ * Deep analysis of product data quality for AI agent visibility
+ */
+
+/**
+ * Severity levels for feed issues
+ */
+export type IssueSeverity = 'critical' | 'warning' | 'info';
+
+/**
+ * Categories of feed quality checks
+ */
+export type CheckCategory =
+    | 'completeness'
+    | 'identifiers'
+    | 'images'
+    | 'pricing'
+    | 'descriptions'
+    | 'categories'
+    | 'availability';
+
+/**
+ * Individual product data from Schema.org JSON-LD
+ */
+export interface ProductData {
+    name?: string;
+    description?: string;
+    sku?: string;
+    gtin?: string;
+    gtin8?: string;
+    gtin12?: string;
+    gtin13?: string;
+    gtin14?: string;
+    mpn?: string;
+    brand?: string | { name?: string };
+    image?: string | string[] | { url?: string }[];
+    offers?: ProductOffer | ProductOffer[];
+    category?: string;
+    color?: string;
+    size?: string;
+    material?: string;
+    weight?: string | { value?: number; unitCode?: string };
+    aggregateRating?: {
+        ratingValue?: number;
+        reviewCount?: number;
+        ratingCount?: number;
+    };
+    review?: unknown[];
+    url?: string;
+    '@type'?: string;
+}
+
+/**
+ * Product offer/pricing data
+ */
+export interface ProductOffer {
+    '@type'?: string;
+    price?: number | string;
+    priceCurrency?: string;
+    availability?: string;
+    url?: string;
+    seller?: { name?: string };
+    priceValidUntil?: string;
+    itemCondition?: string;
+    shippingDetails?: unknown;
+}
+
+/**
+ * Individual quality check result
+ */
+export interface QualityCheck {
+    id: string;
+    name: string;
+    category: CheckCategory;
+    passed: boolean;
+    severity: IssueSeverity;
+    message: string;
+    details?: string;
+    recommendation?: string;
+    affectedProducts?: string[];
+}
+
+/**
+ * Product-level analysis result
+ */
+export interface ProductAnalysis {
+    name: string;
+    url?: string;
+    sku?: string;
+    score: number;
+    issues: QualityCheck[];
+    attributes: {
+        hasName: boolean;
+        hasDescription: boolean;
+        hasSku: boolean;
+        hasGtin: boolean;
+        hasBrand: boolean;
+        hasImage: boolean;
+        hasPrice: boolean;
+        hasAvailability: boolean;
+        hasCategory: boolean;
+        descriptionLength: number;
+        imageCount: number;
+    };
+}
+
+/**
+ * Category scores breakdown
+ */
+export interface CategoryScores {
+    completeness: number;
+    identifiers: number;
+    images: number;
+    pricing: number;
+    descriptions: number;
+    categories: number;
+    availability: number;
+}
+
+/**
+ * Overall feed analysis result
+ */
+export interface FeedAnalysisResult {
+    url: string;
+    analyzedAt: string;
+    productsFound: number;
+    productsAnalyzed: number;
+    overallScore: number;
+    agentVisibilityScore: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    categoryScores: CategoryScores;
+    issues: QualityCheck[];
+    topIssues: QualityCheck[];
+    products: ProductAnalysis[];
+    recommendations: Recommendation[];
+    summary: FeedSummary;
+}
+
+/**
+ * Recommendation for improving feed quality
+ */
+export interface Recommendation {
+    priority: 'high' | 'medium' | 'low';
+    category: CheckCategory;
+    title: string;
+    description: string;
+    impact: string;
+    affectedCount: number;
+}
+
+/**
+ * Summary statistics for the feed
+ */
+export interface FeedSummary {
+    totalProducts: number;
+    withName: number;
+    withDescription: number;
+    withSku: number;
+    withGtin: number;
+    withBrand: number;
+    withImages: number;
+    withPrice: number;
+    withAvailability: number;
+    withCategory: number;
+    averageDescriptionLength: number;
+    averageImageCount: number;
+}
+
+/**
+ * Input options for feed analysis
+ */
+export interface FeedAnalysisInput {
+    url: string;
+    maxProducts?: number;
+    includeProductDetails?: boolean;
+}
+
+/**
+ * GTIN validation result
+ */
+export interface GtinValidation {
+    isValid: boolean;
+    type?: 'GTIN-8' | 'GTIN-12' | 'GTIN-13' | 'GTIN-14' | 'UPC' | 'EAN';
+    error?: string;
+}
+
+/**
+ * Quality check definitions
+ */
+export const QUALITY_CHECKS: Record<string, {
+    name: string;
+    category: CheckCategory;
+    severity: IssueSeverity;
+    description: string;
+}> = {
+    // Completeness checks
+    'missing-name': {
+        name: 'Missing Product Name',
+        category: 'completeness',
+        severity: 'critical',
+        description: 'Product name is required for AI agents to identify products',
+    },
+    'missing-description': {
+        name: 'Missing Description',
+        category: 'completeness',
+        severity: 'warning',
+        description: 'Product description helps AI agents understand and recommend products',
+    },
+    'short-description': {
+        name: 'Short Description',
+        category: 'descriptions',
+        severity: 'info',
+        description: 'Longer descriptions provide better context for AI agents',
+    },
+    'missing-brand': {
+        name: 'Missing Brand',
+        category: 'completeness',
+        severity: 'warning',
+        description: 'Brand information helps with product identification and search',
+    },
+
+    // Identifier checks
+    'missing-sku': {
+        name: 'Missing SKU',
+        category: 'identifiers',
+        severity: 'warning',
+        description: 'SKU helps uniquely identify products in your catalog',
+    },
+    'missing-gtin': {
+        name: 'Missing GTIN/UPC/EAN',
+        category: 'identifiers',
+        severity: 'warning',
+        description: 'Global identifiers enable cross-platform product matching',
+    },
+    'invalid-gtin': {
+        name: 'Invalid GTIN Format',
+        category: 'identifiers',
+        severity: 'critical',
+        description: 'GTIN has invalid format or check digit',
+    },
+
+    // Image checks
+    'missing-image': {
+        name: 'Missing Product Image',
+        category: 'images',
+        severity: 'critical',
+        description: 'Product images are essential for AI shopping experiences',
+    },
+    'single-image': {
+        name: 'Single Image Only',
+        category: 'images',
+        severity: 'info',
+        description: 'Multiple images improve product presentation',
+    },
+    'missing-image-alt': {
+        name: 'Missing Image Alt Text',
+        category: 'images',
+        severity: 'info',
+        description: 'Alt text helps with accessibility and SEO',
+    },
+
+    // Pricing checks
+    'missing-price': {
+        name: 'Missing Price',
+        category: 'pricing',
+        severity: 'critical',
+        description: 'Price is required for AI agents to complete purchases',
+    },
+    'missing-currency': {
+        name: 'Missing Currency',
+        category: 'pricing',
+        severity: 'warning',
+        description: 'Currency must be specified for international commerce',
+    },
+    'invalid-price': {
+        name: 'Invalid Price Format',
+        category: 'pricing',
+        severity: 'critical',
+        description: 'Price must be a valid number',
+    },
+
+    // Availability checks
+    'missing-availability': {
+        name: 'Missing Availability',
+        category: 'availability',
+        severity: 'warning',
+        description: 'Availability status helps AI agents make purchase decisions',
+    },
+    'invalid-availability': {
+        name: 'Invalid Availability Value',
+        category: 'availability',
+        severity: 'warning',
+        description: 'Availability should use Schema.org ItemAvailability values',
+    },
+
+    // Category checks
+    'missing-category': {
+        name: 'Missing Category',
+        category: 'categories',
+        severity: 'info',
+        description: 'Product categorization improves discoverability',
+    },
+};
+
+/**
+ * Valid Schema.org availability values
+ */
+export const VALID_AVAILABILITY_VALUES = [
+    'https://schema.org/InStock',
+    'https://schema.org/OutOfStock',
+    'https://schema.org/PreOrder',
+    'https://schema.org/PreSale',
+    'https://schema.org/SoldOut',
+    'https://schema.org/InStoreOnly',
+    'https://schema.org/OnlineOnly',
+    'https://schema.org/LimitedAvailability',
+    'https://schema.org/Discontinued',
+    'https://schema.org/BackOrder',
+    'InStock',
+    'OutOfStock',
+    'PreOrder',
+    'PreSale',
+    'SoldOut',
+    'InStoreOnly',
+    'OnlineOnly',
+    'LimitedAvailability',
+    'Discontinued',
+    'BackOrder',
+];
+
+/**
+ * Scoring weights for different categories
+ */
+export const CATEGORY_WEIGHTS: Record<CheckCategory, number> = {
+    completeness: 25,
+    identifiers: 15,
+    images: 20,
+    pricing: 20,
+    descriptions: 10,
+    categories: 5,
+    availability: 5,
+};
+
+/**
+ * Grade thresholds (aligned with all other scoring models)
+ */
+export const GRADE_THRESHOLDS = {
+    A: 90,
+    B: 80,
+    C: 70,
+    D: 60,
+    F: 0,
+};

package/src/generator/index.ts

@@ -0,0 +1,7 @@
+/**
+ * UCP Profile Generator Module
+ */
+
+export { buildProfile, generateMinimalProfile } from './profile-builder.js';
+export { generateSigningKeyPair, validatePublicKey } from './key-generator.js';
+export type { KeyAlgorithm, KeyPairResult } from './key-generator.js';

package/src/generator/key-generator.ts

@@ -0,0 +1,124 @@
+/**
+ * Signing Key Generator for UCP Webhook Signing
+ * Generates EC or RSA key pairs in JWK format
+ */
+
+import * as jose from 'jose';
+import { nanoid } from 'nanoid';
+import type { JwkKey } from '../types/ucp-profile.js';
+
+export type KeyAlgorithm = 'ES256' | 'RS256';
+
+export interface KeyPairResult {
+  publicKey: JwkKey;
+  privateKey: string;  // PEM format for merchant storage
+}
+
+/**
+ * Generate a new signing key pair
+ */
+export async function generateSigningKeyPair(
+  algorithm: KeyAlgorithm = 'ES256'
+): Promise<KeyPairResult> {
+  const keyId = `ucp-${nanoid(12)}`;
+
+  if (algorithm === 'ES256') {
+    return generateECKeyPair(keyId);
+  } else {
+    return generateRSAKeyPair(keyId);
+  }
+}
+
+/**
+ * Generate EC (P-256) key pair
+ */
+async function generateECKeyPair(keyId: string): Promise<KeyPairResult> {
+  const { publicKey, privateKey } = await jose.generateKeyPair('ES256', {
+    extractable: true,
+  });
+
+  // Export public key as JWK
+  const publicJwk = await jose.exportJWK(publicKey);
+
+  // Export private key as PEM
+  const privatePem = await jose.exportPKCS8(privateKey);
+
+  return {
+    publicKey: {
+      kty: 'EC',
+      kid: keyId,
+      use: 'sig',
+      alg: 'ES256',
+      crv: publicJwk.crv as string,
+      x: publicJwk.x as string,
+      y: publicJwk.y as string,
+    },
+    privateKey: privatePem,
+  };
+}
+
+/**
+ * Generate RSA (2048-bit) key pair
+ */
+async function generateRSAKeyPair(keyId: string): Promise<KeyPairResult> {
+  const { publicKey, privateKey } = await jose.generateKeyPair('RS256', {
+    extractable: true,
+    modulusLength: 2048,
+  });
+
+  // Export public key as JWK
+  const publicJwk = await jose.exportJWK(publicKey);
+
+  // Export private key as PEM
+  const privatePem = await jose.exportPKCS8(privateKey);
+
+  return {
+    publicKey: {
+      kty: 'RSA',
+      kid: keyId,
+      use: 'sig',
+      alg: 'RS256',
+      n: publicJwk.n as string,
+      e: publicJwk.e as string,
+    },
+    privateKey: privatePem,
+  };
+}
+
+/**
+ * Validate a JWK public key structure
+ */
+export function validatePublicKey(key: JwkKey): string[] {
+  const errors: string[] = [];
+
+  if (!key.kty) {
+    errors.push('Missing required field: kty');
+  }
+
+  if (!key.kid) {
+    errors.push('Missing required field: kid');
+  }
+
+  if (key.kty === 'EC') {
+    if (!key.crv) errors.push('EC key missing curve (crv)');
+    if (!key.x) errors.push('EC key missing x coordinate');
+    if (!key.y) errors.push('EC key missing y coordinate');
+    if (key.crv && !['P-256', 'P-384', 'P-521'].includes(key.crv)) {
+      errors.push(`Unsupported EC curve: ${key.crv}`);
+    }
+  } else if (key.kty === 'RSA') {
+    if (!key.n) errors.push('RSA key missing modulus (n)');
+    if (!key.e) errors.push('RSA key missing exponent (e)');
+  } else if (key.kty) {
+    errors.push(`Unsupported key type: ${key.kty}`);
+  }
+
+  return errors;
+}
+
+/**
+ * Import and validate a public key from JWK
+ */
+export async function importPublicKey(jwk: JwkKey): Promise<jose.KeyLike | Uint8Array> {
+  return jose.importJWK(jwk as jose.JWK, jwk.alg);
+}