mppx 0.1.1 → 0.2.0

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 }),
+        },
+      })),
+    ),
+  },
+})

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

@@ -0,0 +1,189 @@
+import { Challenge, Credential } from 'mppx'
+import { Mppx, stripe } from 'mppx/client'
+import { Mppx as Mppx_server, stripe as stripe_server } from 'mppx/server'
+import { describe, expect, test, vi } from 'vitest'
+import type { StripeJs } from '../internal/types.js'
+import { charge as clientCharge_ } from './Charge.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-hmac-key'
+
+const dummyClientCharge = clientCharge_({
+  createToken: async () => 'spt_test',
+  paymentMethod: 'pm_test',
+})
+
+async function createChallenge() {
+  const server = Mppx_server.create({
+    methods: [
+      stripe_server.charge({
+        networkId: 'internal',
+        paymentMethodTypes: ['card'],
+        secretKey: 'sk_test',
+      }),
+    ],
+    realm,
+    secretKey,
+  })
+
+  const handle = server.charge({ amount: '100', currency: 'usd', decimals: 2 })
+  const result = await handle(new Request('https://example.com'))
+  if (result.status !== 402) throw new Error('Expected 402')
+  return Challenge.fromResponse(result.challenge, { methods: [dummyClientCharge] })
+}
+
+function createMockStripeJs(): StripeJs {
+  return {
+    createPaymentMethod: vi.fn(async () => ({
+      error: null,
+      paymentMethod: { id: 'pm_mock_123' },
+    })),
+    elements: vi.fn(() => ({})),
+  }
+}
+
+describe('stripe.charge client param', () => {
+  test('default: forwards client to createToken callback', async () => {
+    const mockClient = createMockStripeJs()
+    let receivedClient: StripeJs | undefined
+
+    const charge = stripe.charge({
+      client: mockClient,
+      createToken: async (params) => {
+        receivedClient = params.client
+        return 'spt_test_123'
+      },
+      paymentMethod: 'pm_card_visa',
+    })
+
+    const challenge = await createChallenge()
+    await charge.createCredential({ challenge, context: {} })
+
+    expect(receivedClient).toBe(mockClient)
+  })
+
+  test('behavior: client is undefined when not provided', async () => {
+    let receivedClient: StripeJs | undefined = createMockStripeJs()
+
+    const charge = stripe.charge({
+      createToken: async (params) => {
+        receivedClient = params.client
+        return 'spt_test_123'
+      },
+      paymentMethod: 'pm_card_visa',
+    })
+
+    const challenge = await createChallenge()
+    await charge.createCredential({ challenge, context: {} })
+
+    expect(receivedClient).toBeUndefined()
+  })
+
+  test('behavior: createToken receives all expected params', async () => {
+    const mockClient = createMockStripeJs()
+    let receivedParams: Record<string, unknown> | undefined
+
+    const charge = stripe.charge({
+      client: mockClient,
+      createToken: async (params) => {
+        receivedParams = params as unknown as Record<string, unknown>
+        return 'spt_test_123'
+      },
+      paymentMethod: 'pm_card_visa',
+    })
+
+    const challenge = await createChallenge()
+    await charge.createCredential({ challenge, context: {} })
+
+    expect(receivedParams).toBeDefined()
+    expect(receivedParams!.amount).toBe('10000')
+    expect(receivedParams!.currency).toBe('usd')
+    expect(receivedParams!.networkId).toBe('internal')
+    expect(receivedParams!.paymentMethod).toBe('pm_card_visa')
+    expect(receivedParams!.client).toBe(mockClient)
+    expect(receivedParams!.challenge).toBeDefined()
+    expect(typeof receivedParams!.expiresAt).toBe('number')
+  })
+
+  test('behavior: produces valid credential string', async () => {
+    const charge = stripe.charge({
+      createToken: async () => 'spt_test_123',
+      paymentMethod: 'pm_card_visa',
+    })
+
+    const challenge = await createChallenge()
+    const credential = await charge.createCredential({ challenge, context: {} })
+
+    expect(credential).toMatch(/^Payment /)
+
+    const parsed = Credential.deserialize(credential)
+    expect(parsed.payload).toMatchObject({ spt: 'spt_test_123' })
+  })
+
+  test('behavior: includes externalId in credential payload', async () => {
+    const charge = stripe.charge({
+      createToken: async () => 'spt_test_123',
+      externalId: 'order_456',
+      paymentMethod: 'pm_card_visa',
+    })
+
+    const challenge = await createChallenge()
+    const credential = await charge.createCredential({ challenge, context: {} })
+    const parsed = Credential.deserialize(credential)
+    expect(parsed.payload).toMatchObject({
+      externalId: 'order_456',
+      spt: 'spt_test_123',
+    })
+  })
+
+  test('behavior: context paymentMethod overrides default', async () => {
+    let receivedPaymentMethod: string | undefined
+
+    const charge = stripe.charge({
+      createToken: async (params) => {
+        receivedPaymentMethod = params.paymentMethod
+        return 'spt_test_123'
+      },
+      paymentMethod: 'pm_default',
+    })
+
+    const challenge = await createChallenge()
+    await charge.createCredential({
+      challenge,
+      context: { paymentMethod: 'pm_override' },
+    })
+
+    expect(receivedPaymentMethod).toBe('pm_override')
+  })
+
+  test('behavior: Mppx.create with client forwards through createCredential', async () => {
+    const mockClient = createMockStripeJs()
+    let receivedClient: StripeJs | undefined
+
+    const mppx = Mppx.create({
+      methods: [
+        stripe.charge({
+          client: mockClient,
+          createToken: async (params) => {
+            receivedClient = params.client
+            return 'spt_test_123'
+          },
+          paymentMethod: 'pm_card_visa',
+        }),
+      ],
+      polyfill: false,
+    })
+
+    const challenge = await createChallenge()
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    await mppx.createCredential(response)
+
+    expect(receivedClient).toBe(mockClient)
+  })
+})

package/src/stripe/client/Charge.ts

@@ -1,8 +1,9 @@
 import type * as Challenge from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
-import * as MethodIntent from '../../MethodIntent.js'
+import * as Method from '../../Method.js'
 import * as z from '../../zod.js'
-import * as Intents from '../Intents.js'
+import type { StripeJs } from '../internal/types.js'
+import * as Methods from '../Methods.js'
 
 /**
  * Creates a Stripe charge method intent for usage on the client.
@@ -14,11 +15,18 @@ import * as Intents from '../Intents.js'
  * The `paymentMethod` (e.g. from Stripe Elements) can be provided at
  * initialization or at credential-creation time via `context`.
  *
+ * Optionally accepts a `client` (a Stripe.js instance from `@stripe/stripe-js`)
+ * which is forwarded to the `createToken` callback for use with Elements.
+ *
  * @example
  * ```ts
+ * import { loadStripe } from '@stripe/stripe-js'
  * import { stripe } from 'mppx/client'
  *
+ * const stripeJs = await loadStripe('pk_...')
+ *
  * const charge = stripe.charge({
+ *   client: stripeJs,
  *   createToken: async ({ amount, currency, expiresAt, metadata, networkId, paymentMethod }) => {
  *     const res = await fetch('/api/create-spt', {
  *       method: 'POST',
@@ -32,9 +40,9 @@ import * as Intents from '../Intents.js'
  * ```
  */
 export function charge(parameters: charge.Parameters) {
-  const { createToken, externalId, paymentMethod: defaultPaymentMethod } = parameters
+  const { client, createToken, externalId, paymentMethod: defaultPaymentMethod } = parameters
 
-  return MethodIntent.toClient(Intents.charge, {
+  return Method.toClient(Methods.charge, {
     context: z.object({
       paymentMethod: z.optional(z.string()),
     }),
@@ -63,13 +71,14 @@ export function charge(parameters: charge.Parameters) {
         : Math.floor(Date.now() / 1000) + 3600
 
       const spt = await createToken({
-        challenge,
-        paymentMethod,
         amount,
+        challenge,
+        client,
         currency,
-        networkId,
         expiresAt,
         metadata,
+        networkId,
+        paymentMethod,
       })
 
       return Credential.serialize({
@@ -85,6 +94,8 @@ export function charge(parameters: charge.Parameters) {
 
 export declare namespace charge {
   type Parameters = {
+    /** Stripe.js instance from `@stripe/stripe-js`. Forwarded to `createToken` for use with Elements. */
+    client?: StripeJs | undefined
     /** Called when a Stripe challenge is received. Create an SPT to retry. */
     createToken: (parameters: OnChallengeParameters) => Promise<string>
     /** Optional client-side external reference ID for the credential payload. */
@@ -94,22 +105,24 @@ export declare namespace charge {
   }
 
   type OnChallengeParameters = {
-    challenge: Challenge.Challenge<
-      z.output<typeof Intents.charge.schema.request>,
-      typeof Intents.charge.name,
-      typeof Intents.charge.method
-    >
-    /** Stripe payment method ID (e.g. from Stripe Elements). */
-    paymentMethod?: string | undefined
     /** Payment amount (in smallest currency unit). */
     amount: string
+    challenge: Challenge.Challenge<
+      z.output<typeof Methods.charge.schema.request>,
+      typeof Methods.charge.intent,
+      typeof Methods.charge.name
+    >
+    /** Stripe.js instance, if provided to `stripe.charge()`. */
+    client?: StripeJs | undefined
     /** Three-letter ISO currency code. */
     currency: string
-    /** Stripe Business Network profile ID. */
-    networkId: string | undefined
     /** SPT expiration as a Unix timestamp (seconds). */
     expiresAt: number
     /** Optional metadata to associate with the SPT. */
     metadata?: Record<string, string> | undefined
+    /** Stripe Business Network profile ID. */
+    networkId: string | undefined
+    /** Stripe payment method ID (e.g. from Stripe Elements). */
+    paymentMethod?: string | undefined
   }
 }

package/src/stripe/client/{MethodIntents.ts → Methods.ts}

@@ -1,7 +1,7 @@
 import { charge as charge_ } from './Charge.js'
 
 /**
- * Creates a Stripe `charge` client method intent.
+ * Creates a Stripe `charge` client method.
  *
  * @example
  * ```ts
@@ -32,6 +32,6 @@ export function stripe(parameters: stripe.Parameters) {
 export namespace stripe {
   export type Parameters = charge_.Parameters
 
-  /** Creates a Stripe `charge` client method intent for SPT-based payments. */
+  /** Creates a Stripe `charge` client method for SPT-based payments. */
   export const charge = charge_
 }

package/src/stripe/client/index.ts

@@ -1,2 +1,2 @@
 export { charge } from './Charge.js'
-export { stripe } from './MethodIntents.js'
+export { stripe } from './Methods.js'

package/src/stripe/index.ts

@@ -1 +1 @@
-export * as MethodIntents from './Intents.js'
+export * as Methods from './Methods.js'

package/src/stripe/internal/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Duck-typed interface for the Stripe Node SDK (`stripe` npm package).
+ * Matches the subset of the API used by mppx for server-side payment verification.
+ *
+ * Uses loose signatures so any Stripe SDK version is assignable.
+ */
+export type StripeClient = {
+  paymentIntents: {
+    create(...args: any[]): Promise<{ id: string; status: string }>
+  }
+}
+
+/**
+ * Duck-typed interface for Stripe.js (`@stripe/stripe-js`).
+ * Matches the subset of the API used by mppx for client-side payment method creation.
+ *
+ * Uses loose signatures so any Stripe.js version is assignable.
+ */
+export type StripeJs = {
+  createPaymentMethod(...args: any[]): Promise<Record<string, unknown>>
+  elements(...args: any[]): unknown
+}

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

@@ -0,0 +1,241 @@
+import { Challenge, Credential } from 'mppx'
+import { Mppx, stripe } from 'mppx/server'
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import * as Http from '~test/Http.js'
+import type { StripeClient } from '../internal/types.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+let httpServer: Awaited<ReturnType<typeof Http.createServer>> | undefined
+
+afterEach(() => httpServer?.close())
+
+function createMockStripeClient(
+  overrides?: Partial<{ status: string; id: string; throws: boolean }>,
+): { client: StripeClient; create: ReturnType<typeof vi.fn> } {
+  const { status = 'succeeded', id = 'pi_mock_123', throws = false } = overrides ?? {}
+  const create = vi.fn(async () => {
+    if (throws) throw new Error('Stripe API error')
+    return { id, status }
+  })
+  return {
+    client: { paymentIntents: { create } },
+    create,
+  }
+}
+
+describe('stripe.charge with client', () => {
+  test('default: verifies payment via client.paymentIntents.create', async () => {
+    const { client, create } = createMockStripeClient()
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    expect(response.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(response)
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    const paidResponse = await fetch(httpServer.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+    expect(paidResponse.status).toBe(200)
+    expect(create).toHaveBeenCalledOnce()
+
+    const [params, options] = create.mock.calls[0]!
+    expect(params).toMatchObject({
+      amount: 100,
+      confirm: true,
+      currency: 'usd',
+      payment_method: 'spt_test_token',
+    })
+    expect(params.automatic_payment_methods).toMatchObject({
+      allow_redirects: 'never',
+      enabled: true,
+    })
+    expect(options.idempotencyKey).toMatch(/^mppx_/)
+  })
+
+  test('behavior: includes metadata in client call', async () => {
+    const { client, create } = createMockStripeClient()
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          metadata: { plan: 'pro' },
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    const challenge = Challenge.fromResponse(response)
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    await fetch(httpServer.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+
+    const [params] = create.mock.calls[0]!
+    expect(params.metadata).toMatchObject({ plan: 'pro' })
+    expect(params.metadata.mpp_is_mpp).toBe('true')
+  })
+
+  test('behavior: rejects when client throws', async () => {
+    const { client } = createMockStripeClient({ throws: true })
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    const challenge = Challenge.fromResponse(response)
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    const paidResponse = await fetch(httpServer.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+    expect(paidResponse.status).toBe(402)
+    const body = (await paidResponse.json()) as { detail: string }
+    expect(body.detail).toContain('Stripe PaymentIntent failed')
+  })
+
+  test('behavior: rejects requires_action status', async () => {
+    const { client } = createMockStripeClient({ status: 'requires_action' })
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    const challenge = Challenge.fromResponse(response)
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    const paidResponse = await fetch(httpServer.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+    expect(paidResponse.status).toBe(402)
+    const body = (await paidResponse.json()) as { detail: string }
+    expect(body.detail).toContain('requires action')
+  })
+
+  test('behavior: receipt contains mock reference', async () => {
+    const { client } = createMockStripeClient({ id: 'pi_custom_ref' })
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    const handle = server.charge({ amount: '1', currency: 'usd', decimals: 2 })
+
+    const firstResult = await handle(new Request('https://example.com'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    const result = await handle(
+      new Request('https://example.com', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error()
+
+    const wrapped = result.withReceipt(Response.json({ ok: true }))
+    const receiptHeader = wrapped.headers.get('Payment-Receipt')
+    expect(receiptHeader).toBeTruthy()
+
+    const decoded = JSON.parse(
+      Buffer.from(receiptHeader!.replace('Payment ', ''), 'base64url').toString(),
+    ) as { reference: string }
+    expect(decoded.reference).toBe('pi_custom_ref')
+  })
+})