🤖 AP2-lib - Agent Payments Protocol Library


> TypeScript/Deno implementation of the Agent Payments Protocol (AP2) - The open, universal protocol backed by Google and 60+ organizations for autonomous commerce.

---

🚀 What is AP2?

The Agent Payments Protocol (AP2) enables AI agents to make secure, autonomous purchases on behalf of users. This library provides the core cryptographic primitives, mandate management, and validation logic needed to implement AP2-compliant payment systems.

$3

- 🔒 JWT/JOSE Security - Industry-standard JWT signatures with RS256/ES256 algorithms
- 📝 Strong TypeScript Typing - Complete type safety for all AP2 structures
- 🏗️ SOLID Architecture - Clean OOP design with class-based API
- ✅ High Test Coverage - Comprehensive validation and error handling (91.0%+)
- 🌐 Universal Compatibility - Works in Deno, Node.js, and browsers
- 📊 Advanced Validation - Multi-layered mandate integrity checking

---

📦 Installation

$3

``bash
deno add @xja77/ap2-lib
`

$3

`bash
npm install ap2-lib
`

$3

`typescript
import { IntentMandateClass, CartMandateClass } from "https://deno.land/x/ap2_lib/mod.ts";
`

---

🏗️ Architecture Overview

`mermaid
graph TB
User[👤 User Intent] --> Agent[🤖 AI Agent]
Agent --> IntentMandate[📋 Intent Mandate]
IntentMandate --> Shopping[🛍️ Shopping Process]
Shopping --> CartMandate[🛒 Cart Mandate]
CartMandate --> JWT[🔏 JWT Signature]
JWT --> Payment[💳 Secure Payment]
Payment --> Verification[✅ JWT Verification]

style IntentMandate fill:#e1f5fe
style CartMandate fill:#f3e5f5
style JWT fill:#e8f5e8
style Payment fill:#fff3e0
`

$3

`mermaid
graph LR
A[ap2-lib] --> B[Types]
A --> C[Core]
A --> D[Utils]

B --> B1[Mandates]
B --> B2[Payment Request]
B --> B3[Contact Picker]

C --> C1[Mandates]
C --> C2[JWT/Crypto]
C --> C3[Validation]

C1 --> C1a[Intent]
C1 --> C1b[Cart]
C1 --> C1c[Payment]
C1 --> C1d[Shared]

D --> D1[Errors]
D --> D2[Date Utils]
`

---

🔥 Quick Start

$3

`typescript
import { IntentMandateClass } from "@xja77/ap2-lib";

// Create a user's purchase intent
const intent = await IntentMandateClass.createNew({
natural_language_description: "Wireless noise-canceling headphones under $200",
intent_expiry: "2024-12-31T23:59:59Z",
user_cart_confirmation_required: false,
merchants: ["amazon.com", "bestbuy.com"],
requires_refundability: true
});

console.log(intent.toString());
// Output: "Intent Mandate (ID: abc123...)"

console.log(intent.getData());
// Output: Complete intent mandate data structure

// Check if intent is expired
const isExpired = await intent.checkExpiry();
console.log(Intent expired: ${isExpired});
`

$3

`typescript
import { CartMandateClass } from "@xja77/ap2-lib";

// Define cart contents
const cartContents = {
id: "cart-12345",
merchant_name: "TechStore",
cart_expiry: "2024-12-31T23:59:59Z",
payment_request: {
id: "payment-67890",
methodData: [{ supportedMethods: "basic-card" }],
details: {
total: {
label: "Sony WH-1000XM4",
amount: { currency: "USD", value: "299.99" },
refund_period: 30
}
}
},
user_cart_confirmation_required: false
};

// Create cart mandate
const cartMandate = await CartMandateClass.createNew({
contents: cartContents
});

// Sign with JWT
await cartMandate.sign(
"-----BEGIN RSA PRIVATE KEY-----\n...", // Your RSA private key in PEM format
{ algorithm: "RS256", keyId: "key-1" },
{ merchantId: "merchant-123" }
);

// Verify the JWT signature
const isValid = await cartMandate.verifySignature();
console.log(Cart mandate JWT signature valid: ${isValid});

console.log(cartMandate.getStatus()); // "authorized"
`

$3

`typescript
import { CartMandateValidator } from "@xja77/ap2-lib";

// Direct validation using class methods (recommended)
await cartMandate.validate(); // Throws if invalid

// Or use validator directly
const validator = new CartMandateValidator();

// Validate cart mandate structure
const validationResult = await validator.validate(cartMandate.getData());
if (!validationResult.isValid) {
console.error("Validation errors:", validationResult.errors);
}

// Check mandate integrity
const integrityResult = await validator.validateIntegrity(cartMandate.getData());
if (!integrityResult.isValid) {
console.error("Integrity check failed:", integrityResult.errors);
}

// Check expiry using class method
const isExpired = await cartMandate.checkExpiry();
console.log(Mandate expired: ${isExpired});
`

---

📋 Mandate Types

| Type | Purpose | Signature Required | Methods Available |
|------|---------|-------------------|------------------|
| Intent | User's purchase intent in natural language | ❌ No | .validate(), .checkExpiry(), .toString() |
| Cart | Specific cart contents with pricing | ✅ Yes (JWT) | .sign(), .verifySignature(), .validate(), .checkExpiry() |
| Payment | Payment method and transaction details | ✅ Yes (JWT) | .sign(), .verifySignature(), .validate() |

$3

`mermaid
stateDiagram-v2
[*] --> Pending
Pending --> Authorized: validate()
Authorized --> Captured: execute_payment()
Authorized --> Failed: payment_error()
Captured --> Refunded: process_refund()
Pending --> Cancelled: user_cancel()
Failed --> [*]
Refunded --> [*]
Cancelled --> [*]
`

---

🔐 Security Features

$3

AP2-lib uses industry-standard JWT/JOSE signatures for cart mandate authentication:

`typescript
import { jwtService } from "@xja77/ap2-lib";

// Sign cart contents with JWT
const payload = {
iss: "merchant-123",
sub: "merchant-123",
aud: "payment-processor",
cart_hash: await jwtService.computeCartHash(cartContents),
};

const keyConfig = {
privateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
publicKey: "-----BEGIN RSA PUBLIC KEY-----\n...",
algorithm: "RS256" as const, // or "ES256"
};

const jwt = await jwtService.signMerchantAuthorization(payload, {
keyConfig,
expiresIn: 900 // 15 minutes
});

// Verify JWT signature
const result = await jwtService.verifyMerchantAuthorization(jwt, {
keyConfig,
audience: "payment-processor",
issuer: "merchant-123"
});

console.log(JWT valid: ${result.valid});
`

$3

1. Schema Validation - TypeScript interfaces and runtime checks
2. Business Logic Validation - AP2 protocol compliance
3. Cryptographic Validation - Signature verification and integrity
4. Temporal Validation - Expiry and timing checks

---

🧪 Testing

Run the comprehensive test suite:

`bash


Run all tests

deno task test

Generate coverage report

deno task coverage

Detailed coverage with uncovered lines

deno task coverage:detailed
`

$3

- Total Tests: 260+ passing
- Line Coverage: 91.0%+
- Branch Coverage: 89.9%+
- Files: 54+ TypeScript modules

---

📚 API Documentation

$3

📖 Browse Complete API Documentation →

$3

`bash


Generate HTML documentation

deno task doc

View documentation in terminal

deno doc ./src/mod.ts
`

$3

`typescript
// Mandate Classes (OOP API)
export class IntentMandateClass extends BaseMandate {
static createNew(params: CreateIntentMandateParams): Promise
validate(): Promise
checkExpiry(currentDate?: Date): Promise
toString(): string
getData(): IntentMandate
getStatus(): MandateStatus
}

export class CartMandateClass extends BaseMandate {
static createNew(params: CreateCartMandateParams): Promise
sign(privateKey: string, keyConfig: Partial, merchantInfo: { merchantId: string }): Promise
verifySignature(): Promise
validate(): Promise
checkExpiry(currentDate?: Date): Promise
}

// Validation Classes
export class IntentMandateValidator {
validate(mandate: IntentMandate): Promise
validateIntegrity(mandate: IntentMandate): Promise
checkExpiry(mandate: IntentMandate, currentDate?: Date): Promise
}

// JWT Service
export class JWTService implements IJWTService {
signMerchantAuthorization(payload: MerchantAuthorizationPayload, options: JWTSignOptions): Promise
verifyMerchantAuthorization(jwt: string, options: JWTVerifyOptions): Promise
computeCartHash(cartContents: unknown): Promise
generateJTI(): string
}
`

---

🛠️ Development

$3

`bash
deno task dev # Watch mode development
deno task test # Run test suite
deno task coverage # Generate coverage report
deno task build # Build for npm distribution
deno task publish # Publish to JSR and npm
`

$3

`
src/
├── core/ # Core AP2 implementations
│ ├── mandates/ # Mandate management (Intent, Cart, Payment)
│ ├── jwt/ # JWT/JWS cryptographic services
│ ├── config/ # Validation configuration
│ └── utils/ # Internal utilities
├── types/ # TypeScript type definitions
│ ├── mandates.ts # Mandate interfaces
│ ├── payment_request.ts # W3C Payment Request types
│ └── contact_picker.ts # Contact picker types
└── utils/ # Public utility functions
├── errors.ts # Error definitions
└── date.ts # Date/time utilities
`

$3

- Factory Pattern - Mandate creation (IntentMandateClass.createNew(), CartMandateClass.createNew())
- Strategy Pattern - Validation strategies per mandate type
- Template Method - Base mandate class with common functionality
- Command Pattern - Validation and serialization operations
- Interface Segregation - Focused JWT service interfaces

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following SOLID principles
4. Ensure 100% test coverage: deno task test`
5. Submit a pull request

$3

- Follow TypeScript strict mode
- Use descriptive variable and function names
- Write comprehensive JSDoc comments
- Maintain SOLID design principles
- Achieve 100% test coverage for new features

---

🌟 Why AP2-lib?

$3

- Type Safety: Complete TypeScript coverage prevents runtime errors
- Standards Compliant: Full AP2 protocol implementation
- Universal: Works across Deno, Node.js, and browsers
- Well-Tested: Comprehensive test suite with high coverage

$3

- Security First: Industry-standard cryptography
- Regulatory Ready: Built for PCI-DSS compliance
- Scalable: SOLID architecture supports high-volume transactions
- Auditable: Complete transaction trails and validation

$3

- Open Standard: Google-backed, vendor-neutral protocol
- Interoperable: Works with any AP2-compliant system
- Future-Proof: Designed for the autonomous commerce era

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

- Google and the AP2 Working Group for the protocol specification
- 60+ Organizations supporting the AP2 standard
- Deno Team for the excellent runtime and tooling
- Web Standards Community for Payment Request API and Web Crypto API

---