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

package/src/consumer/withdrawal.ts

@@ -0,0 +1,302 @@
+import type Stripe from 'stripe'
+import {
+  consumerText, oneTimeWithdrawalRefund, PurchaseKind, subscriptionWithdrawalRefund,
+} from '@owlmeans/payment'
+import type { WithdrawalEstimate } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_OWNER_KEY, STRIPE_OWNER_VALUE, STRIPE_PAYGATE_ALIAS } from '../consts.js'
+import { findPlan } from '../plan.js'
+import { compact, errorText, isMissingObject, subscriptions } from '../utils.js'
+import { invoiceEvidenceOf } from './capture.js'
+import { formatDate } from './format.js'
+import { hasEvent, patchPurchase, purchaseRefOf, recordEvent } from './records.js'
+import type {
+  ConsumerDeclarationRecord, PaymentSubscriptionRecord, PurchaseRecord, UsageMeter, UsageReading,
+} from '../types.js'
+
+const DAY_MS = 86_400_000
+
+/** What a withdrawal of one purchase reimburses, as computed at one instant. */
+export interface WithdrawalComputation {
+  reading: UsageReading
+  /** Gross, tax included — what is refunded. */
+  refundMinor: number
+  /** Net of tax — the credit note's line amount. */
+  netMinor: number
+  estimate: WithdrawalEstimate
+  /** The units the deduction counts: used after consent, plus settled debt and earlier claw-backs. */
+  deducted: number
+  /** What the application takes back from the balance: the purchase's units still unused. */
+  unitsReturned: number
+}
+
+/**
+ * The refund of a withdrawal from one purchase, in the consumer's favour (`@owlmeans/payment`
+ * calculators). The meter's deduction is `usedAfter + settled + clawed`: units used after consent
+ * (before it the consumer bears no cost), units that paid an earlier overdraft, units already
+ * refunded by money. A subscription's `time` components count from its start request; without
+ * one nothing is deducted for time.
+ */
+export const computeWithdrawal = async (
+  ctx: ApiContext, meter: UsageMeter, purchase: PurchaseRecord, at: Date,
+): Promise<WithdrawalComputation> => {
+  const reading = await meter.used(ctx, compact({
+    entityId: purchase.entityId, purchase: purchaseRefOf(purchase),
+    after: purchase.consentedAt != null ? new Date(purchase.consentedAt) : undefined, at,
+  }))
+  const deducted = Math.max(0, reading.usedAfter) + Math.max(0, reading.settled ?? 0) + Math.max(0, reading.clawed ?? 0)
+  const unitsReturned = Math.max(0, Math.floor(reading.remaining
+    ?? reading.granted - reading.used - (reading.settled ?? 0) - (reading.clawed ?? 0)))
+  const paid = purchase.amountTotalMinor
+  const refunded = purchase.refundedMinor ?? 0
+  const net = purchase.amountSubtotalMinor
+  // The earlier refunds' net share, so the credit note never credits more than is left.
+  const refundedNet = paid > 0 ? Math.floor(refunded * net / paid) : 0
+
+  if (purchase.kind === PurchaseKind.TopUp) {
+    const gross = oneTimeWithdrawalRefund({ paidMinor: paid, refundedMinor: refunded, unitsGranted: reading.granted, unitsUsed: deducted })
+    const netRefund = oneTimeWithdrawalRefund({ paidMinor: net, refundedMinor: refundedNet, unitsGranted: reading.granted, unitsUsed: deducted })
+    const open = Math.max(0, paid - refunded)
+
+    return {
+      reading, deducted, unitsReturned,
+      refundMinor: gross.refundMinor,
+      netMinor: netRefund.refundMinor,
+      estimate: {
+        refundMinor: gross.refundMinor, currency: purchase.currency, timeDeductionMinor: 0,
+        unitsDeductionMinor: Math.max(0, open - gross.refundMinor),
+        unitsUsed: Math.min(deducted, reading.granted), unitsGranted: reading.granted,
+      },
+    }
+  }
+
+  const subscription = purchase.subscriptionId != null
+    ? await subscriptions(ctx).byExternalId(purchase.subscriptionId, STRIPE_PAYGATE_ALIAS) : null
+  const plan = purchase.planSku != null ? await findPlan(ctx, purchase.planSku) : null
+  const purchasedAt = new Date(purchase.purchasedAt)
+  const periodStart = subscription?.periodStart != null ? new Date(subscription.periodStart) : purchasedAt
+  const periodEnd = subscription?.periodEnd != null ? new Date(subscription.periodEnd)
+    : new Date(periodStart.getTime() + (plan?.recurring?.interval === 'year' ? 365 : 30) * DAY_MS)
+  const result = subscriptionWithdrawalRefund({
+    paidMinor: paid, refundedMinor: refunded, netMinor: net,
+    components: plan?.withdrawal?.components,
+    periodStart, periodEnd,
+    servicesRequestedAt: purchase.servicesStartedAt != null ? new Date(purchase.servicesStartedAt) : null,
+    withdrawnAt: at,
+    units: { granted: reading.granted, used: deducted },
+  })
+
+  return {
+    reading, deducted, unitsReturned,
+    refundMinor: result.refundMinor,
+    netMinor: result.refundNetMinor,
+    estimate: compact({
+      refundMinor: result.refundMinor, currency: purchase.currency, timeDeductionMinor: result.timeDeductionMinor,
+      unitsDeductionMinor: result.unitsDeductionMinor, elapsedDays: result.elapsedDays, periodDays: result.periodDays,
+      unitsUsed: result.unitsUsed, unitsGranted: result.unitsGranted,
+    }) as WithdrawalEstimate,
+  }
+}
+
+export interface WithdrawalExecution {
+  /** Every paygate step succeeded (or had nothing to do). */
+  ok: boolean
+  refundId?: string
+  creditNoteId?: string
+  refundedMinor: number
+  subscriptionCanceled: boolean
+  /** A step can never succeed without an operator (no payment to refund). */
+  needsReview: boolean
+}
+
+/** A Stripe error that says the subscription is already gone. */
+const alreadyCanceled = (error: unknown): boolean => isMissingObject(error)
+  || /canceled subscription|already (been )?cancel/i.test((error as { message?: string } | null)?.message ?? '')
+
+/** A refund this withdrawal already made (found by its metadata) — what a retry adopts. */
+const existingRefund = async (stripe: Stripe, paymentIntentId: string, withdrawalId: string): Promise<Stripe.Refund | null> => {
+  const { data } = await stripe.refunds.list({ payment_intent: paymentIntentId, limit: 100 })
+
+  return data.find(refund => refund.metadata?.withdrawalId === withdrawalId && refund.status !== 'failed'
+    && refund.status !== 'canceled') ?? null
+}
+
+/** A credit note this withdrawal already made — what a retry adopts. */
+const existingCreditNote = async (stripe: Stripe, invoiceId: string, withdrawalId: string): Promise<Stripe.CreditNote | null> => {
+  const { data } = await stripe.creditNotes.list({ invoice: invoiceId, limit: 100 })
+
+  return data.find(note => note.metadata?.withdrawalId === withdrawalId && note.status !== 'void') ?? null
+}
+
+/**
+ * Stripe replays the stored answer of an idempotency key — a failure too — for a day: a retry
+ * uses a fresh key (`…:<attempt>`) and first adopts what an earlier attempt may have made.
+ */
+const keyOf = (withdrawalId: string, step: string, attempt: number): Stripe.RequestOptions => ({
+  idempotencyKey: attempt > 0 ? `withdrawal:${withdrawalId}:${step}:${attempt}` : `withdrawal:${withdrawalId}:${step}`,
+})
+
+/**
+ * Execute a withdrawal at the paygate, the first attempt of every call under the idempotency key
+ * `withdrawal:<id>:<step>` (a retry by `reconcile` adopts what an earlier attempt made):
+ *
+ * 1. a subscription purchase: `subscriptions.cancel` at once, without proration or a final invoice;
+ * 2. an invoice-backed purchase: `creditNotes.preview` of the invoice line at the net refund, then
+ *    OUR `refunds.create` for the previewed total (metadata `withdrawalId` — the refund webhook then
+ *    tells observers not to claw back), then `creditNotes.create` linking that refund — the
+ *    corrective tax document; a failed credit note keeps the plain refund and is recorded;
+ * 3. no invoice: a plain proportional refund on the payment intent.
+ *
+ * Steps that already succeeded (a recorded `ok` event) are skipped. Every step is an event.
+ */
+export const executeWithdrawal = async (
+  ctx: ApiContext, stripe: Stripe, declaration: ConsumerDeclarationRecord, purchase: PurchaseRecord,
+  computation: { refundMinor: number, netMinor: number }, opts: { attempt?: number } = {},
+): Promise<WithdrawalExecution> => {
+  const withdrawalId = declaration.id as string
+  const attempt = opts.attempt ?? 0
+  const key = (step: string): Stripe.RequestOptions => keyOf(withdrawalId, step, attempt)
+  const event = (action: 'refund' | 'credit-note' | 'subscription-cancel', fields: Record<string, unknown>) =>
+    recordEvent(ctx, {
+      recordId: withdrawalId, recordKind: 'declaration', entityId: purchase.entityId, action, ok: false, ...fields,
+    } as Parameters<typeof recordEvent>[1])
+  const outcome: WithdrawalExecution = { ok: true, refundedMinor: 0, subscriptionCanceled: false, needsReview: false }
+
+  if (purchase.kind === PurchaseKind.Subscription && purchase.subscriptionId != null) {
+    if (await hasEvent(ctx, withdrawalId, 'subscription-cancel', undefined, true)) {
+      outcome.subscriptionCanceled = true
+    } else {
+      try {
+        await stripe.subscriptions.cancel(purchase.subscriptionId, {
+          prorate: false, invoice_now: false, cancellation_details: { comment: `withdrawal:${withdrawalId}` },
+        }, key('subscription-cancel'))
+        outcome.subscriptionCanceled = true
+        await event('subscription-cancel', { ok: true, externalId: purchase.subscriptionId })
+      } catch (error) {
+        if (alreadyCanceled(error)) {
+          outcome.subscriptionCanceled = true
+          await event('subscription-cancel', { ok: true, externalId: purchase.subscriptionId, detail: '{"already":true}' })
+        } else {
+          outcome.ok = false
+          await event('subscription-cancel', { externalId: purchase.subscriptionId, error: errorText(error) })
+        }
+      }
+      if (outcome.subscriptionCanceled) {
+        const row: PaymentSubscriptionRecord | null = await subscriptions(ctx).byExternalId(purchase.subscriptionId, STRIPE_PAYGATE_ALIAS)
+        if (row != null && row.withdrawnAt == null) {
+          await subscriptions(ctx).update({ ...row, withdrawnAt: new Date(declaration.receivedAt) })
+        }
+      }
+    }
+  }
+
+  if (await hasEvent(ctx, withdrawalId, 'refund', undefined, true)) {
+    return { ...outcome, refundedMinor: declaration.refundMinor ?? computation.refundMinor }
+  }
+  if (computation.refundMinor <= 0) {
+    return outcome
+  }
+
+  let paymentIntentId = purchase.paymentIntentId
+  let invoiceLineId = purchase.invoiceLineId
+  if (purchase.invoiceId != null && (paymentIntentId == null || invoiceLineId == null)) {
+    const invoice = await invoiceEvidenceOf(stripe, purchase.invoiceId)
+    paymentIntentId = paymentIntentId ?? invoice.paymentIntentId
+    invoiceLineId = invoiceLineId ?? invoice.invoiceLineId
+    await patchPurchase(ctx, purchase.purchaseId, compact({
+      paymentIntentId, invoiceLineId, invoiceNumber: purchase.invoiceNumber ?? invoice.invoiceNumber,
+    }))
+  }
+  if (paymentIntentId == null) {
+    await event('refund', { error: 'no-payment-intent', amountMinor: computation.refundMinor, currency: purchase.currency })
+    return { ...outcome, ok: false, needsReview: true }
+  }
+
+  const open = Math.max(0, purchase.amountTotalMinor - (purchase.refundedMinor ?? 0))
+  let amount = Math.min(open, computation.refundMinor)
+  let lines: Stripe.CreditNoteCreateParams.Line[] | null = null
+  if (purchase.invoiceId != null && invoiceLineId != null && computation.netMinor > 0) {
+    lines = [{ type: 'invoice_line_item', invoice_line_item: invoiceLineId, amount: computation.netMinor }]
+    try {
+      const preview = await stripe.creditNotes.preview({ invoice: purchase.invoiceId, lines })
+      amount = Math.min(open, preview.total)
+    } catch (error) {
+      lines = null
+      await event('credit-note', { step: 'preview', error: errorText(error) })
+    }
+  }
+  if (amount <= 0) {
+    return outcome
+  }
+
+  let refund: Stripe.Refund
+  try {
+    refund = (attempt > 0 ? await existingRefund(stripe, paymentIntentId, withdrawalId) : null)
+      ?? await stripe.refunds.create({
+        payment_intent: paymentIntentId, amount, reason: 'requested_by_customer',
+        metadata: { [STRIPE_OWNER_KEY]: STRIPE_OWNER_VALUE, withdrawalId, purchaseId: purchase.purchaseId },
+      }, key('refund'))
+  } catch (error) {
+    await event('refund', { error: errorText(error), amountMinor: amount, currency: purchase.currency })
+    return { ...outcome, ok: false }
+  }
+  await event('refund', { ok: true, externalId: refund.id, amountMinor: refund.amount, currency: refund.currency })
+  outcome.refundId = refund.id
+  outcome.refundedMinor = refund.amount
+
+  if (lines != null && purchase.invoiceId != null) {
+    try {
+      const note = await stripe.creditNotes.create({
+        invoice: purchase.invoiceId, lines, refund: refund.id,
+        memo: consumerText(declaration.language, 'credit-note.memo', {
+          contractRef: purchase.contractRef, date: formatDate(new Date(declaration.receivedAt), declaration.language),
+        }),
+        metadata: { withdrawalId, purchaseId: purchase.purchaseId },
+      }, key('credit-note'))
+      outcome.creditNoteId = note.id
+      await event('credit-note', { ok: true, externalId: note.id, amountMinor: note.total, currency: note.currency })
+    } catch (error) {
+      // The refund stands; the corrective document is retried by reconcile.
+      await event('credit-note', { error: errorText(error), detail: JSON.stringify({ refundId: refund.id }) })
+    }
+  }
+
+  return outcome
+}
+
+/** Retry a credit note that failed after its refund succeeded. */
+export const retryCreditNote = async (
+  ctx: ApiContext, stripe: Stripe, declaration: ConsumerDeclarationRecord, purchase: PurchaseRecord,
+  netMinor: number, refundId: string, attempt: number,
+): Promise<boolean> => {
+  const withdrawalId = declaration.id as string
+  let invoiceLineId = purchase.invoiceLineId
+  if (invoiceLineId == null && purchase.invoiceId != null) {
+    invoiceLineId = (await invoiceEvidenceOf(stripe, purchase.invoiceId)).invoiceLineId
+  }
+  if (purchase.invoiceId == null || invoiceLineId == null || netMinor <= 0) {
+    return false
+  }
+  try {
+    const note = await existingCreditNote(stripe, purchase.invoiceId, withdrawalId) ?? await stripe.creditNotes.create({
+      invoice: purchase.invoiceId,
+      lines: [{ type: 'invoice_line_item', invoice_line_item: invoiceLineId, amount: netMinor }],
+      refund: refundId,
+      memo: consumerText(declaration.language, 'credit-note.memo', {
+        contractRef: purchase.contractRef, date: formatDate(new Date(declaration.receivedAt), declaration.language),
+      }),
+      metadata: { withdrawalId, purchaseId: purchase.purchaseId },
+    }, keyOf(withdrawalId, 'credit-note', attempt))
+    await recordEvent(ctx, {
+      recordId: withdrawalId, recordKind: 'declaration', entityId: purchase.entityId, action: 'credit-note', ok: true,
+      externalId: note.id, amountMinor: note.total, currency: note.currency,
+    })
+    return true
+  } catch (error) {
+    await recordEvent(ctx, {
+      recordId: withdrawalId, recordKind: 'declaration', entityId: purchase.entityId, action: 'credit-note', ok: false,
+      error: errorText(error), detail: JSON.stringify({ refundId }),
+    })
+    return false
+  }
+}

package/src/entitlement.ts

@@ -0,0 +1,84 @@
+import { createService } from '@owlmeans/context'
+import {
+  capabilityOf, entitlementViewOf, INTERNAL_PAYGATE, SubscriptionStatus, windowKeyOf,
+} from '@owlmeans/payment'
+import type { EntitlementPlanView, EntitlementView, LimitUsage } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { ENTITLEMENT_SERVICE } from './consts.js'
+import { planRank, resolveEffectivePlan } from './plan.js'
+import {
+  consumeLimit, consumptionByRefOf, consumptionOf, limitStateOf, reconcileLedgerCounters, reconcileOccupancyOf, releaseLimit,
+} from './usage.js'
+import { compact, usageCounters } from './utils.js'
+import type { EffectivePlan, EntitlementService } from './types.js'
+
+const dateOrUndefined = (value: Date | null | undefined): Date | undefined =>
+  value == null ? undefined : new Date(value)
+
+/** The plan half of an entitlement view. `subscribedAt` is what a grandfathered promo is measured against. */
+export const planViewOf = (effective: EffectivePlan): EntitlementPlanView => {
+  const { plan, subscription, fallback } = effective
+  const status = subscription?.status ?? SubscriptionStatus.Active
+
+  return compact<EntitlementPlanView>({
+    sku: plan.sku,
+    productSku: plan.productSku,
+    title: plan.title,
+    rank: planRank(plan),
+    free: plan.free === true,
+    status,
+    paygate: subscription?.paygate ?? INTERNAL_PAYGATE,
+    subscriptionId: subscription?.externalId ?? undefined,
+    subscribedAt: dateOrUndefined(subscription?.createdAt),
+    periodStart: dateOrUndefined(subscription?.periodStart),
+    periodEnd: dateOrUndefined(subscription?.periodEnd),
+    cancelAtPeriodEnd: subscription?.cancelAtPeriodEnd ?? undefined,
+    trialEnd: dateOrUndefined(subscription?.trialEnd),
+    pausedAt: dateOrUndefined(subscription?.pausedAt),
+    pastDue: status === SubscriptionStatus.PastDue,
+    fallbackSku: plan.free !== true ? fallback?.sku : undefined,
+  })
+}
+
+/** What an entity may do now: its effective plan, every capability and every limit with its usage. */
+export const entitlementViewFor = async (ctx: ApiContext, entityId: string): Promise<EntitlementView> => {
+  const at = new Date()
+  const effective = await resolveEffectivePlan(ctx, entityId, at)
+  const declared = Object.entries(effective.plan.limits ?? {})
+  const windows = new Map(declared.map(([key, declaration]) => [
+    key, windowKeyOf(declaration.kind, declaration.window, at),
+  ]))
+  const usage: LimitUsage[] = []
+  if (declared.length > 0) {
+    const { items } = await usageCounters(ctx).list({
+      entityId, limitKey: [...windows.keys()], window: [...new Set(windows.values())],
+    }, { size: 0 })
+    for (const counter of items) {
+      if (windows.get(counter.limitKey) === counter.window) {
+        usage.push({ key: counter.limitKey, window: counter.window, used: counter.used })
+      }
+    }
+  }
+
+  return entitlementViewOf(effective.plan, planViewOf(effective), usage, at)
+}
+
+/** Plan resolution, the entitlement view and the usage ledger — Mongo only, never the paygate. */
+export const makeEntitlementService = (alias: string = ENTITLEMENT_SERVICE): EntitlementService => {
+  const service: EntitlementService = createService<EntitlementService>(alias, {
+    effectivePlan: async entityId => await resolveEffectivePlan(ctxOf(), entityId),
+    entitlements: async entityId => await entitlementViewFor(ctxOf(), entityId),
+    hasCapability: async (entityId, param) => capabilityOf(await entitlementViewFor(ctxOf(), entityId), param),
+    limitState: async (entityId, key) => await limitStateOf(ctxOf(), entityId, key),
+    consume: async req => await consumeLimit(ctxOf(), req),
+    release: async req => await releaseLimit(ctxOf(), req),
+    reconcileOccupancy: async (entityId, limitKey, actual) =>
+      await reconcileOccupancyOf(ctxOf(), entityId, limitKey, actual),
+    reconcileCounters: async entityId => await reconcileLedgerCounters(ctxOf(), entityId),
+    consumption: async (entityId, limitKey, eventKey) => await consumptionOf(ctxOf(), entityId, limitKey, eventKey),
+    consumptionByRef: async (entityId, limitKey, ref) => await consumptionByRefOf(ctxOf(), entityId, limitKey, ref),
+  })
+  const ctxOf = (): ApiContext => service.assertCtx() as unknown as ApiContext
+
+  return service
+}

package/src/entrypoints.ts

@@ -1,10 +1,11 @@
 import { bind } from '@owlmeans/server-entrypoint'
 import { paymentGate } from './consts.js'
-import { resync, webhook } from './actions/index.js'
+import { resync, resyncSubscriptions, webhook } from './actions/index.js'
 
 /** Runtime-local bindings for the shared immutable payment-gateway protocol tree. */
 export const paymentGateEntrypoints = [
   bind(paymentGate.base),
   bind(paymentGate.webhook, webhook),
   bind(paymentGate.resync, resync),
+  bind(paymentGate.resyncSubscriptions, resyncSubscriptions),
 ]

package/src/gate.ts

@@ -2,50 +2,117 @@ import { createLazyService } from '@owlmeans/context'
 import type { AbstractRequest, GateService } from '@owlmeans/entrypoint'
 import { AuthForbidden, entitySlugOf } from '@owlmeans/auth'
 import type { Auth, PermissionSet } from '@owlmeans/auth'
-import { ENTITLEMENT_GATE, hasEntitlement, SubscriptionStatus } from '@owlmeans/payment'
+import { hasPermission } from '@owlmeans/iam'
+import {
+  CapabilityRequired, ENTITLEMENT_GATE, parseEntitlementParam, promoActive,
+} from '@owlmeans/payment'
+import { capabilityOf } from '@owlmeans/payment'
 import type { Context as ApiContext } from '@owlmeans/server-api'
-import { subscriptions } from './utils.js'
+import { resolveEffectivePlan } from './plan.js'
+import { entitlements } from './utils.js'
 import type { Config, Context } from './types.js'
 
-export interface EntitlementGateOptions {
-  productSkus?: string[]
+export interface EntityResolverOption {
+  /** The stable organization id a request acts for. Default: `req.entity.id`, else the token's entity. */
   resolveEntity?: (req: AbstractRequest) => string | null
 }
 
+export interface CapabilityGateOptions extends EntityResolverOption {
+  /** Refuse unless the effective plan belongs to one of these products. */
+  productSkus?: string[]
+  /**
+   * Also require the token to grant the permission (IAM `hasPermission`). Off by default: a
+   * platform token carries no permissions, and the subscription is the authority.
+   */
+  requirePermission?: boolean
+}
+
+/** @deprecated use `CapabilityGateOptions` */
+export type EntitlementGateOptions = CapabilityGateOptions
+
+export const defaultEntity = (req: AbstractRequest): string | null =>
+  req.entity?.id ?? entitySlugOf(req.auth as Auth | undefined) ?? null
+
+/**
+ * The capability sets an entity's effective plan grants now — sets behind a lapsed promo left out.
+ * Empty when the plan is not of one of `productSkus`.
+ */
 export const entitlementsOf = async (
   ctx: ApiContext, entityId: string, productSkus?: string[],
 ): Promise<PermissionSet[]> => {
-  const { items } = await subscriptions(ctx).list({
-    entityId, status: [SubscriptionStatus.Active, SubscriptionStatus.Trial], productSku: productSkus,
-  }, { size: 0 })
-  return items.flatMap(record => record.capabilities ?? [])
+  const { plan, subscription } = await resolveEffectivePlan(ctx, entityId)
+  if (productSkus != null && !productSkus.includes(plan.productSku)) {
+    return []
+  }
+  const at = new Date()
+
+  return (plan.capabilities ?? [])
+    .filter(set => promoActive(set.promo, subscription?.createdAt, at))
+    .map(({ promo: _promo, ...set }) => set)
 }
 
-const defaultEntity = (req: AbstractRequest): string | null =>
-  req.entity?.id ?? entitySlugOf(req.auth as Auth | undefined) ?? null
+/** An explicit `false` for the permission in the token denies, whatever the plan grants. */
+const tokenDenies = (auth: Auth, param: string): boolean => {
+  const { scope, permission } = parseEntitlementParam(param)
+  return auth.permissions?.some(set =>
+    (scope == null || set.scope === scope) && set.permissions?.[permission] === false,
+  ) ?? false
+}
 
-export const makeEntitlementGate = (
-  alias: string = ENTITLEMENT_GATE, opts?: EntitlementGateOptions,
+const tokenGrants = (auth: Auth, param: string): boolean => {
+  const { scope, permission } = parseEntitlementParam(param)
+  return hasPermission(auth, permission, scope != null ? { scope } : undefined)
+}
+
+/** Resolve the authenticated entity a gate asserts for, or refuse. */
+export const gateEntityOf = (req: AbstractRequest, opts?: EntityResolverOption): { auth: Auth, entityId: string } => {
+  if (req.auth == null) {
+    throw new AuthForbidden('auth')
+  }
+  const entityId = (opts?.resolveEntity ?? defaultEntity)(req)
+  if (entityId == null || entityId === '') {
+    throw new AuthForbidden('entity')
+  }
+
+  return { auth: req.auth, entityId }
+}
+
+/**
+ * The capability gate (`ENTITLEMENT_GATE`): passes when the effective plan grants ANY of the
+ * parameters (`[scope:]permission[>=n]`) and the token does not deny it. Fails closed — an unreadable
+ * store refuses. Refuses with `CapabilityRequired`, an `AuthForbidden`.
+ */
+export const makeCapabilityGate = (
+  alias: string = ENTITLEMENT_GATE, opts?: CapabilityGateOptions,
 ): GateService => {
   const service = createLazyService<GateService>(alias, {
     assert: async (req, _, params) => {
       await service.ready()
       const ctx = service.assertCtx<Config, Context>() as unknown as ApiContext
-      if (req.auth == null) throw new AuthForbidden('auth')
-      const entityId = (opts?.resolveEntity ?? defaultEntity)(req)
-      if (entityId == null || entityId === '') throw new AuthForbidden('entity')
+      const { auth, entityId } = gateEntityOf(req, opts)
+      const list = (Array.isArray(params) ? params : [params]).filter(param => typeof param === 'string')
 
-      let capabilities: PermissionSet[]
+      let view
       try {
-        capabilities = await entitlementsOf(ctx, entityId, opts?.productSkus)
+        view = await entitlements(ctx).entitlements(entityId)
       } catch (error) {
-        console.error(`entitlement gate: cannot read subscriptions for "${entityId}"`, error)
-        throw new AuthForbidden('entitlement')
+        console.error(`capability gate: cannot resolve entitlements of "${entityId}"`, error)
+        throw new CapabilityRequired(list)
       }
-      if (!params.some(param => hasEntitlement(capabilities, param))) {
-        throw new AuthForbidden('entitlement')
+      if (opts?.productSkus != null && !opts.productSkus.includes(view.plan.productSku)) {
+        throw new CapabilityRequired(list)
+      }
+
+      const allowed = list.some(param => capabilityOf(view, param) && !tokenDenies(auth, param)
+        && (opts?.requirePermission !== true || tokenGrants(auth, param)))
+      if (!allowed) {
+        throw new CapabilityRequired(list)
       }
     },
   })
+
   return service
 }
+
+/** The capability gate under its historical name. */
+export const makeEntitlementGate = makeCapabilityGate

package/src/index.ts

@@ -5,9 +5,30 @@ export * from './resource.js'
 export * from './observer.js'
 export * from './service.js'
 export * from './gate.js'
+export * from './limit.js'
+export * from './entitlement.js'
+export * from './reconcile.js'
 export * from './entrypoints.js'
-export { initialize as syncPaymentProducts, planLookupKey } from './sync.js'
-export { amountCheckoutLineItem } from './plugins/stripe.js'
+export { findPlan, findProduct, freePlanOf, planRank, resolveEffectivePlan } from './plan.js'
+export { consumeLimit, consumptionByRefOf, consumptionOf, limitStateOf, reconcileLedgerCounters, reconcileOccupancyOf, releaseLimit } from './usage.js'
 export {
-  payment, gateway, observer, paygateCustomers, subscriptions, fingerprints, activeSubscription,
+  classifySubscriptionChange, commitSubscription, propagatedStateOf, subscriptionEventKey,
+} from './subscription.js'
+export type { CommitOptions, CommitResult } from './subscription.js'
+export { planLookupKey, syncedPlanPrices, syncPaymentProducts, syncStripeProducts } from './sync.js'
+export { amountCheckoutLineItem, quantityCheckoutLineItem } from './plugins/stripe.js'
+export { assertAmountAllowed, narrowAmountFor, sessionTtlOf } from './plugins/checkout-plugins.js'
+export * from './consumer/index.js'
+export { makeEstimateCache, estimateStripePrice } from './plugins/estimate.js'
+export type { EstimateCache } from './plugins/estimate.js'
+export { applySubscription, createEventHandler, mapStatus } from './plugins/events.js'
+export type { ApplyOptions } from './plugins/events.js'
+export {
+  ensureWebhookEndpoint, stripeWebhookSecret, stripeWebhookSecrets, webhookUrlOf,
+} from './plugins/webhook-manager.js'
+export { ensurePortalConfiguration } from './plugins/portal.js'
+export {
+  activeSubscription, apiVersionOf, billingProfiles, consumerConsents, consumerDeclarations, consumerEvents,
+  consumerRights, consumerRightsOf, entitlements, fingerprints, fulfillments, gateway, observer, paygateCustomers,
+  payment, paymentWebhooks, purchases, stripeClient, stripeConfig, subscriptions, usageCounters, usageEvents,
 } from './utils.js'

package/src/limit.ts

@@ -0,0 +1,57 @@
+import { createLazyService } from '@owlmeans/context'
+import type { GateService } from '@owlmeans/entrypoint'
+import { LIMIT_GATE, LimitExhausted, LimitUnknown, parseLimitParam } from '@owlmeans/payment'
+import type { LimitParam, LimitView } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { gateEntityOf } from './gate.js'
+import type { EntityResolverOption } from './gate.js'
+import { entitlements } from './utils.js'
+import type { Config, Context } from './types.js'
+
+export interface LimitGateOptions extends EntityResolverOption {}
+
+/**
+ * The limit gate (`LIMIT_GATE`): passes when ANY `limit:<key>[>=n]` parameter has at least `n` left
+ * in its current window. It never consumes — checking room and spending it are different moments,
+ * and only the handler knows the work started. Malformed parameters and keys the plan does not
+ * declare are skipped; a store error refuses. Refuses with `LimitExhausted` naming the first
+ * declared key, an `AuthForbidden`.
+ */
+export const makeLimitGate = (alias: string = LIMIT_GATE, opts?: LimitGateOptions): GateService => {
+  const service = createLazyService<GateService>(alias, {
+    assert: async (req, _, params) => {
+      await service.ready()
+      const ctx = service.assertCtx<Config, Context>() as unknown as ApiContext
+      const { entityId } = gateEntityOf(req, opts)
+      const list = (Array.isArray(params) ? params : [params]).filter(param => typeof param === 'string')
+
+      const parsed = list.map(parseLimitParam).filter((param): param is LimitParam => param != null)
+      if (parsed.length === 0) {
+        throw new LimitExhausted({ key: list[0] ?? 'unknown', used: 0, limit: 0 })
+      }
+
+      let refused: LimitView | null = null
+      for (const param of parsed) {
+        let state: LimitView
+        try {
+          state = await entitlements(ctx).limitState(entityId, param.key)
+        } catch (error) {
+          if (!(error instanceof LimitUnknown)) {
+            console.error(`limit gate: cannot read "${param.key}" of "${entityId}"`, error)
+          }
+          continue
+        }
+        if (state.remaining >= param.atLeast) {
+          return
+        }
+        refused ??= state
+      }
+
+      throw new LimitExhausted(refused != null
+        ? { key: refused.key, used: refused.used, limit: refused.limit, resetsAt: refused.resetsAt }
+        : { key: parsed[0].key, used: 0, limit: 0 })
+    },
+  })
+
+  return service
+}