mppx 0.3.4 → 0.3.6

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/NodeListener.ts

@@ -1,3 +1,9 @@
 import * as FetchServer from '@remix-run/node-fetch-server'
 
+/**
+ * Writes a Fetch API `Response` to a Node.js `ServerResponse`.
+ *
+ * Delegates to `@remix-run/node-fetch-server`. Useful when bridging
+ * Fetch API handlers with Node.js HTTP servers.
+ */
 export const sendResponse = FetchServer.sendResponse

package/src/server/Response.ts

@@ -1,6 +1,23 @@
 import * as Challenge from '../Challenge.js'
 import type * as Errors from '../Errors.js'
 
+/**
+ * Creates a 402 Payment Required response with a `WWW-Authenticate: Payment` header.
+ *
+ * Optionally includes RFC 9457 Problem Details in the response body when an error is provided.
+ *
+ * @param parameters - The challenge and optional error.
+ * @returns A 402 Response suitable for returning from a route handler.
+ *
+ * @example
+ * ```ts
+ * import { Challenge } from 'mppx'
+ * import { Response } from 'mppx/server'
+ *
+ * const challenge = Challenge.from({ id: '...', realm: 'api.example.com', method: 'tempo', intent: 'charge', request: { ... } })
+ * return Response.requirePayment({ challenge })
+ * ```
+ */
 export function requirePayment(parameters: requirePayment.Parameters): Response {
   const { challenge, error } = parameters
 

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/client/ChannelOps.ts

@@ -47,7 +47,7 @@ export function resolveEscrow(
   const escrow =
     challengeEscrow ??
     escrowContractOverride ??
-    ((defaults.escrowContract as Record<number, string>)[chainId] as Address | undefined)
+    defaults.escrowContract[chainId as keyof typeof defaults.escrowContract]
   if (!escrow)
     throw new Error(
       'No `escrowContract` available. Provide it in parameters or ensure the server challenge includes it.',

package/src/tempo/internal/defaults.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'vitest'
+import {
+  chainId,
+  currency,
+  decimals,
+  escrowContract,
+  resolveCurrency,
+  rpcUrl,
+  tokens,
+} from './defaults.js'
+
+describe('chain ID constants', () => {
+  test('mainnet is 4217', () => {
+    expect(chainId.mainnet).toBe(4217)
+  })
+
+  test('testnet is 42431', () => {
+    expect(chainId.testnet).toBe(42431)
+  })
+})
+
+describe('token address constants', () => {
+  test('usdc address', () => {
+    expect(tokens.usdc).toBe('0x20C000000000000000000000b9537d11c60E8b50')
+  })
+
+  test('pathUsd address', () => {
+    expect(tokens.pathUsd).toBe('0x20c0000000000000000000000000000000000000')
+  })
+
+  test('usdc and pathUsd are different addresses', () => {
+    expect(tokens.usdc).not.toBe(tokens.pathUsd)
+  })
+
+  test('decimals is 6', () => {
+    expect(decimals).toBe(6)
+  })
+})
+
+describe('rpcUrl', () => {
+  test('mainnet RPC URL', () => {
+    expect(rpcUrl[chainId.mainnet]).toBe('https://rpc.tempo.xyz')
+  })
+
+  test('testnet RPC URL', () => {
+    expect(rpcUrl[chainId.testnet]).toBe('https://rpc.moderato.tempo.xyz')
+  })
+})
+
+describe('escrowContract', () => {
+  test('mainnet escrow contract', () => {
+    expect(escrowContract[chainId.mainnet]).toBe('0x0901aED692C755b870F9605E56BAA66C35BEfF69')
+  })
+
+  test('testnet escrow contract', () => {
+    expect(escrowContract[chainId.testnet]).toBe('0x542831e3E4Ace07559b7C8787395f4Fb99F70787')
+  })
+})
+
+describe('currency', () => {
+  test('mainnet (4217) returns USDC', () => {
+    expect(currency[chainId.mainnet]).toBe(tokens.usdc)
+  })
+
+  test('testnet (42431) returns pathUSD', () => {
+    expect(currency[chainId.testnet]).toBe(tokens.pathUsd)
+  })
+
+  test('mainnet and testnet return different currencies', () => {
+    expect(currency[chainId.mainnet]).not.toBe(currency[chainId.testnet])
+  })
+})
+
+describe('resolveCurrency', () => {
+  test('defaults to USDC (mainnet)', () => {
+    expect(resolveCurrency({})).toBe(tokens.usdc)
+  })
+
+  test('testnet: true returns pathUSD', () => {
+    expect(resolveCurrency({ testnet: true })).toBe(tokens.pathUsd)
+  })
+
+  test('testnet: false returns USDC', () => {
+    expect(resolveCurrency({ testnet: false })).toBe(tokens.usdc)
+  })
+
+  test('chainId takes precedence over testnet', () => {
+    expect(resolveCurrency({ chainId: chainId.testnet, testnet: false })).toBe(tokens.pathUsd)
+  })
+
+  test('unknown chainId falls back to pathUSD', () => {
+    expect(resolveCurrency({ chainId: 999999 })).toBe(tokens.pathUsd)
+  })
+})

package/src/tempo/internal/defaults.ts

@@ -1,20 +1,53 @@
-export const rpcUrl = {
-  4217: 'https://rpc.tempo.xyz',
-  42431: 'https://rpc.moderato.tempo.xyz',
+import type { ValueOf } from '../../internal/types.js'
+
+export const chainId = {
+  mainnet: 4217,
+  testnet: 42431,
 } as const
+export type ChainId = ValueOf<typeof chainId>
 
-export const escrowContract = {
-  4217: '0x0901aED692C755b870F9605E56BAA66C35BEfF69',
-  42431: '0x542831e3E4Ace07559b7C8787395f4Fb99F70787',
+/** Token addresses. */
+export const tokens = {
+  /** USDC (USDC.e) token address. */
+  usdc: '0x20C000000000000000000000b9537d11c60E8b50',
+  /** pathUSD token address. */
+  pathUsd: '0x20c0000000000000000000000000000000000000',
 } as const
 
-export const testnetChainId = 42431
+/** Chain ID → default currency. */
+export const currency = {
+  [chainId.mainnet]: tokens.usdc,
+  [chainId.testnet]: tokens.pathUsd,
+} as const satisfies Record<ChainId, string>
 
 /**
- * Default token decimals for TIP-20 stablecoins (e.g. pathUSD).
+ * Default token decimals for TIP-20 stablecoins (e.g. pathUSD, USDC).
  *
  * All TIP-20 tokens on Tempo use 6 decimals, so there is no risk of
  * client/server mismatch within the Tempo ecosystem. Other chains and
  * runtimes should set `decimals` explicitly to match their token.
  */
 export const decimals = 6
+
+/** Default payment-channel escrow contract addresses per chain. */
+export const escrowContract = {
+  [chainId.mainnet]: '0x0901aED692C755b870F9605E56BAA66C35BEfF69',
+  [chainId.testnet]: '0x542831e3E4Ace07559b7C8787395f4Fb99F70787',
+} as const satisfies Record<ChainId, string>
+
+/** Default RPC URLs for each Tempo chain. */
+export const rpcUrl = {
+  [chainId.mainnet]: 'https://rpc.tempo.xyz',
+  [chainId.testnet]: 'https://rpc.moderato.tempo.xyz',
+} as const satisfies Record<ChainId, string>
+
+/** Resolves the default currency. */
+export function resolveCurrency(parameters: {
+  /** Chain ID. */
+  chainId?: number | undefined
+  /** Whether in testnet mode. */
+  testnet?: boolean | undefined
+}): string {
+  const id = parameters.chainId ?? (parameters.testnet ? chainId.testnet : chainId.mainnet)
+  return currency[id as keyof typeof currency] ?? tokens.pathUsd
+}

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

@@ -656,6 +656,156 @@ describe('tempo', () => {
     })
   })
 
+  describe('default currency resolution', () => {
+    test('mainnet (default) resolves to USDC', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+      })
+      expect((method.defaults as Record<string, unknown>)?.currency).toBe(
+        '0x20C000000000000000000000b9537d11c60E8b50',
+      )
+    })
+
+    test('testnet: true defaults to pathUSD', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+        testnet: true,
+      })
+      expect((method.defaults as Record<string, unknown>)?.currency).toBe(
+        '0x20c0000000000000000000000000000000000000',
+      )
+    })
+
+    test('unknown chain defaults to pathUSD', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+        chainId: 69420,
+      })
+      expect((method.defaults as Record<string, unknown>)?.currency).toBe(
+        '0x20c0000000000000000000000000000000000000',
+      )
+    })
+
+    test('explicit currency overrides default', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+        testnet: false,
+        currency: '0xcustom',
+      })
+      expect(method.defaults?.currency).toBe('0xcustom')
+    })
+
+    test('decimals defaults to 6', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+      })
+      expect((method.defaults as Record<string, unknown>)?.decimals).toBe(6)
+    })
+
+    test('challenge contains USDC currency (mainnet default)', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await (handler.charge as Function)({ amount: '1' })(
+        new Request('https://example.com'),
+      )
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe('0x20C000000000000000000000b9537d11c60E8b50')
+    })
+
+    test('challenge contains pathUSD currency when testnet: true', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            testnet: true,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await (handler.charge as Function)({ amount: '1', chainId: chain.id })(
+        new Request('https://example.com'),
+      )
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+    })
+
+    test('challenge contains pathUSD currency (unknown chain)', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            chainId: 69420,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await (handler.charge as Function)({ amount: '1' })(
+        new Request('https://example.com'),
+      )
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+    })
+
+    test('explicit currency in challenge overrides testnet default', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            testnet: false,
+            currency: asset,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await handler.charge({ amount: '1' })(new Request('https://example.com'))
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe(asset)
+    })
+  })
+
   describe('attribution memo', () => {
     test('client always generates attribution memo (hash credential)', async () => {
       const httpServer = await Http.createServer(async (req, res) => {

package/src/tempo/server/Charge.ts

@@ -40,7 +40,7 @@ export function charge<const parameters extends charge.Parameters>(
 ) {
   const {
     amount,
-    currency,
+    currency = defaults.resolveCurrency(parameters),
     decimals = defaults.decimals,
     description,
     externalId,
@@ -71,7 +71,7 @@ export function charge<const parameters extends charge.Parameters>(
     async request({ credential, request }) {
       const chainId = await (async () => {
         if (request.chainId) return request.chainId
-        if (parameters.testnet) return defaults.testnetChainId
+        if (parameters.testnet) return defaults.chainId.testnet
         return (await getClient({})).chain?.id
       })()