mppx 0.6.27 → 0.6.28

package/src/stripe/server/Charge.ts

@@ -1,7 +1,8 @@
+import type * as Challenge from '../../Challenge.js'
 import type * as Credential from '../../Credential.js'
 import { PaymentActionRequiredError, VerificationFailedError } from '../../Errors.js'
 import * as Expires from '../../Expires.js'
-import type { LooseOmit, OneOf } from '../../internal/types.js'
+import type { LooseOmit, MaybePromise, OneOf } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import type * as Html from '../../server/internal/html/config.ts'
 import type * as z from '../../zod.js'
@@ -54,6 +55,7 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
   } = parameters
 
   const client = 'client' in parameters ? parameters.client : undefined
+  const connect = parameters.connect
   const secretKey = 'secretKey' in parameters ? parameters.secretKey : undefined
 
   type Defaults = charge.DeriveDefaults<parameters>
@@ -92,7 +94,7 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
           }
         : undefined,
 
-    async verify({ credential, request }) {
+    async verify({ credential, envelope, request }) {
       const { challenge } = credential
       const resolvedRequest = (() => {
         const parsed = Methods.charge.schema.request.safeParse(request)
@@ -115,6 +117,13 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
         | Record<string, string>
         | undefined
       const resolvedMetadata = { ...buildAnalytics({ credential }), ...userMetadata }
+      const settlement = validateConnectSettlement({
+        amount: resolvedRequest.amount,
+        settlement:
+          typeof connect === 'function'
+            ? await connect({ challenge, credential, envelope, request: resolvedRequest })
+            : connect,
+      })
 
       const pi = client
         ? await createWithClient({
@@ -123,6 +132,7 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
             request: resolvedRequest,
             spt,
             metadata: resolvedMetadata,
+            settlement,
           })
         : await createWithSecretKey({
             secretKey: secretKey!,
@@ -130,6 +140,7 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
             request: resolvedRequest,
             spt,
             metadata: resolvedMetadata,
+            settlement,
           })
 
       if (pi.replayed)
@@ -171,6 +182,8 @@ export declare namespace charge {
       | undefined
     /** Optional metadata to include in SPT creation requests. */
     metadata?: Record<string, string> | undefined
+    /** Optional server-side Stripe Connect settlement policy. Not included in MPP challenges. */
+    connect?: ConnectSettlement | ResolveConnectSettlement | undefined
   } & Defaults &
     OneOf<
       | {
@@ -187,6 +200,45 @@ export declare namespace charge {
     parameters,
     Extract<keyof parameters, keyof Defaults>
   > & { decimals: number }
+
+  /**
+   * Server-side Stripe Connect settlement parameters.
+   *
+   * @see https://docs.stripe.com/connect/destination-charges
+   */
+  type ConnectSettlement = {
+    /** Connected account used as the Stripe account context for the request. */
+    stripeAccount?: string | undefined
+    /** Platform application fee amount in the smallest currency unit. */
+    applicationFeeAmount?: number | undefined
+    /** Connected account used as the business of record. */
+    onBehalfOf?: string | undefined
+    /** Destination transfer created from the PaymentIntent. */
+    transferData?: { amount?: number | undefined; destination: string } | undefined
+    /** Reconciliation token linking related charges and transfers. */
+    transferGroup?: string | undefined
+  }
+
+  type ResolveConnectSettlement = (parameters: {
+    challenge: Challenge.Challenge<
+      z.output<typeof Methods.charge.schema.request>,
+      'charge',
+      'stripe'
+    >
+    credential: Credential.Credential<
+      z.output<typeof Methods.charge.schema.credential.payload>,
+      Challenge.Challenge<z.output<typeof Methods.charge.schema.request>, 'charge', 'stripe'>
+    >
+    envelope?:
+      | Method.VerifiedChallengeEnvelope<
+          z.output<typeof Methods.charge.schema.request>,
+          z.output<typeof Methods.charge.schema.credential.payload>,
+          'charge',
+          'stripe'
+        >
+      | undefined
+    request: z.output<typeof Methods.charge.schema.request>
+  }) => MaybePromise<ConnectSettlement | undefined>
 }
 
 /** Creates a PaymentIntent using the Stripe SDK client. */
@@ -195,21 +247,41 @@ async function createWithClient(parameters: {
   challenge: { id: string }
   metadata: Record<string, string>
   request: { amount: unknown; currency: unknown }
+  settlement: charge.ConnectSettlement | undefined
   spt: string
 }): Promise<{ id: string; status: string; replayed: boolean }> {
-  const { client, challenge, metadata, request, spt } = parameters
+  const { client, challenge, metadata, request, settlement, spt } = parameters
   try {
+    const paymentIntentParams = {
+      amount: Number(request.amount),
+      automatic_payment_methods: { allow_redirects: 'never', enabled: true },
+      confirm: true,
+      currency: request.currency as string,
+      metadata,
+      ...(settlement?.applicationFeeAmount !== undefined && {
+        application_fee_amount: settlement.applicationFeeAmount,
+      }),
+      ...(settlement?.onBehalfOf !== undefined && { on_behalf_of: settlement.onBehalfOf }),
+      ...(settlement?.transferData !== undefined && {
+        transfer_data: {
+          destination: settlement.transferData.destination,
+          ...(settlement.transferData.amount !== undefined && {
+            amount: settlement.transferData.amount,
+          }),
+        },
+      }),
+      ...(settlement?.transferGroup !== undefined && { transfer_group: settlement.transferGroup }),
+      // `shared_payment_granted_token` is not yet in the Stripe SDK types (SPTs are in private preview).
+      shared_payment_granted_token: spt,
+    }
+    const paymentIntentOptions = {
+      apiVersion: stripePreviewVersion,
+      idempotencyKey: `mppx_${challenge.id}_${spt}`,
+      ...(settlement?.stripeAccount !== undefined && { stripeAccount: settlement.stripeAccount }),
+    }
     const result = await client.paymentIntents.create(
-      {
-        amount: Number(request.amount),
-        automatic_payment_methods: { allow_redirects: 'never', enabled: true },
-        confirm: true,
-        currency: request.currency as string,
-        metadata,
-        // `shared_payment_granted_token` is not yet in the Stripe SDK types (SPTs are in private preview).
-        shared_payment_granted_token: spt,
-      } as any,
-      { idempotencyKey: `mppx_${challenge.id}_${spt}`, apiVersion: stripePreviewVersion },
+      paymentIntentParams as any,
+      paymentIntentOptions,
     )
     // https://docs.stripe.com/error-low-level#idempotency
     const replayed = result.lastResponse?.headers?.['idempotent-replayed'] === 'true'
@@ -228,9 +300,10 @@ async function createWithSecretKey(parameters: {
   challenge: { id: string }
   metadata: Record<string, string>
   request: { amount: unknown; currency: unknown }
+  settlement: charge.ConnectSettlement | undefined
   spt: string
 }): Promise<{ id: string; status: string; replayed: boolean }> {
-  const { secretKey, challenge, metadata, request, spt } = parameters
+  const { secretKey, challenge, metadata, request, settlement, spt } = parameters
 
   const body = new URLSearchParams({
     amount: request.amount as string,
@@ -243,15 +316,27 @@ async function createWithSecretKey(parameters: {
   for (const [key, value] of Object.entries(metadata)) {
     body.set(`metadata[${key}]`, value)
   }
+  if (settlement?.applicationFeeAmount !== undefined)
+    body.set('application_fee_amount', String(settlement.applicationFeeAmount))
+  if (settlement?.onBehalfOf !== undefined) body.set('on_behalf_of', settlement.onBehalfOf)
+  if (settlement?.transferData !== undefined) {
+    body.set('transfer_data[destination]', settlement.transferData.destination)
+    if (settlement.transferData.amount !== undefined)
+      body.set('transfer_data[amount]', String(settlement.transferData.amount))
+  }
+  if (settlement?.transferGroup !== undefined) body.set('transfer_group', settlement.transferGroup)
+
+  const headers = {
+    Authorization: `Basic ${btoa(`${secretKey}:`)}`,
+    'Content-Type': 'application/x-www-form-urlencoded',
+    'Idempotency-Key': `mppx_${challenge.id}_${spt}`,
+    'Stripe-Version': stripePreviewVersion,
+    ...(settlement?.stripeAccount !== undefined && { 'Stripe-Account': settlement.stripeAccount }),
+  }
 
   const response = await fetch('https://api.stripe.com/v1/payment_intents', {
     method: 'POST',
-    headers: {
-      Authorization: `Basic ${btoa(`${secretKey}:`)}`,
-      'Content-Type': 'application/x-www-form-urlencoded',
-      'Idempotency-Key': `mppx_${challenge.id}_${spt}`,
-      'Stripe-Version': stripePreviewVersion,
-    },
+    headers,
     body,
   })
 
@@ -288,3 +373,48 @@ function buildAnalytics(parameters: { credential: Credential.Credential }): Reco
     ...(credential.source ? { mpp_client_id: credential.source } : {}),
   }
 }
+
+function validateConnectSettlement(parameters: {
+  amount: unknown
+  settlement: charge.ConnectSettlement | undefined
+}): charge.ConnectSettlement | undefined {
+  const { amount, settlement } = parameters
+  if (settlement === undefined) return undefined
+
+  const paymentAmount = Number(amount)
+  if (!Number.isSafeInteger(paymentAmount) || paymentAmount < 0)
+    throw new VerificationFailedError({ reason: 'Stripe amount must be a non-negative integer.' })
+
+  validateAccountId(settlement.stripeAccount, 'stripeAccount')
+  validateAccountId(settlement.onBehalfOf, 'onBehalfOf')
+  validateAmount(settlement.applicationFeeAmount, paymentAmount, 'applicationFeeAmount')
+
+  if (settlement.transferData !== undefined) {
+    validateRequiredAccountId(settlement.transferData.destination, 'transferData.destination')
+    validateAmount(settlement.transferData.amount, paymentAmount, 'transferData.amount')
+  }
+
+  return settlement
+}
+
+function validateAccountId(value: string | undefined, name: string) {
+  if (value !== undefined && value.length === 0)
+    throw new VerificationFailedError({ reason: `Stripe Connect ${name} must be non-empty.` })
+}
+
+function validateRequiredAccountId(value: string | undefined, name: string) {
+  if (value === undefined || value.length === 0)
+    throw new VerificationFailedError({ reason: `Stripe Connect ${name} must be non-empty.` })
+}
+
+function validateAmount(value: number | undefined, paymentAmount: number, name: string) {
+  if (value === undefined) return
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new VerificationFailedError({
+      reason: `Stripe Connect ${name} must be a non-negative integer.`,
+    })
+  if (value > paymentAmount)
+    throw new VerificationFailedError({
+      reason: `Stripe Connect ${name} must be less than or equal to the PaymentIntent amount.`,
+    })
+}

package/src/tempo/server/Charge.test.ts

@@ -286,6 +286,7 @@ describe('tempo', () => {
     })
 
     test('behavior: rejects replayed transaction hash', async () => {
+      const dedupStore = Store.memory()
       const dedupServer = Mppx_server.create({
         methods: [
           tempo_server.charge({
@@ -294,7 +295,8 @@ describe('tempo', () => {
             },
             currency: asset,
             account: accounts[0],
-            store: Store.memory(),
+            store: dedupStore,
+            storeKeyPrefix: 'tenant:',
           }),
         ],
         realm,
@@ -336,6 +338,8 @@ describe('tempo', () => {
         })
         expect(response.status).toBe(200)
       }
+      expect(await dedupStore.get(`tenant:mppx:charge:${receipt.transactionHash}`)).not.toBeNull()
+      expect(await dedupStore.get(`mppx:charge:${receipt.transactionHash}`)).toBeNull()
 
       const response2 = await fetch(httpServer.url)
       expect(response2.status).toBe(402)
@@ -1616,6 +1620,7 @@ describe('tempo', () => {
             currency: asset,
             account: accounts[0],
             store: sponsoredStore,
+            storeKeyPrefix: 'tenant:',
           }),
         ],
         realm,
@@ -1661,6 +1666,16 @@ describe('tempo', () => {
 
       const first = fetch(httpServer.url, { headers: { Authorization: credential1 } })
       await simulationStarted
+      expect(
+        await sponsoredStore.get(
+          `tenant:mppx:charge:sponsor:${chain.id}:${accounts[1].address.toLowerCase()}`,
+        ),
+      ).not.toBeNull()
+      expect(
+        await sponsoredStore.get(
+          `mppx:charge:sponsor:${chain.id}:${accounts[1].address.toLowerCase()}`,
+        ),
+      ).toBeNull()
       const second = fetch(httpServer.url, { headers: { Authorization: credential2 } })
 
       try {
@@ -2870,6 +2885,7 @@ describe('tempo', () => {
 
     test('behavior: store keys proof replay protection by challenge ID', async () => {
       const replayStore = Store.memory()
+      const storeKeyPrefix = 'tenant:'
       const server_ = Mppx_server.create({
         methods: [
           tempo_server.charge({
@@ -2879,6 +2895,7 @@ describe('tempo', () => {
             currency: asset,
             account: accounts[0],
             store: replayStore,
+            storeKeyPrefix,
           }),
         ],
         realm,
@@ -2918,6 +2935,10 @@ describe('tempo', () => {
         headers: { Authorization: Credential.serialize(credential1) },
       })
       expect(response2.status).toBe(200)
+      expect(
+        await replayStore.get(`${storeKeyPrefix}mppx:charge:proof:${challenge1.id}`),
+      ).not.toBeNull()
+      expect(await replayStore.get(`mppx:charge:proof:${challenge1.id}`)).toBeNull()
 
       const response3 = await fetch(httpServer.url)
       expect(response3.status).toBe(402)

package/src/tempo/server/Charge.ts

@@ -66,8 +66,16 @@ export function charge<const parameters extends charge.Parameters>(
     validateSender,
     waitForConfirmation = true,
   } = parameters
-  const store = (parameters.store ?? Store.memory()) as Store.AtomicStore<charge.StoreItemMap>
-  const proofStore = parameters.store as Store.AtomicStore<charge.StoreItemMap> | undefined
+  const storeKeyPrefix = parameters.storeKeyPrefix ?? ''
+  const store = Store.from(
+    (parameters.store ?? Store.memory()) as Store.AtomicStore<charge.StoreItemMap>,
+    { keyPrefix: storeKeyPrefix },
+  )
+  const proofStore = parameters.store
+    ? Store.from(parameters.store as Store.AtomicStore<charge.StoreItemMap>, {
+        keyPrefix: storeKeyPrefix,
+      })
+    : undefined
 
   const { recipient, feePayer, feePayerUrl } = Account.resolve(parameters)
 
@@ -539,6 +547,12 @@ export declare namespace charge {
      * memo binding, transaction success, and replay protection.
      */
     validateSender?: ValidateSender | undefined
+    /**
+     * Prefix prepended to charge replay-protection store keys.
+     *
+     * By default, no prefix is applied.
+     */
+    storeKeyPrefix?: string | undefined
     /**
      * Whether to wait for the charge transaction to confirm on-chain before
      * responding. @default true

package/src/tempo/server/Session.ts

@@ -104,7 +104,9 @@ export function session<const parameters extends session.Parameters>(
 
   const lastOnChainVerified = new Map<Hex, number>()
 
-  const store = ChannelStore.fromStore(rawStore)
+  const store = ChannelStore.fromStore(
+    Store.from(rawStore, { keyPrefix: parameters.storeKeyPrefix }),
+  )
 
   const { account, recipient, feePayer, feePayerUrl } = Account.resolve(parameters)
 
@@ -357,6 +359,12 @@ export declare namespace session {
      * local single-process usage.
      */
     store?: Store.AtomicStore | undefined
+    /**
+     * Prefix prepended to channel state store keys.
+     *
+     * By default, no prefix is applied.
+     */
+    storeKeyPrefix?: string | undefined
     /**
      * Enable SSE streaming.
      *

package/src/tempo/server/Subscription.ts

@@ -72,7 +72,7 @@ export function subscription<const parameters extends subscription.Parameters>(
 
   const { recipient } = Account.resolve(parameters)
   const context = createContext(parameters, {
-    store: rawStore,
+    store: Store.from(rawStore, { keyPrefix: parameters.storeKeyPrefix }),
     options: {
       activationTimeoutMs: parameters.activationTimeoutMs,
       renewalTimeoutMs: parameters.renewalTimeoutMs,
@@ -1110,6 +1110,12 @@ export declare namespace subscription {
         subscription: SubscriptionRecord
       }) => Promise<RenewalResult>
       store?: Store.AtomicStore<Record<string, unknown>> | undefined
+      /**
+       * Prefix prepended to all subscription store keys.
+       *
+       * By default, no prefix is applied.
+       */
+      storeKeyPrefix?: string | undefined
       testnet?: boolean | undefined
       waitForConfirmation?: boolean | undefined
     } & Defaults

package/src/tempo/session/ChannelStore.test.ts

@@ -117,6 +117,27 @@ describe('channelStore', () => {
       expect(typeof loaded!.createdAt).toBe('string')
     })
 
+    test('prefixes backing store keys when configured', async () => {
+      const rawStore = Store.memory()
+      const cs = ChannelStore.fromStore(Store.from(rawStore, { keyPrefix: 'tenant:' }))
+      await cs.updateChannel(channelId, () => makeChannel())
+
+      expect(await rawStore.get(`tenant:${channelId}`)).not.toBeNull()
+      expect(await rawStore.get(channelId)).toBeNull()
+      expect((await cs.getChannel(channelId))?.channelId).toBe(channelId)
+    })
+
+    test('isolates prefixed store wrappers', async () => {
+      const rawStore = Store.memory()
+      const first = ChannelStore.fromStore(Store.from(rawStore, { keyPrefix: 'tenant-a:' }))
+      const second = ChannelStore.fromStore(Store.from(rawStore, { keyPrefix: 'tenant-b:' }))
+      await first.updateChannel(channelId, () => makeChannel())
+
+      expect(await second.getChannel(channelId)).toBeNull()
+      expect(await rawStore.get(`tenant-a:${channelId}`)).not.toBeNull()
+      expect(await rawStore.get(`tenant-b:${channelId}`)).toBeNull()
+    })
+
     test('treats case-variant channelIds as the same record', async () => {
       const cs = ChannelStore.fromStore(Store.memory())
       await cs.updateChannel(mixedCaseAliasChannelId, () =>

package/src/tempo/subscription/Store.test.ts

@@ -26,6 +26,61 @@ function createRecord(overrides: Partial<SubscriptionRecord> = {}): Subscription
 }
 
 describe('tempo subscription store', () => {
+  test('prefixes all backing store keys when configured', async () => {
+    const rawStore = Store.memory()
+    const store = fromStore(Store.from(rawStore, { keyPrefix: 'tenant:' }))
+    let finishActivation!: () => void
+    const pendingActivation = new Promise<void>((resolve) => {
+      finishActivation = resolve
+    })
+    let activationStarted!: () => void
+    const activationStartedPromise = new Promise<void>((resolve) => {
+      activationStarted = resolve
+    })
+
+    const activation = store.activate({
+      challengeId: 'challenge-1',
+      create: async () => {
+        activationStarted()
+        await pendingActivation
+        return { subscription: createRecord() }
+      },
+      lookupKey: 'user-1:plan:pro',
+    })
+    await activationStartedPromise
+
+    expect(await rawStore.get('tenant:tempo:subscription:credential:challenge-1')).not.toBeNull()
+    expect(
+      await rawStore.get('tenant:tempo:subscription:activation:user-1:plan:pro'),
+    ).not.toBeNull()
+    expect(await rawStore.get('tempo:subscription:credential:challenge-1')).toBeNull()
+
+    finishActivation()
+    expect((await activation).status).toBe('activated')
+    await store.getOrCreateAccessKey('user-1:plan:pro')
+
+    expect(await rawStore.get(`tenant:tempo:subscription:record:${subscriptionId}`)).not.toBeNull()
+    expect(await rawStore.get('tenant:tempo:subscription:key:user-1:plan:pro')).toBe(subscriptionId)
+    expect(
+      await rawStore.get('tenant:tempo:subscription:access-key:user-1:plan:pro'),
+    ).not.toBeNull()
+    expect(await rawStore.get(`tempo:subscription:record:${subscriptionId}`)).toBeNull()
+  })
+
+  test('combines store prefix with custom key family prefixes', async () => {
+    const rawStore = Store.memory()
+    const store = fromStore(Store.from(rawStore, { keyPrefix: 'tenant:' }), {
+      keyPrefix: 'lookup:',
+      recordPrefix: 'record:',
+    })
+
+    await store.put(createRecord())
+
+    expect(await rawStore.get(`tenant:record:${subscriptionId}`)).not.toBeNull()
+    expect(await rawStore.get('tenant:lookup:user-1:plan:pro')).toBe(subscriptionId)
+    expect(await rawStore.get(`record:${subscriptionId}`)).toBeNull()
+  })
+
   test('rejects a replayed activation challenge', async () => {
     const store = fromStore(Store.memory())