mppx 0.3.4 → 0.3.6

package/src/Challenge.ts

@@ -27,6 +27,8 @@ export const Schema = z.object({
   intent: z.string(),
   /** Payment method (e.g., "tempo", "stripe"). */
   method: z.string(),
+  /** Optional server-defined correlation data. Flat string-to-string map; clients MUST NOT modify. */
+  opaque: z.optional(z.record(z.string(), z.string())),
   /** Server realm (e.g., hostname). */
   realm: z.string(),
   /** Method-specific request data. */
@@ -111,11 +113,20 @@ export function from<
   const methods extends readonly Method.Method[] | undefined = undefined,
 >(parameters: parameters, options?: from.Options<methods>): from.ReturnType<parameters, methods> {
   void options
-  const { description, digest, method: methodName, intent, realm, request, secretKey } = parameters
+  const {
+    description,
+    digest,
+    meta,
+    method: methodName,
+    intent,
+    realm,
+    request,
+    secretKey,
+  } = parameters
 
   const expires = (parameters.expires ?? request.expires) as string
   const id = secretKey
-    ? computeId({ ...parameters, expires }, { secretKey })
+    ? computeId({ ...parameters, expires, ...(meta && { opaque: meta }) }, { secretKey })
     : (parameters as { id: string }).id
 
   return Schema.parse({
@@ -127,6 +138,7 @@ export function from<
     ...(description && { description }),
     ...(digest && { digest }),
     ...(expires && { expires }),
+    ...(meta && { opaque: meta }),
   }) as from.ReturnType<parameters, methods>
 }
 
@@ -153,6 +165,8 @@ export declare namespace from {
     expires?: string | undefined
     /** Intent type (e.g., "charge", "session"). */
     intent: string
+    /** Optional server-defined correlation data (serialized as `opaque` on the challenge). Flat string-to-string map; clients MUST NOT modify. */
+    meta?: Record<string, string> | undefined
     /** Payment method (e.g., "tempo", "stripe"). */
     method: string
     /** Server realm (e.g., hostname). */
@@ -206,7 +220,7 @@ export function fromMethod<const method extends Method.Method>(
   parameters: fromMethod.Parameters<method>,
 ): fromMethod.ReturnType<method> {
   const { name: methodName, intent } = method
-  const { description, digest, expires, id, realm, secretKey } = parameters
+  const { description, digest, expires, id, meta, realm, secretKey } = parameters
 
   const request = PaymentRequest.fromMethod(method, parameters.request)
 
@@ -219,6 +233,7 @@ export function fromMethod<const method extends Method.Method>(
     description,
     digest,
     expires,
+    meta,
   } as from.Parameters) as fromMethod.ReturnType<method>
 }
 
@@ -239,6 +254,8 @@ export declare namespace fromMethod {
     digest?: string | undefined
     /** Optional expiration timestamp (ISO 8601). */
     expires?: string | undefined
+    /** Optional server-defined correlation data (serialized as `opaque` on the challenge). Flat string-to-string map; clients MUST NOT modify. */
+    meta?: Record<string, string> | undefined
     /** Server realm (e.g., hostname). */
     realm: string
     /** Method-specific request data. */
@@ -274,6 +291,8 @@ export function serialize(challenge: Challenge): string {
   if (challenge.description !== undefined) parts.push(`description="${challenge.description}"`)
   if (challenge.digest !== undefined) parts.push(`digest="${challenge.digest}"`)
   if (challenge.expires !== undefined) parts.push(`expires="${challenge.expires}"`)
+  if (challenge.opaque !== undefined)
+    parts.push(`opaque="${PaymentRequest.serialize(challenge.opaque)}"`)
 
   return `Payment ${parts.join(', ')}`
 }
@@ -314,13 +333,14 @@ export function deserialize<const methods extends readonly Method.Method[] | und
     }
   }
 
-  const { request, ...rest } = result
+  const { request, opaque, ...rest } = result
   if (!request) throw new Error('Missing request parameter.')
 
   return from(
     {
       ...rest,
       request: PaymentRequest.deserialize(request),
+      ...(opaque && { meta: PaymentRequest.deserialize(opaque) as Record<string, string> }),
     } as from.Parameters,
     options,
   )
@@ -404,8 +424,17 @@ export declare namespace verify {
   }
 }
 
+/** Alias for `challenge.opaque`. Extracts server-defined correlation data from a challenge. */
+export function meta(challenge: Challenge): Record<string, string> | undefined {
+  return challenge.opaque
+}
+
 /** @internal Computes HMAC-SHA256 challenge ID from parameters. */
 function computeId(challenge: Omit<Challenge, 'id'>, options: { secretKey: string }): string {
+  // Each field occupies a fixed positional slot joined by '|'. Optional fields
+  // use an empty string when absent so the slot count is stable — this avoids
+  // ambiguity between e.g. (expires set, no digest) vs (no expires, digest set)
+  // and means adding a new optional field changes all HMACs exactly once.
   const input = [
     challenge.realm,
     challenge.method,
@@ -413,6 +442,7 @@ function computeId(challenge: Omit<Challenge, 'id'>, options: { secretKey: strin
     PaymentRequest.serialize(challenge.request),
     challenge.expires ?? '',
     challenge.digest ?? '',
+    challenge.opaque ? PaymentRequest.serialize(challenge.opaque) : '',
   ].join('|')
 
   const key = Bytes.fromString(options.secretKey)

package/src/Store.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'vitest'
+import * as Store from './Store.js'
+
+const nested = {
+  name: 'alice',
+  scores: [1, 2, 3],
+  meta: { active: true, tags: ['a', 'b'] },
+}
+
+function fakeKv(): Store.cloudflare.Parameters {
+  const map = new Map<string, string>()
+  return {
+    async get(key) {
+      return map.get(key) ?? null
+    },
+    async put(key, value) {
+      map.set(key, value)
+    },
+    async delete(key) {
+      map.delete(key)
+    },
+  }
+}
+
+describe.each([
+  { label: 'memory', create: () => Store.memory() },
+  { label: 'cloudflare', create: () => Store.cloudflare(fakeKv()) },
+  {
+    label: 'upstash',
+    create: () => {
+      const kv = fakeKv()
+      return Store.upstash({
+        get: kv.get,
+        set: (key, value) => kv.put(key, value as string),
+        del: (key) => kv.delete(key),
+      })
+    },
+  },
+])('$label', ({ create }) => {
+  test('roundtrip', async () => {
+    const store = create()
+    await store.put('k', nested)
+    expect(await store.get('k')).toEqual(nested)
+  })
+
+  test('get missing key returns null', async () => {
+    const store = create()
+    expect(await store.get('missing')).toBeNull()
+  })
+
+  test('delete removes key', async () => {
+    const store = create()
+    await store.put('k', 'value')
+    await store.delete('k')
+    expect(await store.get('k')).toBeNull()
+  })
+
+  test('put overwrites existing value', async () => {
+    const store = create()
+    await store.put('k', 'first')
+    await store.put('k', 'second')
+    expect(await store.get('k')).toBe('second')
+  })
+})
+
+describe('json roundtrip behavior', () => {
+  test('memory json-roundtrips nested objects', async () => {
+    const store = Store.memory()
+    const value = { a: [1, { b: 'c' }], d: null }
+    await store.put('k', value)
+    expect(await store.get('k')).toEqual(value)
+  })
+
+  test('cloudflare json-roundtrips nested objects', async () => {
+    const store = Store.cloudflare(fakeKv())
+    const value = { a: [1, { b: 'c' }], d: null }
+    await store.put('k', value)
+    expect(await store.get('k')).toEqual(value)
+  })
+
+  test('upstash passes values through without json serialization', async () => {
+    const kv = fakeKv()
+    const store = Store.upstash({
+      get: kv.get,
+      set: (key, value) => kv.put(key, value as string),
+      del: (key) => kv.delete(key),
+    })
+    const value = { a: 1 }
+    await store.put('k', value)
+    // upstash store does not JSON-serialize; the fake map holds the original reference
+    expect(await kv.get('k')).toBe(value)
+  })
+})

package/src/cli.test.ts

@@ -11,6 +11,7 @@ import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 import * as Store from './Store.js'
 import * as Mppx_server from './server/Mppx.js'
 import { toNodeListener } from './server/Mppx.js'
+import { stripe as stripe_server } from './stripe/server/Methods.js'
 import { tempo } from './tempo/server/Methods.js'
 
 const cliPath = path.resolve(import.meta.dirname, 'cli.ts')
@@ -44,12 +45,12 @@ function runRaw(
 
 function runAsync(
   args: string[],
-  options?: { input?: string },
+  options?: { input?: string; env?: NodeJS.ProcessEnv },
 ): Promise<{ stdout: string; stderr: string }> {
   return new Promise((resolve, reject) => {
     const child = spawn('node', ['--import', 'tsx', cliPath, ...args], {
       cwd,
-      env,
+      env: options?.env ?? env,
       stdio: ['pipe', 'pipe', 'pipe'],
     })
 
@@ -126,19 +127,36 @@ describe('basic charge (examples/basic)', () => {
     }
   })
 
-  test('error: no account found', { timeout: 60_000 }, () => {
-    const result = spawnSync(
-      'node',
-      ['--import', 'tsx', cliPath, 'http://localhost:1', '--account', 'nonexistent-account'],
-      {
-        encoding: 'utf8',
-        cwd,
-        timeout: 60_000,
+  test('error: no account found', { timeout: 60_000 }, async () => {
+    const server = Mppx_server.create({
+      methods: [tempo.charge({ getClient: () => client })],
+      realm: 'cli-test-no-account',
+      secretKey: 'cli-test-secret',
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('paid')
+    })
+
+    try {
+      const result = await runAsync([httpServer.url, '--account', 'nonexistent-account'], {
+        input: '',
         env: { ...process.env, NODE_NO_WARNINGS: '1' },
-      },
-    )
-    expect(result.status).not.toBe(0)
-    expect(result.stdout).toContain('Account "nonexistent-account" not found')
+      }).catch((err) => err as Error)
+      expect(result).toBeInstanceOf(Error)
+      expect((result as Error).message).toContain('Account "nonexistent-account" not found')
+    } finally {
+      httpServer.close()
+    }
   })
 })
 
@@ -179,7 +197,7 @@ describe('session multi-fetch (examples/session/multi-fetch)', () => {
 
     try {
       const { stdout } = await runAsync(
-        [httpServer.url, '--rpc-url', rpcUrl, '-s', '--deposit', '10'],
+        [httpServer.url, '--rpc-url', rpcUrl, '-s', '-M', 'deposit=10'],
         { input: '' },
       )
       expect(stdout).toContain('scraped-content')
@@ -228,7 +246,7 @@ describe('session multi-fetch (examples/session/multi-fetch)', () => {
       try {
         // First request: open a channel, answer "y" to proceed, "n" to close channel
         const first = await runAsync(
-          [httpServer.url, '--rpc-url', rpcUrl, '--confirm', '--deposit', '10'],
+          [httpServer.url, '--rpc-url', rpcUrl, '--confirm', '-M', 'deposit=10'],
           { input: 'y\nn\n' },
         )
         expect(first.stdout).toContain('scraped-content')
@@ -238,9 +256,18 @@ describe('session multi-fetch (examples/session/multi-fetch)', () => {
         expect(match).toBeTruthy()
         const channelId = match![1]!
 
-        // Second request: reuse the channel via --channel
+        // Second request: reuse the channel via -M channel=<id>
         const second = await runAsync(
-          [httpServer.url, '--rpc-url', rpcUrl, '-s', '--channel', channelId, '--deposit', '10'],
+          [
+            httpServer.url,
+            '--rpc-url',
+            rpcUrl,
+            '-s',
+            '-M',
+            `channel=${channelId}`,
+            '-M',
+            'deposit=10',
+          ],
           { input: '' },
         )
         expect(second.stdout).toContain('scraped-content')
@@ -266,6 +293,53 @@ describe('session multi-fetch (examples/session/multi-fetch)', () => {
   })
 })
 
+describe.skipIf(!process.env.VITE_STRIPE_SECRET_KEY)('stripe charge (integration)', () => {
+  test('happy path: makes Stripe payment via real API', { timeout: 120_000 }, async () => {
+    const stripeSecretKey = process.env.VITE_STRIPE_SECRET_KEY!
+
+    const server = Mppx_server.create({
+      methods: [
+        stripe_server.charge({
+          secretKey: stripeSecretKey,
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm: 'cli-test-stripe',
+      secretKey: 'cli-test-secret',
+    })
+
+    const httpServer = await Http.createServer(async (req, res) => {
+      const result = await toNodeListener(
+        server.charge({
+          amount: '1',
+          currency: 'usd',
+          decimals: 2,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('paid')
+    })
+
+    try {
+      const { stdout } = await runAsync(
+        [httpServer.url, '-M', 'paymentMethod=pm_card_visa', '-s'],
+        {
+          input: '',
+          env: {
+            ...env,
+            MPPX_STRIPE_SECRET_KEY: stripeSecretKey,
+            MPPX_PRIVATE_KEY: undefined as unknown as string,
+          },
+        },
+      )
+      expect(stdout).toContain('paid')
+    } finally {
+      httpServer.close()
+    }
+  })
+})
+
 describe('session sse (examples/session/sse)', () => {
   test('streams SSE tokens to stdout', { timeout: 120_000 }, async () => {
     await fundAccount({ address: testAccount.address, token: Addresses.pathUsd })
@@ -313,7 +387,7 @@ describe('session sse (examples/session/sse)', () => {
     })
 
     try {
-      const { stdout } = await runAsync([httpServer.url, '--rpc-url', rpcUrl, '--deposit', '10'], {
+      const { stdout } = await runAsync([httpServer.url, '--rpc-url', rpcUrl, '-M', 'deposit=10'], {
         input: '',
       })
       expect(stdout.trim()).toBe('Hello world!')
@@ -337,6 +411,129 @@ describe('session sse (examples/session/sse)', () => {
   })
 })
 
+describe('stripe charge', () => {
+  test('happy path: makes Stripe payment and receives response', { timeout: 60_000 }, async () => {
+    const mockStripeClient = {
+      paymentIntents: { create: async () => ({ id: 'pi_mock_cli_123', status: 'succeeded' }) },
+    }
+
+    const server = Mppx_server.create({
+      methods: [
+        stripe_server.charge({
+          client: mockStripeClient,
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm: 'cli-test-stripe',
+      secretKey: 'cli-test-secret',
+    })
+
+    const sptServer = await Http.createServer(async (_req, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ id: 'spt_mock_cli_test' }))
+    })
+
+    const appServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('paid')
+    })
+
+    try {
+      const { stdout } = await runAsync([appServer.url, '-s', '-M', 'paymentMethod=pm_card_visa'], {
+        input: '',
+        env: {
+          ...process.env,
+          NODE_NO_WARNINGS: '1',
+          MPPX_STRIPE_SECRET_KEY: 'sk_test_mock',
+          MPPX_STRIPE_SPT_URL: sptServer.url,
+        },
+      })
+      expect(stdout).toContain('paid')
+    } finally {
+      appServer.close()
+      sptServer.close()
+    }
+  })
+
+  test('error: missing MPPX_STRIPE_SECRET_KEY', { timeout: 60_000 }, async () => {
+    const server = Mppx_server.create({
+      methods: [
+        stripe_server.charge({
+          secretKey: 'sk_test_mock',
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm: 'cli-test-stripe-nokey',
+      secretKey: 'cli-test-secret',
+    })
+
+    const appServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('paid')
+    })
+
+    try {
+      const result = await runAsync([appServer.url, '-s', '-M', 'paymentMethod=pm_card_visa'], {
+        input: '',
+        env: {
+          ...process.env,
+          NODE_NO_WARNINGS: '1',
+          MPPX_STRIPE_SECRET_KEY: '',
+        },
+      }).catch((err) => err as Error)
+      expect(result).toBeInstanceOf(Error)
+      expect((result as Error).message).toContain('MPPX_STRIPE_SECRET_KEY')
+    } finally {
+      appServer.close()
+    }
+  })
+
+  test('error: production key rejected', { timeout: 60_000 }, async () => {
+    const server = Mppx_server.create({
+      methods: [
+        stripe_server.charge({
+          secretKey: 'sk_test_mock',
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm: 'cli-test-stripe-live',
+      secretKey: 'cli-test-secret',
+    })
+
+    const appServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx_server.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('paid')
+    })
+
+    try {
+      const result = await runAsync([appServer.url, '-s', '-M', 'paymentMethod=pm_card_visa'], {
+        input: '',
+        env: {
+          ...process.env,
+          NODE_NO_WARNINGS: '1',
+          MPPX_STRIPE_SECRET_KEY: 'sk_live_fake',
+        },
+      }).catch((err) => err as Error)
+      expect(result).toBeInstanceOf(Error)
+      expect((result as Error).message).toContain('test mode')
+    } finally {
+      appServer.close()
+    }
+  })
+})
+
 // ---------------------------------------------------------------------------
 // account [action]
 // TODO: investigate account tests timing out in CI (secret-tool/gnome-keyring hangs)
@@ -505,24 +702,23 @@ test('mppx --help', () => {
       view     View account address
 
     Options:
-      -a, --account <name>   Account name (env: MPPX_ACCOUNT) 
-      -d, --data <data>      Send request body (implies POST unless -X is set) 
-      -f, --fail             Fail silently on HTTP errors (exit 22) 
-      -i, --include          Include response headers in output 
-      -k, --insecure         Skip TLS certificate verification (true for localhost/.local) 
-      -r, --rpc-url <url>    RPC endpoint, defaults to public RPC for chain (env: MPPX_RPC_URL) 
-      -s, --silent           Silent mode (suppress progress and info) 
-      -v, --verbose          Show request/response headers 
-      -A, --user-agent <ua>  Set User-Agent header 
-      -H, --header <header>  Add header (repeatable) 
-      -L, --location         Follow redirects 
-      -X, --method <method>  HTTP method 
-      --channel <id>         Reuse existing session channel ID 
-      --confirm              Show confirmation prompts 
-      --deposit <amount>     Deposit amount for session payments (human-readable units) 
-      --json <json>          Send JSON body (sets Content-Type and Accept, implies POST) 
-      -V, --version          Display version number 
-      -h, --help             Display this message 
+      -a, --account <name>    Account name (env: MPPX_ACCOUNT) 
+      -d, --data <data>       Send request body (implies POST unless -X is set) 
+      -f, --fail              Fail silently on HTTP errors (exit 22) 
+      -i, --include           Include response headers in output 
+      -k, --insecure          Skip TLS certificate verification (true for localhost/.local) 
+      -r, --rpc-url <url>     RPC endpoint, defaults to public RPC for chain (env: MPPX_RPC_URL) 
+      -s, --silent            Silent mode (suppress progress and info) 
+      -v, --verbose           Show request/response headers 
+      -A, --user-agent <ua>   Set User-Agent header 
+      -H, --header <header>   Add header (repeatable) 
+      -L, --location          Follow redirects 
+      -X, --method <method>   HTTP method 
+      -M, --method-opt <opt>  Method-specific option (key=value, repeatable) 
+      --confirm               Show confirmation prompts 
+      --json <json>           Send JSON body (sets Content-Type and Accept, implies POST) 
+      -V, --version           Display version number 
+      -h, --help              Display this message 
 
     Examples:
     mppx example.com/content