ucpify 1.0.0

package/dist/ucp-server.js

@@ -0,0 +1,331 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UCPServer = void 0;
+const uuid_1 = require("uuid");
+const schema_1 = require("./schema");
+// In-memory stores
+const checkoutSessions = new Map();
+const orders = new Map();
+class UCPServer {
+    config;
+    itemsMap;
+    constructor(config) {
+        this.config = config;
+        this.itemsMap = new Map(config.items.map((item) => [item.id, item]));
+    }
+    // Generate UCP profile for /.well-known/ucp
+    getProfile() {
+        const paymentHandlers = {};
+        for (const handler of this.config.payment_handlers) {
+            paymentHandlers[handler.namespace] = [
+                {
+                    id: handler.id,
+                    version: schema_1.UCP_VERSION,
+                    config: handler.config,
+                },
+            ];
+        }
+        return {
+            ucp: {
+                version: schema_1.UCP_VERSION,
+                services: {
+                    'dev.ucp.shopping': [
+                        {
+                            version: schema_1.UCP_VERSION,
+                            spec: 'https://ucp.dev/specification/overview',
+                            transport: 'rest',
+                            endpoint: `${this.config.domain}/ucp/v1`,
+                            schema: 'https://ucp.dev/services/shopping/rest.openapi.json',
+                        },
+                    ],
+                },
+                capabilities: {
+                    'dev.ucp.shopping.checkout': [
+                        {
+                            version: schema_1.UCP_VERSION,
+                            spec: 'https://ucp.dev/specification/checkout',
+                            schema: 'https://ucp.dev/schemas/shopping/checkout.json',
+                        },
+                    ],
+                    'dev.ucp.shopping.fulfillment': [
+                        {
+                            version: schema_1.UCP_VERSION,
+                            spec: 'https://ucp.dev/specification/fulfillment',
+                            schema: 'https://ucp.dev/schemas/shopping/fulfillment.json',
+                            extends: 'dev.ucp.shopping.checkout',
+                        },
+                    ],
+                    'dev.ucp.shopping.order': [
+                        {
+                            version: schema_1.UCP_VERSION,
+                            spec: 'https://ucp.dev/specification/order',
+                            schema: 'https://ucp.dev/schemas/shopping/order.json',
+                        },
+                    ],
+                },
+                payment_handlers: paymentHandlers,
+            },
+        };
+    }
+    // Calculate totals for line items
+    calculateLineItemTotals(lineItems) {
+        const subtotal = lineItems.reduce((sum, li) => sum + li.item.price * li.quantity, 0);
+        const tax = Math.round(subtotal * this.config.tax_rate);
+        return [
+            { type: 'subtotal', amount: subtotal },
+            { type: 'tax', amount: tax },
+            { type: 'total', amount: subtotal + tax },
+        ];
+    }
+    // Validate checkout and generate messages
+    validateCheckout(session) {
+        const messages = [];
+        if (!session.buyer?.email) {
+            messages.push({
+                type: 'error',
+                code: 'missing',
+                path: '$.buyer.email',
+                content: 'Buyer email is required',
+                severity: 'recoverable',
+            });
+        }
+        if (!session.fulfillment?.methods?.[0]?.selected_destination_id) {
+            messages.push({
+                type: 'error',
+                code: 'missing',
+                path: '$.fulfillment.methods[0].selected_destination_id',
+                content: 'Shipping address is required',
+                severity: 'recoverable',
+            });
+        }
+        return messages;
+    }
+    // Create checkout session
+    createCheckout(data) {
+        const id = `chk_${(0, uuid_1.v4)().replace(/-/g, '').slice(0, 12)}`;
+        // Resolve items from catalog or use provided
+        const lineItems = data.line_items.map((li, idx) => {
+            const catalogItem = this.itemsMap.get(li.item.id);
+            const item = catalogItem || {
+                id: li.item.id,
+                title: li.item.title || 'Unknown Item',
+                price: li.item.price || 0,
+            };
+            const subtotal = item.price * li.quantity;
+            return {
+                id: li.id || `li_${idx + 1}`,
+                item,
+                quantity: li.quantity,
+                totals: [
+                    { type: 'subtotal', amount: subtotal },
+                    { type: 'total', amount: subtotal },
+                ],
+            };
+        });
+        const totals = this.calculateLineItemTotals(lineItems);
+        const messages = this.validateCheckout({ line_items: lineItems });
+        const paymentHandlers = {};
+        for (const handler of this.config.payment_handlers) {
+            paymentHandlers[handler.namespace] = [{ id: handler.id, version: schema_1.UCP_VERSION, config: handler.config }];
+        }
+        // Build links
+        const links = [];
+        if (this.config.terms_url) {
+            links.push({ type: 'terms_of_service', url: this.config.terms_url });
+        }
+        if (this.config.privacy_url) {
+            links.push({ type: 'privacy_policy', url: this.config.privacy_url });
+        }
+        // Set expiry (1 hour from now)
+        const expiresAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const session = {
+            ucp: {
+                version: schema_1.UCP_VERSION,
+                capabilities: {
+                    'dev.ucp.shopping.checkout': [{ version: schema_1.UCP_VERSION }],
+                },
+                payment_handlers: paymentHandlers,
+            },
+            id,
+            status: messages.length > 0 ? 'incomplete' : 'ready_for_complete',
+            messages: messages.length > 0 ? messages : undefined,
+            currency: this.config.currency,
+            line_items: lineItems,
+            totals,
+            links,
+            continue_url: `${this.config.domain}/checkout/${id}`,
+            expires_at: expiresAt,
+        };
+        checkoutSessions.set(id, session);
+        return session;
+    }
+    // Get checkout session
+    getCheckout(id) {
+        return checkoutSessions.get(id);
+    }
+    // Update checkout session
+    updateCheckout(id, data) {
+        const session = checkoutSessions.get(id);
+        if (!session)
+            return undefined;
+        // Update buyer
+        if (data.buyer) {
+            session.buyer = { ...session.buyer, ...data.buyer };
+        }
+        // Update line items
+        if (data.line_items) {
+            session.line_items = data.line_items.map((li, idx) => {
+                const catalogItem = this.itemsMap.get(li.item.id);
+                const item = catalogItem || {
+                    id: li.item.id,
+                    title: li.item.title || 'Unknown Item',
+                    price: li.item.price || 0,
+                };
+                const subtotal = item.price * li.quantity;
+                return {
+                    id: li.id || `li_${idx + 1}`,
+                    item,
+                    quantity: li.quantity,
+                    totals: [
+                        { type: 'subtotal', amount: subtotal },
+                        { type: 'total', amount: subtotal },
+                    ],
+                };
+            });
+        }
+        // Update fulfillment with shipping options
+        if (data.fulfillment) {
+            const methods = data.fulfillment.methods.map((method, mIdx) => {
+                const destinations = method.destinations.map((dest, dIdx) => ({
+                    ...dest,
+                    id: dest.id || `dest_${dIdx + 1}`,
+                }));
+                const groups = method.groups?.length
+                    ? method.groups
+                    : [
+                        {
+                            id: `group_${mIdx + 1}`,
+                            line_item_ids: session.line_items.map((li) => li.id),
+                            selected_option_id: this.config.shipping_options[0]?.id,
+                            options: this.config.shipping_options.map((opt) => ({
+                                id: opt.id,
+                                title: opt.title,
+                                description: opt.description || opt.estimated_days,
+                                totals: [{ type: 'total', amount: opt.price }],
+                            })),
+                        },
+                    ];
+                return {
+                    id: method.id || `method_${mIdx + 1}`,
+                    type: method.type,
+                    line_item_ids: method.line_item_ids || session.line_items.map((li) => li.id),
+                    selected_destination_id: method.selected_destination_id || destinations[0]?.id,
+                    destinations,
+                    groups,
+                };
+            });
+            session.fulfillment = { methods };
+        }
+        // Recalculate totals including shipping
+        let shippingTotal = 0;
+        if (session.fulfillment) {
+            for (const method of session.fulfillment.methods) {
+                for (const group of method.groups) {
+                    const selectedOption = group.options.find((o) => o.id === group.selected_option_id);
+                    if (selectedOption) {
+                        const total = selectedOption.totals.find((t) => t.type === 'total');
+                        shippingTotal += total?.amount || 0;
+                    }
+                }
+            }
+        }
+        const subtotal = session.line_items.reduce((sum, li) => sum + li.item.price * li.quantity, 0);
+        const tax = Math.round(subtotal * this.config.tax_rate);
+        session.totals = [
+            { type: 'subtotal', amount: subtotal },
+            { type: 'shipping', amount: shippingTotal },
+            { type: 'tax', amount: tax },
+            { type: 'total', amount: subtotal + shippingTotal + tax },
+        ];
+        // Revalidate
+        const newMessages = this.validateCheckout(session);
+        session.messages = newMessages.length > 0 ? newMessages : undefined;
+        session.status = newMessages.length > 0 ? 'incomplete' : 'ready_for_complete';
+        checkoutSessions.set(id, session);
+        return session;
+    }
+    // Complete checkout (create order)
+    async completeCheckout(id) {
+        const session = checkoutSessions.get(id);
+        if (!session)
+            return { error: 'Checkout session not found' };
+        if (session.status !== 'ready_for_complete') {
+            return { error: 'Checkout is not ready for completion', messages: session.messages };
+        }
+        const orderId = `order_${(0, uuid_1.v4)().replace(/-/g, '').slice(0, 12)}`;
+        const order = {
+            ucp: {
+                version: schema_1.UCP_VERSION,
+                capabilities: {
+                    'dev.ucp.shopping.order': [{ version: schema_1.UCP_VERSION }],
+                },
+            },
+            id: orderId,
+            checkout_id: id,
+            permalink_url: `${this.config.domain}/orders/${orderId}`,
+            line_items: session.line_items,
+            buyer: session.buyer,
+            totals: session.totals,
+            fulfillment: session.fulfillment
+                ? {
+                    expectations: session.fulfillment.methods.map((m, idx) => ({
+                        id: `exp_${idx + 1}`,
+                        line_items: m.line_item_ids.map((liId) => {
+                            const li = session.line_items.find((l) => l.id === liId);
+                            return { id: liId, quantity: li?.quantity || 1 };
+                        }),
+                        method_type: m.type,
+                        destination: m.destinations.find((d) => d.id === m.selected_destination_id),
+                        description: 'Arrives in 5-7 business days',
+                        fulfillable_on: 'now',
+                    })),
+                    events: [],
+                }
+                : undefined,
+            created_at: new Date().toISOString(),
+        };
+        orders.set(orderId, order);
+        // Update session to completed state with order confirmation
+        session.status = 'completed';
+        session.order = {
+            id: orderId,
+            permalink_url: order.permalink_url,
+        };
+        delete session.continue_url;
+        delete session.messages;
+        checkoutSessions.set(id, session);
+        return session;
+    }
+    // Cancel checkout
+    cancelCheckout(id) {
+        const session = checkoutSessions.get(id);
+        if (!session)
+            return undefined;
+        session.status = 'canceled';
+        delete session.continue_url;
+        checkoutSessions.set(id, session);
+        return session;
+    }
+    // Get order
+    getOrder(id) {
+        return orders.get(id);
+    }
+    // List orders
+    listOrders() {
+        return Array.from(orders.values());
+    }
+    getConfig() {
+        return this.config;
+    }
+}
+exports.UCPServer = UCPServer;

package/merchant-config.json

@@ -0,0 +1,64 @@
+{
+  "name": "My Store",
+  "domain": "http://localhost:3000",
+  "currency": "USD",
+  "terms_url": "https://example.com/terms",
+  "privacy_url": "https://example.com/privacy",
+  "tax_rate": 0.08,
+  "port": 3000,
+  "items": [
+    {
+      "id": "item_001",
+      "title": "Classic T-Shirt",
+      "description": "A comfortable cotton t-shirt",
+      "price": 2500,
+      "sku": "TSH-001"
+    },
+    {
+      "id": "item_002",
+      "title": "Premium Hoodie",
+      "description": "Warm and stylish hoodie",
+      "price": 5999,
+      "sku": "HOO-001"
+    }
+  ],
+  "shipping_options": [
+    {
+      "id": "standard",
+      "title": "Standard Shipping",
+      "description": "Arrives in 5-7 business days",
+      "price": 500,
+      "estimated_days": "5-7 business days"
+    },
+    {
+      "id": "express",
+      "title": "Express Shipping",
+      "description": "Arrives in 2-3 business days",
+      "price": 1500,
+      "estimated_days": "2-3 business days"
+    },
+    {
+      "id": "overnight",
+      "title": "Overnight Shipping",
+      "description": "Arrives next business day",
+      "price": 2999,
+      "estimated_days": "1 business day"
+    }
+  ],
+  "payment_handlers": [
+    {
+      "namespace": "com.stripe",
+      "id": "stripe_handler",
+      "config": {
+        "publishable_key": "pk_test_..."
+      }
+    },
+    {
+      "namespace": "com.paypal",
+      "id": "paypal_handler",
+      "config": {
+        "client_id": "your_paypal_client_id"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ucpify",
+  "version": "1.0.0",
+  "description": "Generate UCP-compliant servers for merchants from a simple schema",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ucpify": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "ts-node src/cli.ts",
+    "init": "ts-node src/cli.ts init",
+    "serve": "ts-node src/cli.ts serve",
+    "validate": "ts-node src/cli.ts validate",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "ucp",
+    "commerce",
+    "checkout",
+    "agentic",
+    "ai-commerce"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "@paypal/paypal-server-sdk": "^2.2.0",
+    "better-sqlite3": "^12.6.2",
+    "commander": "^14.0.2",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
+    "pino": "^10.3.0",
+    "stripe": "^20.3.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.1.0",
+    "@types/supertest": "^6.0.3",
+    "@types/uuid": "^10.0.0",
+    "supertest": "^7.2.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/__tests__/api.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import request from 'supertest';
+import { createExpressApp } from '../express-app';
+import { MerchantConfig } from '../schema';
+
+const testConfig: MerchantConfig = {
+  name: 'Test Store',
+  domain: 'https://test.example.com',
+  currency: 'USD',
+  port: 3000,
+  items: [
+    { id: 'item-1', title: 'Test Item', price: 1000 },
+    { id: 'item-2', title: 'Another Item', price: 2500 },
+  ],
+  shipping_options: [
+    { id: 'standard', title: 'Standard Shipping', price: 500, estimated_days: '5-7 days' },
+  ],
+  payment_handlers: [
+    { namespace: 'com.stripe', id: 'stripe-test' },
+  ],
+  tax_rate: 0.08,
+};
+
+describe('UCP Server API', () => {
+  const app = createExpressApp(testConfig, { useDb: false });
+
+  describe('GET /.well-known/ucp', () => {
+    it('returns UCP profile', async () => {
+      const res = await request(app).get('/.well-known/ucp');
+      expect(res.status).toBe(200);
+      expect(res.body.ucp.version).toBe('2026-01-11');
+      expect(res.body.ucp.services['dev.ucp.shopping']).toBeDefined();
+    });
+  });
+
+  describe('GET /health', () => {
+    it('returns health status', async () => {
+      const res = await request(app).get('/health');
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBeDefined();
+    });
+  });
+
+  describe('POST /ucp/v1/checkout-sessions', () => {
+    it('creates a checkout session', async () => {
+      const res = await request(app)
+        .post('/ucp/v1/checkout-sessions')
+        .send({
+          line_items: [{ item: { id: 'item-1' }, quantity: 2 }],
+        });
+      expect(res.status).toBe(201);
+      expect(res.body.id).toBeDefined();
+      expect(res.body.status).toBe('incomplete');
+      expect(res.body.line_items).toHaveLength(1);
+      expect(res.body.line_items[0].quantity).toBe(2);
+    });
+
+    it('rejects invalid requests', async () => {
+      const res = await request(app)
+        .post('/ucp/v1/checkout-sessions')
+        .send({ line_items: [] }); // Empty array
+      expect(res.status).toBe(400);
+      expect(res.body.error).toBe('Validation failed');
+    });
+
+    it('rejects excessive quantity', async () => {
+      const res = await request(app)
+        .post('/ucp/v1/checkout-sessions')
+        .send({
+          line_items: [{ item: { id: 'item-1' }, quantity: 999 }],
+        });
+      expect(res.status).toBe(400);
+    });
+  });
+
+  describe('Checkout flow', () => {
+    let checkoutId: string;
+
+    it('creates checkout', async () => {
+      const res = await request(app)
+        .post('/ucp/v1/checkout-sessions')
+        .send({
+          line_items: [{ item: { id: 'item-1' }, quantity: 1 }],
+        });
+      checkoutId = res.body.id;
+      expect(res.body.status).toBe('incomplete');
+    });
+
+    it('updates with buyer and fulfillment', async () => {
+      const res = await request(app)
+        .put(`/ucp/v1/checkout-sessions/${checkoutId}`)
+        .send({
+          buyer: { email: 'test@example.com' },
+          fulfillment: {
+            methods: [{
+              type: 'shipping',
+              destinations: [{
+                street_address: '123 Main St',
+                address_locality: 'Anytown',
+                address_region: 'CA',
+                postal_code: '12345',
+                address_country: 'US',
+              }],
+            }],
+          },
+        });
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('ready_for_complete');
+    });
+
+    it('completes checkout', async () => {
+      const res = await request(app)
+        .post(`/ucp/v1/checkout-sessions/${checkoutId}/complete`);
+      expect(res.status).toBe(201);
+      expect(res.body.status).toBe('completed');
+      expect(res.body.order).toBeDefined();
+      expect(res.body.order.id).toMatch(/^order_/);
+    });
+  });
+
+  describe('GET /ucp/v1/items', () => {
+    it('returns product catalog', async () => {
+      const res = await request(app).get('/ucp/v1/items');
+      expect(res.status).toBe(200);
+      expect(res.body).toHaveLength(2);
+      expect(res.body[0].id).toBe('item-1');
+    });
+  });
+});