mppx 0.1.0 → 0.2.0

package/src/server/Mppx.test-d.ts

@@ -2,29 +2,32 @@ import { tempo } from 'mppx/server'
 import { createClient, http } from 'viem'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { describe, expectTypeOf, test } from 'vitest'
-import * as Intent from '../Intent.js'
-import * as MethodIntent from '../MethodIntent.js'
+import * as Method from '../Method.js'
 import * as z from '../zod.js'
 import * as Mppx from './Mppx.js'
 
 const account = privateKeyToAccount(generatePrivateKey())
 const getClient = () => createClient({ account, transport: http() })
 
-const fooCharge = MethodIntent.fromIntent(Intent.charge, {
-  method: 'test',
+const fooCharge = Method.from({
+  name: 'test',
+  intent: 'charge',
   schema: {
     credential: {
       payload: z.object({ signature: z.string() }),
     },
-    request: {
-      requires: ['recipient'],
-    },
+    request: z.object({
+      amount: z.string(),
+      currency: z.string(),
+      decimals: z.number(),
+      recipient: z.string(),
+    }),
   },
 })
 
 describe('Mppx', () => {
   test('has methods and realm properties', () => {
-    const method = MethodIntent.toServer(fooCharge, {
+    const method = Method.toServer(fooCharge, {
       async verify() {
         return {
           method: 'test',
@@ -45,8 +48,8 @@ describe('Mppx', () => {
     expectTypeOf(handler.realm).toBeString()
   })
 
-  test('has intent functions matching method intents', () => {
-    const method = MethodIntent.toServer(fooCharge, {
+  test('has method functions matching methods', () => {
+    const method = Method.toServer(fooCharge, {
       async verify() {
         return {
           method: 'test',
@@ -66,8 +69,8 @@ describe('Mppx', () => {
     expectTypeOf(handler.charge).toBeFunction()
   })
 
-  test('intent function options include request', () => {
-    const method = MethodIntent.toServer(fooCharge, {
+  test('method function options include request', () => {
+    const method = Method.toServer(fooCharge, {
       async verify() {
         return {
           method: 'test',
@@ -93,8 +96,8 @@ describe('Mppx', () => {
     })
   })
 
-  test('intent function returns handler that accepts Request', async () => {
-    const method = MethodIntent.toServer(fooCharge, {
+  test('method function returns handler that accepts Request', async () => {
+    const method = Method.toServer(fooCharge, {
       async verify() {
         return {
           method: 'test',
@@ -128,10 +131,14 @@ describe('Mppx', () => {
     }
   })
 
-  test('multiple method intents', () => {
-    const authorize = Intent.from({
-      name: 'authorize',
+  test('multiple methods', () => {
+    const fooAuthorize = Method.from({
+      name: 'test',
+      intent: 'authorize',
       schema: {
+        credential: {
+          payload: z.object({ token: z.string() }),
+        },
         request: z.object({
           scope: z.string(),
           duration: z.number(),
@@ -139,16 +146,7 @@ describe('Mppx', () => {
       },
     })
 
-    const fooAuthorize = MethodIntent.fromIntent(authorize, {
-      method: 'test',
-      schema: {
-        credential: {
-          payload: z.object({ token: z.string() }),
-        },
-      },
-    })
-
-    const chargeMethod = MethodIntent.toServer(fooCharge, {
+    const chargeMethod = Method.toServer(fooCharge, {
       defaults: {
         currency: '0x1234',
         recipient: '0xabc',
@@ -163,7 +161,7 @@ describe('Mppx', () => {
       },
     })
 
-    const authorizeMethod = MethodIntent.toServer(fooAuthorize, {
+    const authorizeMethod = Method.toServer(fooAuthorize, {
       async verify() {
         return {
           method: 'test',
@@ -194,7 +192,7 @@ describe('Mppx', () => {
   })
 
   describe('defaults', () => {
-    test('defaulted fields are optional in intent options', () => {
+    test('defaulted fields are optional in method options', () => {
       const handler = Mppx.create({
         methods: [tempo({ currency: '0x1234', recipient: '0xabc', getClient })],
         realm: 'api.example.com',

package/src/server/Mppx.test.ts

@@ -1,4 +1,4 @@
-import { Challenge, Credential, Intent, MethodIntent, z } from 'mppx'
+import { Challenge, Credential, Method, z } from 'mppx'
 import { Mppx, Transport, tempo } from 'mppx/server'
 import { describe, expect, test } from 'vitest'
 import * as Http from '~test/Http.js'
@@ -56,8 +56,8 @@ describe('request handler', () => {
         "detail": "Payment is required for "api.example.com".",
         "instance": "[instance]",
         "status": 402,
-        "title": "PaymentRequiredError",
-        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-required",
+        "title": "Payment Required",
+        "type": "https://paymentauth.org/problems/payment-required",
       }
     `)
   })
@@ -88,8 +88,8 @@ describe('request handler', () => {
         "detail": "Credential is malformed: Invalid base64url or JSON..",
         "instance": "[instance]",
         "status": 402,
-        "title": "MalformedCredentialError",
-        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/malformed-credential",
+        "title": "Malformed Credential",
+        "type": "https://paymentauth.org/problems/malformed-credential",
       }
     `)
   })
@@ -132,8 +132,8 @@ describe('request handler', () => {
         "detail": "Challenge "wrong-id" is invalid: challenge was not issued by this server.",
         "instance": "[instance]",
         "status": 402,
-        "title": "InvalidChallengeError",
-        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge",
+        "title": "Invalid Challenge",
+        "type": "https://paymentauth.org/problems/invalid-challenge",
       }
     `)
   })
@@ -178,8 +178,8 @@ describe('request handler', () => {
         "detail": "[detail]",
         "instance": "[instance]",
         "status": 402,
-        "title": "InvalidPayloadError",
-        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-payload",
+        "title": "Invalid Payload",
+        "type": "https://paymentauth.org/problems/invalid-payload",
       }
     `)
     expect(body.detail).toContain('Credential payload is invalid')
@@ -218,8 +218,8 @@ describe('request handler (node)', () => {
         "detail": "Payment is required for "api.example.com".",
         "instance": "[instance]",
         "status": 402,
-        "title": "PaymentRequiredError",
-        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-required",
+        "title": "Payment Required",
+        "type": "https://paymentauth.org/problems/payment-required",
       }
     `)
 
@@ -271,8 +271,8 @@ describe('request handler (node)', () => {
         "detail": "[detail]",
         "instance": "[instance]",
         "status": 402,
-        "title": "VerificationFailedError",
-        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/verification-failed",
+        "title": "Verification Failed",
+        "type": "https://paymentauth.org/problems/verification-failed",
       }
     `)
     expect(body.detail).toContain('Payment verification failed')
@@ -283,19 +283,23 @@ describe('request handler (node)', () => {
 
 describe('receipt handling', () => {
   test('returns 200 when verify returns a success receipt', async () => {
-    const mockCharge = MethodIntent.fromIntent(Intent.charge, {
-      method: 'mock',
+    const mockCharge = Method.from({
+      name: 'mock',
+      intent: 'charge',
       schema: {
         credential: {
           payload: z.object({ token: z.string() }),
         },
-        request: {
-          requires: ['recipient'],
-        },
+        request: z.object({
+          amount: z.string(),
+          currency: z.string(),
+          decimals: z.number(),
+          recipient: z.string(),
+        }),
       },
     })
 
-    const mockMethod = MethodIntent.toServer(mockCharge, {
+    const mockMethod = Method.toServer(mockCharge, {
       async verify() {
         return {
           method: 'mock',

package/src/server/Mppx.ts

@@ -2,14 +2,14 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import * as Challenge from '../Challenge.js'
 import type * as Credential from '../Credential.js'
 import * as Errors from '../Errors.js'
-import type * as MethodIntent from '../MethodIntent.js'
+import type * as Method from '../Method.js'
 import type * as Receipt from '../Receipt.js'
 import type * as z from '../zod.js'
 import * as NodeListener from './NodeListener.js'
 import * as Request from './Request.js'
 import * as Transport from './Transport.js'
 
-export type Methods = readonly (MethodIntent.AnyServer | readonly MethodIntent.AnyServer[])[]
+export type Methods = readonly (Method.AnyServer | readonly Method.AnyServer[])[]
 
 /**
  * Payment handler.
@@ -26,14 +26,14 @@ export type Mppx<
   transport: transport
 } & Handlers<FlattenMethods<methods>, transport>
 
-/** Extracts the transport override from a method intent, if any. */
+/** Extracts the transport override from a method, if any. */
 type TransportOverrideOf<mi> = mi extends { transport?: infer transport }
   ? Exclude<transport, undefined> extends Transport.AnyTransport
     ? Exclude<transport, undefined>
     : never
   : never
 
-/** Resolves the effective transport for an intent: override if present, else global default. */
+/** Resolves the effective transport for a method: override if present, else global default. */
 type EffectiveTransportOf<mi, defaultTransport extends Transport.AnyTransport> = [
   TransportOverrideOf<mi>,
 ] extends [never]
@@ -41,18 +41,18 @@ type EffectiveTransportOf<mi, defaultTransport extends Transport.AnyTransport> =
   : TransportOverrideOf<mi>
 
 type Handlers<
-  methods extends readonly MethodIntent.AnyServer[],
+  methods extends readonly Method.AnyServer[],
   transport extends Transport.AnyTransport,
 > = {
-  [intent in methods[number]['name']]: IntentFn<
-    Extract<methods[number], { name: intent }>,
-    EffectiveTransportOf<Extract<methods[number], { name: intent }>, transport>,
-    NonNullable<Extract<methods[number], { name: intent }>['defaults']>
+  [method_name in methods[number]['intent']]: MethodFn<
+    Extract<methods[number], { intent: method_name }>,
+    EffectiveTransportOf<Extract<methods[number], { intent: method_name }>, transport>,
+    NonNullable<Extract<methods[number], { intent: method_name }>['defaults']>
   >
 }
 
 /**
- * Creates a server-side payment handler from method intents.
+ * Creates a server-side payment handler from methods.
  *
  * It is highly recommended to set a `secretKey` to bind challenges to their contents,
  * and allow the server to verify that incoming credentials match challenges it issued.
@@ -82,9 +82,9 @@ export function create<
   const handlers: Record<string, unknown> = {}
 
   for (const mi of methods) {
-    handlers[mi.name] = createIntentFn({
+    handlers[mi.intent] = createMethodFn({
       defaults: mi.defaults,
-      intent: mi,
+      method: mi,
       realm,
       request: mi.request as never,
       respond: mi.respond as never,
@@ -113,25 +113,25 @@ export declare namespace create {
   }
 }
 
-function createIntentFn<
-  intent extends MethodIntent.MethodIntent,
+function createMethodFn<
+  method extends Method.Method,
   transport extends Transport.AnyTransport,
   defaults extends Record<string, unknown>,
 >(
-  parameters: createIntentFn.Parameters<intent, transport, defaults>,
-): createIntentFn.ReturnType<intent, transport, defaults>
+  parameters: createMethodFn.Parameters<method, transport, defaults>,
+): createMethodFn.ReturnType<method, transport, defaults>
 // biome-ignore lint/correctness/noUnusedVariables: _
-function createIntentFn(parameters: createIntentFn.Parameters): createIntentFn.ReturnType {
-  const { defaults, intent, realm, respond, secretKey, transport, verify } = parameters
+function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.ReturnType {
+  const { defaults, method, realm, respond, secretKey, transport, verify } = parameters
 
   return (options) => {
     const meta = {
-      ...intent,
+      ...method,
       ...defaults,
       ...options,
     }
     return Object.assign(
-      async (input: Transport.InputOf): Promise<IntentFn.Response> => {
+      async (input: Transport.InputOf): Promise<MethodFn.Response> => {
         const { description, ...rest } = options
         const expires = 'expires' in options ? (options.expires as string | undefined) : undefined
 
@@ -160,7 +160,7 @@ function createIntentFn(parameters: createIntentFn.Parameters): createIntentFn.R
         // Recompute challenge from options. The HMAC-bound ID means we don't need to
         // store challenges server-side—if the client echoes back a credential with
         // a matching ID, we know it was issued by us with these exact parameters.
-        const challenge = Challenge.fromIntent(intent, {
+        const challenge = Challenge.fromIntent(method, {
           description,
           expires,
           realm,
@@ -202,9 +202,9 @@ function createIntentFn(parameters: createIntentFn.Parameters): createIntentFn.R
           return { challenge: response, status: 402 }
         }
 
-        // Validate payload structure against intent schema
+        // Validate payload structure against method schema
         try {
-          intent.schema.credential.payload.parse(credential.payload)
+          method.schema.credential.payload.parse(credential.payload)
         } catch (e) {
           const response = await transport.respondChallenge({
             challenge,
@@ -265,50 +265,50 @@ function createIntentFn(parameters: createIntentFn.Parameters): createIntentFn.R
   }
 }
 
-declare namespace createIntentFn {
+declare namespace createMethodFn {
   type Parameters<
-    intent extends MethodIntent.MethodIntent = MethodIntent.MethodIntent,
+    method extends Method.Method = Method.Method,
     transport extends Transport.AnyTransport = Transport.Http,
     defaults extends Record<string, unknown> = Record<string, unknown>,
   > = {
     defaults?: defaults
-    intent: intent
+    method: method
     realm: string
-    request?: MethodIntent.RequestFn<intent>
-    respond?: MethodIntent.RespondFn<intent>
+    request?: Method.RequestFn<method>
+    respond?: Method.RespondFn<method>
     secretKey: string
     transport: transport
-    verify: MethodIntent.VerifyFn<intent>
+    verify: Method.VerifyFn<method>
   }
 
   type ReturnType<
-    intent extends MethodIntent.MethodIntent = MethodIntent.MethodIntent,
+    method extends Method.Method = Method.Method,
     transport extends Transport.AnyTransport = Transport.Http,
     defaults extends Record<string, unknown> = Record<string, unknown>,
-  > = IntentFn<intent, transport, defaults>
+  > = MethodFn<method, transport, defaults>
 }
 
-export type IntentFn<
-  intent extends MethodIntent.MethodIntent,
+export type MethodFn<
+  method extends Method.Method,
   transport extends Transport.AnyTransport,
   defaults extends Record<string, unknown>,
 > = (
-  options: IntentFn.Options<intent, defaults>,
-) => (input: Transport.InputOf<transport>) => Promise<IntentFn.Response<transport>>
+  options: MethodFn.Options<method, defaults>,
+) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>
 /** @internal */
-export type AnyIntentFn = (options: any) => (input: any) => Promise<any>
+export type AnyMethodFn = (options: any) => (input: any) => Promise<any>
 
 /** @internal */
-declare namespace IntentFn {
+declare namespace MethodFn {
   export type Options<
-    intent extends MethodIntent.MethodIntent,
+    method extends Method.Method,
     defaults extends Record<string, unknown> = Record<string, unknown>,
   > = {
     /** Optional human-readable description of the payment. */
     description?: string | undefined
     /** Optional challenge expiration timestamp (ISO 8601). */
     expires?: string | undefined
-  } & MethodIntent.WithDefaults<z.input<intent['schema']['request']>, defaults>
+  } & Method.WithDefaults<z.input<method['schema']['request']>, defaults>
 
   export type Response<transport extends Transport.AnyTransport = Transport.Http> =
     | {
@@ -346,8 +346,8 @@ declare namespace IntentFn {
  * ```
  */
 export function toNodeListener(
-  handler: (input: globalThis.Request) => Promise<IntentFn.Response<Transport.Http>>,
-): (req: IncomingMessage, res: ServerResponse) => Promise<IntentFn.Response<Transport.Http>> {
+  handler: (input: globalThis.Request) => Promise<MethodFn.Response<Transport.Http>>,
+): (req: IncomingMessage, res: ServerResponse) => Promise<MethodFn.Response<Transport.Http>> {
   return async (req, res) => {
     const result = await handler(Request.fromNodeListener(req, res))
 
@@ -370,9 +370,9 @@ type FlattenMethods<methods extends Methods> = methods extends readonly [
   infer head,
   ...infer tail extends Methods,
 ]
-  ? head extends readonly MethodIntent.AnyServer[]
+  ? head extends readonly Method.AnyServer[]
     ? readonly [...head, ...FlattenMethods<tail>]
-    : head extends MethodIntent.AnyServer
+    : head extends Method.AnyServer
       ? readonly [head, ...FlattenMethods<tail>]
       : never
   : readonly []

package/src/server/Transport.test.ts

@@ -1,13 +1,13 @@
 import { Challenge, Credential, Mcp, Receipt } from 'mppx'
 import { Transport } from 'mppx/server'
-import { MethodIntents as Intents } from 'mppx/tempo'
+import { Methods } from 'mppx/tempo'
 import { describe, expect, test } from 'vitest'
 import { BadRequestError, ChannelClosedError } from '../Errors.js'
 
 const realm = 'api.example.com'
 const secretKey = 'test-secret-key'
 
-const challenge = Challenge.fromIntent(Intents.charge, {
+const challenge = Challenge.fromIntent(Methods.charge, {
   realm,
   secretKey,
   request: {
@@ -111,7 +111,7 @@ describe('http', () => {
 
       expect(response.status).toBe(400)
       const body = await response.json()
-      expect(body.type).toBe('https://tempoxyz.github.io/payment-auth-spec/problems/bad-request')
+      expect(body.type).toBe('https://paymentauth.org/problems/bad-request')
       expect(body.status).toBe(400)
     })
 

package/src/stripe/Charge.integration.test.ts

@@ -87,7 +87,10 @@ describe.skipIf(!stripeSecretKey)('stripe', () => {
   })
 
   const clientCharge = stripe_client.charge({
-    createSpt: createTestSpt,
+    createToken: async (params) => {
+      if (!params.paymentMethod) throw new Error('paymentMethod is required')
+      return createTestSpt({ ...params, paymentMethod: params.paymentMethod })
+    },
     paymentMethod: 'pm_card_visa',
     externalId: 'client_order_789',
   })

package/src/stripe/{Intents.test.ts → Methods.test.ts}

@@ -1,22 +1,22 @@
-import { MethodIntents } from 'mppx/stripe'
+import { Methods } from 'mppx/stripe'
 import { describe, expect, expectTypeOf, test } from 'vitest'
 
 describe('charge', () => {
-  test('has correct name and method', () => {
-    expect(MethodIntents.charge.name).toBe('charge')
-    expect(MethodIntents.charge.method).toBe('stripe')
+  test('has correct name and intent', () => {
+    expect(Methods.charge.intent).toBe('charge')
+    expect(Methods.charge.name).toBe('stripe')
   })
 
-  test('types: name is literal', () => {
-    expectTypeOf(MethodIntents.charge.name).toEqualTypeOf<'charge'>()
+  test('types: intent is literal', () => {
+    expectTypeOf(Methods.charge.intent).toEqualTypeOf<'charge'>()
   })
 
-  test('types: method is literal', () => {
-    expectTypeOf(MethodIntents.charge.method).toEqualTypeOf<'stripe'>()
+  test('types: name is literal', () => {
+    expectTypeOf(Methods.charge.name).toEqualTypeOf<'stripe'>()
   })
 
   test('schema: validates valid request', () => {
-    const result = MethodIntents.charge.schema.request.safeParse({
+    const result = Methods.charge.schema.request.safeParse({
       amount: '1',
       currency: 'usd',
       decimals: 2,
@@ -29,14 +29,14 @@ describe('charge', () => {
   })
 
   test('schema: rejects invalid request', () => {
-    const result = MethodIntents.charge.schema.request.safeParse({
+    const result = Methods.charge.schema.request.safeParse({
       amount: '1',
     })
     expect(result.success).toBe(false)
   })
 
   test('schema: validates spt payload', () => {
-    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+    const result = Methods.charge.schema.credential.payload.safeParse({
       spt: 'spt_test_123',
       externalId: 'client_order_789',
     })
@@ -44,7 +44,7 @@ describe('charge', () => {
   })
 
   test('schema: rejects invalid payload', () => {
-    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+    const result = Methods.charge.schema.credential.payload.safeParse({
       signature: '0x...',
     })
     expect(result.success).toBe(false)

package/src/stripe/Methods.ts

@@ -0,0 +1,45 @@
+import { parseUnits } from 'viem'
+import * as Expires from '../Expires.js'
+import * as Method from '../Method.js'
+import * as z from '../zod.js'
+
+/**
+ * Stripe charge intent for one-time payments via Shared Payment Tokens (SPTs).
+ *
+ * @see https://github.com/tempoxyz/payment-auth-spec/blob/main/specs/methods/stripe/draft-stripe-charge-00.md
+ */
+export const charge = Method.from({
+  name: 'stripe',
+  intent: 'charge',
+  schema: {
+    credential: {
+      payload: z.object({
+        externalId: z.optional(z.string()),
+        spt: z.string(),
+      }),
+    },
+    request: z.pipe(
+      z.object({
+        amount: z.amount(),
+        currency: z.string(),
+        decimals: z.number(),
+        description: z.optional(z.string()),
+        expires: z._default(z.datetime(), () => Expires.minutes(5)),
+        externalId: z.optional(z.string()),
+        metadata: z.optional(z.record(z.string(), z.string())),
+        networkId: z.string(),
+        paymentMethodTypes: z.array(z.string()).check(z.minLength(1)),
+        recipient: z.optional(z.string()),
+      }),
+      z.transform(({ amount, decimals, metadata, networkId, paymentMethodTypes, ...rest }) => ({
+        ...rest,
+        amount: parseUnits(amount, decimals).toString(),
+        methodDetails: {
+          networkId,
+          paymentMethodTypes,
+          ...(metadata !== undefined && { metadata }),
+        },
+      })),
+    ),
+  },
+})