Commerce SDK

The @agent-cards/commerce-sdk package gives your agent a buy tool that searches stores, builds a cart, and places the order once the shopper approves it. The package also hands your server a message, ready to post into the shopper’s chat, for each moment the shopper should hear about, such as a saved card or a placed order.

Install

npm install @agent-cards/commerce-sdk

The package runs on Node 18 or later and has no dependencies. The browser entry @agent-cards/commerce-sdk/browser imports no Node module, so any build tool takes it.

Wire it up

agent.ts

import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';

const agentcard = new AgentcardClient({
  clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
  clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '',
});

const buy = buyTool({ agentcard, externalUserId: 'user-42' });
const turn = buy.turn('two packs of AA batteries from Amazon');

The snippet builds one AgentcardClient, one buy tool for the shopper user-42, and one turn for the shopper’s message. Pass turn to your model as its tool. The Quickstart page walks through each framework.

Exports

Every name below comes from @agent-cards/commerce-sdk, except the browser entry.

Client

Export	Kind	What it is
`AgentcardClient`	class	Holds your credentials and talks to Agentcard.
`AgentcardApiError`	class	The error every refusal and failed call throws.
`DEFAULT_BASE_URL`	constant	`https://api.agentcard.sh`.
`BUY_TURN_TIMEOUT_MS`	constant	The wait for one purchase turn, in milliseconds.

Buy tool

Export	Kind	What it is
`buyTool`	function	Builds the buy tool for one shopper.
`BUY_TOOL_NAME`, `BUY_TOOL_DESCRIPTION`, `buyToolDefinition`, `parseBuyToolInput`	values	The tool’s name, description, definition and input check.
`forModel`, `forModelError`, `replyAsWritten`, `stripLinks`	functions	Turn an answer or an error into what a model may read.
`instantAck`, `instantReaction`, `ackFor`, `keepsYes`, `ACK_REACTION`	values	Decide whether a message gets a reaction or an instant reply.
`toOpenRouterTool`, `toAnthropicTool`	functions	Adapters for OpenRouter’s agent SDK, and a deprecated pass-through.
`productAction`	function	Names what taking a product does: `buy`, `reserve` or `book`.

Turn

Export	Kind	What it is
`buy.turn`	method	Opens the turn of one shopper message.
`buy.nextStep`	method	Opens the turn your agent takes once the shopper finishes a step outside the chat.
`nextStepPrompt`	function	Writes the model’s message for a next-step turn.
`toMessages`, `messageStream`, `typingDelay`	functions	Cut text into chat messages and space them.

Listen

Export	Kind	What it is
`agentcard.listen`, `listenToAgentcard`	method, function	Hear every event over one connection your server opens.
`AGENTCARD_EVENT_TYPES`	constant	Every event type Agentcard sends your company.

Webhooks

Export	Kind	What it is
`agentcardWebhook`	function	Builds the handler for your webhook endpoint.
`purchaseAgentWebhook`	function	The earlier handler, for `purchase.message` events only.
`verifyAgentcardWebhook`, `AgentcardSignatureError`	function, class	Check a delivery’s signature.
`readShopperMessage`, `readPurchaseMessage`, `isStale`	functions	Read the message an event carries.

Messages and steps

Export	Kind	What it is
`ShopperMessage`, `ShopperFacts`, `ShopperMessageKind`	types	The message you post into a shopper’s chat.
`SHOPPER_EVENT_TYPES`, `NEXT_STEP_KINDS`	constants	The event types that carry a message, and the kinds that advance a step.
`ACTION_LINK_KINDS`, `ACTION_LINK_ENDINGS`, `actionLinkId`, `actionLinkOutcome`, `isActionLink`	values	Tell which message ends which link.

Browser entry

Export	Kind	What it is
`actionWindows`	function	Opens each step in a pop-up and closes it when the step ends.

The browser entry also re-exports the action-link helpers.

Guides

Each guide shows what the shopper sees, the code that implements it, and how to check it in the sandbox.

Overview

Access tokens

Connections

Vault

Cards

Identity verification

Webhook endpoints

Blooio connection

Commerce SDK

Install

Wire it up

Exports

Client

Buy tool

Turn

Listen

Webhooks

Messages and steps

Browser entry

Guides

​Install

​Wire it up

​Exports

​Client

​Buy tool

​Turn

​Listen

​Webhooks

​Messages and steps

​Browser entry

​Guides

Install

Wire it up

Exports

Client

Buy tool

Turn

Listen

Webhooks

Messages and steps

Browser entry

Guides