ucpify 1.0.0

package/.env.example

@@ -0,0 +1,23 @@
+# UCP Server Configuration
+
+# Server
+PORT=3000
+NODE_ENV=production
+
+# Database (SQLite path)
+DATABASE_PATH=./data/ucp.db
+
+# Logging
+LOG_LEVEL=info
+
+# UCP (your public domain)
+UCP_DOMAIN=https://your-store.com
+
+# Stripe (optional - for real payments)
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# PayPal (optional - alternative to Stripe)
+PAYPAL_CLIENT_ID=...
+PAYPAL_CLIENT_SECRET=...
+PAYPAL_MODE=sandbox

package/Dockerfile

@@ -0,0 +1,35 @@
+FROM node:20-alpine
+
+# Install build dependencies for better-sqlite3
+RUN apk add --no-cache python3 make g++
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy source
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Expose port
+EXPOSE 3000
+
+# Set environment
+ENV NODE_ENV=production
+ENV DATABASE_PATH=/app/data/ucp.db
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+# Run server
+CMD ["node", "dist/cli.js", "serve", "/app/config/merchant-config.json"]

package/README.md

@@ -0,0 +1,320 @@
+# ucpify
+
+Generate UCP-compliant (Universal Commerce Protocol) servers for merchants from a simple schema.
+
+## What is UCP?
+
+The [Universal Commerce Protocol](https://ucp.dev) is an open standard for agentic commerce, enabling AI agents, apps, businesses, and payment providers to interact seamlessly. UCP was co-developed by Google, Shopify, Etsy, Wayfair, Target, and Walmart.
+
+## Quick Start
+
+```bash
+# Initialize a sample merchant config
+npx ts-node src/cli.ts init
+
+# Edit merchant-config.json to add your products, shipping, payments
+
+# Start the UCP server
+npx ts-node src/cli.ts serve merchant-config.json
+```
+
+## Merchant Configuration Schema
+
+```json
+{
+  "name": "My Store",
+  "domain": "http://localhost:3000",
+  "currency": "USD",
+  "tax_rate": 0.08,
+  "terms_url": "https://example.com/terms",
+  "port": 3000,
+  "items": [
+    {
+      "id": "item_001",
+      "title": "Classic T-Shirt",
+      "description": "A comfortable cotton t-shirt",
+      "price": 2500
+    }
+  ],
+  "shipping_options": [
+    {
+      "id": "standard",
+      "title": "Standard Shipping",
+      "price": 500,
+      "estimated_days": "5-7 business days"
+    }
+  ],
+  "payment_handlers": [
+    {
+      "namespace": "com.stripe",
+      "id": "stripe_handler",
+      "config": { "publishable_key": "pk_test_..." }
+    }
+  ]
+}
+```
+
+## UCP Endpoints
+
+Once running, your server exposes these UCP-compliant endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/.well-known/ucp` | GET | UCP Profile (discovery) |
+| `/ucp/v1/checkout-sessions` | POST | Create checkout session |
+| `/ucp/v1/checkout-sessions/:id` | GET | Get checkout session |
+| `/ucp/v1/checkout-sessions/:id` | PUT | Update checkout session |
+| `/ucp/v1/checkout-sessions/:id/complete` | POST | Complete checkout (create order) |
+| `/ucp/v1/checkout-sessions/:id/cancel` | POST | Cancel checkout |
+| `/ucp/v1/orders` | GET | List orders |
+| `/ucp/v1/orders/:id` | GET | Get order |
+| `/ucp/v1/items` | GET | Product catalog |
+
+## Example Usage
+
+### 1. Create a checkout session
+
+```bash
+curl -X POST http://localhost:3000/ucp/v1/checkout-sessions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "line_items": [
+      {
+        "item": { "id": "item_001" },
+        "quantity": 2
+      }
+    ]
+  }'
+```
+
+### 2. Update with buyer info and shipping
+
+```bash
+curl -X PUT http://localhost:3000/ucp/v1/checkout-sessions/chk_xxx \
+  -H "Content-Type: application/json" \
+  -d '{
+    "buyer": {
+      "email": "customer@example.com",
+      "first_name": "Jane",
+      "last_name": "Doe"
+    },
+    "line_items": [{ "item": { "id": "item_001" }, "quantity": 2 }],
+    "fulfillment": {
+      "methods": [{
+        "type": "shipping",
+        "destinations": [{
+          "street_address": "123 Main St",
+          "address_locality": "Springfield",
+          "address_region": "IL",
+          "postal_code": "62701",
+          "address_country": "US"
+        }]
+      }]
+    }
+  }'
+```
+
+### 3. Complete checkout
+
+```bash
+curl -X POST http://localhost:3000/ucp/v1/checkout-sessions/chk_xxx/complete
+```
+
+## CLI Commands
+
+```bash
+# Create sample configuration
+ucpify init --output my-store.json
+
+# Validate configuration
+ucpify validate my-store.json
+
+# Start server
+ucpify serve my-store.json --port 8080
+```
+
+## Programmatic Usage
+
+```typescript
+import { createExpressApp, MerchantConfigSchema } from 'ucpify';
+
+const config = MerchantConfigSchema.parse({
+  name: 'My Store',
+  domain: 'http://localhost:3000',
+  currency: 'USD',
+  items: [
+    { id: 'prod_1', title: 'Widget', price: 1999 }
+  ],
+  shipping_options: [
+    { id: 'standard', title: 'Standard', price: 500 }
+  ]
+});
+
+const app = createExpressApp(config);
+app.listen(3000);
+```
+
+## License
+
+MIT
+
+---
+
+## Identity Linking (Bring Your Own OAuth)
+
+UCP uses OAuth 2.0 for identity linking between agents and merchants. ucpify does **not** include a built-in OAuth server—instead, integrate your existing OAuth provider.
+
+### Required OAuth Endpoints
+
+Your OAuth provider must expose these endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/oauth2/authorize` | GET | Authorization page (user consent) |
+| `/oauth2/token` | POST | Token exchange |
+| `/oauth2/revoke` | POST | Token revocation |
+
+### OAuth Discovery Endpoint
+
+Create `/.well-known/oauth-authorization-server` returning:
+
+```json
+{
+  "issuer": "https://your-store.com",
+  "authorization_endpoint": "https://your-store.com/oauth2/authorize",
+  "token_endpoint": "https://your-store.com/oauth2/token",
+  "revocation_endpoint": "https://your-store.com/oauth2/revoke",
+  "scopes_supported": [
+    "ucp:scopes:checkout_session",
+    "ucp:scopes:order_read",
+    "ucp:scopes:order_manage"
+  ],
+  "response_types_supported": ["code"],
+  "grant_types_supported": ["authorization_code", "refresh_token"],
+  "token_endpoint_auth_methods_supported": ["client_secret_basic"],
+  "service_documentation": "https://your-store.com/docs/oauth"
+}
+```
+
+### UCP OAuth Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `ucp:scopes:checkout_session` | Create and manage checkout sessions |
+| `ucp:scopes:order_read` | Read order information |
+| `ucp:scopes:order_manage` | Manage orders (cancel, refund) |
+
+### Integration Examples
+
+#### Using Auth0
+
+```javascript
+// Add to your Express app
+app.get('/.well-known/oauth-authorization-server', (req, res) => {
+  res.json({
+    issuer: 'https://your-tenant.auth0.com',
+    authorization_endpoint: 'https://your-tenant.auth0.com/authorize',
+    token_endpoint: 'https://your-tenant.auth0.com/oauth/token',
+    revocation_endpoint: 'https://your-tenant.auth0.com/oauth/revoke',
+    scopes_supported: ['ucp:scopes:checkout_session'],
+    response_types_supported: ['code'],
+    grant_types_supported: ['authorization_code', 'refresh_token'],
+    token_endpoint_auth_methods_supported: ['client_secret_basic'],
+  });
+});
+```
+
+#### Using Keycloak
+
+```python
+# Add to your Flask app
+@app.route('/.well-known/oauth-authorization-server')
+def oauth_discovery():
+    return jsonify({
+        "issuer": "https://keycloak.example.com/realms/merchant",
+        "authorization_endpoint": "https://keycloak.example.com/realms/merchant/protocol/openid-connect/auth",
+        "token_endpoint": "https://keycloak.example.com/realms/merchant/protocol/openid-connect/token",
+        "revocation_endpoint": "https://keycloak.example.com/realms/merchant/protocol/openid-connect/revoke",
+        "scopes_supported": ["ucp:scopes:checkout_session"],
+        "response_types_supported": ["code"],
+        "grant_types_supported": ["authorization_code", "refresh_token"],
+        "token_endpoint_auth_methods_supported": ["client_secret_basic"],
+    })
+```
+
+#### Using AWS Cognito
+
+```javascript
+app.get('/.well-known/oauth-authorization-server', (req, res) => {
+  const cognitoDomain = 'https://your-domain.auth.us-east-1.amazoncognito.com';
+  res.json({
+    issuer: cognitoDomain,
+    authorization_endpoint: `${cognitoDomain}/oauth2/authorize`,
+    token_endpoint: `${cognitoDomain}/oauth2/token`,
+    revocation_endpoint: `${cognitoDomain}/oauth2/revoke`,
+    scopes_supported: ['ucp:scopes:checkout_session'],
+    response_types_supported: ['code'],
+    grant_types_supported: ['authorization_code', 'refresh_token'],
+    token_endpoint_auth_methods_supported: ['client_secret_basic'],
+  });
+});
+```
+
+### Protecting UCP Endpoints
+
+Add middleware to validate tokens on protected endpoints:
+
+```javascript
+// JavaScript/Express
+const validateToken = async (req, res, next) => {
+  const authHeader = req.headers.authorization;
+  if (!authHeader?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Missing token' });
+  }
+  
+  const token = authHeader.slice(7);
+  // Validate with your OAuth provider
+  const valid = await verifyTokenWithProvider(token);
+  if (!valid) {
+    return res.status(401).json({ error: 'Invalid token' });
+  }
+  next();
+};
+
+// Apply to checkout endpoints
+app.post('/ucp/v1/checkout-sessions', validateToken, createCheckout);
+```
+
+```python
+# Python/Flask
+from functools import wraps
+
+def require_oauth(f):
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        auth_header = request.headers.get('Authorization', '')
+        if not auth_header.startswith('Bearer '):
+            return jsonify({'error': 'Missing token'}), 401
+        
+        token = auth_header[7:]
+        # Validate with your OAuth provider
+        if not verify_token_with_provider(token):
+            return jsonify({'error': 'Invalid token'}), 401
+        return f(*args, **kwargs)
+    return decorated
+
+@app.route('/ucp/v1/checkout-sessions', methods=['POST'])
+@require_oauth
+def create_checkout():
+    ...
+```
+
+### Agent Platform Flow
+
+1. Agent discovers OAuth endpoints via `/.well-known/oauth-authorization-server`
+2. Agent redirects user to `authorization_endpoint` with scopes
+3. User consents on merchant's OAuth page
+4. Agent receives authorization code
+5. Agent exchanges code for access token at `token_endpoint`
+6. Agent uses access token in `Authorization: Bearer <token>` header
+7. Agent refreshes token when expired using `refresh_token` grant

package/dist/__tests__/api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/api.test.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const supertest_1 = __importDefault(require("supertest"));
+const express_app_1 = require("../express-app");
+const testConfig = {
+    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,
+};
+(0, vitest_1.describe)('UCP Server API', () => {
+    const app = (0, express_app_1.createExpressApp)(testConfig, { useDb: false });
+    (0, vitest_1.describe)('GET /.well-known/ucp', () => {
+        (0, vitest_1.it)('returns UCP profile', async () => {
+            const res = await (0, supertest_1.default)(app).get('/.well-known/ucp');
+            (0, vitest_1.expect)(res.status).toBe(200);
+            (0, vitest_1.expect)(res.body.ucp.version).toBe('2026-01-11');
+            (0, vitest_1.expect)(res.body.ucp.services['dev.ucp.shopping']).toBeDefined();
+        });
+    });
+    (0, vitest_1.describe)('GET /health', () => {
+        (0, vitest_1.it)('returns health status', async () => {
+            const res = await (0, supertest_1.default)(app).get('/health');
+            (0, vitest_1.expect)(res.status).toBe(200);
+            (0, vitest_1.expect)(res.body.status).toBeDefined();
+        });
+    });
+    (0, vitest_1.describe)('POST /ucp/v1/checkout-sessions', () => {
+        (0, vitest_1.it)('creates a checkout session', async () => {
+            const res = await (0, supertest_1.default)(app)
+                .post('/ucp/v1/checkout-sessions')
+                .send({
+                line_items: [{ item: { id: 'item-1' }, quantity: 2 }],
+            });
+            (0, vitest_1.expect)(res.status).toBe(201);
+            (0, vitest_1.expect)(res.body.id).toBeDefined();
+            (0, vitest_1.expect)(res.body.status).toBe('incomplete');
+            (0, vitest_1.expect)(res.body.line_items).toHaveLength(1);
+            (0, vitest_1.expect)(res.body.line_items[0].quantity).toBe(2);
+        });
+        (0, vitest_1.it)('rejects invalid requests', async () => {
+            const res = await (0, supertest_1.default)(app)
+                .post('/ucp/v1/checkout-sessions')
+                .send({ line_items: [] }); // Empty array
+            (0, vitest_1.expect)(res.status).toBe(400);
+            (0, vitest_1.expect)(res.body.error).toBe('Validation failed');
+        });
+        (0, vitest_1.it)('rejects excessive quantity', async () => {
+            const res = await (0, supertest_1.default)(app)
+                .post('/ucp/v1/checkout-sessions')
+                .send({
+                line_items: [{ item: { id: 'item-1' }, quantity: 999 }],
+            });
+            (0, vitest_1.expect)(res.status).toBe(400);
+        });
+    });
+    (0, vitest_1.describe)('Checkout flow', () => {
+        let checkoutId;
+        (0, vitest_1.it)('creates checkout', async () => {
+            const res = await (0, supertest_1.default)(app)
+                .post('/ucp/v1/checkout-sessions')
+                .send({
+                line_items: [{ item: { id: 'item-1' }, quantity: 1 }],
+            });
+            checkoutId = res.body.id;
+            (0, vitest_1.expect)(res.body.status).toBe('incomplete');
+        });
+        (0, vitest_1.it)('updates with buyer and fulfillment', async () => {
+            const res = await (0, supertest_1.default)(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',
+                                }],
+                        }],
+                },
+            });
+            (0, vitest_1.expect)(res.status).toBe(200);
+            (0, vitest_1.expect)(res.body.status).toBe('ready_for_complete');
+        });
+        (0, vitest_1.it)('completes checkout', async () => {
+            const res = await (0, supertest_1.default)(app)
+                .post(`/ucp/v1/checkout-sessions/${checkoutId}/complete`);
+            (0, vitest_1.expect)(res.status).toBe(201);
+            (0, vitest_1.expect)(res.body.status).toBe('completed');
+            (0, vitest_1.expect)(res.body.order).toBeDefined();
+            (0, vitest_1.expect)(res.body.order.id).toMatch(/^order_/);
+        });
+    });
+    (0, vitest_1.describe)('GET /ucp/v1/items', () => {
+        (0, vitest_1.it)('returns product catalog', async () => {
+            const res = await (0, supertest_1.default)(app).get('/ucp/v1/items');
+            (0, vitest_1.expect)(res.status).toBe(200);
+            (0, vitest_1.expect)(res.body).toHaveLength(2);
+            (0, vitest_1.expect)(res.body[0].id).toBe('item-1');
+        });
+    });
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};