@owlmeans/server-payment 0.1.18-rc.2 → 0.1.18-rc.21

package/tests/entitlement.spec.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test'
+import { INTERNAL_PAYGATE, PlanRequired, SubscriptionStatus } from '@owlmeans/payment'
+import { entitlements, subscriptions } from '../src/utils.js'
+import type { PaymentSubscriptionRecord } from '../src/types.js'
+import {
+  CAP_PREVIEW, CAP_WHITELABEL, FREE, future, makeFakeContext, past, PLANS_PRODUCT, PRO, TEAM,
+} from './fake-stripe.js'
+import type { FakeContext } from './fake-stripe.js'
+
+const seed = async (
+  fake: FakeContext, planSku: string, overrides: Partial<PaymentSubscriptionRecord> = {},
+): Promise<PaymentSubscriptionRecord> => await subscriptions(fake.ctx).create({
+  entityId: 'entity-1', planSku, productSku: PLANS_PRODUCT, service: 'app', paygate: 'stripe',
+  externalId: `sub_${planSku}_${Math.random().toString(16).slice(2, 8)}`, status: SubscriptionStatus.Active,
+  rank: planSku === TEAM ? 20 : planSku === PRO ? 10 : 0, createdAt: past(5), ...overrides,
+})
+
+describe('@owlmeans/server-payment — effective plan', () => {
+  test('the highest-ranked entitling subscription wins, the newest on a tie', async () => {
+    const fake = await makeFakeContext()
+    await seed(fake, FREE, { paygate: INTERNAL_PAYGATE, externalId: 'free:entity-1' })
+    await seed(fake, PRO, { status: SubscriptionStatus.PastDue })
+    await seed(fake, TEAM, { status: SubscriptionStatus.Canceled })
+    const older = await seed(fake, PRO, { createdAt: past(20) })
+
+    const effective = await entitlements(fake.ctx).effectivePlan('entity-1')
+    expect(effective.plan.sku).toBe(PRO)
+    expect(effective.subscription?.status).toBe(SubscriptionStatus.PastDue)
+    expect(effective.subscription?.externalId).not.toBe(older.externalId)
+    expect(effective.fallback?.sku).toBe(FREE)
+  })
+
+  test('falls back to the free plan past suspended rows, expired internal grants and unknown plans', async () => {
+    const fake = await makeFakeContext()
+    await seed(fake, TEAM, { status: SubscriptionStatus.Suspended })
+    await seed(fake, TEAM, { paygate: INTERNAL_PAYGATE, periodEnd: past(1) })
+    await seed(fake, 'retired-plan', { rank: 99 })
+
+    const effective = await entitlements(fake.ctx).effectivePlan('entity-1')
+    expect(effective.plan.sku).toBe(FREE)
+    expect(effective.subscription).toBeNull()
+
+    await seed(fake, PRO, { paygate: INTERNAL_PAYGATE, periodEnd: future(1) })
+    expect((await entitlements(fake.ctx).effectivePlan('entity-1')).plan.sku).toBe(PRO)
+  })
+
+  test('without a free plan and without a subscription it is a PlanRequired fault', async () => {
+    const fake = await makeFakeContext({ catalogue: { free: false } })
+    await expect(entitlements(fake.ctx).effectivePlan('entity-1')).rejects.toBeInstanceOf(PlanRequired)
+  })
+})
+
+describe('@owlmeans/server-payment — the entitlement view', () => {
+  test('describes the plan behind it: subscribed-at, past-due and the fallback', async () => {
+    const fake = await makeFakeContext()
+    const row = await seed(fake, PRO, {
+      status: SubscriptionStatus.PastDue, periodEnd: future(10), cancelAtPeriodEnd: true,
+    })
+
+    const view = await entitlements(fake.ctx).entitlements('entity-1')
+    expect(view.plan).toEqual(expect.objectContaining({
+      sku: PRO, rank: 10, free: false, status: SubscriptionStatus.PastDue, paygate: 'stripe',
+      subscriptionId: row.externalId, pastDue: true, fallbackSku: FREE, cancelAtPeriodEnd: true,
+    }))
+    expect(view.plan.subscribedAt?.getTime()).toBe(row.createdAt.getTime())
+
+    const free = await entitlements(fake.ctx).entitlements('entity-2')
+    expect(free.plan).toEqual(expect.objectContaining({ sku: FREE, free: true, paygate: INTERNAL_PAYGATE }))
+    expect(free.plan.fallbackSku).toBeUndefined()
+  })
+
+  test('reads usage from the current window counter only', async () => {
+    const fake = await makeFakeContext()
+    await seed(fake, PRO)
+    await entitlements(fake.ctx).consume({ entityId: 'entity-1', limitKey: 'exports', eventKey: 'export:1' })
+    fake.stores['payment-usage-counter'].rows.push({
+      entityId: 'entity-1', limitKey: 'exports', window: '2001-01-01', used: 3, limit: 3, updatedAt: past(9000),
+    })
+
+    const exports = (await entitlements(fake.ctx).entitlements('entity-1')).limits.find(limit => limit.key === 'exports')
+    expect(exports).toEqual(expect.objectContaining({ used: 1, limit: 3, remaining: 2 }))
+  })
+
+  test('grandfathers a promo for a subscription created before it ended, and lapses it otherwise', async () => {
+    const fake = await makeFakeContext({ catalogue: { reportsUntil: past(2), previewUntil: past(2) } })
+    await seed(fake, PRO, { entityId: 'early', createdAt: past(10) })
+    await seed(fake, PRO, { entityId: 'late', createdAt: past(1) })
+
+    const early = await entitlements(fake.ctx).entitlements('early')
+    const late = await entitlements(fake.ctx).entitlements('late')
+    expect(early.limits.find(limit => limit.key === 'reports')).toEqual(expect.objectContaining({
+      limit: 4, promo: expect.objectContaining({ active: true, grandfathered: true }),
+    }))
+    expect(late.limits.find(limit => limit.key === 'reports')).toEqual(expect.objectContaining({
+      limit: 0, promo: expect.objectContaining({ active: false, grandfathered: false }),
+    }))
+
+    // The free plan's preview promo does not grandfather: lapsed for everyone.
+    expect(await entitlements(fake.ctx).hasCapability('nobody', CAP_PREVIEW)).toBe(false)
+    expect(await entitlements(fake.ctx).hasCapability('early', CAP_WHITELABEL)).toBe(true)
+    expect(await entitlements(fake.ctx).hasCapability('nobody', CAP_WHITELABEL)).toBe(false)
+  })
+})

package/tests/estimate.spec.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from 'bun:test'
+import { PaygateError, TaxBehavior, TaxEstimateStatus, TaxType } from '@owlmeans/payment'
+import { makeEstimateCache, estimateStripePrice } from '../src/plugins/estimate.js'
+import { gateway, paygateCustomers } from '../src/utils.js'
+import { CREDITS_PRODUCT, makeFakeContext, PLANS_PRODUCT, PRO } from './fake-stripe.js'
+import type { FakeContext } from './fake-stripe.js'
+
+const withCustomer = async (
+  fake: FakeContext, entityId: string, country: string, taxIds: Array<{ type: string, value: string, country: string }> = [],
+  taxExempt: string = 'none',
+) => {
+  await paygateCustomers(fake.ctx).create({ paygate: 'stripe', externalId: `cus_${entityId}`, entityId })
+  fake.state.customers[`cus_${entityId}`] = {
+    id: `cus_${entityId}`, object: 'customer', address: { country }, tax_exempt: taxExempt,
+    tax_ids: { object: 'list', data: taxIds },
+  }
+}
+
+const estimatingPolicy = { tax: { automatic: true, collectTaxId: true, estimate: true }, currency: { adaptive: true, estimate: true } }
+
+describe('@owlmeans/server-payment — Stripe Tax price estimate', () => {
+  test('taxes the reference amount of a recurring plan at a given country, half-cent rounded up', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } },
+    })
+    const cache = makeEstimateCache()
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, cache)
+    expect(result).toEqual(expect.objectContaining({
+      country: 'PL', source: 'request', currency: 'usd', behavior: TaxBehavior.Exclusive,
+    }))
+    expect(result.tax).toEqual({
+      status: TaxEstimateStatus.Taxed, subtotalMinor: 2_000, taxMinor: 460, totalMinor: 2_460,
+      scalable: true, rates: [{ type: TaxType.Vat, percentage: '23', ratePpm: 230_000, country: 'PL' }],
+    })
+  })
+
+  test('taxes an amount-priced consumable at its default preset, gross-up included', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } },
+    })
+    const cache = makeEstimateCache()
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: CREDITS_PRODUCT, country: 'PL',
+    }, cache)
+    // the credit unit's default preset is 1_000, grossed up to 1_021 by its own amount policy
+    expect(result.tax.subtotalMinor).toBe(1_021)
+    expect(result.tax.taxMinor).toBe(235)
+    expect(result.tax.totalMinor).toBe(1_256)
+  })
+
+  test('no request country and no paygate customer: `location-required`, zero Stripe calls', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    const cache = makeEstimateCache()
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'unknown-entity', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, cache)
+    expect(result.tax.status).toBe(TaxEstimateStatus.LocationRequired)
+    expect(fake.state.calls).not.toContain('tax.calculations.create')
+  })
+
+  test("falls back to the entity's paygate customer address, tagged `source: 'customer'`", async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { DE: [{ type: 'vat', percentage: '19' }] } },
+    })
+    await withCustomer(fake, 'entity-1', 'DE')
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, makeEstimateCache())
+    expect(result.country).toBe('DE')
+    expect(result.source).toBe('customer')
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+  })
+
+  test('a saved tax id for a DIFFERENT country than the resolved one is never sent', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } },
+    })
+    await withCustomer(fake, 'entity-1', 'PL', [{ type: 'eu_vat', value: 'DE123456789', country: 'DE' }])
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, makeEstimateCache())
+    // taxed, not reverse-charged — the DE tax id never reached the calculation
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+    expect(fake.state.taxCalculations[0].customer_details.tax_ids).toBeUndefined()
+  })
+
+  test('a matching-country tax id triggers reverse charge, with zero tax', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { DE: [{ type: 'vat', percentage: '19' }] } },
+    })
+    await withCustomer(fake, 'entity-1', 'DE', [{ type: 'eu_vat', value: 'DE123456789', country: 'DE' }])
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.ReverseCharge)
+    expect(result.tax.taxMinor).toBe(0)
+    expect(result.tax.totalMinor).toBe(2_000)
+  })
+
+  test('an unconfigured country (no registration) reads `none`', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'FR',
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.None)
+    expect(result.tax.taxMinor).toBe(0)
+  })
+
+  test('a jurisdiction Stripe Tax does not cover reads `at-checkout`', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxUnsupportedCountries: ['CU'] } })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'CU',
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.AtCheckout)
+  })
+
+  test('a Stripe invalid-request error (e.g. US missing a postal code) reads `at-checkout`, and the outcome is cached', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxInvalidCountries: ['US'] } })
+    const cache = makeEstimateCache()
+    const first = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, cache)
+    expect(first.tax.status).toBe(TaxEstimateStatus.AtCheckout)
+    const callsAfterFirst = fake.state.calls.filter(name => name === 'tax.calculations.create').length
+    await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, cache)
+    expect(fake.state.calls.filter(name => name === 'tax.calculations.create')).toHaveLength(callsAfterFirst)
+  })
+
+  test('an identical request within the cache TTL makes exactly one Stripe Tax call; a different entity with its own tax id makes another', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } } })
+    const cache = makeEstimateCache()
+    const params = { entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL' }
+    await estimateStripePrice(fake.ctx, fake.stripe, params, cache)
+    await estimateStripePrice(fake.ctx, fake.stripe, params, cache)
+    expect(fake.state.taxCalculations).toHaveLength(1)
+
+    await withCustomer(fake, 'entity-2', 'PL', [{ type: 'eu_vat', value: 'PL123456789', country: 'PL' }])
+    await estimateStripePrice(fake.ctx, fake.stripe, { ...params, entityId: 'entity-2' }, cache)
+    expect(fake.state.taxCalculations).toHaveLength(2)
+  })
+
+  test('never caches a rate-limit or connection error', async () => {
+    let fail = true
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } } })
+    const cache = makeEstimateCache()
+    const original = (fake.stripe as never as { tax: { calculations: { create: (...args: unknown[]) => unknown } } })
+      .tax.calculations.create
+    ;(fake.stripe as never as { tax: { calculations: { create: (...args: unknown[]) => unknown } } })
+      .tax.calculations.create = async (...args: unknown[]) => {
+        if (fail) { fail = false; throw new Error('connection reset') }
+        return await original(...args)
+      }
+    const params = { entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL' }
+    await expect(estimateStripePrice(fake.ctx, fake.stripe, params, cache)).rejects.toThrow('connection reset')
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, params, cache)
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+  })
+
+  test('carries a local-currency conversion from the FX Quotes API, requested to_currency=usd from_currencies=[local]', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy,
+      stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] }, fxRates: { pln: { exchangeRate: 0.25, fxFeeRate: 0.02 } } },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.local).toEqual({ currency: 'pln', exchangeRate: 0.25, fxFeeRate: 0.02 })
+    expect(fake.state.rawRequests[0]).toEqual(expect.objectContaining({
+      method: 'POST', path: '/v1/fx_quotes', params: { to_currency: 'usd', 'from_currencies[]': 'pln', lock_duration: 'none' },
+    }))
+  })
+
+  test('estimates the same USD to EUR to local chain used by settlement and Adaptive Pricing', async () => {
+    const fake = await makeFakeContext({
+      pricing: { ...estimatingPolicy, stripe: { settlementCurrency: 'eur' } },
+      stripe: {
+        taxRates: { PL: [{ type: 'vat', percentage: '23' }] },
+        fxRates: {
+          usd: { exchangeRate: 0.853568, referenceRate: 0.8726 },
+          pln: { exchangeRate: 0.22, referenceRate: 0.224, fxFeeRate: 0.02 },
+        },
+      },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.local?.currency).toBe('pln')
+    expect(result.local?.exchangeRate).toBeCloseTo(0.22 / 0.8726)
+    expect(fake.state.rawRequests.map(request => request.params)).toEqual([
+      { to_currency: 'eur', 'from_currencies[]': 'usd', lock_duration: 'none' },
+      { to_currency: 'eur', 'from_currencies[]': 'pln', lock_duration: 'none' },
+    ])
+  })
+
+  test('omits `local` when the FX Quotes call fails, without failing the estimate', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] }, fxUnavailable: true },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+    expect(result.local).toBeUndefined()
+  })
+
+  test('omits `local` for a US billing country (same currency as the integration currency), with no FX call', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, makeEstimateCache())
+    expect(result.local).toBeUndefined()
+    expect(fake.state.rawRequests).toHaveLength(0)
+  })
+
+  test('`currency.estimate: false` never computes a local total, even with `currency.adaptive: true`', async () => {
+    const fake = await makeFakeContext({
+      pricing: {
+        tax: { automatic: true, collectTaxId: true, estimate: true },
+        currency: { adaptive: true, estimate: false },
+      },
+      stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] }, fxRates: { pln: { exchangeRate: 0.25 } } },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.local).toBeUndefined()
+    expect(fake.state.rawRequests).toHaveLength(0)
+  })
+
+  test('an unmanaged gateway throws PaygateError before ever reaching Stripe', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    await expect(gateway(fake.ctx).estimatePrice(fake.ctx, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    })).rejects.toBeInstanceOf(PaygateError)
+  })
+})