npm package: @opencommerceprotocol/registry
Description: Open Commerce Protocol — Public agent registry for discovering agent-enabled websites (agents.directory)
Latest version: 1.0.0

# @opencommerceprotocol/registry

Public agent registry server for the [Open Commerce Protocol](https://opencommerceprotocol.org). A searchable directory of agent-enabled websites — the "agents.directory" — where AI agents can discover sites that expose OCP tools or agent APIs.

## Installation

```bash
npm install @opencommerceprotocol/registry
```

## Quick Start

### Run the registry server

```bash
OCP_REGISTRY_PORT=3200 OCP_REGISTRY_DB=./registry.db npx tsx src/index.ts
```

### Embed in your application

```typescript
import { createApp } from '@opencommerceprotocol/registry';
import { serve } from '@hono/node-server';

const { app, storage } = createApp('./registry.db');

serve({ fetch: app.fetch, port: 3200 });
console.log('OCP Registry running at http://localhost:3200');
```

## `createApp(dbPath?)`

Returns `{ app: Hono, storage: RegistryStorage }`.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `dbPath` | `':memory:'` | SQLite database file path |

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OCP_REGISTRY_PORT` | `3200` | HTTP server port |
| `OCP_REGISTRY_DB` | `./ocp-registry.db` | SQLite database path |

## API Endpoints

### `POST /v1/register` — Register a site

```bash
curl -X POST http://localhost:3200/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mystore.com",
    "name": "My Store",
    "description": "Premium pet supplies — agent-enabled",
    "vertical": "commerce",
    "manifest_url": "https://mystore.com/.well-known/ocp.json",
    "tools": ["search_products", "get_product", "add_to_cart"],
    "ships_to": ["US", "CA", "GB"],
    "payment_methods": ["card", "paypal"],
    "categories": ["Dog Food", "Cat Food", "Pet Toys"],
    "price_tier": "mid"
  }'
```

### `GET /v1/search` — Search registered sites

```bash
# Full-text search
curl "http://localhost:3200/v1/search?q=organic+pet+food"

# With filters
curl "http://localhost:3200/v1/search?q=restaurants&vertical=food&ships_to=US"
curl "http://localhost:3200/v1/search?vertical=commerce&payment_method=paypal&price_tier=budget"
curl "http://localhost:3200/v1/search?category=electronics&q=headphones&limit=20&offset=0"
```

| Query Parameter | Description |
|-----------------|-------------|
| `q` | Full-text search query |
| `vertical` | Filter by vertical (see list below) |
| `ships_to` | ISO country code filter |
| `payment_method` | Payment method filter |
| `category` | Product category filter |
| `price_tier` | `budget`, `mid`, `premium`, `luxury` |
| `limit` | Max results (default: 20) |
| `offset` | Pagination offset |

### `GET /v1/route` — Intent-based routing

Finds the most relevant site for a natural language intent:

```bash
curl "http://localhost:3200/v1/route?intent=buy+wireless+headphones+under+%24100"
```

Response:
```json
{
  "url": "https://electronicshub.com",
  "name": "Electronics Hub",
  "manifest_url": "https://electronicshub.com/.well-known/ocp.json",
  "match_reason": "Best match for electronics in budget range"
}
```

### `GET /v1/site/:id` — Get site details

```bash
curl http://localhost:3200/v1/site/abc123
```

### `DELETE /v1/site/:id` — Unregister a site

```bash
curl -X DELETE http://localhost:3200/v1/site/abc123
```

### `GET /v1/stats` — Registry statistics

```bash
curl http://localhost:3200/v1/stats
```

Response:
```json
{
  "total_sites": 1234,
  "by_vertical": { "commerce": 890, "food": 234, "travel": 110 },
  "recently_registered": 42,
  "by_payment_method": { "card": 900, "paypal": 600 }
}
```

### `GET /health` — Health check

```bash
curl http://localhost:3200/health
# { "status": "ok", "service": "ocp-registry" }
```

## `RegistryStorage`

Access the registry database directly:

```typescript
import { RegistryStorage } from '@opencommerceprotocol/registry';

const storage = new RegistryStorage('./registry.db');

// Register a site
const entry = await storage.register({
  url: 'https://mystore.com',
  name: 'My Store',
  vertical: 'commerce',
  manifest_url: 'https://mystore.com/.well-known/ocp.json',
});

// Search
const results = await storage.search({ q: 'pet food', vertical: 'commerce' });

// Get one
const site = await storage.getById(entry.id);

// Delete
await storage.delete(entry.id);

// Stats
const stats = await storage.getStats();
```

## Verticals

The registry supports 10 verticals:

| Vertical | Description |
|----------|-------------|
| `commerce` | E-commerce stores |
| `food` | Restaurants, food delivery, groceries |
| `travel` | Hotels, flights, vacation packages |
| `knowledge` | Documentation, wikis, knowledge bases |
| `saas` | Software services |
| `enterprise` | B2B tools and services |
| `finance` | Financial products and services |
| `health` | Health and wellness |
| `real_estate` | Property listings |
| `media` | News, content, streaming |

## Self-Registration via CLI

```bash
# Register your store with the public OCP registry
npx @opencommerceprotocol/cli agent-discover https://agents.directory/register \
  --manifest .well-known/ocp.json
```

## Public Registry

The public OCP registry is available at `https://agents.directory`. AI agents can query it to find agent-enabled sites by topic, vertical, or capability.

```bash
# Find pet stores that ship to the US
curl "https://agents.directory/v1/search?q=pet+food&ships_to=US&vertical=commerce"
```