mppx 0.0.1 → 0.1.1

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

@@ -0,0 +1,315 @@
+import { Receipt } from 'mppx'
+import { tempo } from 'mppx/client'
+import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
+import { createClient } from 'viem'
+import { describe, expect, test, vi } from 'vitest'
+import * as Http from '~test/Http.js'
+import { accounts, asset, chain, client, http } from '~test/tempo/viem.js'
+import * as Fetch from './Fetch.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+const server = Mppx_server.create({
+  methods: [
+    tempo_server({
+      getClient: () => client,
+    }),
+  ],
+  realm,
+  secretKey,
+})
+
+describe('Fetch.from', () => {
+  test('default: account at creation', async () => {
+    const fetch = Fetch.from({
+      methods: [
+        tempo.charge({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(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,
+      reference: '[reference]',
+      timestamp: '[timestamp]',
+    }).toMatchInlineSnapshot(`
+      {
+        "method": "tempo",
+        "reference": "[reference]",
+        "status": "success",
+        "timestamp": "[timestamp]",
+      }
+    `)
+
+    httpServer.close()
+  })
+
+  test('default: account via context', async () => {
+    const fetch = Fetch.from({
+      methods: [
+        tempo.charge({
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url, {
+      context: { account: accounts[1] },
+    })
+    expect(response.status).toBe(200)
+
+    const receipt = Receipt.fromResponse(response)
+    expect(receipt.status).toBe('success')
+
+    httpServer.close()
+  })
+
+  test('behavior: context overrides account at creation', async () => {
+    const fetch = Fetch.from({
+      methods: [
+        tempo.charge({
+          account: accounts[0],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url, {
+      context: { account: accounts[1] },
+    })
+    expect(response.status).toBe(200)
+
+    httpServer.close()
+  })
+
+  test('behavior: throws when no account provided', async () => {
+    const fetch = Fetch.from({
+      methods: [
+        tempo.charge({
+          getClient: () => createClient({ chain, transport: http() }),
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    await expect(fetch(httpServer.url)).rejects.toThrow(
+      'No `account` provided. Pass `account` to parameters or context.',
+    )
+
+    httpServer.close()
+  })
+
+  test('behavior: passes through non-402 responses', async () => {
+    const fetch = Fetch.from({
+      methods: [
+        tempo.charge({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (_req, res) => {
+      res.writeHead(200)
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('OK')
+
+    httpServer.close()
+  })
+
+  test('behavior: fee payer', async () => {
+    const serverWithFeePayer = Mppx_server.create({
+      methods: [
+        tempo_server.charge({
+          feePayer: accounts[0],
+          getClient: () => client,
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    const fetch = Fetch.from({
+      methods: [
+        tempo.charge({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        serverWithFeePayer.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(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,
+      reference: '[reference]',
+      timestamp: '[timestamp]',
+    }).toMatchInlineSnapshot(`
+      {
+        "method": "tempo",
+        "reference": "[reference]",
+        "status": "success",
+        "timestamp": "[timestamp]",
+      }
+    `)
+
+    httpServer.close()
+  })
+
+  test('behavior: onChallenge can create credential', async () => {
+    const onChallenge = vi.fn(async (_challenge, { createCredential }) =>
+      createCredential({ account: accounts[1] }),
+    )
+
+    const fetch = Fetch.from({
+      methods: [
+        tempo.charge({
+          getClient: () => client,
+        }),
+      ],
+      onChallenge,
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    expect(response.status).toBe(200)
+    expect(onChallenge).toHaveBeenCalledTimes(1)
+
+    httpServer.close()
+  })
+})
+
+describe('Fetch.polyfill', () => {
+  test('default', async () => {
+    Fetch.polyfill({
+      methods: [
+        tempo.charge({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(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,
+      reference: '[reference]',
+      timestamp: '[timestamp]',
+    }).toMatchInlineSnapshot(`
+      {
+        "method": "tempo",
+        "reference": "[reference]",
+        "status": "success",
+        "timestamp": "[timestamp]",
+      }
+    `)
+
+    httpServer.close()
+    Fetch.restore()
+  })
+})

package/src/client/internal/Fetch.ts

@@ -0,0 +1,169 @@
+import * as Challenge from '../../Challenge.js'
+import type * as MethodIntent from '../../MethodIntent.js'
+import type * as z from '../../zod.js'
+
+let originalFetch: typeof globalThis.fetch | undefined
+
+/**
+ * Creates a fetch wrapper that automatically handles 402 Payment Required responses.
+ *
+ * @example
+ * ```ts
+ * import { Fetch, tempo } from 'mppx/client'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * const fetch = Fetch.from({
+ *   methods: [
+ *     tempo({
+ *       account: privateKeyToAccount('0x...'),
+ *     }),
+ *   ],
+ * })
+ *
+ * // Use the wrapped fetch — handles 402 automatically
+ * const res = await fetch('https://api.example.com/resource')
+ * ```
+ *
+ */
+export function from<const methods extends readonly MethodIntent.AnyClient[]>(
+  config: from.Config<methods>,
+): from.Fetch<methods> {
+  const { fetch = globalThis.fetch, methods, onChallenge } = config
+
+  return async (input, init) => {
+    const { context, ...fetchInit } = init ?? {}
+    const response = await fetch(input, fetchInit)
+
+    if (response.status !== 402) return response
+
+    const challenge = Challenge.fromResponse(response)
+
+    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 onChallengeCredential = onChallenge
+      ? await onChallenge(challenge, {
+          createCredential: async (overrideContext?: AnyContextFor<methods>) =>
+            resolveCredential(challenge, mi, overrideContext ?? context),
+        })
+      : undefined
+    const credential = onChallengeCredential ?? (await resolveCredential(challenge, mi, context))
+
+    return fetch(input, {
+      ...fetchInit,
+      headers: {
+        ...fetchInit.headers,
+        Authorization: credential,
+      },
+    })
+  }
+}
+
+/** Union of all context types from all methods that have context schemas. */
+type AnyContextFor<methods extends readonly MethodIntent.AnyClient[]> = {
+  [K in keyof methods]: methods[K] extends MethodIntent.Client<any, infer contextSchema>
+    ? contextSchema extends z.ZodMiniType
+      ? z.input<contextSchema>
+      : undefined
+    : undefined
+}[number]
+
+export declare namespace from {
+  type Config<
+    methods extends readonly MethodIntent.AnyClient[] = readonly MethodIntent.AnyClient[],
+  > = {
+    /** Custom fetch function to wrap. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch
+    /** Array of method intents to use. */
+    methods: methods
+    /** Called when a 402 challenge is received, before credential creation. */
+    onChallenge?:
+      | ((
+          challenge: Challenge.Challenge,
+          helpers: {
+            createCredential: (context?: AnyContextFor<methods>) => Promise<string>
+          },
+        ) => Promise<string | undefined>)
+      | undefined
+  }
+
+  type Fetch<
+    methods extends readonly MethodIntent.AnyClient[] = readonly MethodIntent.AnyClient[],
+  > = (input: RequestInfo | URL, init?: RequestInit<methods>) => Promise<Response>
+
+  type RequestInit<
+    methods extends readonly MethodIntent.AnyClient[] = readonly MethodIntent.AnyClient[],
+  > = globalThis.RequestInit & {
+    /** Context to pass to the method intent's createCredential. */
+    context?: AnyContextFor<methods>
+  }
+}
+
+/**
+ * Replaces the global `fetch` with a payment-aware wrapper.
+ *
+ * @example
+ * ```ts
+ * import { Fetch, tempo } from 'mppx/client'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * Fetch.polyfill({
+ *   methods: [
+ *     tempo({
+ *       account: privateKeyToAccount('0x...'),
+ *     }),
+ *   ],
+ * })
+ *
+ * // Global fetch now handles 402 automatically
+ * const res = await fetch('https://api.example.com/resource')
+ * ```
+ */
+export function polyfill<const methods extends readonly MethodIntent.AnyClient[]>(
+  config: polyfill.Config<methods>,
+): void {
+  originalFetch = globalThis.fetch
+  globalThis.fetch = from(config) as typeof globalThis.fetch
+}
+
+export declare namespace polyfill {
+  type Config<
+    methods extends readonly MethodIntent.AnyClient[] = readonly MethodIntent.AnyClient[],
+  > = from.Config<methods>
+}
+
+/**
+ * Restores the original `fetch` after calling `polyfill`.
+ *
+ * @example
+ * ```ts
+ * import { Fetch } from 'mppx/client'
+ *
+ * Fetch.polyfill({ methods: [...] })
+ *
+ * // ... use payment-aware fetch ...
+ *
+ * Fetch.restore()
+ * ```
+ */
+export function restore(): void {
+  if (originalFetch) {
+    globalThis.fetch = originalFetch
+    originalFetch = undefined
+  }
+}
+
+/** @internal */
+async function resolveCredential(
+  challenge: Challenge.Challenge,
+  mi: MethodIntent.AnyClient,
+  context: unknown,
+): Promise<string> {
+  const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined
+  return mi.createCredential(
+    parsedContext !== undefined ? { challenge, context: parsedContext } : ({ challenge } as never),
+  )
+}

package/src/env.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_NODE_ENV: 'localnet' | 'testnet' | 'mainnet'
+  readonly VITE_HTTP_LOG: 'true' | 'false'
+  readonly VITE_RPC_CREDENTIALS: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * as BodyDigest from './BodyDigest.js'
+export * as Challenge from './Challenge.js'
+export * as Credential from './Credential.js'
+export * as Errors from './Errors.js'
+export * as Expires from './Expires.js'
+export * as Intent from './Intent.js'
+export * as Mcp from './Mcp.js'
+export * as MethodIntent from './MethodIntent.js'
+export * as PaymentRequest from './PaymentRequest.js'
+export * as Receipt from './Receipt.js'
+export * as Store from './Store.js'
+export * as z from './zod.js'