cresvadevelopers

SDKs

Official client libraries for the Agent Commerce Protocol. Install an SDK to start querying storefronts in minutes.

JavaScript / TypeScript

Full-featured SDK with TypeScript types, auto-retry, and streaming support.

@cresva/sdk

Python

Pythonic SDK with type hints, async support, and automatic pagination.

cresva

JavaScript / TypeScript SDK

Installation

npm install @cresva/sdk

Initialization

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

const client = new CresvaClient({
  apiKey: process.env.CRESVA_API_KEY,  // pk_live_* or sk_live_*
  brandId: "brand_abc123",
  // Optional configuration:
  timeout: 30000,       // Request timeout in ms (default: 30s)
  maxRetries: 3,        // Auto-retry on transient errors (default: 3)
  baseUrl: undefined,   // Override base URL (for testing)
});

Core Methods

TypeScript
// Search products
const results = await client.query({
  intent: "search",
  query: "wireless headphones under $200",
  filters: { price: { max: 200, currency: "USD" } },
  limit: 10,
});

// Get a product
const product = await client.products.get("prod_h7k2m");

// List products
const products = await client.products.list({ category: "electronics" });

// Get recommendations
const recs = await client.recommend("prod_h7k2m", { type: "similar" });

// Compare products
const comparison = await client.compare({
  productIds: ["prod_h7k2m", "prod_x9y8z"],
});

// Negotiate
const negotiation = await client.negotiate({
  action: "initiate",
  productId: "prod_h7k2m",
  offeredPrice: 149.99,
  currency: "USD",
});

// Create transaction
const txn = await client.transactions.create({
  items: [{ productId: "prod_h7k2m", quantity: 1, price: 164.99 }],
  currency: "USD",
  shippingAddress: { line1: "123 Main St", city: "SF", state: "CA", postalCode: "94102", country: "US" },
});

// Get trust score
const trust = await client.trust.get();

TypeScript Types

TypeScript
import type {
  AgentQueryRequest,
  AgentQueryResponse,
  AgentProductCard,
  NegotiationRequest,
  NegotiationResponse,
  TransactionRequest,
  TransactionResponse,
  TrustScore,
} from "@cresva/sdk";

Error Handling

TypeScript
import { CresvaError, RateLimitError, NotFoundError } from "@cresva/sdk";

try {
  const results = await client.query({ intent: "search", query: "headphones" });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof NotFoundError) {
    console.log("Product not found");
  } else if (error instanceof CresvaError) {
    console.log("API error:", error.code, error.message);
  }
}

Python SDK

Installation

pip install cresva

Initialization

Python
from cresva import CresvaClient

client = CresvaClient(
    api_key="pk_live_your_key_here",  # or use CRESVA_API_KEY env var
    brand_id="brand_abc123",
    # Optional:
    timeout=30,         # Request timeout in seconds
    max_retries=3,      # Auto-retry on transient errors
)

# Async client
from cresva import AsyncCresvaClient

async_client = AsyncCresvaClient(
    api_key="pk_live_your_key_here",
    brand_id="brand_abc123",
)

Core Methods

Python
# Search products
results = client.query(
    intent="search",
    query="wireless headphones under $200",
    filters={"price": {"max": 200, "currency": "USD"}},
    limit=10,
)

# Get a product
product = client.products.get("prod_h7k2m")

# List products with automatic pagination
for product in client.products.list(category="electronics"):
    print(product.title, product.price)

# Negotiate
negotiation = client.negotiate(
    action="initiate",
    product_id="prod_h7k2m",
    offered_price=149.99,
    currency="USD",
)

# Create transaction
txn = client.transactions.create(
    items=[{"product_id": "prod_h7k2m", "quantity": 1, "price": 164.99}],
    currency="USD",
    shipping_address={
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94102",
        "country": "US",
    },
)

# Get trust score
trust = client.trust.get()
print(f"Trust: {trust.overall}/100 ({trust.tier})")

Error Handling

Python
from cresva.errors import CresvaError, RateLimitError, NotFoundError

try:
    results = client.query(intent="search", query="headphones")
except RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after}s")
except NotFoundError:
    print("Product not found")
except CresvaError as e:
    print(f"API error: {e.code} - {e.message}")

cURL Examples

Every endpoint can be accessed directly with cURL. Replace pk_live_your_key_here with your API key and brand_abc123 with your brand ID.

Search Products

bash
curl "https://cresva.ai/api/storefront/brand_abc123/search?q=wireless+headphones&max_price=200" \
  -H "Authorization: Bearer pk_live_your_key_here"

Query Products

bash
curl -X POST "https://cresva.ai/api/storefront/brand_abc123/query" \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "search",
    "query": "noise-cancelling headphones",
    "filters": {"price": {"max": 200, "currency": "USD"}},
    "limit": 5
  }'

Initiate Negotiation

bash
curl -X POST "https://cresva.ai/api/storefront/brand_abc123/negotiate" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "initiate",
    "product_id": "prod_h7k2m",
    "offered_price": 149.99,
    "currency": "USD"
  }'

Check Health

bash
curl "https://cresva.ai/api/storefront/brand_abc123/health"