mppx 0.0.1 → 0.1.1

package/src/client/Mppx.ts

@@ -0,0 +1,165 @@
+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 { onChallenge, polyfill = true, transport = Transport.http() as transport } = config
+
+  const methods = config.methods.flat() as unknown as FlattenMethods<methods>
+
+  const resolvedOnChallenge = onChallenge as Fetch.from.Config<
+    FlattenMethods<methods>
+  >['onChallenge']
+  const config_fetch = {
+    ...(config.fetch && { fetch: config.fetch }),
+    ...(resolvedOnChallenge && { onChallenge: resolvedOnChallenge }),
+    methods,
+  } satisfies Fetch.from.Config<FlattenMethods<methods>>
+  const fetch = Fetch.from<FlattenMethods<methods>>(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
+    /** Called when a 402 challenge is received, before credential creation. */
+    onChallenge?:
+      | ((
+          challenge: Challenge.Challenge,
+          helpers: {
+            createCredential: (context?: AnyContextFor<FlattenMethods<methods>>) => Promise<string>
+          },
+        ) => Promise<string | undefined>)
+      | undefined
+    /** 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 []

package/src/client/Transport.test.ts

@@ -0,0 +1,283 @@
+import { Challenge, Credential, Mcp } from 'mppx'
+import { Transport } from 'mppx/client'
+import { MethodIntents as Intents } from 'mppx/tempo'
+import { describe, expect, test } from 'vitest'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+const challenge = Challenge.fromIntent(Intents.charge, {
+  realm,
+  secretKey,
+  request: {
+    amount: '0.001',
+    currency: '0x20c0000000000000000000000000000000000001',
+    decimals: 6,
+    recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+    expires: '2025-01-01T00:00:00.000Z',
+  },
+})
+
+const credential = Credential.from({
+  challenge,
+  payload: { signature: '0xabc123', type: 'transaction' },
+})
+
+describe('http', () => {
+  describe('isPaymentRequired', () => {
+    test('returns true for 402 response', () => {
+      const transport = Transport.http()
+      const response = new Response(null, { status: 402 })
+
+      expect(transport.isPaymentRequired(response)).toBe(true)
+    })
+
+    test('returns false for 200 response', () => {
+      const transport = Transport.http()
+      const response = new Response(null, { status: 200 })
+
+      expect(transport.isPaymentRequired(response)).toBe(false)
+    })
+
+    test('returns false for other error responses', () => {
+      const transport = Transport.http()
+      const response = new Response(null, { status: 401 })
+
+      expect(transport.isPaymentRequired(response)).toBe(false)
+    })
+  })
+
+  describe('getChallenge', () => {
+    test('default', () => {
+      const transport = Transport.http()
+      const response = new Response(null, {
+        status: 402,
+        headers: {
+          'WWW-Authenticate': Challenge.serialize(challenge),
+        },
+      })
+
+      expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
+        {
+          "expires": "2025-01-01T00:00:00.000Z",
+          "id": "EUAHxZRCSFB29SAs5TEcB4cQDS0uVDzl8uSYuA58aVs",
+          "intent": "charge",
+          "method": "tempo",
+          "realm": "api.example.com",
+          "request": {
+            "amount": "1000",
+            "currency": "0x20c0000000000000000000000000000000000001",
+            "expires": "2025-01-01T00:00:00.000Z",
+            "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+          },
+        }
+      `)
+    })
+
+    test('throws for non-402 response', () => {
+      const transport = Transport.http()
+      const response = new Response(null, { status: 200 })
+
+      expect(() => transport.getChallenge(response)).toThrow()
+    })
+  })
+
+  describe('setCredential', () => {
+    test('default', () => {
+      const transport = Transport.http()
+      const serialized = Credential.serialize(credential)
+
+      const result = transport.setCredential({}, serialized)
+      const headers = result.headers as Headers
+
+      expect(headers.get('Authorization')).toMatchInlineSnapshot(
+        `"Payment eyJjaGFsbGVuZ2UiOnsiZXhwaXJlcyI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiIsImlkIjoiRVVBSHhaUkNTRkIyOVNBczVURWNCNGNRRFMwdVZEemw4dVNZdUE1OGFWcyIsImludGVudCI6ImNoYXJnZSIsIm1ldGhvZCI6InRlbXBvIiwicmVhbG0iOiJhcGkuZXhhbXBsZS5jb20iLCJyZXF1ZXN0IjoiZXlKamRYSnlaVzVqZVNJNklqQjRNakJqTURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREF3TVNJc0ltVjRjR2x5WlhNaU9pSXlNREkxTFRBeExUQXhWREF3T2pBd09qQXdMakF3TUZvaUxDSnlaV05wY0dsbGJuUWlPaUl3ZURjME1tUXpOVU5qTmpZek5FTXdOVE15T1RJMVlUTmlPRFEwUW1NNVpUYzFPVFZtT0daRk1EQWlMQ0poYlc5MWJuUWlPaUl4TURBd0luMCJ9LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4YWJjMTIzIiwidHlwZSI6InRyYW5zYWN0aW9uIn19"`,
+      )
+    })
+
+    test('preserves existing headers', () => {
+      const transport = Transport.http()
+      const serialized = Credential.serialize(credential)
+
+      const result = transport.setCredential(
+        { headers: { 'Content-Type': 'application/json' } },
+        serialized,
+      )
+      const headers = result.headers as Headers
+
+      expect(headers.get('Content-Type')).toBe('application/json')
+    })
+  })
+})
+
+describe('mcp', () => {
+  const mcpRequest: Mcp.Request = {
+    method: 'tools/call',
+    params: {
+      name: 'test-tool',
+    },
+  }
+
+  describe('isPaymentRequired', () => {
+    test('returns true for payment required error', () => {
+      const transport = Transport.mcp()
+      const response: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+          code: Mcp.paymentRequiredCode,
+          message: 'Payment Required',
+          data: {
+            httpStatus: 402,
+            challenges: [challenge],
+          },
+        },
+      }
+
+      expect(transport.isPaymentRequired(response)).toBe(true)
+    })
+
+    test('returns false for success response', () => {
+      const transport = Transport.mcp()
+      const response: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        result: { content: [] },
+      }
+
+      expect(transport.isPaymentRequired(response)).toBe(false)
+    })
+
+    test('returns false for other error codes', () => {
+      const transport = Transport.mcp()
+      const response: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+          code: -32600,
+          message: 'Invalid Request',
+        },
+      }
+
+      expect(transport.isPaymentRequired(response)).toBe(false)
+    })
+  })
+
+  describe('getChallenge', () => {
+    test('default', () => {
+      const transport = Transport.mcp()
+      const response: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+          code: Mcp.paymentRequiredCode,
+          message: 'Payment Required',
+          data: {
+            httpStatus: 402,
+            challenges: [challenge],
+          },
+        },
+      }
+
+      expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
+        {
+          "expires": "2025-01-01T00:00:00.000Z",
+          "id": "EUAHxZRCSFB29SAs5TEcB4cQDS0uVDzl8uSYuA58aVs",
+          "intent": "charge",
+          "method": "tempo",
+          "realm": "api.example.com",
+          "request": {
+            "amount": "1000",
+            "currency": "0x20c0000000000000000000000000000000000001",
+            "expires": "2025-01-01T00:00:00.000Z",
+            "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+          },
+        }
+      `)
+    })
+
+    test('throws for success response', () => {
+      const transport = Transport.mcp()
+      const response: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        result: { content: [] },
+      }
+
+      expect(() => transport.getChallenge(response)).toThrow('Response is not an error')
+    })
+
+    test('throws when no challenges in error', () => {
+      const transport = Transport.mcp()
+      const response: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+          code: Mcp.paymentRequiredCode,
+          message: 'Payment Required',
+          data: {
+            httpStatus: 402,
+            challenges: [],
+          },
+        },
+      }
+
+      expect(() => transport.getChallenge(response)).toThrow('No challenge in error response')
+    })
+  })
+
+  describe('setCredential', () => {
+    test('default', () => {
+      const transport = Transport.mcp()
+      const serialized = Credential.serialize(credential)
+
+      expect(transport.setCredential(mcpRequest, serialized)).toMatchInlineSnapshot(`
+        {
+          "method": "tools/call",
+          "params": {
+            "_meta": {
+              "org.paymentauth/credential": {
+                "challenge": {
+                  "expires": "2025-01-01T00:00:00.000Z",
+                  "id": "EUAHxZRCSFB29SAs5TEcB4cQDS0uVDzl8uSYuA58aVs",
+                  "intent": "charge",
+                  "method": "tempo",
+                  "realm": "api.example.com",
+                  "request": {
+                    "amount": "1000",
+                    "currency": "0x20c0000000000000000000000000000000000001",
+                    "expires": "2025-01-01T00:00:00.000Z",
+                    "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+                  },
+                },
+                "payload": {
+                  "signature": "0xabc123",
+                  "type": "transaction",
+                },
+              },
+            },
+            "name": "test-tool",
+          },
+        }
+      `)
+    })
+
+    test('preserves existing _meta', () => {
+      const transport = Transport.mcp()
+      const serialized = Credential.serialize(credential)
+      const requestWithMeta: Mcp.Request = {
+        ...mcpRequest,
+        params: {
+          ...mcpRequest.params,
+          _meta: {
+            existingKey: 'existingValue',
+          },
+        },
+      }
+
+      const result = transport.setCredential(requestWithMeta, serialized)
+
+      expect(result.params?._meta?.existingKey).toBe('existingValue')
+    })
+  })
+})

package/src/client/Transport.ts

@@ -0,0 +1,115 @@
+import * as Challenge from '../Challenge.js'
+import * as Credential from '../Credential.js'
+import * as Mcp from '../Mcp.js'
+
+/**
+ * Client-side transport adapter.
+ *
+ * Abstracts how challenges are received and credentials are sent
+ * across different transport protocols (HTTP, MCP, etc.).
+ */
+export type Transport<in out request = unknown, in out response = unknown> = {
+  /** Transport name for identification. */
+  name: string
+  /** Checks if a response indicates payment is required. */
+  isPaymentRequired: (response: response) => boolean
+  /** Extracts the challenge from a payment-required response. */
+  getChallenge: (response: response) => Challenge.Challenge
+  /** Attaches a credential to a request. */
+  setCredential: (request: request, credential: string) => request
+}
+export type AnyTransport = Transport<any, any>
+
+/** Extracts the response type from a transport. */
+export type ResponseOf<transport extends Transport> =
+  transport extends Transport<any, infer response> ? response : never
+
+/** Extracts the request type from a transport. */
+export type RequestOf<transport extends Transport> =
+  transport extends Transport<infer request, any> ? request : never
+
+/**
+ * Creates a custom client-side transport.
+ *
+ * @example
+ * ```ts
+ * import { Transport } from 'mppx/client'
+ *
+ * const custom = Transport.from({
+ *   name: 'custom',
+ *   isPaymentRequired(response) { ... },
+ *   getChallenge(response) { ... },
+ *   setCredential(request, credential) { ... },
+ * })
+ * ```
+ */
+export function from<request, response>(
+  transport: Transport<request, response>,
+): Transport<request, response> {
+  return transport
+}
+
+/**
+ * HTTP transport for client-side payment handling.
+ *
+ * - Detects payment required via 402 status
+ * - Extracts challenges from `WWW-Authenticate` header
+ * - Sends credentials via `Authorization` header
+ */
+export function http() {
+  return from<RequestInit, Response>({
+    name: 'http',
+
+    isPaymentRequired(response) {
+      return response.status === 402
+    },
+
+    getChallenge(response) {
+      return Challenge.fromResponse(response)
+    },
+
+    setCredential(request, credential) {
+      const headers = new Headers(request.headers)
+      headers.set('Authorization', credential)
+      return { ...request, headers }
+    },
+  })
+}
+
+/**
+ * MCP transport for client-side payment handling.
+ *
+ * - Detects payment required via error code -32042
+ * - Extracts challenges from `error.data.challenges[0]`
+ * - Sends credentials via `_meta["org.paymentauth/credential"]`
+ */
+export function mcp() {
+  return from<Mcp.Request, Mcp.Response>({
+    name: 'mcp',
+
+    isPaymentRequired(response) {
+      return 'error' in response && response.error?.code === Mcp.paymentRequiredCode
+    },
+
+    getChallenge(response) {
+      if (!('error' in response) || !response.error) throw new Error('Response is not an error.')
+      const challenge = response.error.data?.challenges[0]
+      if (!challenge) throw new Error('No challenge in error response.')
+      return challenge
+    },
+
+    setCredential(request, credential) {
+      const parsed = Credential.deserialize(credential)
+      return {
+        ...request,
+        params: {
+          ...request.params,
+          _meta: {
+            ...request.params?._meta,
+            [Mcp.credentialMetaKey]: parsed,
+          },
+        },
+      }
+    },
+  })
+}

package/src/client/index.ts

@@ -0,0 +1,4 @@
+export * as Expires from '../Expires.js'
+export { session, stripe, tempo } from './Methods.js'
+export * as Mppx from './Mppx.js'
+export * as Transport from './Transport.js'

package/src/client/internal/Fetch.test-d.ts

@@ -0,0 +1,57 @@
+import type { Account } from 'viem'
+import { describe, expectTypeOf, test } from 'vitest'
+import { charge } from '../../tempo/client/Charge.js'
+import * as Fetch from './Fetch.js'
+
+describe('Fetch.from', () => {
+  test('default', () => {
+    const fetch = Fetch.from({
+      methods: [charge()],
+    })
+
+    expectTypeOf(fetch).toBeFunction()
+    expectTypeOf(fetch).returns.toMatchTypeOf<Promise<Response>>()
+  })
+
+  test('behavior: accepts context in RequestInit when method has context', () => {
+    const fetch = Fetch.from({
+      methods: [charge()],
+    })
+
+    expectTypeOf(fetch).toBeCallableWith('https://example.com', {
+      context: { account: {} as Account },
+    })
+  })
+
+  test('behavior: context is optional in RequestInit', () => {
+    const fetch = Fetch.from({
+      methods: [charge()],
+    })
+
+    expectTypeOf(fetch).toBeCallableWith('https://example.com')
+    expectTypeOf(fetch).toBeCallableWith('https://example.com', {})
+  })
+
+  test('behavior: RequestInit extends standard RequestInit', () => {
+    const fetch = Fetch.from({
+      methods: [charge()],
+    })
+
+    expectTypeOf(fetch).toBeCallableWith('https://example.com', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ foo: 'bar' }),
+    })
+  })
+})
+
+describe('Fetch.from.RequestInit', () => {
+  test('behavior: has context property typed to method context', () => {
+    const method = charge()
+
+    type Methods = [typeof method]
+    type Init = Fetch.from.RequestInit<Methods>
+
+    expectTypeOf<Init>().toHaveProperty('context')
+  })
+})