ucpregistry 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# ucpregistry
+
+Official SDK for the [UCP Registry](https://ucpregistry.com) API. Discover UCP-enabled merchants, search products across stores, and manage registry entities.
+
+## Install
+
+```bash
+npm install ucpregistry
+```
+
+## Quick Start
+
+```typescript
+import { UCPRegistry } from 'ucpregistry';
+
+const registry = new UCPRegistry();
+
+// Discover merchants
+const merchants = await registry.discover({ category: 'Health & Beauty' });
+
+// Get a specific merchant
+const merchant = await registry.getMerchant('allbirds.com');
+console.log(merchant.capabilities.checkout); // true
+console.log(merchant.transports); // ['mcp', 'embedded']
+
+// Search products across all merchants
+const products = await registry.searchProducts({
+  query: 'running shoes',
+  sort: 'price_asc',
+  limit: 5,
+});
+```
+
+## Authentication
+
+Free tier endpoints (discover, search) work without authentication. For push API and entity management, pass your API token:
+
+```typescript
+const registry = new UCPRegistry({
+  apiKey: 'ucpr_...',
+});
+```
+
+Get your token at [ucpregistry.com/tokens](https://ucpregistry.com/tokens).
+
+## API
+
+### `discover(options?)`
+
+Find UCP-enabled merchants.
+
+```typescript
+const merchants = await registry.discover({
+  search: 'skincare',        // keyword search
+  platform: 'shopify',       // shopify, woocommerce, bigcommerce, etc.
+  category: 'Health & Beauty', // Google Product Taxonomy category
+  has_checkout: true,         // only merchants with checkout
+  sort: 'ucp_score',         // ucp_score | response_time | domain
+  limit: 20,                 // max results
+});
+```
+
+### `getMerchant(domain)`
+
+Get full details for a merchant.
+
+```typescript
+const m = await registry.getMerchant('imageskincare.com');
+// m.capabilities, m.transports, m.sample_products, m.benchmark, etc.
+```
+
+### `searchProducts(options?)`
+
+Search products across all merchants.
+
+```typescript
+const products = await registry.searchProducts({
+  query: 'serum',
+  category: 'Health & Beauty',
+  min_price: 20,
+  max_price: 100,
+  sort: 'price_asc',
+});
+```
+
+### `push(type, slug, options)` (requires token)
+
+Push a manifest version.
+
+```typescript
+const version = await registry.push('merchants', 'mystore.com', {
+  manifest: { version: '1.0', capabilities: ['checkout'] },
+  commit_message: 'Initial push',
+});
+// version.version → '1.0.0'
+```
+
+### `versions(type, slug)` (requires token)
+
+List version history.
+
+### `diff(type, slug, v1, v2)` (requires token)
+
+Diff two versions.
+
+## MCP Server
+
+UCP Registry is also available as an MCP server. Add it to your agent:
+
+```json
+{
+  "mcpServers": {
+    "ucpregistry": {
+      "url": "https://ucpregistry.com/mcp"
+    }
+  }
+}
+```
+
+Tools: `discover-merchants`, `get-merchant`, `search-products`.
+
+## Types
+
+All types are exported:
+
+```typescript
+import type { Merchant, ProductResult, MerchantCapabilities } from 'ucpregistry';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,216 @@
+/** UCP merchant status */
+type MerchantStatus = 'verified' | 'pending' | 'not_detected' | 'invalid' | 'blocked' | 'unreachable';
+/** Merchant capabilities */
+interface MerchantCapabilities {
+    checkout: boolean;
+    identity_linking: boolean;
+    cart_management: boolean;
+    order: boolean;
+    payment_token: boolean;
+    count: number;
+    raw?: string[];
+}
+/** Benchmark grade and score */
+interface MerchantBenchmark {
+    grade: string;
+    score: number;
+}
+/** Sample product from a merchant's catalog */
+interface SampleProduct {
+    title: string;
+    price: number | null;
+    currency: string;
+    url: string | null;
+    image_url: string | null;
+    product_type: string | null;
+}
+/** Merchant entity from the registry */
+interface Merchant {
+    domain: string;
+    status: MerchantStatus;
+    registry_id?: string;
+    ucp_score: number | null;
+    platform: string | null;
+    category: string | null;
+    description: string | null;
+    extended_description?: string | null;
+    capabilities: MerchantCapabilities;
+    transports: string[];
+    response_time_ms: number | null;
+    ucp_endpoint: string | null;
+    last_checked_at?: string | null;
+    benchmark?: MerchantBenchmark | null;
+    sample_products?: SampleProduct[];
+    plugins?: string[];
+    extensions?: string[];
+    registry_url: string;
+}
+/** Product search result */
+interface ProductResult {
+    title: string;
+    price: number | null;
+    currency: string;
+    url: string | null;
+    image_url: string | null;
+    product_type: string | null;
+    merchant: string;
+    category: string | null;
+    platform: string | null;
+}
+/** Discovery query options */
+interface DiscoverOptions {
+    search?: string;
+    platform?: string;
+    category?: string;
+    has_checkout?: boolean;
+    sort?: 'ucp_score' | 'response_time' | 'domain';
+    limit?: number;
+}
+/** Product search options */
+interface SearchProductsOptions {
+    query?: string;
+    category?: string;
+    domain?: string;
+    min_price?: number;
+    max_price?: number;
+    sort?: 'relevance' | 'price_asc' | 'price_desc';
+    limit?: number;
+}
+/** Discovery response */
+interface DiscoverResponse {
+    data: Merchant[];
+    meta: {
+        total: number;
+        returned: number;
+    };
+}
+/** Product search response */
+interface ProductSearchResponse {
+    data: ProductResult[];
+    meta: {
+        total: number;
+        returned: number;
+        merchants: number;
+        query: string | null;
+        sort: string;
+    };
+}
+/** Entity version (from push API) */
+interface EntityVersion {
+    version: string;
+    commit_sha: string;
+    created_at: string;
+    diff_summary: string;
+}
+/** Push manifest options */
+interface PushOptions {
+    manifest: Record<string, unknown>;
+    commit_message?: string;
+}
+/** SDK configuration */
+interface UCPRegistryConfig {
+    baseUrl?: string;
+    apiKey?: string;
+}
+
+/**
+ * UCP Registry SDK
+ *
+ * Official client for the UCP Registry API. Discover UCP merchants,
+ * search products across stores, and manage registry entities.
+ *
+ * @example
+ * ```typescript
+ * import { UCPRegistry } from 'ucpregistry';
+ *
+ * const registry = new UCPRegistry();
+ * const merchants = await registry.discover({ category: 'Health & Beauty' });
+ * ```
+ */
+declare class UCPRegistry {
+    private baseUrl;
+    private apiKey?;
+    constructor(config?: UCPRegistryConfig);
+    /**
+     * Discover UCP-enabled merchants.
+     *
+     * @example
+     * ```typescript
+     * // All verified merchants
+     * const all = await registry.discover();
+     *
+     * // Shopify merchants with checkout
+     * const shopify = await registry.discover({
+     *   platform: 'shopify',
+     *   has_checkout: true,
+     *   sort: 'ucp_score',
+     * });
+     *
+     * // Search by keyword
+     * const skincare = await registry.discover({ search: 'skincare' });
+     * ```
+     */
+    discover(options?: DiscoverOptions): Promise<Merchant[]>;
+    /**
+     * Get detailed information about a specific merchant.
+     *
+     * @example
+     * ```typescript
+     * const merchant = await registry.getMerchant('allbirds.com');
+     * console.log(merchant.capabilities.checkout); // true
+     * console.log(merchant.transports); // ['mcp', 'embedded']
+     * ```
+     */
+    getMerchant(domain: string): Promise<Merchant>;
+    /**
+     * Search products across all UCP merchants.
+     *
+     * @example
+     * ```typescript
+     * const products = await registry.searchProducts({
+     *   query: 'running shoes',
+     *   sort: 'price_asc',
+     *   limit: 5,
+     * });
+     *
+     * for (const product of products) {
+     *   console.log(`${product.title} - $${product.price} at ${product.merchant}`);
+     * }
+     * ```
+     */
+    searchProducts(options?: SearchProductsOptions): Promise<ProductResult[]>;
+    /**
+     * Push a manifest version to an entity (requires API token).
+     *
+     * @example
+     * ```typescript
+     * const registry = new UCPRegistry({ apiKey: 'ucpr_...' });
+     *
+     * const version = await registry.push('merchants', 'mystore.com', {
+     *   manifest: { version: '1.0', capabilities: ['checkout'] },
+     *   commit_message: 'Initial push',
+     * });
+     *
+     * console.log(version.version); // '1.0.0'
+     * ```
+     */
+    push(type: string, slug: string, options: PushOptions): Promise<EntityVersion>;
+    /**
+     * List version history for an entity (requires API token).
+     */
+    versions(type: string, slug: string): Promise<{
+        data: EntityVersion[];
+        meta: {
+            total: number;
+        };
+    }>;
+    /**
+     * Diff two versions of an entity (requires API token).
+     */
+    diff(type: string, slug: string, v1: string, v2: string): Promise<Record<string, unknown>>;
+    private fetch;
+}
+/** Create a new UCPRegistry client */
+declare function createClient(config?: UCPRegistryConfig): UCPRegistry;
+
+export { type DiscoverOptions, type DiscoverResponse, type EntityVersion, type Merchant, type MerchantBenchmark, type MerchantCapabilities, type MerchantStatus, type ProductResult, type ProductSearchResponse, type PushOptions, type SampleProduct, type SearchProductsOptions, UCPRegistry, type UCPRegistryConfig, createClient };

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+/** UCP merchant status */
+type MerchantStatus = 'verified' | 'pending' | 'not_detected' | 'invalid' | 'blocked' | 'unreachable';
+/** Merchant capabilities */
+interface MerchantCapabilities {
+    checkout: boolean;
+    identity_linking: boolean;
+    cart_management: boolean;
+    order: boolean;
+    payment_token: boolean;
+    count: number;
+    raw?: string[];
+}
+/** Benchmark grade and score */
+interface MerchantBenchmark {
+    grade: string;
+    score: number;
+}
+/** Sample product from a merchant's catalog */
+interface SampleProduct {
+    title: string;
+    price: number | null;
+    currency: string;
+    url: string | null;
+    image_url: string | null;
+    product_type: string | null;
+}
+/** Merchant entity from the registry */
+interface Merchant {
+    domain: string;
+    status: MerchantStatus;
+    registry_id?: string;
+    ucp_score: number | null;
+    platform: string | null;
+    category: string | null;
+    description: string | null;
+    extended_description?: string | null;
+    capabilities: MerchantCapabilities;
+    transports: string[];
+    response_time_ms: number | null;
+    ucp_endpoint: string | null;
+    last_checked_at?: string | null;
+    benchmark?: MerchantBenchmark | null;
+    sample_products?: SampleProduct[];
+    plugins?: string[];
+    extensions?: string[];
+    registry_url: string;
+}
+/** Product search result */
+interface ProductResult {
+    title: string;
+    price: number | null;
+    currency: string;
+    url: string | null;
+    image_url: string | null;
+    product_type: string | null;
+    merchant: string;
+    category: string | null;
+    platform: string | null;
+}
+/** Discovery query options */
+interface DiscoverOptions {
+    search?: string;
+    platform?: string;
+    category?: string;
+    has_checkout?: boolean;
+    sort?: 'ucp_score' | 'response_time' | 'domain';
+    limit?: number;
+}
+/** Product search options */
+interface SearchProductsOptions {
+    query?: string;
+    category?: string;
+    domain?: string;
+    min_price?: number;
+    max_price?: number;
+    sort?: 'relevance' | 'price_asc' | 'price_desc';
+    limit?: number;
+}
+/** Discovery response */
+interface DiscoverResponse {
+    data: Merchant[];
+    meta: {
+        total: number;
+        returned: number;
+    };
+}
+/** Product search response */
+interface ProductSearchResponse {
+    data: ProductResult[];
+    meta: {
+        total: number;
+        returned: number;
+        merchants: number;
+        query: string | null;
+        sort: string;
+    };
+}
+/** Entity version (from push API) */
+interface EntityVersion {
+    version: string;
+    commit_sha: string;
+    created_at: string;
+    diff_summary: string;
+}
+/** Push manifest options */
+interface PushOptions {
+    manifest: Record<string, unknown>;
+    commit_message?: string;
+}
+/** SDK configuration */
+interface UCPRegistryConfig {
+    baseUrl?: string;
+    apiKey?: string;
+}
+
+/**
+ * UCP Registry SDK
+ *
+ * Official client for the UCP Registry API. Discover UCP merchants,
+ * search products across stores, and manage registry entities.
+ *
+ * @example
+ * ```typescript
+ * import { UCPRegistry } from 'ucpregistry';
+ *
+ * const registry = new UCPRegistry();
+ * const merchants = await registry.discover({ category: 'Health & Beauty' });
+ * ```
+ */
+declare class UCPRegistry {
+    private baseUrl;
+    private apiKey?;
+    constructor(config?: UCPRegistryConfig);
+    /**
+     * Discover UCP-enabled merchants.
+     *
+     * @example
+     * ```typescript
+     * // All verified merchants
+     * const all = await registry.discover();
+     *
+     * // Shopify merchants with checkout
+     * const shopify = await registry.discover({
+     *   platform: 'shopify',
+     *   has_checkout: true,
+     *   sort: 'ucp_score',
+     * });
+     *
+     * // Search by keyword
+     * const skincare = await registry.discover({ search: 'skincare' });
+     * ```
+     */
+    discover(options?: DiscoverOptions): Promise<Merchant[]>;
+    /**
+     * Get detailed information about a specific merchant.
+     *
+     * @example
+     * ```typescript
+     * const merchant = await registry.getMerchant('allbirds.com');
+     * console.log(merchant.capabilities.checkout); // true
+     * console.log(merchant.transports); // ['mcp', 'embedded']
+     * ```
+     */
+    getMerchant(domain: string): Promise<Merchant>;
+    /**
+     * Search products across all UCP merchants.
+     *
+     * @example
+     * ```typescript
+     * const products = await registry.searchProducts({
+     *   query: 'running shoes',
+     *   sort: 'price_asc',
+     *   limit: 5,
+     * });
+     *
+     * for (const product of products) {
+     *   console.log(`${product.title} - $${product.price} at ${product.merchant}`);
+     * }
+     * ```
+     */
+    searchProducts(options?: SearchProductsOptions): Promise<ProductResult[]>;
+    /**
+     * Push a manifest version to an entity (requires API token).
+     *
+     * @example
+     * ```typescript
+     * const registry = new UCPRegistry({ apiKey: 'ucpr_...' });
+     *
+     * const version = await registry.push('merchants', 'mystore.com', {
+     *   manifest: { version: '1.0', capabilities: ['checkout'] },
+     *   commit_message: 'Initial push',
+     * });
+     *
+     * console.log(version.version); // '1.0.0'
+     * ```
+     */
+    push(type: string, slug: string, options: PushOptions): Promise<EntityVersion>;
+    /**
+     * List version history for an entity (requires API token).
+     */
+    versions(type: string, slug: string): Promise<{
+        data: EntityVersion[];
+        meta: {
+            total: number;
+        };
+    }>;
+    /**
+     * Diff two versions of an entity (requires API token).
+     */
+    diff(type: string, slug: string, v1: string, v2: string): Promise<Record<string, unknown>>;
+    private fetch;
+}
+/** Create a new UCPRegistry client */
+declare function createClient(config?: UCPRegistryConfig): UCPRegistry;
+
+export { type DiscoverOptions, type DiscoverResponse, type EntityVersion, type Merchant, type MerchantBenchmark, type MerchantCapabilities, type MerchantStatus, type ProductResult, type ProductSearchResponse, type PushOptions, type SampleProduct, type SearchProductsOptions, UCPRegistry, type UCPRegistryConfig, createClient };

package/dist/index.js

@@ -0,0 +1,176 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UCPRegistry: () => UCPRegistry,
+  createClient: () => createClient
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://ucpregistry.com";
+var UCPRegistry = class {
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Discover UCP-enabled merchants.
+   *
+   * @example
+   * ```typescript
+   * // All verified merchants
+   * const all = await registry.discover();
+   *
+   * // Shopify merchants with checkout
+   * const shopify = await registry.discover({
+   *   platform: 'shopify',
+   *   has_checkout: true,
+   *   sort: 'ucp_score',
+   * });
+   *
+   * // Search by keyword
+   * const skincare = await registry.discover({ search: 'skincare' });
+   * ```
+   */
+  async discover(options = {}) {
+    const params = new URLSearchParams();
+    if (options.search) params.set("search", options.search);
+    if (options.platform) params.set("platform", options.platform);
+    if (options.category) params.set("category", options.category);
+    if (options.sort) params.set("sort", options.sort);
+    if (options.limit) params.set("per_page", String(options.limit));
+    const url = `${this.baseUrl}/api/v1/merchants?${params}`;
+    const res = await this.fetch(url);
+    const data = await res.json();
+    return data.data;
+  }
+  /**
+   * Get detailed information about a specific merchant.
+   *
+   * @example
+   * ```typescript
+   * const merchant = await registry.getMerchant('allbirds.com');
+   * console.log(merchant.capabilities.checkout); // true
+   * console.log(merchant.transports); // ['mcp', 'embedded']
+   * ```
+   */
+  async getMerchant(domain) {
+    const url = `${this.baseUrl}/api/v1/merchants/${encodeURIComponent(domain)}`;
+    const res = await this.fetch(url);
+    if (!res.ok) {
+      throw new Error(`Merchant '${domain}' not found (HTTP ${res.status})`);
+    }
+    const data = await res.json();
+    return data.data;
+  }
+  /**
+   * Search products across all UCP merchants.
+   *
+   * @example
+   * ```typescript
+   * const products = await registry.searchProducts({
+   *   query: 'running shoes',
+   *   sort: 'price_asc',
+   *   limit: 5,
+   * });
+   *
+   * for (const product of products) {
+   *   console.log(`${product.title} - $${product.price} at ${product.merchant}`);
+   * }
+   * ```
+   */
+  async searchProducts(options = {}) {
+    const params = new URLSearchParams();
+    if (options.query) params.set("q", options.query);
+    if (options.category) params.set("category", options.category);
+    if (options.domain) params.set("domain", options.domain);
+    if (options.min_price) params.set("min_price", String(options.min_price));
+    if (options.max_price) params.set("max_price", String(options.max_price));
+    if (options.sort) params.set("sort", options.sort);
+    if (options.limit) params.set("limit", String(options.limit));
+    const url = `${this.baseUrl}/api/v1/products/search?${params}`;
+    const res = await this.fetch(url);
+    const data = await res.json();
+    return data.data;
+  }
+  /**
+   * Push a manifest version to an entity (requires API token).
+   *
+   * @example
+   * ```typescript
+   * const registry = new UCPRegistry({ apiKey: 'ucpr_...' });
+   *
+   * const version = await registry.push('merchants', 'mystore.com', {
+   *   manifest: { version: '1.0', capabilities: ['checkout'] },
+   *   commit_message: 'Initial push',
+   * });
+   *
+   * console.log(version.version); // '1.0.0'
+   * ```
+   */
+  async push(type, slug, options) {
+    const url = `${this.baseUrl}/api/v1/entities/${type}/${slug}/push`;
+    const res = await this.fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.error ?? `Push failed (HTTP ${res.status})`);
+    }
+    return await res.json();
+  }
+  /**
+   * List version history for an entity (requires API token).
+   */
+  async versions(type, slug) {
+    const url = `${this.baseUrl}/api/v1/entities/${type}/${slug}/versions`;
+    const res = await this.fetch(url);
+    return await res.json();
+  }
+  /**
+   * Diff two versions of an entity (requires API token).
+   */
+  async diff(type, slug, v1, v2) {
+    const url = `${this.baseUrl}/api/v1/entities/${type}/${slug}/diff/${v1}/${v2}`;
+    const res = await this.fetch(url);
+    return await res.json();
+  }
+  async fetch(url, init = {}) {
+    const headers = {
+      "Accept": "application/json",
+      "User-Agent": "ucpregistry-sdk/0.1.0",
+      ...init.headers ?? {}
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    return globalThis.fetch(url, { ...init, headers });
+  }
+};
+function createClient(config) {
+  return new UCPRegistry(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UCPRegistry,
+  createClient
+});

package/dist/index.mjs

@@ -0,0 +1,150 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://ucpregistry.com";
+var UCPRegistry = class {
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Discover UCP-enabled merchants.
+   *
+   * @example
+   * ```typescript
+   * // All verified merchants
+   * const all = await registry.discover();
+   *
+   * // Shopify merchants with checkout
+   * const shopify = await registry.discover({
+   *   platform: 'shopify',
+   *   has_checkout: true,
+   *   sort: 'ucp_score',
+   * });
+   *
+   * // Search by keyword
+   * const skincare = await registry.discover({ search: 'skincare' });
+   * ```
+   */
+  async discover(options = {}) {
+    const params = new URLSearchParams();
+    if (options.search) params.set("search", options.search);
+    if (options.platform) params.set("platform", options.platform);
+    if (options.category) params.set("category", options.category);
+    if (options.sort) params.set("sort", options.sort);
+    if (options.limit) params.set("per_page", String(options.limit));
+    const url = `${this.baseUrl}/api/v1/merchants?${params}`;
+    const res = await this.fetch(url);
+    const data = await res.json();
+    return data.data;
+  }
+  /**
+   * Get detailed information about a specific merchant.
+   *
+   * @example
+   * ```typescript
+   * const merchant = await registry.getMerchant('allbirds.com');
+   * console.log(merchant.capabilities.checkout); // true
+   * console.log(merchant.transports); // ['mcp', 'embedded']
+   * ```
+   */
+  async getMerchant(domain) {
+    const url = `${this.baseUrl}/api/v1/merchants/${encodeURIComponent(domain)}`;
+    const res = await this.fetch(url);
+    if (!res.ok) {
+      throw new Error(`Merchant '${domain}' not found (HTTP ${res.status})`);
+    }
+    const data = await res.json();
+    return data.data;
+  }
+  /**
+   * Search products across all UCP merchants.
+   *
+   * @example
+   * ```typescript
+   * const products = await registry.searchProducts({
+   *   query: 'running shoes',
+   *   sort: 'price_asc',
+   *   limit: 5,
+   * });
+   *
+   * for (const product of products) {
+   *   console.log(`${product.title} - $${product.price} at ${product.merchant}`);
+   * }
+   * ```
+   */
+  async searchProducts(options = {}) {
+    const params = new URLSearchParams();
+    if (options.query) params.set("q", options.query);
+    if (options.category) params.set("category", options.category);
+    if (options.domain) params.set("domain", options.domain);
+    if (options.min_price) params.set("min_price", String(options.min_price));
+    if (options.max_price) params.set("max_price", String(options.max_price));
+    if (options.sort) params.set("sort", options.sort);
+    if (options.limit) params.set("limit", String(options.limit));
+    const url = `${this.baseUrl}/api/v1/products/search?${params}`;
+    const res = await this.fetch(url);
+    const data = await res.json();
+    return data.data;
+  }
+  /**
+   * Push a manifest version to an entity (requires API token).
+   *
+   * @example
+   * ```typescript
+   * const registry = new UCPRegistry({ apiKey: 'ucpr_...' });
+   *
+   * const version = await registry.push('merchants', 'mystore.com', {
+   *   manifest: { version: '1.0', capabilities: ['checkout'] },
+   *   commit_message: 'Initial push',
+   * });
+   *
+   * console.log(version.version); // '1.0.0'
+   * ```
+   */
+  async push(type, slug, options) {
+    const url = `${this.baseUrl}/api/v1/entities/${type}/${slug}/push`;
+    const res = await this.fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.error ?? `Push failed (HTTP ${res.status})`);
+    }
+    return await res.json();
+  }
+  /**
+   * List version history for an entity (requires API token).
+   */
+  async versions(type, slug) {
+    const url = `${this.baseUrl}/api/v1/entities/${type}/${slug}/versions`;
+    const res = await this.fetch(url);
+    return await res.json();
+  }
+  /**
+   * Diff two versions of an entity (requires API token).
+   */
+  async diff(type, slug, v1, v2) {
+    const url = `${this.baseUrl}/api/v1/entities/${type}/${slug}/diff/${v1}/${v2}`;
+    const res = await this.fetch(url);
+    return await res.json();
+  }
+  async fetch(url, init = {}) {
+    const headers = {
+      "Accept": "application/json",
+      "User-Agent": "ucpregistry-sdk/0.1.0",
+      ...init.headers ?? {}
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    return globalThis.fetch(url, { ...init, headers });
+  }
+};
+function createClient(config) {
+  return new UCPRegistry(config);
+}
+export {
+  UCPRegistry,
+  createClient
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ucpregistry",
+  "version": "0.1.0",
+  "description": "Official SDK for the UCP Registry API — discover UCP merchants, search products, and manage registry entities.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "ucp",
+    "registry",
+    "commerce",
+    "merchant",
+    "mcp",
+    "agent",
+    "ai",
+    "shopping"
+  ],
+  "author": "UCP Registry",
+  "license": "MIT",
+  "homepage": "https://ucpregistry.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ucpregistry/sdk"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}