@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.

Installation

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

Quick Start

$3

`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);
`

$3

`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 });
`

$3

`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",
},
});
`

$3

`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

$3

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

$3

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

$3

`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 });
`

$3

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;
};
`

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
- GitHub Issues