mppx 0.0.1 → 0.1.0

package/src/client/Methods.ts

@@ -0,0 +1,3 @@
+export { stripe } from '../stripe/client/MethodIntents.js'
+export { tempo } from '../tempo/client/MethodIntents.js'
+export { session } from '../tempo/client/Session.js'

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

@@ -0,0 +1,90 @@
+import type { Account } from 'viem'
+import { describe, expectTypeOf, test } from 'vitest'
+import * as MethodIntent from '../MethodIntent.js'
+import { charge } from '../tempo/client/Charge.js'
+import * as Intents from '../tempo/Intents.js'
+import * as z from '../zod.js'
+import * as Mppx from './Mppx.js'
+
+describe('Mppx', () => {
+  test('has methods array', () => {
+    const method = charge({
+      account: {} as Account,
+    })
+    const mppx = Mppx.create({ methods: [method] })
+
+    expectTypeOf(mppx.methods).toMatchTypeOf<readonly MethodIntent.AnyClient[]>()
+    expectTypeOf(mppx.methods[0]?.name).toEqualTypeOf<'charge'>()
+  })
+
+  test('has createCredential function', () => {
+    const method = charge({
+      account: {} as Account,
+    })
+    const mppx = Mppx.create({ methods: [method] })
+
+    expectTypeOf(mppx.createCredential).toBeFunction()
+    expectTypeOf(mppx.createCredential).returns.toMatchTypeOf<Promise<string>>()
+  })
+})
+
+describe('create.Config', () => {
+  test('requires methods array', () => {
+    type Config = Mppx.create.Config
+
+    expectTypeOf<Config>().toHaveProperty('methods')
+  })
+})
+
+describe('Method.toClient', () => {
+  test('createCredential receives typed challenge', () => {
+    MethodIntent.toClient(Intents.charge, {
+      async createCredential({ challenge }) {
+        expectTypeOf(challenge.method).toBeString()
+        expectTypeOf(challenge.intent).toBeString()
+        expectTypeOf(challenge.request).toHaveProperty('amount')
+        expectTypeOf(challenge.request).toHaveProperty('currency')
+        expectTypeOf(challenge.request).toHaveProperty('recipient')
+
+        return 'Payment ...'
+      },
+    })
+  })
+
+  test('createCredential receives typed context when provided', () => {
+    MethodIntent.toClient(Intents.charge, {
+      context: z.object({
+        account: z.custom<Account>(),
+        extra: z.optional(z.string()),
+      }),
+      async createCredential({ context }) {
+        expectTypeOf(context.account).toEqualTypeOf<Account>()
+        expectTypeOf(context.extra).toEqualTypeOf<string | undefined>()
+
+        return 'Payment ...'
+      },
+    })
+  })
+})
+
+describe('Mppx with context', () => {
+  test('createCredential accepts context matching method schema', () => {
+    const method = charge()
+
+    const mppx = Mppx.create({ methods: [method] })
+
+    expectTypeOf(mppx.createCredential).toBeFunction()
+    expectTypeOf(mppx.createCredential).returns.toMatchTypeOf<Promise<string>>()
+  })
+
+  test('createCredential context is optional when account provided at creation', () => {
+    const method = charge({
+      account: {} as Account,
+    })
+
+    const mppx = Mppx.create({ methods: [method] })
+
+    expectTypeOf(mppx.createCredential).toBeFunction()
+    expectTypeOf(mppx.createCredential).returns.toMatchTypeOf<Promise<string>>()
+  })
+})

package/src/client/Mppx.test.ts

@@ -0,0 +1,468 @@
+import { Challenge, Credential, Intent, Mcp, MethodIntent, Receipt } from 'mppx'
+import { Mppx, Transport, tempo } from 'mppx/client'
+import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
+import { MethodIntents } from 'mppx/tempo'
+import { afterEach, describe, expect, test } from 'vitest'
+import * as Http from '~test/Http.js'
+import { accounts, asset, client } from '~test/tempo/viem.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+afterEach(() => {
+  Mppx.restore()
+})
+
+describe('Mppx.create', () => {
+  test('default', () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client })],
+    })
+
+    expect(mppx.methods).toHaveLength(2)
+    expect(mppx.methods[0]?.method).toBe('tempo')
+    expect(mppx.methods[0]?.name).toBe('charge')
+    expect(mppx.methods[1]?.method).toBe('tempo')
+    expect(mppx.methods[1]?.name).toBe('session')
+    expect(mppx.transport.name).toBe('http')
+    expect(typeof mppx.createCredential).toBe('function')
+    expect(typeof mppx.fetch).toBe('function')
+  })
+
+  test('behavior: with mcp transport', () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client })],
+      transport: Transport.mcp(),
+    })
+
+    expect(mppx.transport.name).toBe('mcp')
+  })
+
+  test('behavior: with multiple methods', () => {
+    const stripeCharge = MethodIntent.fromIntent(Intent.charge, {
+      method: 'stripe',
+      schema: {
+        credential: {
+          payload: MethodIntents.charge.schema.credential.payload,
+        },
+      },
+    })
+    const stripeMethod = MethodIntent.toClient(stripeCharge, {
+      async createCredential({ challenge }) {
+        return Credential.serialize({
+          challenge,
+          payload: { signature: '0xstripe', type: 'transaction' },
+        })
+      },
+    })
+
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client }), stripeMethod],
+    })
+
+    expect(mppx.methods).toHaveLength(3)
+    expect(mppx.methods[0]?.method).toBe('tempo')
+    expect(mppx.methods[1]?.method).toBe('tempo')
+    expect(mppx.methods[2]?.method).toBe('stripe')
+  })
+})
+
+describe('createCredential', () => {
+  test('behavior: routes to correct method based on challenge', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client })],
+    })
+
+    const challenge = Challenge.fromIntent(MethodIntents.charge, {
+      realm,
+      secretKey,
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+        expires: new Date(Date.now() + 60_000).toISOString(),
+      },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    const credential = await mppx.createCredential(response)
+
+    expect(credential).toMatch(/^Payment /)
+
+    const parsed = Credential.deserialize(credential)
+    expect((parsed.payload as { type: string }).type).toBe('transaction')
+    expect(parsed.challenge.method).toBe('tempo')
+  })
+
+  test('behavior: throws when method not found', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client })],
+    })
+
+    const challenge = Challenge.from({
+      id: 'test-id',
+      realm,
+      method: 'unknown',
+      intent: 'charge',
+      request: { amount: '1000', currency: '0x1234' },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    await expect(mppx.createCredential(response)).rejects.toThrow(
+      'No method intent found for "unknown.charge". Available: tempo.charge, tempo.session',
+    )
+  })
+
+  test('behavior: routes to correct method with multiple methods', async () => {
+    const stripeCharge = MethodIntent.fromIntent(Intent.charge, {
+      method: 'stripe',
+      schema: {
+        credential: {
+          payload: MethodIntents.charge.schema.credential.payload,
+        },
+      },
+    })
+
+    const stripe = MethodIntent.toClient(stripeCharge, {
+      async createCredential({ challenge }) {
+        return Credential.serialize({
+          challenge,
+          payload: { signature: '0xstripe', type: 'transaction' },
+        })
+      },
+    })
+
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client }), stripe],
+    })
+
+    const stripeChallenge = Challenge.from({
+      id: 'stripe-challenge-id',
+      realm,
+      method: 'stripe',
+      intent: 'charge',
+      request: {
+        amount: '2000',
+        currency: '0xabcd',
+        recipient: '0xefgh',
+        expires: new Date(Date.now() + 60_000).toISOString(),
+      },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(stripeChallenge),
+      },
+    })
+
+    const credential = await mppx.createCredential(response)
+    const parsed = Credential.deserialize(credential)
+
+    expect(parsed.payload).toEqual({ signature: '0xstripe', type: 'transaction' })
+    expect(parsed.challenge.method).toBe('stripe')
+  })
+
+  test('behavior: passes context to createCredential', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ getClient: () => client })],
+    })
+
+    const challenge = Challenge.fromIntent(MethodIntents.charge, {
+      realm,
+      secretKey,
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+        expires: new Date(Date.now() + 60_000).toISOString(),
+      },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    const credential = await mppx.createCredential(response, { account: accounts[1] })
+
+    const parsed = Credential.deserialize(credential)
+    expect((parsed.payload as { type: string }).type).toBe('transaction')
+    expect(parsed.source).toContain(accounts[1].address)
+  })
+
+  test('behavior: works without context when account provided at creation', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client })],
+    })
+
+    const challenge = Challenge.fromIntent(MethodIntents.charge, {
+      realm,
+      secretKey,
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+        expires: new Date(Date.now() + 60_000).toISOString(),
+      },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    const credential = await mppx.createCredential(response)
+    const parsed = Credential.deserialize(credential)
+    expect((parsed.payload as { type: string }).type).toBe('transaction')
+  })
+
+  test('behavior: with mcp transport', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client })],
+      transport: Transport.mcp(),
+    })
+
+    const challenge = Challenge.fromIntent(MethodIntents.charge, {
+      realm,
+      secretKey,
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+        expires: new Date(Date.now() + 60_000).toISOString(),
+      },
+    })
+
+    const mcpResponse: Mcp.Response = {
+      jsonrpc: '2.0',
+      id: 1,
+      error: {
+        code: Mcp.paymentRequiredCode,
+        message: 'Payment Required',
+        data: {
+          httpStatus: 402,
+          challenges: [challenge],
+        },
+      },
+    }
+
+    const credential = await mppx.createCredential(mcpResponse)
+    const parsed = Credential.deserialize(credential)
+    expect((parsed.payload as { type: string }).type).toBe('transaction')
+    expect(parsed.challenge.method).toBe('tempo')
+  })
+})
+
+const server = Mppx_server.create({
+  methods: [
+    tempo_server.charge({
+      currency: asset,
+      getClient: () => client,
+      recipient: accounts[0].address,
+    }),
+  ],
+})
+
+describe('fetch', () => {
+  test('default: handles 402 automatically', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [
+        tempo({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+        }),
+      )(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('tempo')
+
+    httpServer.close()
+  })
+
+  test('behavior: passes through non-402 responses', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [
+        tempo({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (_req, res) => {
+      res.writeHead(200)
+      res.end('OK')
+    })
+
+    const response = await mppx.fetch(httpServer.url)
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('OK')
+
+    httpServer.close()
+  })
+
+  test('behavior: supports context', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [
+        tempo({
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await mppx.fetch(httpServer.url, {
+      context: { account: accounts[1] },
+    })
+    expect(response.status).toBe(200)
+
+    httpServer.close()
+  })
+})
+
+describe('polyfill', () => {
+  test('default: polyfills globalThis.fetch', async () => {
+    const originalFetch = globalThis.fetch
+
+    Mppx.create({
+      methods: [
+        tempo({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    expect(globalThis.fetch).not.toBe(originalFetch)
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    expect(response.status).toBe(200)
+
+    const receipt = Receipt.fromResponse(response)
+    expect(receipt.status).toBe('success')
+
+    httpServer.close()
+  })
+
+  test('behavior: polyfill false does not mutate globalThis.fetch', () => {
+    const originalFetch = globalThis.fetch
+
+    Mppx.create({
+      polyfill: false,
+      methods: [
+        tempo({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    expect(globalThis.fetch).toBe(originalFetch)
+  })
+})
+
+describe('restore', () => {
+  test('default: restores original fetch', () => {
+    const originalFetch = globalThis.fetch
+
+    Mppx.create({
+      methods: [
+        tempo({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    expect(globalThis.fetch).not.toBe(originalFetch)
+
+    Mppx.restore()
+
+    expect(globalThis.fetch).toBe(originalFetch)
+  })
+
+  test('behavior: noop when not polyfilled', () => {
+    const originalFetch = globalThis.fetch
+
+    Mppx.create({
+      polyfill: false,
+      methods: [
+        tempo({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    Mppx.restore()
+
+    expect(globalThis.fetch).toBe(originalFetch)
+  })
+})

package/src/client/Mppx.ts

@@ -0,0 +1,149 @@
+import type * as Challenge from '../Challenge.js'
+import type * as MethodIntent from '../MethodIntent.js'
+import type * as z from '../zod.js'
+import * as Fetch from './internal/Fetch.js'
+import * as Transport from './Transport.js'
+
+export type Methods = readonly (MethodIntent.AnyClient | readonly MethodIntent.AnyClient[])[]
+
+/**
+ * Client-side payment handler.
+ */
+export type Mppx<
+  methods extends Methods = Methods,
+  transport extends Transport.Transport = Transport.Transport,
+> = {
+  /** Payment-aware fetch function that automatically handles 402 responses. */
+  fetch: Fetch.from.Fetch<FlattenMethods<methods>>
+  /** Methods to configure. */
+  methods: FlattenMethods<methods>
+  /** The transport used. */
+  transport: transport
+  /** Creates a credential from a payment-required response by routing to the correct method. */
+  createCredential: (
+    response: Transport.ResponseOf<transport>,
+    context?: AnyContextFor<FlattenMethods<methods>> | undefined,
+  ) => Promise<string>
+}
+
+/**
+ * Creates a client-side payment handler from an array of method intents.
+ *
+ * Returns a payment handler with a `fetch` function that automatically handles
+ * 402 Payment Required responses. By default, also polyfills `globalThis.fetch`.
+ *
+ * @example
+ * ```ts
+ * import { Mppx, tempo } from 'mppx/client'
+ *
+ * const mppx = Mppx.create({
+ *   methods: [tempo({ account })],
+ * })
+ *
+ * // Use the returned fetch — handles 402 automatically
+ * const res = await mppx.fetch('/resource')
+ *
+ * // Or use globalThis.fetch (polyfilled by default)
+ * const res2 = await fetch('/resource')
+ * ```
+ */
+export function create<
+  const methods extends Methods,
+  const transport extends Transport.Transport<any, any> = Transport.Transport<
+    RequestInit,
+    Response
+  >,
+>(config: create.Config<methods, transport>): Mppx<methods, transport> {
+  const { polyfill = true, transport = Transport.http() as transport } = config
+
+  const methods = config.methods.flat() as unknown as FlattenMethods<methods>
+
+  const config_fetch = { ...(config.fetch && { fetch: config.fetch }), methods }
+  const fetch = Fetch.from(config_fetch)
+
+  if (polyfill) Fetch.polyfill(config_fetch)
+  return {
+    fetch,
+    methods,
+    transport,
+    async createCredential(response: Transport.ResponseOf<transport>, context?: unknown) {
+      const challenge = transport.getChallenge(response as never) as Challenge.Challenge
+
+      const mi = methods.find((m) => m.method === challenge.method && m.name === challenge.intent)
+      if (!mi)
+        throw new Error(
+          `No method intent found for "${challenge.method}.${challenge.intent}". Available: ${methods.map((m) => `${m.method}.${m.name}`).join(', ')}`,
+        )
+
+      const parsedContext =
+        mi.context && context !== undefined ? mi.context.parse(context) : undefined
+
+      return mi.createCredential(
+        parsedContext !== undefined
+          ? { challenge, context: parsedContext }
+          : ({ challenge } as never),
+      )
+    },
+  }
+}
+
+/**
+ * Restores the original `fetch` after `create()` polyfilled it.
+ *
+ * @example
+ * ```ts
+ * import { Mppx, tempo } from 'mppx/client'
+ *
+ * Mppx.create({ methods: [tempo({ account })] })
+ *
+ * // ... use payment-aware fetch ...
+ *
+ * Mppx.restore()
+ * ```
+ */
+export function restore(): void {
+  Fetch.restore()
+}
+
+export declare namespace create {
+  type Config<
+    methods extends Methods = Methods,
+    transport extends Transport.Transport = Transport.Transport,
+  > = {
+    /** Custom fetch function to wrap. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch
+    /** Array of method intents to use. Accepts individual clients or tuples (e.g. from `tempo()`). */
+    methods: methods
+    /** Whether to polyfill `globalThis.fetch` with the payment-aware wrapper. @default true */
+    polyfill?: boolean | undefined
+    /** Transport to use (defaults to HTTP). */
+    transport?: transport | undefined
+  }
+}
+
+/**
+ * Union of all context types from all methods that have context schemas.
+ * @internal
+ */
+type AnyContextFor<methods extends readonly MethodIntent.AnyClient[]> = {
+  [method in keyof methods]: methods[method] extends MethodIntent.Client<any, infer context>
+    ? context extends z.ZodMiniType
+      ? z.input<context>
+      : undefined
+    : undefined
+}[number]
+
+/**
+ * Flattens a methods config tuple, preserving positional types.
+ * @internal
+ */
+type FlattenMethods<methods extends Methods> = methods extends readonly [
+  infer head,
+  ...infer tail extends Methods,
+]
+  ? head extends readonly MethodIntent.AnyClient[]
+    ? readonly [...head, ...FlattenMethods<tail>]
+    : head extends MethodIntent.AnyClient
+      ? readonly [head, ...FlattenMethods<tail>]
+      : never
+  : readonly []