@owlmeans/server-payment 0.1.18-rc.0

package/src/types.ts

@@ -0,0 +1,157 @@
+import type { InitializedService, LazyService } from '@owlmeans/context'
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { MongoResource } from '@owlmeans/mongo-resource'
+import type { PluginConfig } from '@owlmeans/config'
+import type { PermissionSet } from '@owlmeans/auth'
+import type { Config as ApiConfig, Context as ApiContext } from '@owlmeans/server-api'
+import type {
+  AmountCheckoutPolicy, CheckoutPricingMode, LimitConfig, PlanDuration, Product, ProductPlan,
+  ProductType, QuantityCheckoutPolicy, SubscriptionStatus,
+} from '@owlmeans/payment'
+
+export interface Config extends ApiConfig {}
+export interface Context<C extends Config = Config> extends ApiContext<C> {}
+
+export interface PaymentProduct extends Product {
+  taxCode?: string
+  unitLabel?: string
+}
+
+export interface PaymentPlan extends ProductPlan {
+  recurring?: { interval: 'month' | 'year' }
+  minQuantity?: number
+  maxQuantity?: number
+  defaultQuantity?: number
+  pricingMode?: CheckoutPricingMode
+  amountPolicy?: AmountCheckoutPolicy
+  quantityPolicy?: QuantityCheckoutPolicy
+}
+
+export interface PaymentProductDef {
+  sku: string
+  type: ProductType
+  services: string[]
+  gateways?: string[]
+  taxCode?: string
+  name: string
+  description?: string
+  unitLabel?: string
+  defaultLng?: string
+  capabilities?: PermissionSet[]
+}
+
+export interface PaymentPlanDef {
+  productSku: string
+  sku: string
+  duration: PlanDuration
+  /** Reference unit price in major units; amount checkout uses it only for fulfillment conversion. */
+  price: number
+  currency?: string
+  recurring?: { interval: 'month' | 'year' }
+  order?: number
+  title?: string
+  capabilities?: PermissionSet[]
+  limits?: { [key: string]: LimitConfig }
+  pricingMode?: CheckoutPricingMode
+  amountPolicy?: AmountCheckoutPolicy
+  quantityPolicy?: QuantityCheckoutPolicy
+  /** Legacy quantity declarations retained for source compatibility. */
+  minQuantity?: number
+  maxQuantity?: number
+  defaultQuantity?: number
+}
+
+export interface StripePluginConfig extends PluginConfig { api: string; webhook: string }
+
+export interface CreateLinkParams {
+  productSku: string
+  /** Stable database key resolved by the application before this in-process call. */
+  entityId: string
+  profileId?: string
+  service: string
+  planSku?: string
+  amountMinor?: number
+  successUrl?: string
+  cancelUrl?: string
+}
+
+export interface PaymentPlugin {
+  createLink: (ctx: ApiContext, params: CreateLinkParams) => Promise<string>
+  handleWebhook: (request: unknown, ctx: ApiContext) => Promise<void>
+  initialize?: (ctx: ApiContext) => Promise<void>
+  manageSubscription: (ctx: ApiContext, entityId: string, returnUrl: string) => Promise<string>
+}
+export interface GatewayService extends InitializedService {
+  createLink: PaymentPlugin['createLink']
+  manageSubscription: PaymentPlugin['manageSubscription']
+}
+export interface PaymentResourceOptions { dbAlias?: string; serviceAlias?: string }
+
+interface TopUpBase {
+  entityId: string
+  productSku: string
+  planSku?: string
+  service: string
+  paygate: string
+  externalId: string
+}
+export interface QuantityTopUpCompletion extends TopUpBase {
+  mode: 'quantity'
+  units: number
+}
+export interface AmountTopUpCompletion extends TopUpBase {
+  mode: 'amount'
+  amountMinor: number
+  chargeAmountMinor: number
+  currency: string
+}
+export type TopUpCompletion = QuantityTopUpCompletion | AmountTopUpCompletion
+
+export interface SubscriptionCompletion {
+  entityId: string
+  status: SubscriptionStatus
+  productSku: string
+  planSku: string
+  service: string
+  paygate: string
+  externalId: string
+  isNew: boolean
+  capabilities?: PermissionSet[]
+  limits?: { [key: string]: LimitConfig }
+}
+export interface TopUpCallback { (completion: TopUpCompletion, ctx: ApiContext): Promise<void> }
+export interface SubscriptionCallback { (completion: SubscriptionCompletion, ctx: ApiContext): Promise<void> }
+export interface CompletionObserver extends LazyService {
+  onTopUp: (cb: TopUpCallback) => void
+  onSubscription: (cb: SubscriptionCallback) => void
+  propagateTopUp: (completion: TopUpCompletion, ctx: ApiContext) => Promise<void>
+  propagateSubscription: (completion: SubscriptionCompletion, ctx: ApiContext) => Promise<void>
+}
+
+export interface PaygateCustomerRecord extends ResourceRecord {
+  paygate: string; externalId: string; entityId?: string; profileId?: string
+  email?: string; name?: string; taxId?: string
+}
+export interface PaygateCustomerResource extends MongoResource<PaygateCustomerRecord> {
+  loadByPgId: (externalId: string, paygate: string) => Promise<PaygateCustomerRecord | null>
+  byEntity: (entityId: string, paygate: string) => Promise<PaygateCustomerRecord | null>
+}
+export interface PaymentSubscriptionRecord extends ResourceRecord {
+  sku: string; productSku: string; entityId: string; service: string; paygate: string
+  externalId: string; status: SubscriptionStatus; kind: 'consumable' | 'subscription'
+  capabilities?: PermissionSet[]; limits?: { [key: string]: LimitConfig }
+  pricingMode?: CheckoutPricingMode; units?: number; amountMinor?: number
+  chargeAmountMinor?: number; currency?: string
+  createdAt: Date; endsAt?: Date; trialUntil?: Date; canceledAt?: Date
+  fulfilledAt?: Date; initialPropagatedAt?: Date
+}
+export interface PaymentSubscriptionResource extends MongoResource<PaymentSubscriptionRecord> {
+  byExternalId: (externalId: string, paygate: string) => Promise<PaymentSubscriptionRecord | null>
+}
+export interface FingerprintRecord extends ResourceRecord {
+  sku: string; hash: string; productId?: string; updatedAt: Date
+}
+export interface FingerprintResource extends MongoResource<FingerprintRecord> {
+  bySku: (sku: string) => Promise<FingerprintRecord | null>
+  clear: () => Promise<void>
+}

package/src/utils.ts

@@ -0,0 +1,33 @@
+import Stripe from 'stripe'
+import { PLUGINS } from '@owlmeans/config'
+import { DEFAULT_ALIAS as PAYMENT_SERVICE, SubscriptionStatus } from '@owlmeans/payment'
+import type { PaymentService } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import {
+  GATEWAY_SERVICE, PAYMENT_OBSERVER, RES_PAYGATE_CUSTOMER, RES_PAYMENT_FINGERPRINT,
+  RES_PAYMENT_SUBSCRIPTION, STRIPE_PLUGIN_CONFIG,
+} from './consts.js'
+import type {
+  CompletionObserver, FingerprintResource, GatewayService, PaygateCustomerResource,
+  PaymentSubscriptionRecord, PaymentSubscriptionResource, StripePluginConfig,
+} from './types.js'
+
+export const payment = (ctx: ApiContext): PaymentService => ctx.service<PaymentService>(PAYMENT_SERVICE)
+export const gateway = (ctx: ApiContext): GatewayService => ctx.service<GatewayService>(GATEWAY_SERVICE)
+export const observer = (ctx: ApiContext): CompletionObserver => ctx.service<CompletionObserver>(PAYMENT_OBSERVER)
+export const paygateCustomers = (ctx: ApiContext): PaygateCustomerResource =>
+  ctx.resource<PaygateCustomerResource>(RES_PAYGATE_CUSTOMER)
+export const subscriptions = (ctx: ApiContext): PaymentSubscriptionResource =>
+  ctx.resource<PaymentSubscriptionResource>(RES_PAYMENT_SUBSCRIPTION)
+export const fingerprints = (ctx: ApiContext): FingerprintResource =>
+  ctx.resource<FingerprintResource>(RES_PAYMENT_FINGERPRINT)
+export const stripeConfig = async (ctx: ApiContext): Promise<StripePluginConfig> =>
+  await (ctx as never as { getConfigResource: (alias: string) => { get: (id: string) => Promise<unknown> } })
+    .getConfigResource(PLUGINS).get(STRIPE_PLUGIN_CONFIG) as StripePluginConfig
+export const stripeClient = async (ctx: ApiContext): Promise<Stripe> => new Stripe((await stripeConfig(ctx)).api)
+export const activeSubscription = async (
+  ctx: ApiContext, entityId: string, productSku: string,
+): Promise<PaymentSubscriptionRecord | null> => await subscriptions(ctx).load({
+  entityId, productSku, kind: 'subscription',
+  status: [SubscriptionStatus.Active, SubscriptionStatus.Trial],
+})

package/tests/checkout.spec.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from 'bun:test'
+import { CheckoutPricingMode, PlanDuration, PlanStatus, ProductType } from '@owlmeans/payment'
+import { PAYMENT_OBSERVER, RES_PAYMENT_SUBSCRIPTION } from '../src/consts.js'
+import { createEventHandler } from '../src/plugins/events.js'
+import { amountCheckoutLineItem, quantityCheckoutLineItem } from '../src/plugins/stripe.js'
+import type { PaymentPlan, PaymentProduct, PaymentSubscriptionRecord, TopUpCompletion } from '../src/types.js'
+
+const product: PaymentProduct = {
+  type: ProductType.Consumable, sku: 'credits', title: 'Credits', services: ['app'],
+}
+const plan: PaymentPlan = {
+  productSku: product.sku, sku: 'credits-unit', title: 'Credits', status: PlanStatus.Active,
+  duration: PlanDuration.Consumable, price: 0.02, currency: 'usd',
+  pricingMode: CheckoutPricingMode.Amount,
+  amountPolicy: {
+    currency: 'usd', minimumMinor: 500, maximumMinor: 50_000, defaultMinor: 1_000,
+    presetsMinor: [1_000, 2_000, 5_000, 10_000], fixedMinor: 0, rateBps: 200,
+  },
+}
+
+const paid = (overrides: Record<string, unknown> = {}) => ({
+  id: 'cs_amount', mode: 'payment', payment_status: 'paid', customer: 'cus_1',
+  currency: 'usd', amount_subtotal: 1021,
+  metadata: {
+    pricingMode: 'amount', amountMinor: '1000', chargeAmountMinor: '1021', currency: 'usd',
+    entityId: 'entity-1', service: 'app', productSku: 'credits', planSku: 'credits-unit',
+  },
+  ...overrides,
+})
+
+const harness = () => {
+  const records: PaymentSubscriptionRecord[] = []
+  const completions: TopUpCompletion[] = []
+  const subscriptions = {
+    byExternalId: async (id: string) => records.find(record => record.externalId === id) ?? null,
+    create: async (record: PaymentSubscriptionRecord) => {
+      const created = { ...record, id: String(records.length + 1) }
+      records.push(created)
+      return created
+    },
+    save: async (record: PaymentSubscriptionRecord) => {
+      const index = records.findIndex(item => item.id === record.id)
+      records[index] = { ...record }
+      return records[index]
+    },
+  }
+  const observer = { propagateTopUp: async (completion: TopUpCompletion) => { completions.push(completion) } }
+  const context = {
+    resource: (alias: string) => alias === RES_PAYMENT_SUBSCRIPTION ? subscriptions : undefined,
+    service: (alias: string) => alias === PAYMENT_OBSERVER ? observer : undefined,
+  }
+  const stripe = { checkout: { sessions: { listLineItems: async () => ({ data: [{ quantity: 7 }] }) } } }
+  return { records, completions, context, stripe }
+}
+
+describe('Stripe amount checkout', () => {
+  test('uses one inline, tax-exclusive item and no reusable Price', () => {
+    const result = amountCheckoutLineItem(product, plan, 1_000)
+    expect(result.chargeMinor).toBe(1_021)
+    expect(result.lineItem).toEqual({
+      price_data: { product: 'credits', currency: 'usd', unit_amount: 1_021, tax_behavior: 'exclusive' },
+      quantity: 1,
+    })
+    expect(result.lineItem.adjustable_quantity).toBeUndefined()
+  })
+
+  test('keeps reusable Price and adjustable quantity for quantity checkout', () => {
+    expect(quantityCheckoutLineItem({ id: 'price_1' } as never, {
+      minimum: 5, maximum: 500, default: 10,
+    })).toEqual({
+      price: 'price_1', quantity: 10,
+      adjustable_quantity: { enabled: true, minimum: 5, maximum: 500 },
+    })
+  })
+
+  test('fulfills a paid amount without crediting the adjustment', async () => {
+    const h = harness()
+    await createEventHandler(h.context as never, h.stripe as never).process({
+      type: 'checkout.session.completed', data: { object: paid() },
+    } as never)
+    expect(h.completions).toEqual([expect.objectContaining({ mode: 'amount', amountMinor: 1_000, chargeAmountMinor: 1_021 })])
+    expect(h.records[0]?.fulfilledAt).toBeInstanceOf(Date)
+  })
+
+  test('does not fulfill an unpaid completion; asynchronous success does', async () => {
+    const h = harness()
+    const handler = createEventHandler(h.context as never, h.stripe as never)
+    await handler.process({
+      type: 'checkout.session.completed', data: { object: paid({ payment_status: 'unpaid' }) },
+    } as never)
+    expect(h.completions).toHaveLength(0)
+    await handler.process({ type: 'checkout.session.async_payment_succeeded', data: { object: paid() } } as never)
+    expect(h.completions).toHaveLength(1)
+  })
+
+  test('rejects currency/subtotal metadata mismatches and is idempotent on retries', async () => {
+    const h = harness()
+    const handler = createEventHandler(h.context as never, h.stripe as never)
+    await expect(handler.process({
+      type: 'checkout.session.completed', data: { object: paid({ amount_subtotal: 1020 }) },
+    } as never)).rejects.toThrow()
+    await handler.process({ type: 'checkout.session.completed', data: { object: paid() } } as never)
+    await handler.process({ type: 'checkout.session.completed', data: { object: paid() } } as never)
+    expect(h.completions).toHaveLength(1)
+  })
+
+  test('retries fulfillment when the application observer fails', async () => {
+    const h = harness()
+    let attempts = 0
+    ;(h.context.service(PAYMENT_OBSERVER) as never as { propagateTopUp: () => Promise<void> })
+      .propagateTopUp = async () => {
+        attempts++
+        if (attempts === 1) throw new Error('ledger unavailable')
+        h.completions.push({ mode: 'amount' } as never)
+      }
+    const handler = createEventHandler(h.context as never, h.stripe as never)
+    const event = { type: 'checkout.session.completed', data: { object: paid() } } as never
+    await expect(handler.process(event)).rejects.toThrow('ledger unavailable')
+    expect(h.records[0]?.fulfilledAt).toBeUndefined()
+    await handler.process(event)
+    expect(attempts).toBe(2)
+    expect(h.records[0]?.fulfilledAt).toBeInstanceOf(Date)
+  })
+
+  test('legacy sessions without pricing metadata still fulfill by quantity', async () => {
+    const h = harness()
+    const legacy = paid({ id: 'cs_legacy', metadata: {
+      entityId: 'entity-1', service: 'app', productSku: 'credits', planSku: 'credits-unit',
+    } })
+    await createEventHandler(h.context as never, h.stripe as never).process({
+      type: 'checkout.session.completed', data: { object: legacy },
+    } as never)
+    expect(h.completions[0]).toEqual(expect.objectContaining({ mode: 'quantity', units: 7 }))
+  })
+})

package/tests/gate.spec.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig } from '@owlmeans/context'
+import type { AbstractRequest, AbstractResponse, GateService } from '@owlmeans/entrypoint'
+import type { Auth } from '@owlmeans/auth'
+import { AuthForbidden, AuthRole } from '@owlmeans/auth'
+import { CAPABILITY_FEATURE_SCOPE, ENTITLEMENT_GATE } from '@owlmeans/payment'
+import { SubscriptionStatus } from '@owlmeans/payment'
+import { filterRecords } from '@owlmeans/resource'
+import type { Criteria, ResourceRecord } from '@owlmeans/resource'
+import { RES_PAYMENT_SUBSCRIPTION } from '../src/consts.js'
+import { makeEntitlementGate } from '../src/gate.js'
+
+const record = (status: SubscriptionStatus, capabilities?: unknown[]) => ({
+  entityId: 'entity-1',
+  productSku: 'pro',
+  status,
+  capabilities: capabilities ?? [
+    { scope: 'renewable', permissions: { production: 1 } },
+    { scope: CAPABILITY_FEATURE_SCOPE, permissions: { 'branding--whitelabel': true } },
+  ],
+})
+
+/** The gate must fail closed, including when its subscription store is unreadable. */
+const makeGate = async (answer: () => unknown): Promise<GateService> => {
+  const ctx = makeBasicContext<BasicConfig>({
+    ready: false,
+    service: 'server-payment-tests',
+    type: AppType.Backend,
+  })
+  const resource = {
+    alias: RES_PAYMENT_SUBSCRIPTION,
+    list: async (where?: Criteria<ResourceRecord>) => {
+      const items = filterRecords(answer() as ResourceRecord[], where)
+      return { items, total: items.length }
+    },
+    registerContext: () => resource,
+    init: async () => undefined,
+    ready: async () => true,
+  }
+  ctx.registerResource(resource as never)
+  ctx.registerService(makeEntitlementGate())
+  ctx.configure()
+  await ctx.init()
+
+  return ctx.service<GateService>(ENTITLEMENT_GATE)
+}
+
+const request = (auth: Partial<Auth> | null = {}): AbstractRequest => ({
+  alias: 'test', headers: {}, params: {}, query: {}, body: {}, path: '/',
+  ...(auth != null ? {
+    auth: {
+      type: 'ed25519-basic-token', token: 't', userId: 'u', role: AuthRole.User,
+      scopes: [], entitySlug: 'entity-1', isUser: true, createdAt: new Date(), ...auth,
+    } satisfies Auth,
+  } : {}),
+}) as unknown as AbstractRequest
+
+const res = {} as AbstractResponse<unknown>
+
+describe('@owlmeans/server-payment — the entitlement gate', () => {
+  test('passes capabilities from active and trial subscriptions', async () => {
+    for (const status of [SubscriptionStatus.Active, SubscriptionStatus.Trial]) {
+      const gate = await makeGate(() => [record(status)])
+      await gate.assert(request(), res, ['feature:branding--whitelabel'])
+    }
+  })
+
+  test('refuses cancelled, missing, and unrelated capabilities', async () => {
+    const canceled = await makeGate(() => [record(SubscriptionStatus.Canceled)])
+    await expect(canceled.assert(request(), res, ['feature:branding--whitelabel']))
+      .rejects.toBeInstanceOf(AuthForbidden)
+    const unrelated = await makeGate(() => [record(SubscriptionStatus.Active)])
+    await expect(unrelated.assert(request(), res, ['feature:domain--custom']))
+      .rejects.toBeInstanceOf(AuthForbidden)
+  })
+
+  test('treats gate parameters as any-of', async () => {
+    const gate = await makeGate(() => [record(SubscriptionStatus.Active)])
+    await gate.assert(request(), res, ['feature:nothing--here', 'feature:branding--whitelabel'])
+  })
+
+  test('refuses missing authentication or organization before reading storage', async () => {
+    const unread = await makeGate(() => { throw new Error('must not be reached') })
+    await expect(unread.assert(request(null), res, ['feature:branding--whitelabel']))
+      .rejects.toBeInstanceOf(AuthForbidden)
+    const noEntity = await makeGate(() => [])
+    await expect(noEntity.assert(request({ entitySlug: undefined }), res, ['feature:branding--whitelabel']))
+      .rejects.toBeInstanceOf(AuthForbidden)
+  })
+
+  test('refuses when the subscription store is unreadable', async () => {
+    const gate = await makeGate(() => { throw new Error('mongo is down') })
+    await expect(gate.assert(request(), res, ['feature:branding--whitelabel']))
+      .rejects.toBeInstanceOf(AuthForbidden)
+  })
+})

package/tests/protocol.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test'
+import type { ParamsOf, ResponseOf } from '@owlmeans/entrypoint'
+import { paymentGate, paymentGateProtocols } from '../src/index.js'
+
+describe('server payment protocols', () => {
+  test('bind webhook params and resync response to their declarations', () => {
+    const params: ParamsOf<typeof paymentGate.webhook> = { paygate: 'stripe' }
+    const response: ResponseOf<typeof paymentGate.resync> = { ok: true }
+
+    expect(params.paygate).toBe('stripe')
+    expect(response.ok).toBe(true)
+    expect(paymentGate.webhook.route.route.parent).toBe(paymentGate.base.alias)
+  })
+
+  test('exports a flattened list of immutable protocol objects', () => {
+    expect(paymentGateProtocols).toContain(paymentGate.webhook)
+    expect(paymentGateProtocols.every(item => item.kind === 'entrypoint-protocol')).toBe(true)
+    expect(Object.isFrozen(paymentGate.resync)).toBe(true)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": ["@owlmeans/dep-config/tsconfig.base.json"],
+  "compilerOptions": { "types": ["bun"], "rootDir": "../", "noEmit": true },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts", "./tests/**/*"]
+}