@cresva/sdk

Official TypeScript SDK for the Cresva Agent Commerce Protocol (ACP) storefront API. Lets brand engineers and AI agent builders query ACP storefronts directly from Node.js — no MCP runtime required.

The SDK is a thin wrapper over api.cresva.ai. It uses native fetch (Node 18+), ships dual ESM + CJS bundles, and surfaces typed responses for every endpoint.

Install

npm install @cresva/sdk

Requires Node.js 18 or later.

Quick start

import { CresvaClient } from "@cresva/sdk";

const client = new CresvaClient();

const acp = await client.discover("demo_acp_store_v1");
const { products } = await client.products.list("demo_acp_store_v1");
const results = await client.products.search("demo_acp_store_v1", "running marathon");

console.log(acp.brand_name, products.length, results.products[0]?.title);

An API key is optional — public endpoints work without one but are rate limited to 100 requests/minute per IP. Authenticated keys lift the limit to 1000/minute:

const client = new CresvaClient({
  apiKey: process.env.CRESVA_API_KEY,
  timeoutMs: 15_000,           // default: 10s
  baseUrl: "https://api.cresva.ai", // default
});

API reference

| Method | HTTP | Description | | --- | --- | --- | | client.discover(brandId) | GET /.well-known/acp.json?brand=… | Discovery document with capabilities, currencies, rate limits. | | client.products.list(brandId, opts?) | GET /api/storefront/{brandId}/products | Paginated catalog (page, limit). | | client.products.get(brandId, productId) | GET /api/storefront/{brandId}/products/{id} | Single product card with review summary. | | client.products.search(brandId, q, opts?) | GET /api/storefront/{brandId}/search | Relevance-ranked search results. | | client.products.compare(brandId, productIds) | GET /api/storefront/{brandId}/compare?ids=… | Side-by-side comparison of 2–5 products. | | client.trust.get(brandId) | GET /api/storefront/{brandId}/trust | Trust score, tier, component breakdown. | | client.negotiate(brandId, payload) | POST /api/storefront/{brandId}/negotiate | Agent-to-agent negotiation. Requires agent.session_id. |

Full API reference: developers.cresva.ai/docs/api.

Reserved for the Management API

The following surfaces exist on the client for autocomplete and forward compatibility, but throw NotImplementedError until the Management API ships. Track progress on the protocol changelog.

• client.transactions.create / get / list / cancel / confirm
• client.escrow.hold / release / refund
• client.feedback.submit / list

Errors

import { CresvaApiError, CresvaNetworkError } from "@cresva/sdk";

try {
  await client.products.get("demo_acp_store_v1", "missing");
} catch (err) {
  if (err instanceof CresvaApiError) {
    console.error(err.status, err.code, err.message, err.details);
  } else if (err instanceof CresvaNetworkError) {
    console.error("network/timeout:", err.message);
  } else {
    throw err;
  }
}

• CresvaApiError — HTTP 4xx/5xx from the storefront. Carries { status, code, message, details }.
• CresvaNetworkError — DNS, connection, or timeout failure before a response was received.
• NotImplementedError — thrown by Management API surfaces that are not yet public.

License

MIT © Cresva