mppx 0.0.1 → 0.1.0

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