feat: support new subject field, grant spent amounts (#20)

* feat: support new subject field

* feat: support new outgoing payment grant spent amounts endpoint

* chore: add changeset

* Update .changeset/selfish-geese-beg.md

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

* fix: grant types

* chore: update changeset with new type guards

* docs: update readme

---------

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

Author: BlairCurrey

.changeset/selfish-geese-beg.md

@@ -0,0 +1,7 @@
+---
+'@interledger/open-payments': minor
+---
+
+- Adds support for new subject field on grants
+- Adds support for new outgoing payment grant spent amounts (`client.outgoingPayment.getGrantSpentAmounts`)
+- Deprecated `isFinalizedGrant` in favor of `isFinalizedGrantWithAccessToken` and `isFinalizedGrantWithSubject`, since grants finalized via `subject` may not include an `access_token`

open-payments-specifications

@@ -291,7 +291,7 @@ Alice would be then redirected to her [Identity Provider](https://openpayments.d
 Once Alice approves the grant request at Cloud Nine Wallet (or the Identity Provider that Cloud Nine Wallet has configured), she will be redirected to the URL specified in the original outgoing payment grant request, with an `interact_ref` in the URL. This `interact_ref` can be used to finalize the outgoing payment grant request:
 
 ```ts
-const finalizedOutgoingPaymentGrant = await client.grant.continue(
+const continueGrantResult = await client.grant.continue(
   {
     url: outgoingPaymentGrant.continue.uri,
     accessToken: outgoingPaymentGrant.continue.access_token.value
@@ -300,7 +300,21 @@ const finalizedOutgoingPaymentGrant = await client.grant.continue(
 )
 ```
 
-7. Create `OutgoingPayment`:
+7. Verify grant finalization:
+
+Use the `isFinalizedGrantWithAccessToken` type guard to check if the grant was successfully finalized with an access token:
+
+```ts
+import { isFinalizedGrantWithAccessToken } from '@interledger/open-payments'
+
+if (!isFinalizedGrantWithAccessToken(continueGrantResult)) {
+  throw new Error('Expected finalized grant with access token')
+}
+
+const finalizedOutgoingPaymentGrant = continueGrantResult
+```
+
+8. Create `OutgoingPayment`:
 
 Once the grant interaction flow has finished, and Alice has consented to the payment, Online Marketplace can create the `OutgoingPayment` on her account:
 

packages/open-payments/README.md

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { createGrantRoutes } from './grant'
 import { OpenAPI, HttpMethod } from '@interledger/openapi'
-import { createTestDeps, mockGrantRequest } from '../test/helpers'
+import { createTestDeps, mockGrantRequest, mockSubject } from '../test/helpers'
 import * as requestors from './requests'
 import { v4 as uuid } from 'uuid'
 import { getAuthServerOpenAPI } from '../openapi'
@@ -136,6 +136,101 @@ describe('grant', (): void => {
           }
         }
       )
+
+      test('POST grant request with subject field only', async (): Promise<void> => {
+        const postSpy = jest.spyOn(requestors, 'post')
+        const subjectOnlyRequest: Omit<GrantRequest, 'client'> = {
+          subject: mockSubject(),
+          interact: {
+            start: ['redirect'],
+            finish: {
+              method: 'redirect',
+              uri: 'http://localhost:3030/mock-idp/fake-client',
+              nonce: '456'
+            }
+          }
+        }
+
+        await createGrantRoutes({
+          openApi,
+          client,
+          ...deps
+        }).request({ url }, subjectOnlyRequest)
+
+        expect(postSpy).toHaveBeenCalledWith(
+          deps,
+          {
+            url,
+            body: {
+              ...subjectOnlyRequest,
+              client
+            }
+          },
+          true
+        )
+      })
+
+      test('POST grant request with both access_token and subject', async (): Promise<void> => {
+        const postSpy = jest.spyOn(requestors, 'post')
+        const combinedRequest: Omit<GrantRequest, 'client'> = {
+          access_token: {
+            access: [
+              {
+                type: 'quote',
+                actions: ['create', 'read']
+              }
+            ]
+          },
+          subject: mockSubject(),
+          interact: {
+            start: ['redirect'],
+            finish: {
+              method: 'redirect',
+              uri: 'http://localhost:3030/mock-idp/fake-client',
+              nonce: '456'
+            }
+          }
+        }
+
+        await createGrantRoutes({
+          openApi,
+          client,
+          ...deps
+        }).request({ url }, combinedRequest)
+
+        expect(postSpy).toHaveBeenCalledWith(
+          deps,
+          {
+            url,
+            body: {
+              ...combinedRequest,
+              client
+            }
+          },
+          true
+        )
+      })
+
+      test('POST grant request with neither access_token nor subject fails', async (): Promise<void> => {
+        const emptyRequest: any = {
+          interact: {
+            start: ['redirect'],
+            finish: {
+              method: 'redirect',
+              uri: 'http://localhost:3030/mock-idp/fake-client',
+              nonce: '456'
+            }
+          }
+        }
+
+        await expect(
+          createGrantRoutes({
+            openApi,
+            client,
+            ...deps
+          }).request({ url }, emptyRequest)
+        ).rejects.toThrow('Invalid Grant Request')
+      })
     })
 
     describe('cancel', () => {

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

@@ -60,20 +60,30 @@ export const createGrantRoutes = (deps: GrantRouteDeps): GrantRoutes => {
       { url }: UnauthenticatedResourceRequestArgs,
       args: Omit<GrantRequest, 'client'>
     ) => {
-      const outgoingPaymentAccess = args.access_token.access.find(
-        (el) => el.type === 'outgoing-payment'
-      )
-      if (
-        (outgoingPaymentAccess?.limits as AccessOutgoingWithDebitAmount)
-          ?.debitAmount &&
-        (outgoingPaymentAccess?.limits as AccessOutgoingWithReceiveAmount)
-          ?.receiveAmount
-      ) {
+      if (!args.access_token && !args.subject) {
         throw new OpenPaymentsClientError('Invalid Grant Request', {
           description:
-            'Only one of "debitAmount" or "receiveAmount" may be specified.'
+            'Grant request must include at least one of "access_token" or "subject".'
         })
       }
+
+      if (args.access_token) {
+        const outgoingPaymentAccess = args.access_token.access.find(
+          (el) => el.type === 'outgoing-payment'
+        )
+        if (
+          (outgoingPaymentAccess?.limits as AccessOutgoingWithDebitAmount)
+            ?.debitAmount &&
+          (outgoingPaymentAccess?.limits as AccessOutgoingWithReceiveAmount)
+            ?.receiveAmount
+        ) {
+          throw new OpenPaymentsClientError('Invalid Grant Request', {
+            description:
+              'Only one of "debitAmount" or "receiveAmount" may be specified.'
+          })
+        }
+      }
+
       return post(
         baseDeps,
         {

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

@@ -2,13 +2,15 @@ import {
   createOutgoingPayment,
   createOutgoingPaymentRoutes,
   getOutgoingPayment,
+  getOutgoingPaymentGrantSpentAmounts,
   listOutgoingPayments,
   validateOutgoingPayment
 } from './outgoing-payment'
 import { OpenAPI, HttpMethod } from '@interledger/openapi'
 import {
   mockOutgoingPayment,
   mockOutgoingPaymentWithSpentAmounts,
+  mockOutgoingPaymentGrantSpentAmounts,
   mockOpenApiResponseValidators,
   mockOutgoingPaymentPaginationResult,
   createTestDeps
@@ -632,5 +634,91 @@ describe('outgoing-payment', (): void => {
         }
       )
     })
+
+    describe('getGrantSpentAmounts', (): void => {
+      test.each`
+        validateResponses | description
+        ${true}           | ${'with response validation'}
+        ${false}          | ${'without response validation'}
+      `(
+        'calls get method $description',
+        async ({ validateResponses }): Promise<void> => {
+          const mockResponseValidator = ({ path, method }) =>
+            path === '/outgoing-payment-grant' && method === HttpMethod.GET
+
+          jest
+            .spyOn(openApi, 'createResponseValidator')
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .mockImplementation(mockResponseValidator as any)
+
+          const getSpy = jest
+            .spyOn(requestors, 'get')
+            .mockResolvedValueOnce(mockOutgoingPaymentGrantSpentAmounts())
+
+          await createOutgoingPaymentRoutes({
+            openApi: validateResponses ? openApi : undefined,
+            ...deps
+          }).getGrantSpentAmounts({
+            url: serverAddress,
+            accessToken: 'accessToken'
+          })
+
+          expect(getSpy).toHaveBeenCalledWith(
+            deps,
+            {
+              url: `${serverAddress}/outgoing-payment-grant`,
+              accessToken: 'accessToken'
+            },
+            validateResponses ? true : undefined
+          )
+        }
+      )
+    })
+  })
+
+  describe('getOutgoingPaymentGrantSpentAmounts', (): void => {
+    test('returns grant spent amounts', async (): Promise<void> => {
+      const grantSpentAmounts = mockOutgoingPaymentGrantSpentAmounts()
+
+      const scope = nock(serverAddress)
+        .get('/outgoing-payment-grant')
+        .reply(200, grantSpentAmounts)
+
+      const result = await getOutgoingPaymentGrantSpentAmounts(
+        deps,
+        {
+          url: serverAddress,
+          accessToken: 'accessToken'
+        },
+        openApiValidators.successfulValidator
+      )
+
+      expect(result).toEqual(grantSpentAmounts)
+      scope.done()
+    })
+
+    test('returns grant spent amounts with partial data', async (): Promise<void> => {
+      const grantSpentAmounts = mockOutgoingPaymentGrantSpentAmounts({
+        spentReceiveAmount: undefined
+      })
+
+      const scope = nock(serverAddress)
+        .get('/outgoing-payment-grant')
+        .reply(200, grantSpentAmounts)
+
+      const result = await getOutgoingPaymentGrantSpentAmounts(
+        deps,
+        {
+          url: serverAddress,
+          accessToken: 'accessToken'
+        },
+        openApiValidators.successfulValidator
+      )
+
+      expect(result).toEqual(grantSpentAmounts)
+      expect(result.spentDebitAmount).toBeDefined()
+      expect(result.spentReceiveAmount).toBeUndefined()
+      scope.done()
+    })
   })
 })

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

@@ -9,6 +9,7 @@ import {
   CreateOutgoingPaymentArgs,
   getRSPath,
   OutgoingPayment,
+  OutgoingPaymentGrantSpentAmounts,
   OutgoingPaymentPaginationResult,
   OutgoingPaymentWithSpentAmounts,
   PaginationArgs
@@ -26,6 +27,9 @@ export interface OutgoingPaymentRoutes {
     requestArgs: ResourceRequestArgs,
     createArgs: CreateOutgoingPaymentArgs
   ): Promise<OutgoingPaymentWithSpentAmounts>
+  getGrantSpentAmounts(
+    args: ResourceRequestArgs
+  ): Promise<OutgoingPaymentGrantSpentAmounts>
 }
 
 export const createOutgoingPaymentRoutes = (
@@ -36,6 +40,7 @@ export const createOutgoingPaymentRoutes = (
   let getOutgoingPaymentOpenApiValidator: ResponseValidator<OutgoingPayment>
   let listOutgoingPaymentOpenApiValidator: ResponseValidator<OutgoingPaymentPaginationResult>
   let createOutgoingPaymentOpenApiValidator: ResponseValidator<OutgoingPayment>
+  let getGrantSpentAmountsOpenApiValidator: ResponseValidator<OutgoingPaymentGrantSpentAmounts>
 
   if (openApi) {
     getOutgoingPaymentOpenApiValidator = openApi.createResponseValidator({
@@ -52,6 +57,11 @@ export const createOutgoingPaymentRoutes = (
       path: getRSPath('/outgoing-payments'),
       method: HttpMethod.POST
     })
+
+    getGrantSpentAmountsOpenApiValidator = openApi.createResponseValidator({
+      path: getRSPath('/outgoing-payment-grant'),
+      method: HttpMethod.GET
+    })
   }
 
   return {
@@ -77,6 +87,12 @@ export const createOutgoingPaymentRoutes = (
         requestArgs,
         createOutgoingPaymentOpenApiValidator,
         createArgs
+      ),
+    getGrantSpentAmounts: (requestArgs: ResourceRequestArgs) =>
+      getOutgoingPaymentGrantSpentAmounts(
+        baseDeps,
+        requestArgs,
+        getGrantSpentAmountsOpenApiValidator
       )
   }
 }
@@ -194,3 +210,21 @@ export const validateOutgoingPayment = (
 
   return payment
 }
+
+export const getOutgoingPaymentGrantSpentAmounts = async (
+  deps: BaseDeps,
+  requestArgs: ResourceRequestArgs,
+  validateOpenApiResponse: ResponseValidator<OutgoingPaymentGrantSpentAmounts>
+): Promise<OutgoingPaymentGrantSpentAmounts> => {
+  const { url: baseUrl, accessToken } = requestArgs
+  const url = `${baseUrl}${getRSPath('/outgoing-payment-grant')}`
+
+  return await get(
+    deps,
+    {
+      url,
+      accessToken
+    },
+    validateOpenApiResponse
+  )
+}