mppx 0.0.1 → 0.1.0

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

@@ -0,0 +1,326 @@
+import { Challenge, Credential, Receipt } from 'mppx'
+import { Mppx as Mppx_client, stripe as stripe_client } from 'mppx/client'
+import { Mppx as Mppx_server, stripe as stripe_server } from 'mppx/server'
+import { afterEach, describe, expect, test } from 'vitest'
+import * as Http from '~test/Http.js'
+
+const stripeSecretKey = process.env.VITE_STRIPE_SECRET_KEY
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+let httpServer: Awaited<ReturnType<typeof Http.createServer>> | undefined
+
+afterEach(() => httpServer?.close())
+
+async function createTestSpt(parameters: {
+  paymentMethod: string
+  amount: string
+  currency: string
+  networkId: string | undefined
+  expiresAt: number
+  metadata?: Record<string, string> | undefined
+}) {
+  const body = new URLSearchParams({
+    payment_method: parameters.paymentMethod,
+    'usage_limits[currency]': parameters.currency,
+    'usage_limits[max_amount]': parameters.amount,
+    'usage_limits[expires_at]': parameters.expiresAt.toString(),
+  })
+  if (parameters.networkId) body.set('seller_details[network_id]', parameters.networkId)
+  if (parameters.metadata) {
+    for (const [key, value] of Object.entries(parameters.metadata)) {
+      body.set(`metadata[${key}]`, value)
+    }
+  }
+  // Test-only endpoint; production SPT flow uses the agent-side issued_tokens API.
+  const createSpt = async (bodyParams: URLSearchParams) =>
+    fetch('https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens', {
+      method: 'POST',
+      headers: {
+        Authorization: `Basic ${btoa(`${stripeSecretKey!}:`)}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: bodyParams,
+    })
+
+  let response = await createSpt(body)
+  if (!response.ok) {
+    const error = (await response.json()) as { error: { message: string } }
+    if (
+      (parameters.metadata || parameters.networkId) &&
+      error.error.message.includes('Received unknown parameter')
+    ) {
+      const fallbackBody = new URLSearchParams({
+        payment_method: parameters.paymentMethod,
+        'usage_limits[currency]': parameters.currency,
+        'usage_limits[max_amount]': parameters.amount,
+        'usage_limits[expires_at]': parameters.expiresAt.toString(),
+      })
+      response = await createSpt(fallbackBody)
+    } else {
+      throw new Error(`Failed to create SPT: ${error.error.message}`)
+    }
+  }
+
+  if (!response.ok) {
+    const error = (await response.json()) as { error: { message: string } }
+    throw new Error(`Failed to create SPT: ${error.error.message}`)
+  }
+
+  const { id } = (await response.json()) as { id: string }
+  return id
+}
+
+describe.skipIf(!stripeSecretKey)('stripe', () => {
+  const server = Mppx_server.create({
+    methods: [
+      stripe_server.charge({
+        secretKey: stripeSecretKey!,
+        networkId: 'internal',
+        paymentMethodTypes: ['card'],
+        metadata: { example: 'metadata' },
+      }),
+    ],
+    realm,
+    secretKey,
+  })
+
+  const clientCharge = stripe_client.charge({
+    createSpt: createTestSpt,
+    paymentMethod: 'pm_card_visa',
+    externalId: 'client_order_789',
+  })
+
+  describe('intent: charge; type: spt', () => {
+    test('default', async () => {
+      httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.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, {
+        methods: [clientCharge],
+      })
+      expect(challenge.method).toBe('stripe')
+      expect(challenge.intent).toBe('charge')
+      expect(challenge.request.amount).toBe('100')
+      expect(challenge.realm).toBe(realm)
+
+      const credential = await clientCharge.createCredential({ challenge, context: {} })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: credential },
+        })
+        expect(response.status).toBe(200)
+
+        const receipt = Receipt.fromResponse(response)
+        expect({
+          ...receipt,
+          reference: '[reference]',
+          timestamp: '[timestamp]',
+          externalId: '[externalId]',
+        }).toMatchInlineSnapshot(`
+          {
+            "externalId": "[externalId]",
+            "method": "stripe",
+            "reference": "[reference]",
+            "status": "success",
+            "timestamp": "[timestamp]",
+          }
+        `)
+      }
+    })
+
+    test('behavior: rejects invalid SPT', async () => {
+      httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.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_invalid_token' },
+      })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: Credential.serialize(credential) },
+        })
+        expect(response.status).toBe(402)
+        const body = (await response.json()) as { detail: string }
+        expect(body.detail).toContain('Stripe PaymentIntent failed')
+      }
+    })
+
+    test('behavior: rejects expired challenge', async () => {
+      httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          server.charge({
+            amount: '1',
+            currency: 'usd',
+            decimals: 2,
+            expires: new Date(Date.now() - 1000).toISOString(),
+          }),
+        )(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_does_not_matter' },
+      })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: Credential.serialize(credential) },
+        })
+        expect(response.status).toBe(402)
+        const body = (await response.json()) as { detail: string }
+        expect(body.detail).toMatch(/^Payment expired at /)
+      }
+    })
+
+    test('behavior: rejects malformed credential payload (missing spt)', async () => {
+      httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.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: {},
+      })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: Credential.serialize(credential) },
+        })
+        expect(response.status).toBe(402)
+      }
+    })
+
+    test('behavior: receipt format stability', async () => {
+      httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.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, {
+        methods: [clientCharge],
+      })
+
+      const credential = await clientCharge.createCredential({ challenge, context: {} })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: credential },
+        })
+        expect(response.status).toBe(200)
+
+        const receipt = Receipt.fromResponse(response)
+        expect(receipt.status).toBe('success')
+        expect(receipt.method).toBe('stripe')
+        expect(receipt.reference).toMatch(/^pi_/)
+        expect(receipt.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)
+      }
+    })
+  })
+
+  describe('intent: charge; type: spt; via Mppx', () => {
+    test('default', async () => {
+      const mppx = Mppx_client.create({
+        polyfill: false,
+        methods: [clientCharge],
+      })
+
+      httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.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 credential = await mppx.createCredential(response)
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: credential },
+        })
+        expect(response.status).toBe(200)
+
+        const receipt = Receipt.fromResponse(response)
+        expect({
+          ...receipt,
+          reference: '[reference]',
+          timestamp: '[timestamp]',
+          externalId: '[externalId]',
+        }).toMatchInlineSnapshot(`
+          {
+            "externalId": "[externalId]",
+            "method": "stripe",
+            "reference": "[reference]",
+            "status": "success",
+            "timestamp": "[timestamp]",
+          }
+        `)
+      }
+    })
+
+    test('behavior: full mppx.fetch() auto flow', async () => {
+      const mppx = Mppx_client.create({
+        polyfill: false,
+        methods: [clientCharge],
+      })
+
+      httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await mppx.fetch(httpServer.url)
+      expect(response.status).toBe(200)
+
+      const receipt = Receipt.fromResponse(response)
+      expect(receipt.status).toBe('success')
+      expect(receipt.method).toBe('stripe')
+      expect(receipt.reference).toMatch(/^pi_/)
+    })
+  })
+})

package/src/stripe/Intents.test.ts

@@ -0,0 +1,52 @@
+import { MethodIntents } 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('types: name is literal', () => {
+    expectTypeOf(MethodIntents.charge.name).toEqualTypeOf<'charge'>()
+  })
+
+  test('types: method is literal', () => {
+    expectTypeOf(MethodIntents.charge.method).toEqualTypeOf<'stripe'>()
+  })
+
+  test('schema: validates valid request', () => {
+    const result = MethodIntents.charge.schema.request.safeParse({
+      amount: '1',
+      currency: 'usd',
+      decimals: 2,
+      expires: '2025-02-05T12:05:00Z',
+      networkId: 'profile_123',
+      paymentMethodTypes: ['card'],
+      metadata: { example: 'metadata' },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('schema: rejects invalid request', () => {
+    const result = MethodIntents.charge.schema.request.safeParse({
+      amount: '1',
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('schema: validates spt payload', () => {
+    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+      spt: 'spt_test_123',
+      externalId: 'client_order_789',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('schema: rejects invalid payload', () => {
+    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+      signature: '0x...',
+    })
+    expect(result.success).toBe(false)
+  })
+})

package/src/stripe/Intents.ts

@@ -0,0 +1,27 @@
+import * as Intent from '../Intent.js'
+import * as MethodIntent from '../MethodIntent.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 = MethodIntent.fromIntent(Intent.charge, {
+  method: 'stripe',
+  schema: {
+    credential: {
+      payload: z.object({
+        spt: z.string(),
+        externalId: z.optional(z.string()),
+      }),
+    },
+    request: {
+      methodDetails: z.object({
+        networkId: z.string(),
+        paymentMethodTypes: z.array(z.string()).check(z.minLength(1)),
+        metadata: z.optional(z.record(z.string(), z.string())),
+      }),
+    },
+  },
+})

package/src/stripe/client/Charge.ts

@@ -0,0 +1,119 @@
+import * as Credential from '../../Credential.js'
+import * as MethodIntent from '../../MethodIntent.js'
+import * as z from '../../zod.js'
+import * as Intents from '../Intents.js'
+
+/**
+ * Creates a Stripe charge method intent for usage on the client.
+ *
+ * Accepts a `createSpt` callback that handles SPT creation (requires
+ * a secret key, so typically proxied through a server endpoint).
+ *
+ * The `paymentMethod` (e.g. from Stripe Elements) can be provided at
+ * initialization or at credential-creation time via `context`.
+ *
+ * @example
+ * ```ts
+ * import { stripe } from 'mppx/client'
+ *
+ * const charge = stripe.charge({
+ *   createSpt: async ({ paymentMethod, amount, currency, networkId, expiresAt, metadata }) => {
+ *     const res = await fetch('/api/create-spt', {
+ *       method: 'POST',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       body: JSON.stringify({ paymentMethod, amount, currency, networkId, expiresAt, metadata }),
+ *     })
+ *     const { spt } = await res.json()
+ *     return spt
+ *   },
+ * })
+ *
+ * // paymentMethod comes from Stripe Elements at credential-creation time
+ * const credential = await charge.createCredential({
+ *   challenge,
+ *   context: { paymentMethod: 'pm_xxx' },
+ * })
+ * ```
+ */
+export function charge(parameters: charge.Parameters) {
+  const { createSpt, externalId, paymentMethod: defaultPaymentMethod } = parameters
+
+  return MethodIntent.toClient(Intents.charge, {
+    context: z.object({
+      paymentMethod: z.optional(z.string()),
+    }),
+
+    async createCredential({ challenge, context }) {
+      const paymentMethod = context?.paymentMethod ?? defaultPaymentMethod
+      if (!paymentMethod)
+        throw new Error('paymentMethod is required (pass via context or parameters)')
+
+      const amount = challenge.request.amount as string
+      const currency = challenge.request.currency as string
+      const networkId = challenge.request.methodDetails?.networkId as string | undefined
+      if (!networkId) throw new Error('networkId is required in challenge.methodDetails')
+      const metadata = challenge.request.methodDetails?.metadata as
+        | Record<string, string>
+        | undefined
+      if (metadata?.externalId) {
+        throw new Error(
+          'methodDetails.metadata.externalId is reserved; use credential externalId instead',
+        )
+      }
+
+      const expiresAt = challenge.request.expires
+        ? Math.floor(new Date(challenge.request.expires as string).getTime() / 1000)
+        : Math.floor(Date.now() / 1000) + 3600
+
+      const spt = await createSpt({
+        paymentMethod,
+        amount,
+        currency,
+        networkId,
+        expiresAt,
+        metadata,
+      })
+
+      return Credential.serialize({
+        challenge,
+        payload: {
+          spt,
+          ...(externalId ? { externalId } : {}),
+        },
+      })
+    },
+  })
+}
+
+export declare namespace charge {
+  type Parameters = {
+    /**
+     * Creates a Shared Payment Token (SPT) for the given parameters.
+     *
+     * SPT creation requires a Stripe secret key, so this typically
+     * proxies through a server endpoint (e.g. `POST /api/create-spt`).
+     * If you are running a client in an enviroment with a secret key, you can just create the
+     * SPT directly in this callback.
+     */
+    createSpt: (parameters: CreateSptParameters) => Promise<string>
+    /** Optional client-side external reference ID for the credential payload. */
+    externalId?: string | undefined
+    /** Default payment method ID. Overridden by `context.paymentMethod`. */
+    paymentMethod?: string | undefined
+  }
+
+  type CreateSptParameters = {
+    /** Stripe payment method ID (e.g. from Stripe Elements). */
+    paymentMethod: string
+    /** Payment amount (in smallest currency unit). */
+    amount: string
+    /** 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
+  }
+}

package/src/stripe/client/MethodIntents.ts

@@ -0,0 +1,37 @@
+import { charge as charge_ } from './Charge.js'
+
+/**
+ * Creates a Stripe `charge` client method intent.
+ *
+ * @example
+ * ```ts
+ * import { Mppx, stripe } from 'mppx/client'
+ *
+ * const mppx = Mppx.create({
+ *   methods: [
+ *     stripe({
+ *       createSpt: async (params) => {
+ *         const res = await fetch('/api/create-spt', {
+ *           method: 'POST',
+ *           headers: { 'Content-Type': 'application/json' },
+ *           body: JSON.stringify(params),
+ *         })
+ *         const { spt } = await res.json()
+ *         return spt
+ *       },
+ *       paymentMethod: 'pm_card_visa',
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function stripe(parameters: stripe.Parameters) {
+  return [charge_(parameters)] as const
+}
+
+export namespace stripe {
+  export type Parameters = charge_.Parameters
+
+  /** Creates a Stripe `charge` client method intent for SPT-based payments. */
+  export const charge = charge_
+}

package/src/stripe/client/index.ts

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

package/src/stripe/index.ts

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

package/src/stripe/server/Charge.ts

@@ -0,0 +1,121 @@
+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'
+
+/**
+ * Creates a Stripe charge method intent for usage on the server.
+ *
+ * Verifies payment by creating a Stripe PaymentIntent with the provided SPT.
+ *
+ * @example
+ * ```ts
+ * import { stripe } from 'mppx/server'
+ *
+ * const charge = stripe.charge({ secretKey: 'sk_...' })
+ * ```
+ */
+export function charge<const parameters extends charge.Parameters>(parameters: parameters) {
+  const {
+    amount,
+    currency,
+    decimals,
+    description,
+    externalId,
+    metadata,
+    networkId,
+    paymentMethodTypes,
+    secretKey,
+  } = parameters
+
+  type Defaults = charge.DeriveDefaults<parameters>
+  return MethodIntent.toServer<typeof Intents.charge, Defaults>(Intents.charge, {
+    defaults: {
+      amount,
+      currency,
+      decimals,
+      description,
+      externalId,
+      metadata,
+      networkId,
+      paymentMethodTypes,
+    } as unknown as Defaults,
+
+    async verify({ credential }) {
+      const { challenge } = credential
+      const { request } = challenge
+
+      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)
+      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 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 }
+
+      if (pi.status === 'requires_action') {
+        throw new PaymentActionRequiredError({ reason: 'Stripe PaymentIntent requires action' })
+      }
+      if (pi.status !== 'succeeded') throw new Error(`Stripe PaymentIntent status: ${pi.status}`)
+
+      return {
+        method: 'stripe',
+        status: 'success',
+        timestamp: new Date().toISOString(),
+        reference: pi.id,
+        ...(credentialExternalId ? { externalId: credentialExternalId } : {}),
+      } as const
+    },
+  })
+}
+
+export declare namespace charge {
+  type Defaults = LooseOmit<MethodIntent.RequestDefaults<typeof Intents.charge>, 'recipient'>
+
+  type Parameters = {
+    /** Stripe secret API key. */
+    secretKey: string
+    /** Optional metadata to include in SPT creation requests. */
+    metadata?: Record<string, string> | undefined
+  } & Defaults
+
+  type DeriveDefaults<parameters extends Parameters> = Pick<
+    parameters,
+    Extract<keyof parameters, keyof Defaults>
+  > & { decimals: number }
+}