feat: support new subject field, grant spent amounts by BlairCurrey · Pull Request #20 · interledger/open-payments-node

BlairCurrey · 2026-01-08T18:00:49Z

Adds support for new subject field on grants
Adds support for new outgoing payment grant spent amounts (client.outgoingPayment.getGrantSpentAmounts)

fixes: #17
fixes: #19

changeset-bot · 2026-01-08T18:00:53Z

🦋 Changeset detected

Latest commit: dbf2b04

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

This PR includes changesets to release 2 packages

Name	Type
@interledger/open-payments	Minor
example-peer-to-peer	Patch

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

BlairCurrey · 2026-01-08T19:48:50Z

packages/open-payments/src/openapi/index.test.ts

-    test('properly references $ref to external ./schemas.yaml', async () => {
-      const openApi = await getResourceServerOpenAPI()
-
-      expect(
-        Object.keys(
-          openApi.paths?.['/incoming-payments']?.['post']?.['requestBody']?.[
-            'content'
-          ]['application/json']['schema']['properties']['incomingAmount'][
-            'properties'
-          ]
-        ).sort()
-      ).toEqual(['assetCode', 'assetScale', 'value'].sort())
-    })


These are no longer relevant nor testing what they are supposed to (references to external schema) because we got rid of the external schema.

This came on my radar because one of them broke since the details of the spec changed (subject field). Which means it's also quite flakey (even if we did need it). I think all these tests really need to do is just ensure it loads (specific details are irrelevant), which it still does.

BlairCurrey · 2026-01-08T19:52:40Z

packages/open-payments/src/client/outgoing-payment.ts

    requestArgs: ResourceRequestArgs,
    createArgs: CreateOutgoingPaymentArgs
  ): Promise<OutgoingPaymentWithSpentAmounts>
+  getGrantSpentAmounts(


called like client.outgoingPayment.getGrantSpentAmounts. Makes it discoverable through outgoing payment which seems appropriate given the use case ("how much has been spent against the outgoing payemnt?") and a top-level method (client.outgoingPaymentGrant.getSpentAmounts) seemed like overkill and im not sure we intend on having more details for the outgoing payment grant exposed on this new endpoint, although it kinda fits the pattern more (/outgoing-payment, /incoming-payment, outgoing-payment-grant etc.). I think this ended up being the most reasonable way.

Makes sense to me, since it's still "scoped" to the outgoing payments.

.changeset/selfish-geese-beg.md

mkurapov · 2026-01-09T17:58:20Z

packages/open-payments/src/types.ts

-  access_token: { access: GrantRequestAccessItem[] }
-  client: ASOperations['post-request']['requestBody']['content']['application/json']['client']
-  interact?: ASOperations['post-request']['requestBody']['content']['application/json']['interact']
+  subject?: Subject


I think we can remove subject from GrantContinuation, since I imagine it was meant as the pending grant continuation return type (ie during polling). Maybe a better name for GrantContinuation is PendingGrantContinuation

I can remove it but I just want to verify since I'm not sure im completely following.

The openapi spec for /continue/{id} defines subject as an optional property in the response. But we still don't want to expose it here, is that correct? Should it be on the response in the spec?

It looks like the types are:

Grant: the result of calling /continue/{id} where we get continue with access_token and/or subject (i.e. a "finalized" grant)

GrantContinuation: the result of calling /continue/{id} where we only get continue (what we get back during polling only)

As a result, I think subject belongs only on Grant and not on GrantContinuation

gotcha, removed subject

mkurapov · 2026-01-09T18:10:03Z

packages/open-payments/src/types.ts

 export type Grant = {
  access_token: ASComponents['schemas']['access_token']
  continue: ASComponents['schemas']['continue']
+  subject?: Subject


Technically, now the access_token becomes optional in this type since the client could have made the grant requests only with the subject. As a result, the isFinalizedGrant type guard becomes unclear. From the top of my head, maybe we can deprecate isFinalizedGrant, and then have something like isFinalizedGrantWithAccessToken | isFinalizedGrantWithSubject? What do you think?

I think that makes sense. I added isFinalizedGrantWithSubject that verifies subject in grant. And madeaccess_token optional.

Nice, thank you! Let's update the client README and the changeset with this.

updated the changeset

updated the readme with the isFinalizedGrantWithAccessToken typeguard in the example flow: dbf2b04

mkurapov · 2026-01-09T18:11:45Z

packages/open-payments/src/client/outgoing-payment.ts

    requestArgs: ResourceRequestArgs,
    createArgs: CreateOutgoingPaymentArgs
  ): Promise<OutgoingPaymentWithSpentAmounts>
+  getGrantSpentAmounts(


Makes sense to me, since it's still "scoped" to the outgoing payments.

Co-authored-by: Max Kurapov <max@interledger.org>

mkurapov

Approving, but let's wait for the Rafiki release + test wallet to go through first

mkurapov · 2026-01-15T12:50:46Z

packages/open-payments/src/types.ts

 export type Grant = {
  access_token: ASComponents['schemas']['access_token']
  continue: ASComponents['schemas']['continue']
+  subject?: Subject


Nice, thank you! Let's update the client README and the changeset with this.

feat: support new subject field

4eaea30

feat: support new outgoing payment grant spent amounts endpoint

d82b287

BlairCurrey commented Jan 8, 2026

View reviewed changes

chore: add changeset

3a8830b

BlairCurrey marked this pull request as ready for review January 8, 2026 19:59

BlairCurrey requested a review from mkurapov January 8, 2026 19:59

BlairCurrey changed the title ~~feat: support new subject field~~ feat: support new subject field, grant spent amounts Jan 8, 2026

BlairCurrey requested review from koekiebox, njlie, oana-lolea and sanducb January 8, 2026 20:00

mkurapov reviewed Jan 9, 2026

View reviewed changes

BlairCurrey and others added 2 commits January 9, 2026 13:33

Update .changeset/selfish-geese-beg.md

f4b188a

Co-authored-by: Max Kurapov <max@interledger.org>

fix: grant types

668338f

mkurapov previously approved these changes Jan 15, 2026

View reviewed changes

chore: update changeset with new type guards

db21c08

BlairCurrey dismissed mkurapov’s stale review via db21c08 January 23, 2026 01:15

docs: update readme

dbf2b04

BlairCurrey mentioned this pull request Jan 23, 2026

Update with new subject field, isFinalizedGrant deprecation interledger/open-payments#757

Open

BlairCurrey requested a review from mkurapov January 27, 2026 16:06

mkurapov approved these changes Jan 27, 2026

View reviewed changes

BlairCurrey merged commit 5a5c789 into main Jan 27, 2026
5 checks passed

Conversation

BlairCurrey commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

BlairCurrey Jan 8, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BlairCurrey Jan 9, 2026 • 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!

mkurapov Jan 12, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BlairCurrey Jan 23, 2026 • 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!

BlairCurrey Jan 23, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

mkurapov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BlairCurrey commented Jan 8, 2026 •

edited

Loading

changeset-bot bot commented Jan 8, 2026 •

edited

Loading

BlairCurrey Jan 8, 2026 •

edited

Loading

BlairCurrey Jan 9, 2026 •

edited

Loading

mkurapov Jan 12, 2026 •

edited

Loading

BlairCurrey Jan 23, 2026 •

edited

Loading

BlairCurrey Jan 23, 2026 •

edited

Loading