mppx 0.5.11 → 0.5.13

package/src/internal/AcceptPayment.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, test } from 'vp/test'
+
+import * as AcceptPayment from './AcceptPayment.js'
+
+function stripIndex(entry: AcceptPayment.Entry) {
+  const { index: _index, ...rest } = entry
+  return rest
+}
+
+describe('AcceptPayment', () => {
+  test('resolve builds a typed header from methods and overrides', () => {
+    const resolved = AcceptPayment.resolve(
+      [
+        { name: 'tempo', intent: 'charge' },
+        { name: 'tempo', intent: 'session' },
+        { name: 'stripe', intent: 'charge' },
+      ] as const,
+      ({ tempo, stripe }) => ({
+        [stripe.charge]: 0.5,
+        [tempo.session]: 0,
+      }),
+    )
+
+    expect(resolved.header).toBe('tempo/charge, tempo/session;q=0, stripe/charge;q=0.5')
+    expect(resolved.keys.tempo.charge).toBe('tempo/charge')
+    expect(resolved.keys.tempo.session).toBe('tempo/session')
+    expect(resolved.keys.stripe.charge).toBe('stripe/charge')
+  })
+
+  test('parse supports q-values and wildcards', () => {
+    expect(
+      AcceptPayment.parse('tempo/*, stripe/charge;q=0.5, */session;q=0').map(stripIndex),
+    ).toEqual([
+      { intent: '*', method: 'tempo', q: 1 },
+      { intent: 'charge', method: 'stripe', q: 0.5 },
+      { intent: 'session', method: '*', q: 0 },
+    ])
+  })
+
+  test('parse raw header vectors into normalized entries', () => {
+    const vectors = [
+      {
+        header: 'tempo/charge',
+        entries: [{ intent: 'charge', method: 'tempo', q: 1 }],
+        normalized: 'tempo/charge',
+      },
+      {
+        header: ' stripe/charge ; q = 0.25 , */session ; q=0 ',
+        entries: [
+          { intent: 'charge', method: 'stripe', q: 0.25 },
+          { intent: 'session', method: '*', q: 0 },
+        ],
+        normalized: 'stripe/charge;q=0.25, */session;q=0',
+      },
+      {
+        header: 'tempo/*;q=1, tempo/charge;q=0, stripe/*;q=0.5',
+        entries: [
+          { intent: '*', method: 'tempo', q: 1 },
+          { intent: 'charge', method: 'tempo', q: 0 },
+          { intent: '*', method: 'stripe', q: 0.5 },
+        ],
+        normalized: 'tempo/*, tempo/charge;q=0, stripe/*;q=0.5',
+      },
+    ] as const
+
+    for (const { entries, header, normalized } of vectors) {
+      const parsed = AcceptPayment.parse(header)
+      expect(parsed.map(stripIndex)).toEqual(entries)
+      expect(AcceptPayment.serialize(parsed)).toBe(normalized)
+    }
+  })
+
+  test('parse rejects empty and malformed headers', () => {
+    expect(() => AcceptPayment.parse('')).toThrow('Accept-Payment header is empty.')
+    expect(() => AcceptPayment.parse('tempo')).toThrow('Invalid Accept-Payment entry: tempo')
+    expect(() => AcceptPayment.parse('Tempo/charge')).toThrow(
+      'Invalid Accept-Payment method: Tempo',
+    )
+    expect(() => AcceptPayment.parse('tempo/charge;q')).toThrow(
+      'Invalid Accept-Payment parameter: q',
+    )
+    expect(() => AcceptPayment.parse('tempo/charge;q=1.001')).toThrow('Expected an HTTP qvalue')
+  })
+
+  test('rank prefers higher q then preserves offer order for ties', () => {
+    const offers = [
+      { method: 'tempo', intent: 'charge' },
+      { method: 'stripe', intent: 'charge' },
+      { method: 'tempo', intent: 'session' },
+    ]
+    const preferences = AcceptPayment.parse(
+      'stripe/charge;q=0.5, tempo/charge;q=0.9, tempo/session;q=0.9',
+    )
+
+    expect(AcceptPayment.rank(offers, preferences)).toEqual([
+      { method: 'tempo', intent: 'charge' },
+      { method: 'tempo', intent: 'session' },
+      { method: 'stripe', intent: 'charge' },
+    ])
+  })
+
+  test('rank prefers more specific wildcard matches', () => {
+    const preferences = AcceptPayment.parse('tempo/*;q=0.5, tempo/session;q=0.5, */*;q=0.1')
+
+    expect(AcceptPayment.rank([{ method: 'tempo', intent: 'session' }], preferences)).toEqual([
+      { method: 'tempo', intent: 'session' },
+    ])
+  })
+
+  test('rank applies the most specific match before q-value filtering', () => {
+    const preferences = AcceptPayment.parse('tempo/*;q=1, tempo/charge;q=0, stripe/*;q=0.5')
+
+    expect(
+      AcceptPayment.rank(
+        [
+          { method: 'tempo', intent: 'charge' },
+          { method: 'stripe', intent: 'charge' },
+        ],
+        preferences,
+      ),
+    ).toEqual([{ method: 'stripe', intent: 'charge' }])
+  })
+
+  test('rank excludes offers matched only by q=0 preferences', () => {
+    const preferences = AcceptPayment.parse('tempo/charge;q=0, stripe/*;q=0.1')
+
+    expect(
+      AcceptPayment.rank(
+        [
+          { method: 'tempo', intent: 'charge' },
+          { method: 'stripe', intent: 'session' },
+        ],
+        preferences,
+      ),
+    ).toEqual([{ method: 'stripe', intent: 'session' }])
+  })
+
+  test('selectChallenge returns the best supported offer', () => {
+    const selected = AcceptPayment.selectChallenge(
+      [
+        { id: '1', intent: 'charge', method: 'stripe', realm: 'test', request: {} },
+        { id: '2', intent: 'session', method: 'tempo', realm: 'test', request: {} },
+      ],
+      [
+        { name: 'tempo', intent: 'session' },
+        { name: 'stripe', intent: 'charge' },
+      ] as const,
+      AcceptPayment.parse('stripe/charge;q=0.5, tempo/session;q=0.9'),
+    )
+
+    expect(selected?.challenge.id).toBe('2')
+    expect(selected?.method).toEqual({ name: 'tempo', intent: 'session' })
+  })
+
+  test('selectChallenge honors a specific opt-out over a broader wildcard', () => {
+    const selected = AcceptPayment.selectChallenge(
+      [
+        { id: '1', intent: 'charge', method: 'tempo', realm: 'test', request: {} },
+        { id: '2', intent: 'charge', method: 'stripe', realm: 'test', request: {} },
+      ],
+      [
+        { name: 'tempo', intent: 'charge' },
+        { name: 'stripe', intent: 'charge' },
+      ] as const,
+      AcceptPayment.parse('tempo/*;q=1, tempo/charge;q=0, stripe/*;q=0.5'),
+    )
+
+    expect(selected?.challenge.id).toBe('2')
+    expect(selected?.method).toEqual({ name: 'stripe', intent: 'charge' })
+  })
+
+  test('selectChallenge returns undefined when supported offers are disabled', () => {
+    const selected = AcceptPayment.selectChallenge(
+      [
+        { id: '1', intent: 'charge', method: 'tempo', realm: 'test', request: {} },
+        { id: '2', intent: 'charge', method: 'stripe', realm: 'test', request: {} },
+      ],
+      [{ name: 'tempo', intent: 'charge' }] as const,
+      AcceptPayment.parse('tempo/charge;q=0, stripe/charge'),
+    )
+
+    expect(selected).toBeUndefined()
+  })
+
+  test('throws for unknown payment preference keys', () => {
+    expect(() =>
+      AcceptPayment.resolve(
+        [{ name: 'tempo', intent: 'charge' }] as const,
+        {
+          'stripe/charge': 1,
+        } as never,
+      ),
+    ).toThrow('Unknown payment preference "stripe/charge"')
+  })
+
+  test('throws for invalid configured q-values', () => {
+    expect(() =>
+      AcceptPayment.resolve([{ name: 'tempo', intent: 'charge' }] as const, {
+        'tempo/charge': 0.3333,
+      }),
+    ).toThrow('Expected at most 3 decimal places')
+  })
+
+  test('throws for non-finite configured q-values', () => {
+    expect(() =>
+      AcceptPayment.resolve([{ name: 'tempo', intent: 'charge' }] as const, {
+        'tempo/charge': Number.POSITIVE_INFINITY,
+      }),
+    ).toThrow('Expected a finite number')
+  })
+})

package/src/internal/AcceptPayment.ts

@@ -0,0 +1,304 @@
+import type * as Challenge from '../Challenge.js'
+
+type MethodLike = {
+  intent: string
+  name: string
+}
+
+/** Typed `method/intent` key for a configured payment capability. */
+export type Key<methods extends readonly MethodLike[]> = methods[number] extends infer mi
+  ? mi extends { name: infer name extends string; intent: infer intent extends string }
+    ? `${name}/${intent}`
+    : never
+  : never
+
+/** Method keys grouped by method name for ergonomic config callbacks. */
+export type KeyTree<methods extends readonly MethodLike[]> = {
+  [name in methods[number]['name']]: {
+    [mi in Extract<
+      methods[number],
+      { name: name }
+    > as mi['intent']]: `${mi['name']}/${mi['intent']}`
+  }
+}
+
+/** Per-capability q-values keyed by typed `method/intent` strings. */
+export type Definition<methods extends readonly MethodLike[]> = Partial<
+  Record<Key<methods>, number>
+>
+
+/**
+ * Accept-Payment configuration.
+ *
+ * Callers may provide a plain definition map or a callback that receives a
+ * typed key tree for authoring preferences without string literals.
+ */
+export type Config<methods extends readonly MethodLike[]> =
+  | Definition<methods>
+  | ((keys: KeyTree<methods>) => Definition<methods>)
+
+/** Parsed Accept-Payment entry with its original declaration order. */
+export type Entry = {
+  intent: string | '*'
+  method: string | '*'
+  q: number
+  index: number
+}
+
+/** Resolved negotiation data derived from client methods and config. */
+export type Resolved<methods extends readonly MethodLike[]> = {
+  definition: Definition<methods>
+  entries: Entry[]
+  header: string
+  keys: KeyTree<methods>
+}
+
+type Match = Entry & { specificity: number }
+
+/** Builds the typed key tree used by callback-style preference config. */
+export function buildKeys<const methods extends readonly MethodLike[]>(
+  methods: methods,
+): KeyTree<methods> {
+  const keys: Record<string, Record<string, string>> = {}
+
+  for (const method of methods) {
+    const group = (keys[method.name] ??= {})
+    group[method.intent] = keyOf(method)
+  }
+
+  return keys as KeyTree<methods>
+}
+
+/** Resolves configured payment preferences into a header string and parsed entries. */
+export function resolve<const methods extends readonly MethodLike[]>(
+  methods: methods,
+  config?: Config<methods>,
+): Resolved<methods> {
+  const keys = buildKeys(methods)
+  const definition = resolveDefinition(methods, keys, config)
+  const entries = methods.map((method, index) => ({
+    intent: method.intent,
+    method: method.name,
+    q: definition[keyOf(method) as Key<methods>] ?? 1,
+    index,
+  }))
+
+  return {
+    definition,
+    entries,
+    header: serialize(entries),
+    keys,
+  }
+}
+
+/** Parses an `Accept-Payment` header into normalized preference entries. */
+export function parse(header: string): Entry[] {
+  const parts = header
+    .split(/\s*,\s*/)
+    .map((part) => part.trim())
+    .filter(Boolean)
+
+  if (parts.length === 0) throw new Error('Accept-Payment header is empty.')
+
+  return parts.map((part, index) => parseEntry(part, index))
+}
+
+/** Serializes preference entries to an `Accept-Payment` header value. */
+export function serialize(entries: readonly Omit<Entry, 'index'>[] | readonly Entry[]): string {
+  return entries
+    .map(({ method, intent, q }) => {
+      const value = `${method}/${intent}`
+      return q === 1 ? value : `${value};q=${formatQ(q)}`
+    })
+    .join(', ')
+}
+
+/**
+ * Orders offered payment methods by the best matching client preference.
+ *
+ * More specific matches win before comparing q-values, so an explicit opt-out
+ * like `tempo/charge;q=0` overrides a broader wildcard such as `tempo/*;q=1`.
+ */
+export function rank<const offer extends { intent: string; method: string }>(
+  offers: readonly offer[],
+  preferences: readonly Entry[],
+): offer[] {
+  return offers
+    .map((offer, index) => {
+      const match = bestMatch(offer, preferences)
+      return match && match.q > 0 ? { match, offer, index } : undefined
+    })
+    .filter((candidate): candidate is NonNullable<typeof candidate> => Boolean(candidate))
+    .sort((left, right) => right.match.q - left.match.q || left.index - right.index)
+    .map(({ offer }) => offer)
+}
+
+/** Selects the best supported challenge from a set of server offers. */
+export function selectChallenge<const methods extends readonly MethodLike[]>(
+  challenges: readonly Challenge.Challenge[],
+  methods: methods,
+  preferences: readonly Entry[],
+):
+  | {
+      challenge: Challenge.Challenge
+      method: methods[number]
+    }
+  | undefined {
+  const methodByKey = new Map<string, methods[number]>()
+  for (const method of methods) {
+    const key = keyOf(method)
+    if (!methodByKey.has(key)) methodByKey.set(key, method)
+  }
+
+  const ranked = rank(
+    challenges.filter((challenge) => methodByKey.has(keyOf(challenge))),
+    preferences,
+  )
+  const challenge = ranked[0]
+  if (!challenge) return undefined
+
+  return {
+    challenge,
+    method: methodByKey.get(keyOf(challenge))!,
+  }
+}
+
+/** Returns the canonical `method/intent` key for a method or challenge-like value. */
+export function keyOf(value: { intent: string; method?: string; name?: string }): string {
+  const method = value.method ?? value.name
+  if (!method) throw new Error('Missing payment method name.')
+  return `${method}/${value.intent}`
+}
+
+function bestMatch(
+  offer: { intent: string; method: string },
+  preferences: readonly Entry[],
+): Match | undefined {
+  let best: Match | undefined
+
+  for (const preference of preferences) {
+    if (!matches(offer, preference)) continue
+
+    const candidate = { ...preference, specificity: specificity(preference) }
+    if (
+      !best ||
+      candidate.specificity > best.specificity ||
+      (candidate.specificity === best.specificity && candidate.q > best.q) ||
+      (candidate.specificity === best.specificity &&
+        candidate.q === best.q &&
+        candidate.index < best.index)
+    ) {
+      best = candidate
+    }
+  }
+
+  return best
+}
+
+function matches(
+  offer: { intent: string; method: string },
+  preference: Pick<Entry, 'intent' | 'method'>,
+): boolean {
+  return (
+    (preference.method === '*' || preference.method === offer.method) &&
+    (preference.intent === '*' || preference.intent === offer.intent)
+  )
+}
+
+function specificity(preference: Pick<Entry, 'intent' | 'method'>): number {
+  return Number(preference.method !== '*') + Number(preference.intent !== '*')
+}
+
+function parseEntry(part: string, index: number): Entry {
+  const match =
+    /^(?<method>[^/;\s]+|\*)\s*\/\s*(?<intent>[^/;\s]+|\*)(?<params>(?:\s*;\s*.+)?)$/u.exec(part)
+  const method = match?.groups?.method
+  const intent = match?.groups?.intent
+
+  if (!method || !intent) {
+    throw new Error(`Invalid Accept-Payment entry: ${part}`)
+  }
+
+  assertToken(method, 'method')
+  assertToken(intent, 'intent')
+
+  let q = 1
+  for (const param of splitParameters(match.groups?.params)) {
+    if (!param) continue
+
+    const parameterMatch = /^(?<name>[A-Za-z0-9_-]+)\s*=\s*(?<value>\S+)$/u.exec(param)
+    const name = parameterMatch?.groups?.name
+    const rawValue = parameterMatch?.groups?.value
+
+    if (!name || !rawValue) {
+      throw new Error(`Invalid Accept-Payment parameter: ${param}`)
+    }
+    if (name !== 'q') continue
+    q = parseHeaderQ(rawValue, `Accept-Payment entry "${part}"`)
+  }
+
+  return { intent, method, q, index }
+}
+
+function splitParameters(value?: string): string[] {
+  return value ? value.split(/\s*;\s*/).filter(Boolean) : []
+}
+
+function resolveDefinition<const methods extends readonly MethodLike[]>(
+  methods: methods,
+  keys: KeyTree<methods>,
+  config?: Config<methods>,
+): Definition<methods> {
+  if (!config) return {} as Definition<methods>
+
+  const raw = typeof config === 'function' ? config(keys) : config
+  const allowed = new Set(methods.map((method) => keyOf(method)))
+  const normalized: Record<string, number> = {}
+
+  for (const [key, value] of Object.entries(raw ?? {})) {
+    if (!allowed.has(key)) {
+      throw new Error(`Unknown payment preference "${key}". Available: ${[...allowed].join(', ')}`)
+    }
+    normalized[key] = parseQ(value, `payment preference "${key}"`)
+  }
+
+  return normalized as Definition<methods>
+}
+
+function parseQ(value: unknown, context: string): number {
+  if (typeof value !== 'number' || Number.isNaN(value) || !Number.isFinite(value)) {
+    throw new Error(`Invalid q-value for ${context}. Expected a finite number.`)
+  }
+  return assertQ(value, context)
+}
+
+function parseHeaderQ(value: string, context: string): number {
+  if (!/^0(?:\.\d{0,3})?$|^1(?:\.0{0,3})?$/.test(value)) {
+    throw new Error(`Invalid q-value for ${context}. Expected an HTTP qvalue.`)
+  }
+  return assertQ(Number(value), context)
+}
+
+function assertQ(value: number, context: string): number {
+  if (value < 0 || value > 1) {
+    throw new Error(`Invalid q-value for ${context}. Expected a value between 0 and 1.`)
+  }
+  const rounded = Math.round(value * 1000)
+  if (Math.abs(value * 1000 - rounded) > 1e-9) {
+    throw new Error(`Invalid q-value for ${context}. Expected at most 3 decimal places.`)
+  }
+  return rounded / 1000
+}
+
+function formatQ(value: number): string {
+  return value
+    .toFixed(3)
+    .replace(/\.0+$/, '')
+    .replace(/(\.\d*?)0+$/, '$1')
+}
+
+function assertToken(value: string, label: string): void {
+  if (value !== '*' && !/^[a-z0-9-]+$/.test(value)) {
+    throw new Error(`Invalid Accept-Payment ${label}: ${value}`)
+  }
+}

package/src/mcp-sdk/client/McpClient.ts

@@ -3,6 +3,7 @@ import type { McpError } from '@modelcontextprotocol/sdk/types.js'
 
 import type * as Challenge from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
+import * as AcceptPayment from '../../internal/AcceptPayment.js'
 import * as core_Mcp from '../../Mcp.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
@@ -51,6 +52,7 @@ export function wrap<
   const methods extends readonly Method.AnyClient[],
 >(client: client, config: wrap.Config<methods>): wrap.McpClient<client, methods> {
   const { methods } = config
+  const paymentPreferences = AcceptPayment.resolve(methods)
 
   return {
     ...client,
@@ -76,11 +78,12 @@ export function wrap<
         const challenges = (error.data as { challenges?: Challenge.Challenge[] })?.challenges
         if (!challenges?.length) throw error
 
-        // Select first challenge that matches an installed method intent
-        const challenge = challenges.find((c) =>
-          methods.some((m) => m.name === c.method && m.intent === c.intent),
+        const selected = AcceptPayment.selectChallenge(
+          challenges,
+          methods,
+          paymentPreferences.entries,
         )
-        if (!challenge) {
+        if (!selected) {
           const available = challenges.map((c) => `${c.method}.${c.intent}`).join(', ')
           const installed = methods.map((m) => `${m.name}.${m.intent}`).join(', ')
           throw new Error(
@@ -89,7 +92,10 @@ export function wrap<
           )
         }
 
-        const credential = await createCredential(challenge, { context, methods })
+        const credential = await createCredential(selected.challenge, {
+          context,
+          methods,
+        })
         const parsed = Credential.deserialize(credential)
 
         const retryResult = await client.callTool(