@xyo-network/payment-plugin 4.2.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyo-network/payment-plugin",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "Typescript/Javascript Plugins for XYO Platform",
   "homepage": "https://xyo.network",
   "bugs": {
@@ -28,35 +28,39 @@
   },
   "module": "dist/neutral/index.mjs",
   "types": "dist/neutral/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
   "dependencies": {
-    "@xylabs/array": "^4.15.1",
-    "@xylabs/assert": "^4.15.1",
-    "@xylabs/exists": "^4.15.1",
-    "@xylabs/hex": "^4.15.1",
-    "@xyo-network/archivist-model": "^4.3.0",
-    "@xyo-network/diviner-abstract": "^4.3.0",
-    "@xyo-network/diviner-boundwitness-model": "^4.3.0",
-    "@xyo-network/diviner-hash-lease": "^4.3.0",
-    "@xyo-network/diviner-model": "^4.3.0",
-    "@xyo-network/module-model": "^4.3.0",
-    "@xyo-network/payload-builder": "^4.3.0",
-    "@xyo-network/payload-model": "^4.3.0",
-    "@xyo-network/payment-payload-plugins": "^4.2.0",
-    "@xyo-network/schema-payload-plugin": "^4.3.0",
-    "@xyo-network/xns-record-payload-plugins": "^4.2.0",
+    "@xylabs/array": "^5.0.0",
+    "@xylabs/assert": "^5.0.0",
+    "@xylabs/exists": "^5.0.0",
+    "@xylabs/hex": "^5.0.0",
+    "@xyo-network/archivist-model": "^5.0.0",
+    "@xyo-network/diviner-abstract": "^5.0.0",
+    "@xyo-network/diviner-boundwitness-model": "^5.0.0",
+    "@xyo-network/diviner-hash-lease": "^5.0.0",
+    "@xyo-network/diviner-model": "^5.0.0",
+    "@xyo-network/module-model": "^5.0.0",
+    "@xyo-network/payload-builder": "^5.0.0",
+    "@xyo-network/payload-model": "^5.0.0",
+    "@xyo-network/payment-payload-plugins": "^5.0.0",
+    "@xyo-network/schema-payload-plugin": "^5.0.0",
+    "@xyo-network/xns-record-payload-plugins": "^5.0.0",
     "ajv": "^8.17.1"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "^7.0.1",
-    "@xylabs/tsconfig": "^7.0.1",
-    "@xylabs/vitest-extended": "^4.15.1",
-    "@xyo-network/archivist-memory": "^4.3.0",
-    "@xyo-network/boundwitness-builder": "^4.3.0",
-    "@xyo-network/diviner-boundwitness-memory": "^4.3.0",
-    "@xyo-network/id-payload-plugin": "^4.3.0",
-    "@xyo-network/node-memory": "^4.3.0",
-    "@xyo-network/wallet": "^4.3.0",
-    "@xyo-network/wallet-model": "^4.3.0",
+    "@xylabs/ts-scripts-yarn3": "^7.0.2",
+    "@xylabs/tsconfig": "^7.0.2",
+    "@xylabs/vitest-extended": "^5.0.0",
+    "@xyo-network/archivist-memory": "^5.0.0",
+    "@xyo-network/boundwitness-builder": "^5.0.0",
+    "@xyo-network/diviner-boundwitness-memory": "^5.0.0",
+    "@xyo-network/id-payload-plugin": "^5.0.0",
+    "@xyo-network/node-memory": "^5.0.0",
+    "@xyo-network/wallet": "^5.0.0",
+    "@xyo-network/wallet-model": "^5.0.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },

package/src/Discount/lib/spec/applyCoupons.spec.ts

@@ -0,0 +1,104 @@
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { HashLeaseEstimateSchema } from '@xyo-network/diviner-hash-lease'
+import type { Coupon } from '@xyo-network/payment-payload-plugins'
+import {
+  DiscountSchema, FixedAmountCouponSchema, FixedPercentageCouponSchema,
+  FixedPriceCouponSchema,
+} from '@xyo-network/payment-payload-plugins'
+import {
+  beforeEach, describe, expect,
+  it, vi,
+} from 'vitest'
+
+import { applyCoupons } from '../applyCoupons.ts'
+
+describe('applyCoupons', () => {
+  const nbf = Date.now()
+  const exp = Date.now() + 10_000_000
+  // Coupons
+  const TEN_DOLLAR_OFF_COUPON: Coupon = {
+    amount: 10, exp, nbf, schema: FixedAmountCouponSchema, currency: 'USD',
+  }
+  const TEN_PERCENT_OFF_COUPON: Coupon = {
+    percentage: 0.1, exp, nbf, schema: FixedPercentageCouponSchema,
+  }
+  const TEN_DOLLAR_ITEM_COUPON: Coupon = {
+    amount: 10, exp, nbf, schema: FixedPriceCouponSchema, currency: 'USD',
+  }
+
+  // Appraisals
+  const HUNDRED_DOLLAR_ESTIMATE: HashLeaseEstimate = {
+    price: 100, currency: 'USD', exp, nbf, schema: HashLeaseEstimateSchema,
+  }
+  const SEVENTY_DOLLAR_ESTIMATE: HashLeaseEstimate = {
+    price: 70, currency: 'USD', exp, nbf, schema: HashLeaseEstimateSchema,
+  }
+  const THIRTY_DOLLAR_ESTIMATE: HashLeaseEstimate = {
+    price: 30, currency: 'USD', exp, nbf, schema: HashLeaseEstimateSchema,
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+  describe('when coupon is less than total', () => {
+    const validCoupons: [estimates: HashLeaseEstimate[], coupons: Coupon[], discount: number][] = [
+      // $100 item with $10 off coupon = $90 total/$10 discount
+      [[HUNDRED_DOLLAR_ESTIMATE], [TEN_DOLLAR_OFF_COUPON], 10],
+      // Two items (totalling $100) with $10 off coupon = $90 total/$10 discount
+      [[SEVENTY_DOLLAR_ESTIMATE, THIRTY_DOLLAR_ESTIMATE], [TEN_DOLLAR_OFF_COUPON], 10],
+      // $100 item with 10% off coupon = $90 total/$10 discount
+      [[HUNDRED_DOLLAR_ESTIMATE], [TEN_PERCENT_OFF_COUPON], 10],
+      // Two items (totalling $100) with 10% off coupon = $90 total/$10 discount
+      [[SEVENTY_DOLLAR_ESTIMATE, THIRTY_DOLLAR_ESTIMATE], [TEN_PERCENT_OFF_COUPON], 10],
+      // Two items (totalling $100) with 10% off coupon = $90 total/$10 discount
+      [[THIRTY_DOLLAR_ESTIMATE, SEVENTY_DOLLAR_ESTIMATE], [TEN_PERCENT_OFF_COUPON], 10],
+      // $100 item with $10 per item coupon = $10 total/$90 discount
+      [[HUNDRED_DOLLAR_ESTIMATE], [TEN_DOLLAR_ITEM_COUPON], 90],
+      // Two items (totalling $100) with $10 per item coupon = $20 total/$80 discount
+      [[SEVENTY_DOLLAR_ESTIMATE, THIRTY_DOLLAR_ESTIMATE], [TEN_DOLLAR_ITEM_COUPON], 80],
+      // Four items (totalling $200) with $10 per item coupon = $40 total/$160 discount
+      [[SEVENTY_DOLLAR_ESTIMATE, THIRTY_DOLLAR_ESTIMATE, SEVENTY_DOLLAR_ESTIMATE, THIRTY_DOLLAR_ESTIMATE], [TEN_DOLLAR_ITEM_COUPON], 160],
+    ]
+    it.each(validCoupons)('Applies coupon discount', (estimates, coupons, amount) => {
+      const results = applyCoupons(estimates, coupons)
+      expect(results).toEqual({
+        amount, schema: DiscountSchema, currency: 'USD',
+      })
+    })
+  })
+  describe('when discount exceeds total', () => {
+    const discountExceedsTotal: [HashLeaseEstimate[], Coupon[]][] = [
+      [
+        [HUNDRED_DOLLAR_ESTIMATE],
+        [{
+          amount: 101, exp, nbf, schema: FixedAmountCouponSchema, currency: 'USD',
+        }]],
+      [
+        [HUNDRED_DOLLAR_ESTIMATE],
+        [{
+          percentage: 1.1, exp, nbf, schema: FixedPercentageCouponSchema,
+        }]],
+    ]
+    it.each(discountExceedsTotal)('Discounts only to total', (estimates, coupons) => {
+      const results = applyCoupons(estimates, coupons)
+      const amount = estimates.reduce((acc, a) => acc + a.price, 0)
+      expect(results).toEqual({
+        amount, schema: DiscountSchema, currency: 'USD',
+      })
+    })
+  })
+  describe('with stackable discounts', () => {
+    const STACKABLE_TEN_DOLLAR_OFF_COUPON: Coupon = { ...TEN_DOLLAR_OFF_COUPON, stackable: true }
+    const STACKABLE_TEN_PERCENT_OFF_COUPON: Coupon = { ...TEN_PERCENT_OFF_COUPON, stackable: true }
+    const validCoupons: [HashLeaseEstimate[], Coupon[], number][] = [
+      [[HUNDRED_DOLLAR_ESTIMATE], [STACKABLE_TEN_DOLLAR_OFF_COUPON, STACKABLE_TEN_PERCENT_OFF_COUPON], 19],
+      [[HUNDRED_DOLLAR_ESTIMATE], [STACKABLE_TEN_PERCENT_OFF_COUPON, STACKABLE_TEN_DOLLAR_OFF_COUPON], 19],
+    ]
+    it.each(validCoupons)('Applies both discounts', (estimates, coupons, amount) => {
+      const results = applyCoupons(estimates, coupons)
+      expect(results).toEqual({
+        amount, schema: DiscountSchema, currency: 'USD',
+      })
+    })
+  })
+})

package/src/Discount/lib/spec/findUnfulfilledConditions.spec.ts

@@ -0,0 +1,243 @@
+import type { Address } from '@xylabs/hex'
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { HashLeaseEstimateSchema } from '@xyo-network/diviner-hash-lease'
+import type { Id } from '@xyo-network/id-payload-plugin'
+import { IdSchema } from '@xyo-network/id-payload-plugin'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type {
+  BuyerCondition,
+  Condition, Coupon, EscrowTerms,
+} from '@xyo-network/payment-payload-plugins'
+import {
+  createConditionForMaximumAppraisalAmount,
+  createConditionForMinimumAssetQuantity, createConditionForRequiredBuyer,
+  EscrowTermsSchema, FixedAmountCouponSchema,
+} from '@xyo-network/payment-payload-plugins'
+import type { SchemaPayload } from '@xyo-network/schema-payload-plugin'
+import { HDWallet } from '@xyo-network/wallet'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import {
+  beforeEach, describe, expect,
+  it,
+} from 'vitest'
+
+import { findUnfulfilledConditions } from '../findUnfulfilledConditions.ts'
+
+describe('findUnfulfilledConditions', () => {
+  const nbf = Date.now()
+  const exp = Date.now() + 10_000_000
+  // Coupons
+  const validCoupon: Coupon = {
+    amount: 10, exp, nbf, schema: FixedAmountCouponSchema, currency: 'USD',
+  }
+
+  // Conditions
+  const CONDITION_REQUIRES_BUYING_TWO: Condition = createConditionForMinimumAssetQuantity(2)
+  const CONDITION_REQUIRES_APPRAISAL_DOES_NOT_EXCEED_AMOUNT: Condition = createConditionForMaximumAppraisalAmount(20)
+  const CONDITION_FOR_SPECIFIC_BUYER: BuyerCondition = createConditionForRequiredBuyer('TODO: Replace in beforeAll' as Address)
+
+  const allConditions: SchemaPayload[] = [
+    CONDITION_REQUIRES_BUYING_TWO,
+    CONDITION_REQUIRES_APPRAISAL_DOES_NOT_EXCEED_AMOUNT,
+    CONDITION_FOR_SPECIFIC_BUYER,
+  ]
+
+  let buyer: WalletInstance
+  let seller: WalletInstance
+  const baseTerms: EscrowTerms = {
+    schema: EscrowTermsSchema, appraisals: [], exp, nbf,
+  }
+  const appraisal1: HashLeaseEstimate = {
+    schema: HashLeaseEstimateSchema, price: 10, currency: 'USD', exp, nbf,
+  }
+  const appraisal2: HashLeaseEstimate = {
+    schema: HashLeaseEstimateSchema, price: 20, currency: 'USD', exp, nbf,
+  }
+  const appraisals = [appraisal1, appraisal2]
+
+  const asset1: Id = { schema: IdSchema, salt: nbf.toString() }
+  const asset2: Id = { schema: IdSchema, salt: exp.toString() }
+  const assets = [asset1, asset2]
+
+  beforeEach(async () => {
+    buyer = await HDWallet.random()
+    seller = await HDWallet.random()
+
+    // Configure base terms
+    baseTerms.buyer = [buyer.address]
+    baseTerms.seller = [seller.address]
+    baseTerms.appraisals = await PayloadBuilder.dataHashes(appraisals)
+    baseTerms.assets = await PayloadBuilder.dataHashes(assets)
+
+    // Configure condition for specific buyer
+    CONDITION_FOR_SPECIFIC_BUYER.definition.contains.properties.buyer.items.const = buyer.address
+  })
+  describe('when all conditions are fulfilled', () => {
+    describe('returns empty array', () => {
+      it.each(allConditions)('for single condition', async (rule) => {
+        const conditions = [await PayloadBuilder.dataHash(rule)]
+        const coupon: Coupon = { ...validCoupon, conditions }
+        const terms: EscrowTerms = { ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)] }
+        const payloads = [terms, coupon, rule, ...assets, ...appraisals]
+        const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+        expect(results).toEqual([])
+      })
+      it('for multiple conditions', async () => {
+        const conditions = await PayloadBuilder.dataHashes(allConditions)
+        const coupon: Coupon = { ...validCoupon, conditions }
+        const terms: EscrowTerms = { ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)] }
+        const payloads = [terms, coupon, ...allConditions, ...assets, ...appraisals]
+        const results = await findUnfulfilledConditions(coupon, allConditions, payloads)
+        expect(results).toEqual([])
+      })
+    })
+  })
+  describe('when conditions are not fulfilled', () => {
+    describe('returns all unfulfilled condition hashes', () => {
+      describe('for maximum appraisal amount', () => {
+        const rule = CONDITION_REQUIRES_APPRAISAL_DOES_NOT_EXCEED_AMOUNT
+        it('when escrow terms do not exist', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const payloads = [coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms appraisals do not exist', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const terms: EscrowTerms = {
+            ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)], appraisals: undefined,
+          }
+          const payloads = [terms, coupon, rule, ...appraisals, ...assets]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms appraisals is empty', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const terms: EscrowTerms = {
+            ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)], appraisals: [],
+          }
+          const payloads = [terms, coupon, rule, ...appraisals, ...assets]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when appraisals not supplied', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const terms: EscrowTerms = { ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)] }
+          const payloads = [terms, coupon, rule, ...assets]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when supplied appraisal price exceeds the maximum amount', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const assets = [asset1]
+          const appraisal1: HashLeaseEstimate = {
+            schema: HashLeaseEstimateSchema, price: 1000, currency: 'USD', exp, nbf,
+          }
+          const appraisals = [appraisal1]
+          const terms: EscrowTerms = {
+            ...baseTerms,
+            discounts: [await PayloadBuilder.dataHash(coupon)],
+            assets: await PayloadBuilder.dataHashes(assets),
+            appraisals: await PayloadBuilder.dataHashes(appraisals),
+          }
+          const payloads = [terms, coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+      })
+      describe('for minimum purchase quantity', () => {
+        const rule = CONDITION_REQUIRES_BUYING_TWO
+        it('when escrow terms do not exist', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const payloads = [coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms assets do not exist', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const terms: EscrowTerms = {
+            ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)], assets: undefined,
+          }
+          const payloads = [terms, coupon, rule, ...appraisals, ...assets]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms assets is empty', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const terms: EscrowTerms = {
+            ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)], assets: [],
+          }
+          const payloads = [terms, coupon, rule, ...appraisals, ...assets]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms assets quantity does not exceed the required amount', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const assets = [asset1]
+          const terms: EscrowTerms = {
+            ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)], assets: await PayloadBuilder.dataHashes(assets),
+          }
+          const payloads = [terms, coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+      })
+      describe('for specific buyer', () => {
+        const rule = CONDITION_FOR_SPECIFIC_BUYER
+        it('when escrow terms do not exist', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const payloads = [coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms buyer does not exist', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const terms: EscrowTerms = {
+            ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)], buyer: undefined,
+          }
+          const payloads = [terms, coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms buyers is empty', async () => {
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const terms: EscrowTerms = {
+            ...baseTerms, discounts: [await PayloadBuilder.dataHash(coupon)], buyer: [],
+          }
+          const payloads = [terms, coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+        it('when escrow terms buyer does not contain specified address', async () => {
+          const buyer = await HDWallet.random()
+          const conditions = [await PayloadBuilder.dataHash(rule)]
+          const coupon: Coupon = { ...validCoupon, conditions }
+          const assets = [asset1]
+          const appraisals = [appraisal1]
+          const terms: EscrowTerms = {
+            ...baseTerms,
+            discounts: [await PayloadBuilder.dataHash(coupon)],
+            assets: await PayloadBuilder.dataHashes(assets),
+            appraisals: await PayloadBuilder.dataHashes(appraisals),
+            buyer: [buyer.address],
+          }
+          const payloads = [terms, coupon, rule, ...assets, ...appraisals]
+          const results = await findUnfulfilledConditions(coupon, [rule], payloads)
+          expect(results).toEqual(conditions)
+        })
+      })
+    })
+  })
+})

package/src/Discount/spec/Diviner.spec.ts

@@ -0,0 +1,128 @@
+import '@xylabs/vitest-extended'
+
+import { MemoryArchivist } from '@xyo-network/archivist-memory'
+import { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'
+import { MemoryBoundWitnessDiviner } from '@xyo-network/diviner-boundwitness-memory'
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { HashLeaseEstimateSchema } from '@xyo-network/diviner-hash-lease'
+import { MemoryNode } from '@xyo-network/node-memory'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { Coupon, EscrowTerms } from '@xyo-network/payment-payload-plugins'
+import {
+  DiscountSchema,
+  EscrowTermsSchema, FixedAmountCouponSchema, FixedPercentageCouponSchema,
+  isDiscount,
+  PaymentDiscountDivinerConfigSchema,
+} from '@xyo-network/payment-payload-plugins'
+import { HDWallet } from '@xyo-network/wallet'
+import {
+  beforeAll, beforeEach, describe, expect, it, vi,
+} from 'vitest'
+
+import { PaymentDiscountDiviner } from '../Diviner.ts'
+
+describe('PaymentDiscountDiviner', () => {
+  let sut: PaymentDiscountDiviner
+  const nbf = Date.now()
+  const exp = Number.MAX_SAFE_INTEGER
+  const termsBase: EscrowTerms = {
+    schema: EscrowTermsSchema, appraisals: [], exp, nbf,
+  }
+  const HUNDRED_DOLLAR_ESTIMATE: HashLeaseEstimate = {
+    price: 100, currency: 'USD', exp, nbf, schema: HashLeaseEstimateSchema,
+  }
+  const validCoupons: Coupon[] = [
+    {
+      amount: 10, exp, nbf: Date.now(), schema: FixedAmountCouponSchema, currency: 'USD',
+    },
+    {
+      percentage: 0.1, exp, nbf: Date.now(), schema: FixedPercentageCouponSchema,
+    },
+  ]
+  const unsignedCoupons: Coupon[] = [
+    {
+      amount: 10, exp: Number.MAX_SAFE_INTEGER, nbf: 0, schema: FixedAmountCouponSchema, currency: 'USD',
+    },
+    {
+      percentage: 0.1, exp: Number.MAX_SAFE_INTEGER, nbf: 0, schema: FixedPercentageCouponSchema,
+    },
+  ]
+  beforeAll(async () => {
+    termsBase.appraisals?.push(await PayloadBuilder.hash(HUNDRED_DOLLAR_ESTIMATE))
+    const node = await MemoryNode.create({ account: 'random' })
+    const archivist = await MemoryArchivist.create({ account: 'random' })
+    const signer = await HDWallet.random()
+    // Sign the valid coupons and insert them into the archivist
+    for (const coupon of validCoupons) {
+      const [bw, payloads] = await new BoundWitnessBuilder().signer(signer).payload(coupon).build()
+      await archivist.insert([bw, ...payloads])
+    }
+    // Insert (but do not sign) the unsigned coupons into the archivist
+    await archivist.insert(unsignedCoupons)
+    const boundWitnessDiviner = await MemoryBoundWitnessDiviner.create({
+      account: 'random',
+      config: {
+        archivist: archivist.address,
+        schema: MemoryBoundWitnessDiviner.defaultConfigSchema,
+      },
+    })
+    sut = await PaymentDiscountDiviner.create({
+      account: 'random',
+      config: {
+        archivist: archivist.address,
+        boundWitnessDiviner: boundWitnessDiviner.address,
+        couponAuthorities: [signer.address],
+        schema: PaymentDiscountDivinerConfigSchema,
+      },
+    })
+    const modules = [archivist, boundWitnessDiviner, sut]
+    for (const mod of modules) {
+      await node.register(mod)
+      await node.attach(mod.address, false)
+    }
+  })
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+  describe('with valid coupon', () => {
+    it.each(validCoupons)('Applies coupon', async (coupon) => {
+      const terms = { ...termsBase, discounts: [await PayloadBuilder.dataHash(coupon)] }
+      const results = await sut.divine([terms, HUNDRED_DOLLAR_ESTIMATE, coupon])
+      expect(results).toBeArrayOfSize(1)
+      const result = results.find(isDiscount)
+      expect(result).toBeDefined()
+      expect(result).toMatchObject({ amount: 10, schema: DiscountSchema })
+    })
+  })
+  describe('with invalid coupon', () => {
+    it.each(unsignedCoupons)('Does not apply coupons', async (coupon) => {
+      const terms = { ...termsBase, discounts: [await PayloadBuilder.dataHash(coupon)] }
+      const results = await sut.divine([terms, HUNDRED_DOLLAR_ESTIMATE, coupon])
+      expect(results).toBeArrayOfSize(1)
+      const result = results.find(isDiscount)
+      expect(result).toBeDefined()
+      expect(result).toMatchObject({ amount: 0, schema: DiscountSchema })
+    })
+  })
+  describe('with expired coupon', () => {
+    const now = Date.now()
+    const expiredCoupons: Coupon[] = [
+      // In past
+      {
+        amount: 10, exp: now, nbf: 0, schema: FixedAmountCouponSchema, currency: 'USD',
+      },
+      // In future
+      {
+        percentage: 0.1, exp: now + 100_000_000, nbf: now + 10_000_000, schema: FixedPercentageCouponSchema,
+      },
+    ]
+    it.each(expiredCoupons)('Does not apply coupons', async (coupon) => {
+      const terms = { ...termsBase, discounts: [await PayloadBuilder.dataHash(coupon)] }
+      const results = await sut.divine([terms, HUNDRED_DOLLAR_ESTIMATE, coupon])
+      expect(results).toBeArrayOfSize(1)
+      const result = results.find(isDiscount)
+      expect(result).toBeDefined()
+      expect(result).toMatchObject({ amount: 0, schema: DiscountSchema })
+    })
+  })
+})

package/src/Invoice/spec/getInvoiceForEscrow.spec.ts

@@ -0,0 +1,94 @@
+import '@xylabs/vitest-extended'
+
+import { assertEx } from '@xylabs/assert'
+import { MemoryArchivist } from '@xyo-network/archivist-memory'
+import { MemoryBoundWitnessDiviner } from '@xyo-network/diviner-boundwitness-memory'
+import { BoundWitnessDivinerConfigSchema } from '@xyo-network/diviner-boundwitness-model'
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { HashLeaseEstimateSchema } from '@xyo-network/diviner-hash-lease'
+import { MemoryNode } from '@xyo-network/node-memory'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { EscrowTerms } from '@xyo-network/payment-payload-plugins'
+import { EscrowTermsSchema, NO_DISCOUNT } from '@xyo-network/payment-payload-plugins'
+import {
+  beforeAll,
+  describe, expect, it,
+} from 'vitest'
+
+import { PaymentDiscountDiviner } from '../../Discount/index.ts'
+import { PaymentSubtotalDiviner } from '../../Subtotal/index.ts'
+import { PaymentTotalDiviner } from '../../Total/index.ts'
+import { getInvoiceForEscrow } from '../getInvoiceForEscrow.ts'
+
+describe('getInvoiceForEscrow', () => {
+  let node: MemoryNode
+  let paymentTotalDiviner: PaymentTotalDiviner
+  beforeAll(async () => {
+    node = await MemoryNode.create({ account: 'random' })
+    const discountsArchivist = await MemoryArchivist.create({ account: 'random' })
+    const discountsBoundWitnessDiviner = await MemoryBoundWitnessDiviner.create({
+      account: 'random',
+      config: { archivist: discountsArchivist.address, schema: BoundWitnessDivinerConfigSchema },
+    })
+    const paymentDiscountDiviner = await PaymentDiscountDiviner.create({
+      account: 'random',
+      config: {
+        archivist: discountsArchivist.address,
+        boundWitnessDiviner: discountsBoundWitnessDiviner.address,
+        schema: PaymentDiscountDiviner.defaultConfigSchema,
+      },
+    })
+    const paymentSubtotalDiviner = await PaymentSubtotalDiviner.create({ account: 'random' })
+    paymentTotalDiviner = await PaymentTotalDiviner.create({
+      account: 'random',
+      config: {
+        paymentDiscountDiviner: paymentDiscountDiviner.address,
+        paymentSubtotalDiviner: paymentSubtotalDiviner.address,
+        schema: PaymentTotalDiviner.defaultConfigSchema,
+      },
+    })
+    const modules = [
+      discountsArchivist,
+      discountsBoundWitnessDiviner,
+      paymentDiscountDiviner,
+      paymentSubtotalDiviner,
+      paymentTotalDiviner]
+    for (const module of modules) {
+      await node.register(module)
+      await node.attach(module.address, true)
+    }
+  })
+  describe('with no discount', () => {
+    it('should return invoice values', async () => {
+      const nbf = Date.now()
+      const exp = nbf + 1000 * 60 * 10
+      const appraisal: HashLeaseEstimate = {
+        price: 10, currency: 'USD', schema: HashLeaseEstimateSchema, exp, nbf,
+      }
+      const appraisalHash = await PayloadBuilder.dataHash(appraisal)
+      const terms: EscrowTerms = {
+        schema: EscrowTermsSchema, appraisals: [appraisalHash], exp, nbf,
+      }
+      const dataHashMap = await PayloadBuilder.toDataHashMap([appraisal])
+      const result = await getInvoiceForEscrow(terms, dataHashMap, paymentTotalDiviner)
+      expect(result).toBeArray()
+      expect(result?.length).toBeGreaterThan(0)
+      const invoice = assertEx(result)
+      const [subtotal, total, payment, discount] = invoice
+      expect(subtotal).toBeDefined()
+      expect(subtotal.amount).toBeNumber()
+      expect(subtotal.amount).toBe(appraisal.price)
+      expect(subtotal.currency).toBe('USD')
+      expect(total).toBeDefined()
+      expect(total.amount).toBeNumber()
+      expect(total.amount).toBe(subtotal.amount)
+      expect(total.currency).toBe('USD')
+      expect(payment).toBeDefined()
+      expect(payment.amount).toBeNumber()
+      expect(payment.amount).toBe(total.amount)
+      expect(payment.currency).toBe('USD')
+      expect(discount).toBeDefined()
+      expect(discount).toMatchObject(NO_DISCOUNT)
+    })
+  })
+})

package/src/Subtotal/spec/Diviner.spec.ts

@@ -0,0 +1,113 @@
+import '@xylabs/vitest-extended'
+
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { HashLeaseEstimateSchema } from '@xyo-network/diviner-hash-lease'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { EscrowTerms } from '@xyo-network/payment-payload-plugins'
+import {
+  EscrowTermsSchema,
+  isSubtotal,
+  SubtotalSchema,
+} from '@xyo-network/payment-payload-plugins'
+import {
+  beforeAll, beforeEach, describe, expect,
+  it, vi,
+} from 'vitest'
+
+import { PaymentSubtotalDiviner } from '../Diviner.ts'
+
+describe('PaymentSubtotalDiviner', () => {
+  let sut: PaymentSubtotalDiviner
+  const nbf = Date.now()
+  const exp = Number.MAX_SAFE_INTEGER
+  const termsBase: EscrowTerms = {
+    schema: EscrowTermsSchema, appraisals: [], exp, nbf,
+  }
+  const cases: [estimates: HashLeaseEstimate[], subtotal: number][] = [
+    [
+      [
+        {
+          schema: HashLeaseEstimateSchema, price: 1, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 10, currency: 'USD', exp, nbf,
+        },
+      ], 11],
+    [
+      [
+        {
+          schema: HashLeaseEstimateSchema, price: 10, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 20, currency: 'USD', exp, nbf,
+        },
+      ], 30],
+    [
+      [
+        {
+          schema: HashLeaseEstimateSchema, price: 100, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 100, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 100, currency: 'USD', exp, nbf,
+        },
+      ], 300],
+  ]
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+  beforeAll(async () => {
+    sut = await PaymentSubtotalDiviner.create({ account: 'random' })
+  })
+  describe('with escrow terms containing valid appraisals', () => {
+    it.each(cases)('calculates the subtotal of all the appraisals', async (appraisals, total) => {
+      const appraisalHashes = await PayloadBuilder.dataHashes(appraisals)
+      const terms: EscrowTerms = { ...termsBase, appraisals: appraisalHashes }
+      const results = await sut.divine([terms, ...appraisals])
+      expect(results).toBeArrayOfSize(1)
+      const result = results.find(isSubtotal)
+      expect(result).toBeDefined()
+      expect(result).toMatchObject({ amount: total, schema: SubtotalSchema })
+      expect(result?.$sources).toEqual([await PayloadBuilder.dataHash(terms), ...appraisalHashes])
+    })
+  })
+  describe('with escrow terms containing invalid appraisals', () => {
+    describe('when containing negative values in appraisals', () => {
+      it('calculates the subtotal of all the appraisals', async () => {
+        const appraisals = [{
+          schema: HashLeaseEstimateSchema, price: -1, currency: 'USD', exp, nbf,
+        }]
+        const appraisalHashes = await PayloadBuilder.dataHashes(appraisals)
+        const terms: EscrowTerms = { ...termsBase, appraisals: appraisalHashes }
+        const results = await sut.divine([terms, ...appraisals])
+        expect(results).toBeArrayOfSize(0)
+      })
+    })
+    describe('when containing non-numeric values in appraisals', () => {
+      it('calculates the subtotal of all the appraisals', async () => {
+        const appraisals = [{
+          schema: HashLeaseEstimateSchema, price: 'three dollars', currency: 'USD', exp, nbf,
+        }]
+        const appraisalHashes = await PayloadBuilder.dataHashes(appraisals)
+        const terms: EscrowTerms = { ...termsBase, appraisals: appraisalHashes }
+        const results = await sut.divine([terms, ...appraisals])
+        expect(results).toBeArrayOfSize(0)
+      })
+    })
+    describe('when containing mixed currencies in appraisals', () => {
+      it('calculates the subtotal of all the appraisals', async () => {
+        const appraisals = [{
+          schema: HashLeaseEstimateSchema, price: 1, currency: 'USD', exp, nbf,
+        }, {
+          schema: HashLeaseEstimateSchema, price: 1, currency: 'EUR', exp, nbf,
+        }]
+        const appraisalHashes = await PayloadBuilder.dataHashes(appraisals)
+        const terms: EscrowTerms = { ...termsBase, appraisals: appraisalHashes }
+        const results = await sut.divine([terms, ...appraisals])
+        expect(results).toBeArrayOfSize(0)
+      })
+    })
+  })
+})

package/src/Total/spec/Diviner.spec.ts

@@ -0,0 +1,173 @@
+import '@xylabs/vitest-extended'
+
+import { MemoryArchivist } from '@xyo-network/archivist-memory'
+import { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'
+import { MemoryBoundWitnessDiviner } from '@xyo-network/diviner-boundwitness-memory'
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { HashLeaseEstimateSchema } from '@xyo-network/diviner-hash-lease'
+import { MemoryNode } from '@xyo-network/node-memory'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { Coupon, EscrowTerms } from '@xyo-network/payment-payload-plugins'
+import {
+  EscrowTermsSchema,
+  FixedAmountCouponSchema, FixedPercentageCouponSchema, isTotal,
+  TotalSchema,
+} from '@xyo-network/payment-payload-plugins'
+import { HDWallet } from '@xyo-network/wallet'
+import {
+  beforeAll, beforeEach, describe, expect,
+  it, vi,
+} from 'vitest'
+
+import { PaymentDiscountDiviner } from '../../Discount/index.ts'
+import { PaymentSubtotalDiviner } from '../../Subtotal/index.ts'
+import { PaymentTotalDiviner } from '../Diviner.ts'
+
+describe('PaymentTotalDiviner', () => {
+  let sut: PaymentTotalDiviner
+  const nbf = Date.now()
+  const exp = nbf + 1000 * 60 * 10
+  const termsBase: EscrowTerms = {
+    schema: EscrowTermsSchema, appraisals: [], exp, nbf,
+  }
+  const cases: [estimates: HashLeaseEstimate[], subtotal: number][] = [
+    [
+      [
+        {
+          schema: HashLeaseEstimateSchema, price: 1, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 10, currency: 'USD', exp, nbf,
+        },
+      ], 11],
+    [
+      [
+        {
+          schema: HashLeaseEstimateSchema, price: 10, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 20, currency: 'USD', exp, nbf,
+        },
+      ], 30],
+    [
+      [
+        {
+          schema: HashLeaseEstimateSchema, price: 100, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 100, currency: 'USD', exp, nbf,
+        },
+        {
+          schema: HashLeaseEstimateSchema, price: 100, currency: 'USD', exp, nbf,
+        },
+      ], 300],
+  ]
+  const validCoupons: Coupon[] = [
+    {
+      amount: 10, exp, nbf: Date.now(), schema: FixedAmountCouponSchema, currency: 'USD',
+    },
+    {
+      percentage: 0.1, exp, nbf: Date.now(), schema: FixedPercentageCouponSchema,
+    },
+  ]
+  const unsignedCoupons: Coupon[] = [
+    {
+      amount: 10, exp: Number.MAX_SAFE_INTEGER, nbf: 0, schema: FixedAmountCouponSchema, currency: 'USD',
+    },
+    {
+      percentage: 0.1, exp: Number.MAX_SAFE_INTEGER, nbf: 0, schema: FixedPercentageCouponSchema,
+    },
+  ]
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+  beforeAll(async () => {
+    const node = await MemoryNode.create({ account: 'random' })
+    expect(node).toBeDefined()
+    const paymentSubtotalDiviner = await PaymentSubtotalDiviner.create({ account: 'random' })
+    const discountsArchivist = await MemoryArchivist.create({ account: 'random' })
+    const signer = await HDWallet.random()
+    // Sign the valid coupons and insert them into the archivist
+    for (const coupon of validCoupons) {
+      const [bw, payloads] = await new BoundWitnessBuilder().signer(signer).payload(coupon).build()
+      await discountsArchivist.insert([bw, ...payloads])
+    }
+    // Insert (but do not sign) the unsigned coupons into the archivist
+    await discountsArchivist.insert(unsignedCoupons)
+    const discountsBoundWitnessDiviner = await MemoryBoundWitnessDiviner.create({
+      account: 'random',
+      config: {
+        archivist: discountsArchivist.address,
+        schema: MemoryBoundWitnessDiviner.defaultConfigSchema,
+      },
+    })
+    const discountDiviner = await PaymentDiscountDiviner.create({
+      account: 'random',
+      config: {
+        archivist: discountsArchivist.address,
+        boundWitnessDiviner: discountsBoundWitnessDiviner.address,
+        couponAuthorities: [signer.address],
+        schema: PaymentDiscountDiviner.defaultConfigSchema,
+      },
+    })
+    sut = await PaymentTotalDiviner.create({
+      account: 'random',
+      config: {
+        paymentDiscountDiviner: discountDiviner.address,
+        paymentSubtotalDiviner: paymentSubtotalDiviner.address,
+        schema: PaymentTotalDiviner.defaultConfigSchema,
+      },
+    })
+
+    const modules = [paymentSubtotalDiviner, discountsArchivist, discountsBoundWitnessDiviner, discountDiviner, sut]
+    for (const mod of modules) {
+      await node.register(mod)
+      await node.attach(mod.address, true)
+    }
+  })
+  describe('with valid escrow', () => {
+    describe('with no discounts', () => {
+      it.each(cases)('calculates total', async (appraisals, total) => {
+        const appraisalHashes = await PayloadBuilder.dataHashes(appraisals)
+        const terms: EscrowTerms = { ...termsBase, appraisals: appraisalHashes }
+        const results = await sut.divine([terms, ...appraisals])
+        expect(results).toBeArrayOfSize(3)
+        const result = results.find(isTotal)
+        expect(result).toBeDefined()
+        expect(result).toMatchObject({ amount: total, schema: TotalSchema })
+      })
+    })
+    describe('with valid discounts', () => {
+      describe.each(cases)('calculates total', (appraisals, total) => {
+        it.each(validCoupons)('applying coupon discount to total', async (coupon) => {
+          const discounts = await PayloadBuilder.dataHashes([coupon])
+          const appraisalHashes = await PayloadBuilder.dataHashes(appraisals)
+          const terms: EscrowTerms = {
+            ...termsBase, appraisals: appraisalHashes, discounts,
+          }
+          const results = await sut.divine([terms, ...appraisals, coupon])
+          expect(results).toBeArrayOfSize(3)
+          const result = results.find(isTotal)
+          expect(result).toBeDefined()
+          expect(result?.amount).toBeLessThan(total)
+        })
+      })
+    })
+    describe('with invalid discounts', () => {
+      describe.each(cases)('calculates total', (appraisals, total) => {
+        it.each(unsignedCoupons)('without applying coupon discount to total', async (coupon) => {
+          const discounts = await PayloadBuilder.dataHashes([coupon])
+          const appraisalHashes = await PayloadBuilder.dataHashes(appraisals)
+          const terms: EscrowTerms = {
+            ...termsBase, appraisals: appraisalHashes, discounts,
+          }
+          const results = await sut.divine([terms, ...appraisals, coupon])
+          expect(results).toBeArrayOfSize(3)
+          const result = results.find(isTotal)
+          expect(result).toBeDefined()
+          expect(result).toMatchObject({ amount: total, schema: TotalSchema })
+        })
+      })
+    })
+  })
+})

package/typedoc.json

@@ -1,5 +0,0 @@
-{
-  "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["./src/index.ts"],
-  "tsconfig": "./tsconfig.typedoc.json"
-}

package/xy.config.ts

@@ -1,10 +0,0 @@
-import type { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
-const config: XyTsupConfig = {
-  compile: {
-    browser: {},
-    node: {},
-    neutral: { src: true },
-  },
-}
-
-export default config