mppx 0.3.4 → 0.3.6

package/src/cli.ts

@@ -15,6 +15,7 @@ import { type ZodMiniType, z } from 'zod/mini'
 import * as Challenge from './Challenge.js'
 import * as Credential from './Credential.js'
 import * as Mppx from './client/Mppx.js'
+import { stripe } from './stripe/client/index.js'
 import { tempo } from './tempo/client/index.js'
 import type { SessionCredentialPayload } from './tempo/session/Types.js'
 import { signVoucher } from './tempo/session/Voucher.js'
@@ -41,9 +42,8 @@ cli
   .option('-H, --header <header>', 'Add header (repeatable)')
   .option('-L, --location', 'Follow redirects')
   .option('-X, --method <method>', 'HTTP method')
-  .option('--channel <id>', 'Reuse existing session channel ID')
+  .option('-M, --method-opt <opt>', 'Method-specific option (key=value, repeatable)')
   .option('--confirm', 'Show confirmation prompts')
-  .option('--deposit <amount>', 'Deposit amount for session payments (human-readable units)')
   .option('--json <json>', 'Send JSON body (sets Content-Type and Accept, implies POST)')
   .example(`${name} example.com/content`)
   .example(`${name} example.com/api --json '{"key":"value"}'`)
@@ -51,10 +51,8 @@ cli
     const options = parseOptions(
       z.object({
         account: z.optional(z.string()),
-        channel: z.optional(z.coerce.string()),
         confirm: z.optional(z.boolean()),
         data: z.optional(z.string()),
-        deposit: z.optional(z.union([z.string(), z.number()])),
         fail: z.optional(z.boolean()),
         header: z.optional(z.union([z.string(), z.array(z.string())])),
         include: z.optional(z.boolean()),
@@ -62,6 +60,7 @@ cli
         json: z.optional(z.string()),
         location: z.optional(z.boolean()),
         method: z.optional(z.string()),
+        methodOpt: z.optional(z.union([z.string(), z.array(z.string())])),
         rpcUrl: z.optional(z.string()),
         silent: z.optional(z.boolean()),
         userAgent: z.optional(z.string()),
@@ -69,6 +68,7 @@ cli
       }),
       rawOptions,
     )
+    const methodOpts = parseMethodOpts(options.methodOpt)
     if (!rawUrl) {
       cli.outputHelp()
       return
@@ -79,12 +79,6 @@ cli
     if (silent) options.confirm = false
 
     const accountName = resolveAccountName(options.account)
-    const privateKey = process.env.MPPX_PRIVATE_KEY || (await createKeychain(accountName).get())
-    if (!privateKey) {
-      if (options.account) console.log(`Account "${accountName}" not found.`)
-      else console.log(`No account found.`)
-      process.exit(1)
-    }
 
     const headers: Record<string, string> = {}
     if (options.header) {
@@ -157,24 +151,43 @@ cli
         return
       }
 
-      const account = privateKeyToAccount(privateKey as `0x${string}`)
-      const rpcUrl = options.rpcUrl ?? (process.env.MPPX_RPC_URL || undefined)
-      const client = createClient({
-        chain: await resolveChain({ ...options, rpcUrl }),
-        transport: http(rpcUrl),
-      })
-
       const challenge = Challenge.fromResponse(challengeResponse)
-      const explorerUrl = client.chain?.blockExplorers?.default?.url
-      const shownKeys = new Set<string>()
       const challengeRequest = challenge.request as Record<string, unknown>
       const currency = challengeRequest.currency as string | undefined
-      const tokenInfo = currency
-        ? await fetchTokenInfo(client, currency as Address, account.address).catch(() => undefined)
-        : undefined
-      const tokenSymbol = tokenInfo?.symbol ?? currency ?? ''
-      const tokenDecimals =
-        tokenInfo?.decimals ?? (challengeRequest.decimals as number | undefined) ?? 6
+      const shownKeys = new Set<string>()
+
+      let tokenSymbol =
+        challenge.method === 'stripe' ? (currency?.toUpperCase() ?? '') : (currency ?? '')
+      let tokenDecimals =
+        (challengeRequest.decimals as number | undefined) ?? (challenge.method === 'stripe' ? 2 : 6)
+      let explorerUrl: string | undefined
+
+      // Tempo-specific setup (private key, viem account/client, token info)
+      let account: ReturnType<typeof privateKeyToAccount> | undefined
+      let client: ReturnType<typeof createClient> | undefined
+      if (challenge.method === 'tempo') {
+        const privateKey = process.env.MPPX_PRIVATE_KEY ?? (await createKeychain(accountName).get())
+        if (!privateKey) {
+          if (options.account) console.error(`Account "${accountName}" not found.`)
+          else console.error(`No account found.`)
+          process.exit(1)
+        }
+        account = privateKeyToAccount(privateKey as `0x${string}`)
+        const rpcUrl = options.rpcUrl ?? process.env.RPC_URL
+        client = createClient({
+          chain: await resolveChain({ ...options, rpcUrl }),
+          transport: http(rpcUrl),
+        })
+        explorerUrl = client.chain?.blockExplorers?.default?.url
+        const tokenInfo = currency
+          ? await fetchTokenInfo(client, currency as Address, account.address).catch(
+              () => undefined,
+            )
+          : undefined
+        tokenSymbol = tokenInfo?.symbol ?? currency ?? ''
+        tokenDecimals =
+          tokenInfo?.decimals ?? (challengeRequest.decimals as number | undefined) ?? 6
+      }
 
       {
         printResponseHeaders(challengeResponse)
@@ -276,42 +289,149 @@ cli
         }
       }
 
-      const mppx = Mppx.create({
-        methods: tempo({
-          account,
-          getClient: () => client,
-          deposit: (() => {
-            if (challenge.intent !== 'session') return undefined
-            const suggestedDeposit = (challenge.request as Record<string, unknown>)
-              .suggestedDeposit as string | undefined
-            const cliDeposit = options.deposit !== undefined ? String(options.deposit) : undefined
-            const resolved =
-              suggestedDeposit ?? cliDeposit ?? (isTestnet(client.chain!) ? '10' : undefined)
-            if (!resolved) {
-              console.error(
-                'Session payment requires a deposit. Use --deposit <amount> or connect to testnet.',
-              )
-              process.exit(1)
+      let credential: string
+      if (challenge.method === 'tempo') {
+        if (!account || !client) {
+          console.error('Tempo requires a configured account.')
+          process.exit(1)
+        }
+        const tempoOpts = parseOptions(
+          z.object({
+            channel: z.optional(z.coerce.string()),
+            deposit: z.optional(z.union([z.string(), z.number()])),
+          }),
+          methodOpts,
+        )
+        const mppx = Mppx.create({
+          methods: tempo({
+            account,
+            getClient: () => client!,
+            deposit: (() => {
+              if (challenge.intent !== 'session') return undefined
+              const suggestedDeposit = (challenge.request as Record<string, unknown>)
+                .suggestedDeposit as string | undefined
+              const cliDeposit =
+                tempoOpts.deposit !== undefined ? String(tempoOpts.deposit) : undefined
+              const resolved =
+                suggestedDeposit ?? cliDeposit ?? (isTestnet(client!.chain!) ? '10' : undefined)
+              if (!resolved) {
+                console.error(
+                  'Session payment requires a deposit. Use -M deposit=<amount> or connect to testnet.',
+                )
+                process.exit(1)
+              }
+              return resolved
+            })(),
+          }),
+          polyfill: false,
+        })
+        credential = await mppx.createCredential(
+          challengeResponse,
+          (() => {
+            if (!tempoOpts.channel) return undefined
+            const channelId = tempoOpts.channel
+            const saved = readChannelCumulative(channelId)
+            return {
+              channelId,
+              ...(saved !== undefined && { cumulativeAmountRaw: saved.toString() }),
             }
-            return resolved
           })(),
-        }),
-        polyfill: false,
-      })
-
-      const credential = await mppx.createCredential(
-        challengeResponse,
-        (() => {
-          if (!options.channel) return undefined
-          const idx = process.argv.indexOf('--channel')
-          const channelId = idx !== -1 ? process.argv[idx + 1]! : String(options.channel)
-          const saved = readChannelCumulative(channelId)
-          return {
-            channelId,
-            ...(saved !== undefined && { cumulativeAmountRaw: saved.toString() }),
-          }
-        })(),
-      )
+        )
+      } else if (challenge.method === 'stripe') {
+        const stripeOpts = parseOptions(
+          z.object({
+            paymentMethod: z.string(),
+          }),
+          methodOpts,
+        )
+        const stripeSecretKey = process.env.MPPX_STRIPE_SECRET_KEY
+        if (!stripeSecretKey) {
+          console.error(
+            '\nMPPX_STRIPE_SECRET_KEY environment variable is required for Stripe payments.',
+          )
+          process.exit(1)
+        }
+        if (!stripeSecretKey.startsWith('sk_test_')) {
+          console.error(
+            '\nStripe CLI payments are currently only supported in test mode (sk_test_... keys).',
+          )
+          process.exit(1)
+        }
+        const mppx = Mppx.create({
+          methods: [
+            stripe.charge({
+              paymentMethod: stripeOpts.paymentMethod,
+              createToken: async ({
+                paymentMethod,
+                amount,
+                currency,
+                networkId,
+                expiresAt,
+                metadata,
+              }) => {
+                const body = new URLSearchParams({
+                  payment_method: paymentMethod!,
+                  'usage_limits[currency]': currency,
+                  'usage_limits[max_amount]': amount,
+                  'usage_limits[expires_at]': expiresAt.toString(),
+                })
+                if (networkId) body.set('seller_details[network_id]', networkId)
+                if (metadata) {
+                  for (const [key, value] of Object.entries(metadata)) {
+                    body.set(`metadata[${key}]`, value)
+                  }
+                }
+                const sptUrl =
+                  process.env.MPPX_STRIPE_SPT_URL ??
+                  'https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens'
+                const sptHeaders = {
+                  Authorization: `Basic ${btoa(`${stripeSecretKey}:`)}`,
+                  'Content-Type': 'application/x-www-form-urlencoded',
+                }
+                let response = await globalThis.fetch(sptUrl, {
+                  method: 'POST',
+                  headers: sptHeaders,
+                  body,
+                })
+                if (!response.ok) {
+                  const errorBody = (await response.json()) as { error: { message: string } }
+                  if (
+                    (metadata || networkId) &&
+                    errorBody.error.message.includes('Received unknown parameter')
+                  ) {
+                    const fallbackBody = new URLSearchParams({
+                      payment_method: paymentMethod!,
+                      'usage_limits[currency]': currency,
+                      'usage_limits[max_amount]': amount,
+                      'usage_limits[expires_at]': expiresAt.toString(),
+                    })
+                    response = await globalThis.fetch(sptUrl, {
+                      method: 'POST',
+                      headers: sptHeaders,
+                      body: fallbackBody,
+                    })
+                    if (!response.ok) {
+                      const fallbackError = (await response.json()) as {
+                        error: { message: string }
+                      }
+                      throw new Error(`Failed to create SPT: ${fallbackError.error.message}`)
+                    }
+                  } else {
+                    throw new Error(`Failed to create SPT: ${errorBody.error.message}`)
+                  }
+                }
+                const { id } = (await response.json()) as { id: string }
+                return id
+              },
+            }),
+          ],
+          polyfill: false,
+        })
+        credential = await mppx.createCredential(challengeResponse)
+      } else {
+        console.error(`Unsupported payment method: ${challenge.method}`)
+        process.exit(1)
+      }
 
       const sessionMd = challenge.request.methodDetails as
         | { escrowContract?: string; chainId?: number }
@@ -324,18 +444,23 @@ cli
       if (challenge.intent === 'session') {
         const parsed = Credential.deserialize<SessionCredentialPayload>(credential)
         sessionChannelId = parsed.payload.channelId
-        sessionChainId = sessionMd?.chainId ?? client.chain?.id ?? 0
+        sessionChainId = sessionMd?.chainId ?? client?.chain?.id ?? 0
         sessionEscrowContract = sessionMd?.escrowContract as Address | undefined
         if ('cumulativeAmount' in parsed.payload && parsed.payload.cumulativeAmount)
           sessionCumulativeAmount = BigInt(parsed.payload.cumulativeAmount)
 
         if (parsed.payload.action === 'open') {
-          const depositRaw =
-            (challengeRequest.suggestedDeposit as string | undefined) ?? options.deposit
+          const depositRaw = challengeRequest.suggestedDeposit as string | undefined
           const depositDisplay = depositRaw
             ? ` ${pc.dim(`(deposit ${depositRaw} ${tokenSymbol})`)}`
             : ''
-          info(`\n${pc.dim(`Channel opened ${parsed.payload.channelId}`)}${depositDisplay}\n`)
+          const prefix = options.confirm ? '' : '\n'
+          info(
+            `${prefix}${pc.dim(`Channel opened ${parsed.payload.channelId}`)}${depositDisplay}\n`,
+          )
+        } else {
+          const prefix = options.confirm ? '' : '\n'
+          info(`${prefix}${pc.dim(`Channel reused ${parsed.payload.channelId}`)}\n`)
         }
       }
 
@@ -403,6 +528,15 @@ cli
                 explorerUrl
               ) {
                 rows.push([key, pc.link(`${explorerUrl}/tx/${value}`, value)])
+              } else if (
+                key === 'reference' &&
+                typeof value === 'string' &&
+                challenge.method === 'stripe' &&
+                value.startsWith('pi_')
+              ) {
+                const isTest = process.env.MPPX_STRIPE_SECRET_KEY?.startsWith('sk_test_')
+                const dashboardUrl = `https://dashboard.stripe.com${isTest ? '/test' : ''}/payments/${value}`
+                rows.push([key, pc.link(dashboardUrl, value)])
               } else rows.push([key, String(value)])
             }
             rows.sort(([a], [b]) => a.localeCompare(b))
@@ -430,7 +564,7 @@ cli
           const md = challenge.request.methodDetails as
             | { escrowContract?: string; chainId?: number }
             | undefined
-          const sessionChainId = md?.chainId ?? client.chain?.id ?? 0
+          const sessionChainId = md?.chainId ?? client?.chain?.id ?? 0
           const escrowContract = md?.escrowContract as Address | undefined
           let cumulativeAmount =
             sessionCred?.payload &&
@@ -493,8 +627,8 @@ cli
                   cumulativeAmount = cumulativeAmount > required ? cumulativeAmount : required
 
                   const signature = await signVoucher(
-                    client,
-                    account,
+                    client!,
+                    account!,
                     { channelId, cumulativeAmount },
                     escrowContract,
                     sessionChainId,
@@ -507,7 +641,7 @@ cli
                       cumulativeAmount: cumulativeAmount.toString(),
                       signature,
                     },
-                    source: `did:pkh:eip155:${sessionChainId}:${account.address}`,
+                    source: `did:pkh:eip155:${sessionChainId}:${account!.address}`,
                   })
                   await globalThis.fetch(url, {
                     method: 'POST',
@@ -586,8 +720,8 @@ cli
 
           if (channelId && escrowContract && sessionChainId) {
             const signature = await signVoucher(
-              client,
-              account,
+              client!,
+              account!,
               { channelId, cumulativeAmount },
               escrowContract,
               sessionChainId,
@@ -601,7 +735,7 @@ cli
             const closeCred = Credential.serialize({
               challenge,
               payload: closePayload,
-              source: `did:pkh:eip155:${sessionChainId}:${account.address}`,
+              source: `did:pkh:eip155:${sessionChainId}:${account!.address}`,
             })
             const closeRes = await globalThis.fetch(url, {
               method: 'POST',
@@ -649,8 +783,8 @@ cli
             info(`${pc.dim('Kept channel open.')}\n`)
           } else if (shouldClose) {
             const signature = await signVoucher(
-              client,
-              account,
+              client!,
+              account!,
               { channelId: sessionChannelId!, cumulativeAmount: sessionCumulativeAmount },
               sessionEscrowContract!,
               sessionChainId,
@@ -664,7 +798,7 @@ cli
             const closeCred = Credential.serialize({
               challenge,
               payload: closePayload,
-              source: `did:pkh:eip155:${sessionChainId}:${account.address}`,
+              source: `did:pkh:eip155:${sessionChainId}:${account!.address}`,
             })
             const closeRes = await globalThis.fetch(url, {
               ...fetchInit,
@@ -690,20 +824,21 @@ cli
                 closeTxHash && explorerUrl
                   ? ` ${pc.dim(pc.link(`${explorerUrl}/tx/${closeTxHash}`, closeTxHash))}`
                   : ''
+              const closePrefix = options.confirm ? '' : '\n'
               info(
-                `\n${pc.dim('Channel closed.')} ${pc.dim(`Spent ${fmtBalance(sessionCumulativeAmount, tokenSymbol, tokenDecimals)}.`)}${txInfo}\n`,
+                `${closePrefix}${pc.dim('Channel closed.')} ${pc.dim(`Spent ${fmtBalance(sessionCumulativeAmount, tokenSymbol, tokenDecimals)}.`)}${txInfo}\n`,
               )
             } else {
               const closeBody = await closeRes.text().catch(() => '')
               info(
-                `${pc.dim(pc.yellow('Channel close failed'))} ${pc.dim(`(${closeRes.status})`)}\n`,
+                `\n${pc.dim(pc.yellow('Channel close failed'))} ${pc.dim(`(${closeRes.status})`)}\n`,
               )
               info(
                 `${pc.dim(`  channelId:          ${sessionChannelId}`)}\n` +
                   `${pc.dim(`  cumulativeAmount:   ${sessionCumulativeAmount}`)}\n` +
                   `${pc.dim(`  escrowContract:     ${sessionEscrowContract}`)}\n` +
                   `${pc.dim(`  chainId:            ${sessionChainId}`)}\n` +
-                  `${pc.dim(`  account:            ${account.address}`)}\n` +
+                  `${pc.dim(`  account:            ${account?.address}`)}\n` +
                   `${pc.dim(`  response:           ${closeBody || '(empty)'}`)}\n`,
               )
             }
@@ -988,6 +1123,21 @@ try {
 
 /////////////////////////////////////////////////////////////////////////////////////////////////
 
+function parseMethodOpts(raw: string | string[] | undefined): Record<string, string> {
+  if (!raw) return {}
+  const list = Array.isArray(raw) ? raw : [raw]
+  const result: Record<string, string> = {}
+  for (const item of list) {
+    const idx = item.indexOf('=')
+    if (idx === -1) {
+      console.error(`Invalid method option format: ${item} (expected key=value)`)
+      process.exit(1)
+    }
+    result[item.slice(0, idx)] = item.slice(idx + 1)
+  }
+  return result
+}
+
 function parseOptions<const schema extends ZodMiniType>(
   schema: schema,
   rawOptions: unknown,
@@ -1285,8 +1435,8 @@ function chainName(chain: { id: number; name: string }) {
 }
 
 const pathUsd = '0x20c0000000000000000000000000000000000000' as Address
-const usdcE = '0x20C000000000000000000000b9537d11c60E8b50' as Address
-const mainnetTokens = [pathUsd, usdcE] as const
+const usdc = '0x20C000000000000000000000b9537d11c60E8b50' as Address
+const mainnetTokens = [pathUsd, usdc] as const
 const testnetTokens = [
   '0x20c0000000000000000000000000000000000000',
   '0x20c0000000000000000000000000000000000001',
@@ -1326,7 +1476,7 @@ async function fetchTokenInfo(
   ])
   const knownSymbols: Record<string, string> = {
     [pathUsd]: 'PathUSD',
-    [usdcE]: 'USDC.e',
+    [usdc]: 'USDC',
   }
   const symbol = knownSymbols[token] ?? metadata.symbol
   const decimals = 'decimals' in metadata ? metadata.decimals : 6

package/src/client/Transport.test.ts

@@ -60,7 +60,7 @@ describe('http', () => {
       expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
         {
           "expires": "2025-01-01T00:00:00.000Z",
-          "id": "i1474pQ7BtfAx76cLch6u8_AQkcp3akMkerEYrL5Rwo",
+          "id": "z8dUi61lViOj6cwh_ISb_5X8nBJF2OjTydcEap8wX0o",
           "intent": "charge",
           "method": "tempo",
           "realm": "api.example.com",
@@ -91,7 +91,7 @@ describe('http', () => {
       const headers = result.headers as Headers
 
       expect(headers.get('Authorization')).toMatchInlineSnapshot(
-        `"Payment eyJjaGFsbGVuZ2UiOnsiZXhwaXJlcyI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiIsImlkIjoiaTE0NzRwUTdCdGZBeDc2Y0xjaDZ1OF9BUWtjcDNha01rZXJFWXJMNVJ3byIsImludGVudCI6ImNoYXJnZSIsIm1ldGhvZCI6InRlbXBvIiwicmVhbG0iOiJhcGkuZXhhbXBsZS5jb20iLCJyZXF1ZXN0IjoiZXlKaGJXOTFiblFpT2lJeE1EQXdJaXdpWTNWeWNtVnVZM2tpT2lJd2VESXdZekF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREVpTENKbGVIQnBjbVZ6SWpvaU1qQXlOUzB3TVMwd01WUXdNRG93TURvd01DNHdNREJhSWl3aWNtVmphWEJwWlc1MElqb2lNSGczTkRKa016VkRZelkyTXpSRE1EVXpNamt5TldFellqZzBORUpqT1dVM05UazFaamhtUlRBd0luMCJ9LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4YWJjMTIzIiwidHlwZSI6InRyYW5zYWN0aW9uIn19"`,
+        `"Payment eyJjaGFsbGVuZ2UiOnsiZXhwaXJlcyI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiIsImlkIjoiejhkVWk2MWxWaU9qNmN3aF9JU2JfNVg4bkJKRjJPalR5ZGNFYXA4d1gwbyIsImludGVudCI6ImNoYXJnZSIsIm1ldGhvZCI6InRlbXBvIiwicmVhbG0iOiJhcGkuZXhhbXBsZS5jb20iLCJyZXF1ZXN0IjoiZXlKaGJXOTFiblFpT2lJeE1EQXdJaXdpWTNWeWNtVnVZM2tpT2lJd2VESXdZekF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREVpTENKbGVIQnBjbVZ6SWpvaU1qQXlOUzB3TVMwd01WUXdNRG93TURvd01DNHdNREJhSWl3aWNtVmphWEJwWlc1MElqb2lNSGczTkRKa016VkRZelkyTXpSRE1EVXpNamt5TldFellqZzBORUpqT1dVM05UazFaamhtUlRBd0luMCJ9LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4YWJjMTIzIiwidHlwZSI6InRyYW5zYWN0aW9uIn19"`,
       )
     })
 
@@ -182,7 +182,7 @@ describe('mcp', () => {
       expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
         {
           "expires": "2025-01-01T00:00:00.000Z",
-          "id": "i1474pQ7BtfAx76cLch6u8_AQkcp3akMkerEYrL5Rwo",
+          "id": "z8dUi61lViOj6cwh_ISb_5X8nBJF2OjTydcEap8wX0o",
           "intent": "charge",
           "method": "tempo",
           "realm": "api.example.com",
@@ -239,7 +239,7 @@ describe('mcp', () => {
               "org.paymentauth/credential": {
                 "challenge": {
                   "expires": "2025-01-01T00:00:00.000Z",
-                  "id": "i1474pQ7BtfAx76cLch6u8_AQkcp3akMkerEYrL5Rwo",
+                  "id": "z8dUi61lViOj6cwh_ISb_5X8nBJF2OjTydcEap8wX0o",
                   "intent": "charge",
                   "method": "tempo",
                   "realm": "api.example.com",

package/src/internal/env.test.ts

@@ -0,0 +1,42 @@
+import * as Env from './env.js'
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe('Env.get', () => {
+  test('returns default realm when no env vars are set', () => {
+    expect(Env.get('realm')).toBe('MPP Payment')
+  })
+
+  test('returns default secretKey when MPP_SECRET_KEY is not set', () => {
+    expect(Env.get('secretKey')).toBe('tmp')
+  })
+
+  test('returns MPP_SECRET_KEY when set', () => {
+    vi.stubEnv('MPP_SECRET_KEY', 'sk_live_abc123')
+    expect(Env.get('secretKey')).toBe('sk_live_abc123')
+  })
+
+  test('returns FLY_APP_NAME when set', () => {
+    vi.stubEnv('FLY_APP_NAME', 'my-fly-app')
+    expect(Env.get('realm')).toBe('my-fly-app')
+  })
+
+  test('FLY_APP_NAME takes precedence over HOST', () => {
+    vi.stubEnv('FLY_APP_NAME', 'fly-app')
+    vi.stubEnv('HOST', 'my-host')
+    expect(Env.get('realm')).toBe('fly-app')
+  })
+
+  test('HOST takes precedence over MPP_REALM', () => {
+    vi.stubEnv('HOST', 'my-host')
+    vi.stubEnv('MPP_REALM', 'custom-realm')
+    expect(Env.get('realm')).toBe('my-host')
+  })
+
+  test('falls through to later vars when earlier ones are unset', () => {
+    vi.stubEnv('MPP_REALM', 'fallback-realm')
+    expect(Env.get('realm')).toBe('fallback-realm')
+  })
+})

package/src/internal/types.ts

@@ -401,3 +401,14 @@ export type Distribute<U, R> = U extends infer member ? (response: member) => R
 
 /** @internal */
 export type Flatten<element> = element extends readonly (infer item)[] ? item : element
+
+/**
+ * @description Creates a type that extracts the values of T.
+ *
+ * @example
+ * ValueOf<{ a: string, b: number }>
+ * => string | number
+ *
+ * @internal
+ */
+export type ValueOf<T> = T[keyof T]

package/src/proxy/internal/Headers.ts

@@ -9,6 +9,7 @@ const hopByHopHeaders = new Set([
   'trailer',
 ])
 
+/** Strips hop-by-hop, auth, encoding, cookie, and forwarding headers from a request before proxying upstream. */
 export function scrub(headers: Headers): Headers {
   const scrubbed = new Headers()
 
@@ -28,6 +29,7 @@ export function scrub(headers: Headers): Headers {
   return scrubbed
 }
 
+/** Strips `content-encoding` and `content-length` from an upstream response so the proxy can re-stream it. */
 export function scrubResponse(response: Response): Response {
   const headers = new Headers(response.headers)
   headers.delete('content-encoding')

package/src/proxy/internal/Route.ts

@@ -1,5 +1,6 @@
 const httpMethods = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'])
 
+/** Extracts the pathname from a URL, stripping the optional `basePath` prefix. Returns `null` if the path doesn't match. */
 export function pathname(url: URL, basePath?: string): string | null {
   let pathname = url.pathname
   if (basePath) {
@@ -10,6 +11,7 @@ export function pathname(url: URL, basePath?: string): string | null {
   return pathname
 }
 
+/** Splits a `/{serviceId}/rest/of/path` pathname into its service ID and upstream path. */
 export function parse(pathname: string): { serviceId: string; upstreamPath: string } | null {
   const segments = pathname.split('/').filter(Boolean)
   const serviceId = segments[0]
@@ -19,6 +21,7 @@ export function parse(pathname: string): { serviceId: string; upstreamPath: stri
   return { serviceId, upstreamPath }
 }
 
+/** Finds the first route matching both the HTTP method and path (via `URLPattern`). */
 export function match(
   routes: Record<string, unknown>,
   method: string,
@@ -33,6 +36,7 @@ export function match(
   return null
 }
 
+/** Finds the first route matching just the path, ignoring the HTTP method. Used for management POST fallback. */
 export function matchPath(
   routes: Record<string, unknown>,
   path: string,