@owlmeans/payment 0.1.18-rc.9 → 0.1.18

package/src/pricing.ts

@@ -0,0 +1,110 @@
+import { PaymentError } from './errors.js'
+import type { AmountCheckoutPolicy, QuantityCheckoutPolicy } from './types.js'
+import type { CheckoutPricingHelper } from './pricing/types.js'
+
+const integer = (value: number): boolean => Number.isSafeInteger(value)
+
+export const createCheckoutPricingHelper = (): CheckoutPricingHelper => {
+  const assertAmountCheckoutPolicy = (
+    policy: AmountCheckoutPolicy,
+  ): AmountCheckoutPolicy => {
+    if (
+      !integer(policy.minimumMinor)
+      || !integer(policy.maximumMinor)
+      || !integer(policy.defaultMinor)
+      || !integer(policy.fixedMinor)
+      || !integer(policy.rateBps)
+      || policy.minimumMinor < 0
+      || policy.minimumMinor > policy.defaultMinor
+      || policy.defaultMinor > policy.maximumMinor
+      || policy.fixedMinor < 0
+      || policy.rateBps < 0
+      || policy.rateBps >= 10_000
+      || policy.currency.trim().length !== 3
+    ) {
+      throw new PaymentError('checkout-policy:amount')
+    }
+
+    const presets = new Set(policy.presetsMinor)
+    if (
+      presets.size !== policy.presetsMinor.length
+      || policy.presetsMinor.some(value =>
+        !integer(value) || value < policy.minimumMinor || value > policy.maximumMinor
+      )
+    ) {
+      throw new PaymentError('checkout-policy:presets')
+    }
+
+    return policy
+  }
+
+  const assertQuantityCheckoutPolicy = (
+    policy: QuantityCheckoutPolicy,
+  ): QuantityCheckoutPolicy => {
+    if (
+      !integer(policy.minimum)
+      || !integer(policy.maximum)
+      || !integer(policy.default)
+      || policy.minimum < 1
+      || policy.minimum > policy.default
+      || policy.default > policy.maximum
+    ) {
+      throw new PaymentError('checkout-policy:quantity')
+    }
+    return policy
+  }
+
+  const assertCheckoutAmount = (
+    policy: AmountCheckoutPolicy, amountMinor: number,
+  ): number => {
+    assertAmountCheckoutPolicy(policy)
+    if (!integer(amountMinor)) {
+      throw new PaymentError('checkout-amount:integer')
+    }
+    if (amountMinor < policy.minimumMinor) {
+      throw new PaymentError('checkout-amount:minimum')
+    }
+    if (amountMinor > policy.maximumMinor) {
+      throw new PaymentError('checkout-amount:maximum')
+    }
+    return amountMinor
+  }
+
+  const chargeAmountMinor = (
+    amountMinor: number, policy: Pick<AmountCheckoutPolicy, 'fixedMinor' | 'rateBps'>,
+  ): number => {
+    const adjusted = amountMinor + policy.fixedMinor
+    const numerator = adjusted * 10_000
+    if (
+      !integer(amountMinor) || !integer(policy.fixedMinor) || !integer(policy.rateBps)
+      || amountMinor < 0 || policy.fixedMinor < 0 || policy.rateBps < 0 || policy.rateBps >= 10_000
+      || !integer(adjusted) || !integer(numerator)
+    ) {
+      throw new PaymentError('checkout-charge')
+    }
+    const charge = Math.ceil(numerator / (10_000 - policy.rateBps))
+    if (!integer(charge)) throw new PaymentError('checkout-charge')
+    return charge
+  }
+
+  return { assertAmountCheckoutPolicy, assertQuantityCheckoutPolicy, assertCheckoutAmount, chargeAmountMinor }
+}
+
+export const checkoutPricingHelper = createCheckoutPricingHelper()
+
+/** @deprecated compat:factory-refactor — use `checkoutPricingHelper.assertAmountCheckoutPolicy(…)` */
+export const assertAmountCheckoutPolicy = (policy: AmountCheckoutPolicy): AmountCheckoutPolicy =>
+  checkoutPricingHelper.assertAmountCheckoutPolicy(policy)
+
+/** @deprecated compat:factory-refactor — use `checkoutPricingHelper.assertQuantityCheckoutPolicy(…)` */
+export const assertQuantityCheckoutPolicy = (policy: QuantityCheckoutPolicy): QuantityCheckoutPolicy =>
+  checkoutPricingHelper.assertQuantityCheckoutPolicy(policy)
+
+/** @deprecated compat:factory-refactor — use `checkoutPricingHelper.assertCheckoutAmount(…)` */
+export const assertCheckoutAmount = (policy: AmountCheckoutPolicy, amountMinor: number): number =>
+  checkoutPricingHelper.assertCheckoutAmount(policy, amountMinor)
+
+/** @deprecated compat:factory-refactor — use `checkoutPricingHelper.chargeAmountMinor(…)` */
+export const chargeAmountMinor = (
+  amountMinor: number, policy: Pick<AmountCheckoutPolicy, 'fixedMinor' | 'rateBps'>,
+): number => checkoutPricingHelper.chargeAmountMinor(amountMinor, policy)

package/src/promo/types.ts

@@ -0,0 +1,18 @@
+import type { PromoDeclaration, PromoView } from '../types.js'
+
+/** Whether a promo is in force, and how a UI inscribes it. */
+export interface PromoHelper {
+  /**
+   * Whether a grant behind a promo is in force.
+   *
+   * No promo ⇒ always. Otherwise while `at < until`, or — with `grandfather` — for a subscription
+   * created before `until`. `at === until` is already over.
+   */
+  promoActive: (
+    promo: PromoDeclaration | null | undefined, subscribedAt: Date | null | undefined, at?: Date,
+  ) => boolean
+  /** What a UI needs to inscribe a promo: `undefined` when the grant has none. */
+  promoViewOf: (
+    promo: PromoDeclaration | null | undefined, subscribedAt: Date | null | undefined, at?: Date,
+  ) => PromoView | undefined
+}

package/src/promo.ts

@@ -0,0 +1,46 @@
+import type { PromoDeclaration, PromoView } from './types.js'
+import type { PromoHelper } from './promo/types.js'
+
+/**
+ * A date as epoch milliseconds. A declaration read back from JSON carries an ISO string where the
+ * type says `Date`; an unparseable value is `NaN`, which fails every comparison — so a broken
+ * promo is never in force.
+ */
+const timeOf = (value: Date | string | number | null | undefined): number =>
+  value == null ? Number.NaN : value instanceof Date ? value.getTime() : new Date(value).getTime()
+
+export const createPromoHelper = (): PromoHelper => {
+  const grandfathers = (promo: PromoDeclaration, subscribedAt: Date | null | undefined): boolean =>
+    promo.grandfather === true && timeOf(subscribedAt) < timeOf(promo.until)
+
+  const promoActive = (
+    promo: PromoDeclaration | null | undefined,
+    subscribedAt: Date | null | undefined,
+    at: Date = new Date(),
+  ): boolean => {
+    if (promo == null) {
+      return true
+    }
+
+    return timeOf(at) < timeOf(promo.until) || grandfathers(promo, subscribedAt)
+  }
+
+  const promoViewOf = (
+    promo: PromoDeclaration | null | undefined,
+    subscribedAt: Date | null | undefined,
+    at: Date = new Date(),
+  ): PromoView | undefined => promo == null ? undefined : {
+    until: new Date(timeOf(promo.until)),
+    grandfathered: grandfathers(promo, subscribedAt),
+    active: promoActive(promo, subscribedAt, at),
+  }
+
+  return { promoActive, promoViewOf }
+}
+
+export const promoHelper = createPromoHelper()
+
+/** @deprecated compat:factory-refactor — use `promoHelper.promoActive(…)` */
+export const promoActive = (
+  promo: PromoDeclaration | null | undefined, subscribedAt: Date | null | undefined, at?: Date,
+): boolean => promoHelper.promoActive(promo, subscribedAt, at)

package/src/regions/types.ts

@@ -0,0 +1,42 @@
+import type { ConsumerRegion } from '../consts.js'
+import type { ConsumerRightsPolicy } from '../types.js'
+import type { RegionPolicy } from '../types.local.js'
+
+/** The consumer region of a billing country and what it decides: scope, currency and legal language. */
+export interface ConsumerRegionHelper {
+  /** A member state of the EU (not a territory with its own code). */
+  isEuCountry: (country: string | null | undefined) => boolean
+  /** A member state of the EEA: the EU's 27 plus Iceland, Liechtenstein and Norway. */
+  isEeaCountry: (country: string | null | undefined) => boolean
+  /**
+   * The consumer region of a billing country: `Eu` inside the policy's territories (the default
+   * ones without a policy), `Other` outside, `null` when the country is unknown.
+   */
+  regionOf: (country: string | null | undefined, policy?: RegionPolicy) => ConsumerRegion | null
+  /**
+   * Whether a buyer has the consumer rights: a known country decides by the policy's territories;
+   * without one, a known region decides; with neither, `unknownCountry: 'protect'` (the default) puts
+   * the buyer in scope — the safe side.
+   */
+  inScope: (
+    region: ConsumerRegion | null | undefined, country: string | null | undefined,
+    policy?: Pick<ConsumerRightsPolicy, 'countries' | 'unknownCountry'> | null,
+  ) => boolean
+  /**
+   * The currency a region is charged in (lowercase ISO 4217): the policy's currency for the region,
+   * an unknown region reading as `Eu`; `fallback` when the policy names none.
+   */
+  chargeCurrencyOf: (
+    region: ConsumerRegion | null | undefined, policy: Pick<ConsumerRightsPolicy, 'currencies'> | null | undefined,
+    fallback: string,
+  ) => string
+  /**
+   * The language of a billing country's legal copy: the policy's own map, then
+   * `COUNTRY_LANGUAGES`, then `fallback`, then the policy's default language, then `en`.
+   */
+  billingLanguageOf: (
+    country: string | null | undefined,
+    policy?: Pick<ConsumerRightsPolicy, 'languages' | 'defaultLanguage'> | null,
+    fallback?: string,
+  ) => string
+}

package/src/regions.ts

@@ -0,0 +1,85 @@
+import { ConsumerRegion, CONSUMER_RIGHTS_TERRITORIES, COUNTRY_LANGUAGES, EEA_EXTRA, EU_COUNTRIES } from './consts.js'
+import type { ConsumerRightsPolicy } from './types.js'
+import type { RegionPolicy } from './types.local.js'
+import type { ConsumerRegionHelper } from './regions/types.js'
+
+const codeOf = (country: string | null | undefined): string | null =>
+  country == null || country.trim() === '' ? null : country.trim().toUpperCase()
+
+export const createConsumerRegionHelper = (): ConsumerRegionHelper => {
+  const isEuCountry = (country: string | null | undefined): boolean =>
+    EU_COUNTRIES.includes(codeOf(country) ?? '')
+
+  const isEeaCountry = (country: string | null | undefined): boolean => {
+    const code = codeOf(country) ?? ''
+
+    return EU_COUNTRIES.includes(code) || EEA_EXTRA.includes(code)
+  }
+
+  const regionOf = (country: string | null | undefined, policy?: RegionPolicy): ConsumerRegion | null => {
+    const code = codeOf(country)
+    if (code == null) {
+      return null
+    }
+
+    return (policy?.countries ?? CONSUMER_RIGHTS_TERRITORIES).includes(code) ? ConsumerRegion.Eu : ConsumerRegion.Other
+  }
+
+  const inScope = (
+    region: ConsumerRegion | null | undefined, country: string | null | undefined,
+    policy?: Pick<ConsumerRightsPolicy, 'countries' | 'unknownCountry'> | null,
+  ): boolean => {
+    const code = codeOf(country)
+    if (code != null) {
+      return (policy?.countries ?? CONSUMER_RIGHTS_TERRITORIES).includes(code)
+    }
+    if (region != null) {
+      return region === ConsumerRegion.Eu
+    }
+
+    return (policy?.unknownCountry ?? 'protect') === 'protect'
+  }
+
+  const chargeCurrencyOf = (
+    region: ConsumerRegion | null | undefined, policy: Pick<ConsumerRightsPolicy, 'currencies'> | null | undefined,
+    fallback: string,
+  ): string => (policy?.currencies?.[region ?? ConsumerRegion.Eu] ?? fallback).toLowerCase()
+
+  const billingLanguageOf = (
+    country: string | null | undefined,
+    policy?: Pick<ConsumerRightsPolicy, 'languages' | 'defaultLanguage'> | null,
+    fallback?: string,
+  ): string => {
+    const code = codeOf(country)
+    const mapped = code == null ? undefined : policy?.languages?.[code] ?? COUNTRY_LANGUAGES[code]
+
+    return mapped ?? fallback ?? policy?.defaultLanguage ?? 'en'
+  }
+
+  return { isEuCountry, isEeaCountry, regionOf, inScope, chargeCurrencyOf, billingLanguageOf }
+}
+
+export const consumerRegionHelper = createConsumerRegionHelper()
+
+/** @deprecated compat:factory-refactor — use `consumerRegionHelper.regionOf(…)` */
+export const regionOf = (country: string | null | undefined, policy?: RegionPolicy): ConsumerRegion | null =>
+  consumerRegionHelper.regionOf(country, policy)
+
+/** @deprecated compat:factory-refactor — use `consumerRegionHelper.inScope(…)` */
+export const inScope = (
+  region: ConsumerRegion | null | undefined, country: string | null | undefined,
+  policy?: Pick<ConsumerRightsPolicy, 'countries' | 'unknownCountry'> | null,
+): boolean => consumerRegionHelper.inScope(region, country, policy)
+
+/** @deprecated compat:factory-refactor — use `consumerRegionHelper.chargeCurrencyOf(…)` */
+export const chargeCurrencyOf = (
+  region: ConsumerRegion | null | undefined, policy: Pick<ConsumerRightsPolicy, 'currencies'> | null | undefined,
+  fallback: string,
+): string => consumerRegionHelper.chargeCurrencyOf(region, policy, fallback)
+
+/** @deprecated compat:factory-refactor — use `consumerRegionHelper.billingLanguageOf(…)` */
+export const billingLanguageOf = (
+  country: string | null | undefined,
+  policy?: Pick<ConsumerRightsPolicy, 'languages' | 'defaultLanguage'> | null,
+  fallback?: string,
+): string => consumerRegionHelper.billingLanguageOf(country, policy, fallback)

package/src/service.ts

@@ -1,17 +1,14 @@
-import { createService } from '@owlmeans/context'
-import type { ConfigRecord } from '@owlmeans/context'
-import { DEFAULT_ALIAS, PaymentEntityType, PLAN_RECORD_PREFIX, PRODUCT_RECORD_TYPE } from './consts.js'
-import type { Localization, PaymentService } from './types.js'
+import { createService, type ConfigRecord } from '@owlmeans/context'
+import { CONSUMER_RIGHTS_RECORD_ID, DEFAULT_ALIAS, PaymentEntityType, PLAN_RECORD_PREFIX, PRICING_POLICY_RECORD_ID, PRODUCT_RECORD_TYPE, PLAN_RECORD_TYPE, PRODUCT_RECORD_PREFIX, DEFAULT_PRICING_POLICY } from './consts.js'
+import type { ConsumerRightsPolicy, Localization, PaymentService, PricingPolicy, Product, ProductPlan } from './types.js'
 import type { Config, Context } from './utils/types.js'
-import { PLAN_RECORD_TYPE, PRODUCT_RECORD_PREFIX } from './consts.js'
 import { PaymentIdentificationError, UnknownPlan, UnknownProduct } from './errors.js'
-import type { Product, ProductPlan } from './types.js'
-import { fromConfigRecord } from '@owlmeans/config'
 import type { ResourceRecord } from '@owlmeans/resource'
 import { l10nToId } from './helper.js'
 import { DEFAULT_LNG } from '@owlmeans/i18n'
 import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
 import type { AuthCredentials } from '@owlmeans/auth'
+import { configHelper } from '@owlmeans/config'
 
 export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentService => {
   const service: PaymentService = createService<PaymentService>(alias, {
@@ -19,9 +16,7 @@ export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentServic
       const context = service.assertCtx() as Context
       const configRes = context.getConfigResource()
 
-      const result = fromConfigRecord<ConfigRecord, Product & ResourceRecord>(
-        await configRes.get(`${PRODUCT_RECORD_PREFIX}:${sku}`)
-      )
+      const result = configHelper.fromConfigRecord<ConfigRecord, Product & ResourceRecord>(await configRes.get(`${PRODUCT_RECORD_PREFIX}:${sku}`))
 
       if (result == null) {
         throw new UnknownProduct(sku)
@@ -36,7 +31,7 @@ export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentServic
 
       const { items } = await configRes.list({ recordType: PRODUCT_RECORD_TYPE })
 
-      return items.map(i => fromConfigRecord<ConfigRecord, Product & ResourceRecord>(i))
+      return items.map(i => configHelper.fromConfigRecord<ConfigRecord, Product & ResourceRecord>(i))
     },
 
     plans: async (productSku, duration) => {
@@ -48,7 +43,7 @@ export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentServic
       })
 
       return result.items.map(
-        item => fromConfigRecord<ConfigRecord, ProductPlan & ResourceRecord>(item)
+        item => configHelper.fromConfigRecord<ConfigRecord, ProductPlan & ResourceRecord>(item)
       )
     },
 
@@ -62,7 +57,7 @@ export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentServic
         throw new UnknownPlan(planSku)
       }
 
-      return fromConfigRecord<ConfigRecord, ProductPlan & ResourceRecord>(result)
+      return configHelper.fromConfigRecord<ConfigRecord, ProductPlan & ResourceRecord>(result)
     },
 
     allPlans: async productSku => {
@@ -74,7 +69,7 @@ export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentServic
       })
 
       return items.map(
-        item => fromConfigRecord<ConfigRecord, ProductPlan & ResourceRecord>(item)
+        item => configHelper.fromConfigRecord<ConfigRecord, ProductPlan & ResourceRecord>(item)
       )
     },
 
@@ -100,7 +95,7 @@ export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentServic
       for (let id of idsToCheck) {
         const l10n = await configRes.load(id)
         if (l10n != null) {
-          return fromConfigRecord<ConfigRecord, Localization & ResourceRecord>(l10n)
+          return configHelper.fromConfigRecord<ConfigRecord, Localization & ResourceRecord>(l10n)
         }
       }
 
@@ -118,6 +113,28 @@ export const makePaymentService = (alias: string = DEFAULT_ALIAS): PaymentServic
       }
 
       return auth.profileId
+    },
+
+    pricingPolicy: async () => {
+      const context = service.assertCtx() as Context
+      const configRes = context.getConfigResource()
+
+      const record = await configRes.load(PRICING_POLICY_RECORD_ID)
+
+      return record == null
+        ? DEFAULT_PRICING_POLICY
+        : configHelper.fromConfigRecord<ConfigRecord, PricingPolicy & ResourceRecord>(record)
+    },
+
+    consumerRightsPolicy: async () => {
+      const context = service.assertCtx() as Context
+      const configRes = context.getConfigResource()
+
+      const record = await configRes.load(CONSUMER_RIGHTS_RECORD_ID)
+
+      return record == null
+        ? null
+        : configHelper.fromConfigRecord<ConfigRecord, ConsumerRightsPolicy & ResourceRecord>(record)
     }
   }, service => async () => {
     service.initialized = true

package/src/types.local.ts

@@ -0,0 +1,5 @@
+import type { ConsumerRightsPolicy } from './types.js'
+
+export type RegionPolicy = Pick<ConsumerRightsPolicy, 'countries'> | null | undefined
+
+export type Dated = Record<string, unknown>