mppx 0.3.4 → 0.3.5

package/src/server/Mppx.test.ts

@@ -344,3 +344,176 @@ describe('receipt handling', () => {
     expect(result.status).toBe(200)
   })
 })
+
+describe('withReceipt', () => {
+  const mockCharge = Method.from({
+    name: 'mock',
+    intent: 'charge',
+    schema: {
+      credential: {
+        payload: z.object({ token: z.string() }),
+      },
+      request: z.object({
+        amount: z.string(),
+        currency: z.string(),
+        decimals: z.number(),
+        recipient: z.string(),
+      }),
+    },
+  })
+
+  function mockReceipt() {
+    return {
+      method: 'mock',
+      reference: 'tx-ref',
+      status: 'success' as const,
+      timestamp: new Date().toISOString(),
+    }
+  }
+
+  test('attaches Payment-Receipt header to response', async () => {
+    const mockMethod = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethod], realm, secretKey })
+    const handle = handler.charge({
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error()
+
+    const response = result.withReceipt(Response.json({ data: 'ok' }))
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+    const body = await response.json()
+    expect(body).toEqual({ data: 'ok' })
+  })
+
+  test('throws when called without response arg and no management response', async () => {
+    const mockMethod = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethod], realm, secretKey })
+    const handle = handler.charge({
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error()
+
+    expect(() => result.withReceipt()).toThrow('withReceipt() requires a response argument')
+  })
+
+  test('returns management response when respond hook returns Response', async () => {
+    const mockMethodWithRespond = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+      respond() {
+        return new Response(null, { status: 204 })
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethodWithRespond], realm, secretKey })
+    const handle = handler.charge({
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error()
+
+    const response = result.withReceipt()
+    expect(response.status).toBe(204)
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+  })
+
+  test('toNodeListener sets Payment-Receipt header on 200', async () => {
+    const mockMethod = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethod], realm, secretKey })
+
+    const server = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        handler.charge({
+          amount: '1000',
+          currency: '0x0000000000000000000000000000000000000001',
+          decimals: 6,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: '0x0000000000000000000000000000000000000002',
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const firstResponse = await fetch(server.url)
+    expect(firstResponse.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(firstResponse)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const response = await fetch(server.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+
+    server.close()
+  })
+})

package/src/server/Mppx.ts

@@ -126,14 +126,14 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
   const { defaults, method, realm, respond, secretKey, transport, verify } = parameters
 
   return (options) => {
-    const meta = {
+    const methodMeta = {
       ...method,
       ...defaults,
       ...options,
     }
     return Object.assign(
       async (input: Transport.InputOf): Promise<MethodFn.Response> => {
-        const { description, ...rest } = options
+        const { description, meta, ...rest } = options
         const expires = 'expires' in options ? (options.expires as string | undefined) : undefined
 
         // Merge defaults with per-request options
@@ -164,6 +164,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         const challenge = Challenge.fromMethod(method, {
           description,
           expires,
+          meta,
           realm,
           request,
           secretKey,
@@ -261,7 +262,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           },
         }
       },
-      { _internal: meta },
+      { _internal: methodMeta },
     )
   }
 }
@@ -309,6 +310,8 @@ declare namespace MethodFn {
     description?: string | undefined
     /** Optional challenge expiration timestamp (ISO 8601). */
     expires?: string | undefined
+    /** Optional server-defined correlation data (serialized as `opaque` in the request). Flat string-to-string map; clients MUST NOT modify. */
+    meta?: Record<string, string> | undefined
   } & Method.WithDefaults<z.input<method['schema']['request']>, defaults>
 
   export type Response<transport extends Transport.AnyTransport = Transport.Http> =

package/src/server/Transport.test.ts

@@ -43,7 +43,7 @@ describe('http', () => {
         {
           "challenge": {
             "expires": "2025-01-01T00:00:00.000Z",
-            "id": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+            "id": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
             "intent": "charge",
             "method": "tempo",
             "realm": "api.example.com",
@@ -93,7 +93,7 @@ describe('http', () => {
         {
           "headers": {
             "cache-control": "no-store",
-            "www-authenticate": "Payment id="N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAwMDAwIiwiY3VycmVuY3kiOiIweDIwYzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEiLCJleHBpcmVzIjoiMjAyNS0wMS0wMVQwMDowMDowMC4wMDBaIiwicmVjaXBpZW50IjoiMHg3NDJkMzVDYzY2MzRDMDUzMjkyNWEzYjg0NEJjOWU3NTk1ZjhmRTAwIn0", expires="2025-01-01T00:00:00.000Z"",
+            "www-authenticate": "Payment id="4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAwMDAwIiwiY3VycmVuY3kiOiIweDIwYzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEiLCJleHBpcmVzIjoiMjAyNS0wMS0wMVQwMDowMDowMC4wMDBaIiwicmVjaXBpZW50IjoiMHg3NDJkMzVDYzY2MzRDMDUzMjkyNWEzYjg0NEJjOWU3NTk1ZjhmRTAwIn0", expires="2025-01-01T00:00:00.000Z"",
           },
           "status": 402,
         }
@@ -183,7 +183,7 @@ describe('mcp', () => {
         {
           "challenge": {
             "expires": "2025-01-01T00:00:00.000Z",
-            "id": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+            "id": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
             "intent": "charge",
             "method": "tempo",
             "realm": "api.example.com",
@@ -221,7 +221,7 @@ describe('mcp', () => {
               "challenges": [
                 {
                   "expires": "2025-01-01T00:00:00.000Z",
-                  "id": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+                  "id": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
                   "intent": "charge",
                   "method": "tempo",
                   "realm": "api.example.com",
@@ -262,7 +262,7 @@ describe('mcp', () => {
           "result": {
             "_meta": {
               "org.paymentauth/receipt": {
-                "challengeId": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+                "challengeId": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
                 "method": "tempo",
                 "reference": "0xtxhash",
                 "status": "success",

package/src/tempo/server/Session.test.ts

@@ -1099,6 +1099,58 @@ describe('session', () => {
       } as any)
       expect(result).toBeUndefined()
     })
+
+    test('returns undefined for voucher POST with content-length > 0 (content request)', () => {
+      const server = createServer()
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'voucher' },
+        },
+        input: new Request('http://localhost', {
+          method: 'POST',
+          headers: { 'content-length': '42' },
+        }),
+      } as any)
+      expect(result).toBeUndefined()
+    })
+
+    test('returns undefined for voucher POST with transfer-encoding header (content request)', () => {
+      const server = createServer()
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'voucher' },
+        },
+        input: new Request('http://localhost', {
+          method: 'POST',
+          headers: { 'transfer-encoding': 'chunked' },
+        }),
+      } as any)
+      expect(result).toBeUndefined()
+    })
+
+    test('returns 204 for voucher POST with content-length: 0', () => {
+      const server = createServer()
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'voucher' },
+        },
+        input: new Request('http://localhost', {
+          method: 'POST',
+          headers: { 'content-length': '0' },
+        }),
+      } as any)
+      expect(result).toBeInstanceOf(Response)
+      expect((result as Response).status).toBe(204)
+    })
   })
 
   describe('SSE', () => {

package/src/tempo/server/internal/transport.test.ts

@@ -0,0 +1,285 @@
+import { Challenge, Credential } from 'mppx'
+import type { Address, Hex } from 'viem'
+import { describe, expect, test } from 'vitest'
+import * as Store from '../../../Store.js'
+import * as ChannelStore from '../../session/ChannelStore.js'
+import { sse } from './transport.js'
+
+const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+const challengeId = 'challenge-1'
+
+function memoryStore() {
+  return ChannelStore.fromStore(Store.memory())
+}
+
+function seedChannel(
+  storage: ChannelStore.ChannelStore,
+  balance: bigint,
+): Promise<ChannelStore.State | null> {
+  return storage.updateChannel(channelId, () => ({
+    channelId,
+    payer: '0x0000000000000000000000000000000000000001' as Address,
+    payee: '0x0000000000000000000000000000000000000002' as Address,
+    token: '0x0000000000000000000000000000000000000003' as Address,
+    authorizedSigner: '0x0000000000000000000000000000000000000004' as Address,
+    chainId: 42431,
+    escrowContract: '0x542831e3E4Ace07559b7C8787395f4Fb99F70787' as Address,
+    deposit: balance,
+    settledOnChain: 0n,
+    highestVoucherAmount: balance,
+    highestVoucher: null,
+    spent: 0n,
+    units: 0,
+    finalized: false,
+    createdAt: new Date().toISOString(),
+  }))
+}
+
+function makeChallenge() {
+  return Challenge.from({
+    id: challengeId,
+    realm: 'test.example.com',
+    method: 'tempo',
+    intent: 'session',
+    request: {
+      amount: '1000000',
+      currency: '0x20c0000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    },
+  })
+}
+
+function makeCredential() {
+  const challenge = makeChallenge()
+  return Credential.from({
+    challenge,
+    payload: {
+      action: 'voucher',
+      channelId,
+      cumulativeAmount: '1000000',
+      signature: '0xdeadbeef',
+    },
+  })
+}
+
+function makeAuthorizedRequest(): Request {
+  const credential = makeCredential()
+  const header = Credential.serialize(credential)
+  return new Request('https://test.example.com/session', {
+    headers: { Authorization: header },
+  })
+}
+
+function makeReceipt() {
+  return {
+    method: 'tempo',
+    status: 'success' as const,
+    timestamp: new Date().toISOString(),
+    reference: channelId,
+  }
+}
+
+describe('sse transport', () => {
+  test('getCredential returns null when no Authorization header', () => {
+    const store = memoryStore()
+    const transport = sse({ store })
+    const request = new Request('https://test.example.com/session')
+    expect(transport.getCredential(request)).toBeNull()
+  })
+
+  test('getCredential returns credential from Authorization header', () => {
+    const store = memoryStore()
+    const transport = sse({ store })
+    const request = makeAuthorizedRequest()
+    const credential = transport.getCredential(request)
+    expect(credential).not.toBeNull()
+    expect(credential!.challenge.id).toBe(challengeId)
+    expect((credential!.payload as any).channelId).toBe(channelId)
+  })
+
+  test('getCredential captures SSE context in contextMap', async () => {
+    const store = memoryStore()
+    await seedChannel(store, 10000000n)
+    const transport = sse({ store })
+
+    const request = makeAuthorizedRequest()
+    transport.getCredential(request)
+
+    async function* gen() {
+      yield 'test'
+    }
+
+    const response = transport.respondReceipt({
+      receipt: makeReceipt(),
+      response: gen(),
+      challengeId,
+    })
+    expect(response.headers.get('Content-Type')).toContain('text/event-stream')
+  })
+
+  test('respondChallenge delegates to base http transport', async () => {
+    const store = memoryStore()
+    const transport = sse({ store })
+    const challenge = makeChallenge()
+
+    const response = await transport.respondChallenge({
+      challenge,
+      input: new Request('https://test.example.com/session'),
+    })
+    expect(response).toBeInstanceOf(Response)
+    expect(response.status).toBe(402)
+    expect(response.headers.get('WWW-Authenticate')).toContain('Payment')
+  })
+
+  test('respondReceipt with AsyncIterable produces SSE response', async () => {
+    const store = memoryStore()
+    await seedChannel(store, 10000000n)
+    const transport = sse({ store })
+
+    transport.getCredential(makeAuthorizedRequest())
+
+    async function* gen() {
+      yield 'hello'
+      yield 'world'
+    }
+
+    const response = transport.respondReceipt({
+      receipt: makeReceipt(),
+      response: gen(),
+      challengeId,
+    })
+    expect(response.headers.get('Content-Type')).toContain('text/event-stream')
+  })
+
+  test('respondReceipt with AsyncGeneratorFunction passes stream controller', async () => {
+    const store = memoryStore()
+    await seedChannel(store, 10000000n)
+    const transport = sse({ store })
+
+    transport.getCredential(makeAuthorizedRequest())
+
+    const response = transport.respondReceipt({
+      receipt: makeReceipt(),
+      response: async function* (stream) {
+        await stream.charge()
+        yield 'hello'
+      },
+      challengeId,
+    })
+    expect(response.headers.get('Content-Type')).toContain('text/event-stream')
+  })
+
+  test('respondReceipt with upstream SSE Response auto-detects and iterates', async () => {
+    const store = memoryStore()
+    await seedChannel(store, 10000000n)
+    const transport = sse({ store })
+
+    transport.getCredential(makeAuthorizedRequest())
+
+    const encoder = new TextEncoder()
+    const upstream = new Response(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode('event: message\ndata: chunk1\n\n'))
+          controller.enqueue(encoder.encode('event: message\ndata: chunk2\n\n'))
+          controller.close()
+        },
+      }),
+      { headers: { 'Content-Type': 'text/event-stream; charset=utf-8' } },
+    )
+
+    const response = transport.respondReceipt({
+      receipt: makeReceipt(),
+      response: upstream,
+      challengeId,
+    })
+    expect(response.headers.get('Content-Type')).toContain('text/event-stream')
+  })
+
+  test('respondReceipt with plain Response delegates to base http transport', () => {
+    const store = memoryStore()
+    const transport = sse({ store })
+    const receipt = makeReceipt()
+
+    const plainResponse = new Response('ok', {
+      headers: { 'Content-Type': 'application/json' },
+    })
+
+    const response = transport.respondReceipt({
+      receipt,
+      response: plainResponse,
+      challengeId,
+    })
+    expect(response).toBeInstanceOf(Response)
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+  })
+
+  test('respondReceipt cleans up contextMap after use', async () => {
+    const store = memoryStore()
+    await seedChannel(store, 10000000n)
+    const transport = sse({ store })
+
+    transport.getCredential(makeAuthorizedRequest())
+
+    async function* gen() {
+      yield 'first'
+    }
+
+    transport.respondReceipt({
+      receipt: makeReceipt(),
+      response: gen(),
+      challengeId,
+    })
+
+    async function* gen2() {
+      yield 'second'
+    }
+
+    expect(() =>
+      transport.respondReceipt({
+        receipt: makeReceipt(),
+        response: gen2(),
+        challengeId,
+      }),
+    ).toThrow('No SSE context available')
+  })
+
+  test('respondReceipt throws when no SSE context available', () => {
+    const store = memoryStore()
+    const transport = sse({ store })
+
+    async function* gen() {
+      yield 'hello'
+    }
+
+    expect(() =>
+      transport.respondReceipt({
+        receipt: makeReceipt(),
+        response: gen(),
+        challengeId,
+      }),
+    ).toThrow('No SSE context available')
+  })
+
+  test('poll: true strips waitForUpdate from store', async () => {
+    const store = memoryStore()
+    ;(store as any).waitForUpdate = async () => {}
+    await seedChannel(store, 10000000n)
+
+    const transport = sse({ store, poll: true })
+
+    transport.getCredential(makeAuthorizedRequest())
+
+    async function* gen() {
+      yield 'test'
+    }
+
+    const response = transport.respondReceipt({
+      receipt: makeReceipt(),
+      response: gen(),
+      challengeId,
+    })
+    expect(response.headers.get('Content-Type')).toContain('text/event-stream')
+    expect(transport.name).toBe('sse')
+  })
+})