@ucptools/validator 1.0.0 → 1.0.1

package/src/services/directory.ts

@@ -1,434 +0,0 @@
-/**
- * Directory Service
- * Business logic for the UCP Merchant Directory
- */
-
-import { eq, ilike, sql, desc, asc, and, count, SQL } from 'drizzle-orm';
-import { getDb, merchants, type Merchant, type NewMerchant } from '../db/index.js';
-
-// Types
-export interface ListMerchantsParams {
-  page?: number;
-  limit?: number;
-  category?: string;
-  country?: string;
-  search?: string;
-  sort?: 'score' | 'domain' | 'displayName' | 'createdAt';
-  order?: 'asc' | 'desc';
-}
-
-export interface ListMerchantsResult {
-  merchants: Merchant[];
-  pagination: {
-    page: number;
-    limit: number;
-    total: number;
-    totalPages: number;
-  };
-  filters: {
-    categories: { name: string; count: number }[];
-    countries: { code: string; count: number }[];
-  };
-}
-
-export interface SubmitMerchantParams {
-  domain: string;
-  displayName?: string;
-  description?: string;
-  logoUrl?: string;
-  websiteUrl?: string;
-  category?: string;
-  countryCode?: string;
-}
-
-export interface DirectoryStats {
-  totalMerchants: number;
-  verifiedMerchants: number;
-  avgScore: number;
-  totalCategories: number;
-  totalCountries: number;
-  gradeDistribution: { grade: string; count: number }[];
-  topCategories: { name: string; count: number }[];
-  recentAdditions: { domain: string; displayName: string; grade: string | null; addedAt: Date }[];
-}
-
-export interface ValidationResult {
-  valid: boolean;
-  error?: string;
-  score?: number;
-  grade?: string;
-  transports?: string;
-  ucpVersion?: string;
-}
-
-// UCP Profile structure (minimal typing for validation)
-interface UcpProfile {
-  ucp?: {
-    version?: string;
-    services?: Record<string, { rest?: unknown; mcp?: unknown; a2a?: unknown; embedded?: unknown }>;
-    capabilities?: Array<{ name: string }>;
-  };
-  signing_keys?: unknown[];
-}
-
-/**
- * Fetch UCP profile from a URL, return null if not valid JSON
- */
-async function tryFetchProfile(url: string): Promise<UcpProfile | null> {
-  try {
-    const res = await fetch(url, {
-      headers: {
-        Accept: 'application/json',
-        'User-Agent': 'UCP-Directory/1.0 (https://ucptools.dev)',
-      },
-      signal: AbortSignal.timeout(10000),
-    });
-
-    if (!res.ok) return null;
-
-    const text = await res.text();
-    // Check if response looks like JSON (not HTML)
-    if (text.trim().startsWith('<')) return null;
-
-    return JSON.parse(text) as UcpProfile;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Validate a domain's UCP profile
- */
-export async function validateDomain(domain: string): Promise<ValidationResult> {
-  // Try both /.well-known/ucp and /.well-known/ucp.json
-  const urls = [
-    `https://${domain}/.well-known/ucp`,
-    `https://${domain}/.well-known/ucp.json`,
-  ];
-
-  let profile: UcpProfile | null = null;
-
-  for (const url of urls) {
-    profile = await tryFetchProfile(url);
-    if (profile) break;
-  }
-
-  try {
-    if (!profile) {
-      return { valid: false, error: 'No UCP profile found at /.well-known/ucp or /.well-known/ucp.json' };
-    }
-
-    // Basic validation
-    if (!profile?.ucp?.version || !profile?.ucp?.services) {
-      return { valid: false, error: 'Invalid UCP profile structure' };
-    }
-
-    // Extract transports
-    const transports = new Set<string>();
-    for (const svc of Object.values(profile.ucp.services || {})) {
-      if (svc.rest) transports.add('REST');
-      if (svc.mcp) transports.add('MCP');
-      if (svc.a2a) transports.add('A2A');
-      if (svc.embedded) transports.add('Embedded');
-    }
-
-    // Simple scoring
-    let score = 50;
-    const capabilities = profile.ucp.capabilities || [];
-    if (capabilities.some((c) => c.name === 'dev.ucp.shopping.checkout')) score += 20;
-    if (capabilities.some((c) => c.name === 'dev.ucp.shopping.cart')) score += 10;
-    if (capabilities.some((c) => c.name === 'dev.ucp.shopping.order')) score += 10;
-    if (profile.signing_keys && profile.signing_keys.length > 0) score += 10;
-
-    const grade = score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';
-
-    return {
-      valid: true,
-      score,
-      grade,
-      transports: Array.from(transports).join(','),
-      ucpVersion: profile.ucp.version,
-    };
-  } catch (e: unknown) {
-    const message = e instanceof Error ? e.message : 'Failed to fetch profile';
-    return { valid: false, error: message };
-  }
-}
-
-/**
- * List merchants with pagination and filters
- */
-export async function listMerchants(params: ListMerchantsParams): Promise<ListMerchantsResult> {
-  const db = getDb();
-
-  const page = Math.max(1, params.page || 1);
-  const limit = Math.min(100, Math.max(1, params.limit || 20));
-  const offset = (page - 1) * limit;
-
-  // Build where conditions
-  const conditions: SQL[] = [eq(merchants.isPublic, true)];
-
-  if (params.category) {
-    conditions.push(eq(merchants.category, params.category));
-  }
-
-  if (params.country) {
-    conditions.push(eq(merchants.countryCode, params.country.toUpperCase()));
-  }
-
-  if (params.search) {
-    conditions.push(
-      sql`(${merchants.domain} ILIKE ${`%${params.search}%`} OR ${merchants.displayName} ILIKE ${`%${params.search}%`})`
-    );
-  }
-
-  const whereClause = and(...conditions);
-
-  // Determine sort column and order
-  const sortColumn =
-    params.sort === 'domain'
-      ? merchants.domain
-      : params.sort === 'displayName'
-        ? merchants.displayName
-        : params.sort === 'createdAt'
-          ? merchants.createdAt
-          : merchants.ucpScore;
-
-  const orderFn = params.order === 'asc' ? asc : desc;
-
-  // Get total count
-  const countResult = await db
-    .select({ total: count() })
-    .from(merchants)
-    .where(whereClause);
-
-  const total = countResult[0]?.total || 0;
-
-  // Get merchants
-  const merchantList = await db
-    .select()
-    .from(merchants)
-    .where(whereClause)
-    .orderBy(orderFn(sortColumn))
-    .limit(limit)
-    .offset(offset);
-
-  // Get category counts
-  const categoryResult = await db
-    .select({
-      category: merchants.category,
-      count: count(),
-    })
-    .from(merchants)
-    .where(and(eq(merchants.isPublic, true), sql`${merchants.category} IS NOT NULL`))
-    .groupBy(merchants.category)
-    .orderBy(desc(count()));
-
-  // Get country counts
-  const countryResult = await db
-    .select({
-      countryCode: merchants.countryCode,
-      count: count(),
-    })
-    .from(merchants)
-    .where(and(eq(merchants.isPublic, true), sql`${merchants.countryCode} IS NOT NULL`))
-    .groupBy(merchants.countryCode)
-    .orderBy(desc(count()));
-
-  return {
-    merchants: merchantList,
-    pagination: {
-      page,
-      limit,
-      total,
-      totalPages: Math.ceil(total / limit),
-    },
-    filters: {
-      categories: categoryResult.map((r) => ({ name: r.category!, count: r.count })),
-      countries: countryResult.map((r) => ({ code: r.countryCode!, count: r.count })),
-    },
-  };
-}
-
-/**
- * Get a single merchant by domain
- */
-export async function getMerchantByDomain(domain: string): Promise<Merchant | null> {
-  const db = getDb();
-  const result = await db.select().from(merchants).where(eq(merchants.domain, domain.toLowerCase())).limit(1);
-  return result[0] || null;
-}
-
-/**
- * Submit a new merchant to the directory
- */
-export async function submitMerchant(
-  params: SubmitMerchantParams
-): Promise<{ success: boolean; merchant?: Merchant; error?: string; details?: string }> {
-  const db = getDb();
-
-  // Clean domain
-  const cleanDomain = params.domain
-    .replace(/^https?:\/\//, '')
-    .replace(/\/$/, '')
-    .split('/')[0]
-    .toLowerCase();
-
-  // Check if domain already exists
-  const existing = await getMerchantByDomain(cleanDomain);
-  if (existing) {
-    return {
-      success: false,
-      error: 'Domain already registered',
-      details: `Merchant ID: ${existing.id}`,
-    };
-  }
-
-  // Validate the domain has a valid UCP profile
-  const validation = await validateDomain(cleanDomain);
-
-  if (!validation.valid) {
-    return {
-      success: false,
-      error: 'Invalid UCP profile',
-      details: validation.error,
-    };
-  }
-
-  // Insert merchant
-  const newMerchant: NewMerchant = {
-    domain: cleanDomain,
-    displayName: params.displayName || cleanDomain,
-    description: params.description || null,
-    logoUrl: params.logoUrl || null,
-    websiteUrl: params.websiteUrl || `https://${cleanDomain}`,
-    category: params.category || null,
-    countryCode: params.countryCode?.toUpperCase() || null,
-    ucpScore: validation.score || null,
-    ucpGrade: validation.grade || null,
-    transports: validation.transports || null,
-    isPublic: true,
-    isVerified: false,
-    lastValidatedAt: new Date(),
-  };
-
-  const result = await db.insert(merchants).values(newMerchant).returning();
-
-  return {
-    success: true,
-    merchant: result[0],
-  };
-}
-
-/**
- * Get directory statistics
- */
-export async function getDirectoryStats(): Promise<DirectoryStats> {
-  const db = getDb();
-
-  // Overall stats
-  const statsResult = await db
-    .select({
-      totalMerchants: count(),
-      verifiedMerchants: sql<number>`COUNT(*) FILTER (WHERE ${merchants.isVerified} = true)`,
-      avgScore: sql<number>`COALESCE(AVG(${merchants.ucpScore}), 0)`,
-    })
-    .from(merchants)
-    .where(eq(merchants.isPublic, true));
-
-  // Count distinct categories and countries
-  const categoryCountResult = await db
-    .select({ count: sql<number>`COUNT(DISTINCT ${merchants.category})` })
-    .from(merchants)
-    .where(and(eq(merchants.isPublic, true), sql`${merchants.category} IS NOT NULL`));
-
-  const countryCountResult = await db
-    .select({ count: sql<number>`COUNT(DISTINCT ${merchants.countryCode})` })
-    .from(merchants)
-    .where(and(eq(merchants.isPublic, true), sql`${merchants.countryCode} IS NOT NULL`));
-
-  // Grade distribution
-  const gradeResult = await db
-    .select({
-      grade: merchants.ucpGrade,
-      count: count(),
-    })
-    .from(merchants)
-    .where(and(eq(merchants.isPublic, true), sql`${merchants.ucpGrade} IS NOT NULL`))
-    .groupBy(merchants.ucpGrade)
-    .orderBy(merchants.ucpGrade);
-
-  // Top categories
-  const topCategoriesResult = await db
-    .select({
-      name: merchants.category,
-      count: count(),
-    })
-    .from(merchants)
-    .where(and(eq(merchants.isPublic, true), sql`${merchants.category} IS NOT NULL`))
-    .groupBy(merchants.category)
-    .orderBy(desc(count()))
-    .limit(10);
-
-  // Recent additions
-  const recentResult = await db
-    .select({
-      domain: merchants.domain,
-      displayName: merchants.displayName,
-      grade: merchants.ucpGrade,
-      addedAt: merchants.createdAt,
-    })
-    .from(merchants)
-    .where(eq(merchants.isPublic, true))
-    .orderBy(desc(merchants.createdAt))
-    .limit(5);
-
-  const stats = statsResult[0];
-
-  return {
-    totalMerchants: stats?.totalMerchants || 0,
-    verifiedMerchants: stats?.verifiedMerchants || 0,
-    avgScore: Math.round(stats?.avgScore || 0),
-    totalCategories: categoryCountResult[0]?.count || 0,
-    totalCountries: countryCountResult[0]?.count || 0,
-    gradeDistribution: gradeResult.map((r) => ({ grade: r.grade!, count: r.count })),
-    topCategories: topCategoriesResult.map((r) => ({ name: r.name!, count: r.count })),
-    recentAdditions: recentResult.map((r) => ({
-      domain: r.domain,
-      displayName: r.displayName,
-      grade: r.grade,
-      addedAt: r.addedAt,
-    })),
-  };
-}
-
-/**
- * Re-validate a merchant's UCP profile and update their record
- */
-export async function revalidateMerchant(domain: string): Promise<{ success: boolean; error?: string }> {
-  const db = getDb();
-
-  const merchant = await getMerchantByDomain(domain);
-  if (!merchant) {
-    return { success: false, error: 'Merchant not found' };
-  }
-
-  const validation = await validateDomain(domain);
-
-  if (!validation.valid) {
-    return { success: false, error: validation.error };
-  }
-
-  await db
-    .update(merchants)
-    .set({
-      ucpScore: validation.score || null,
-      ucpGrade: validation.grade || null,
-      transports: validation.transports || null,
-      lastValidatedAt: new Date(),
-      updatedAt: new Date(),
-    })
-    .where(eq(merchants.domain, domain.toLowerCase()));
-
-  return { success: true };
-}

package/src/types/generator.ts

@@ -1,140 +0,0 @@
-/**
- * Generator Types for UCP Profile Generator
- */
-
-import type { Environment, ProfileStatus } from './ucp-profile.js';
-
-// Merchant information
-export interface MerchantInfo {
-  merchantId: string;
-  primaryDomain: string;
-  displayName?: string;
-  environment?: Environment;
-}
-
-// Transport configuration inputs
-export interface TransportConfig {
-  rest?: {
-    endpoint: string;
-    schemaUrl?: string;  // Override default
-  };
-  mcp?: {
-    endpoint: string;
-    schemaUrl?: string;
-  };
-  a2a?: {
-    agentCardUrl: string;
-  };
-  embedded?: {
-    schemaUrl: string;
-  };
-}
-
-// Capability selection (based on official UCP spec)
-export interface CapabilitySelection {
-  checkout: boolean;      // Default: true
-  order: boolean;         // Requires signing keys
-  fulfillment: boolean;   // Extension of order
-  discount: boolean;      // Extension
-  payment?: boolean;      // Payment capability
-  buyerConsent?: boolean; // Buyer consent capability
-  customCapabilities?: CustomCapability[];
-}
-
-// Custom/vendor capability
-export interface CustomCapability {
-  namespace: string;      // e.g., "com.myvendor"
-  name: string;           // e.g., "custom-feature"
-  version: string;
-  specUrl: string;
-  schemaUrl: string;
-  extendsCapability?: string;
-}
-
-// Security configuration
-export interface SecurityConfig {
-  generateSigningKeys: boolean;
-  signingKeyAlgorithm?: 'ES256' | 'RS256';
-  uploadedPublicKey?: string;  // PEM or JWK format
-}
-
-// Complete generator input
-export interface GeneratorInput {
-  merchant: MerchantInfo;
-  transport: TransportConfig;
-  capabilities: CapabilitySelection;
-  security?: SecurityConfig;
-  ucpVersion?: string;    // Override default version
-}
-
-// Generator output artifacts
-export interface GeneratorOutput {
-  profile: object;                    // The UCP profile JSON
-  profileJson: string;                // Formatted JSON string
-  installInstructions: string;        // Markdown instructions
-  validationReport?: object;          // Initial validation
-  signingKeyPair?: {                  // If keys were generated
-    publicKey: object;                // JWK public key
-    privateKey: string;               // PEM private key (for merchant to store securely)
-  };
-}
-
-// Hosting mode options
-export type HostingMode = 'static' | 'edge-worker' | 'reverse-proxy';
-
-// Hosting target platforms
-export type HostingPlatform =
-  | 'nginx'
-  | 'apache'
-  | 'vercel'
-  | 'netlify'
-  | 'cloudflare-worker'
-  | 'cloudflare-pages'
-  | 's3-cloudfront'
-  | 'generic';
-
-// Hosting configuration
-export interface HostingConfig {
-  mode: HostingMode;
-  platform?: HostingPlatform;
-  merchantId: string;
-  merchantDomain: string;
-  hostedProfileUrl?: string;  // For edge/proxy modes
-}
-
-// Install artifact
-export interface InstallArtifact {
-  filename: string;
-  content: string;
-  contentType: 'json' | 'javascript' | 'nginx' | 'apache' | 'markdown';
-  description: string;
-}
-
-// Database models (for API service)
-export interface MerchantRecord {
-  id: string;
-  primaryDomain: string;
-  displayName?: string;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-export interface ProfileRecord {
-  id: string;
-  merchantId: string;
-  versionTag: string;
-  ucpVersion: string;
-  jsonBody: object;
-  status: ProfileStatus;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-export interface ValidationRunRecord {
-  id: string;
-  profileId: string;
-  mode: 'draft' | 'remote';
-  result: object;
-  ok: boolean;
-  createdAt: Date;
-}

package/src/types/ucp-profile.ts

@@ -1,140 +0,0 @@
-/**
- * UCP (Universal Commerce Protocol) Profile Types
- * Based on https://ucp.dev/specification/overview/
- */
-
-// Current UCP version
-export const CURRENT_UCP_VERSION = '2026-01-11';
-
-// Transport binding types
-export interface RestTransport {
-  schema: string;  // OpenAPI schema URL
-  endpoint: string; // REST API endpoint (https, no trailing slash)
-}
-
-export interface McpTransport {
-  schema: string;  // MCP schema URL
-  endpoint: string; // MCP endpoint URL
-}
-
-export interface A2aTransport {
-  agentCard: string; // A2A agent card URL
-}
-
-export interface EmbeddedTransport {
-  schema: string;  // Embedded schema URL
-}
-
-// Service definition with transport bindings
-export interface UcpService {
-  version: string;
-  spec: string;
-  rest?: RestTransport;
-  mcp?: McpTransport;
-  a2a?: A2aTransport;
-  embedded?: EmbeddedTransport;
-}
-
-// Capability definition
-export interface UcpCapability {
-  name: string;        // e.g., "dev.ucp.shopping.checkout"
-  version: string;     // e.g., "2026-01-11"
-  spec: string;        // Specification URL
-  schema: string;      // JSON Schema URL
-  extends?: string;    // Parent capability for extensions
-  config?: Record<string, unknown>; // Capability-specific settings
-}
-
-// JWK (JSON Web Key) for signing
-export interface JwkKey {
-  kty: string;         // Key type (e.g., "EC", "RSA")
-  kid: string;         // Key ID
-  use?: string;        // Key use (e.g., "sig")
-  alg?: string;        // Algorithm (e.g., "ES256")
-  crv?: string;        // Curve (for EC keys)
-  x?: string;          // X coordinate (for EC keys)
-  y?: string;          // Y coordinate (for EC keys)
-  n?: string;          // Modulus (for RSA keys)
-  e?: string;          // Exponent (for RSA keys)
-}
-
-// Signing keys - array of JWK public keys at root level
-export type SigningKeys = JwkKey[];
-
-// Payment handler definition
-export interface PaymentHandler {
-  id: string;           // Handler identifier
-  name: string;         // Display name
-  version: string;      // Handler version (YYYY-MM-DD)
-  spec: string;         // Handler specification URL
-  config_schema?: string;        // Configuration schema URL
-  instrument_schemas?: string[]; // Payment instrument schemas
-  config?: Record<string, unknown>; // Handler-specific config
-}
-
-// Payment configuration
-export interface PaymentConfig {
-  handlers: PaymentHandler[];
-}
-
-// Main UCP object within profile
-export interface UcpObject {
-  version: string;
-  services: Record<string, UcpService>;
-  capabilities: UcpCapability[];
-}
-
-// Complete UCP Business Profile (/.well-known/ucp)
-export interface UcpProfile {
-  ucp: UcpObject;
-  payment?: PaymentConfig;       // Payment handlers configuration
-  signing_keys?: SigningKeys;    // JWK public keys for webhook verification
-  // Additional vendor extensions can be added as siblings
-  [key: string]: unknown;
-}
-
-// Known capability namespaces
-export const CAPABILITY_NAMESPACES = {
-  UCP_OFFICIAL: 'dev.ucp.',
-  VENDOR_PREFIX: 'com.',
-} as const;
-
-// Known UCP capabilities (from official spec)
-export const KNOWN_CAPABILITIES = {
-  CHECKOUT: 'dev.ucp.shopping.checkout',
-  ORDER: 'dev.ucp.shopping.order',
-  PAYMENT: 'dev.ucp.shopping.payment',
-  PAYMENT_DATA: 'dev.ucp.shopping.payment_data',
-  FULFILLMENT: 'dev.ucp.shopping.fulfillment',
-  DISCOUNT: 'dev.ucp.shopping.discount',
-  BUYER_CONSENT: 'dev.ucp.shopping.buyer_consent',
-} as const;
-
-// Known UCP services
-export const KNOWN_SERVICES = {
-  SHOPPING: 'dev.ucp.shopping',
-} as const;
-
-// Default URLs for UCP official resources
-export const UCP_DEFAULTS = {
-  SPEC_BASE: 'https://ucp.dev/specification/',
-  SCHEMA_BASE: 'https://ucp.dev/schemas/',
-  SERVICE_SCHEMA_BASE: 'https://ucp.dev/services/',
-
-  // Default schema URLs
-  SHOPPING_REST_SCHEMA: 'https://ucp.dev/services/shopping/rest.openapi.json',
-  CHECKOUT_SPEC: 'https://ucp.dev/specification/checkout/',
-  CHECKOUT_SCHEMA: 'https://ucp.dev/schemas/shopping/checkout.json',
-  ORDER_SPEC: 'https://ucp.dev/specification/order/',
-  ORDER_SCHEMA: 'https://ucp.dev/schemas/shopping/order.json',
-  FULFILLMENT_SPEC: 'https://ucp.dev/specification/fulfillment/',
-  FULFILLMENT_SCHEMA: 'https://ucp.dev/schemas/shopping/fulfillment.json',
-  DISCOUNT_SPEC: 'https://ucp.dev/specification/discount/',
-  DISCOUNT_SCHEMA: 'https://ucp.dev/schemas/shopping/discount.json',
-} as const;
-
-// Environment types
-export type Environment = 'production' | 'staging' | 'development';
-
-// Profile status
-export type ProfileStatus = 'draft' | 'published';