@owlmeans/payment 0.1.18-rc.8 → 0.1.18

package/src/errors.ts

@@ -1,5 +1,8 @@
 
 import { ResilientError } from '@owlmeans/error'
+import { AuthForbidden } from '@owlmeans/auth'
+import { BILLING_COUNTRY_LOCKED_MARKER, CANCELLATION_UNAVAILABLE_MARKER, CAPABILITY_REQUIRED_MARKER, CHECKOUT_LIMIT_MARKER, LIMIT_EXHAUSTED_FIELDS, LIMIT_EXHAUSTED_MARKER, PERFORMANCE_CONSENT_MARKER, SUBSCRIPTION_START_MARKER, WITHDRAWAL_UNAVAILABLE_MARKER } from './consts.local.js'
+import type { BillingCountryLockedDetails, CheckoutLimitExceededDetails, LimitExhaustedDetails, PerformanceConsentRequiredDetails } from './types.js'
 
 export class PaymentError extends ResilientError {
   public static override typeName: string = 'PaymentError'
@@ -36,6 +39,22 @@ export class PaygateMappingError extends PaygateError {
   }
 }
 
+/**
+ * A webhook delivery whose signature is missing or verifies against no known secret. The sender is
+ * refused as a client error (400): a forged or unsigned POST at a public hook is not a server fault,
+ * and answering 500 would page operators for it and invite the sender to retry it.
+ */
+export class PaygateSignatureError extends PaygateError {
+  public static override typeName: string = `${PaygateError.typeName}Signature`
+  /** Read by the HTTP boundary (`server-api` `declaredErrorStatus`). */
+  public static httpStatus: number = 400
+
+  constructor() {
+    super('signature')
+    this.type = PaygateSignatureError.typeName
+  }
+}
+
 export class ProductError extends PaymentError {
   public static override typeName: string = `${PaymentError.typeName}Product`
 
@@ -90,13 +109,439 @@ export class UnknownSubscription extends SubscriptionError {
   }
 }
 
+export class LimitUnknown extends ProductError {
+  public static override typeName: string = `${ProductError.typeName}LimitUnknown`
+
+  constructor(message: string = 'error') {
+    super(`limit-unknown:${message}`)
+    this.type = LimitUnknown.typeName
+  }
+}
+
+export class LimitMisdeclared extends ProductError {
+  public static override typeName: string = `${ProductError.typeName}LimitMisdeclared`
+
+  constructor(message: string = 'error') {
+    super(`limit-misdeclared:${message}`)
+    this.type = LimitMisdeclared.typeName
+  }
+}
+
+export class PlanRequired extends ProductError {
+  public static override typeName: string = `${ProductError.typeName}PlanRequired`
+
+  constructor(message: string = 'error') {
+    super(`plan-required:${message}`)
+    this.type = PlanRequired.typeName
+  }
+}
+
+export class PlanRankConflict extends ProductError {
+  public static override typeName: string = `${ProductError.typeName}PlanRankConflict`
+
+  constructor(message: string = 'error') {
+    super(`plan-rank-conflict:${message}`)
+    this.type = PlanRankConflict.typeName
+  }
+}
+
+export class WebhookSetupError extends PaygateError {
+  public static override typeName: string = `${PaygateError.typeName}WebhookSetup`
+
+  constructor(message: string = 'error') {
+    super(`webhook-setup:${message}`)
+    this.type = WebhookSetupError.typeName
+  }
+}
+
+/**
+ * The entity has nothing the requested portal flow can act on — no paygate customer, no entitling
+ * subscription, no plan or item to change to. The entity's own state, not a fault: an HTTP boundary
+ * that honours `httpStatus` (`@owlmeans/server-api`) answers 409 Conflict.
+ */
+export class PortalUnavailable extends PaygateError {
+  public static override typeName: string = `${PaygateError.typeName}PortalUnavailable`
+  public static httpStatus = 409
+
+  constructor(message: string = 'error') {
+    super(`portal-unavailable:${message}`)
+    this.type = PortalUnavailable.typeName
+  }
+}
+
+/**
+ * The entity's plan does not allow the request.
+ *
+ * Extends `AuthForbidden` so an HTTP boundary answers 403, never 500. Only `type` and `message`
+ * survive a marshal round trip, so each subclass packs its fields into the message and rebuilds
+ * them in `finalizeUnmarshal()`.
+ */
+export class EntitlementRefusal extends AuthForbidden {
+  public static override typeName: string = 'EntitlementRefusal'
+
+  constructor(message: string = 'error') {
+    super(`entitlement:${message}`)
+    this.type = EntitlementRefusal.typeName
+  }
+}
+
+/** None of the capability parameters (OR'd) is granted. Message marker `capability-required:<a|b>`. */
+export class CapabilityRequired extends EntitlementRefusal {
+  public static override typeName: string = `${EntitlementRefusal.typeName}CapabilityRequired`
+
+  /** The refused parameters, as the gate took them. */
+  public params: string[] = []
+
+  constructor(params: string | string[] = []) {
+    const list = (Array.isArray(params) ? params : [params]).filter(param => param !== '')
+    super(`${CAPABILITY_REQUIRED_MARKER}${list.join('|')}`)
+    this.type = CapabilityRequired.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const at = this.message.indexOf(CAPABILITY_REQUIRED_MARKER)
+    const packed = at < 0 ? '' : this.message.slice(at + CAPABILITY_REQUIRED_MARKER.length)
+    this.params = packed.split('|').filter(param => param !== '')
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+
+/**
+ * A limit has no room left. Message marker `limit-exhausted:<key>:<used>/<limit>[:<resetsAt ISO>]`.
+ */
+export class LimitExhausted extends EntitlementRefusal {
+  public static override typeName: string = `${EntitlementRefusal.typeName}LimitExhausted`
+
+  public limitKey: string = ''
+  public used: number = 0
+  public limit: number = 0
+  public resetsAt?: Date
+
+  /** The packed marker body of a refusal. */
+  static encode(details: LimitExhaustedDetails): string {
+    const resetsAt = details.resetsAt != null && !Number.isNaN(details.resetsAt.getTime())
+      ? `:${details.resetsAt.toISOString()}` : ''
+    return `${details.key}:${details.used}/${details.limit}${resetsAt}`
+  }
+
+  constructor(details: LimitExhaustedDetails)
+  /** A packed marker body (`LimitExhausted.encode`) or a marshaled message — the error registry's path. */
+  constructor(message: string)
+  constructor(details: LimitExhaustedDetails | string = 'error') {
+    super(`${LIMIT_EXHAUSTED_MARKER}${typeof details === 'string' ? details : LimitExhausted.encode(details)}`)
+    this.type = LimitExhausted.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const at = this.message.indexOf(LIMIT_EXHAUSTED_MARKER)
+    const match = at < 0 ? null
+      : LIMIT_EXHAUSTED_FIELDS.exec(this.message.slice(at + LIMIT_EXHAUSTED_MARKER.length))
+    if (match == null) {
+      return
+    }
+    const [, key, used, limit, resetsAt] = match
+    this.limitKey = key
+    this.used = Number(used) || 0
+    this.limit = Number(limit) || 0
+    const date = resetsAt != null ? new Date(resetsAt) : null
+    this.resetsAt = date != null && !Number.isNaN(date.getTime()) ? date : undefined
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+/**
+ * A consumer-rights fault — a misdeclared policy (`policy:<field>`), a missing usage meter or
+ * mailer, a copy template without a value (`copy:<path>`). Declares no status: 500.
+ */
+export class ConsumerRightsError extends PaymentError {
+  public static override typeName: string = `${PaymentError.typeName}ConsumerRights`
+
+  constructor(message: string = 'error') {
+    super(`consumer-rights:${message}`)
+    this.type = ConsumerRightsError.typeName
+  }
+}
+
+/**
+ * The consumer's own position refuses the request — never a fault. Deliberately NOT an
+ * `AuthForbidden`: an HTTP boundary tests that family first, and a 403 would hide the declared
+ * 428/409 a client acts on.
+ */
+export class ConsumerRightsRefusal extends ConsumerRightsError {
+  public static override typeName: string = `${ConsumerRightsError.typeName}Refusal`
+
+  constructor(message: string = 'error') {
+    super(message)
+    this.type = ConsumerRightsRefusal.typeName
+  }
+}
+
+/** The packed body after the LAST marker occurrence — a registry rebuild doubles the prefix. */
+const packedAfter = (message: string, marker: string): string | null => {
+  const at = message.lastIndexOf(marker)
+
+  return at < 0 ? null : message.slice(at + marker.length)
+}
+
+const dateOf = (value: string | undefined): Date | undefined => {
+  const date = value != null && value !== '' ? new Date(value) : null
+
+  return date != null && !Number.isNaN(date.getTime()) ? date : undefined
+}
+
+const isoOf = (date: Date | undefined): string =>
+  date != null && !Number.isNaN(date.getTime()) ? `:${date.toISOString()}` : ''
+
+const decode = (value: string): string => {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+/**
+ * Billed work would spend credits of a purchase still inside its withdrawal window, and the
+ * consumer has not expressly requested performance. HTTP 428. Marker
+ * `performance-consent-required:<pending>[:<deadline ISO>]`.
+ */
+export class PerformanceConsentRequired extends ConsumerRightsRefusal {
+  public static override typeName: string = `${ConsumerRightsRefusal.typeName}PerformanceConsentRequired`
+  public static httpStatus = 428
+
+  public pending: number = 0
+  public deadline?: Date
+
+  static encode(details: PerformanceConsentRequiredDetails): string {
+    return `${Math.max(0, Math.floor(details.pending))}${isoOf(details.deadline)}`
+  }
+
+  constructor(details: PerformanceConsentRequiredDetails)
+  /** A packed marker body (`encode`) or a marshaled message — the error registry's path. */
+  constructor(message: string)
+  constructor(details: PerformanceConsentRequiredDetails | string = 'error') {
+    super(`${PERFORMANCE_CONSENT_MARKER}${typeof details === 'string' ? details : PerformanceConsentRequired.encode(details)}`)
+    this.type = PerformanceConsentRequired.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const match = /^(\d+)(?::(.+))?$/.exec(packedAfter(this.message, PERFORMANCE_CONSENT_MARKER) ?? '')
+    if (match == null) {
+      return
+    }
+    this.pending = Number(match[1])
+    this.deadline = dateOf(match[2])
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+/**
+ * A subscription checkout needs a fresh express start request bound to this plan. HTTP 428.
+ * Marker `subscription-start-required:<encodeURIComponent(planSku)>`.
+ */
+export class SubscriptionStartRequired extends ConsumerRightsRefusal {
+  public static override typeName: string = `${ConsumerRightsRefusal.typeName}SubscriptionStartRequired`
+  public static httpStatus = 428
+
+  public planSku: string = ''
+
+  static encode(planSku: string): string {
+    return encodeURIComponent(planSku)
+  }
+
+  /** `planSku` as is, or a packed marker body / marshaled message (the registry's path). */
+  constructor(planSku: string | { planSku: string } = 'error') {
+    super(`${SUBSCRIPTION_START_MARKER}${typeof planSku === 'string' ? SubscriptionStartRequired.encodeLoose(planSku) : SubscriptionStartRequired.encode(planSku.planSku)}`)
+    this.type = SubscriptionStartRequired.typeName
+    this.applyFields()
+  }
+
+  /** A string that already is a marker (the registry path) passes through unencoded. */
+  private static encodeLoose(value: string): string {
+    return value.includes(SUBSCRIPTION_START_MARKER) ? value : SubscriptionStartRequired.encode(value)
+  }
+
+  private applyFields(): void {
+    const packed = packedAfter(this.message, SUBSCRIPTION_START_MARKER)
+    if (packed != null) {
+      this.planSku = decode(packed)
+    }
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+/**
+ * The entity's billing country is fixed and the request declared another. HTTP 409. Marker
+ * `billing-country-locked:<country>[:<requested>]`.
+ */
+export class BillingCountryLocked extends ConsumerRightsRefusal {
+  public static override typeName: string = `${ConsumerRightsRefusal.typeName}BillingCountryLocked`
+  public static httpStatus = 409
+
+  public country: string = ''
+  public requested?: string
+
+  static encode(details: BillingCountryLockedDetails): string {
+    return details.requested != null && details.requested !== ''
+      ? `${details.country}:${details.requested}` : details.country
+  }
+
+  constructor(details: BillingCountryLockedDetails)
+  constructor(message: string)
+  constructor(details: BillingCountryLockedDetails | string = 'error') {
+    super(`${BILLING_COUNTRY_LOCKED_MARKER}${typeof details === 'string' ? details : BillingCountryLocked.encode(details)}`)
+    this.type = BillingCountryLocked.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const match = /^([A-Za-z]{2})(?::([A-Za-z]{2}))?$/.exec(packedAfter(this.message, BILLING_COUNTRY_LOCKED_MARKER) ?? '')
+    if (match == null) {
+      return
+    }
+    this.country = match[1]
+    this.requested = match[2]
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+/**
+ * The named purchase cannot be withdrawn from (`WithdrawalUnavailableReason`). HTTP 409. Marker
+ * `withdrawal-unavailable:<reason>`. Never raised on the public page, which discloses nothing.
+ */
+export class WithdrawalUnavailable extends ConsumerRightsRefusal {
+  public static override typeName: string = `${ConsumerRightsRefusal.typeName}WithdrawalUnavailable`
+  public static httpStatus = 409
+
+  public reason: string = ''
+
+  constructor(reason: string = 'error') {
+    super(`${WITHDRAWAL_UNAVAILABLE_MARKER}${reason}`)
+    this.type = WithdrawalUnavailable.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    this.reason = /^[\w-]*/.exec(packedAfter(this.message, WITHDRAWAL_UNAVAILABLE_MARKER) ?? '')?.[0] ?? ''
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+/**
+ * Nothing to cancel in-app (`CancellationUnavailableReason`). HTTP 409. Marker
+ * `cancellation-unavailable:<reason>`.
+ */
+export class CancellationUnavailable extends ConsumerRightsRefusal {
+  public static override typeName: string = `${ConsumerRightsRefusal.typeName}CancellationUnavailable`
+  public static httpStatus = 409
+
+  public reason: string = ''
+
+  constructor(reason: string = 'error') {
+    super(`${CANCELLATION_UNAVAILABLE_MARKER}${reason}`)
+    this.type = CancellationUnavailable.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    this.reason = /^[\w-]*/.exec(packedAfter(this.message, CANCELLATION_UNAVAILABLE_MARKER) ?? '')?.[0] ?? ''
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+/**
+ * The amount is above what this entity may buy now (a narrowing of the plan's policy). HTTP 409.
+ * Marker `checkout-limit-exceeded:<encodeURIComponent(reason)>:<maximumMinor>:<currency>[:<ISO>]`.
+ * A payment refusal, not a consumer-rights one.
+ */
+export class CheckoutLimitExceeded extends PaymentError {
+  public static override typeName: string = `${PaymentError.typeName}CheckoutLimitExceeded`
+  public static httpStatus = 409
+
+  public reason: string = ''
+  public maximumMinor: number = 0
+  public currency: string = ''
+  public resetsAt?: Date
+
+  static encode(details: CheckoutLimitExceededDetails): string {
+    return `${encodeURIComponent(details.reason)}:${Math.max(0, Math.floor(details.maximumMinor))}`
+      + `:${details.currency.toLowerCase()}${isoOf(details.resetsAt)}`
+  }
+
+  constructor(details: CheckoutLimitExceededDetails)
+  constructor(message: string)
+  constructor(details: CheckoutLimitExceededDetails | string = 'error') {
+    super(`${CHECKOUT_LIMIT_MARKER}${typeof details === 'string' ? details : CheckoutLimitExceeded.encode(details)}`)
+    this.type = CheckoutLimitExceeded.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const match = /^([^:]*):(\d+):([a-z]{3})(?::(.+))?$/.exec(packedAfter(this.message, CHECKOUT_LIMIT_MARKER) ?? '')
+    if (match == null) {
+      return
+    }
+    this.reason = decode(match[1])
+    this.maximumMinor = Number(match[2])
+    this.currency = match[3]
+    this.resetsAt = dateOf(match[4])
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
 ResilientError.registerErrorClass(PaymentError)
 ResilientError.registerErrorClass(PaygateError)
 ResilientError.registerErrorClass(UnknownPaygate)
 ResilientError.registerErrorClass(PaygateMappingError)
+ResilientError.registerErrorClass(PaygateSignatureError)
 ResilientError.registerErrorClass(ProductError)
 ResilientError.registerErrorClass(UnknownProduct)
 ResilientError.registerErrorClass(UnknownPlan)
 ResilientError.registerErrorClass(PaymentIdentificationError)
 ResilientError.registerErrorClass(SubscriptionError)
 ResilientError.registerErrorClass(UnknownSubscription)
+ResilientError.registerErrorClass(LimitUnknown)
+ResilientError.registerErrorClass(LimitMisdeclared)
+ResilientError.registerErrorClass(PlanRequired)
+ResilientError.registerErrorClass(PlanRankConflict)
+ResilientError.registerErrorClass(WebhookSetupError)
+ResilientError.registerErrorClass(PortalUnavailable)
+ResilientError.registerErrorClass(EntitlementRefusal)
+ResilientError.registerErrorClass(CapabilityRequired)
+ResilientError.registerErrorClass(LimitExhausted)
+ResilientError.registerErrorClass(ConsumerRightsError)
+ResilientError.registerErrorClass(ConsumerRightsRefusal)
+ResilientError.registerErrorClass(PerformanceConsentRequired)
+ResilientError.registerErrorClass(SubscriptionStartRequired)
+ResilientError.registerErrorClass(BillingCountryLocked)
+ResilientError.registerErrorClass(WithdrawalUnavailable)
+ResilientError.registerErrorClass(CancellationUnavailable)
+ResilientError.registerErrorClass(CheckoutLimitExceeded)

package/src/estimate/types.ts

@@ -0,0 +1,34 @@
+import type { AmountEstimate, PriceEstimate, PricingPolicy } from '../types.js'
+
+/** The pricing policy's invariants and the tax / local-currency estimate of an amount. */
+export interface PriceEstimateHelper {
+  /**
+   * @throws PaymentError when a tax estimate is served without automatic tax, a currency estimate is
+   * served without Adaptive Pricing, or a TTL is not a positive integer.
+   */
+  assertPricingPolicy: (policy: PricingPolicy) => PricingPolicy
+  /**
+   * Stripe's `percentage_decimal` (e.g. `"23"`, `"8.875"`) as parts per million — `1_000_000` is
+   * `100%` — parsed digit by digit so it is exact where a float parse (`Number(x) * 10_000`) is not.
+   * Fractional digits past the fourth are truncated, not rounded: a quarter of a hundredth of a
+   * percent is already far finer than any real tax rate.
+   *
+   * @throws PaymentError when the string is not a plain (unsigned, non-exponential) decimal.
+   */
+  ratePpmOf: (percentageDecimal: string) => number
+  /**
+   * Re-derive tax and the local-currency total for `amountMinor` from a `PriceEstimate` already
+   * fetched for the SAME product/plan/country, so a UI can re-price a custom amount (the credit
+   * dialog) without a second Stripe Tax call ($0.05 each).
+   *
+   * Exact for `amountMinor === estimate.tax.subtotalMinor` (Stripe's own numbers, echoed back).
+   * Otherwise exact only for `TaxBehavior.Exclusive` with `estimate.tax.scalable` — a linear
+   * percentage rate scales; a flat fee, a reduced-rate portion, or several inclusive rates do not, and
+   * neither does rescaling an inclusive amount (its tax portion is carved OUT of the total by a
+   * different formula this helper does not attempt). Both cases return `null` amounts, meaning
+   * "computed at checkout".
+   *
+   * @throws PaymentError when `amountMinor` is not a non-negative safe integer.
+   */
+  estimateOf: (amountMinor: number, estimate: PriceEstimate) => AmountEstimate
+}

package/src/estimate.ts

@@ -0,0 +1,90 @@
+import { PaymentError } from './errors.js'
+import { TaxBehavior } from './consts.js'
+import type { PriceEstimate, PricingPolicy, AmountEstimate } from './types.js'
+import type { PriceEstimateHelper } from './estimate/types.js'
+
+/** Stripe's own convention for a tax amount: half a unit rounds up. */
+const roundHalfUp = (value: number): number => Math.floor(value + 0.5)
+
+export const createPriceEstimateHelper = (): PriceEstimateHelper => {
+  const assertPricingPolicy = (policy: PricingPolicy): PricingPolicy => {
+    if (policy.tax.estimate && !policy.tax.automatic) {
+      throw new PaymentError('pricing-policy:tax-estimate-requires-automatic')
+    }
+    if (policy.currency.estimate && policy.currency.adaptive !== true) {
+      throw new PaymentError('pricing-policy:currency-estimate-requires-adaptive')
+    }
+    const feeRate = policy.currency.adaptiveFeeRate
+    if (feeRate != null) {
+      if (policy.currency.adaptive !== true) {
+        throw new PaymentError('pricing-policy:adaptive-fee-requires-adaptive')
+      }
+      if (!Number.isFinite(feeRate) || feeRate < 0 || feeRate >= 1) {
+        throw new PaymentError('pricing-policy:adaptive-fee-rate')
+      }
+    }
+    for (const ttl of [policy.tax.estimateTtlSeconds, policy.currency.estimateTtlSeconds]) {
+      if (ttl != null && (!Number.isSafeInteger(ttl) || ttl < 1)) {
+        throw new PaymentError('pricing-policy:ttl')
+      }
+    }
+    return policy
+  }
+
+  const ratePpmOf = (percentageDecimal: string): number => {
+    const match = /^(\d+)(?:\.(\d+))?$/.exec(percentageDecimal.trim())
+    if (match == null) {
+      throw new PaymentError('tax-rate:percentage')
+    }
+    const [, whole, fraction = ''] = match
+    const fractionPpm = Number(`${fraction}0000`.slice(0, 4))
+    const ppm = Number(whole) * 10_000 + fractionPpm
+    if (!Number.isSafeInteger(ppm)) {
+      throw new PaymentError('tax-rate:percentage')
+    }
+    return ppm
+  }
+
+  const estimateOf = (amountMinor: number, estimate: PriceEstimate): AmountEstimate => {
+    if (!Number.isSafeInteger(amountMinor) || amountMinor < 0) {
+      throw new PaymentError('price-estimate:amount')
+    }
+    const { tax, behavior, local } = estimate
+    const sameAmount = amountMinor === tax.subtotalMinor
+    const rescalable = sameAmount || (behavior === TaxBehavior.Exclusive && tax.scalable)
+    if (!rescalable) {
+      return { subtotalMinor: amountMinor, taxMinor: null, totalMinor: null }
+    }
+    // `sameAmount` trusts Stripe's own numbers outright; otherwise only Exclusive ever reaches here
+    // (`rescalable` above excludes an Inclusive amount that differs from the reference).
+    const taxMinor = sameAmount ? tax.taxMinor : tax.rates.reduce(
+      (sum, rate) => sum + roundHalfUp(amountMinor * rate.ratePpm / 1_000_000), 0,
+    )
+    const totalMinor = sameAmount ? tax.totalMinor : amountMinor + taxMinor
+    const result: AmountEstimate = { subtotalMinor: amountMinor, taxMinor, totalMinor }
+    if (local != null) {
+      result.local = {
+        currency: local.currency,
+        subtotalAmount: amountMinor / 100 / local.exchangeRate,
+        taxAmount: taxMinor / 100 / local.exchangeRate,
+        totalAmount: totalMinor / 100 / local.exchangeRate,
+      }
+    }
+    return result
+  }
+
+  return { assertPricingPolicy, ratePpmOf, estimateOf }
+}
+
+export const priceEstimateHelper = createPriceEstimateHelper()
+
+/** @deprecated compat:factory-refactor — use `priceEstimateHelper.assertPricingPolicy(…)` */
+export const assertPricingPolicy = (policy: PricingPolicy): PricingPolicy =>
+  priceEstimateHelper.assertPricingPolicy(policy)
+
+/** @deprecated compat:factory-refactor — use `priceEstimateHelper.ratePpmOf(…)` */
+export const ratePpmOf = (percentageDecimal: string): number => priceEstimateHelper.ratePpmOf(percentageDecimal)
+
+/** @deprecated compat:factory-refactor — use `priceEstimateHelper.estimateOf(…)` */
+export const estimateOf = (amountMinor: number, estimate: PriceEstimate): AmountEstimate =>
+  priceEstimateHelper.estimateOf(amountMinor, estimate)