npm package: @paypal/agentic-commerce-spec
Description: TypeScript types, Zod schemas, and Axios client for PayPal Cart API v1
Latest version: 1.1.0

# @paypal/agentic-commerce-spec

TypeScript types, Zod schemas, and Axios client for PayPal Cart API v1, generated from OpenAPI specification.

## Overview

This package provides comprehensive TypeScript support for PayPal Cart API v1, enabling AI-powered agentic commerce integrations:

- **TypeScript Types**: Complete type definitions for all API operations
- **Zod Schemas**: Runtime validation for request/response data
- **Axios Client**: HTTP client with full type safety
- **SDK Functions**: Typed functions for each API endpoint

Generated automatically from the official OpenAPI specification using [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts).

## Installation

```bash
npm install @paypal/agentic-commerce-spec
```

## Quick Start

### Basic Usage

```typescript
import {
  PayPalCart,
  createCart,
  getCart,
  updateCart,
  payPalCartSchema,
  client,
} from "@paypal/agentic-commerce-spec";

// Create a new cart
const cartData = {
  items: [
    {
      item_id: "ITEM123",
      variant_id: "VAR456",
      quantity: 2,
      unit_price: "29.99",
    },
  ],
  totals: {
    total: "59.98",
    currency_code: "USD",
  },
};

const newCart = await createCart({
  body: cartData,
});

console.log("Cart created:", newCart.data);
```

### Runtime Validation with Zod

```typescript
import { payPalCartSchema, createCart } from "@paypal/agentic-commerce-spec";

// Validate incoming data
const validatedCart = payPalCartSchema.parse(unknownCartData);

// Validate request before API call
const result = await createCart({ body: validatedCart });
```

### Client Configuration

```typescript
import { client } from "@paypal/agentic-commerce-spec";

// Configure the HTTP client
client.setConfig({
  baseURL: "https://your-api-server.com/api/paypal/v1",
  headers: {
    Authorization: "Bearer your-jwt-token",
  },
});
```

### Error Handling

```typescript
import { createCart } from "@paypal/agentic-commerce-spec";

try {
  const cart = await createCart({ body: cartData });

  if (cart.data?.validation_issues?.length) {
    console.log("Validation issues:", cart.data.validation_issues);
  }
} catch (error) {
  console.error("API Error:", error);
}
```

## API Operations

### Cart Management

- **`createCart(options)`** - Create a new cart
- **`getCart(options)`** - Retrieve cart by ID
- **`updateCart(options)`** - Update existing cart
- **`checkoutCart(options)`** - Complete cart checkout

### Type Definitions

Key types exported from the package:

```typescript
// Core cart type
type PayPalCart = {
  id?: string;
  status?: "CREATED" | "INCOMPLETE" | "READY" | "COMPLETED";
  items: CartItem[];
  totals?: CartTotals;
  shipping_address?: Address;
  billing_address?: Address;
  payment_method?: PaymentMethod;
  validation_issues?: ValidationIssue[];
  // ... additional fields
};

// API request/response types
type CreateCartRequest = {
  /* ... */
};
type CreateCartResponse = {
  /* ... */
};
type UpdateCartRequest = {
  /* ... */
};
type CheckoutRequest = {
  /* ... */
};
```

## Advanced Usage

### Complete Import Example

```typescript
import {
  // Types
  PayPalCart,
  CartItem,
  ValidationIssue,

  // SDK Functions
  createCart,
  getCart,
  updateCart,

  // Zod Schemas
  payPalCartSchema,

  // Client
  client,
} from "@paypal/agentic-commerce-spec";

// Configure authentication
client.setConfig({
  baseURL: "https://your-api-server.com/api/paypal/v1",
  headers: {
    Authorization: "Bearer YOUR_PAYPAL_JWT_TOKEN",
  },
});

// Validate and create cart
const validatedCart = payPalCartSchema.parse(incomingData);
const result = await createCart({ body: validatedCart });
```

### Authentication

The API requires JWT authentication. Set up your client with proper headers:

```typescript
import { client } from "@paypal/agentic-commerce-spec";

client.setConfig({
  headers: {
    Authorization: "Bearer YOUR_PAYPAL_JWT_TOKEN",
  },
});
```

## Cart Status Flow

Understanding cart statuses is crucial for proper integration:

- **`CREATED`** - Cart successfully created and ready for payment
- **`INCOMPLETE`** - Cart has validation issues that need resolution
- **`READY`** - Previously incomplete cart is now ready
- **`COMPLETED`** - Order finished, payment captured

```typescript
const cart = await createCart({ body: cartData });

switch (cart.data?.status) {
  case "CREATED":
    // Proceed to payment
    break;
  case "INCOMPLETE":
    // Handle validation issues
    console.log("Issues:", cart.data.validation_issues);
    break;
  case "READY":
    // Cart is ready for checkout
    break;
  case "COMPLETED":
    // Order complete
    break;
}
```

## Validation Issues

When a cart has validation issues, they're returned in the `validation_issues` array:

```typescript
type ValidationIssue = {
  code: string;
  type: string;
  message: string;
  user_message?: string;
  item_id?: string;
  field?: string;
  context?: Record<string, any>;
};
```

Handle validation issues appropriately:

```typescript
if (cart.data?.validation_issues?.length) {
  cart.data.validation_issues.forEach((issue) => {
    console.log(`${issue.type}: ${issue.message}`);
    if (issue.item_id) {
      console.log(`Affects item: ${issue.item_id}`);
    }
  });
}
```

## Development

This package uses pre-generated code committed to the repository. To regenerate:

```bash
# From the package directory
npm run generate

# Or from the workspace root
npm run generate-agentic-spec
```

## Architecture

```
Customer ↔ AI Agent ↔ PayPal Commerce Platform ↔ Your Merchant API
```

This package facilitates the "Your Merchant API" integration with PayPal's commerce platform.

## License

Apache-2.0

## Support

For issues and questions:

- [PayPal Developer Documentation](https://developer.paypal.com)
- [GitHub Issues](https://github.com/paypal/agent-commerce/issues)