npm package: @stateset/acp-client
Description: Node.js client for StateSet Agentic Commerce Protocol Handler
Author: StateSet
Latest version: 1.0.0

# @stateset/acp-client

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

## Installation

```bash
npm install @stateset/acp-client
```

## Quick Start

### HTTP Client

```typescript
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: 'john@example.com',
      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

```typescript
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

```typescript
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

```typescript
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:

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

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

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

## License

MIT