ap2-payment-handler 1.0.0

package/dist/x402.d.ts

@@ -0,0 +1,31 @@
+import { AP2PaymentResponse } from './types';
+export declare class X402Bridge {
+    /**
+     * Parse an HTTP 402 Payment Required response headers to extract payment details.
+     */
+    parsePaymentRequired(headers: Record<string, string>): Promise<{
+        amount: string;
+        currency: string;
+        address: string;
+    }>;
+    /**
+     * Build a non-custodial payment proof for a given payment request.
+     */
+    buildPaymentProof(params: {
+        amount: string;
+        currency: string;
+        address: string;
+        agentId: string;
+    }): Promise<{
+        proof: string;
+        timestamp: number;
+    }>;
+    /**
+     * Handle an HTTP response. Returns an AP2PaymentResponse if it's a 402, null otherwise.
+     */
+    handleResponse(response: {
+        status: number;
+        headers: Record<string, string>;
+    }): Promise<AP2PaymentResponse | null>;
+}
+//# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAM7C,qBAAa,UAAU;IACrB;;OAEG;IACG,oBAAoB,CACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IA0BjE;;OAEG;IACG,iBAAiB,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAejD;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE;QAC7B,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAkBvC"}

package/dist/x402.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402Bridge = void 0;
+function generateId() {
+    return Math.random().toString(36).substring(2) + Date.now().toString(36);
+}
+class X402Bridge {
+    /**
+     * Parse an HTTP 402 Payment Required response headers to extract payment details.
+     */
+    async parsePaymentRequired(headers) {
+        const paymentHeader = headers['x-payment-required'] || headers['X-Payment-Required'];
+        if (paymentHeader) {
+            try {
+                const parsed = JSON.parse(paymentHeader);
+                return {
+                    amount: parsed.amount || '0',
+                    currency: parsed.currency || 'USDC',
+                    address: parsed.address || '',
+                };
+            }
+            catch {
+                // fall through to individual headers
+            }
+        }
+        const amount = headers['x-payment-amount'] || headers['X-Payment-Amount'] || '0';
+        const currency = headers['x-payment-currency'] || headers['X-Payment-Currency'] || 'USDC';
+        const address = headers['x-payment-address'] || headers['X-Payment-Address'] || '';
+        if (!address) {
+            throw new Error('Missing payment address in 402 response headers');
+        }
+        return { amount, currency, address };
+    }
+    /**
+     * Build a non-custodial payment proof for a given payment request.
+     */
+    async buildPaymentProof(params) {
+        const timestamp = Date.now();
+        const proofData = {
+            agentId: params.agentId,
+            amount: params.amount,
+            currency: params.currency,
+            address: params.address,
+            timestamp,
+            nonce: generateId(),
+        };
+        // In production this would be EIP-712 signed. Here we encode it.
+        const proof = Buffer.from(JSON.stringify(proofData)).toString('base64');
+        return { proof, timestamp };
+    }
+    /**
+     * Handle an HTTP response. Returns an AP2PaymentResponse if it's a 402, null otherwise.
+     */
+    async handleResponse(response) {
+        if (response.status !== 402) {
+            return null;
+        }
+        try {
+            const paymentDetails = await this.parsePaymentRequired(response.headers);
+            return {
+                success: false,
+                error: `Payment required: ${paymentDetails.amount} ${paymentDetails.currency} to ${paymentDetails.address}`,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `402 Payment Required: ${err.message}`,
+            };
+        }
+    }
+}
+exports.X402Bridge = X402Bridge;
+//# sourceMappingURL=x402.js.map

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "ap2-payment-handler",
+  "version": "1.0.0",
+  "description": "Non-custodial crypto payment handler for the AP2 Agent Payment Protocol. Supports x402, USDC/Base, EIP-712 signing. Zero key escrow.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --testEnvironment=node",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": ["ap2", "agent-payments", "x402", "crypto", "non-custodial", "agentic-commerce", "ai-agents"],
+  "author": "AI Agent Economy <max@ai-agent-economy.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/up2itnow0822/ap2-payment-handler.git"
+  },
+  "dependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "@types/jest": "^29.0.0"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": ["**/src/**/*.test.ts"],
+    "testPathIgnorePatterns": ["/node_modules/", "/dist/"]
+  }
+}

package/src/__tests__/handler.test.ts

@@ -0,0 +1,278 @@
+import { AP2PaymentHandler } from '../handler';
+import { X402Bridge } from '../x402';
+import { AP2ValidationError, validateMandate } from '../validation';
+import { IntentMandate, CartMandate } from '../types';
+
+const futureTime = Date.now() + 60_000; // 1 minute from now
+const pastTime = Date.now() - 60_000;   // 1 minute ago
+
+function makeIntentMandate(overrides: Partial<IntentMandate> = {}): IntentMandate {
+  return {
+    type: 'intent',
+    agentId: 'agent-123',
+    merchantId: 'merchant-456',
+    maxAmount: 10.0,
+    currency: 'USDC',
+    ttl: futureTime,
+    isAgentInitiated: true,
+    isNonCustodial: true,
+    ...overrides,
+  };
+}
+
+function makeCartMandate(overrides: Partial<CartMandate> = {}): CartMandate {
+  return {
+    type: 'cart',
+    agentId: 'agent-123',
+    lineItems: [
+      { name: 'Widget', price: 5.0, qty: 2 },
+    ],
+    total: 10.0,
+    currency: 'USDC',
+    ...overrides,
+  };
+}
+
+describe('AP2PaymentHandler', () => {
+  let handler: AP2PaymentHandler;
+
+  beforeEach(() => {
+    handler = new AP2PaymentHandler({ supportedMethods: ['usdc_base', 'x402'] });
+  });
+
+  // 1. IntentMandate creation with correct flags
+  test('createIntentMandate sets isAgentInitiated and isNonCustodial', () => {
+    const mandate = handler.createIntentMandate({
+      agentId: 'a1',
+      merchantId: 'm1',
+      maxAmount: 5,
+      currency: 'USDC',
+      ttl: futureTime,
+    });
+    expect(mandate.isAgentInitiated).toBe(true);
+    expect(mandate.isNonCustodial).toBe(true);
+    expect(mandate.type).toBe('intent');
+  });
+
+  // 2. CartMandate total validation (correct sum)
+  test('validateMandate accepts CartMandate with correct total', () => {
+    const cart = makeCartMandate();
+    expect(() => validateMandate(cart)).not.toThrow();
+  });
+
+  // 3. CartMandate total validation (wrong sum — should throw)
+  test('validateMandate rejects CartMandate with wrong total', () => {
+    const cart = makeCartMandate({ total: 99.0 });
+    expect(() => validateMandate(cart)).toThrow(AP2ValidationError);
+    expect(() => validateMandate(cart)).toThrow(/mismatch/);
+  });
+
+  // 4. IntentMandate TTL validation (future TTL — valid)
+  test('validateMandate accepts IntentMandate with future TTL', () => {
+    const intent = makeIntentMandate({ ttl: futureTime });
+    expect(() => validateMandate(intent)).not.toThrow();
+  });
+
+  // 5. IntentMandate TTL validation (past TTL — invalid)
+  test('validateMandate rejects IntentMandate with expired TTL', () => {
+    const intent = makeIntentMandate({ ttl: pastTime });
+    expect(() => validateMandate(intent)).toThrow(AP2ValidationError);
+    expect(() => validateMandate(intent)).toThrow(/expired/);
+  });
+
+  // 6. Handler with usdc_base method
+  test('handle succeeds with usdc_base method', async () => {
+    const response = await handler.handle({
+      mandate: makeIntentMandate(),
+      preferredMethod: 'usdc_base',
+    });
+    expect(response.success).toBe(true);
+    expect(response.paymentMandate?.method).toBe('usdc_base');
+  });
+
+  // 7. Handler with x402 method
+  test('handle succeeds with x402 method', async () => {
+    const response = await handler.handle({
+      mandate: makeIntentMandate(),
+      preferredMethod: 'x402',
+    });
+    expect(response.success).toBe(true);
+    expect(response.paymentMandate?.method).toBe('x402');
+  });
+
+  // 8. Handler with unsupported method falls back
+  test('handle falls back to first supported method when preferred is unsupported', async () => {
+    const response = await handler.handle({
+      mandate: makeIntentMandate(),
+      preferredMethod: 'usdc_arbitrum',
+    });
+    expect(response.success).toBe(true);
+    expect(response.paymentMandate?.method).toBe('usdc_base');
+  });
+
+  // 9. Handler returns success with transactionId
+  test('handle returns transactionId on success', async () => {
+    const response = await handler.handle({
+      mandate: makeIntentMandate(),
+      preferredMethod: 'usdc_base',
+    });
+    expect(response.success).toBe(true);
+    expect(response.transactionId).toBeDefined();
+    expect(typeof response.transactionId).toBe('string');
+  });
+
+  // 10. Handler audit trail includes entries
+  test('handle returns paymentMandate with non-empty auditTrail', async () => {
+    const response = await handler.handle({
+      mandate: makeIntentMandate(),
+      preferredMethod: 'usdc_base',
+    });
+    expect(response.paymentMandate?.auditTrail.length).toBeGreaterThan(0);
+  });
+
+  // 11. PaymentMandate has isNonCustodial flag
+  test('paymentMandate has isNonCustodial set to true', async () => {
+    const response = await handler.handle({
+      mandate: makeIntentMandate(),
+      preferredMethod: 'usdc_base',
+    });
+    expect(response.paymentMandate?.isNonCustodial).toBe(true);
+  });
+
+  // 16. Validation rejects missing agentId
+  test('validateMandate rejects missing agentId', () => {
+    const intent = makeIntentMandate({ agentId: '' });
+    expect(() => validateMandate(intent)).toThrow(AP2ValidationError);
+    expect(() => validateMandate(intent)).toThrow(/agentId/);
+  });
+
+  // 17. Validation rejects negative amount
+  test('validateMandate rejects negative maxAmount on IntentMandate', () => {
+    const intent = makeIntentMandate({ maxAmount: -5 });
+    expect(() => validateMandate(intent)).toThrow(AP2ValidationError);
+    expect(() => validateMandate(intent)).toThrow(/positive/);
+  });
+
+  // 18. createIntentMandate sets correct defaults
+  test('createIntentMandate preserves all provided params', () => {
+    const mandate = handler.createIntentMandate({
+      agentId: 'myAgent',
+      merchantId: 'myMerchant',
+      maxAmount: 25,
+      currency: 'USDC',
+      ttl: futureTime,
+    });
+    expect(mandate.agentId).toBe('myAgent');
+    expect(mandate.merchantId).toBe('myMerchant');
+    expect(mandate.maxAmount).toBe(25);
+    expect(mandate.currency).toBe('USDC');
+  });
+
+  // 19. createCartMandate with multiple items
+  test('createCartMandate with multiple line items', () => {
+    const mandate = handler.createCartMandate({
+      agentId: 'agent-1',
+      lineItems: [
+        { name: 'Item A', price: 3, qty: 2 },
+        { name: 'Item B', price: 4, qty: 1 },
+      ],
+      total: 10,
+      currency: 'USDC',
+    });
+    expect(mandate.type).toBe('cart');
+    expect(mandate.lineItems.length).toBe(2);
+    expect(mandate.total).toBe(10);
+  });
+
+  // 20. getSupportedMethods returns config
+  test('getSupportedMethods returns configured methods', () => {
+    const methods = handler.getSupportedMethods();
+    expect(methods).toContain('usdc_base');
+    expect(methods).toContain('x402');
+    expect(methods.length).toBe(2);
+  });
+});
+
+describe('X402Bridge', () => {
+  let bridge: X402Bridge;
+
+  beforeEach(() => {
+    bridge = new X402Bridge();
+  });
+
+  // 12. X402Bridge parsePaymentRequired
+  test('parsePaymentRequired extracts payment details from headers', async () => {
+    const headers = {
+      'x-payment-amount': '5.00',
+      'x-payment-currency': 'USDC',
+      'x-payment-address': '0xabc123',
+    };
+    const result = await bridge.parsePaymentRequired(headers);
+    expect(result.amount).toBe('5.00');
+    expect(result.currency).toBe('USDC');
+    expect(result.address).toBe('0xabc123');
+  });
+
+  // 13. X402Bridge buildPaymentProof
+  test('buildPaymentProof returns a proof and timestamp', async () => {
+    const result = await bridge.buildPaymentProof({
+      amount: '5.00',
+      currency: 'USDC',
+      address: '0xabc123',
+      agentId: 'agent-1',
+    });
+    expect(result.proof).toBeTruthy();
+    expect(typeof result.proof).toBe('string');
+    expect(result.timestamp).toBeGreaterThan(0);
+  });
+
+  // 14. X402Bridge handleResponse for 402 status
+  test('handleResponse returns AP2PaymentResponse for 402 status', async () => {
+    const response = await bridge.handleResponse({
+      status: 402,
+      headers: {
+        'x-payment-amount': '10.00',
+        'x-payment-currency': 'USDC',
+        'x-payment-address': '0xdef456',
+      },
+    });
+    expect(response).not.toBeNull();
+    expect(response?.success).toBe(false);
+    expect(response?.error).toContain('Payment required');
+  });
+
+  // 15. X402Bridge handleResponse for 200 status (null)
+  test('handleResponse returns null for non-402 status', async () => {
+    const response = await bridge.handleResponse({
+      status: 200,
+      headers: {},
+    });
+    expect(response).toBeNull();
+  });
+
+  // Additional: parsePaymentRequired with JSON header
+  test('parsePaymentRequired parses JSON x-payment-required header', async () => {
+    const headers = {
+      'x-payment-required': JSON.stringify({
+        amount: '7.50',
+        currency: 'USDC',
+        address: '0xfeed',
+      }),
+    };
+    const result = await bridge.parsePaymentRequired(headers);
+    expect(result.amount).toBe('7.50');
+    expect(result.address).toBe('0xfeed');
+  });
+
+  // Additional: buildPaymentProof encodes agentId
+  test('buildPaymentProof encodes agentId in proof', async () => {
+    const result = await bridge.buildPaymentProof({
+      amount: '1.00',
+      currency: 'USDC',
+      address: '0xabc',
+      agentId: 'agent-special',
+    });
+    const decoded = JSON.parse(Buffer.from(result.proof, 'base64').toString());
+    expect(decoded.agentId).toBe('agent-special');
+  });
+});

package/src/handler.ts

@@ -0,0 +1,107 @@
+import {
+  AP2PaymentMethod,
+  AP2PaymentRequest,
+  AP2PaymentResponse,
+  IntentMandate,
+  CartMandate,
+  PaymentMandate,
+} from './types';
+import { validateMandate } from './validation';
+
+function generateId(): string {
+  return Math.random().toString(36).substring(2) + Date.now().toString(36);
+}
+
+export class AP2PaymentHandler {
+  private supportedMethods: AP2PaymentMethod[];
+
+  constructor(config: { supportedMethods: AP2PaymentMethod[] }) {
+    this.supportedMethods = config.supportedMethods;
+  }
+
+  getSupportedMethods(): AP2PaymentMethod[] {
+    return [...this.supportedMethods];
+  }
+
+  createIntentMandate(
+    params: Omit<IntentMandate, 'type' | 'isAgentInitiated' | 'isNonCustodial'>
+  ): IntentMandate {
+    return {
+      type: 'intent',
+      isAgentInitiated: true,
+      isNonCustodial: true,
+      ...params,
+    };
+  }
+
+  createCartMandate(params: Omit<CartMandate, 'type'>): CartMandate {
+    return {
+      type: 'cart',
+      ...params,
+    };
+  }
+
+  private selectMethod(preferred: AP2PaymentMethod): AP2PaymentMethod | null {
+    if (this.supportedMethods.includes(preferred)) {
+      return preferred;
+    }
+    // Fallback to first supported method
+    return this.supportedMethods.length > 0 ? this.supportedMethods[0] : null;
+  }
+
+  private getAmount(mandate: IntentMandate | CartMandate): number {
+    if (mandate.type === 'intent') {
+      return mandate.maxAmount;
+    }
+    return mandate.total;
+  }
+
+  async handle(request: AP2PaymentRequest): Promise<AP2PaymentResponse> {
+    try {
+      validateMandate(request.mandate);
+    } catch (err) {
+      return {
+        success: false,
+        error: (err as Error).message,
+      };
+    }
+
+    const method = this.selectMethod(request.preferredMethod);
+    if (!method) {
+      return {
+        success: false,
+        error: 'No supported payment methods available',
+      };
+    }
+
+    const mandateId = generateId();
+    const timestamp = Date.now();
+    const amount = this.getAmount(request.mandate);
+
+    const auditTrail: string[] = [
+      `[${new Date(timestamp).toISOString()}] Mandate received: type=${request.mandate.type}, agentId=${request.mandate.agentId}`,
+      `[${new Date(timestamp).toISOString()}] Payment method selected: ${method}`,
+      `[${new Date(timestamp).toISOString()}] Non-custodial payment initiated: amount=${amount} ${request.mandate.currency}`,
+      `[${new Date(timestamp).toISOString()}] MandateId assigned: ${mandateId}`,
+    ];
+
+    const paymentMandate: PaymentMandate = {
+      type: 'payment',
+      mandateId,
+      method,
+      amount,
+      currency: request.mandate.currency,
+      auditTrail,
+      timestamp,
+      isNonCustodial: true,
+    };
+
+    const transactionId = `tx_${generateId()}`;
+
+    return {
+      success: true,
+      transactionId,
+      paymentMandate,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './handler';
+export * from './x402';
+export * from './validation';

package/src/types.ts

@@ -0,0 +1,53 @@
+export type AP2PaymentMethod = 'usdc_base' | 'x402' | 'usdc_arbitrum' | 'usdc_optimism';
+
+export type MandateType = 'intent' | 'cart' | 'payment';
+
+export interface IntentMandate {
+  type: 'intent';
+  agentId: string;
+  merchantId: string;
+  maxAmount: number;
+  currency: string;
+  ttl: number; // Unix timestamp ms
+  isAgentInitiated: true;
+  isNonCustodial: true;
+  signature?: string;
+}
+
+export interface LineItem {
+  name: string;
+  price: number;
+  qty: number;
+}
+
+export interface CartMandate {
+  type: 'cart';
+  agentId: string;
+  lineItems: LineItem[];
+  total: number;
+  currency: string;
+  signature?: string;
+}
+
+export interface PaymentMandate {
+  type: 'payment';
+  mandateId: string;
+  method: AP2PaymentMethod;
+  amount: number;
+  currency: string;
+  auditTrail: string[];
+  timestamp: number;
+  isNonCustodial: true;
+}
+
+export interface AP2PaymentRequest {
+  mandate: IntentMandate | CartMandate;
+  preferredMethod: AP2PaymentMethod;
+}
+
+export interface AP2PaymentResponse {
+  success: boolean;
+  transactionId?: string;
+  error?: string;
+  paymentMandate?: PaymentMandate;
+}

package/src/validation.ts

@@ -0,0 +1,61 @@
+import { IntentMandate, CartMandate } from './types';
+
+export class AP2ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AP2ValidationError';
+  }
+}
+
+export function validateMandate(mandate: IntentMandate | CartMandate): void {
+  if (!mandate.agentId) {
+    throw new AP2ValidationError('Missing required field: agentId');
+  }
+
+  if (mandate.type === 'intent') {
+    if (!mandate.merchantId) {
+      throw new AP2ValidationError('Missing required field: merchantId');
+    }
+    if (mandate.maxAmount === undefined || mandate.maxAmount === null) {
+      throw new AP2ValidationError('Missing required field: maxAmount');
+    }
+    if (typeof mandate.maxAmount !== 'number' || mandate.maxAmount <= 0) {
+      throw new AP2ValidationError('maxAmount must be a positive number');
+    }
+    if (!mandate.currency) {
+      throw new AP2ValidationError('Missing required field: currency');
+    }
+    if (!mandate.ttl) {
+      throw new AP2ValidationError('Missing required field: ttl');
+    }
+    if (mandate.ttl < Date.now()) {
+      throw new AP2ValidationError('IntentMandate TTL has expired');
+    }
+  } else if (mandate.type === 'cart') {
+    if (!mandate.lineItems || mandate.lineItems.length === 0) {
+      throw new AP2ValidationError('CartMandate must have at least one line item');
+    }
+    if (!mandate.currency) {
+      throw new AP2ValidationError('Missing required field: currency');
+    }
+    if (mandate.total === undefined || mandate.total === null) {
+      throw new AP2ValidationError('Missing required field: total');
+    }
+    if (typeof mandate.total !== 'number' || mandate.total <= 0) {
+      throw new AP2ValidationError('total must be a positive number');
+    }
+
+    const computedTotal = mandate.lineItems.reduce((sum, item) => {
+      return sum + item.price * item.qty;
+    }, 0);
+
+    const diff = Math.abs(computedTotal - mandate.total);
+    if (diff > 0.001) {
+      throw new AP2ValidationError(
+        `CartMandate total mismatch: expected ${computedTotal.toFixed(4)}, got ${mandate.total.toFixed(4)}`
+      );
+    }
+  } else {
+    throw new AP2ValidationError('Unknown mandate type');
+  }
+}