@paypal/agentic-commerce-spec

@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

npm install @paypal/agentic-commerce-spec

Quick Start

Basic Usage

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

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

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

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:

// 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

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:

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

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:

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

Handle validation issues appropriately:

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:

# 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