mppx 0.1.1 → 0.2.1

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

package/src/stripe/server/Charge.ts

@@ -1,22 +1,37 @@
+import type * as Credential from '../../Credential.js'
 import {
   PaymentActionRequiredError,
   PaymentExpiredError,
   VerificationFailedError,
 } from '../../Errors.js'
-import type { LooseOmit } from '../../internal/types.js'
-import * as MethodIntent from '../../MethodIntent.js'
-import * as Intents from '../Intents.js'
+import type { LooseOmit, OneOf } from '../../internal/types.js'
+import * as Method from '../../Method.js'
+import type { StripeClient } from '../internal/types.js'
+import * as Methods from '../Methods.js'
 
 /**
  * Creates a Stripe charge method intent for usage on the server.
  *
  * Verifies payment by creating a Stripe PaymentIntent with the provided SPT.
  *
+ * Accepts either a `client` (a pre-configured Stripe SDK instance) or a raw
+ * `secretKey`. Using `client` is recommended—it lets you configure retries,
+ * API version, and other options on the Stripe instance you control.
+ *
+ * @example
+ * ```ts
+ * import Stripe from 'stripe'
+ * import { stripe } from 'mppx/server'
+ *
+ * const stripeClient = new Stripe(process.env.STRIPE_SECRET_KEY!)
+ * const charge = stripe.charge({ client: stripeClient, networkId: 'internal', paymentMethodTypes: ['card'] })
+ * ```
+ *
  * @example
  * ```ts
  * import { stripe } from 'mppx/server'
  *
- * const charge = stripe.charge({ secretKey: 'sk_...' })
+ * const charge = stripe.charge({ secretKey: 'sk_...', networkId: 'internal', paymentMethodTypes: ['card'] })
  * ```
  */
 export function charge<const parameters extends charge.Parameters>(parameters: parameters) {
@@ -29,11 +44,13 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
     metadata,
     networkId,
     paymentMethodTypes,
-    secretKey,
   } = parameters
 
+  const client = 'client' in parameters ? parameters.client : undefined
+  const secretKey = 'secretKey' in parameters ? parameters.secretKey : undefined
+
   type Defaults = charge.DeriveDefaults<parameters>
-  return MethodIntent.toServer<typeof Intents.charge, Defaults>(Intents.charge, {
+  return Method.toServer<typeof Methods.charge, Defaults>(Methods.charge, {
     defaults: {
       amount,
       currency,
@@ -52,41 +69,25 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
       if (request.expires && new Date(request.expires) < new Date())
         throw new PaymentExpiredError({ expires: request.expires })
 
-      const parsed = Intents.charge.schema.credential.payload.safeParse(credential.payload)
+      const parsed = Methods.charge.schema.credential.payload.safeParse(credential.payload)
       if (!parsed.success) throw new Error('Invalid credential payload: missing or malformed spt')
       const { spt, externalId: credentialExternalId } = parsed.data as {
         spt: string
         externalId?: string
       }
 
-      const body = new URLSearchParams({
-        amount: request.amount as string,
-        currency: request.currency as string,
-        shared_payment_granted_token: spt,
-        confirm: 'true',
-        'automatic_payment_methods[enabled]': 'true',
-        'automatic_payment_methods[allow_redirects]': 'never',
-      })
-      const resolvedMetadata = request.methodDetails?.metadata as Record<string, string> | undefined
-      if (resolvedMetadata) {
-        for (const [key, value] of Object.entries(resolvedMetadata)) {
-          body.set(`metadata[${key}]`, value)
-        }
-      }
+      const userMetadata = request.methodDetails?.metadata as Record<string, string> | undefined
+      const resolvedMetadata = { ...buildAnalytics({ credential }), ...userMetadata }
 
-      const response = await fetch('https://api.stripe.com/v1/payment_intents', {
-        method: 'POST',
-        headers: {
-          Authorization: `Basic ${btoa(`${secretKey}:`)}`,
-          'Content-Type': 'application/x-www-form-urlencoded',
-          'Idempotency-Key': `mppx_${challenge.id}_${spt}`,
-        },
-        body,
-      })
-
-      if (!response.ok) throw new VerificationFailedError({ reason: 'Stripe PaymentIntent failed' })
-
-      const pi = (await response.json()) as { id: string; status: string }
+      const pi = client
+        ? await createWithClient({ client, challenge, request, spt, metadata: resolvedMetadata })
+        : await createWithSecretKey({
+            secretKey: secretKey!,
+            challenge,
+            request,
+            spt,
+            metadata: resolvedMetadata,
+          })
 
       if (pi.status === 'requires_action') {
         throw new PaymentActionRequiredError({ reason: 'Stripe PaymentIntent requires action' })
@@ -105,17 +106,102 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
 }
 
 export declare namespace charge {
-  type Defaults = LooseOmit<MethodIntent.RequestDefaults<typeof Intents.charge>, 'recipient'>
+  type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.charge>, 'recipient'>
 
   type Parameters = {
-    /** Stripe secret API key. */
-    secretKey: string
     /** Optional metadata to include in SPT creation requests. */
     metadata?: Record<string, string> | undefined
-  } & Defaults
+  } & Defaults &
+    OneOf<
+      | {
+          /** Pre-configured Stripe SDK instance. Any object matching the duck-typed `StripeClient` shape works. */
+          client: StripeClient
+        }
+      | {
+          /** Stripe secret API key. */
+          secretKey: string
+        }
+    >
 
   type DeriveDefaults<parameters extends Parameters> = Pick<
     parameters,
     Extract<keyof parameters, keyof Defaults>
   > & { decimals: number }
 }
+
+/** Creates a PaymentIntent using the Stripe SDK client. */
+async function createWithClient(parameters: {
+  client: StripeClient
+  challenge: { id: string }
+  metadata: Record<string, string>
+  request: { amount: unknown; currency: unknown }
+  spt: string
+}): Promise<{ id: string; status: string }> {
+  const { client, challenge, metadata, request, spt } = parameters
+  try {
+    const result = await client.paymentIntents.create(
+      {
+        amount: Number(request.amount),
+        automatic_payment_methods: { allow_redirects: 'never', enabled: true },
+        confirm: true,
+        currency: request.currency as string,
+        metadata,
+        payment_method: spt,
+      },
+      { idempotencyKey: `mppx_${challenge.id}_${spt}` },
+    )
+    return { id: result.id, status: result.status }
+  } catch {
+    throw new VerificationFailedError({ reason: 'Stripe PaymentIntent failed' })
+  }
+}
+
+/** Creates a PaymentIntent using a raw secret key and fetch. */
+async function createWithSecretKey(parameters: {
+  secretKey: string
+  challenge: { id: string }
+  metadata: Record<string, string>
+  request: { amount: unknown; currency: unknown }
+  spt: string
+}): Promise<{ id: string; status: string }> {
+  const { secretKey, challenge, metadata, request, spt } = parameters
+
+  const body = new URLSearchParams({
+    amount: request.amount as string,
+    'automatic_payment_methods[allow_redirects]': 'never',
+    'automatic_payment_methods[enabled]': 'true',
+    confirm: 'true',
+    currency: request.currency as string,
+    shared_payment_granted_token: spt,
+  })
+  for (const [key, value] of Object.entries(metadata)) {
+    body.set(`metadata[${key}]`, value)
+  }
+
+  const response = await fetch('https://api.stripe.com/v1/payment_intents', {
+    method: 'POST',
+    headers: {
+      Authorization: `Basic ${btoa(`${secretKey}:`)}`,
+      'Content-Type': 'application/x-www-form-urlencoded',
+      'Idempotency-Key': `mppx_${challenge.id}_${spt}`,
+    },
+    body,
+  })
+
+  if (!response.ok) throw new VerificationFailedError({ reason: 'Stripe PaymentIntent failed' })
+  return (await response.json()) as { id: string; status: string }
+}
+
+/** @internal */
+function buildAnalytics(parameters: { credential: Credential.Credential }): Record<string, string> {
+  const { credential } = parameters
+  const { challenge } = credential
+  return {
+    mpp_version: '1',
+    mpp_is_mpp: 'true',
+    mpp_intent: challenge.intent,
+    mpp_challenge_id: challenge.id,
+    mpp_server_id: challenge.realm,
+    ...(credential.source ? { mpp_client_id: credential.source } : {}),
+  }
+}

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

@@ -1,7 +1,7 @@
 import { charge as charge_ } from './Charge.js'
 
 /**
- * Creates a Stripe `charge` method intent for usage on the server.
+ * Creates a Stripe `charge` method for usage on the server.
  *
  * @example
  * ```ts
@@ -19,6 +19,6 @@ export function stripe<const parameters extends stripe.Parameters>(parameters: p
 export namespace stripe {
   export type Parameters = charge_.Parameters
 
-  /** Creates a Stripe `charge` method intent for SPT-based payments. */
+  /** Creates a Stripe `charge` method for SPT-based payments. */
   export const charge = charge_
 }

package/src/stripe/server/index.ts

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

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

@@ -1,22 +1,22 @@
-import { MethodIntents } from 'mppx/tempo'
+import { Methods } from 'mppx/tempo'
 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('tempo')
+  test('has correct name and intent', () => {
+    expect(Methods.charge.intent).toBe('charge')
+    expect(Methods.charge.name).toBe('tempo')
   })
 
-  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<'tempo'>()
+  test('types: name is literal', () => {
+    expectTypeOf(Methods.charge.name).toEqualTypeOf<'tempo'>()
   })
 
   test('schema: validates valid request', () => {
-    const result = MethodIntents.charge.schema.request.safeParse({
+    const result = Methods.charge.schema.request.safeParse({
       amount: '1',
       currency: '0x20c0000000000000000000000000000000000001',
       decimals: 6,
@@ -27,7 +27,7 @@ describe('charge', () => {
   })
 
   test('schema: validates request with methodDetails', () => {
-    const result = MethodIntents.charge.schema.request.safeParse({
+    const result = Methods.charge.schema.request.safeParse({
       amount: '1',
       currency: '0x20c0000000000000000000000000000000000001',
       decimals: 6,
@@ -40,7 +40,7 @@ describe('charge', () => {
   })
 
   test('schema: validates request with memo', () => {
-    const result = MethodIntents.charge.schema.request.safeParse({
+    const result = Methods.charge.schema.request.safeParse({
       amount: '1',
       currency: '0x20c0000000000000000000000000000000000001',
       decimals: 6,
@@ -52,14 +52,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 transaction payload', () => {
-    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+    const result = Methods.charge.schema.credential.payload.safeParse({
       signature: '0x76f90100000000000000000000000000000000000000000000000000000000000000000000',
       type: 'transaction',
     })
@@ -67,7 +67,7 @@ describe('charge', () => {
   })
 
   test('schema: validates hash payload', () => {
-    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+    const result = Methods.charge.schema.credential.payload.safeParse({
       hash: '0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890',
       type: 'hash',
     })
@@ -75,7 +75,7 @@ describe('charge', () => {
   })
 
   test('schema: rejects invalid payload type', () => {
-    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+    const result = Methods.charge.schema.credential.payload.safeParse({
       signature: '0x...',
       type: 'keyAuthorization',
     })