feat: migrate discovery payment info to offers (#384)

* feat: migrate discovery payment info to offers

* fix: pin uuid to address audit failure

* fix: correct changeset frontmatter

Author: brendanjryan

.changeset/tiny-dingos-type.md

@@ -0,0 +1,5 @@
+---
+'mppx': patch
+---
+
+Added canonical discovery output using `x-payment-info.offers[]` while continuing to accept the legacy flat shorthand during validation and parsing.

pnpm-lock.yaml

@@ -44,5 +44,6 @@ overrides:
   brace-expansion@<5.0.5: '>=5.0.5'
   lodash@<=4.17.23: '>=4.18.0'
   protobufjs@<7.5.5: '7.5.5'
+  uuid@<14.0.0: '14.0.0'
 
 nodeOptions: '--disable-warning=ExperimentalWarning --disable-warning=DeprecationWarning'

pnpm-workspace.yaml

@@ -1,14 +1,26 @@
 import { DiscoveryDocument, PaymentInfo, ServiceInfo } from './Discovery.js'
 
 describe('PaymentInfo', () => {
-  test('parses a valid charge payment info', () => {
+  test('normalizes legacy shorthand to offers', () => {
     const result = PaymentInfo.safeParse({
       amount: '1000',
       intent: 'charge',
       method: 'tempo',
     })
     expect(result.success).toBe(true)
-    expect(result.data).toEqual({ amount: '1000', intent: 'charge', method: 'tempo' })
+    expect(result.data).toEqual({
+      offers: [{ amount: '1000', intent: 'charge', method: 'tempo' }],
+    })
+  })
+
+  test('parses offers format without modification', () => {
+    const result = PaymentInfo.safeParse({
+      offers: [{ amount: '1000', intent: 'charge', method: 'tempo' }],
+    })
+    expect(result.success).toBe(true)
+    expect(result.data).toEqual({
+      offers: [{ amount: '1000', intent: 'charge', method: 'tempo' }],
+    })
   })
 
   test('parses a session with null amount', () => {
@@ -18,7 +30,7 @@ describe('PaymentInfo', () => {
       method: 'tempo',
     })
     expect(result.success).toBe(true)
-    expect(result.data?.amount).toBeNull()
+    expect(result.data?.offers[0]?.amount).toBeNull()
   })
 
   test('accepts custom intents', () => {
@@ -28,7 +40,7 @@ describe('PaymentInfo', () => {
       method: 'tempo',
     })
     expect(result.success).toBe(true)
-    expect(result.data?.intent).toBe('subscribe')
+    expect(result.data?.offers[0]?.intent).toBe('subscribe')
   })
 
   test('rejects invalid amount pattern', () => {
@@ -40,13 +52,36 @@ describe('PaymentInfo', () => {
     expect(result.success).toBe(false)
   })
 
+  test('rejects mixed shorthand and offers shapes', () => {
+    const result = PaymentInfo.safeParse({
+      amount: '100',
+      offers: [{ amount: '100', intent: 'charge', method: 'tempo' }],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('rejects empty offers arrays', () => {
+    const result = PaymentInfo.safeParse({ offers: [] })
+    expect(result.success).toBe(false)
+  })
+
+  test('rejects malformed offers', () => {
+    const result = PaymentInfo.safeParse({
+      offers: [{ amount: '01', intent: 'charge', method: 'tempo' }],
+    })
+    expect(result.success).toBe(false)
+  })
+
   test('accepts x402 format with unknown fields', () => {
     const result = PaymentInfo.safeParse({
       price: '0.54',
       pricingMode: 'fixed',
       protocols: ['x402', 'mpp'],
     })
     expect(result.success).toBe(true)
+    expect(result.data).toEqual({
+      offers: [{ price: '0.54', pricingMode: 'fixed', protocols: ['x402', 'mpp'] }],
+    })
   })
 })
 
@@ -118,6 +153,33 @@ describe('DiscoveryDocument', () => {
       },
     })
     expect(result.success).toBe(true)
+    expect(result.data?.paths?.['/search']?.post?.['x-payment-info']).toEqual({
+      offers: [{ amount: '100', intent: 'charge', method: 'tempo' }],
+    })
+  })
+
+  test('normalizes offers-based discovery documents', () => {
+    const result = DiscoveryDocument.safeParse({
+      info: { title: 'Test', version: '1.0.0' },
+      openapi: '3.1.0',
+      paths: {
+        '/search': {
+          post: {
+            'x-payment-info': {
+              offers: [{ amount: '100', intent: 'charge', method: 'tempo' }],
+            },
+            responses: {
+              '200': { description: 'OK' },
+              '402': { description: 'Payment Required' },
+            },
+          },
+        },
+      },
+    })
+    expect(result.success).toBe(true)
+    expect(result.data?.paths?.['/search']?.post?.['x-payment-info']).toEqual({
+      offers: [{ amount: '100', intent: 'charge', method: 'tempo' }],
+    })
   })
 
   test('accepts path items with summary, parameters, and extensions', () => {

src/discovery/Discovery.test.ts

@@ -1,18 +1,13 @@
 import * as z from '../zod.js'
 
 const uriOrPathPattern = /^([a-zA-Z][a-zA-Z\d+.-]*:\/\/\S+|\/\S*)$/
+const paymentInfoFieldNames = new Set(['amount', 'currency', 'description', 'intent', 'method'])
 
 function uriOrPath() {
   return z.string().check(z.regex(uriOrPathPattern, 'Invalid URI or path'))
 }
 
-/**
- * Schema for the `x-payment-info` OpenAPI extension on an operation.
- *
- * Only validates spec-defined fields when present; unknown fields are ignored.
- * Discovery is advisory only. Runtime 402 challenges remain authoritative.
- */
-export const PaymentInfo = z.looseObject({
+const PaymentOffer = z.looseObject({
   amount: z.optional(
     z.union([z.null(), z.string().check(z.regex(/^(0|[1-9][0-9]*)$/, 'Invalid amount'))]),
   ),
@@ -21,6 +16,44 @@ export const PaymentInfo = z.looseObject({
   intent: z.optional(z.string()),
   method: z.optional(z.string()),
 })
+
+/**
+ * Schema for the `x-payment-info` OpenAPI extension on an operation.
+ *
+ * Only validates spec-defined fields when present; unknown fields are ignored.
+ * Discovery is advisory only. Runtime 402 challenges remain authoritative.
+ */
+export const PaymentInfo = z.pipe(
+  z
+    .looseObject({
+      amount: z.optional(
+        z.union([z.null(), z.string().check(z.regex(/^(0|[1-9][0-9]*)$/, 'Invalid amount'))]),
+      ),
+      currency: z.optional(z.string()),
+      description: z.optional(z.string()),
+      intent: z.optional(z.string()),
+      method: z.optional(z.string()),
+      offers: z.optional(z.array(PaymentOffer).check(z.minLength(1))),
+    })
+    .check(
+      z.refine(
+        (value) =>
+          value.offers === undefined || Object.keys(value).every((key) => key === 'offers'),
+        'Cannot mix offers with flat payment info fields',
+      ),
+    ),
+  z.transform((value) => {
+    if (value.offers) return { offers: value.offers }
+
+    const offer: Record<string, unknown> = {}
+    for (const [key, field] of Object.entries(value)) {
+      if (key === 'offers') continue
+      if (paymentInfoFieldNames.has(key) || field !== undefined) offer[key] = field
+    }
+
+    return { offers: [offer] }
+  }),
+)
 export type PaymentInfo = z.infer<typeof PaymentInfo>
 
 const ServiceDocs = z.looseObject({