@xyo-network/payment-plugin 3.0.18

package/src/Discount/lib/applyCoupons.ts

@@ -0,0 +1,58 @@
+import { assertEx } from '@xylabs/assert'
+import { exists } from '@xylabs/exists'
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import type {
+  AmountFields,
+  Coupon, Discount, FixedAmountCoupon,
+  FixedPercentageCoupon,
+} from '@xyo-network/payment-payload-plugins'
+import {
+  DiscountSchema, isFixedAmountCoupon, isFixedPercentageCoupon,
+  isStackable,
+} from '@xyo-network/payment-payload-plugins'
+
+export const applyCoupons = (appraisals: HashLeaseEstimate[], coupons: Coupon[]): Discount => {
+  // Ensure all appraisals and coupons are in USD
+  const allAppraisalsAreUSD = appraisals.every(appraisal => appraisal.currency === 'USD')
+  assertEx(allAppraisalsAreUSD, 'All appraisals must be in USD')
+  const allCouponsAreUSD = coupons.map(coupon => (coupon as Partial<AmountFields>)?.currency).filter(exists).every(currency => currency === 'USD')
+  assertEx(allCouponsAreUSD, 'All coupons must be in USD')
+  const total = appraisals.reduce((acc, appraisal) => acc + appraisal.price, 0)
+
+  // Calculated non-stackable discount coupons
+  const singularFixedDiscount = Math.max(...coupons
+    .filter(coupon => isFixedAmountCoupon(coupon) && !isStackable(coupon))
+    .map(coupon => (coupon as FixedAmountCoupon).amount), 0)
+  const singularPercentageDiscount = (Math.max(...coupons
+    .filter(coupon => isFixedPercentageCoupon(coupon) && !isStackable(coupon))
+    .map(coupon => (coupon as FixedPercentageCoupon).percentage), 0)) * total
+
+  // Calculate stackable discount coupons
+  // First calculate the total discount from fixed amount coupons
+  const stackedFixedDiscount = coupons
+    .filter(coupon => isFixedAmountCoupon(coupon) && isStackable(coupon))
+    .reduce((acc, coupon) => acc + (coupon as FixedAmountCoupon).amount, 0)
+  // Then calculate the total discount from percentage coupons and apply
+  // the percentage discount to the remaining total after fixed discounts
+  const stackedPercentageDiscount = coupons
+    .filter(coupon => isFixedPercentageCoupon(coupon) && isStackable(coupon))
+    .reduce((acc, coupon) => acc + (coupon as FixedPercentageCoupon).percentage, 0) * (total - stackedFixedDiscount)
+  // Sum all stackable discounts
+  const stackedDiscount = stackedFixedDiscount + stackedPercentageDiscount
+
+  // Find the best coupon(s) to apply
+  const maxDiscount = Math.max(
+    singularFixedDiscount,
+    singularPercentageDiscount,
+    stackedDiscount,
+    0,
+  )
+
+  // Ensure discount is not more than the total
+  const amount = Math.min(maxDiscount, total)
+
+  // Return single discount payload
+  return {
+    amount, schema: DiscountSchema, currency: 'USD',
+  }
+}

package/src/Discount/lib/index.ts

@@ -0,0 +1 @@
+export * from './applyCoupons.ts'

package/src/Invoice/getInvoiceForEscrow.ts

@@ -0,0 +1,39 @@
+import type { Hash } from '@xylabs/hex'
+import type { DivinerInstance } from '@xyo-network/diviner-model'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { Payload } from '@xyo-network/payload-model'
+import type {
+  Discount, EscrowTerms, Invoice, Payment, Subtotal, Total,
+} from '@xyo-network/payment-payload-plugins'
+import {
+  isDiscount, isSubtotal, isTotal, PaymentSchema,
+} from '@xyo-network/payment-payload-plugins'
+
+/**
+ * Validates the escrow terms to ensure they are valid for a purchase
+ * @returns A payment if the terms are valid for a purchase, undefined otherwise
+ */
+export const getInvoiceForEscrow = async (
+  terms: EscrowTerms,
+  dataHashMap: Record<Hash, Payload>,
+  paymentTotalDiviner: DivinerInstance,
+): Promise<Invoice | undefined> => {
+  const payloads = Object.values(dataHashMap)
+  const results = await paymentTotalDiviner.divine([terms, ...payloads])
+  const subtotal = results.find(isSubtotal) as Subtotal | undefined
+  const discount = results.find(isDiscount) as Discount | undefined
+  const total = results.find(isTotal) as Total | undefined
+  if (!subtotal || !total) return undefined
+  const { amount, currency } = total
+  if (currency !== 'USD') return undefined
+  const sources = await getSources(terms, subtotal, total, discount)
+  const payment: Payment = {
+    amount, currency, schema: PaymentSchema, sources,
+  }
+  return discount ? [subtotal, total, payment, discount] : [subtotal, total, payment]
+}
+
+const getSources = async (terms: EscrowTerms, subtotal: Subtotal, total: Total, discount?: Discount): Promise<Hash[]> => {
+  const sources = discount ? [terms, subtotal, total, discount] : [terms, subtotal, total]
+  return await Promise.all(sources.map(p => PayloadBuilder.dataHash(p)))
+}

package/src/Invoice/index.ts

@@ -0,0 +1 @@
+export * from './getInvoiceForEscrow.ts'

package/src/Subtotal/Diviner.ts

@@ -0,0 +1,65 @@
+import { AbstractDiviner } from '@xyo-network/diviner-abstract'
+import { HashLeaseEstimate, isHashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { DivinerInstance, DivinerModuleEventData } from '@xyo-network/diviner-model'
+import { creatableModule } from '@xyo-network/module-model'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import { Payload } from '@xyo-network/payload-model'
+import {
+  EscrowTerms, isEscrowTerms, PaymentSubtotalDivinerConfigSchema, PaymentSubtotalDivinerParams, Subtotal, SubtotalSchema,
+} from '@xyo-network/payment-payload-plugins'
+
+import {
+  appraisalValidators, termsValidators, ValidEscrowTerms,
+} from './lib/index.ts'
+
+const currency = 'USD'
+
+/**
+ * Escrow terms that contain all the valid fields for calculating a subtotal
+ */
+export type PaymentSubtotalDivinerInputType = EscrowTerms | HashLeaseEstimate | Payload
+
+@creatableModule()
+export class PaymentSubtotalDiviner<
+  TParams extends PaymentSubtotalDivinerParams = PaymentSubtotalDivinerParams,
+  TIn extends PaymentSubtotalDivinerInputType = PaymentSubtotalDivinerInputType,
+  TOut extends Subtotal = Subtotal,
+  TEventData extends DivinerModuleEventData<DivinerInstance<TParams, TIn, TOut>, TIn, TOut> = DivinerModuleEventData<
+    DivinerInstance<TParams, TIn, TOut>,
+    TIn,
+    TOut
+  >,
+> extends AbstractDiviner<TParams, TIn, TOut, TEventData> {
+  static override configSchemas = [PaymentSubtotalDivinerConfigSchema]
+  static override defaultConfigSchema = PaymentSubtotalDivinerConfigSchema
+
+  protected async divineHandler(payloads: TIn[] = []): Promise<TOut[]> {
+    // Find the escrow terms
+    const terms = payloads.find(isEscrowTerms) as EscrowTerms | undefined
+    if (!terms) return []
+
+    // Run all terms validations
+    if (!termsValidators.every(validator => validator(terms))) return []
+    const validTerms = terms as ValidEscrowTerms
+
+    // Retrieve all appraisals from terms
+    const hashMap = await PayloadBuilder.toAllHashMap(payloads)
+    const appraisals = validTerms.appraisals.map(appraisal => hashMap[appraisal]).filter(isHashLeaseEstimate) as unknown as HashLeaseEstimate[]
+
+    // Ensure all appraisals are present
+    if (appraisals.length !== validTerms.appraisals.length) return []
+
+    // Run all appraisal validations
+    if (!appraisalValidators.every(validator => validator(appraisals))) return []
+    const amount = calculateSubtotal(appraisals)
+    const sources = [await PayloadBuilder.dataHash(validTerms), ...validTerms.appraisals]
+    return [{
+      amount, currency, schema: SubtotalSchema, sources,
+    }] as TOut[]
+  }
+}
+
+// TODO: Add support for other currencies
+const calculateSubtotal = (appraisals: HashLeaseEstimate[]): number => {
+  return appraisals.reduce((sum, appraisal) => sum + appraisal.price, 0)
+}

package/src/Subtotal/index.ts

@@ -0,0 +1 @@
+export * from './Diviner.ts'

package/src/Subtotal/lib/appraisalValidators.ts

@@ -0,0 +1,45 @@
+import type { HashLeaseEstimate } from '@xyo-network/diviner-hash-lease'
+import { isIso4217CurrencyCode } from '@xyo-network/payment-payload-plugins'
+
+import { validateDuration } from './durationValidators.ts'
+
+const validateAppraisalAmount = (appraisals: HashLeaseEstimate[]): boolean => {
+  // Ensure all appraisals are numeric
+  if (appraisals.some(appraisal => typeof appraisal.price !== 'number')) return false
+  // Ensure all appraisals are positive numbers
+  if (appraisals.some(appraisal => appraisal.price < 0)) return false
+  return true
+}
+
+const validateAppraisalCurrency = (appraisals: HashLeaseEstimate[]): boolean => {
+  // NOTE: Only supporting USD for now, the remaining checks are for future-proofing.
+  if (!appraisals.every(appraisal => appraisal.currency == 'USD')) return false
+
+  // Check every object in the array to ensure they all are in a supported currency.
+  if (!appraisals.every(appraisal => isIso4217CurrencyCode(appraisal.currency))) return false
+
+  return true
+}
+
+const validateAppraisalConsistentCurrency = (appraisals: HashLeaseEstimate[]): boolean => {
+  // Check if the array is empty or contains only one element, no need to compare.
+  if (appraisals.length <= 1) return true
+
+  // Get the currency of the first element to compare with others.
+  const { currency } = appraisals[0]
+  if (!currency) return false
+
+  // Check every object in the array to ensure they all have the same currency.
+  if (!appraisals.every(item => item.currency === currency)) return false
+
+  return true
+}
+
+const validateAppraisalWindow = (appraisals: HashLeaseEstimate[]): boolean => appraisals.every(validateDuration)
+
+export const appraisalValidators = [
+  validateAppraisalAmount,
+  validateAppraisalCurrency,
+  validateAppraisalConsistentCurrency,
+  validateAppraisalWindow,
+]

package/src/Subtotal/lib/durationValidators.ts

@@ -0,0 +1,18 @@
+import type { DurationFields } from '@xyo-network/xns-record-payload-plugins'
+
+const FIVE_MINUTES = 1000 * 60 * 5
+
+/**
+ * Validates that the current time is within the duration window, within a configurable a buffer
+ * @param value The duration value
+ * @param windowMs The window in milliseconds to allow for a buffer
+ * @returns True if the duration is valid, false otherwise
+ */
+export const validateDuration = (value: Partial<DurationFields>, windowMs = FIVE_MINUTES): boolean => {
+  const now = Date.now()
+  if (!value.nbf || value.nbf > now) return false
+  // If already expired (include for a 5 minute buffer to allow for a reasonable
+  // minimum amount of time for the transaction to be processed)
+  if (!value.exp || value.exp - now < windowMs) return false
+  return true
+}

package/src/Subtotal/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './appraisalValidators.ts'
+export * from './termsValidators.ts'

package/src/Subtotal/lib/termsValidators.ts

@@ -0,0 +1,18 @@
+import type { Hash } from '@xylabs/hex'
+import type { EscrowTerms } from '@xyo-network/payment-payload-plugins'
+
+import { validateDuration } from './durationValidators.ts'
+
+export type ValidEscrowTerms = Required<EscrowTerms>
+
+const validateTermsAppraisals = (terms: EscrowTerms): terms is Required<EscrowTerms & { appraisals: Hash[] }> => {
+  if (!terms.appraisals) return false
+  if (terms.appraisals.length === 0) return false
+  return true
+}
+const validateTermsWindow = (terms: EscrowTerms): boolean => validateDuration(terms)
+
+export const termsValidators = [
+  validateTermsAppraisals,
+  validateTermsWindow,
+]

package/src/Total/Diviner.ts

@@ -0,0 +1,67 @@
+import { assertEx } from '@xylabs/assert'
+import { Hash } from '@xylabs/hex'
+import { AbstractDiviner } from '@xyo-network/diviner-abstract'
+import {
+  asDivinerInstance, DivinerInstance, DivinerModuleEventData,
+} from '@xyo-network/diviner-model'
+import { creatableModule } from '@xyo-network/module-model'
+import {
+  Discount,
+  isDiscountWithMeta,
+  isSubtotalWithMeta,
+  PaymentTotalDivinerConfigSchema, PaymentTotalDivinerParams, Subtotal, Total, TotalSchema,
+} from '@xyo-network/payment-payload-plugins'
+
+import { PaymentDiscountDiviner, PaymentDiscountDivinerInputType } from '../Discount/index.ts'
+import { PaymentSubtotalDiviner, PaymentSubtotalDivinerInputType } from '../Subtotal/index.ts'
+
+type InputType = PaymentDiscountDivinerInputType | PaymentSubtotalDivinerInputType
+type OutputType = Subtotal | Discount | Total
+
+@creatableModule()
+export class PaymentTotalDiviner<
+  TParams extends PaymentTotalDivinerParams = PaymentTotalDivinerParams,
+  TIn extends InputType = InputType,
+  TOut extends OutputType = OutputType,
+  TEventData extends DivinerModuleEventData<DivinerInstance<TParams, TIn, TOut>, TIn, TOut> = DivinerModuleEventData<
+    DivinerInstance<TParams, TIn, TOut>,
+    TIn,
+    TOut
+  >,
+> extends AbstractDiviner<TParams, TIn, TOut, TEventData> {
+  static override configSchemas = [PaymentTotalDivinerConfigSchema]
+  static override defaultConfigSchema: PaymentTotalDivinerConfigSchema = PaymentTotalDivinerConfigSchema
+
+  protected async divineHandler(payloads: TIn[] = []): Promise<TOut[]> {
+    const subtotalDiviner = await this.getPaymentSubtotalDiviner()
+    const subtotalResult = await subtotalDiviner.divine(payloads)
+    const subtotal = subtotalResult.find(isSubtotalWithMeta)
+    if (!subtotal) return []
+    const discountDiviner = await this.getPaymentDiscountsDiviner()
+    const discountResult = await discountDiviner.divine(payloads)
+    const discount = discountResult.find(isDiscountWithMeta)
+    if (!discount) return []
+    const { currency: subtotalCurrency } = subtotal
+    const { currency: discountCurrency } = discount
+    assertEx(subtotalCurrency === discountCurrency, () => `Subtotal currency ${subtotalCurrency} does not match discount currency ${discountCurrency}`)
+    const amount = Math.max(0, subtotal.amount - discount.amount)
+    const currency = subtotalCurrency
+    const sources = [subtotal.$hash, discount.$hash] as Hash[]
+    const total: Total = {
+      amount, currency, sources, schema: TotalSchema,
+    }
+    return [subtotal, discount, total] as TOut[]
+  }
+
+  protected async getPaymentDiscountsDiviner(): Promise<PaymentDiscountDiviner> {
+    const name = assertEx(this.config.paymentDiscountDiviner, () => 'Missing paymentDiscountDiviner in config')
+    const mod = assertEx(await this.resolve(name), () => `Error resolving paymentDiscountDiviner: ${name}`)
+    return assertEx(asDivinerInstance(mod), () => `Resolved module ${mod.address} not a valid Diviner`) as PaymentDiscountDiviner
+  }
+
+  protected async getPaymentSubtotalDiviner(): Promise<PaymentSubtotalDiviner> {
+    const name = assertEx(this.config.paymentSubtotalDiviner, () => 'Missing paymentSubtotalDiviner in config')
+    const mod = assertEx(await this.resolve(name), () => `Error resolving paymentSubtotalDiviner: ${name}`)
+    return assertEx(asDivinerInstance(mod), () => `Resolved module ${mod.address} not a valid Diviner`) as PaymentSubtotalDiviner
+  }
+}

package/src/Total/index.ts

@@ -0,0 +1 @@
+export * from './Diviner.ts'

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './Discount/index.ts'
+export * from './Invoice/index.ts'
+export * from './Subtotal/index.ts'
+export * from './Total/index.ts'

package/typedoc.json

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

package/xy.config.ts

@@ -0,0 +1,11 @@
+import type { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
+const config: XyTsupConfig = {
+  compile: {
+    browser: {},
+    node: {},
+    neutral: { src: true },
+  },
+}
+
+// eslint-disable-next-line import-x/no-default-export
+export default config