Agent Commerce SDK

The Agent Commerce SDK provides a complete set of backend abstractions to build AI-driven, conversational shopping experiences. It includes built-in services for natural language intent extraction, product search, AI recommendations, checkout orchestration, and Two-Stage Mandate Authorization (AP2) for secure cryptographic checkout and payments.

This SDK is designed to run in modern Node.js backend environments and serves as the bridge between your merchant APIs, Large Language Models (LLMs), and your user-facing applications.

Features

• Agent & LLM Service: Translate natural language ("Show me gaming laptops under $1000") into structured product queries and intent parameters.
• Product & Catalog: Unified interfaces (ProductProvider) to connect the AI agent directly to your backend merchant catalog.
• Intelligent Recommendations: Combine your existing merchant endpoints (upsell/cross-sell APIs) with AI-fallback recommendations.
• Checkout & Payments: Abstracted checkout and payment flows with built-in Razorpay integration (RazorpayPaymentProvider).
• AP2 Mandate Authorization: Secure cryptographic signature flows for checkouts and payments utilizing ES256 key pairs to prevent fraud and guarantee user consent.

Installation

npm install agent-commerce-sdk

Quick Start

Here is a minimal example showing how to initialize the core services using the provided default HTTP implementations.

import { 
  AgentService, 
  LLMService, 
  ProductService, 
  HttpProductProvider,
  ProductRecommendationService,
  HttpRecommendationProvider
} from "agent-commerce-sdk";

// 1. Initialize the LLM Service (e.g., using Gemini)
const llmService = new LLMService("YOUR_API_KEY", "gemini");

// 2. Connect your merchant catalog via HTTP Provider
const productProvider = new HttpProductProvider({
  baseUrl: "https://api.yourmerchant.com",
  merchantId: "merch_123"
});
const productService = new ProductService(productProvider);

// 3. Connect your recommendation endpoints
const recommendationProvider = new HttpRecommendationProvider({
  baseUrl: "https://api.yourmerchant.com",
  merchantId: "merch_123"
});
const recommendationService = new ProductRecommendationService(
  productService,
  recommendationProvider,
  llmService
);

// 4. Initialize the main Agent Service
const agentService = new AgentService(
  productService,
  llmService,
  recommendationService
);

// Process a natural language query
const response = await agentService.process({
  model: "gemini-2.5-flash",
  message: "I am looking for a noise cancelling headphone"
});

console.log(response.response);

Architecture

The SDK revolves around a Service and Provider architecture.

• Services (e.g., ProductService, CheckoutService) orchestrate the business logic, AI interactions, and AP2 cryptographic workflows.
• Providers (e.g., ProductProvider, PaymentProvider) act as interfaces to integrate your own backend APIs, databases, or third-party payment gateways.

High-Level Flow

1. User Request → AgentService
2. Intent Extraction → LLMService extracts structured query parameters.
3. Product Discovery → ProductService fetches catalog data via your ProductProvider.
4. Recommendation → ProductRecommendationService fetches cross-sells/upsells.
5. Checkout → CheckoutService validates stock and returns a Checkout ID.
6. AP2 / Payment → AP2Service signs mandates, and PaymentService processes the charge.

Core Modules

Agent & LLM Service

The AgentService is responsible for intent extraction. It parses natural language to build a structured query containing keywords, categories, and price filters.

// The agent will extract intent, search products, and generate a contextual response.
const response = await agentService.process({
    model: "gemini-2.5-flash",
    message: "Do you have any blue running shoes under $150?"
});

Product Discovery

Implement a ProductProvider to plug in your custom backend, or use the out-of-the-box HttpProductProvider.

import { HttpProductProvider, ProductService } from "agent-commerce-sdk";

const provider = new HttpProductProvider({ baseUrl: "https://api.store.com", merchantId: "123" });
const productService = new ProductService(provider);

const products = await productService.searchProducts({ 
  query: "laptops", 
  limit: 5 
});

Recommendations

The ProductRecommendationService takes an array of selected products and fetches relevant upsells or cross-sells. It first attempts to use the merchant's RecommendationProvider and gracefully falls back to an AI-powered recommendation strategy if the provider fails.

const recommendations = await recommendationService.getRecommendations({
    selectedProducts: [ { id: "prod_gaming_laptop", quantity: 1 } ],
    type: "cross_sell",
    limit: 3
});

Checkout & AP2 Mandates

The SDK enforces a secure Two-Stage Mandate Authorization (AP2) pattern. Rather than initiating a checkout immediately, the backend generates a CheckoutMandate containing a JWT.

import { AP2Service } from "agent-commerce-sdk";

const ap2Service = new AP2Service({
    merchantPrivateKey: "YOUR_PRIVATE_KEY",
    merchantKeyId: "KEY_ID"
});

// Create a verifiable mandate for the client to sign
const mandate = await ap2Service.createCheckoutAuthorization({
    checkoutId: "chk_789",
    checkout: { items: [...], total: 1500 }
});

The user application will sign this mandate using an ES256 keypair, which is then verified by the backend before a PaymentMandate is issued.

Payments

You can plug in your own payment gateway or use the included RazorpayPaymentProvider.

import { RazorpayPaymentProvider, PaymentService } from "agent-commerce-sdk";

const paymentProvider = new RazorpayPaymentProvider({
    keyId: "rzp_test_123",
    keySecret: "secret"
});
const paymentService = new PaymentService(paymentProvider);

const result = await paymentService.processPayment({
    checkoutId: "chk_789",
    amount: 1500,
    currency: "USD",
    paymentMandate: { /* Verified Mandate */ }
});

Requirements

• Node.js: Requires ESM resolution.
• TypeScript: Set "moduleResolution": "nodenext" in your tsconfig.json.

Development

# Install dependencies
npm install

# Build the SDK using TypeScript
npm run build

This project generates ECMAScript Modules (ESM) and CommonJS types in the dist directory.

License

License documentation needs to be provided by the package maintainers.