npm package: @opencommerceprotocol/bridge-ucp
Description: Open Commerce Protocol — UCP (Universal Checkout Protocol) bridge
Latest version: 1.0.0

# @opencommerceprotocol/bridge-ucp

UCP (Universal Checkout Protocol) bridge for the [Open Commerce Protocol](https://opencommerceprotocol.org). Converts an OCP manifest into a UCP-compatible manifest, enabling Google UCP checkout agents to discover and interact with OCP stores.

## Installation

```bash
npm install @opencommerceprotocol/bridge-ucp
```

## Usage

```typescript
import { ocpToUCP, generateUCPWellKnown } from '@opencommerceprotocol/bridge-ucp';
import type { OCPManifest } from '@opencommerceprotocol/spec';

const ocpManifest: OCPManifest = { /* your manifest */ };

// Convert to UCP manifest object
const ucpManifest = ocpToUCP(ocpManifest);

// Or generate the JSON string for serving at /.well-known/ucp
const ucpJson = generateUCPWellKnown(ocpManifest);
```

## Serving the UCP endpoint

### Express

```typescript
import express from 'express';
import { generateUCPWellKnown } from '@opencommerceprotocol/bridge-ucp';
import manifest from './.well-known/ocp.json';

const app = express();

app.get('/.well-known/ucp', (req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(generateUCPWellKnown(manifest));
});
```

### Hono (Cloudflare Workers)

```typescript
import { Hono } from 'hono';
import { ocpToUCP } from '@opencommerceprotocol/bridge-ucp';
import manifest from './.well-known/ocp.json';

const app = new Hono();
app.get('/.well-known/ucp', (c) => c.json(ocpToUCP(manifest)));
```

## `OCPManifest` → `UCPManifest` Mapping

| OCP Field | UCP Field |
|-----------|-----------|
| `merchant.name` | `name` |
| `merchant.url` | `url` |
| `merchant.logo` | `logo` |
| `merchant.description` | `description` |
| `capabilities.catalog` | `capabilities[{ type: 'Catalog' }]` |
| `capabilities.search` | `capabilities[{ type: 'Search' }]` |
| `capabilities.cart` | `capabilities[{ type: 'Cart' }]` |
| `capabilities.checkout` | `capabilities[{ type: 'Checkout' }]` + `checkout.mode` |
| `capabilities.orders` | `capabilities[{ type: 'OrderTracking' }]` |
| `payments.handlers` | `payments.methods` |
| `payments.currencies` | `payments.currencies` |
| `discovery.feed` | `catalog.feed` |
| `discovery.feed_format` | `catalog.format` |

## `UCPManifest` Type

```typescript
interface UCPManifest {
  '@context': string;    // 'https://schema.googleapis.com/ucp/v1'
  '@type': string;       // 'UniversalCheckoutProvider'
  name: string;
  url: string;
  logo?: string;
  description?: string;
  capabilities: UCPCapability[];
  payments: {
    methods: string[];
    currencies: string[];
  };
  catalog?: {
    feed: string;
    format: string;
  };
  checkout?: {
    mode: string;        // 'full' | 'redirect' | 'escalate'
    url?: string;
  };
  ocp_source?: string;   // link back to the OCP manifest
}

interface UCPCapability {
  type: string;          // 'Catalog' | 'Search' | 'Cart' | 'Checkout' | 'OrderTracking'
  enabled: boolean;
  endpoint?: string;
}
```

## CLI Alternative

```bash
npx @opencommerceprotocol/cli bridge --protocol ucp --manifest .well-known/ocp.json
```

Also declare the UCP endpoint in your OCP manifest to make it discoverable:

```json
{
  "bridge": {
    "ucp": "https://mystore.com/.well-known/ucp"
  }
}
```