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

package/src/service.ts

@@ -1,35 +1,191 @@
+import type Stripe from 'stripe'
 import { createService } from '@owlmeans/context'
-import { DEFAULT_ALIAS as PAYMENT_SERVICE, ENTITLEMENT_GATE, appendPaymentService } from '@owlmeans/payment'
+import {
+  appendPaymentService, DEFAULT_ALIAS as PAYMENT_SERVICE, ENTITLEMENT_GATE, INTERNAL_PAYGATE, LIMIT_GATE,
+  PaygateError, ProductError, SubscriptionStatus, UnknownPlan,
+} 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 { assertPlanDeclarations } from './config.js'
+import {
+  ENTITLEMENT_SERVICE, GATEWAY_SERVICE, RES_PAYGATE_CUSTOMER, RES_PAYMENT_FINGERPRINT, RES_PAYMENT_FULFILLMENT,
+  RES_PAYMENT_SUBSCRIPTION, RES_PAYMENT_USAGE, RES_PAYMENT_USAGE_COUNTER, RES_PAYMENT_WEBHOOK,
+} from './consts.js'
+import { registerConsumerRights } from './consumer/service.js'
+import { makeEntitlementService } from './entitlement.js'
+import { makeCapabilityGate } from './gate.js'
+import { makeLimitGate } from './limit.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'
+import { findPlan, findProduct, planRank } from './plan.js'
+import { resyncStripeSubscription, resyncStripeSubscriptions } from './plugins/events.js'
+import { makeEstimateCache, estimateStripePrice } from './plugins/estimate.js'
+import { createPortalLink, ensurePortalConfiguration } from './plugins/portal.js'
+import { makeCheckoutPluginRegistry, narrowAmountFor } from './plugins/checkout-plugins.js'
+import { consumablePlanOf, createCheckoutLink } from './plugins/stripe.js'
+import { ensureWebhookEndpoint } from './plugins/webhook-manager.js'
+import {
+  makeFingerprintResource, makeFulfillmentResource, makePaygateCustomerResource, makeSubscriptionResource,
+  makeUsageCounterResource, makeUsageResource, makeWebhookResource,
+} from './resource.js'
+import { commitSubscription } from './subscription.js'
+import { syncedPlanPrices, syncStripeProducts } from './sync.js'
+import { consumerRightsOf, stripeClient, subscriptions } from './utils.js'
+import type {
+  Config, Context, GatewayService, GrantInternalPlanOptions, PaymentGatewayOptions, PaymentPlan,
+  PaymentSubscriptionRecord,
+} from './types.js'
 
-export const makeGatewayService = (alias: string = GATEWAY_SERVICE): GatewayService => {
+export interface StripeBootstrapOptions {
+  /** Re-verify what the stored fingerprints say is in place. */
+  force?: boolean
+}
+
+/**
+ * Bring Stripe to what this deployment declares, each step on its own so one failing does not block
+ * the others: products and prices, the customer-portal configuration, the webhook endpoint.
+ */
+export const bootstrapStripe = async (
+  ctx: ApiContext, stripe: Stripe, opts: StripeBootstrapOptions = {},
+): Promise<void> => {
+  const steps: Array<[string, () => Promise<unknown>]> = [
+    ['products', async () => await syncStripeProducts(ctx, stripe)],
+    ['portal', async () => await ensurePortalConfiguration(ctx, stripe, opts)],
+    ['webhook', async () => await ensureWebhookEndpoint(ctx, stripe, opts)],
+  ]
+  for (const [name, step] of steps) {
+    try {
+      await step()
+    } catch (error) {
+      console.error(`[payment] Stripe ${name} bootstrap failed`, error)
+    }
+  }
+}
+
+/**
+ * Grant a plan without a paygate — the free plan every entity holds, or a complimentary one
+ * (`force`). One row per grant (`free:<entityId>` / `internal:<planSku>:<entityId>`), upserted: its
+ * `createdAt` survives a re-grant, and observers hear `created` once.
+ */
+export const grantInternalPlan = async (
+  ctx: ApiContext, entityId: string, planSku: string, opts: GrantInternalPlanOptions = {},
+): Promise<PaymentSubscriptionRecord> => {
+  const plan = await findPlan(ctx, planSku)
+  if (plan == null) {
+    throw new UnknownPlan(planSku)
+  }
+  if (plan.free !== true && opts.force !== true) {
+    throw new ProductError(`internal-grant:${planSku}`)
+  }
+  const product = await findProduct(ctx, plan.productSku)
+  const externalId = plan.free === true ? `free:${entityId}` : `internal:${planSku}:${entityId}`
+  const previous = await subscriptions(ctx).byExternalId(externalId, INTERNAL_PAYGATE)
+  const now = new Date()
+  const { periodEnd: _periodEnd, endedAt: _endedAt, canceledAt: _canceledAt, ...kept } = previous ?? {}
+
+  const next = {
+    ...kept,
+    entityId,
+    planSku,
+    productSku: plan.productSku,
+    service: previous?.service ?? product?.services?.[0] ?? ctx.cfg.service,
+    paygate: INTERNAL_PAYGATE,
+    externalId,
+    status: SubscriptionStatus.Active,
+    rank: planRank(plan),
+    ...(opts.periodEnd != null ? { periodEnd: opts.periodEnd } : {}),
+    createdAt: previous?.createdAt ?? now,
+    updatedAt: now,
+  } as PaymentSubscriptionRecord
+  const { record } = await commitSubscription(ctx, previous, next)
+
+  return record ?? next
+}
+
+const unmanaged = (): never => { throw new PaygateError('unmanaged') }
+
+export const makeGatewayService = (
+  alias: string = GATEWAY_SERVICE, opts: Pick<PaymentGatewayOptions, 'manage'> = {},
+): GatewayService => {
+  const managed = opts.manage !== false
+  // One estimate cache per gateway SERVICE instance, never module-level: several service
+  // instances (several tests, several deployments in one process) must never share hits.
+  const estimateCache = makeEstimateCache()
+  // Checkout plugins are seated per gateway instance, like the estimate cache.
+  const plugins = makeCheckoutPluginRegistry()
   const service = createService<GatewayService>(alias, {
-    createLink: async (ctx, params) => stripePlugin.createLink(ctx, params),
-    manageSubscription: async (ctx, entityId, returnUrl) => stripePlugin.manageSubscription(ctx, entityId, returnUrl),
+    managed,
+    createLink: async (ctx, params) => managed
+      ? await createCheckoutLink(ctx, await stripeClient(ctx), params, plugins.list()) : unmanaged(),
+    use: plugin => { plugins.use(plugin) },
+    checkoutPlugins: () => plugins.list(),
+    amountPolicy: async (ctx, entityId, productSku, planSku) => {
+      const { plan } = await consumablePlanOf(ctx, productSku, planSku)
+      if (plan.amountPolicy == null) throw new ProductError(`amount-policy:${plan.sku}`)
+      return await narrowAmountFor(ctx, plugins.list(), {
+        entityId, productSku, planSku: (plan as PaymentPlan).sku, base: plan.amountPolicy, at: new Date(),
+      })
+    },
+    planPrices: async (ctx, productSku) => await syncedPlanPrices(ctx, productSku),
+    portalLink: async (ctx, entityId, link) => managed
+      ? await createPortalLink(ctx, await stripeClient(ctx), entityId, link) : unmanaged(),
+    grantInternalPlan: async (ctx, entityId, planSku, grant) => await grantInternalPlan(ctx, entityId, planSku, grant),
+    resyncSubscription: async (ctx, ref) => managed
+      ? await resyncStripeSubscription(ctx, await stripeClient(ctx), ref) : unmanaged(),
+    resyncAll: async ctx => managed
+      ? await resyncStripeSubscriptions(ctx, await stripeClient(ctx)) : unmanaged(),
+    estimatePrice: async (ctx, params) => managed
+      ? await estimateStripePrice(ctx, await stripeClient(ctx), params, estimateCache) : unmanaged(),
   }, service => async () => {
+    const ctx = service.assertCtx() as unknown as ApiContext
+    assertPlanDeclarations(ctx.cfg)
     service.initialized = true
-    const ctx = service.assertCtx() as ApiContext
-    ctx.waitForInitialized().then(() => initialize(ctx).catch(console.error))
+    // The consumer-rights service is lazy (reachable while the application is wired): initialize it
+    // with the gateway, so its boot checks run at boot.
+    consumerRightsOf(ctx)
+    if (managed) {
+      void ctx.waitForInitialized().then(async () => {
+        await bootstrapStripe(ctx, await stripeClient(ctx))
+      }).catch(error => { console.error('[payment] Stripe bootstrap failed', error) })
+    }
   })
+
   return service
 }
 
+/**
+ * Register the payment resources, the catalogue service, the completion observer, the gateway, both
+ * gate services, the entitlement service and the consumer-rights records and service — each only
+ * when not registered yet.
+ *
+ * `manage: false` registers the same surface for a process that reads entitlements but never talks
+ * to Stripe.
+ */
 export const appendPaymentGatewayService = <C extends Config, T extends Context<C>>(
-  ctx: T, opts?: PaymentResourceOptions,
+  ctx: T, opts?: PaymentGatewayOptions,
 ): 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))
+  const makers = [
+    [RES_PAYGATE_CUSTOMER, makePaygateCustomerResource],
+    [RES_PAYMENT_SUBSCRIPTION, makeSubscriptionResource],
+    [RES_PAYMENT_FULFILLMENT, makeFulfillmentResource],
+    [RES_PAYMENT_WEBHOOK, makeWebhookResource],
+    [RES_PAYMENT_USAGE, makeUsageResource],
+    [RES_PAYMENT_USAGE_COUNTER, makeUsageCounterResource],
+    [RES_PAYMENT_FINGERPRINT, makeFingerprintResource],
+  ] as const
+  for (const [alias, maker] of makers) {
+    if (!ctx.hasResource(alias)) {
+      ctx.registerResource(maker(opts?.dbAlias, opts?.serviceAlias) as never)
+    }
+  }
   if (!ctx.hasService(PAYMENT_SERVICE)) appendPaymentService(ctx as never)
   appendCompletionObserver(ctx)
-  ctx.registerService(makeGatewayService())
-  if (!ctx.hasService(ENTITLEMENT_GATE)) ctx.registerService(makeEntitlementGate())
+  if (!ctx.hasService(GATEWAY_SERVICE)) ctx.registerService(makeGatewayService(GATEWAY_SERVICE, { manage: opts?.manage }))
+  if (!ctx.hasService(ENTITLEMENT_GATE)) ctx.registerService(makeCapabilityGate())
+  if (!ctx.hasService(LIMIT_GATE)) ctx.registerService(makeLimitGate())
+  if (!ctx.hasService(ENTITLEMENT_SERVICE)) ctx.registerService(makeEntitlementService())
+  // The consumer-rights records and service, with this gateway's `manage` unless the application
+  // gave its own (before or after this call): the webhook writes purchases and locks, and an
+  // unmanaged process still reads and asserts consent.
+  registerConsumerRights(ctx, { manage: opts?.manage, dbAlias: opts?.dbAlias, serviceAlias: opts?.serviceAlias }, 'gateway')
+
   return ctx
 }

package/src/subscription.ts

@@ -0,0 +1,231 @@
+import { ENTITLING_STATUSES, SubscriptionStatus } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { findPlan } from './plan.js'
+import { compact, isDuplicateKey, observer, subscriptions } from './utils.js'
+import type {
+  PaymentSubscriptionRecord, PropagatedState, SubscriptionChange, SubscriptionSnapshot,
+} from './types.js'
+
+export interface CommitOptions {
+  /** The paygate event being applied; a repeat of the last applied one is ignored. */
+  eventId?: string
+  /** A paid renewal invoice. */
+  renewal?: boolean
+  invoiceId?: string
+  /** The paygate announced the trial ends soon. */
+  trialEnding?: boolean
+  /**
+   * Runs after the new state is written and BEFORE observers hear the change — what must exist
+   * before an observer grants anything (a subscription's purchase row). A throw propagates: the
+   * observers are not told and the paygate retries.
+   */
+  beforePropagate?: (record: PaymentSubscriptionRecord, change: SubscriptionChange) => Promise<void>
+}
+
+export interface CommitResult {
+  record: PaymentSubscriptionRecord | null
+  change: SubscriptionChange | null
+  /** The stored subscription state changed. */
+  updated: boolean
+}
+
+const ENDED: readonly SubscriptionStatus[] = [SubscriptionStatus.Canceled, SubscriptionStatus.Ended]
+
+const timeOf = (value: Date | null | undefined): number | null => value == null ? null : new Date(value).getTime()
+
+/** The inputs classification compares. */
+export const propagatedStateOf = (record: PaymentSubscriptionRecord, renewedInvoiceId?: string): PropagatedState => compact({
+  planSku: record.planSku,
+  rank: record.rank,
+  status: record.status,
+  cancelAtPeriodEnd: record.cancelAtPeriodEnd === true,
+  pausedAt: record.pausedAt ?? undefined,
+  renewedInvoiceId: renewedInvoiceId ?? undefined,
+})
+
+/**
+ * What one subscription change means — the first rule that matches:
+ * `created` (first entitling state ever propagated), `canceled`, `paused`, `resumed`,
+ * `upgraded`/`downgraded` (plan change by rank; equal rank reads as an upgrade),
+ * `cancel-scheduled`, `cancel-undone`, `renewed` (once per invoice), `past-due`, `suspended`,
+ * `trial-ending`; otherwise nothing an observer is told about.
+ */
+export const classifySubscriptionChange = (
+  previous: PropagatedState | null, current: PaymentSubscriptionRecord, opts: CommitOptions = {},
+): SubscriptionChange | null => {
+  const active = ENTITLING_STATUSES.includes(current.status)
+  if (previous == null) {
+    return active ? 'created' : null
+  }
+  if (ENDED.includes(current.status) && !ENDED.includes(previous.status)) {
+    return 'canceled'
+  }
+  if (current.pausedAt != null && previous.pausedAt == null) {
+    return 'paused'
+  }
+  if ((current.pausedAt == null && previous.pausedAt != null)
+    || (previous.status === SubscriptionStatus.Suspended && active)) {
+    return 'resumed'
+  }
+  if (current.planSku !== previous.planSku) {
+    return current.rank < previous.rank ? 'downgraded' : 'upgraded'
+  }
+  if (previous.cancelAtPeriodEnd !== true && current.cancelAtPeriodEnd === true) {
+    return 'cancel-scheduled'
+  }
+  if (previous.cancelAtPeriodEnd === true && current.cancelAtPeriodEnd !== true) {
+    return 'cancel-undone'
+  }
+  if (opts.renewal === true && opts.invoiceId != null && opts.invoiceId !== previous.renewedInvoiceId) {
+    return 'renewed'
+  }
+  if (current.status === SubscriptionStatus.PastDue && previous.status !== SubscriptionStatus.PastDue) {
+    return 'past-due'
+  }
+  if (current.status === SubscriptionStatus.Suspended && previous.status !== SubscriptionStatus.Suspended) {
+    return 'suspended'
+  }
+  if (opts.trialEnding === true) {
+    return 'trial-ending'
+  }
+
+  return null
+}
+
+/** The idempotency key a consumer keys the side effect of a change by. */
+export const subscriptionEventKey = (
+  record: PaymentSubscriptionRecord, change: SubscriptionChange, opts: CommitOptions = {},
+): string => {
+  const base = `subscription:${record.externalId}:${change}`
+  switch (change) {
+    case 'created':
+      return `${base}:${new Date(record.createdAt).toISOString()}`
+    case 'renewed':
+      return `${base}:${opts.invoiceId ?? record.latestInvoiceId ?? 'unknown'}`
+    case 'upgraded':
+    case 'downgraded':
+      return `${base}:${record.planSku}`
+    case 'trial-ending':
+      return `${base}:${record.trialEnd != null ? new Date(record.trialEnd).toISOString() : 'unknown'}`
+    default:
+      return `${base}:${opts.eventId ?? `sync-${new Date(record.updatedAt ?? Date.now()).toISOString()}`}`
+  }
+}
+
+/** A subscription as observers see it; `state` overlays what was last propagated. */
+export const snapshotOf = async (
+  ctx: ApiContext, record: PaymentSubscriptionRecord, state?: PropagatedState,
+): Promise<SubscriptionSnapshot> => {
+  const planSku = state?.planSku ?? record.planSku
+  const plan = await findPlan(ctx, planSku)
+
+  return compact<SubscriptionSnapshot>({
+    entityId: record.entityId,
+    planSku,
+    productSku: plan?.productSku ?? record.productSku,
+    rank: state?.rank ?? record.rank,
+    status: state?.status ?? record.status,
+    paygate: record.paygate,
+    subscriptionId: record.externalId,
+    service: record.service,
+    periodStart: record.periodStart ?? undefined,
+    periodEnd: record.periodEnd ?? undefined,
+    cancelAtPeriodEnd: state != null ? state.cancelAtPeriodEnd : record.cancelAtPeriodEnd ?? undefined,
+    trialEnd: record.trialEnd ?? undefined,
+    pausedAt: state != null ? state.pausedAt : record.pausedAt ?? undefined,
+    createdAt: record.createdAt ?? undefined,
+    capabilities: plan?.capabilities,
+    limits: plan?.limits,
+  })
+}
+
+const MATERIAL: Array<keyof PaymentSubscriptionRecord> = [
+  'entityId', 'planSku', 'productSku', 'service', 'itemId', 'priceId', 'status', 'externalStatus', 'rank',
+  'periodStart', 'periodEnd', 'cancelAtPeriodEnd', 'canceledAt', 'endedAt', 'pausedAt', 'trialEnd',
+  'latestInvoiceId', 'customerId',
+]
+
+const sameValue = (left: unknown, right: unknown): boolean => {
+  if (left == null || right == null) {
+    return left == null && right == null
+  }
+  if (left instanceof Date || right instanceof Date) {
+    return timeOf(left as Date) === timeOf(right as Date)
+  }
+
+  return left === right
+}
+
+export const materiallyDiffers = (previous: PaymentSubscriptionRecord, next: PaymentSubscriptionRecord): boolean =>
+  MATERIAL.some(field => !sameValue(previous[field], next[field]))
+
+/**
+ * Store a subscription's new state, tell observers what changed, then record what was told.
+ *
+ * The state is written BEFORE observers run, so an observer reading entitlements sees the new plan.
+ * What classification compares against is the state last PROPAGATED (`propagated`), stamped only
+ * after every observer succeeded — so an observer that throws leaves the change to be classified
+ * again, identically, when the paygate retries. `lastEventId` is stamped with it.
+ */
+export const commitSubscription = async (
+  ctx: ApiContext, previous: PaymentSubscriptionRecord | null, next: PaymentSubscriptionRecord,
+  opts: CommitOptions = {},
+): Promise<CommitResult> => {
+  const resource = subscriptions(ctx)
+  const updated = previous == null || materiallyDiffers(previous, next)
+  const prior = previous?.propagated ?? null
+  const change = classifySubscriptionChange(prior, next, opts)
+  const at = new Date()
+
+  const finalize = (record: PaymentSubscriptionRecord): PaymentSubscriptionRecord => {
+    const tracked = prior != null || change === 'created'
+    return {
+      ...record,
+      ...(opts.eventId != null ? { lastEventId: opts.eventId } : {}),
+      ...(tracked ? {
+        propagated: propagatedStateOf(record, change === 'renewed' ? opts.invoiceId : prior?.renewedInvoiceId),
+      } : {}),
+      ...(change === 'created' && record.initialPropagatedAt == null ? { initialPropagatedAt: at } : {}),
+    }
+  }
+
+  const write = async (record: PaymentSubscriptionRecord): Promise<PaymentSubscriptionRecord> => {
+    if (record.id != null) {
+      return await resource.update(record)
+    }
+    try {
+      return await resource.create(record)
+    } catch (error) {
+      if (!isDuplicateKey(error)) {
+        throw error
+      }
+      const winner = await resource.byExternalId(record.externalId, record.paygate)
+      return await resource.update({ ...record, id: winner?.id })
+    }
+  }
+
+  if (change == null) {
+    const quiet = previous != null && !updated && (opts.eventId == null || previous.lastEventId === opts.eventId)
+      && (prior == null || !stateDiffers(prior, next))
+    return { record: quiet ? previous : await write(finalize(next)), change: null, updated }
+  }
+
+  const stored = await write(next)
+  await opts.beforePropagate?.(stored, change)
+  await observer(ctx).propagateSubscription({
+    change,
+    previous: prior != null && previous != null ? await snapshotOf(ctx, previous, prior) : null,
+    current: await snapshotOf(ctx, stored),
+    active: ENTITLING_STATUSES.includes(stored.status),
+    eventKey: subscriptionEventKey(stored, change, opts),
+    ...(opts.invoiceId != null ? { invoiceId: opts.invoiceId } : {}),
+    ...(opts.eventId != null ? { externalEventId: opts.eventId } : {}),
+  }, ctx)
+
+  return { record: await resource.update(finalize(stored)), change, updated }
+}
+
+const stateDiffers = (state: PropagatedState, record: PaymentSubscriptionRecord): boolean =>
+  state.planSku !== record.planSku || state.rank !== record.rank || state.status !== record.status
+  || (state.cancelAtPeriodEnd === true) !== (record.cancelAtPeriodEnd === true)
+  || timeOf(state.pausedAt) !== timeOf(record.pausedAt)