feat: update outgoing payment limits spec #564

njlie · 2025-03-12T20:54:24Z

Changes proposed in this pull request

Prevents outgoing payment grant requests where debitAmount and receiveAmount are both included in the limits.

Context

Closes #471.

changeset-bot · 2025-03-12T20:54:27Z

🦋 Changeset detected

Latest commit: 6a474dd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@interledger/open-payments	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2025-03-12T20:54:50Z

✅ Deploy Preview for openpayments-preview ready!

Name	Link
🔨 Latest commit
🔍 Latest deploy log	https://app.netlify.com/sites/openpayments-preview/deploys/67e29d4638c80400b528c072
😎 Deploy Preview	https://deploy-preview-564--openpayments-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

mkurapov · 2025-03-17T12:58:48Z

packages/open-payments/src/openapi/generated/auth-server-types.ts

+    }> &
+      Partial<{
+        receiver?: external["schemas.yaml"]["components"]["schemas"]["receiver"];
+        interval?: components["schemas"]["interval"];
+        /** @description All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant. */
+        debitAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
+      }> &
+      Partial<{
+        receiver?: external["schemas.yaml"]["components"]["schemas"]["receiver"];
+        interval?: components["schemas"]["interval"];
+        /** @description All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant. */
+        receiveAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
+      }>;


These types would allow the client to take in both receiveAmount or debitAmount (because of the old openapi-typescript lib). I've updated it here (and upgraded to TS 5 here) so we can get those in first)

raducristianpopa

I think we should add some runtime assertions as well when we are dealing with mutually exclusive types and not fully rely on TS errors.

mkurapov · 2025-03-18T10:46:14Z

packages/open-payments/src/client/grant.ts

+        outgoingPaymentAccess?.limits?.debitAmount &&
+        outgoingPaymentAccess.limits?.receiveAmount
+      ) {
+        throw new Error('Invalid Grant Request')


Maybe we can throw an OpenPaymentsClientError here

raducristianpopa

I hoped that the openapi-typescript update will fix the XOR issue that we are facing for mutually exclusive types, but it looks like it is not generating proper XOR for oneOf. Right now, TypeScript will not complain if a client still provides both amounts.

Since this is a major bump, we can improve the types a bit. Let me know what you think about this.

raducristianpopa · 2025-03-19T05:41:12Z

packages/open-payments/src/types.ts

+export type OutgoingPaymentLimitWithDebitAmount = Extract<
+  ASComponents['schemas']['access-outgoing']['limits'],
+  { debitAmount: components['schemas']['amount'] }
+>
+export type OutgoingPaymentLimitWithReceiveAmount = Extract<
+  ASComponents['schemas']['access-outgoing']['limits'],
+  { receiveAmount: components['schemas']['amount'] }
+>


Suggested change

export type OutgoingPaymentLimitWithDebitAmount = Extract<

ASComponents['schemas']['access-outgoing']['limits'],

{ debitAmount: components['schemas']['amount'] }

>

export type OutgoingPaymentLimitWithReceiveAmount = Extract<

ASComponents['schemas']['access-outgoing']['limits'],

{ receiveAmount: components['schemas']['amount'] }

>

// From: https://github.com/microsoft/TypeScript/issues/14094#issuecomment-373782604

type Without<T, U> = { [P in Exclude<keyof T, keyof U>]?: never }

type XOR<T, U> = T | U extends object

? (Without<T, U> & U) | (Without<U, T> & T)

: T | U

type XOR3<T, U, V> = XOR<T, XOR<U,V>>

export type AccessOutgoingBase = {

receiver?: ASComponents['schemas']['receiver']

interval?: ASComponents['schemas']['interval']

}

export type AccessOutgoingWithDebitAmount = AccessOutgoingBase & {

debitAmount: ASComponents['schemas']['amount']

}

export type AccessOutgoingWithReceiveAmount = AccessOutgoingBase & {

receiveAmount: ASComponents['schemas']['amount']

}

export type AccessOutgoingLimits = XOR3<

AccessOutgoingBase,

AccessOutgoingWithDebitAmount,

AccessOutgoingWithReceiveAmount

>

export type AccessOutgoing = {

type: 'outgoing-payment'

actions: ('create' | 'read' | 'read-all' | 'list' | 'list-all')[]

identifier: string

limits?: AccessOutgoingLimits

}

export type GrantRequestAccessItem =

| ASComponents['schemas']['access-incoming']

| AccessOutgoing

| ASComponents['schemas']['access-quote']

With the new GrantRequestAccessItem, we can now update GrantRequest from

open-payments/packages/open-payments/src/types.ts

Lines 96 to 100 in 97612b4

export type GrantRequest = {

access_token: ASOperations['post-request']['requestBody']['content']['application/json']['access_token']

client: ASOperations['post-request']['requestBody']['content']['application/json']['client']

interact?: ASOperations['post-request']['requestBody']['content']['application/json']['interact']

}

to:

export type GrantRequest = { access_token: { access: GrantRequestAccessItem[] } client: ASOperations['post-request']['requestBody']['content']['application/json']['client'] interact?: ASOperations['post-request']['requestBody']['content']['application/json']['interact'] }

Now, if a client will provide both amounts, a TypeScript error will be raised - in their IDE or at transpilation time:

open-payments/packages/open-payments on  nl/471/outgoing-payment-limits-update [!?] via  v20.18.3 pnpm tsc --noEmit src/scratchpad.ts:26:15 - error TS2322: Type '{ assetScale: number; assetCode: string; value: string; }' is not assignable to type 'undefined'. 26 receiveAmount: { ~~~~~~~~~~~~~ Found 1 error in src/scratchpad.ts:26

This looks great! Thanks for writing it up. The discussion on native XOR implementation is very spirited...

@raducristianpopa I would think it would say is not assignable to type 'never'. instead, but it seems to do the trick

raducristianpopa · 2025-03-19T05:42:18Z

packages/open-payments/src/client/grant.ts

+        (outgoingPaymentAccess?.limits as OutgoingPaymentLimitWithDebitAmount)
+          ?.debitAmount &&
+        (outgoingPaymentAccess?.limits as OutgoingPaymentLimitWithReceiveAmount)
+          ?.receiveAmount


(if we proceed with the new types)

Suggested change

(outgoingPaymentAccess?.limits as OutgoingPaymentLimitWithDebitAmount)

?.debitAmount &&

(outgoingPaymentAccess?.limits as OutgoingPaymentLimitWithReceiveAmount)

?.receiveAmount

(outgoingPaymentAccess?.limits as OutgoingAccessWithDebitAmount)

?.debitAmount &&

(outgoingPaymentAccess?.limits as OutgoingAccessWithReceiveAmount)

?.receiveAmount

raducristianpopa · 2025-03-19T06:24:09Z

openapi/auth-server.yaml

-          description: 'All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.'
-          $ref: ./schemas.yaml#/components/schemas/amount
-        interval:
-          $ref: '#/components/schemas/interval'
      anyOf:


I'm thinking that oneOf might be the property we should go for? Based on OpenAPI docs:

oneOf – validates the value against exactly one of the subschemas
anyOf – validates the value against any (one or more) of the subschemas

raducristianpopa · 2025-03-19T06:27:32Z

packages/open-payments/src/client/grant.ts

+        throw new OpenPaymentsClientError('Invalid Grant Request', {
+          description: 'Invalid Request'
+        })


I feel like this would help the SDK user find the source of the error more easily when using JS directly or when not caring about the TS errors.

Suggested change

throw new OpenPaymentsClientError('Invalid Grant Request', {

description: 'Invalid Request'

})

throw new OpenPaymentsClientError('Invalid Grant Request', {

description: 'Invalid grant request. Both "debitAmount" and "receiveAmount" were provided. Please specify only one of them.'

})

raducristianpopa

@njlie it looks like oneOf is working a bit differently from what I expected when reading the docs - https://swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/#difference-between-anyof-and-oneof (???)

I think that the issue is with the interval and receiver properties since they "match" with multiple schemas when using oneOf. Reverting to anyOf should be the go to solution in this case. Sorry for putting you on the wrong track! 🙇‍♂️

njlie · 2025-03-24T17:10:14Z

@njlie it looks like oneOf is working a bit differently from what I expected when reading the docs - swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not#difference-between-anyof-and-oneof (???)

I think that the issue is with the interval and receiver properties since they "match" with multiple schemas when using oneOf. Reverting to anyOf should be the go to solution in this case. Sorry for putting you on the wrong track! 🙇‍♂️

I also interpreted it the same way as you, at first - so I thought I could "debug" what the issue with the validation was. But this explains why it's been so confusing. Thanks for flagging this anyways 👍

mkurapov · 2025-03-25T12:18:58Z

Interesting, so oneOf to properly work needs all the keys in the objects to be exclusive from one another? Pretty odd but good to know 🤷

njlie requested review from mkurapov and raducristianpopa March 13, 2025 17:40

mkurapov reviewed Mar 17, 2025

View reviewed changes

raducristianpopa reviewed Mar 17, 2025

View reviewed changes

njlie force-pushed the nl/471/outgoing-payment-limits-update branch from 04d1cd4 to d326dbc Compare March 17, 2025 20:39

mkurapov reviewed Mar 18, 2025

View reviewed changes

raducristianpopa and others added 7 commits March 18, 2025 11:14

Update AS Spec

8b0bea0

feat: update types

91a702e

chore: changeset

2fbbd58

fix: tests

81500d5

chore: formatting

1735c69

feat: runtime assertions

b7c7f15

feat: throw OpenPaymentsClientError

acca56a

njlie force-pushed the nl/471/outgoing-payment-limits-update branch from 4cc30fa to acca56a Compare March 18, 2025 18:14

njlie added 2 commits March 18, 2025 14:13

chore: regenerate types

ab3ae0a

fix: build errors

97612b4

njlie requested review from mkurapov and raducristianpopa March 18, 2025 22:01

raducristianpopa reviewed Mar 19, 2025

View reviewed changes

raducristianpopa mentioned this pull request Mar 19, 2025

feat: update limits for outgoing payment access #499

Closed

njlie force-pushed the nl/471/outgoing-payment-limits-update branch 2 times, most recently from a900d8f to 8669a93 Compare March 20, 2025 22:59

raducristianpopa reviewed Mar 21, 2025

View reviewed changes

fix: update types

ee71dd3

njlie force-pushed the nl/471/outgoing-payment-limits-update branch from cb0cb7d to ee71dd3 Compare March 24, 2025 17:13

fix: revert to anyOf in tests

6a474dd

njlie requested a review from raducristianpopa March 24, 2025 17:56

raducristianpopa approved these changes Mar 25, 2025

View reviewed changes

mkurapov approved these changes Mar 25, 2025

View reviewed changes

njlie merged commit 7fb1f25 into main Apr 1, 2025
11 checks passed

njlie deleted the nl/471/outgoing-payment-limits-update branch April 1, 2025 14:17

-export type OutgoingPaymentLimitWithDebitAmount = Extract<
-  ASComponents['schemas']['access-outgoing']['limits'],
-  { debitAmount: components['schemas']['amount'] }
->
-export type OutgoingPaymentLimitWithReceiveAmount = Extract<
-  ASComponents['schemas']['access-outgoing']['limits'],
-  { receiveAmount: components['schemas']['amount'] }
->
+// From: https://github.com/microsoft/TypeScript/issues/14094#issuecomment-373782604
+type Without<T, U> = { [P in Exclude<keyof T, keyof U>]?: never }
+type XOR<T, U> = T | U extends object
+  ? (Without<T, U> & U) | (Without<U, T> & T)
+  : T | U
+type XOR3<T, U, V> = XOR<T, XOR<U,V>>
+export type AccessOutgoingBase = {
+  receiver?: ASComponents['schemas']['receiver']
+  interval?: ASComponents['schemas']['interval']
+}
+export type AccessOutgoingWithDebitAmount = AccessOutgoingBase & {
+  debitAmount: ASComponents['schemas']['amount']
+}
+export type AccessOutgoingWithReceiveAmount = AccessOutgoingBase & {
+  receiveAmount: ASComponents['schemas']['amount']
+}
+export type AccessOutgoingLimits = XOR3<
+  AccessOutgoingBase,
+  AccessOutgoingWithDebitAmount,
+  AccessOutgoingWithReceiveAmount
+>
+export type AccessOutgoing = {
+  type: 'outgoing-payment'
+  actions: ('create' | 'read' | 'read-all' | 'list' | 'list-all')[]
+  identifier: string
+  limits?: AccessOutgoingLimits
+}
+export type GrantRequestAccessItem =
+  | ASComponents['schemas']['access-incoming']
+  | AccessOutgoing
+  | ASComponents['schemas']['access-quote']

	export type GrantRequest = {
	access_token: ASOperations['post-request']['requestBody']['content']['application/json']['access_token']
	client: ASOperations['post-request']['requestBody']['content']['application/json']['client']
	interact?: ASOperations['post-request']['requestBody']['content']['application/json']['interact']
	}

feat: update outgoing payment limits spec #564

feat: update outgoing payment limits spec #564

Uh oh!

Conversation

njlie commented Mar 12, 2025

Changes proposed in this pull request

Context

Uh oh!

changeset-bot bot commented Mar 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Mar 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for openpayments-preview ready!

Uh oh!

mkurapov Mar 17, 2025

Choose a reason for hiding this comment

Uh oh!

raducristianpopa left a comment

Choose a reason for hiding this comment

Uh oh!

mkurapov Mar 18, 2025

Choose a reason for hiding this comment

Uh oh!

raducristianpopa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raducristianpopa Mar 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

njlie Mar 19, 2025

Choose a reason for hiding this comment

Uh oh!

mkurapov Mar 25, 2025

Choose a reason for hiding this comment

Uh oh!

raducristianpopa Mar 19, 2025

Choose a reason for hiding this comment

Uh oh!

raducristianpopa Mar 19, 2025

Choose a reason for hiding this comment

Uh oh!

raducristianpopa Mar 19, 2025

Choose a reason for hiding this comment

Uh oh!

raducristianpopa left a comment

Choose a reason for hiding this comment

Uh oh!

njlie commented Mar 24, 2025

Uh oh!

mkurapov commented Mar 25, 2025

Uh oh!

Uh oh!

Uh oh!

changeset-bot bot commented Mar 12, 2025 •

edited

Loading

netlify bot commented Mar 12, 2025 •

edited

Loading

raducristianpopa left a comment •

edited

Loading

raducristianpopa Mar 19, 2025 •

edited

Loading