@stateset/acp-client

Official Node.js client for the StateSet Agentic Commerce Protocol (ACP) Handler.

Installation

npm install @stateset/acp-client

Quick Start

HTTP Client

import { AcpHttpClient } from '@stateset/acp-client';

const client = new AcpHttpClient({
  baseUrl: 'http://localhost:8080',
  apiKey: 'your_api_key',
});

// Create a checkout session
const session = await client.createCheckoutSession({
  items: [
    { id: 'prod_123', quantity: 1 },
  ],
});

// Update with customer info
await client.updateCheckoutSession(session.id, {
  customer: {
    billing_address: {
      name: 'John Doe',
      email: '[email protected]',
      line1: '123 Main St',
      city: 'San Francisco',
      region: 'CA',
      postal_code: '94102',
      country: 'US',
    },
  },
});

// Complete checkout
const result = await client.completeCheckoutSession(session.id, {
  payment: { delegated_token: 'tok_xxx' },
});

console.log('Order ID:', result.order.id);

gRPC Client

import { AcpGrpcClient } from '@stateset/acp-client';

const client = new AcpGrpcClient({
  grpcAddress: 'localhost:50051',
  apiKey: 'your_api_key',
});

await client.connect();

const session = await client.createCheckoutSession({
  items: [{ id: 'prod_123', quantity: 1 }],
});

client.close();

API Reference

AcpHttpClient

| Method | Description | |--------|-------------| | createCheckoutSession(request) | Create a new checkout session | | getCheckoutSession(sessionId) | Get an existing session | | updateCheckoutSession(sessionId, request) | Update session details | | completeCheckoutSession(sessionId, request) | Complete with payment | | cancelCheckoutSession(sessionId) | Cancel a session | | delegatePayment(request) | Create PSP vault token | | healthCheck() | Check service health |

AcpGrpcClient

| Method | Description | |--------|-------------| | connect() | Establish gRPC connection | | close() | Close connection | | createCheckoutSession(request) | Create a new checkout session | | getCheckoutSession(sessionId) | Get an existing session | | updateCheckoutSession(request) | Update session details | | completeCheckoutSession(request) | Complete with payment | | cancelCheckoutSession(sessionId) | Cancel a session | | delegatePayment(request) | Create PSP vault token |

Configuration

interface AcpClientConfig {
  baseUrl?: string;      // HTTP base URL (default: http://localhost:8080)
  grpcAddress?: string;  // gRPC address (default: localhost:50051)
  apiKey?: string;       // API key for authentication
  timeout?: number;      // Request timeout in ms (default: 30000)
}

Error Handling

import { AcpHttpClient, AcpApiError } from '@stateset/acp-client';

try {
  await client.createCheckoutSession({ items: [] });
} catch (error) {
  if (error instanceof AcpApiError) {
    console.error('Type:', error.type);
    console.error('Code:', error.code);
    console.error('Message:', error.message);
    console.error('Param:', error.param);
    console.error('Status:', error.statusCode);
  }
}

Types

All TypeScript types are exported from the package:

import {
  CheckoutSession,
  CheckoutSessionStatus,
  LineItem,
  Money,
  Customer,
  Address,
  Order,
  // ... and more
} from '@stateset/acp-client';

Development

# Install dependencies
npm install

# Build
npm run build

# Build proto files (for gRPC)
npm run build:proto

License

MIT