@ucptools/validator 1.0.0

package/src/compliance/templates.ts

@@ -0,0 +1,338 @@
+/**
+ * GDPR/Privacy Compliance Templates
+ * Template content for privacy policy addendums and consent language
+ */
+
+import type { ComplianceRegion, LawfulBasis, DataProcessor } from './types.js';
+import { LAWFUL_BASIS_DESCRIPTIONS, AI_PLATFORM_PROCESSORS } from './types.js';
+
+/**
+ * Generate the AI Commerce privacy policy section
+ */
+export function generateAiCommerceSection(
+  companyName: string,
+  platforms: DataProcessor[],
+  lawfulBasis: LawfulBasis,
+  regions: ComplianceRegion[]
+): string {
+  const basisInfo = LAWFUL_BASIS_DESCRIPTIONS[lawfulBasis];
+  const platformList = platforms.map(p => p.name).join(', ');
+
+  let section = `## AI-Powered Shopping and Agentic Commerce
+
+### How We Use AI Shopping Agents
+
+${companyName} enables customers to browse, shop, and complete purchases through AI-powered shopping agents and assistants. These include services such as ${platformList}.
+
+When you interact with our store through an AI shopping agent:
+- The AI agent may access our product catalog, pricing, and availability information
+- Your order details are processed through our Universal Commerce Protocol (UCP) integration
+- Transaction data is shared with the AI platform to complete your purchase
+
+### Legal Basis for Processing
+
+We process your personal data in connection with AI-assisted purchases under **${basisInfo.title}** (${basisInfo.gdprArticle} GDPR).
+
+${basisInfo.description}
+
+### Data Collected Through AI Agents
+
+When you make a purchase through an AI shopping agent, we may collect:
+- Order information (products, quantities, prices)
+- Delivery address and contact details
+- Payment confirmation (we do not receive full payment card details)
+- Transaction identifiers for order tracking
+- Communication preferences
+`;
+
+  if (regions.includes('eu') || regions.includes('uk')) {
+    section += `
+### International Data Transfers
+
+Some AI agent providers are based outside the European Economic Area (EEA) or United Kingdom. When your data is transferred to these providers, it is protected by:
+- Standard Contractual Clauses (SCCs) approved by the European Commission
+- The provider's certification under applicable data protection frameworks
+- Additional technical and organizational security measures
+`;
+  }
+
+  if (regions.includes('california')) {
+    section += `
+### California Privacy Rights (CCPA/CPRA)
+
+California residents have additional rights regarding personal information collected through AI shopping agents:
+- **Right to Know**: You may request details about the personal information we collect and share
+- **Right to Delete**: You may request deletion of your personal information, subject to certain exceptions
+- **Right to Opt-Out**: You may opt out of the "sale" or "sharing" of personal information
+- **Right to Non-Discrimination**: We will not discriminate against you for exercising your privacy rights
+
+To exercise these rights, contact us at the email address provided below.
+`;
+  }
+
+  return section;
+}
+
+/**
+ * Generate data processor disclosures
+ */
+export function generateProcessorDisclosures(
+  processors: DataProcessor[],
+  regions: ComplianceRegion[]
+): string {
+  let disclosure = `## Third-Party Data Processors (AI Commerce)
+
+We work with the following third-party service providers to enable AI-powered shopping:
+
+| Provider | Purpose | Location | Privacy Policy |
+|----------|---------|----------|----------------|
+`;
+
+  for (const processor of processors) {
+    const privacyLink = processor.privacyPolicyUrl
+      ? `[View Policy](${processor.privacyPolicyUrl})`
+      : 'Contact provider';
+    disclosure += `| ${processor.name} | ${processor.purpose} | ${processor.country || 'Various'} | ${privacyLink} |\n`;
+  }
+
+  disclosure += `
+These processors are contractually bound to:
+- Process data only on our documented instructions
+- Ensure appropriate security measures are in place
+- Assist us in responding to data subject requests
+- Delete or return all personal data at the end of the service relationship
+`;
+
+  if (regions.includes('eu') || regions.includes('uk')) {
+    disclosure += `
+All processors have entered into Data Processing Agreements (DPAs) that comply with Article 28 of the GDPR.
+`;
+  }
+
+  return disclosure;
+}
+
+/**
+ * Generate consent language for checkout
+ */
+export function generateConsentLanguage(
+  companyName: string,
+  lawfulBasis: LawfulBasis,
+  includeMarketing: boolean
+): string {
+  let consent = `## Consent Language for AI-Assisted Checkout
+
+Use the following language at checkout or in order confirmations:
+
+### Order Processing Consent
+
+> By completing this purchase through an AI shopping assistant, you acknowledge that:
+> - Your order information will be processed by ${companyName} and the AI platform provider
+> - We will use your data to fulfill your order, process payment, and provide customer support
+> - Your data will be handled in accordance with our Privacy Policy
+`;
+
+  if (lawfulBasis === 'consent') {
+    consent += `
+### Explicit Consent (for consent-based processing)
+
+> [ ] I consent to ${companyName} processing my personal data for the purpose of completing this purchase and providing related services. I understand I can withdraw my consent at any time.
+`;
+  }
+
+  if (includeMarketing) {
+    consent += `
+### Marketing Consent (Optional)
+
+> [ ] I would like to receive marketing communications from ${companyName} about products, offers, and updates. I understand I can unsubscribe at any time.
+
+**Note**: Marketing consent must be:
+- Freely given (not a condition of purchase)
+- Specific and informed
+- Indicated by clear affirmative action (pre-ticked boxes are not valid consent)
+`;
+  }
+
+  consent += `
+### Agent-Originated Orders Notice
+
+> This order was initiated through an AI shopping assistant. The AI platform may retain conversation history in accordance with their privacy policy. Your transaction data with ${companyName} is subject to our Privacy Policy.
+`;
+
+  return consent;
+}
+
+/**
+ * Generate marketing opt-in text
+ */
+export function generateMarketingOptIn(companyName: string): string {
+  return `## Marketing Opt-In for Agent-Acquired Customers
+
+For customers acquired through AI shopping agents, use the following opt-in language:
+
+### Email Opt-In
+
+> [ ] Yes, I'd like to receive emails from ${companyName} about new products, exclusive offers, and updates. I can unsubscribe anytime using the link in each email.
+
+### SMS Opt-In (if applicable)
+
+> [ ] Yes, send me SMS updates about my orders and occasional promotions from ${companyName}. Message frequency varies. Reply STOP to unsubscribe. Message and data rates may apply.
+
+### Post-Purchase Marketing Request
+
+For customers who made purchases via AI agents without opting in, you may send ONE transactional follow-up:
+
+> Thank you for your recent purchase through [AI Agent Name]! Would you like to receive updates about new products and exclusive offers from ${companyName}?
+>
+> [Subscribe to Updates] [No Thanks]
+
+**Important**: Do not add customers to marketing lists without explicit consent. Agent-originated orders do not imply marketing permission.
+`;
+}
+
+/**
+ * Generate data subject rights notice
+ */
+export function generateDataSubjectRights(
+  companyName: string,
+  contactEmail: string,
+  dpoEmail: string | undefined,
+  regions: ComplianceRegion[]
+): string {
+  let rights = `## Your Data Rights (AI Commerce Transactions)
+
+You have the following rights regarding personal data collected through AI-assisted purchases:
+
+### Access and Portability
+- Request a copy of your personal data
+- Receive your data in a portable, machine-readable format
+
+### Correction and Deletion
+- Request correction of inaccurate data
+- Request deletion of your data (subject to legal retention requirements)
+
+### Objection and Restriction
+- Object to processing based on legitimate interests
+- Request restriction of processing in certain circumstances
+`;
+
+  if (regions.includes('eu') || regions.includes('uk')) {
+    rights += `
+### GDPR-Specific Rights
+- **Right to be Forgotten**: Request erasure under Article 17
+- **Right to Restrict Processing**: Under Article 18
+- **Right to Data Portability**: Under Article 20
+- **Right to Object**: Under Article 21
+- **Lodge a Complaint**: With your local data protection authority
+`;
+  }
+
+  if (regions.includes('california')) {
+    rights += `
+### CCPA/CPRA Rights
+- **Right to Know**: Categories and specific pieces of personal information collected
+- **Right to Delete**: Request deletion of personal information
+- **Right to Correct**: Request correction of inaccurate information
+- **Right to Opt-Out**: Of sale or sharing of personal information
+- **Right to Limit Use**: Of sensitive personal information
+`;
+  }
+
+  rights += `
+### How to Exercise Your Rights
+
+To exercise any of these rights, contact us:
+- **Email**: ${contactEmail}
+${dpoEmail ? `- **Data Protection Officer**: ${dpoEmail}` : ''}
+
+We will respond to your request within:
+${regions.includes('eu') || regions.includes('uk') ? '- **EU/UK**: 30 days (extendable by 60 days for complex requests)' : ''}
+${regions.includes('california') ? '- **California**: 45 days (extendable by 45 days if necessary)' : ''}
+
+### Verification
+
+To protect your privacy, we may need to verify your identity before processing your request. For orders placed through AI agents, we may ask for:
+- Order number or transaction ID
+- Email address used for the order
+- Delivery address associated with the order
+`;
+
+  return rights;
+}
+
+/**
+ * Generate tracking/cookie notice for agent transactions
+ */
+export function generateTrackingNotice(
+  companyName: string,
+  regions: ComplianceRegion[]
+): string {
+  let notice = `## Tracking and Cookies for AI Agent Transactions
+
+### How Tracking Works with AI Agents
+
+When you make a purchase through an AI shopping agent, the traditional cookie-based tracking model does not apply because:
+- You may never visit our website directly
+- The transaction occurs within the AI agent's interface
+- Standard cookie consent banners do not load
+
+### What Data is Collected
+
+For AI agent transactions, we collect data through:
+- **API Calls**: Order data transmitted via Universal Commerce Protocol (UCP)
+- **Transaction Logs**: Records of purchases for fulfillment and support
+- **Analytics**: Aggregated, anonymized data about AI agent sales (not linked to individuals)
+
+### Our Commitment
+
+- We do **not** place cookies on your device through AI agent transactions
+- We do **not** build behavioral profiles based solely on AI agent purchases
+- We **do** collect necessary transaction data to fulfill your order
+`;
+
+  if (regions.includes('eu') || regions.includes('uk')) {
+    notice += `
+### ePrivacy Compliance
+
+AI agent transactions are processed under:
+- **Strictly Necessary**: Processing required to complete your requested transaction
+- **Contract Performance**: Data processing necessary to deliver your order
+
+No consent is required for strictly necessary processing of transaction data.
+`;
+  }
+
+  notice += `
+### AI Platform Tracking
+
+The AI shopping agent (ChatGPT, Google AI, Copilot) may have its own data collection practices. Please review their privacy policies:
+- Conversation history with the AI agent
+- Usage data collected by the AI platform
+- Account information you've provided to the AI service
+
+${companyName} is not responsible for data collected directly by AI platform providers.
+`;
+
+  return notice;
+}
+
+/**
+ * Generate the legal disclaimer
+ */
+export function generateDisclaimer(): string {
+  return `---
+
+**IMPORTANT DISCLAIMER**
+
+This document was generated by an automated tool and is provided for informational purposes only. It does NOT constitute legal advice.
+
+- This template should be reviewed by a qualified legal professional before use
+- Privacy laws vary by jurisdiction and change frequently
+- Your specific business circumstances may require additional or different provisions
+- ${new Date().getFullYear()} compliance requirements may have changed since generation
+
+We recommend consulting with a privacy lawyer or data protection specialist to ensure your privacy policy fully complies with applicable laws.
+
+Generated by [UCP.tools](https://ucptools.dev) - AI Commerce Readiness Platform
+`;
+}

package/src/compliance/types.ts

@@ -0,0 +1,170 @@
+/**
+ * GDPR/Privacy Compliance Generator Types
+ * Types for generating privacy policy addendums and consent language
+ */
+
+// Supported regions/jurisdictions
+export type ComplianceRegion = 'eu' | 'uk' | 'california' | 'global';
+
+// GDPR Article 6 lawful bases
+export type LawfulBasis =
+  | 'contract'      // Performance of a contract
+  | 'consent'       // Consent
+  | 'legitimate'    // Legitimate interests
+  | 'legal';        // Legal obligation
+
+// AI agent platforms
+export type AgentPlatform =
+  | 'openai'        // ChatGPT Shopping
+  | 'google'        // Google AI Mode / Gemini
+  | 'microsoft'     // Microsoft Copilot
+  | 'other';
+
+// Input options for compliance generator
+export interface ComplianceGeneratorInput {
+  // Company information
+  companyName: string;
+  companyEmail?: string;
+  companyAddress?: string;
+  dpoEmail?: string;            // Data Protection Officer email
+
+  // Regions to comply with
+  regions: ComplianceRegion[];
+
+  // AI platforms being used
+  platforms: AgentPlatform[];
+
+  // Lawful basis for processing
+  lawfulBasis: LawfulBasis;
+
+  // Optional features
+  includeMarketingConsent?: boolean;
+  includeDataRetention?: boolean;
+  retentionPeriodYears?: number;
+
+  // Custom data processors
+  additionalProcessors?: DataProcessor[];
+}
+
+// Data processor information
+export interface DataProcessor {
+  name: string;
+  purpose: string;
+  country?: string;
+  privacyPolicyUrl?: string;
+}
+
+// Generated compliance document
+export interface ComplianceDocument {
+  title: string;
+  sections: ComplianceSection[];
+  disclaimer: string;
+  generatedAt: string;
+  regions: ComplianceRegion[];
+}
+
+// Section of a compliance document
+export interface ComplianceSection {
+  id: string;
+  title: string;
+  content: string;
+  required: boolean;
+  applicableRegions: ComplianceRegion[];
+}
+
+// Complete generator output
+export interface ComplianceGeneratorOutput {
+  // Full privacy policy addendum
+  privacyAddendum: ComplianceDocument;
+
+  // Individual snippets for easy copy/paste
+  snippets: {
+    // Privacy policy section for AI commerce
+    aiCommerceSection: string;
+
+    // Data processor disclosures
+    processorDisclosures: string;
+
+    // Consent language for checkout
+    consentLanguage: string;
+
+    // Marketing opt-in text
+    marketingOptIn?: string;
+
+    // Data subject rights notice
+    dataSubjectRights: string;
+
+    // Cookie/tracking notice for agent transactions
+    trackingNotice: string;
+  };
+
+  // Combined HTML for embedding
+  embedHtml: string;
+
+  // Plain text version
+  plainText: string;
+
+  // Metadata
+  generatedAt: string;
+  lawfulBasis: LawfulBasis;
+  regions: ComplianceRegion[];
+}
+
+// Predefined data processors for AI platforms
+export const AI_PLATFORM_PROCESSORS: Record<AgentPlatform, DataProcessor> = {
+  openai: {
+    name: 'OpenAI, LLC',
+    purpose: 'AI-powered shopping assistant and checkout processing',
+    country: 'United States',
+    privacyPolicyUrl: 'https://openai.com/privacy/',
+  },
+  google: {
+    name: 'Google LLC',
+    purpose: 'AI shopping agent (Google AI Mode, Gemini) and checkout processing',
+    country: 'United States',
+    privacyPolicyUrl: 'https://policies.google.com/privacy',
+  },
+  microsoft: {
+    name: 'Microsoft Corporation',
+    purpose: 'AI shopping assistant (Copilot) and checkout processing',
+    country: 'United States',
+    privacyPolicyUrl: 'https://privacy.microsoft.com/privacystatement',
+  },
+  other: {
+    name: 'Third-party AI Agent Provider',
+    purpose: 'AI-powered shopping and checkout assistance',
+    country: 'Various',
+  },
+};
+
+// Region display names
+export const REGION_NAMES: Record<ComplianceRegion, string> = {
+  eu: 'European Union (GDPR)',
+  uk: 'United Kingdom (UK GDPR)',
+  california: 'California (CCPA/CPRA)',
+  global: 'Global (General Best Practices)',
+};
+
+// Lawful basis descriptions
+export const LAWFUL_BASIS_DESCRIPTIONS: Record<LawfulBasis, { title: string; description: string; gdprArticle: string }> = {
+  contract: {
+    title: 'Performance of a Contract',
+    description: 'Processing is necessary for the performance of a contract with the data subject or to take steps at their request prior to entering into a contract.',
+    gdprArticle: 'Article 6(1)(b)',
+  },
+  consent: {
+    title: 'Consent',
+    description: 'The data subject has given consent to the processing of their personal data for one or more specific purposes.',
+    gdprArticle: 'Article 6(1)(a)',
+  },
+  legitimate: {
+    title: 'Legitimate Interests',
+    description: 'Processing is necessary for the purposes of the legitimate interests pursued by the controller or by a third party.',
+    gdprArticle: 'Article 6(1)(f)',
+  },
+  legal: {
+    title: 'Legal Obligation',
+    description: 'Processing is necessary for compliance with a legal obligation to which the controller is subject.',
+    gdprArticle: 'Article 6(1)(c)',
+  },
+};

package/src/db/index.ts

@@ -0,0 +1,28 @@
+import { drizzle, NeonHttpDatabase } from 'drizzle-orm/neon-http';
+import { neon } from '@neondatabase/serverless';
+import * as schema from './schema.js';
+
+// Type for our database instance
+type Database = NeonHttpDatabase<typeof schema>;
+
+// Lazy-loaded database instance (for serverless cold starts)
+let dbInstance: Database | null = null;
+
+/**
+ * Get the Drizzle database instance.
+ * Lazily creates the connection on first use.
+ */
+export function getDb(): Database {
+  if (!dbInstance) {
+    if (!process.env.DATABASE_URL) {
+      throw new Error('DATABASE_URL environment variable is not set');
+    }
+    const sql = neon(process.env.DATABASE_URL);
+    dbInstance = drizzle(sql, { schema });
+  }
+  return dbInstance;
+}
+
+// Re-export schema for convenience
+export * from './schema.js';
+export { schema };

package/src/db/schema.ts

@@ -0,0 +1,84 @@
+import {
+  pgTable,
+  uuid,
+  varchar,
+  text,
+  integer,
+  timestamp,
+  boolean,
+  index,
+  decimal,
+} from 'drizzle-orm/pg-core';
+
+/**
+ * Merchants table - stores UCP-enabled merchant directory entries
+ */
+export const merchants = pgTable(
+  'merchants',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // The merchant's primary domain (e.g., "example.com")
+    domain: varchar('domain', { length: 255 }).notNull().unique(),
+    // Display name for the merchant
+    displayName: varchar('display_name', { length: 255 }).notNull(),
+    // Optional description
+    description: text('description'),
+    // Logo URL
+    logoUrl: varchar('logo_url', { length: 512 }),
+    // Website URL (full URL including protocol)
+    websiteUrl: varchar('website_url', { length: 512 }),
+    // Category (e-commerce, saas, marketplace, etc.)
+    category: varchar('category', { length: 100 }),
+    // Country code (ISO 3166-1 alpha-2)
+    countryCode: varchar('country_code', { length: 2 }),
+    // UCP readiness score (0-100)
+    ucpScore: integer('ucp_score'),
+    // UCP grade (A, B, C, D, F)
+    ucpGrade: varchar('ucp_grade', { length: 2 }),
+    // Supported transports (comma-separated: REST, MCP, A2A, Embedded)
+    transports: varchar('transports', { length: 255 }),
+    // Whether the merchant has opted into the directory
+    isPublic: boolean('is_public').default(true).notNull(),
+    // Whether the merchant has been verified
+    isVerified: boolean('is_verified').default(false).notNull(),
+    // Last validation timestamp
+    lastValidatedAt: timestamp('last_validated_at'),
+    // Record timestamps
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at').defaultNow().notNull(),
+  },
+  (table) => [
+    index('idx_merchants_domain').on(table.domain),
+    index('idx_merchants_category').on(table.category),
+    index('idx_merchants_country').on(table.countryCode),
+    index('idx_merchants_score').on(table.ucpScore),
+    index('idx_merchants_public').on(table.isPublic),
+  ]
+);
+
+/**
+ * Benchmark stats table - stores aggregate validation statistics
+ * (migrated from setup script)
+ */
+export const benchmarkStats = pgTable('benchmark_stats', {
+  id: integer('id').primaryKey().generatedAlwaysAsIdentity(),
+  scoreBucket: integer('score_bucket').notNull().unique(),
+  count: integer('count').default(0).notNull(),
+});
+
+/**
+ * Benchmark summary table - quick aggregate stats
+ * (migrated from setup script)
+ */
+export const benchmarkSummary = pgTable('benchmark_summary', {
+  id: integer('id').primaryKey().default(1),
+  totalValidations: integer('total_validations').default(0).notNull(),
+  avgScore: decimal('avg_score', { precision: 5, scale: 2 }).default('0'),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});
+
+// Type exports for use in application code
+export type Merchant = typeof merchants.$inferSelect;
+export type NewMerchant = typeof merchants.$inferInsert;
+export type BenchmarkStat = typeof benchmarkStats.$inferSelect;
+export type BenchmarkSummary = typeof benchmarkSummary.$inferSelect;