mppx 0.0.1 → 0.1.0

package/src/MethodIntent.ts

@@ -0,0 +1,388 @@
+import type * as Challenge from './Challenge.js'
+import type * as Credential from './Credential.js'
+import * as Intent from './Intent.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 * as z from './zod.js'
+
+/**
+ * A payment method-specific intent.
+ */
+export type MethodIntent<
+  intent extends Intent.Intent = Intent.Intent,
+  options extends fromIntent.Options<intent> = fromIntent.Options<intent>,
+> = {
+  method: options['method']
+  name: intent['name']
+  schema: {
+    credential: {
+      payload: options['schema']['credential']['payload']
+    }
+    request: MergedRequestSchema<intent, options>
+  }
+}
+export type AnyMethodIntent = MethodIntent<any, any>
+
+/**
+ * Creates a method-specific intent.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod/mini'
+ * import { MethodIntent } from 'mppx'
+ *
+ * const tempoCharge = MethodIntent.from({
+ *   method: 'tempo',
+ *   name: '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 intent extends MethodIntent>(intent: intent): intent {
+  return intent
+}
+
+/**
+ * Creates a method-specific intent from a base intent.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod/mini'
+ * import { Intent, MethodIntent } from 'mppx'
+ *
+ * const tempoCharge = MethodIntent.fromIntent(Intent.charge, {
+ *   method: 'tempo',
+ *   schema: {
+ *     credential: {
+ *       payload: z.object({
+ *         signature: z.string(),
+ *         type: z.literal('transaction'),
+ *       }),
+ *     },
+ *     request: {
+ *       methodDetails: z.object({
+ *         chainId: z.number(),
+ *       }),
+ *       requires: ['recipient'],
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export function fromIntent<
+  const intent extends Intent.Intent,
+  const options extends fromIntent.Options<intent>,
+>(intent: intent, options: options): MethodIntent<intent, options> {
+  const { name } = intent
+  const { method, schema } = options
+
+  const requestShape = Intent.shapeOf(intent) as Record<string, z.ZodMiniType>
+
+  const methodDetails = schema.request?.methodDetails
+  const requires = schema.request?.requires ?? []
+
+  const requestInputShape: Record<string, z.ZodMiniType> = {}
+  for (const [key, field] of Object.entries(requestShape)) {
+    if (requires.includes(key as never)) requestInputShape[key] = z.unwrapOptional(field)
+    else requestInputShape[key] = field
+  }
+
+  const methodDetailsKeys: string[] = []
+  if (methodDetails)
+    for (const [key, field] of Object.entries(
+      methodDetails.shape as Record<string, z.ZodMiniType>,
+    )) {
+      requestInputShape[key] = field
+      methodDetailsKeys.push(key)
+    }
+
+  const intentRequest = intent.schema.request
+  const hasPipe = !('shape' in intentRequest)
+
+  const request = z.pipe(
+    z.object(requestInputShape),
+    z.transform((input: Record<string, unknown>) => {
+      const transformed = hasPipe ? (intentRequest as z.ZodMiniType).parse(input) : input
+
+      const result: Record<string, unknown> = {}
+      const details: Record<string, unknown> = {}
+
+      for (const [key, value] of Object.entries(transformed as Record<string, unknown>)) {
+        result[key] = value
+      }
+
+      for (const key of methodDetailsKeys) {
+        const value = input[key]
+        if (value !== undefined) details[key] = value
+      }
+
+      if (Object.keys(details).length > 0) result.methodDetails = details
+      return result
+    }),
+  )
+
+  return {
+    method,
+    name,
+    schema: {
+      credential: { payload: schema.credential.payload },
+      request,
+    },
+  } as unknown as MethodIntent<intent, options>
+}
+
+export namespace fromIntent {
+  export type Options<intent extends Intent.Intent> = {
+    method: string
+    schema: {
+      credential: { payload: z.ZodMiniType }
+      request?:
+        | {
+            methodDetails?: z.ZodMiniObject | undefined
+            requires?: readonly (keyof Intent.ShapeOf<intent>)[] | undefined
+          }
+        | undefined
+    }
+  }
+}
+
+/** @internal */
+type RequiresKeys<
+  intent extends Intent.Intent,
+  options extends fromIntent.Options<intent>,
+> = options['schema']['request'] extends { requires: readonly (infer key)[] } ? key : never
+
+/** @internal */
+type UnwrapOptional<schema> = schema extends z.ZodMiniOptional<infer inner> ? inner : schema
+
+/** @internal */
+type MethodDetailsShape<
+  intent extends Intent.Intent,
+  options extends fromIntent.Options<intent>,
+> = options['schema']['request'] extends { methodDetails: infer details extends z.ZodMiniObject }
+  ? details['shape']
+  : Record<never, never>
+
+/** @internal */
+type InputRequestShape<intent extends Intent.Intent, options extends fromIntent.Options<intent>> = {
+  [K in keyof Intent.ShapeOf<intent>]: K extends RequiresKeys<intent, options>
+    ? UnwrapOptional<Intent.ShapeOf<intent>[K]>
+    : Intent.ShapeOf<intent>[K]
+} & MethodDetailsShape<intent, options>
+
+/** @internal */
+type MethodDetailsOutput<
+  intent extends Intent.Intent,
+  options extends fromIntent.Options<intent>,
+> = options['schema']['request'] extends { methodDetails: infer details extends z.ZodMiniObject }
+  ? { methodDetails?: z.output<details> }
+  : Record<never, never>
+
+/** @internal */
+type OutputRequestType<intent extends Intent.Intent, options extends fromIntent.Options<intent>> = {
+  [K in keyof Intent.ShapeOf<intent>]: K extends RequiresKeys<intent, options>
+    ? z.output<UnwrapOptional<Intent.ShapeOf<intent>[K]>>
+    : z.output<Intent.ShapeOf<intent>[K]>
+} & MethodDetailsOutput<intent, options>
+
+/** @internal */
+type MergedRequestSchema<
+  intent extends Intent.Intent,
+  options extends fromIntent.Options<intent>,
+> = z.ZodMiniType<
+  OutputRequestType<intent, options>,
+  z.input<z.ZodMiniObject<InputRequestShape<intent, options>>>
+>
+
+/**
+ * A client-side configured method intent with credential creation logic.
+ */
+export type Client<
+  intent extends AnyMethodIntent = MethodIntent,
+  context extends z.ZodMiniType | undefined = z.ZodMiniType | undefined,
+> = intent & {
+  context?: context
+  createCredential: CreateCredentialFn<
+    intent,
+    context extends z.ZodMiniType ? z.output<context> : Record<never, never>
+  >
+}
+export type AnyClient = Client<any, any>
+
+/**
+ * A server-side configured method intent with verification logic.
+ */
+export type Server<
+  intent extends AnyMethodIntent = MethodIntent,
+  defaults extends ExactPartial<z.input<intent['schema']['request']>> = {},
+  transportOverride = undefined,
+> = intent & {
+  defaults?: defaults | undefined
+  request?: RequestFn<intent> | undefined
+  respond?: RespondFn<intent> | undefined
+  transport?: transportOverride | undefined
+  verify: VerifyFn<intent>
+}
+export type AnyServer = Server<any, any, any>
+
+/** Credential creation function for a single intent. */
+export type CreateCredentialFn<intent extends AnyMethodIntent, context = unknown> = (
+  parameters: {
+    challenge: Challenge.Challenge<
+      z.output<intent['schema']['request']>,
+      intent['name'],
+      intent['method']
+    >
+  } & ([keyof context] extends [never] ? unknown : { context: context }),
+) => Promise<string>
+
+/** Request transform function for a single intent. */
+export type RequestFn<intent extends AnyMethodIntent> = (options: {
+  credential?: Credential.Credential | null | undefined
+  request: z.input<intent['schema']['request']>
+}) => MaybePromise<z.input<intent['schema']['request']>>
+
+/** Verification function for a single intent. */
+export type VerifyFn<intent extends AnyMethodIntent> = (parameters: {
+  credential: Credential.Credential<
+    z.output<intent['schema']['credential']['payload']>,
+    Challenge.Challenge<z.output<intent['schema']['request']>, intent['name'], intent['method']>
+  >
+  request: z.input<intent['schema']['request']>
+}) => Promise<Receipt.Receipt>
+
+/**
+ * Optional respond function for a server-side method intent.
+ *
+ * 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<intent extends AnyMethodIntent> = (parameters: {
+  credential: Credential.Credential<
+    z.output<intent['schema']['credential']['payload']>,
+    Challenge.Challenge<z.output<intent['schema']['request']>, intent['name'], intent['method']>
+  >
+  input: globalThis.Request
+  receipt: Receipt.Receipt
+  request: z.input<intent['schema']['request']>
+}) => MaybePromise<globalThis.Response | undefined>
+
+/** Partial request type for defaults. */
+export type RequestDefaults<intent extends AnyMethodIntent> = ExactPartial<
+  z.input<intent['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 intent with client-side credential creation logic.
+ *
+ * @example
+ * ```ts
+ * import { MethodIntent } from 'mppx'
+ * import { Intents } from 'mppx/tempo'
+ *
+ * const tempoCharge = MethodIntent.toClient(Intents.charge, {
+ *   async createCredential({ challenge }) {
+ *     return Credential.serialize({ challenge, payload: { ... } })
+ *   },
+ * })
+ * ```
+ */
+export function toClient<
+  const intent extends AnyMethodIntent,
+  const context extends z.ZodMiniType | undefined = undefined,
+>(intent: intent, options: toClient.Options<intent, context>): Client<intent, context> {
+  const { context, createCredential } = options
+  return {
+    ...intent,
+    context,
+    createCredential,
+  } as Client<intent, context>
+}
+
+export declare namespace toClient {
+  type Options<
+    intent extends AnyMethodIntent,
+    context extends z.ZodMiniType | undefined = undefined,
+  > = {
+    context?: context
+    createCredential: CreateCredentialFn<
+      intent,
+      context extends z.ZodMiniType ? z.output<context> : Record<never, never>
+    >
+  }
+}
+
+/**
+ * Extends a method intent with server-side verification logic.
+ *
+ * @example
+ * ```ts
+ * import { MethodIntent } from 'mppx'
+ * import { Intents } from 'mppx/tempo'
+ *
+ * const tempoCharge = MethodIntent.toServer(Intents.charge, {
+ *   async verify({ credential }) {
+ *     // verification logic
+ *     return { status: 'success', ... }
+ *   },
+ * })
+ * ```
+ */
+export function toServer<
+  const intent extends AnyMethodIntent,
+  const defaults extends RequestDefaults<intent> = {},
+  const transportOverride extends Transport.AnyTransport | undefined = undefined,
+>(
+  intent: intent,
+  options: toServer.Options<intent, defaults, transportOverride>,
+): Server<intent, defaults, transportOverride> {
+  const { defaults, request, respond, transport, verify } = options
+  return {
+    ...intent,
+    defaults,
+    request,
+    respond,
+    transport,
+    verify,
+  } as Server<intent, defaults, transportOverride>
+}
+
+export declare namespace toServer {
+  type Options<
+    intent extends AnyMethodIntent,
+    defaults extends RequestDefaults<intent> = {},
+    transportOverride extends Transport.AnyTransport | undefined = undefined,
+  > = {
+    defaults?: defaults | undefined
+    request?: RequestFn<intent> | undefined
+    respond?: RespondFn<intent> | undefined
+    transport?: transportOverride | undefined
+    verify: VerifyFn<intent>
+  }
+}

package/src/PaymentRequest.test.ts

@@ -0,0 +1,152 @@
+import { PaymentRequest } from 'mppx'
+import { MethodIntents as Intents } from 'mppx/tempo'
+import { describe, expect, test } from 'vitest'
+
+describe('from', () => {
+  test('creates a request', () => {
+    const request = PaymentRequest.from({
+      amount: '1000000',
+      currency: 'USD',
+      recipient: '0x1234',
+    })
+    expect(request).toMatchInlineSnapshot(`
+      {
+        "amount": "1000000",
+        "currency": "USD",
+        "recipient": "0x1234",
+      }
+    `)
+  })
+})
+
+describe('fromIntent', () => {
+  test('creates a validated request from intent', () => {
+    const request = PaymentRequest.fromIntent(Intents.charge, {
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+      expires: '2025-01-06T12:00:00Z',
+    })
+    expect(request).toMatchInlineSnapshot(`
+      {
+        "amount": "1000000",
+        "currency": "0x20c0000000000000000000000000000000000001",
+        "expires": "2025-01-06T12:00:00Z",
+        "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+      }
+    `)
+  })
+
+  test('includes methodDetails fields', () => {
+    const request = PaymentRequest.fromIntent(Intents.charge, {
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+      expires: '2025-01-06T12:00:00Z',
+      chainId: 42431,
+    })
+    expect(request).toMatchInlineSnapshot(`
+      {
+        "amount": "1000000",
+        "currency": "0x20c0000000000000000000000000000000000001",
+        "expires": "2025-01-06T12:00:00Z",
+        "methodDetails": {
+          "chainId": 42431,
+        },
+        "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+      }
+    `)
+  })
+
+  test('throws on invalid request', () => {
+    expect(() =>
+      PaymentRequest.fromIntent(Intents.charge, {
+        amount: 123,
+        currency: '0x20c0000000000000000000000000000000000001',
+        recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+        expires: '2025-01-06T12:00:00Z',
+      } as any),
+    ).toThrowErrorMatchingInlineSnapshot(`
+      [$ZodError: [
+        {
+          "expected": "string",
+          "code": "invalid_type",
+          "path": [
+            "amount"
+          ],
+          "message": "Invalid input"
+        },
+        {
+          "expected": "number",
+          "code": "invalid_type",
+          "path": [
+            "decimals"
+          ],
+          "message": "Invalid input"
+        }
+      ]]
+    `)
+  })
+})
+
+describe('serialize', () => {
+  test('serializes request to base64url', () => {
+    const request = PaymentRequest.from({
+      amount: '1000000',
+      currency: 'USD',
+    })
+    const serialized = PaymentRequest.serialize(request)
+    expect(serialized).toMatch(/^[A-Za-z0-9_-]+$/)
+    expect(serialized).not.toContain('=')
+    expect(serialized).not.toContain('+')
+    expect(serialized).not.toContain('/')
+  })
+
+  test('roundtrips correctly', () => {
+    const original = PaymentRequest.from({
+      amount: '1000000',
+      currency: 'USD',
+      recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+    })
+    const serialized = PaymentRequest.serialize(original)
+    const deserialized = PaymentRequest.deserialize(serialized)
+    expect(deserialized).toMatchInlineSnapshot(`
+      {
+        "amount": "1000000",
+        "currency": "USD",
+        "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+      }
+    `)
+  })
+})
+
+describe('deserialize', () => {
+  test('deserializes base64url to request', () => {
+    const original = { amount: '500', currency: 'EUR' }
+    const serialized = PaymentRequest.serialize(original)
+    const result = PaymentRequest.deserialize(serialized)
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "amount": "500",
+        "currency": "EUR",
+      }
+    `)
+  })
+
+  test('handles special characters in values', () => {
+    const original = {
+      amount: '1000000',
+      description: 'Payment for café & más',
+    }
+    const serialized = PaymentRequest.serialize(original)
+    const result = PaymentRequest.deserialize(serialized)
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "amount": "1000000",
+        "description": "Payment for café & más",
+      }
+    `)
+  })
+})

package/src/PaymentRequest.ts

@@ -0,0 +1,107 @@
+import { Base64 } from 'ox'
+import type { Compute } from './internal/types.js'
+import type * as MethodIntent from './MethodIntent.js'
+import type * as z from './zod.js'
+
+/**
+ * Intent-specific payment parameters.
+ *
+ * @example
+ * ```ts
+ * import { Request } from 'mppx'
+ *
+ * const request: Request.Request = {
+ *   amount: '1000000',
+ *   currency: '0x20c0000000000000000000000000000000000001',
+ *   recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+ * }
+ * ```
+ */
+export type Request<request extends Record<string, unknown> = Record<string, unknown>> =
+  Compute<request>
+
+/**
+ * Deserializes a base64url string to a request.
+ *
+ * @param encoded - The base64url-encoded string.
+ * @returns The deserialized request.
+ *
+ * @example
+ * ```ts
+ * import { Request } from 'mppx'
+ *
+ * const request = Request.deserialize(serialized)
+ * ```
+ */
+export function deserialize(encoded: string): Request {
+  const json = Base64.toString(encoded)
+  return JSON.parse(json)
+}
+
+/**
+ * Creates a request from the given parameters.
+ *
+ * @param request - Request parameters.
+ * @returns A request.
+ *
+ * @example
+ * ```ts
+ * import { Request } from 'mppx'
+ *
+ * const request = Request.from({
+ *   amount: '1000000',
+ *   currency: '0x20c0000000000000000000000000000000000001',
+ *   recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+ * })
+ * ```
+ */
+export function from<const request extends Request>(request: request): request {
+  return request
+}
+
+/**
+ * Creates a validated request from a method intent.
+ *
+ * @param intent - The method intent to validate against.
+ * @param request - Request parameters.
+ * @returns A validated request.
+ *
+ * @example
+ * ```ts
+ * import { Request } from 'mppx'
+ * import { Intents } from 'mppx/tempo'
+ *
+ * const request = Request.fromIntent(Intents.charge, {
+ *   amount: '1000000',
+ *   currency: '0x20c0000000000000000000000000000000000001',
+ *   recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+ *   expires: '2025-01-06T12:00:00Z',
+ *   chainId: 42431,
+ * })
+ * ```
+ */
+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']>>
+}
+
+/**
+ * Serializes a request to a base64url string.
+ *
+ * @param request - The request to serialize.
+ * @returns A base64url-encoded string (no padding).
+ *
+ * @example
+ * ```ts
+ * import { Request } from 'mppx'
+ *
+ * const serialized = Request.serialize(request)
+ * // => "eyJhbW91bnQiOiIxMDAwMDAwIiwiY3VycmVuY3kiOiIweC4uLiJ9"
+ * ```
+ */
+export function serialize(request: Request): string {
+  const json = JSON.stringify(request)
+  return Base64.fromString(json, { pad: false, url: true })
+}