@owlmeans/server-payment 0.1.18-rc.0

package/src/plugins/events.ts

@@ -0,0 +1,181 @@
+import type Stripe from 'stripe'
+import { Mutex } from 'async-mutex'
+import {
+  CheckoutPricingMode, PaygateError, PlanDuration, SubscriptionStatus,
+} from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_PAYGATE_ALIAS } from '../consts.js'
+import { observer, payment, paygateCustomers, subscriptions } from '../utils.js'
+import type { PaymentPlan, PaymentSubscriptionRecord, TopUpCompletion } from '../types.js'
+
+const customerMutex: Record<string, Mutex> = {}
+const lockOn = async (customerId: string) => {
+  customerMutex[customerId] = customerMutex[customerId] ?? new Mutex()
+  return customerMutex[customerId].acquire()
+}
+const unlockOn = (customerId: string) => {
+  const mutex = customerMutex[customerId]
+  if (mutex != null) {
+    mutex.release()
+    if (!mutex.isLocked()) delete customerMutex[customerId]
+  }
+}
+const customerIdOf = (value: string | { id?: string } | null): string =>
+  typeof value === 'string' ? value : (value?.id ?? '')
+const mapStatus = (status: Stripe.Subscription.Status): SubscriptionStatus => {
+  switch (status) {
+    case 'active': return SubscriptionStatus.Active
+    case 'trialing': return SubscriptionStatus.Trial
+    case 'past_due':
+    case 'unpaid': return SubscriptionStatus.Expired
+    case 'canceled': return SubscriptionStatus.Canceled
+    case 'incomplete':
+    case 'incomplete_expired':
+    case 'paused': return SubscriptionStatus.Suspended
+    default: return SubscriptionStatus.Created
+  }
+}
+const integerMetadata = (metadata: Stripe.Metadata, key: string): number => {
+  const raw = metadata[key]
+  const value = raw == null || raw.trim() === '' ? Number.NaN : Number(raw)
+  if (!Number.isSafeInteger(value)) throw new PaygateError(`metadata:${key}`)
+  return value
+}
+
+export const createEventHandler = (context: ApiContext, stripe: Stripe) => {
+  const fulfillPayment = async (session: Stripe.Checkout.Session): Promise<void> => {
+    if (session.mode !== 'payment' || session.payment_status !== 'paid') return
+    const metadata = session.metadata ?? {}
+    if (metadata.entityId == null || metadata.service == null || metadata.productSku == null) {
+      throw new PaygateError('metadata:owner')
+    }
+    const customerId = customerIdOf(session.customer)
+    await lockOn(customerId)
+    try {
+      let stored = await subscriptions(context).byExternalId(session.id, STRIPE_PAYGATE_ALIAS)
+      if (stored?.fulfilledAt != null) return
+
+      const amountMode = metadata.pricingMode === CheckoutPricingMode.Amount
+      let completion: TopUpCompletion
+      let record: PaymentSubscriptionRecord
+      if (amountMode) {
+        const amountMinor = integerMetadata(metadata, 'amountMinor')
+        const chargedMinor = integerMetadata(metadata, 'chargeAmountMinor')
+        const currency = metadata.currency?.toLowerCase()
+        if (currency == null || session.currency?.toLowerCase() !== currency
+          || session.amount_subtotal !== chargedMinor || amountMinor <= 0 || chargedMinor < amountMinor) {
+          throw new PaygateError('amount-mismatch')
+        }
+        record = {
+          sku: metadata.planSku ?? metadata.productSku, productSku: metadata.productSku,
+          entityId: metadata.entityId, service: metadata.service, paygate: STRIPE_PAYGATE_ALIAS,
+          externalId: session.id, status: SubscriptionStatus.Consumable, kind: 'consumable',
+          pricingMode: CheckoutPricingMode.Amount, amountMinor, chargeAmountMinor: chargedMinor,
+          currency, createdAt: new Date(),
+        }
+        completion = {
+          mode: 'amount', entityId: metadata.entityId, amountMinor,
+          chargeAmountMinor: chargedMinor, currency, productSku: metadata.productSku,
+          planSku: metadata.planSku, service: metadata.service,
+          paygate: STRIPE_PAYGATE_ALIAS, externalId: session.id,
+        }
+      } else {
+        if (metadata.currency != null && session.currency?.toLowerCase() !== metadata.currency.toLowerCase()) {
+          throw new PaygateError('currency-mismatch')
+        }
+        const lineItems = await stripe.checkout.sessions.listLineItems(session.id, { limit: 100 })
+        const units = lineItems.data.reduce((sum, line) => sum + (line.quantity ?? 0), 0)
+        if (units <= 0) throw new PaygateError('units')
+        record = {
+          sku: metadata.planSku ?? metadata.productSku, productSku: metadata.productSku,
+          entityId: metadata.entityId, service: metadata.service, paygate: STRIPE_PAYGATE_ALIAS,
+          externalId: session.id, status: SubscriptionStatus.Consumable, kind: 'consumable', units,
+          pricingMode: CheckoutPricingMode.Quantity,
+          capabilities: [{ scope: PlanDuration.Consumable, permissions: { units } }],
+          createdAt: new Date(),
+        }
+        completion = {
+          mode: 'quantity', entityId: metadata.entityId, units, productSku: metadata.productSku,
+          planSku: metadata.planSku, service: metadata.service,
+          paygate: STRIPE_PAYGATE_ALIAS, externalId: session.id,
+        }
+      }
+      if (stored == null) stored = await subscriptions(context).create(record)
+      await observer(context).propagateTopUp(completion, context)
+      await subscriptions(context).save({ ...stored, fulfilledAt: new Date() })
+    } finally {
+      unlockOn(customerId)
+    }
+  }
+
+  const handler = {
+    process: async (event: Stripe.Event) => {
+      if (event.type in handler) await (handler as never as Record<string, (event: Stripe.Event) => Promise<void>>)[event.type](event)
+    },
+    'customer.created': async (event: Stripe.CustomerCreatedEvent) => handler._upsertCustomer(event.data.object),
+    'customer.updated': async (event: Stripe.CustomerUpdatedEvent) => handler._upsertCustomer(event.data.object),
+    'checkout.session.completed': async (event: Stripe.CheckoutSessionCompletedEvent) => fulfillPayment(event.data.object),
+    'checkout.session.async_payment_succeeded': async (event: Stripe.CheckoutSessionAsyncPaymentSucceededEvent) =>
+      fulfillPayment(event.data.object),
+    'customer.subscription.created': async (event: Stripe.CustomerSubscriptionCreatedEvent) => handler._syncSubscription(event.data.object),
+    'customer.subscription.updated': async (event: Stripe.CustomerSubscriptionUpdatedEvent) => handler._syncSubscription(event.data.object),
+    'customer.subscription.deleted': async (event: Stripe.CustomerSubscriptionDeletedEvent) =>
+      handler._syncSubscription(event.data.object, SubscriptionStatus.Canceled),
+
+    _upsertCustomer: async (customer: Stripe.Customer) => {
+      const resource = paygateCustomers(context)
+      await lockOn(customer.id)
+      try {
+        const existing = await resource.loadByPgId(customer.id, STRIPE_PAYGATE_ALIAS)
+        const data = {
+          email: customer.email ?? undefined, name: customer.name ?? undefined,
+          taxId: customer.tax_ids?.data?.[0]?.value ?? undefined,
+          entityId: customer.metadata?.entityId ?? existing?.entityId,
+          profileId: customer.metadata?.profileId ?? existing?.profileId,
+        }
+        if (existing == null) await resource.create({ paygate: STRIPE_PAYGATE_ALIAS, externalId: customer.id, ...data })
+        else { Object.assign(existing, data); await resource.save(existing) }
+      } finally { unlockOn(customer.id) }
+    },
+
+    _syncSubscription: async (pgSubscription: Stripe.Subscription, forced?: SubscriptionStatus) => {
+      const metadata = pgSubscription.metadata ?? {}
+      const customerId = customerIdOf(pgSubscription.customer)
+      await lockOn(customerId)
+      try {
+        const status = forced ?? mapStatus(pgSubscription.status)
+        for (const item of pgSubscription.items.data) {
+          const planSku = item.price.lookup_key ?? metadata.planSku
+          const entityId = metadata.entityId
+          if (planSku == null || entityId == null) continue
+          let plan: PaymentPlan | null = null
+          try { plan = await payment(context).plan(planSku) as PaymentPlan } catch { /* archived plan */ }
+          const productSku = plan?.productSku ?? metadata.productSku ?? planSku
+          const service = metadata.service ?? productSku
+          let record = await subscriptions(context).byExternalId(item.id, STRIPE_PAYGATE_ALIAS)
+          const isNew = record?.initialPropagatedAt == null
+          const values: Partial<PaymentSubscriptionRecord> = {
+            sku: planSku, productSku, entityId, service, paygate: STRIPE_PAYGATE_ALIAS,
+            externalId: item.id, status, kind: 'subscription',
+            ...(plan?.capabilities != null && { capabilities: plan.capabilities }),
+            ...(plan?.limits != null && { limits: plan.limits }),
+            endsAt: (pgSubscription as never as { current_period_end?: number }).current_period_end != null
+              ? new Date((pgSubscription as never as { current_period_end: number }).current_period_end * 1000) : undefined,
+            canceledAt: status === SubscriptionStatus.Canceled ? new Date() : undefined,
+          }
+          if (record == null) record = await subscriptions(context).create({ createdAt: new Date(), ...values } as PaymentSubscriptionRecord)
+          else { Object.assign(record, values); await subscriptions(context).save(record) }
+          await observer(context).propagateSubscription({
+            entityId, status, productSku, planSku, service, paygate: STRIPE_PAYGATE_ALIAS,
+            externalId: item.id, isNew, capabilities: plan?.capabilities, limits: plan?.limits,
+          }, context)
+          if (isNew) {
+            record.initialPropagatedAt = new Date()
+            await subscriptions(context).save(record)
+          }
+        }
+      } finally { unlockOn(customerId) }
+    },
+  }
+  return handler
+}

package/src/plugins/stripe.ts

@@ -0,0 +1,183 @@
+import Stripe from 'stripe'
+import {
+  assertCheckoutAmount, chargeAmountMinor, CheckoutPricingMode, PaygateError, ProductError, ProductType,
+} from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_PAYGATE_ALIAS, STRIPE_SIGNATURE } from '../consts.js'
+import { paygateCustomers, payment, stripeClient, stripeConfig } from '../utils.js'
+import { planLookupKey } from '../sync.js'
+import { createEventHandler } from './events.js'
+import type { CreateLinkParams, PaymentPlan, PaymentPlugin, PaymentProduct } from '../types.js'
+
+const taxOptions = (promotions: boolean): Partial<Stripe.Checkout.SessionCreateParams> => ({
+  automatic_tax: { enabled: true },
+  billing_address_collection: 'required',
+  tax_id_collection: { enabled: true },
+  customer_update: { address: 'auto', name: 'auto' },
+  allow_promotion_codes: promotions,
+})
+
+const ensureStripeCustomer = async (
+  ctx: ApiContext, stripe: Stripe, params: CreateLinkParams,
+): Promise<Stripe.Customer> => {
+  const resource = paygateCustomers(ctx)
+  const existing = await resource.byEntity(params.entityId, STRIPE_PAYGATE_ALIAS)
+  if (existing != null) {
+    const retrieved = await stripe.customers.retrieve(existing.externalId)
+    if (!(retrieved as Stripe.DeletedCustomer).deleted) return retrieved as Stripe.Customer
+  }
+  const created = await stripe.customers.create({
+    metadata: {
+      entityId: params.entityId, ...(params.profileId && { profileId: params.profileId }),
+      service: params.service,
+    },
+  })
+  if (existing != null) {
+    Object.assign(existing, { externalId: created.id })
+    await resource.save(existing)
+  } else {
+    await resource.create({
+      paygate: STRIPE_PAYGATE_ALIAS, externalId: created.id, entityId: params.entityId,
+      profileId: params.profileId,
+    })
+  }
+  return created
+}
+
+const findPrice = async (stripe: Stripe, productSku: string, lookupKey: string): Promise<Stripe.Price> => {
+  const prices = await stripe.prices.list({ product: productSku, active: true, lookup_keys: [lookupKey] })
+  if (prices.data.length === 0) throw new ProductError(`price:${lookupKey}`)
+  return prices.data[0]
+}
+
+const sharedSession = (
+  customer: Stripe.Customer, params: CreateLinkParams, product: PaymentProduct,
+  plan: PaymentPlan, metadata: Record<string, string>,
+): Pick<Stripe.Checkout.SessionCreateParams, 'customer' | 'success_url' | 'cancel_url' | 'metadata'> => ({
+  customer: customer.id,
+  success_url: params.successUrl,
+  cancel_url: params.cancelUrl ?? params.successUrl,
+  metadata: {
+    pricingMode: plan.pricingMode ?? CheckoutPricingMode.Quantity,
+    currency: (plan.currency ?? 'usd').toLowerCase(),
+    entityId: params.entityId,
+    ...(params.profileId && { profileId: params.profileId }),
+    service: params.service,
+    productSku: product.sku,
+    planSku: plan.sku,
+    ...metadata,
+  },
+})
+
+export const amountCheckoutLineItem = (
+  product: PaymentProduct, plan: PaymentPlan, amountMinor: number,
+): { lineItem: Stripe.Checkout.SessionCreateParams.LineItem; chargeMinor: number; currency: string } => {
+  if (plan.amountPolicy == null) throw new ProductError(`amount-policy:${plan.sku}`)
+  assertCheckoutAmount(plan.amountPolicy, amountMinor)
+  const chargeMinor = chargeAmountMinor(amountMinor, plan.amountPolicy)
+  const currency = plan.amountPolicy.currency.toLowerCase()
+  return {
+    lineItem: {
+      price_data: {
+        product: product.sku, currency, unit_amount: chargeMinor, tax_behavior: 'exclusive',
+      },
+      quantity: 1,
+    },
+    chargeMinor,
+    currency,
+  }
+}
+
+export const quantityCheckoutLineItem = (
+  price: Stripe.Price, policy: { minimum: number; maximum: number; default: number },
+): Stripe.Checkout.SessionCreateParams.LineItem => ({
+  price: price.id,
+  adjustable_quantity: { enabled: true, minimum: policy.minimum, maximum: policy.maximum },
+  quantity: policy.default,
+})
+
+export const stripePlugin: PaymentPlugin = {
+  createLink: async (ctx, params) => {
+    const stripe = await stripeClient(ctx)
+    const product = await payment(ctx).product(params.productSku) as PaymentProduct
+    const plans = await payment(ctx).allPlans(product.sku) as PaymentPlan[]
+    const customer = await ensureStripeCustomer(ctx, stripe, params)
+
+    if (product.type === ProductType.Consumable) {
+      const plan = plans.find(item => item.sku === params.planSku) ?? plans[0]
+      if (plan == null) throw new ProductError('plan')
+
+      if (plan.pricingMode === CheckoutPricingMode.Amount) {
+        if (params.amountMinor == null) throw new ProductError('amount')
+        const { lineItem, chargeMinor, currency } = amountCheckoutLineItem(product, plan, params.amountMinor)
+        const session = await stripe.checkout.sessions.create({
+          mode: 'payment', line_items: [lineItem], invoice_creation: { enabled: true },
+          ...taxOptions(false),
+          ...sharedSession(customer, params, product, plan, {
+            pricingMode: CheckoutPricingMode.Amount,
+            currency,
+            amountMinor: String(params.amountMinor),
+            chargeAmountMinor: String(chargeMinor),
+          }),
+        })
+        if (session.url == null) throw new PaygateError('session')
+        return session.url
+      }
+
+      const price = await findPrice(stripe, product.sku, planLookupKey(product, plan))
+      const policy = plan.quantityPolicy ?? {
+        minimum: plan.minQuantity ?? plan.limits?.['consumable:units']?.limit ?? 1,
+        maximum: plan.maxQuantity ?? Math.max(100_000, plan.minQuantity ?? 1),
+        default: plan.defaultQuantity ?? plan.minQuantity ?? 1,
+      }
+      const session = await stripe.checkout.sessions.create({
+        mode: 'payment',
+        line_items: [quantityCheckoutLineItem(price, policy)],
+        invoice_creation: { enabled: true },
+        ...taxOptions(true),
+        ...sharedSession(customer, params, product, plan, { pricingMode: CheckoutPricingMode.Quantity }),
+      })
+      if (session.url == null) throw new PaygateError('session')
+      return session.url
+    }
+
+    const plan = plans.find(item => item.sku === params.planSku)
+      ?? plans.find(item => item.recurring != null) ?? plans[0]
+    if (plan == null) throw new ProductError('plan')
+    const price = await findPrice(stripe, product.sku, planLookupKey(product, plan))
+    const session = await stripe.checkout.sessions.create({
+      mode: 'subscription', line_items: [{ price: price.id, quantity: 1 }],
+      subscription_data: {
+        metadata: {
+          pricingMode: CheckoutPricingMode.Quantity, entityId: params.entityId,
+          service: params.service, productSku: product.sku, planSku: plan.sku,
+        },
+      },
+      ...taxOptions(true),
+      ...sharedSession(customer, params, product, plan, {}),
+    })
+    if (session.url == null) throw new PaygateError('session')
+    return session.url
+  },
+
+  handleWebhook: async (request, ctx) => {
+    const config = await stripeConfig(ctx)
+    const stripe = await stripeClient(ctx)
+    const typed = request as {
+      original?: { rawBody?: string | Buffer }; rawBody?: string | Buffer
+      headers: Record<string, string | string[] | undefined>
+    }
+    const rawBody = typed.original?.rawBody ?? typed.rawBody
+    const signature = typed.headers[STRIPE_SIGNATURE.toLowerCase()]
+    if (rawBody == null || typeof signature !== 'string') throw new PaygateError('signature')
+    const event = await stripe.webhooks.constructEventAsync(rawBody, signature, config.webhook)
+    await createEventHandler(ctx, stripe).process(event)
+  },
+
+  manageSubscription: async (ctx, entityId, returnUrl) => {
+    const stripe = await stripeClient(ctx)
+    const customer = await paygateCustomers(ctx).byEntity(entityId, STRIPE_PAYGATE_ALIAS)
+    if (customer == null) throw new PaygateError('customer')
+    return (await stripe.billingPortal.sessions.create({ customer: customer.externalId, return_url: returnUrl })).url
+  },
+}

package/src/resource.ts

@@ -0,0 +1,51 @@
+import type { ResourceMaker } from '@owlmeans/resource'
+import { makeMongoResource } from '@owlmeans/mongo-resource'
+import { RES_PAYGATE_CUSTOMER, RES_PAYMENT_FINGERPRINT, RES_PAYMENT_SUBSCRIPTION } from './consts.js'
+import { FingerprintSchema, PaygateCustomerSchema, PaymentSubscriptionSchema } from './model.js'
+import type {
+  FingerprintRecord, FingerprintResource, PaygateCustomerRecord, PaygateCustomerResource,
+  PaymentSubscriptionRecord, PaymentSubscriptionResource,
+} from './types.js'
+
+export const makePaygateCustomerResource: ResourceMaker<PaygateCustomerRecord, PaygateCustomerResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<PaygateCustomerRecord, PaygateCustomerResource>(
+    RES_PAYGATE_CUSTOMER, dbAlias, serviceAlias,
+  )
+  resource.loadByPgId = async (externalId, paygate) => await resource.load({ externalId, paygate })
+  resource.byEntity = async (entityId, paygate) => await resource.load({ entityId, paygate })
+  resource.schema = PaygateCustomerSchema
+  resource.index('entity', { paygate: 1, entityId: 1 })
+  resource.index('profile', { paygate: 1, profileId: 1 })
+  resource.index('external', { paygate: 1, externalId: 1 }, { unique: true })
+  return resource
+}
+
+export const makeSubscriptionResource: ResourceMaker<PaymentSubscriptionRecord, PaymentSubscriptionResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<PaymentSubscriptionRecord, PaymentSubscriptionResource>(
+    RES_PAYMENT_SUBSCRIPTION, dbAlias, serviceAlias,
+  )
+  resource.byExternalId = async (externalId, paygate) => await resource.load({ externalId, paygate })
+  resource.schema = PaymentSubscriptionSchema
+  resource.index('entity', { entityId: 1 })
+  resource.index('entitySku', { entityId: 1, sku: 1 })
+  resource.index('external', { externalId: 1, paygate: 1 }, { unique: true })
+  resource.index('status', { status: 1 })
+  return resource
+}
+
+export const makeFingerprintResource: ResourceMaker<FingerprintRecord, FingerprintResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<FingerprintRecord, FingerprintResource>(
+    RES_PAYMENT_FINGERPRINT, dbAlias, serviceAlias,
+  )
+  resource.bySku = async sku => await resource.load({ sku })
+  resource.clear = async () => { await resource.purge({ sku: { $exists: true } }) }
+  resource.schema = FingerprintSchema
+  resource.index('sku', { sku: 1 }, { unique: true })
+  return resource
+}

package/src/service.ts

@@ -0,0 +1,35 @@
+import { createService } from '@owlmeans/context'
+import { DEFAULT_ALIAS as PAYMENT_SERVICE, ENTITLEMENT_GATE, appendPaymentService } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { GATEWAY_SERVICE, RES_PAYGATE_CUSTOMER, RES_PAYMENT_FINGERPRINT, RES_PAYMENT_SUBSCRIPTION } from './consts.js'
+import { makeEntitlementGate } from './gate.js'
+import { appendCompletionObserver } from './observer.js'
+import { stripePlugin } from './plugins/stripe.js'
+import { makeFingerprintResource, makePaygateCustomerResource, makeSubscriptionResource } from './resource.js'
+import { initialize } from './sync.js'
+import type { Config, Context, GatewayService, PaymentResourceOptions } from './types.js'
+
+export const makeGatewayService = (alias: string = GATEWAY_SERVICE): GatewayService => {
+  const service = createService<GatewayService>(alias, {
+    createLink: async (ctx, params) => stripePlugin.createLink(ctx, params),
+    manageSubscription: async (ctx, entityId, returnUrl) => stripePlugin.manageSubscription(ctx, entityId, returnUrl),
+  }, service => async () => {
+    service.initialized = true
+    const ctx = service.assertCtx() as ApiContext
+    ctx.waitForInitialized().then(() => initialize(ctx).catch(console.error))
+  })
+  return service
+}
+
+export const appendPaymentGatewayService = <C extends Config, T extends Context<C>>(
+  ctx: T, opts?: PaymentResourceOptions,
+): T => {
+  if (!ctx.hasResource(RES_PAYGATE_CUSTOMER)) ctx.registerResource(makePaygateCustomerResource(opts?.dbAlias, opts?.serviceAlias))
+  if (!ctx.hasResource(RES_PAYMENT_SUBSCRIPTION)) ctx.registerResource(makeSubscriptionResource(opts?.dbAlias, opts?.serviceAlias))
+  if (!ctx.hasResource(RES_PAYMENT_FINGERPRINT)) ctx.registerResource(makeFingerprintResource(opts?.dbAlias, opts?.serviceAlias))
+  if (!ctx.hasService(PAYMENT_SERVICE)) appendPaymentService(ctx as never)
+  appendCompletionObserver(ctx)
+  ctx.registerService(makeGatewayService())
+  if (!ctx.hasService(ENTITLEMENT_GATE)) ctx.registerService(makeEntitlementGate())
+  return ctx
+}

package/src/sync.ts

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto'
+import type Stripe from 'stripe'
+import { CheckoutPricingMode, ProductType } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_PAYGATE_ALIAS } from './consts.js'
+import { fingerprints, payment, stripeClient } from './utils.js'
+import type { PaymentPlan, PaymentProduct } from './types.js'
+
+export const planLookupKey = (product: PaymentProduct, plan: PaymentPlan): string =>
+  product.type === ProductType.Consumable ? `${product.sku}-consumable` : plan.sku
+
+const fingerprintOf = (product: PaymentProduct, plans: PaymentPlan[]): string => createHash('sha256')
+  .update(JSON.stringify({
+    sku: product.sku, type: product.type, name: product.title,
+    description: product.description ?? null, taxCode: product.taxCode ?? null,
+    unitLabel: product.unitLabel ?? null, services: [...(product.services ?? [])].sort(),
+    plans: plans.map(plan => ({
+      sku: plan.sku, price: plan.price, currency: plan.currency ?? 'usd', duration: plan.duration,
+      recurring: plan.recurring ?? null, pricingMode: plan.pricingMode ?? null,
+      amountPolicy: plan.amountPolicy ?? null, quantityPolicy: plan.quantityPolicy ?? null,
+      lookup: planLookupKey(product, plan),
+    })).sort((a, b) => a.sku.localeCompare(b.sku)),
+  })).digest('hex')
+
+const ensureStripeProduct = async (stripe: Stripe, product: PaymentProduct): Promise<Stripe.Product> => {
+  const params: Stripe.ProductCreateParams = {
+    name: product.title, description: product.description || undefined, tax_code: product.taxCode,
+    active: true,
+    metadata: { sku: product.sku, ...(product.services && { services: product.services.join(',') }) },
+  }
+  if (product.type === ProductType.Consumable && product.unitLabel != null) params.unit_label = product.unitLabel
+  try {
+    await stripe.products.retrieve(product.sku)
+    return await stripe.products.update(product.sku, params)
+  } catch {
+    return await stripe.products.create({ id: product.sku, ...params })
+  }
+}
+
+const activePrices = async (stripe: Stripe, product: PaymentProduct): Promise<Stripe.Price[]> =>
+  (await stripe.prices.list({ product: product.sku, active: true, limit: 100 })).data
+
+const deactivateAmountPrice = async (stripe: Stripe, product: PaymentProduct, plan: PaymentPlan): Promise<void> => {
+  const lookup = planLookupKey(product, plan)
+  for (const price of (await activePrices(stripe, product)).filter(item => item.lookup_key === lookup)) {
+    await stripe.prices.update(price.id, { active: false })
+  }
+}
+
+const ensureStripePrice = async (stripe: Stripe, product: PaymentProduct, plan: PaymentPlan): Promise<void> => {
+  if (plan.pricingMode === CheckoutPricingMode.Amount) {
+    await deactivateAmountPrice(stripe, product, plan)
+    return
+  }
+  const lookupKey = planLookupKey(product, plan)
+  const unitAmount = Math.round(plan.price * 100)
+  const currency = plan.currency ?? 'usd'
+  const recurring = plan.recurring != null
+    ? { interval: plan.recurring.interval } as Stripe.PriceCreateParams.Recurring : undefined
+  const existing = await activePrices(stripe, product)
+  const match = existing.find(price => price.lookup_key === lookupKey && price.unit_amount === unitAmount
+    && price.currency === currency
+    && ((price.recurring?.interval ?? null) === (recurring?.interval ?? null)))
+  if (match != null) return
+  for (const price of existing.filter(item => item.lookup_key === lookupKey)) {
+    await stripe.prices.update(price.id, { active: false })
+  }
+  await stripe.prices.create({
+    product: product.sku, currency, unit_amount: unitAmount, lookup_key: lookupKey,
+    transfer_lookup_key: true, nickname: plan.sku,
+    ...(recurring != null ? { recurring } : { billing_scheme: 'per_unit' }),
+    metadata: { sku: plan.sku, ...(product.services && { services: product.services.join(',') }) },
+  })
+}
+
+export const initialize = async (ctx: ApiContext): Promise<void> => {
+  const all = await payment(ctx).products() as PaymentProduct[]
+  const products = all.filter(product => (product.gateways ?? []).includes(STRIPE_PAYGATE_ALIAS))
+  if (products.length === 0) return
+  const stripe = await stripeClient(ctx)
+  const fpRes = fingerprints(ctx)
+  for (const product of products) {
+    const plans = await payment(ctx).allPlans(product.sku) as PaymentPlan[]
+    const hash = fingerprintOf(product, plans)
+    const stored = await fpRes.bySku(product.sku)
+    if (stored != null && stored.hash === hash) continue
+    const stripeProduct = await ensureStripeProduct(stripe, product)
+    for (const plan of plans) await ensureStripePrice(stripe, product, plan)
+    if (stored != null) {
+      Object.assign(stored, { hash, productId: stripeProduct.id, updatedAt: new Date() })
+      await fpRes.save(stored)
+    } else {
+      await fpRes.create({ sku: product.sku, hash, productId: stripeProduct.id, updatedAt: new Date() })
+    }
+    console.info(`[payment] synced product '${product.sku}' to Stripe (${plans.length} plan(s))`)
+  }
+}