mppx 0.1.1 → 0.2.0

package/src/Errors.ts

@@ -5,6 +5,9 @@ export abstract class PaymentError extends Error {
   /** RFC 9457 Problem Details type URI. */
   abstract readonly type: string
 
+  /** Human-readable summary for RFC 9457 Problem Details. */
+  abstract readonly title: string
+
   /** HTTP status code. */
   readonly status: number = 402
 
@@ -12,7 +15,7 @@ export abstract class PaymentError extends Error {
   toProblemDetails(challengeId?: string): PaymentError.ProblemDetails {
     return {
       type: this.type,
-      title: this.name,
+      title: this.title,
       status: this.status,
       detail: this.message,
       ...(challengeId && { challengeId }),
@@ -40,7 +43,9 @@ export declare namespace PaymentError {
  */
 export class MalformedCredentialError extends PaymentError {
   override readonly name = 'MalformedCredentialError'
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/malformed-credential'
+  readonly title = 'Malformed Credential'
+  override readonly status = 402
+  readonly type = 'https://paymentauth.org/problems/malformed-credential'
 
   constructor(options: MalformedCredentialError.Options = {}) {
     const { reason } = options
@@ -60,7 +65,9 @@ export declare namespace MalformedCredentialError {
  */
 export class InvalidChallengeError extends PaymentError {
   override readonly name = 'InvalidChallengeError'
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge'
+  readonly title = 'Invalid Challenge'
+  override readonly status = 402
+  readonly type = 'https://paymentauth.org/problems/invalid-challenge'
 
   constructor(options: InvalidChallengeError.Options = {}) {
     const { id, reason } = options
@@ -84,7 +91,8 @@ export declare namespace InvalidChallengeError {
  */
 export class VerificationFailedError extends PaymentError {
   override readonly name = 'VerificationFailedError'
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/verification-failed'
+  readonly title = 'Verification Failed'
+  readonly type = 'https://paymentauth.org/problems/verification-failed'
 
   constructor(options: VerificationFailedError.Options = {}) {
     const { reason } = options
@@ -104,7 +112,8 @@ export declare namespace VerificationFailedError {
  */
 export class PaymentActionRequiredError extends PaymentError {
   override readonly name = 'PaymentActionRequiredError'
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/payment-action-required'
+  readonly title = 'Payment Action Required'
+  readonly type = 'https://paymentauth.org/problems/payment-action-required'
 
   constructor(options: PaymentActionRequiredError.Options = {}) {
     const { reason } = options
@@ -124,7 +133,8 @@ export declare namespace PaymentActionRequiredError {
  */
 export class PaymentExpiredError extends PaymentError {
   override readonly name = 'PaymentExpiredError'
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/payment-expired'
+  readonly title = 'Payment Expired'
+  readonly type = 'https://paymentauth.org/problems/payment-expired'
 
   constructor(options: PaymentExpiredError.Options = {}) {
     const { expires } = options
@@ -144,7 +154,8 @@ export declare namespace PaymentExpiredError {
  */
 export class PaymentRequiredError extends PaymentError {
   override readonly name = 'PaymentRequiredError'
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/payment-required'
+  readonly title = 'Payment Required'
+  readonly type = 'https://paymentauth.org/problems/payment-required'
 
   constructor(options: PaymentRequiredError.Options = {}) {
     const { description, realm } = options
@@ -169,7 +180,8 @@ export declare namespace PaymentRequiredError {
  */
 export class InvalidPayloadError extends PaymentError {
   override readonly name = 'InvalidPayloadError'
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/invalid-payload'
+  readonly title = 'Invalid Payload'
+  readonly type = 'https://paymentauth.org/problems/invalid-payload'
 
   constructor(options: InvalidPayloadError.Options = {}) {
     const { reason } = options
@@ -189,8 +201,9 @@ export declare namespace InvalidPayloadError {
  */
 export class BadRequestError extends PaymentError {
   override readonly name = 'BadRequestError'
+  readonly title = 'Bad Request'
   override readonly status = 400
-  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/bad-request'
+  readonly type = 'https://paymentauth.org/problems/bad-request'
 
   constructor(options: BadRequestError.Options = {}) {
     const { reason } = options
@@ -205,11 +218,57 @@ export declare namespace BadRequestError {
   }
 }
 
+/**
+ * Payment amount is insufficient (too low).
+ */
+export class PaymentInsufficientError extends PaymentError {
+  override readonly name = 'PaymentInsufficientError'
+  readonly title = 'Payment Insufficient'
+  readonly type = 'https://paymentauth.org/problems/payment-insufficient'
+
+  constructor(options: PaymentInsufficientError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Payment insufficient: ${reason}.` : 'Payment amount is insufficient.')
+  }
+}
+
+export declare namespace PaymentInsufficientError {
+  type Options = {
+    /** Reason the payment is insufficient (e.g., "expected 1000, received 500"). */
+    reason?: string
+  }
+}
+
+/**
+ * Payment method is not supported by the server.
+ */
+export class PaymentMethodUnsupportedError extends PaymentError {
+  override readonly name = 'PaymentMethodUnsupportedError'
+  readonly title = 'Method Unsupported'
+  override readonly status = 400
+  readonly type = 'https://paymentauth.org/problems/method-unsupported'
+
+  constructor(options: PaymentMethodUnsupportedError.Options = {}) {
+    const { method } = options
+    super(
+      method ? `Payment method "${method}" is not supported.` : 'Payment method is not supported.',
+    )
+  }
+}
+
+export declare namespace PaymentMethodUnsupportedError {
+  type Options = {
+    /** The unsupported method identifier. */
+    method?: string
+  }
+}
+
 /**
  * Insufficient balance in the payment channel.
  */
 export class InsufficientBalanceError extends PaymentError {
   override readonly name = 'InsufficientBalanceError'
+  readonly title = 'Insufficient Balance'
   override readonly status = 402
   readonly type = 'https://paymentauth.org/problems/stream/insufficient-balance'
 
@@ -231,6 +290,7 @@ export declare namespace InsufficientBalanceError {
  */
 export class InvalidSignatureError extends PaymentError {
   override readonly name = 'InvalidSignatureError'
+  readonly title = 'Invalid Signature'
   override readonly status = 402
   readonly type = 'https://paymentauth.org/problems/stream/invalid-signature'
 
@@ -251,6 +311,7 @@ export declare namespace InvalidSignatureError {
  */
 export class SignerMismatchError extends PaymentError {
   override readonly name = 'SignerMismatchError'
+  readonly title = 'Signer Mismatch'
   override readonly status = 402
   readonly type = 'https://paymentauth.org/problems/stream/signer-mismatch'
 
@@ -271,6 +332,7 @@ export declare namespace SignerMismatchError {
  */
 export class AmountExceedsDepositError extends PaymentError {
   override readonly name = 'AmountExceedsDepositError'
+  readonly title = 'Amount Exceeds Deposit'
   override readonly status = 402
   readonly type = 'https://paymentauth.org/problems/stream/amount-exceeds-deposit'
 
@@ -291,6 +353,7 @@ export declare namespace AmountExceedsDepositError {
  */
 export class DeltaTooSmallError extends PaymentError {
   override readonly name = 'DeltaTooSmallError'
+  readonly title = 'Delta Too Small'
   override readonly status = 402
   readonly type = 'https://paymentauth.org/problems/stream/delta-too-small'
 
@@ -311,6 +374,7 @@ export declare namespace DeltaTooSmallError {
  */
 export class ChannelNotFoundError extends PaymentError {
   override readonly name = 'ChannelNotFoundError'
+  readonly title = 'Channel Not Found'
   override readonly status = 410
   readonly type = 'https://paymentauth.org/problems/stream/channel-not-found'
 
@@ -331,6 +395,7 @@ export declare namespace ChannelNotFoundError {
  */
 export class ChannelClosedError extends PaymentError {
   override readonly name = 'ChannelClosedError'
+  readonly title = 'Channel Closed'
   override readonly status = 410
   readonly type = 'https://paymentauth.org/problems/stream/channel-finalized'
 

package/src/Method.test.ts

@@ -0,0 +1,76 @@
+import { Method, z } from 'mppx'
+import { describe, expect, expectTypeOf, test } from 'vitest'
+
+describe('from', () => {
+  test('behavior: creates intent', () => {
+    const method = Method.from({
+      name: 'tempo',
+      intent: 'charge',
+      schema: {
+        credential: {
+          payload: z.object({
+            signature: z.string(),
+          }),
+        },
+        request: z.object({
+          amount: z.string(),
+          currency: z.string(),
+        }),
+      },
+    })
+
+    expect(method.intent).toBe('charge')
+    expect(method.name).toBe('tempo')
+    expect(method.schema.request).toBeDefined()
+    expect(method.schema.credential.payload).toBeDefined()
+  })
+
+  test('types: intent literal is inferred', () => {
+    const method = Method.from({
+      name: 'tempo',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ sig: z.string() }) },
+        request: z.object({ amount: z.string() }),
+      },
+    })
+
+    expectTypeOf(method.intent).toEqualTypeOf<'charge'>()
+  })
+
+  test('types: name literal is inferred', () => {
+    const method = Method.from({
+      name: 'tempo',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ sig: z.string() }) },
+        request: z.object({ amount: z.string() }),
+      },
+    })
+
+    expectTypeOf(method.name).toEqualTypeOf<'tempo'>()
+  })
+
+  test('types: schema types are preserved', () => {
+    const requestSchema = z.object({
+      amount: z.string(),
+      currency: z.string(),
+    })
+    const payloadSchema = z.object({
+      signature: z.string(),
+      type: z.literal('transaction'),
+    })
+
+    const method = Method.from({
+      name: 'tempo',
+      intent: 'charge',
+      schema: {
+        credential: { payload: payloadSchema },
+        request: requestSchema,
+      },
+    })
+
+    expectTypeOf(method.schema.request).toEqualTypeOf(requestSchema)
+    expectTypeOf(method.schema.credential.payload).toEqualTypeOf(payloadSchema)
+  })
+})

package/src/Method.ts

@@ -0,0 +1,228 @@
+import type * as Challenge from './Challenge.js'
+import type * as Credential from './Credential.js'
+import type { ExactPartial, LooseOmit, MaybePromise } from './internal/types.js'
+import type * as Receipt from './Receipt.js'
+import type * as Transport from './server/Transport.js'
+import type * as z from './zod.js'
+
+/**
+ * A payment method.
+ */
+export type Method = {
+  name: string
+  intent: string
+  schema: {
+    credential: {
+      payload: z.ZodMiniType
+    }
+    request: z.ZodMiniType<Record<string, unknown>>
+  }
+}
+
+/**
+ * Creates a payment method.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod/mini'
+ * import { Method } from 'mppx'
+ *
+ * const tempoCharge = Method.from({
+ *   name: 'tempo',
+ *   intent: 'charge',
+ *   schema: {
+ *     credential: {
+ *       payload: z.object({
+ *         signature: z.string(),
+ *         type: z.literal('transaction'),
+ *       }),
+ *     },
+ *     request: z.object({
+ *       amount: z.string(),
+ *       currency: z.string(),
+ *       recipient: z.string(),
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function from<const method extends Method>(method: method): method {
+  return method
+}
+
+/**
+ * A client-side configured method with credential creation logic.
+ */
+export type Client<
+  method extends Method = Method,
+  context extends z.ZodMiniType | undefined = z.ZodMiniType | undefined,
+> = method & {
+  context?: context
+  createCredential: CreateCredentialFn<
+    method,
+    context extends z.ZodMiniType ? z.output<context> : Record<never, never>
+  >
+}
+export type AnyClient = Client<any, any>
+
+/**
+ * A server-side configured method with verification logic.
+ */
+export type Server<
+  method extends Method = Method,
+  defaults extends ExactPartial<z.input<method['schema']['request']>> = {},
+  transportOverride = undefined,
+> = method & {
+  defaults?: defaults | undefined
+  request?: RequestFn<method> | undefined
+  respond?: RespondFn<method> | undefined
+  transport?: transportOverride | undefined
+  verify: VerifyFn<method>
+}
+export type AnyServer = Server<any, any, any>
+
+/** Credential creation function for a single method. */
+export type CreateCredentialFn<method extends Method, context = unknown> = (
+  parameters: {
+    challenge: Challenge.Challenge<
+      z.output<method['schema']['request']>,
+      method['intent'],
+      method['name']
+    >
+  } & ([keyof context] extends [never] ? unknown : { context: context }),
+) => Promise<string>
+
+/** Request transform function for a single method. */
+export type RequestFn<method extends Method> = (options: {
+  credential?: Credential.Credential | null | undefined
+  request: z.input<method['schema']['request']>
+}) => MaybePromise<z.input<method['schema']['request']>>
+
+/** Verification function for a single method. */
+export type VerifyFn<method extends Method> = (parameters: {
+  credential: Credential.Credential<
+    z.output<method['schema']['credential']['payload']>,
+    Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>
+  >
+  request: z.input<method['schema']['request']>
+}) => Promise<Receipt.Receipt>
+
+/**
+ * Optional respond function for a server-side method.
+ *
+ * Called after `verify` succeeds. If it returns a `Response`, the library
+ * treats the request as fully handled (e.g. channel open/close) and
+ * `withReceipt()` will short-circuit — returning the management response
+ * with the receipt header attached without invoking any user-supplied
+ * response or generator. If it returns `undefined`, the server handler
+ * is expected to serve content via `withReceipt(response)`.
+ *
+ * **HTTP-only.** The `input` parameter is a `Request` object; MCP transports
+ * do not invoke this hook.
+ */
+export type RespondFn<method extends Method> = (parameters: {
+  credential: Credential.Credential<
+    z.output<method['schema']['credential']['payload']>,
+    Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>
+  >
+  input: globalThis.Request
+  receipt: Receipt.Receipt
+  request: z.input<method['schema']['request']>
+}) => MaybePromise<globalThis.Response | undefined>
+
+/** Partial request type for defaults. */
+export type RequestDefaults<method extends Method> = ExactPartial<
+  z.input<method['schema']['request']>
+>
+
+/** Makes fields optional if they exist in defaults. */
+export type WithDefaults<request, defaults> = [keyof defaults] extends [never]
+  ? request
+  : LooseOmit<request, keyof defaults & string> &
+      ExactPartial<Pick<request, keyof defaults & keyof request>>
+
+/**
+ * Extends a method with client-side credential creation logic.
+ *
+ * @example
+ * ```ts
+ * import { Method } from 'mppx'
+ * import { Methods } from 'mppx/tempo'
+ *
+ * const tempoCharge = Method.toClient(Methods.charge, {
+ *   async createCredential({ challenge }) {
+ *     return Credential.serialize({ challenge, payload: { ... } })
+ *   },
+ * })
+ * ```
+ */
+export function toClient<
+  const method extends Method,
+  const context extends z.ZodMiniType | undefined = undefined,
+>(method: method, options: toClient.Options<method, context>): Client<method, context> {
+  const { context, createCredential } = options
+  return {
+    ...method,
+    context,
+    createCredential,
+  } as Client<method, context>
+}
+
+export declare namespace toClient {
+  type Options<method extends Method, context extends z.ZodMiniType | undefined = undefined> = {
+    context?: context
+    createCredential: CreateCredentialFn<
+      method,
+      context extends z.ZodMiniType ? z.output<context> : Record<never, never>
+    >
+  }
+}
+
+/**
+ * Extends a method with server-side verification logic.
+ *
+ * @example
+ * ```ts
+ * import { Method } from 'mppx'
+ * import { Methods } from 'mppx/tempo'
+ *
+ * const tempoCharge = Method.toServer(Methods.charge, {
+ *   async verify({ credential }) {
+ *     // verification logic
+ *     return { status: 'success', ... }
+ *   },
+ * })
+ * ```
+ */
+export function toServer<
+  const method extends Method,
+  const defaults extends RequestDefaults<method> = {},
+  const transportOverride extends Transport.AnyTransport | undefined = undefined,
+>(
+  method: method,
+  options: toServer.Options<method, defaults, transportOverride>,
+): Server<method, defaults, transportOverride> {
+  const { defaults, request, respond, transport, verify } = options
+  return {
+    ...method,
+    defaults,
+    request,
+    respond,
+    transport,
+    verify,
+  } as Server<method, defaults, transportOverride>
+}
+
+export declare namespace toServer {
+  type Options<
+    method extends Method,
+    defaults extends RequestDefaults<method> = {},
+    transportOverride extends Transport.AnyTransport | undefined = undefined,
+  > = {
+    defaults?: defaults | undefined
+    request?: RequestFn<method> | undefined
+    respond?: RespondFn<method> | undefined
+    transport?: transportOverride | undefined
+    verify: VerifyFn<method>
+  }
+}

package/src/PaymentRequest.test.ts

@@ -1,5 +1,5 @@
 import { PaymentRequest } from 'mppx'
-import { MethodIntents as Intents } from 'mppx/tempo'
+import { Methods } from 'mppx/tempo'
 import { describe, expect, test } from 'vitest'
 
 describe('from', () => {
@@ -21,7 +21,7 @@ describe('from', () => {
 
 describe('fromIntent', () => {
   test('creates a validated request from intent', () => {
-    const request = PaymentRequest.fromIntent(Intents.charge, {
+    const request = PaymentRequest.fromIntent(Methods.charge, {
       amount: '1',
       currency: '0x20c0000000000000000000000000000000000001',
       decimals: 6,
@@ -39,7 +39,7 @@ describe('fromIntent', () => {
   })
 
   test('includes methodDetails fields', () => {
-    const request = PaymentRequest.fromIntent(Intents.charge, {
+    const request = PaymentRequest.fromIntent(Methods.charge, {
       amount: '1',
       currency: '0x20c0000000000000000000000000000000000001',
       decimals: 6,
@@ -62,7 +62,7 @@ describe('fromIntent', () => {
 
   test('throws on invalid request', () => {
     expect(() =>
-      PaymentRequest.fromIntent(Intents.charge, {
+      PaymentRequest.fromIntent(Methods.charge, {
         amount: 123,
         currency: '0x20c0000000000000000000000000000000000001',
         recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',

package/src/PaymentRequest.ts

@@ -1,6 +1,6 @@
 import { Base64 } from 'ox'
 import type { Compute } from './internal/types.js'
-import type * as MethodIntent from './MethodIntent.js'
+import type * as Method from './Method.js'
 import type * as z from './zod.js'
 
 /**
@@ -62,16 +62,16 @@ export function from<const request extends Request>(request: request): request {
 /**
  * Creates a validated request from a method intent.
  *
- * @param intent - The method intent to validate against.
+ * @param method - The method to validate against.
  * @param request - Request parameters.
  * @returns A validated request.
  *
  * @example
  * ```ts
  * import { Request } from 'mppx'
- * import { Intents } from 'mppx/tempo'
+ * import { Methods } from 'mppx/tempo'
  *
- * const request = Request.fromIntent(Intents.charge, {
+ * const request = Request.fromIntent(Methods.charge, {
  *   amount: '1000000',
  *   currency: '0x20c0000000000000000000000000000000000001',
  *   recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
@@ -80,11 +80,11 @@ export function from<const request extends Request>(request: request): request {
  * })
  * ```
  */
-export function fromIntent<const intent extends MethodIntent.MethodIntent>(
-  intent: intent,
-  request: z.input<intent['schema']['request']>,
-): Request<z.output<intent['schema']['request']>> {
-  return intent.schema.request.parse(request) as Request<z.output<intent['schema']['request']>>
+export function fromIntent<const method extends Method.Method>(
+  method: method,
+  request: z.input<method['schema']['request']>,
+): Request<z.output<method['schema']['request']>> {
+  return method.schema.request.parse(request) as Request<z.output<method['schema']['request']>>
 }
 
 /**

package/src/cli.test.ts

@@ -11,7 +11,7 @@ import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 import * as Store from './Store.js'
 import * as Mppx_server from './server/Mppx.js'
 import { toNodeListener } from './server/Mppx.js'
-import { tempo } from './tempo/server/MethodIntents.js'
+import { tempo } from './tempo/server/Methods.js'
 
 const cliPath = path.resolve(import.meta.dirname, 'cli.ts')
 const cwd = path.resolve(import.meta.dirname, '..')
@@ -117,7 +117,7 @@ describe('basic charge (examples/basic)', () => {
     })
 
     try {
-      const { stdout } = await runAsync([httpServer.url, '--rpc-url', rpcUrl, '--yes', '-s'], {
+      const { stdout } = await runAsync([httpServer.url, '--rpc-url', rpcUrl, '-s'], {
         input: '',
       })
       expect(stdout).toContain('paid')
@@ -179,7 +179,7 @@ describe('session multi-fetch (examples/session/multi-fetch)', () => {
 
     try {
       const { stdout } = await runAsync(
-        [httpServer.url, '--rpc-url', rpcUrl, '--yes', '-s', '--deposit', '10'],
+        [httpServer.url, '--rpc-url', rpcUrl, '-s', '--deposit', '10'],
         { input: '' },
       )
       expect(stdout).toContain('scraped-content')
@@ -227,9 +227,10 @@ describe('session multi-fetch (examples/session/multi-fetch)', () => {
 
       try {
         // First request: open a channel, answer "y" to proceed, "n" to close channel
-        const first = await runAsync([httpServer.url, '--rpc-url', rpcUrl, '--deposit', '10'], {
-          input: 'y\nn\n',
-        })
+        const first = await runAsync(
+          [httpServer.url, '--rpc-url', rpcUrl, '--confirm', '--deposit', '10'],
+          { input: 'y\nn\n' },
+        )
         expect(first.stdout).toContain('scraped-content')
 
         // Extract channel ID from stderr (logged as "Channel opened 0x...")
@@ -239,17 +240,7 @@ describe('session multi-fetch (examples/session/multi-fetch)', () => {
 
         // Second request: reuse the channel via --channel
         const second = await runAsync(
-          [
-            httpServer.url,
-            '--rpc-url',
-            rpcUrl,
-            '--yes',
-            '-s',
-            '--channel',
-            channelId,
-            '--deposit',
-            '10',
-          ],
+          [httpServer.url, '--rpc-url', rpcUrl, '-s', '--channel', channelId, '--deposit', '10'],
           { input: '' },
         )
         expect(second.stdout).toContain('scraped-content')
@@ -322,10 +313,9 @@ describe('session sse (examples/session/sse)', () => {
     })
 
     try {
-      const { stdout } = await runAsync(
-        [httpServer.url, '--rpc-url', rpcUrl, '--yes', '--deposit', '10'],
-        { input: '' },
-      )
+      const { stdout } = await runAsync([httpServer.url, '--rpc-url', rpcUrl, '--deposit', '10'], {
+        input: '',
+      })
       expect(stdout.trim()).toBe('Hello world!')
     } finally {
       httpServer.close()
@@ -528,9 +518,9 @@ test('mppx --help', () => {
       -L, --location         Follow redirects 
       -X, --method <method>  HTTP method 
       --channel <id>         Reuse existing stream channel ID 
+      --confirm              Show confirmation prompts 
       --deposit <amount>     Deposit amount for stream payments (human-readable units) 
       --json <json>          Send JSON body (sets Content-Type and Accept, implies POST) 
-      --yes                  Skip confirmation prompts 
       -V, --version          Display version number 
       -h, --help             Display this message