@opencommerceprotocol/bridge-ucp

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

Installation

npm install @opencommerceprotocol/bridge-ucp

Usage

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

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)

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

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

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

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

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