mppx 0.3.3 → 0.3.5

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/env.ts

@@ -42,12 +42,12 @@ export function get(key: keyof typeof variables): string {
 /** Reads a single environment variable, probing available runtime APIs. */
 function read(name: string): string | undefined {
   try {
-    if (typeof process !== 'undefined' && process?.env) return process.env[name]
+    if (typeof process !== 'undefined' && process?.env) return process.env[name] || undefined
   } catch {}
 
   try {
     const deno = (globalThis as any).Deno
-    if (deno?.env?.get) return deno.env.get(name)
+    if (deno?.env?.get) return deno.env.get(name) || undefined
   } catch {}
 
   return undefined

package/src/middlewares/express.test.ts

@@ -6,7 +6,7 @@ import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow } from '~test/tempo/stream.js'
+import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: express.Express) {

package/src/middlewares/hono.test.ts

@@ -7,7 +7,7 @@ import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow } from '~test/tempo/stream.js'
+import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: Hono) {

package/src/middlewares/nextjs.test.ts

@@ -6,7 +6,7 @@ import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow } from '~test/tempo/stream.js'
+import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(handler: (request: Request) => Promise<Response> | Response) {

package/src/server/Mppx.test.ts

@@ -344,3 +344,176 @@ describe('receipt handling', () => {
     expect(result.status).toBe(200)
   })
 })
+
+describe('withReceipt', () => {
+  const mockCharge = Method.from({
+    name: 'mock',
+    intent: 'charge',
+    schema: {
+      credential: {
+        payload: z.object({ token: z.string() }),
+      },
+      request: z.object({
+        amount: z.string(),
+        currency: z.string(),
+        decimals: z.number(),
+        recipient: z.string(),
+      }),
+    },
+  })
+
+  function mockReceipt() {
+    return {
+      method: 'mock',
+      reference: 'tx-ref',
+      status: 'success' as const,
+      timestamp: new Date().toISOString(),
+    }
+  }
+
+  test('attaches Payment-Receipt header to response', async () => {
+    const mockMethod = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethod], realm, secretKey })
+    const handle = handler.charge({
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error()
+
+    const response = result.withReceipt(Response.json({ data: 'ok' }))
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+    const body = await response.json()
+    expect(body).toEqual({ data: 'ok' })
+  })
+
+  test('throws when called without response arg and no management response', async () => {
+    const mockMethod = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethod], realm, secretKey })
+    const handle = handler.charge({
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error()
+
+    expect(() => result.withReceipt()).toThrow('withReceipt() requires a response argument')
+  })
+
+  test('returns management response when respond hook returns Response', async () => {
+    const mockMethodWithRespond = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+      respond() {
+        return new Response(null, { status: 204 })
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethodWithRespond], realm, secretKey })
+    const handle = handler.charge({
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error()
+
+    const response = result.withReceipt()
+    expect(response.status).toBe(204)
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+  })
+
+  test('toNodeListener sets Payment-Receipt header on 200', async () => {
+    const mockMethod = Method.toServer(mockCharge, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [mockMethod], realm, secretKey })
+
+    const server = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        handler.charge({
+          amount: '1000',
+          currency: '0x0000000000000000000000000000000000000001',
+          decimals: 6,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: '0x0000000000000000000000000000000000000002',
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const firstResponse = await fetch(server.url)
+    expect(firstResponse.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(firstResponse)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const response = await fetch(server.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+
+    server.close()
+  })
+})

package/src/server/Mppx.ts

@@ -126,14 +126,14 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
   const { defaults, method, realm, respond, secretKey, transport, verify } = parameters
 
   return (options) => {
-    const meta = {
+    const methodMeta = {
       ...method,
       ...defaults,
       ...options,
     }
     return Object.assign(
       async (input: Transport.InputOf): Promise<MethodFn.Response> => {
-        const { description, ...rest } = options
+        const { description, meta, ...rest } = options
         const expires = 'expires' in options ? (options.expires as string | undefined) : undefined
 
         // Merge defaults with per-request options
@@ -164,6 +164,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         const challenge = Challenge.fromMethod(method, {
           description,
           expires,
+          meta,
           realm,
           request,
           secretKey,
@@ -261,7 +262,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           },
         }
       },
-      { _internal: meta },
+      { _internal: methodMeta },
     )
   }
 }
@@ -309,6 +310,8 @@ declare namespace MethodFn {
     description?: string | undefined
     /** Optional challenge expiration timestamp (ISO 8601). */
     expires?: string | undefined
+    /** Optional server-defined correlation data (serialized as `opaque` in the request). Flat string-to-string map; clients MUST NOT modify. */
+    meta?: Record<string, string> | undefined
   } & Method.WithDefaults<z.input<method['schema']['request']>, defaults>
 
   export type Response<transport extends Transport.AnyTransport = Transport.Http> =

package/src/server/Transport.test.ts

@@ -43,7 +43,7 @@ describe('http', () => {
         {
           "challenge": {
             "expires": "2025-01-01T00:00:00.000Z",
-            "id": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+            "id": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
             "intent": "charge",
             "method": "tempo",
             "realm": "api.example.com",
@@ -93,7 +93,7 @@ describe('http', () => {
         {
           "headers": {
             "cache-control": "no-store",
-            "www-authenticate": "Payment id="N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAwMDAwIiwiY3VycmVuY3kiOiIweDIwYzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEiLCJleHBpcmVzIjoiMjAyNS0wMS0wMVQwMDowMDowMC4wMDBaIiwicmVjaXBpZW50IjoiMHg3NDJkMzVDYzY2MzRDMDUzMjkyNWEzYjg0NEJjOWU3NTk1ZjhmRTAwIn0", expires="2025-01-01T00:00:00.000Z"",
+            "www-authenticate": "Payment id="4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAwMDAwIiwiY3VycmVuY3kiOiIweDIwYzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEiLCJleHBpcmVzIjoiMjAyNS0wMS0wMVQwMDowMDowMC4wMDBaIiwicmVjaXBpZW50IjoiMHg3NDJkMzVDYzY2MzRDMDUzMjkyNWEzYjg0NEJjOWU3NTk1ZjhmRTAwIn0", expires="2025-01-01T00:00:00.000Z"",
           },
           "status": 402,
         }
@@ -124,7 +124,7 @@ describe('http', () => {
 
       expect(response.status).toBe(410)
       const body = await response.json()
-      expect(body.type).toBe('https://paymentauth.org/problems/stream/channel-finalized')
+      expect(body.type).toBe('https://paymentauth.org/problems/session/channel-finalized')
       expect(body.status).toBe(410)
     })
   })
@@ -183,7 +183,7 @@ describe('mcp', () => {
         {
           "challenge": {
             "expires": "2025-01-01T00:00:00.000Z",
-            "id": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+            "id": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
             "intent": "charge",
             "method": "tempo",
             "realm": "api.example.com",
@@ -221,7 +221,7 @@ describe('mcp', () => {
               "challenges": [
                 {
                   "expires": "2025-01-01T00:00:00.000Z",
-                  "id": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+                  "id": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
                   "intent": "charge",
                   "method": "tempo",
                   "realm": "api.example.com",
@@ -262,7 +262,7 @@ describe('mcp', () => {
           "result": {
             "_meta": {
               "org.paymentauth/receipt": {
-                "challengeId": "N_Q_IM9V5tO3JMcOTniz7anX81m7MdEp4aLW9q5KNK0",
+                "challengeId": "4XKyFaMO73Ypu-wOofzu3F8pRIt8vb7zxmWB2GgHAsE",
                 "method": "tempo",
                 "reference": "0xtxhash",
                 "status": "success",

package/src/tempo/client/ChannelOps.test.ts

@@ -3,11 +3,11 @@ import { type Address, createClient } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow, openChannel } from '~test/tempo/stream.js'
+import { deployEscrow, openChannel } from '~test/tempo/session.js'
 import { accounts, asset, chain, client, fundAccount, http } from '~test/tempo/viem.js'
 import type { Challenge } from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
-import { verifyVoucher } from '../stream/Voucher.js'
+import { verifyVoucher } from '../session/Voucher.js'
 import {
   createClosePayload,
   createOpenPayload,

package/src/tempo/client/ChannelOps.ts

@@ -18,10 +18,10 @@ import { Abis } from 'viem/tempo'
 import type { Challenge } from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
 import * as defaults from '../internal/defaults.js'
-import { escrowAbi, getOnChainChannel } from '../stream/Chain.js'
-import * as Channel from '../stream/Channel.js'
-import type { StreamCredentialPayload } from '../stream/Types.js'
-import { signVoucher } from '../stream/Voucher.js'
+import { escrowAbi, getOnChainChannel } from '../session/Chain.js'
+import * as Channel from '../session/Channel.js'
+import type { SessionCredentialPayload } from '../session/Types.js'
+import { signVoucher } from '../session/Voucher.js'
 
 export type ChannelEntry = {
   channelId: Hex.Hex
@@ -57,7 +57,7 @@ export function resolveEscrow(
 
 export function serializeCredential(
   challenge: Challenge,
-  payload: StreamCredentialPayload,
+  payload: SessionCredentialPayload,
   chainId: number,
   account: viem_Account,
 ): string {
@@ -76,7 +76,7 @@ export async function createVoucherPayload(
   escrowContract: Address,
   chainId: number,
   authorizedSigner?: Address | undefined,
-): Promise<StreamCredentialPayload> {
+): Promise<SessionCredentialPayload> {
   const signature = await signVoucher(
     client,
     account,
@@ -101,7 +101,7 @@ export async function createClosePayload(
   escrowContract: Address,
   chainId: number,
   authorizedSigner?: Address | undefined,
-): Promise<StreamCredentialPayload> {
+): Promise<SessionCredentialPayload> {
   const signature = await signVoucher(
     client,
     account,
@@ -131,7 +131,7 @@ export async function createOpenPayload(
     chainId: number
     feePayer?: boolean | undefined
   },
-): Promise<{ entry: ChannelEntry; payload: StreamCredentialPayload }> {
+): Promise<{ entry: ChannelEntry; payload: SessionCredentialPayload }> {
   const { escrowContract, payee, currency, deposit, initialAmount, chainId, feePayer } = options
   const authorizedSigner = options.authorizedSigner ?? account.address
 

package/src/tempo/client/Session.test.ts

@@ -2,15 +2,15 @@ import { type Address, createClient, type Hex, http } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow, openChannel } from '~test/tempo/stream.js'
+import { deployEscrow, openChannel } from '~test/tempo/session.js'
 import { accounts, asset, chain, client, fundAccount } from '~test/tempo/viem.js'
 import * as Challenge from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
-import type { StreamCredentialPayload } from '../stream/Types.js'
+import type { SessionCredentialPayload } from '../session/Types.js'
 import { session } from './Session.js'
 
 function deserializePayload(result: string) {
-  const cred = Credential.deserialize<StreamCredentialPayload>(result)
+  const cred = Credential.deserialize<SessionCredentialPayload>(result)
   return cred
 }
 

package/src/tempo/client/Session.ts

@@ -8,8 +8,8 @@ import * as Client from '../../viem/Client.js'
 import * as z from '../../zod.js'
 import * as defaults from '../internal/defaults.js'
 import * as Methods from '../Methods.js'
-import type { StreamCredentialPayload } from '../stream/Types.js'
-import { signVoucher } from '../stream/Voucher.js'
+import type { SessionCredentialPayload } from '../session/Types.js'
+import { signVoucher } from '../session/Voucher.js'
 import {
   type ChannelEntry,
   createOpenPayload,
@@ -19,7 +19,7 @@ import {
   tryRecoverChannel,
 } from './ChannelOps.js'
 
-export const streamContextSchema = z.object({
+export const sessionContextSchema = z.object({
   account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
   action: z.optional(z.enum(['open', 'topUp', 'voucher', 'close'])),
   channelId: z.optional(z.string()),
@@ -32,7 +32,7 @@ export const streamContextSchema = z.object({
   depositRaw: z.optional(z.string()),
 })
 
-export type StreamContext = z.infer<typeof streamContextSchema>
+export type SessionContext = z.infer<typeof sessionContextSchema>
 
 /**
  * Creates a session payment method for use with `Mppx.create()`.
@@ -112,7 +112,7 @@ export function session(parameters: session.Parameters = {}) {
   async function autoManageCredential(
     challenge: Challenge.Challenge,
     account: viem_Account,
-    context?: StreamContext,
+    context?: SessionContext,
   ): Promise<string> {
     const md = challenge.request.methodDetails as
       | { chainId?: number; escrowContract?: string; channelId?: string; feePayer?: boolean }
@@ -174,7 +174,7 @@ export function session(parameters: session.Parameters = {}) {
       }
     }
 
-    let payload: StreamCredentialPayload
+    let payload: SessionCredentialPayload
 
     if (entry?.opened) {
       entry.cumulativeAmount += amount
@@ -212,7 +212,7 @@ export function session(parameters: session.Parameters = {}) {
   async function manualCredential(
     challenge: Challenge.Challenge,
     account: viem_Account,
-    context: StreamContext,
+    context: SessionContext,
   ): Promise<string> {
     const md = challenge.request.methodDetails as
       | { chainId?: number; escrowContract?: string; channelId?: string }
@@ -242,7 +242,7 @@ export function session(parameters: session.Parameters = {}) {
     const escrowContract = resolveEscrowCached(challenge, chainId, channelId)
     escrowContractMap.set(channelId, escrowContract)
 
-    let payload: StreamCredentialPayload
+    let payload: SessionCredentialPayload
 
     switch (action) {
       case 'open': {
@@ -341,7 +341,7 @@ export function session(parameters: session.Parameters = {}) {
   }
 
   return Method.toClient(Methods.session, {
-    context: streamContextSchema,
+    context: sessionContextSchema,
 
     async createCredential({ challenge, context }) {
       const chainId = challenge.request.methodDetails?.chainId ?? 0

package/src/tempo/client/SessionManager.test.ts

@@ -1,8 +1,8 @@
 import type { Hex } from 'viem'
 import { describe, expect, test, vi } from 'vitest'
 import * as Challenge from '../../Challenge.js'
-import { formatNeedVoucherEvent, parseEvent } from '../stream/Sse.js'
-import type { NeedVoucherEvent, StreamReceipt } from '../stream/Types.js'
+import { formatNeedVoucherEvent, parseEvent } from '../session/Sse.js'
+import type { NeedVoucherEvent, SessionReceipt } from '../session/Types.js'
 import { sessionManager } from './SessionManager.js'
 
 const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
@@ -139,7 +139,7 @@ describe('Session', () => {
           acceptedCumulative: '2000000',
           spent: '2000000',
           units: 2,
-        } satisfies StreamReceipt)}\n\n`,
+        } satisfies SessionReceipt)}\n\n`,
       ]
 
       let callCount = 0

package/src/tempo/client/SessionManager.ts

@@ -4,9 +4,9 @@ import type * as Challenge from '../../Challenge.js'
 import * as Fetch from '../../client/internal/Fetch.js'
 import type * as Account from '../../viem/Account.js'
 import type * as Client from '../../viem/Client.js'
-import { deserializeStreamReceipt } from '../stream/Receipt.js'
-import { parseEvent } from '../stream/Sse.js'
-import type { StreamReceipt } from '../stream/Types.js'
+import { deserializeSessionReceipt } from '../session/Receipt.js'
+import { parseEvent } from '../session/Sse.js'
+import type { SessionReceipt } from '../session/Types.js'
 import type { ChannelEntry } from './ChannelOps.js'
 import { session as sessionPlugin } from './Session.js'
 
@@ -20,15 +20,15 @@ export type SessionManager = {
   sse(
     input: RequestInfo | URL,
     init?: RequestInit & {
-      onReceipt?: ((receipt: StreamReceipt) => void) | undefined
+      onReceipt?: ((receipt: SessionReceipt) => void) | undefined
       signal?: AbortSignal | undefined
     },
   ): Promise<AsyncIterable<string>>
-  close(): Promise<StreamReceipt | undefined>
+  close(): Promise<SessionReceipt | undefined>
 }
 
 export type PaymentResponse = Response & {
-  receipt: StreamReceipt | null
+  receipt: SessionReceipt | null
   challenge: Challenge.Challenge | null
   channelId: Hex.Hex | null
   cumulative: bigint
@@ -83,7 +83,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
 
   function toPaymentResponse(response: Response): PaymentResponse {
     const receiptHeader = response.headers.get('Payment-Receipt')
-    const receipt = receiptHeader ? deserializeStreamReceipt(receiptHeader) : null
+    const receipt = receiptHeader ? deserializeSessionReceipt(receiptHeader) : null
     return Object.assign(response, {
       receipt,
       challenge: lastChallenge,
@@ -241,14 +241,14 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         },
       })
 
-      let receipt: StreamReceipt | undefined
+      let receipt: SessionReceipt | undefined
       if (lastUrl) {
         const response = await fetchFn(lastUrl, {
           method: 'POST',
           headers: { Authorization: credential },
         })
         const receiptHeader = response.headers.get('Payment-Receipt')
-        if (receiptHeader) receipt = deserializeStreamReceipt(receiptHeader)
+        if (receiptHeader) receipt = deserializeSessionReceipt(receiptHeader)
       }
 
       return receipt

package/src/tempo/index.ts

@@ -1,2 +1,2 @@
 export * as Methods from './Methods.js'
-export * as Stream from './stream/index.js'
+export * as Session from './session/index.js'

package/src/tempo/server/Charge.ts

@@ -67,7 +67,7 @@ export function charge<const parameters extends charge.Parameters>(
       recipient,
     } as unknown as Defaults,
 
-    // TODO: dedupe `{charge,stream}.request`
+    // TODO: dedupe `{charge,session}.request`
     async request({ credential, request }) {
       const chainId = await (async () => {
         if (request.chainId) return request.chainId