feat: add properties for quoting (#275)

* feat: add properties for quoting * fix: formatting * fix: types * fix: op package with new types * chore: add changeset * fix: tests * chore: remove fees, rename (max)sendAmount -> debit Amount * fix: build * fix: amount description * fix: generate types * fix: remaining `sendAmount`s * chore: versioning * fix: generate types * fix: server urls
interledger · Sep 6, 2023 · dd193c7 · dd193c7
1 parent 9fdba3e
commit dd193c7
Show file tree

Hide file tree

Showing 11 changed files with 135 additions and 153 deletions.
diff --git a/.changeset/tender-ravens-breathe.md b/.changeset/tender-ravens-breathe.md
@@ -0,0 +1,5 @@
+---
+'@interledger/open-payments': major
+---
+
+Adding properties for new quoting mechanism
diff --git a/openapi/auth-server.yaml b/openapi/auth-server.yaml
@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Open Payments Authorization Server
-  version: '1.0'
+  version: '1.1'
   license:
     name: Apache 2.0
     identifier: Apache-2.0
@@ -112,7 +112,7 @@ paths:
                         limits:
                           receiver: 'https://openpayments.guide/connections/45a0d0ee-26dc-4c66-89e0-01fbf93156f7'
                           interval: 'R12/2019-08-24T14:15:22Z/P1M'
-                          sendAmount:
+                          debitAmount:
                             value: '500'
                             assetCode: USD
                             assetScale: 2
@@ -180,7 +180,7 @@ paths:
                           limits:
                             receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2'
                             interval: 'R12/2019-08-24T14:15:22Z/P1M'
-                            sendAmount:
+                            debitAmount:
                               value: '500'
                               assetCode: USD
                               assetScale: 2
@@ -275,7 +275,7 @@ paths:
                           limits:
                             interval: 'R12/2019-08-24T14:15:22Z/P1M'
                             receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2'
-                            sendAmount:
+                            debitAmount:
                               value: '500'
                               assetCode: USD
                               assetScale: 2
@@ -515,9 +515,11 @@ components:
       properties:
         receiver:
           $ref: './schemas.yaml#/components/schemas/receiver'
-        sendAmount:
+        debitAmount:
+          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'
         receiveAmount:
+          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'
@@ -526,7 +528,7 @@ components:
             required:
               - interval
         - required:
-            - sendAmount
+            - debitAmount
         - required:
             - receiveAmount
   securitySchemes:

diff --git a/openapi/resource-server.yaml b/openapi/resource-server.yaml
diff --git a/openapi/schemas.yaml b/openapi/schemas.yaml
@@ -14,7 +14,6 @@ components:
     amount:
       title: amount
       type: object
-      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.'
       properties:
         value:
           type: string

diff --git a/packages/open-payments/README.md b/packages/open-payments/README.md
@@ -179,7 +179,7 @@ const quote = await client.quote.create(
   { receiver: incomingPayment.id }
 )
 
-// quote.sendAmount.value = '5200'
+// quote.debitAmount.value = '5200'
 ```
 
 5. Create `OutgoingPayment` grant & start interaction flow:

diff --git a/packages/open-payments/src/client/outgoing-payment.test.ts b/packages/open-payments/src/client/outgoing-payment.test.ts
@@ -62,7 +62,7 @@ describe('outgoing-payment', (): void => {
 
     test('throws if outgoing payment does not pass validation', async (): Promise<void> => {
       const outgoingPayment = mockOutgoingPayment({
-        sendAmount: {
+        debitAmount: {
           assetCode: 'USD',
           assetScale: 3,
           value: '5'
@@ -194,7 +194,7 @@ describe('outgoing-payment', (): void => {
 
     test('throws if an outgoing payment does not pass validation', async (): Promise<void> => {
       const invalidOutgoingPayment = mockOutgoingPayment({
-        sendAmount: {
+        debitAmount: {
           assetCode: 'CAD',
           assetScale: 2,
           value: '5'
@@ -291,7 +291,7 @@ describe('outgoing-payment', (): void => {
 
     test('throws if outgoing payment does not pass validation', async (): Promise<void> => {
       const outgoingPayment = mockOutgoingPayment({
-        sendAmount: {
+        debitAmount: {
           assetCode: 'USD',
           assetScale: 3,
           value: '5'
@@ -361,7 +361,7 @@ describe('outgoing-payment', (): void => {
 
     test('throws if send amount and sent amount asset scales are different', async (): Promise<void> => {
       const outgoingPayment = mockOutgoingPayment({
-        sendAmount: {
+        debitAmount: {
           assetCode: 'USD',
           assetScale: 3,
           value: '5'
@@ -380,7 +380,7 @@ describe('outgoing-payment', (): void => {
 
     test('throws if send amount and sent amount asset codes are different', async (): Promise<void> => {
       const outgoingPayment = mockOutgoingPayment({
-        sendAmount: {
+        debitAmount: {
           assetCode: 'CAD',
           assetScale: 2,
           value: '5'
@@ -399,7 +399,7 @@ describe('outgoing-payment', (): void => {
 
     test('throws if sent amount is larger than send amount', async (): Promise<void> => {
       const outgoingPayment = mockOutgoingPayment({
-        sendAmount: {
+        debitAmount: {
           assetCode: 'USD',
           assetScale: 2,
           value: '5'
@@ -418,7 +418,7 @@ describe('outgoing-payment', (): void => {
 
     test('throws if sent amount equals send amount, but payment has failed', async (): Promise<void> => {
       const outgoingPayment = mockOutgoingPayment({
-        sendAmount: {
+        debitAmount: {
           assetCode: 'USD',
           assetScale: 2,
           value: '5'

diff --git a/packages/open-payments/src/client/outgoing-payment.ts b/packages/open-payments/src/client/outgoing-payment.ts
@@ -176,19 +176,19 @@ export const listOutgoingPayments = async (
 export const validateOutgoingPayment = (
   payment: OutgoingPayment
 ): OutgoingPayment => {
-  const { sendAmount, sentAmount } = payment
+  const { debitAmount, sentAmount } = payment
   if (
-    sendAmount.assetCode !== sentAmount.assetCode ||
-    sendAmount.assetScale !== sentAmount.assetScale
+    debitAmount.assetCode !== sentAmount.assetCode ||
+    debitAmount.assetScale !== sentAmount.assetScale
   ) {
     throw new Error(
       'Asset code or asset scale of sending amount does not match sent amount'
     )
   }
-  if (BigInt(sendAmount.value) < BigInt(sentAmount.value)) {
+  if (BigInt(debitAmount.value) < BigInt(sentAmount.value)) {
     throw new Error('Amount sent is larger than maximum amount to send')
   }
-  if (sendAmount.value === sentAmount.value && payment.failed) {
+  if (debitAmount.value === sentAmount.value && payment.failed) {
     throw new Error('Amount to send matches sent amount but payment failed')
   }
 

diff --git a/packages/open-payments/src/openapi/generated/auth-server-types.ts b/packages/open-payments/src/openapi/generated/auth-server-types.ts
@@ -166,7 +166,9 @@ export interface components {
      */
     "limits-outgoing": Partial<unknown> & {
       receiver?: external["schemas.yaml"]["components"]["schemas"]["receiver"];
-      sendAmount?: external["schemas.yaml"]["components"]["schemas"]["amount"];
+      /** @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"];
+      /** @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"];
       interval?: components["schemas"]["interval"];
     };
@@ -312,10 +314,7 @@ export interface external {
     paths: {};
     components: {
       schemas: {
-        /**
-         * amount
-         * @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.
-         */
+        /** amount */
         amount: {
           /**
            * Format: uint64

diff --git a/packages/open-payments/src/openapi/generated/resource-server-types.ts b/packages/open-payments/src/openapi/generated/resource-server-types.ts
@@ -245,8 +245,8 @@ export interface components {
       receiver: external["schemas.yaml"]["components"]["schemas"]["receiver"];
       /** @description The total amount that should be received by the receiver when this outgoing payment has been paid. */
       receiveAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
-      /** @description The total amount that should be sent when this outgoing payment has been paid. */
-      sendAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
+      /** @description The total amount that should be deducted from the sender's account when this outgoing payment has been paid. */
+      debitAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
       /** @description The total amount that has been sent under this outgoing payment. */
       sentAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
       /** @description Additional metadata associated with the outgoing payment. (Optional) */
@@ -277,10 +277,13 @@ export interface components {
        * @description The URL of the payment pointer from which this quote's payment would be sent.
        */
       paymentPointer: string;
+      /** @description The URL of the incoming payment or ILP STREAM Connection that the quote is created for. */
       receiver: external["schemas.yaml"]["components"]["schemas"]["receiver"];
+      /** @description The total amount that should be received by the receiver when the corresponding outgoing payment has been paid. */
       receiveAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
-      sendAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
-      /** @description The date and time when the calculated `sendAmount` is no longer valid. */
+      /** @description The total amount that should be deducted from the sender's account when the corresponding outgoing payment has been paid. */
+      debitAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
+      /** @description The date and time when the calculated `debitAmount` is no longer valid. */
       expiresAt?: string;
       /**
        * Format: date-time
@@ -539,7 +542,7 @@ export interface operations {
     /**
      * A subset of the outgoing payments schema is accepted as input to create a new outgoing payment.
      *
-     * The `sendAmount` must use the same `assetCode` and `assetScale` as the payment pointer.
+     * The `debitAmount` must use the same `assetCode` and `assetScale` as the payment pointer.
      */
     requestBody: {
       content: {
@@ -580,7 +583,7 @@ export interface operations {
     /**
      * A subset of the quotes schema is accepted as input to create a new quote.
      *
-     * The quote must be created with a (`sendAmount` xor `receiveAmount`) unless the `receiver` is an Incoming Payment which has an `incomingAmount`.
+     * The quote must be created with a (`debitAmount` xor `receiveAmount`) unless the `receiver` is an Incoming Payment which has an `incomingAmount`.
      */
     requestBody: {
       content: {
@@ -596,7 +599,7 @@ export interface operations {
           | {
               receiver: external["schemas.yaml"]["components"]["schemas"]["receiver"];
               /** @description The fixed amount that would be sent from the sending payment pointer given a successful outgoing payment. */
-              sendAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
+              debitAmount: external["schemas.yaml"]["components"]["schemas"]["amount"];
             };
       };
     };
@@ -720,10 +723,7 @@ export interface external {
     paths: {};
     components: {
       schemas: {
-        /**
-         * amount
-         * @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.
-         */
+        /** amount */
         amount: {
           /**
            * Format: uint64

diff --git a/packages/open-payments/src/test/helpers.ts b/packages/open-payments/src/test/helpers.ts
@@ -154,7 +154,7 @@ export const mockOutgoingPayment = (
   id: `https://example.com/.well-known/pay/outgoing-payments/${uuid()}`,
   paymentPointer: 'https://example.com/.well-known/pay',
   failed: false,
-  sendAmount: {
+  debitAmount: {
     assetCode: 'USD',
     assetScale: 2,
     value: '10'
@@ -286,7 +286,7 @@ export const mockQuote = (overrides?: Partial<Quote>): Quote => ({
   id: `https://example.com/.well-known/pay/quotes/${uuid()}`,
   receiver: 'https://example.com/.well-known/peer',
   paymentPointer: 'https://example.com/.well-known/pay',
-  sendAmount: {
+  debitAmount: {
     value: '100',
     assetCode: 'USD',
     assetScale: 2

diff --git a/packages/open-payments/src/types.ts b/packages/open-payments/src/types.ts
@@ -51,16 +51,16 @@ export type Quote = RSComponents['schemas']['quote']
 type QuoteArgsBase = {
   receiver: RSOperations['create-quote']['requestBody']['content']['application/json']['receiver']
 }
-type QuoteArgsWithSendAmount = QuoteArgsBase & {
-  sendAmount?: RSComponents['schemas']['quote']['sendAmount']
+type QuoteArgsWithDebitAmount = QuoteArgsBase & {
+  debitAmount?: RSComponents['schemas']['quote']['debitAmount']
   receiveAmount?: never
 }
 type QuoteArgsWithReceiveAmount = QuoteArgsBase & {
-  sendAmount?: never
+  debitAmount?: never
   receiveAmount?: RSComponents['schemas']['quote']['receiveAmount']
 }
 export type CreateQuoteArgs =
-  | QuoteArgsWithSendAmount
+  | QuoteArgsWithDebitAmount
   | QuoteArgsWithReceiveAmount
 
 export const getASPath = <P extends keyof ASPaths>(path: P): string =>