@cresva/osp

Renamed twice, and this is the second time. The history matters because two of the three names are still installable and none of them is broken.

| name | published | why it changed | |---|---|---| | @cresva/sdk | until 2026-08-11 | Cresva has two APIs, and sdk said nothing about which one this client speaks. | | @cresva/acp | 2026-08-11 to 2026-09-15 | The protocol it speaks was renamed, because the name ACP collided with OpenAI and Stripe's Agentic Commerce Protocol. | | @cresva/osp | current | Speaks the OSP storefront API. |

It speaks the OSP storefront API. The platform API (ad metrics, forecasts, anomalies) lives at https://cresva.ai/docs and is called over HTTP.

@cresva/sdk and @cresva/acp are deprecated and still installable; neither will receive updates, and NEITHER WILL BE UNPUBLISHED. Switch with npm install @cresva/osp. The API surface is unchanged: this is a rename, not a rewrite, so the only edit a caller needs is the import specifier.

Official TypeScript SDK for the Cresva Open Storefront Protocol (OSP) storefront API. Lets brand engineers and AI agent builders query OSP storefronts directly from Node.js, with 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/osp

Requires Node.js 18 or later.

Quick start

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

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.feedback.submit / list

Cresva holds no funds at any point. A transaction here is a structured envelope carrying state; payment and settlement stay with the merchant's own processor.

Errors

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

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