feat: allow preparing requests without payment (#897)

* feat: allow preparing requests without payment

* fix: require strict request preparation option

* chore: release request preparation as patch

Author: brendanjryan

.changeset/prepare-request-non-payment.md

@@ -0,0 +1,5 @@
+---
+'mppx': patch
+---
+
+Allowed `prepareRequest` to return responses that do not require payment by default and added a strict `requirePayment` option.

src/client/Mppx.test-d.ts

@@ -74,7 +74,19 @@ describe('Mppx', () => {
     expectTypeOf(prepared.request).toEqualTypeOf<Request>()
     expectTypeOf(prepared.response).toEqualTypeOf<Response>()
     expectTypeOf(prepared.redirects).toEqualTypeOf<readonly Mppx.PreparedRequest.Redirect[]>()
-    expectTypeOf(prepared.pay({ account: {} as Account })).toEqualTypeOf<Promise<Response>>()
+    expectTypeOf(prepared.payment).toEqualTypeOf<
+      Mppx.PreparedRequest.Payment<readonly [typeof method]> | undefined
+    >()
+
+    const required = await mppx.prepareRequest('https://example.com/resource', undefined, {
+      requirePayment: true,
+    })
+    expectTypeOf(required.payment.pay({ account: {} as Account })).toEqualTypeOf<
+      Promise<Response>
+    >()
+
+    // @ts-expect-error requirePayment must be passed before the result can be narrowed
+    await mppx.prepareRequest<true>('https://example.com/resource')
   })
 
   test('uses custom transport request and response types', async () => {

src/client/Mppx.test.ts

@@ -412,7 +412,7 @@ describe('prepareRequest', () => {
     expect(Object.isFrozen(prepared)).toBe(true)
     expect(Object.isFrozen(prepared.redirects)).toBe(true)
 
-    const response = await prepared.pay()
+    const response = await prepared.payment!.pay()
 
     expect(response.status).toBe(307)
     expect(requests).toHaveLength(3)
@@ -485,7 +485,7 @@ describe('prepareRequest', () => {
       headers: { accept: 'application/json, text/event-stream' },
       method: 'POST',
     })
-    await prepared.pay()
+    await prepared.payment!.pay()
 
     const paidBody = JSON.parse(await requests[1]!.clone().text())
     expect(paidBody.params._meta[Mcp.credentialMetaKey]).toBeDefined()
@@ -575,12 +575,32 @@ describe('prepareRequest', () => {
     MethodChallenge.register(mppx.methods[0]!, prepare)
     const prepared = await mppx.prepareRequest('https://shop.example/resource')
 
-    await prepared.createCredential()
+    await prepared.payment!.createCredential()
 
     expect(prepare).toHaveBeenCalledOnce()
     expect(prepare.mock.calls[0]?.[0].input).toBeInstanceOf(Request)
   })
 
+  test('behavior: returns responses that do not require payment', async () => {
+    const response = new Response('available', { status: 200 })
+    const mppx = setup(vi.fn(async () => response) as typeof globalThis.fetch)
+
+    const prepared = await mppx.prepareRequest('https://shop.example/resource')
+
+    expect(prepared.response).toBe(response)
+    expect(prepared.payment).toBeUndefined()
+  })
+
+  test('error: optionally requires a payment response', async () => {
+    const mppx = setup(
+      vi.fn(async () => new Response('available', { status: 200 })) as typeof globalThis.fetch,
+    )
+
+    await expect(
+      mppx.prepareRequest('https://shop.example/resource', undefined, { requirePayment: true }),
+    ).rejects.toThrow('Response does not require payment.')
+  })
+
   test('error: explains opaque browser redirects', async () => {
     const opaqueRedirect = {
       headers: new Headers(),

src/client/Mppx.ts

@@ -40,21 +40,32 @@ export type PreparedPayment<
   ) => Transport.RequestOf<transport>
 }>
 
-/** A payment challenge prepared together with the exact HTTP request that produced it. */
-export type PreparedRequest<methods extends readonly Method.AnyClient[]> = Readonly<
-  PreparedPayment<methods, Transport.Transport<RequestInit, Response>> & {
-    /** Exact request that returned the selected payment challenge. */
-    request: Request
-    /** Payment-required response returned for {@link request}. */
-    response: Response
-    /** Redirects followed before receiving the payment challenge. */
-    redirects: readonly PreparedRequest.Redirect[]
-    /** Creates and sends a credential to the prepared request without following redirects. */
-    pay: (context?: AnyContextFor<methods> | undefined) => Promise<Response>
-  }
->
+/** An HTTP request prepared together with its response and optional payment. */
+export type PreparedRequest<
+  methods extends readonly Method.AnyClient[],
+  requirePayment extends boolean = false,
+> = Readonly<{
+  /** Exact request that produced {@link response}. */
+  request: Request
+  /** Response returned for {@link request}. */
+  response: Response
+  /** Redirects followed before receiving {@link response}. */
+  redirects: readonly PreparedRequest.Redirect[]
+  /** Selected payment when the response requires payment. */
+  payment: requirePayment extends true
+    ? PreparedRequest.Payment<methods>
+    : PreparedRequest.Payment<methods> | undefined
+}>
 
 export declare namespace PreparedRequest {
+  /** A request-bound payment that can be inspected or paid. */
+  type Payment<methods extends readonly Method.AnyClient[]> = Readonly<
+    PreparedPayment<methods, Transport.Transport<RequestInit, Response>> & {
+      /** Creates and sends a credential to the prepared request without following redirects. */
+      pay: (context?: AnyContextFor<methods> | undefined) => Promise<Response>
+    }
+  >
+
   /** A redirect followed while discovering a payment challenge. */
   type Redirect = Readonly<{
     from: string
@@ -96,16 +107,26 @@ export type Mppx<
     options?: preparePayment.Options<FlattenMethods<methods>, transport> | undefined,
   ) => Promise<PreparedPayment<FlattenMethods<methods>, transport>>
   /**
-   * Follows safe pre-payment redirects and prepares the challenge with the exact request that
-   * produced it. Credential-bearing requests never follow redirects. Requires a runtime that
-   * exposes manual redirect responses; browsers return opaque redirects and are not supported.
+   * Follows safe pre-payment redirects and returns the response with its exact request. When the
+   * response requires payment, prepares its selected challenge without creating a credential.
+   * Credential-bearing requests never follow redirects. Requires a runtime that exposes manual
+   * redirect responses; browsers return opaque redirects and are not supported.
    */
   prepareRequest: transport extends Transport.Transport<RequestInit, Response>
-    ? (
-        input: RequestInfo | URL,
-        init?: RequestInit | undefined,
-        options?: prepareRequest.Options<FlattenMethods<methods>> | undefined,
-      ) => Promise<PreparedRequest<FlattenMethods<methods>>>
+    ? {
+        <const requirePayment extends boolean>(
+          input: RequestInfo | URL,
+          init: RequestInit | undefined,
+          options: prepareRequest.Options<FlattenMethods<methods>, requirePayment> & {
+            requirePayment: requirePayment
+          },
+        ): Promise<PreparedRequest<FlattenMethods<methods>, requirePayment>>
+        (
+          input: RequestInfo | URL,
+          init?: RequestInit | undefined,
+          options?: prepareRequest.Options<FlattenMethods<methods>> | undefined,
+        ): Promise<PreparedRequest<FlattenMethods<methods>>>
+      }
     : never
   /** Creates a credential from a payment-required response by routing to the correct method. */
   createCredential: (
@@ -376,9 +397,9 @@ export function create<
   async function prepareRequest(
     input: RequestInfo | URL,
     init?: RequestInit,
-    options?: prepareRequest.Options<FlattenMethods<methods>>,
-  ): Promise<PreparedRequest<FlattenMethods<methods>>> {
-    const { maxRedirects = 20, ...paymentOptions } = options ?? {}
+    options?: prepareRequest.Options<FlattenMethods<methods>, boolean>,
+  ): Promise<PreparedRequest<FlattenMethods<methods>, boolean>> {
+    const { maxRedirects = 20, requirePayment = false, ...paymentOptions } = options ?? {}
     const preparedHttp = await prepareHttpRequest({
       acceptPayment: acceptPayment.header,
       acceptPaymentPolicy,
@@ -389,8 +410,17 @@ export function create<
       signer: attestationSigner,
     })
     const requestInit = requestToInit(preparedHttp.replayRequest, preparedHttp.body)
-    if (!(await transport.isPaymentRequired(preparedHttp.response as never, requestInit as never)))
-      throw new Error('Response does not require payment.')
+    if (
+      !(await transport.isPaymentRequired(preparedHttp.response as never, requestInit as never))
+    ) {
+      if (requirePayment) throw new Error('Response does not require payment.')
+      return Object.freeze({
+        payment: undefined,
+        request: preparedHttp.request,
+        response: preparedHttp.response,
+        redirects: preparedHttp.redirects,
+      })
+    }
 
     const payment = (await preparePayment(preparedHttp.response as never, {
       ...paymentOptions,
@@ -412,12 +442,9 @@ export function create<
       return payment.createCredential(context)
     })
 
-    return Object.freeze({
+    const preparedPayment = Object.freeze({
       ...payment,
       createCredential: createRequestCredential,
-      request: preparedHttp.request,
-      response: preparedHttp.response,
-      redirects: preparedHttp.redirects,
       async pay(context?: AnyContextFor<FlattenMethods<methods>>) {
         const credential = await createRequestCredential(context)
         const paidInit = payment.setCredential(
@@ -430,6 +457,12 @@ export function create<
         })
       },
     })
+    return Object.freeze({
+      payment: preparedPayment,
+      request: preparedHttp.request,
+      response: preparedHttp.response,
+      redirects: preparedHttp.redirects,
+    })
   }
 
   return {
@@ -465,12 +498,17 @@ export declare namespace preparePayment {
 
 export declare namespace prepareRequest {
   /** Options for preparing a request-bound payment. */
-  type Options<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[]> = Omit<
+  type Options<
+    methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[],
+    requirePayment extends boolean = false,
+  > = Omit<
     preparePayment.Options<methods, Transport.Transport<RequestInit, Response>>,
     'request'
   > & {
     /** Maximum redirects followed before rejecting the request. @default 20 */
     maxRedirects?: number | undefined
+    /** Throw when the response does not require payment. @default false */
+    requirePayment?: requirePayment | undefined
   }
 }