@ucptools/validator 1.0.0

package/apify-actor/main.ts

@@ -0,0 +1,111 @@
+/**
+ * UCP Profile Validator - Apify Actor
+ * Validates any domain's UCP Business Profile at /.well-known/ucp
+ *
+ * Free tier: validation + report
+ * Paid tier: generation + monitoring
+ */
+
+import { Actor } from 'apify';
+import { validateRemote, validateQuick } from '../src/validator/index.js';
+
+interface Input {
+  domain: string;
+  mode?: 'quick' | 'full';
+  includeRecommendations?: boolean;
+}
+
+interface Output {
+  domain: string;
+  profileUrl: string;
+  valid: boolean;
+  score: number;
+  grade: 'A' | 'B' | 'C' | 'D' | 'F';
+  ucpVersion?: string;
+  errors: number;
+  warnings: number;
+  issues: Array<{
+    severity: string;
+    code: string;
+    message: string;
+    hint?: string;
+  }>;
+  recommendations?: string[];
+  checkedAt: string;
+  // CTA for monetization
+  upgradeUrl: string;
+}
+
+await Actor.init();
+
+const input = await Actor.getInput<Input>();
+
+if (!input?.domain) {
+  throw new Error('Missing required input: domain');
+}
+
+const domain = input.domain.replace(/^https?:\/\//, '').replace(/\/$/, '');
+
+console.log(`Validating UCP profile for: ${domain}`);
+
+const report = await validateRemote(domain, {
+  mode: input.mode === 'quick' ? 'rules' : 'full',
+});
+
+const profileUrl = report.profile_url || `https://${domain}/.well-known/ucp`;
+
+// Calculate score (0-100)
+const errorWeight = 20;
+const warnWeight = 5;
+const errors = report.issues.filter(i => i.severity === 'error').length;
+const warnings = report.issues.filter(i => i.severity === 'warn').length;
+const score = Math.max(0, 100 - (errors * errorWeight) - (warnings * warnWeight));
+
+// Calculate grade
+const grade = score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';
+
+// Generate recommendations
+const recommendations: string[] = [];
+if (errors > 0) {
+  recommendations.push('Fix all errors before going live with UCP-enabled agents');
+}
+if (!report.ucp_version) {
+  recommendations.push('Ensure your profile is accessible at /.well-known/ucp');
+}
+if (report.issues.some(i => i.code === 'UCP_MISSING_SIGNING_KEYS')) {
+  recommendations.push('Add signing_keys if you plan to use Order capability with webhooks');
+}
+if (report.issues.some(i => i.code === 'UCP_ENDPOINT_NOT_HTTPS')) {
+  recommendations.push('All endpoints must use HTTPS for security');
+}
+if (score === 100) {
+  recommendations.push('Your profile is fully compliant! Consider adding more capabilities.');
+}
+
+const output: Output = {
+  domain,
+  profileUrl,
+  valid: report.ok,
+  score,
+  grade,
+  ucpVersion: report.ucp_version,
+  errors,
+  warnings,
+  issues: report.issues.map(i => ({
+    severity: i.severity,
+    code: i.code,
+    message: i.message,
+    hint: i.hint,
+  })),
+  recommendations: input.includeRecommendations !== false ? recommendations : undefined,
+  checkedAt: report.validated_at,
+  upgradeUrl: 'https://ucp.tools/generate?ref=apify',
+};
+
+console.log(`\nValidation complete: ${grade} (${score}/100)`);
+console.log(`Errors: ${errors}, Warnings: ${warnings}`);
+
+await Actor.pushData(output);
+await Actor.setValue('OUTPUT', output);
+
+await Actor.exit();

package/apify-actor/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "ucp-profile-validator-actor",
+  "version": "1.0.0",
+  "description": "Apify Actor: Validate UCP Business Profiles",
+  "type": "module",
+  "main": "src/main.js",
+  "scripts": {
+    "start": "node src/main.js",
+    "test": "echo \"No tests yet\""
+  },
+  "dependencies": {
+    "apify": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/apify-actor/src/main.js

@@ -0,0 +1,199 @@
+/**
+ * UCP Profile Validator - Apify Actor
+ * Validates any domain's UCP Business Profile at /.well-known/ucp
+ */
+
+import { Actor } from 'apify';
+
+const VERSION_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+async function fetchProfile(domain) {
+  // Try both /.well-known/ucp and /.well-known/ucp.json
+  const urls = [
+    `https://${domain}/.well-known/ucp`,
+    `https://${domain}/.well-known/ucp.json`,
+  ];
+
+  for (const url of urls) {
+    try {
+      const res = await fetch(url, {
+        headers: { 'Accept': 'application/json', 'User-Agent': 'UCP-Validator-Apify/1.0' },
+        signal: AbortSignal.timeout(15000),
+      });
+
+      if (!res.ok) continue;
+
+      const text = await res.text();
+      // Check if response looks like JSON (not HTML)
+      if (text.trim().startsWith('<')) continue;
+
+      const profile = JSON.parse(text);
+      return { profile, profileUrl: url };
+    } catch (e) {
+      // Try next URL
+      continue;
+    }
+  }
+
+  return { profile: null, error: 'No UCP profile found at /.well-known/ucp or /.well-known/ucp.json' };
+}
+
+function validateProfile(profile) {
+  const issues = [];
+
+  if (!profile || typeof profile !== 'object') {
+    issues.push({ severity: 'error', code: 'UCP_MISSING_ROOT', path: '$', message: 'Profile must be a JSON object' });
+    return issues;
+  }
+
+  if (!profile.ucp || typeof profile.ucp !== 'object') {
+    issues.push({ severity: 'error', code: 'UCP_MISSING_ROOT', path: '$.ucp', message: 'Missing required "ucp" object' });
+    return issues;
+  }
+
+  const ucp = profile.ucp;
+
+  // Version validation
+  if (!ucp.version) {
+    issues.push({ severity: 'error', code: 'UCP_MISSING_VERSION', path: '$.ucp.version', message: 'Missing version field' });
+  } else if (!VERSION_REGEX.test(ucp.version)) {
+    issues.push({ severity: 'error', code: 'UCP_INVALID_VERSION', path: '$.ucp.version', message: `Invalid version: ${ucp.version}`, hint: 'Use YYYY-MM-DD format' });
+  }
+
+  // Services validation
+  if (!ucp.services || typeof ucp.services !== 'object') {
+    issues.push({ severity: 'error', code: 'UCP_MISSING_SERVICES', path: '$.ucp.services', message: 'Missing services' });
+  } else {
+    for (const [name, svc] of Object.entries(ucp.services)) {
+      if (!svc.version) issues.push({ severity: 'error', code: 'UCP_INVALID_SERVICE', path: `$.ucp.services["${name}"].version`, message: `Service "${name}" missing version` });
+      if (!svc.spec) issues.push({ severity: 'error', code: 'UCP_INVALID_SERVICE', path: `$.ucp.services["${name}"].spec`, message: `Service "${name}" missing spec` });
+      if (!svc.rest && !svc.mcp && !svc.a2a && !svc.embedded) {
+        issues.push({ severity: 'warn', code: 'UCP_NO_TRANSPORT', path: `$.ucp.services["${name}"]`, message: `Service "${name}" has no transport bindings` });
+      }
+      if (svc.rest?.endpoint) {
+        if (!svc.rest.endpoint.startsWith('https://')) {
+          issues.push({ severity: 'error', code: 'UCP_ENDPOINT_NOT_HTTPS', path: `$.ucp.services["${name}"].rest.endpoint`, message: 'Endpoint must use HTTPS' });
+        }
+        if (svc.rest.endpoint.endsWith('/')) {
+          issues.push({ severity: 'warn', code: 'UCP_TRAILING_SLASH', path: `$.ucp.services["${name}"].rest.endpoint`, message: 'Remove trailing slash' });
+        }
+      }
+    }
+  }
+
+  // Capabilities validation
+  if (!ucp.capabilities || !Array.isArray(ucp.capabilities)) {
+    issues.push({ severity: 'error', code: 'UCP_MISSING_CAPABILITIES', path: '$.ucp.capabilities', message: 'Missing capabilities array' });
+  } else {
+    const capNames = new Set(ucp.capabilities.map(c => c.name));
+    ucp.capabilities.forEach((cap, i) => {
+      const path = `$.ucp.capabilities[${i}]`;
+      if (!cap.name) issues.push({ severity: 'error', code: 'UCP_INVALID_CAP', path: `${path}.name`, message: 'Missing name' });
+      if (!cap.version) issues.push({ severity: 'error', code: 'UCP_INVALID_CAP', path: `${path}.version`, message: 'Missing version' });
+      if (!cap.spec) issues.push({ severity: 'error', code: 'UCP_INVALID_CAP', path: `${path}.spec`, message: 'Missing spec' });
+      if (!cap.schema) issues.push({ severity: 'error', code: 'UCP_INVALID_CAP', path: `${path}.schema`, message: 'Missing schema' });
+
+      // Namespace checks
+      if (cap.name?.startsWith('dev.ucp.')) {
+        if (cap.spec && !cap.spec.startsWith('https://ucp.dev/')) {
+          issues.push({ severity: 'error', code: 'UCP_NS_MISMATCH', path: `${path}.spec`, message: 'dev.ucp.* spec must be on ucp.dev' });
+        }
+        if (cap.schema && !cap.schema.startsWith('https://ucp.dev/')) {
+          issues.push({ severity: 'error', code: 'UCP_NS_MISMATCH', path: `${path}.schema`, message: 'dev.ucp.* schema must be on ucp.dev' });
+        }
+      }
+
+      // Extension checks
+      if (cap.extends && !capNames.has(cap.extends)) {
+        issues.push({ severity: 'error', code: 'UCP_ORPHAN_EXT', path: `${path}.extends`, message: `Parent "${cap.extends}" not found` });
+      }
+    });
+
+    // Signing keys check
+    const hasOrder = ucp.capabilities.some(c => c.name === 'dev.ucp.shopping.order');
+    if (hasOrder && (!profile.signing_keys || profile.signing_keys.length === 0)) {
+      issues.push({ severity: 'error', code: 'UCP_MISSING_KEYS', path: '$.signing_keys', message: 'Order requires signing_keys' });
+    }
+  }
+
+  return issues;
+}
+
+await Actor.init();
+
+const input = await Actor.getInput();
+
+if (!input?.domain) {
+  throw new Error('Missing required input: domain');
+}
+
+const domain = input.domain.replace(/^https?:\/\//, '').replace(/\/$/, '');
+
+console.log(`🔍 Validating UCP profile for: ${domain}`);
+
+const { profile, profileUrl: foundProfileUrl, error } = await fetchProfile(domain);
+const profileUrl = foundProfileUrl || `https://${domain}/.well-known/ucp`;
+
+let issues = [];
+let ucpVersion = null;
+
+if (error || !profile) {
+  issues.push({
+    severity: 'error',
+    code: 'UCP_FETCH_FAILED',
+    path: '$.well-known/ucp',
+    message: error || 'Failed to fetch profile',
+  });
+} else {
+  issues = validateProfile(profile);
+  ucpVersion = profile?.ucp?.version;
+}
+
+// Calculate score
+const errors = issues.filter(i => i.severity === 'error').length;
+const warnings = issues.filter(i => i.severity === 'warn').length;
+const score = Math.max(0, 100 - (errors * 20) - (warnings * 5));
+const grade = score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';
+
+// Recommendations
+const recommendations = [];
+if (errors > 0) recommendations.push('Fix all errors before deploying');
+if (!ucpVersion) recommendations.push('Ensure profile is accessible at /.well-known/ucp');
+if (issues.some(i => i.code === 'UCP_MISSING_KEYS')) recommendations.push('Add signing_keys for Order capability');
+if (score === 100) recommendations.push('Profile is fully compliant!');
+
+const output = {
+  domain,
+  profileUrl,
+  valid: errors === 0,
+  score,
+  grade,
+  ucpVersion,
+  errors,
+  warnings,
+  issues: issues.map(i => ({
+    severity: i.severity,
+    code: i.code,
+    message: i.message,
+    hint: i.hint,
+  })),
+  recommendations: input.includeRecommendations !== false ? recommendations : undefined,
+  checkedAt: new Date().toISOString(),
+  generatorUrl: 'https://ucptools.dev/generate',
+};
+
+console.log(`\n📊 Result: ${grade} (${score}/100)`);
+console.log(`   Errors: ${errors}, Warnings: ${warnings}`);
+if (errors === 0) {
+  console.log('✅ Profile is valid!');
+} else {
+  console.log('❌ Profile has issues that need to be fixed');
+}
+
+// Push result to dataset
+// Note: Using PPE with synthetic 'apify-default-dataset-item' event
+// This automatically charges users per result - no manual Actor.charge() needed
+await Actor.pushData(output);
+await Actor.setValue('OUTPUT', output);
+
+await Actor.exit();

package/docs/BRAND-IDENTITY.md

@@ -0,0 +1,238 @@
+# UCP.tools - Brand Identity Guide
+
+## Brand Overview
+
+**UCP.tools** is an independent developer tool that helps merchants prepare for AI-powered commerce by validating and generating Universal Commerce Protocol (UCP) business profiles.
+
+---
+
+## Brand Name & Variations
+
+| Context | Usage |
+|---------|-------|
+| **Primary** | UCP.tools |
+| **Domain** | ucptools.dev (or ucptools.io as fallback) |
+| **Apify Actor** | UCP Profile Validator |
+| **npm package** | ucp-profile-tools |
+| **GitHub** | ucp-tools |
+| **Tagline** | "Get ready for AI commerce" |
+| **Short tagline** | "Validate. Generate. Ship." |
+
+---
+
+## Brand Voice & Personality
+
+### Tone
+- **Developer-first**: Technical but approachable
+- **Direct**: No fluff, get to the point
+- **Helpful**: Focus on solving problems
+- **Independent**: Not affiliated with any platform
+
+### Language Style
+- Use "you/your" not "users/merchants"
+- Active voice: "Validate your profile" not "Profiles can be validated"
+- Confident: "Fix issues instantly" not "May help fix issues"
+- No corporate jargon: "Check" not "Leverage our validation capabilities"
+
+### Example Copy
+
+**Good:**
+> "Your UCP profile has 2 errors. Here's how to fix them."
+
+**Bad:**
+> "Our comprehensive validation engine has detected potential compliance issues in your Universal Commerce Protocol business profile configuration."
+
+---
+
+## Visual Identity
+
+### Colors
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| **Primary Blue** | `#2563eb` | Buttons, links, accents |
+| **Primary Dark** | `#1d4ed8` | Hover states |
+| **Success Green** | `#16a34a` | Valid, success states |
+| **Warning Amber** | `#ca8a04` | Warnings |
+| **Error Red** | `#dc2626` | Errors, invalid states |
+| **Background** | `#f8fafc` | Page background |
+| **Card White** | `#ffffff` | Cards, panels |
+| **Text Dark** | `#1e293b` | Primary text |
+| **Text Muted** | `#64748b` | Secondary text |
+| **Border** | `#e2e8f0` | Borders, dividers |
+
+### Typography
+
+- **Headings**: System font stack (SF Pro, Segoe UI, Roboto)
+- **Body**: Same system font stack
+- **Code**: Monospace (SF Mono, Consolas, Monaco)
+- **Font weights**: 400 (normal), 500 (medium), 600 (semibold), 700 (bold)
+
+### Logo Concepts
+
+**Text Logo:**
+```
+UCP.tools
+```
+- "UCP" in Primary Blue (#2563eb), bold
+- ".tools" in Text Muted (#64748b), normal weight
+
+**Icon Concepts:**
+- Checkmark inside a document/file icon
+- Shield with checkmark (security/validation)
+- Interconnected nodes (protocol/commerce)
+
+### Grade Badges (Validation Scores)
+
+| Grade | Background | Text Color |
+|-------|------------|------------|
+| A | `#dcfce7` | `#16a34a` |
+| B | `#dbeafe` | `#2563eb` |
+| C | `#fef9c3` | `#ca8a04` |
+| D | `#fed7aa` | `#ea580c` |
+| F | `#fee2e2` | `#dc2626` |
+
+---
+
+## Messaging Framework
+
+### Elevator Pitch (10 seconds)
+> "UCP.tools validates and generates UCP business profiles so your store is ready for AI shopping agents."
+
+### Short Description (30 seconds)
+> "UCP.tools is a free validator and generator for Universal Commerce Protocol profiles. Check if your /.well-known/ucp endpoint is correct, generate compliant profiles, and get ready for AI-powered commerce - in seconds."
+
+### Full Description (Product Hunt / Apify Store)
+> "The Universal Commerce Protocol (UCP) lets AI agents discover and transact with online stores. But getting your profile right is tricky - wrong namespaces, missing fields, and endpoint issues break agent compatibility.
+>
+> UCP.tools fixes that:
+> - **Validate** any domain's UCP profile instantly
+> - **Generate** compliant profiles with a simple wizard
+> - **Get actionable fixes** for every issue found
+> - **Score your readiness** with A-F grades
+>
+> Free to use. No signup required. Built by developers, for developers."
+
+### Key Messages
+
+1. **Problem**: "AI agents can't discover your store if your UCP profile is broken"
+2. **Solution**: "Validate and fix your profile in seconds"
+3. **Proof**: "Checks all UCP spec rules: namespaces, endpoints, signing keys"
+4. **CTA**: "Check your profile free at ucptools.dev"
+
+---
+
+## Target Audience
+
+### Primary: Developers & Technical Founders
+- Building on headless commerce (Medusa, Saleor, custom)
+- Care about standards compliance
+- Comfortable with JSON/APIs
+- Value speed and accuracy
+
+### Secondary: E-commerce Agencies
+- Managing multiple client stores
+- Need bulk validation
+- Want white-label reports
+
+### Tertiary: Non-technical Merchants
+- Shopify/WooCommerce store owners
+- Need simple "is it working?" check
+- May upgrade to managed service
+
+---
+
+## Competitive Positioning
+
+### We Are
+- Free and instant
+- Developer-focused
+- Independent (not affiliated with Google/Shopify)
+- Self-serve first
+
+### We Are Not
+- Enterprise sales motion
+- Full UCP implementation service
+- Platform-specific (works with any backend)
+
+### Differentiators
+| Feature | UCP.tools | UCP Ready | WellKnown | UCP Playground |
+|---------|-----------|-----------|-----------|----------------|
+| Free validation | ✅ Unlimited | Limited | ❌ | Demo only |
+| Profile generation | ✅ | ❌ | ❌ | ❌ |
+| CLI/API access | ✅ | ❌ | ❌ | ❌ |
+| No signup | ✅ | ? | ❌ | ✅ |
+
+---
+
+## Content Guidelines
+
+### Headlines
+- Lead with benefit: "Validate Your UCP Profile" not "UCP Validation Tool"
+- Use numbers: "Fix 12 common UCP errors" not "Fix UCP errors"
+- Create urgency: "AI agents are coming. Is your store ready?"
+
+### Call-to-Actions
+- Primary: "Validate Now" / "Check Your Profile"
+- Secondary: "Generate Profile" / "Download JSON"
+- Tertiary: "See Pricing" / "Get Pro"
+
+### Error Messages
+- Be specific: "Endpoint must use HTTPS" not "Invalid endpoint"
+- Be helpful: Include "hint" with fix suggestion
+- Be human: "Oops, we couldn't reach your profile" not "Error 404"
+
+---
+
+## Social Media Templates
+
+### Twitter/X Bio
+> Free UCP profile validator & generator. Get your store ready for AI commerce agents. ⚡ Instant results, no signup.
+
+### Product Hunt Tagline
+> Validate and generate UCP profiles for AI-powered commerce
+
+### GitHub Description
+> Free, open-source UCP (Universal Commerce Protocol) profile validator and generator. CLI + API + Web UI.
+
+---
+
+## Legal & Disclaimers
+
+### Standard Disclaimer
+> "UCP.tools is an independent project and is not affiliated with, endorsed by, or sponsored by Google, Shopify, or the Universal Commerce Protocol working group."
+
+### Open Source Notice
+> "UCP.tools is open source under the MIT license. The UCP specification is maintained by the UCP working group."
+
+---
+
+## Asset Checklist for Launch
+
+- [ ] Logo (SVG, PNG @1x, @2x)
+- [ ] Favicon (16x16, 32x32, apple-touch-icon)
+- [ ] Open Graph image (1200x630)
+- [ ] Twitter card image (1200x600)
+- [ ] Product Hunt thumbnail (240x240)
+- [ ] Apify Actor icon (256x256)
+- [ ] Screenshots (web UI, CLI output, validation report)
+
+---
+
+## GPT Prompt for Brand-Consistent Content
+
+When generating content for UCP.tools, use this context:
+
+```
+You are writing for UCP.tools, a free developer tool that validates and generates Universal Commerce Protocol (UCP) business profiles.
+
+Brand voice: Developer-first, direct, helpful, independent
+Target audience: Developers building e-commerce, technical founders, agencies
+Key differentiator: Free, instant, no signup, generates profiles (not just validates)
+
+Avoid: Corporate jargon, "leverage", "utilize", "comprehensive solution"
+Use: "Check", "fix", "validate", "generate", "your profile", "instant"
+
+Colors: Blue (#2563eb), Green for success, Red for errors
+Tagline: "Get ready for AI commerce"
+```