@ucptools/validator 1.0.0

package/src/simulator/index.ts

@@ -0,0 +1,7 @@
+/**
+ * AI Agent Simulator Module
+ * Exports for simulating AI agent interactions with UCP merchants
+ */
+
+export * from './types.js';
+export * from './agent-simulator.js';

package/src/simulator/types.ts

@@ -0,0 +1,170 @@
+/**
+ * AI Agent Simulation Types
+ * Types for simulating AI agent interactions with UCP merchants
+ */
+
+/**
+ * Simulation step status
+ */
+export type SimulationStepStatus = 'passed' | 'failed' | 'skipped' | 'warning';
+
+/**
+ * Individual simulation step result
+ */
+export interface SimulationStepResult {
+    step: string;
+    status: SimulationStepStatus;
+    message: string;
+    details?: string;
+    durationMs?: number;
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Discovery flow simulation results
+ */
+export interface DiscoveryFlowResult {
+    success: boolean;
+    steps: SimulationStepResult[];
+    profileUrl?: string;
+    capabilities: string[];
+    services: string[];
+    transports: string[];
+}
+
+/**
+ * Capability inspection result
+ */
+export interface CapabilityInspectionResult {
+    name: string;
+    version: string;
+    schemaAccessible: boolean;
+    specAccessible: boolean;
+    isExtension: boolean;
+    parentCapability?: string;
+}
+
+/**
+ * Service inspection result
+ */
+export interface ServiceInspectionResult {
+    name: string;
+    version: string;
+    transports: {
+        rest?: {
+            endpoint: string;
+            schemaAccessible: boolean;
+            endpointResponsive: boolean;
+        };
+        mcp?: {
+            endpoint: string;
+            schemaAccessible: boolean;
+        };
+        a2a?: {
+            agentCard: string;
+            agentCardAccessible: boolean;
+        };
+    };
+}
+
+/**
+ * REST API simulation results
+ */
+export interface RestApiSimulationResult {
+    success: boolean;
+    steps: SimulationStepResult[];
+    schemaLoaded: boolean;
+    endpointAccessible: boolean;
+    sampleOperations: OperationTestResult[];
+}
+
+/**
+ * Operation test result from REST API
+ */
+export interface OperationTestResult {
+    operation: string;
+    method: string;
+    path: string;
+    status: SimulationStepStatus;
+    message: string;
+    responseCode?: number;
+}
+
+/**
+ * Checkout simulation result
+ */
+export interface CheckoutSimulationResult {
+    success: boolean;
+    steps: SimulationStepResult[];
+    canCreateCheckout: boolean;
+    checkoutSchemaValid: boolean;
+    orderFlowSupported: boolean;
+    fulfillmentSupported: boolean;
+}
+
+/**
+ * Payment readiness result
+ */
+export interface PaymentReadinessResult {
+    success: boolean;
+    steps: SimulationStepResult[];
+    handlersFound: number;
+    webhookVerifiable: boolean;
+    signingKeyValid: boolean;
+}
+
+/**
+ * Overall AI readiness simulation result
+ */
+export interface AgentSimulationResult {
+    ok: boolean;
+    domain: string;
+    simulatedAt: string;
+    durationMs: number;
+
+    // Overall scores (0-100) and grade (A-F)
+    overallScore: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+
+    // Individual flow results
+    discovery: DiscoveryFlowResult;
+    capabilities: CapabilityInspectionResult[];
+    services: ServiceInspectionResult[];
+    restApi?: RestApiSimulationResult;
+    checkout?: CheckoutSimulationResult;
+    payment?: PaymentReadinessResult;
+
+    // Summary
+    summary: {
+        totalSteps: number;
+        passedSteps: number;
+        failedSteps: number;
+        warningSteps: number;
+        skippedSteps: number;
+    };
+
+    // Recommendations
+    recommendations: string[];
+}
+
+/**
+ * Simulation options
+ */
+export interface SimulationOptions {
+    timeoutMs?: number;
+    skipRestApiTest?: boolean;
+    skipSchemaValidation?: boolean;
+    testCheckoutFlow?: boolean;
+    verbose?: boolean;
+}
+
+/**
+ * Default simulation options
+ */
+export const DEFAULT_SIMULATION_OPTIONS: Required<SimulationOptions> = {
+    timeoutMs: 30000,
+    skipRestApiTest: false,
+    skipSchemaValidation: false,
+    testCheckoutFlow: true,
+    verbose: false,
+};

package/src/types/generator.ts

@@ -0,0 +1,140 @@
+/**
+ * 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/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Central export for all UCP Profile Manager types
+ */
+
+export * from './ucp-profile.js';
+export * from './validation.js';
+export * from './generator.js';

package/src/types/ucp-profile.ts

@@ -0,0 +1,140 @@
+/**
+ * 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';

package/src/types/validation.ts

@@ -0,0 +1,89 @@
+/**
+ * Validation Types for UCP Profile Validator
+ */
+
+// Validation severity levels
+export type ValidationSeverity = 'error' | 'warn' | 'info';
+
+// Validation error codes
+export const ValidationErrorCodes = {
+  // Structural errors
+  MISSING_UCP_OBJECT: 'UCP_MISSING_ROOT',
+  MISSING_VERSION: 'UCP_MISSING_VERSION',
+  INVALID_VERSION_FORMAT: 'UCP_INVALID_VERSION_FORMAT',
+  MISSING_SERVICES: 'UCP_MISSING_SERVICES',
+  MISSING_CAPABILITIES: 'UCP_MISSING_CAPABILITIES',
+  INVALID_SERVICE_STRUCTURE: 'UCP_INVALID_SERVICE',
+  INVALID_CAPABILITY_STRUCTURE: 'UCP_INVALID_CAPABILITY',
+
+  // UCP rules errors
+  NS_ORIGIN_MISMATCH: 'UCP_NS_ORIGIN_MISMATCH',
+  ORPHANED_EXTENSION: 'UCP_ORPHANED_EXTENSION',
+  ENDPOINT_NOT_HTTPS: 'UCP_ENDPOINT_NOT_HTTPS',
+  ENDPOINT_TRAILING_SLASH: 'UCP_ENDPOINT_TRAILING_SLASH',
+  MISSING_SIGNING_KEYS: 'UCP_MISSING_SIGNING_KEYS',
+  INVALID_SIGNING_KEY: 'UCP_INVALID_SIGNING_KEY',
+
+  // Network validation errors
+  PROFILE_FETCH_FAILED: 'UCP_PROFILE_FETCH_FAILED',
+  SCHEMA_FETCH_FAILED: 'UCP_SCHEMA_FETCH_FAILED',
+  SCHEMA_NOT_SELF_DESCRIBING: 'UCP_SCHEMA_NOT_SELF_DESCRIBING',
+  SCHEMA_NAME_MISMATCH: 'UCP_SCHEMA_NAME_MISMATCH',
+  SCHEMA_VERSION_MISMATCH: 'UCP_SCHEMA_VERSION_MISMATCH',
+  PRIVATE_IP_ENDPOINT: 'UCP_PRIVATE_IP_ENDPOINT',
+} as const;
+
+export type ValidationErrorCode = typeof ValidationErrorCodes[keyof typeof ValidationErrorCodes];
+
+// Single validation issue
+export interface ValidationIssue {
+  severity: ValidationSeverity;
+  code: ValidationErrorCode;
+  path: string;          // JSON path (e.g., "$.ucp.capabilities[0].schema")
+  message: string;       // Human-readable message
+  hint?: string;         // Suggestion for fixing
+}
+
+// Validation report
+export interface ValidationReport {
+  ok: boolean;
+  profile_url?: string;   // For remote validation
+  ucp_version?: string;
+  issues: ValidationIssue[];
+  validated_at: string;   // ISO timestamp
+  validation_mode: ValidationMode;
+  sdk_validation?: {       // Official SDK validation info
+    validated: boolean;    // Whether SDK validation passed
+    sdk_version: string;   // @ucp-js/sdk version used
+    compliant: boolean;    // Whether profile is SDK-compliant
+  };
+}
+
+// Validation modes
+export type ValidationMode = 'structural' | 'rules' | 'network' | 'full';
+
+// Validation options
+export interface ValidationOptions {
+  mode?: ValidationMode;
+  skipNetworkChecks?: boolean;
+  timeoutMs?: number;
+  cacheTtlMs?: number;
+}
+
+// Schema cache entry
+export interface SchemaCacheEntry {
+  url: string;
+  etag?: string;
+  fetchedAt: string;
+  body: Record<string, unknown>;
+  expiresAt: string;
+}
+
+// Remote fetch result
+export interface FetchResult<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  statusCode?: number;
+  etag?: string;
+}