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

package/src/entitlement.ts

@@ -0,0 +1,125 @@
+import type { EntrypointOptions } from '@owlmeans/entrypoint'
+import type { PermissionSet } from '@owlmeans/auth'
+
+/**
+ * The gate alias a paid capability is asserted under.
+ *
+ * Distinct from `paymentGate.base` (a ROUTE id) and from the gateway service alias — three
+ * different things that would otherwise all be called "payment gate".
+ */
+export const ENTITLEMENT_GATE = 'entitlement-gate'
+
+/**
+ * The capability scope that carries FEATURE flags.
+ *
+ * Kept apart from `renewable`, which carries numeric quotas that are consumed or counted. Merging
+ * them would make "has one production slot left" and "may remove the platform credit" the same
+ * number, and the first purchase that spent the quota would take the feature with it.
+ */
+export const CAPABILITY_FEATURE_SCOPE = 'feature'
+
+export interface EntitlementParam {
+  /** Capability scope. Absent means any scope. */
+  scope?: string
+  /** The permission key inside `PermissionSet.permissions`. */
+  permission: string
+  /** Numeric floor: `credits>=100` passes when the held value is a number at least that big. */
+  atLeast?: number
+}
+
+/**
+ * Grammar: `[<scope>:]<permission>[>=<n>]`.
+ *
+ * `feature:branding--whitelabel` · `renewable:credits>=100` · `production--standalone`
+ *
+ * `@` is deliberately not part of it: that is `@owlmeans/iam`'s resource-selector syntax, and a
+ * grammar that reused it would make two different things look the same in a route declaration.
+ */
+export const parseEntitlementParam = (param: string): EntitlementParam => {
+  const [scoped, floor] = param.split('>=')
+  const colon = scoped.indexOf(':')
+  const parsed: EntitlementParam = colon >= 0
+    ? { scope: scoped.slice(0, colon), permission: scoped.slice(colon + 1) }
+    : { permission: scoped }
+
+  if (floor != null) {
+    const value = Number.parseFloat(floor)
+    if (!Number.isNaN(value)) {
+      parsed.atLeast = value
+    }
+  }
+
+  return parsed
+}
+
+export const formatEntitlementParam = (parsed: EntitlementParam): string =>
+  `${parsed.scope != null ? `${parsed.scope}:` : ''}${parsed.permission}` +
+  `${parsed.atLeast != null ? `>=${parsed.atLeast}` : ''}`
+
+/**
+ * Whether a union of capability sets satisfies one requirement.
+ *
+ * Pure, and shared by the server gate and the browser: the UI has to know whether to render a
+ * control disabled, and a second implementation of the rule for the client would eventually
+ * disagree with the one that actually refuses.
+ *
+ * A malformed parameter answers `false` rather than throwing. A gate that crashed on a typo would
+ * take down the endpoint it guards, which is a strictly worse failure than refusing it.
+ */
+export const hasEntitlement = (
+  capabilities: PermissionSet[] | undefined, param: string
+): boolean => {
+  if (capabilities == null || capabilities.length < 1) {
+    return false
+  }
+  const { scope, permission, atLeast } = parseEntitlementParam(param)
+  if (permission === '') {
+    return false
+  }
+
+  return capabilities.some(set => {
+    if (scope != null && set.scope !== scope) {
+      return false
+    }
+    const held = set.permissions?.[permission]
+    if (held == null || held === false) {
+      return false
+    }
+
+    // A floor is a numeric question: a boolean flag, however true, does not answer it.
+    return atLeast != null ? typeof held === 'number' && held >= atLeast : true
+  })
+}
+
+/** Everything a union grants, formatted back into parameters. The wire shape of a client read. */
+export const entitlementList = (capabilities: PermissionSet[] | undefined): string[] => {
+  const list: string[] = []
+  for (const set of capabilities ?? []) {
+    for (const [permission, value] of Object.entries(set.permissions ?? {})) {
+      if (value == null || value === false) {
+        continue
+      }
+      list.push(formatEntitlementParam({ scope: set.scope, permission }))
+    }
+  }
+
+  return [...new Set(list)]
+}
+
+/**
+ * Declare that an entrypoint needs a paid capability.
+ *
+ * Compatibility sugar over the protocol option
+ * `{ gate: { alias: ENTITLEMENT_GATE, params } }` so a route reads as what it means. Several
+ * parameters are OR'd, matching every other gate in the framework.
+ *
+ * Putting the requirement HERE rather than in a handler is the point: the framework asserts a gate
+ * before the handler is entered, so the route table states what a feature costs and no new
+ * endpoint can forget to check.
+ */
+export const entitled = (
+  params: string | string[], opts?: EntrypointOptions,
+): EntrypointOptions => ({
+  ...opts,
+  gate: { alias: ENTITLEMENT_GATE, params },
+})

package/src/entrypoints.ts

@@ -0,0 +1,57 @@
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import { route, backend, RouteMethod } from '@owlmeans/route'
+import { SubscriptionPropagateBodySchema } from './model/subscription.js'
+import { CreateCheckoutBodySchema, CreateCheckoutResponseSchema } from './model/checkout.js'
+
+const aliases = {
+  subscription: {
+    base: 'payment-api:subscription',
+    propagate: 'payment-api:subscription:propagate',
+  },
+  service: {
+    base: 'payment-service:base',
+    checkout: 'payment-service:checkout',
+    session: 'payment-service:checkout:session',
+    external: 'payment-service:checkout:session:external',
+    create: 'payment-service:checkout:session:external:create',
+  },
+} as const
+
+const subscriptionBase = protocol(route(aliases.subscription.base, '/subscription', backend()), contract())
+const serviceBase = protocol(route(aliases.service.base, '/payment-service', backend()), contract())
+const checkoutBase = protocol(
+  route(aliases.service.checkout, '/checkout', backend({ parent: serviceBase })), contract(),
+)
+const sessionBase = protocol(
+  route(aliases.service.session, '/session', backend({ parent: checkoutBase })), contract(),
+)
+const externalBase = protocol(
+  route(aliases.service.external, '/external', backend({ parent: sessionBase })), contract(),
+)
+
+/** Public payment protocols. Alias strings stay private to this declaration module. */
+export const paymentApi = {
+  subscription: {
+    base: subscriptionBase,
+    propagate: protocol(
+      route(aliases.subscription.propagate, '/propagate', backend({ parent: subscriptionBase, method: RouteMethod.POST })),
+      contract.request({ body: SubscriptionPropagateBodySchema }, typed<undefined>()),
+    ),
+  },
+  service: {
+    base: serviceBase,
+    checkout: {
+      base: checkoutBase,
+      session: {
+        base: sessionBase,
+        external: {
+          base: externalBase,
+          create: protocol(
+            route(aliases.service.create, '/create', backend({ parent: externalBase, method: RouteMethod.POST })),
+            contract.request({ body: CreateCheckoutBodySchema }, CreateCheckoutResponseSchema),
+          ),
+        },
+      },
+    },
+  },
+} as const

package/src/index.ts

@@ -3,7 +3,10 @@ export type * from './types.js'
 export * from './model/index.js'
 export * from './errors.js'
 export * from './consts.js'
+export * from './entitlement.js'
 export * from './service.js'
 export * from './i18n.js'
 export * from './helper.js'
-export * from './modules.js'
+export * from './entrypoints.js'
+export * from './advertise.js'
+export * from './pricing.js'

package/src/model/checkout.ts

@@ -1,27 +1,29 @@
 import type { JSONSchemaType } from 'ajv'
 import type { CreateCheckoutBody, CreateCheckoutResponse } from '../types.js'
 import { ResourceValueSchema, EntityValueSchema, IdValueSchema } from '@owlmeans/auth'
+import { schema } from '@owlmeans/entrypoint'
 
-export const CreateCheckoutBodySchema: JSONSchemaType<CreateCheckoutBody> = {
+export const CreateCheckoutBodySchema = schema<CreateCheckoutBody>({
   type: 'object',
   properties: {
     productSku: ResourceValueSchema,
     sku: { ...ResourceValueSchema, nullable: true },
-    entityId: EntityValueSchema,
+    entitySlug: EntityValueSchema,
     service: { ...ResourceValueSchema, minLength: 2 },
+    amountMinor: { type: 'number', minimum: 0, multipleOf: 1, nullable: true },
     subscriptionId: { ...IdValueSchema, nullable: true },
     successUrl: { ...ResourceValueSchema, minLength: 1, nullable: true },
     cancelUrl: { ...ResourceValueSchema, minLength: 1, nullable: true },
   },
-  required: ['productSku', 'entityId', 'service'],
+  required: ['productSku', 'entitySlug', 'service'],
   additionalProperties: false,
-}
+} as JSONSchemaType<CreateCheckoutBody>)
 
-export const CreateCheckoutResponseSchema: JSONSchemaType<CreateCheckoutResponse> = {
+export const CreateCheckoutResponseSchema = schema<CreateCheckoutResponse>({
   type: 'object',
   properties: {
     url: { type: 'string', minLength: 1 },
   },
   required: ['url'],
   additionalProperties: false,
-}
+} as JSONSchemaType<CreateCheckoutResponse>)

package/src/model/index.ts

@@ -5,3 +5,4 @@ export * from './subscription.js'
 export * from './plan.js'
 export * from './utils.js'
 export * from './checkout.js'
+export * from './pricing.js'

package/src/model/plan.ts

@@ -2,10 +2,11 @@ import type { JSONSchemaType } from 'ajv'
 import type { ProductPlan } from '../types.js'
 import { ResourceValueSchema, PermissionSetSchema, DateSchema } from '@owlmeans/auth'
 import {
-  PlanDurationSchema, ProductDescriptionSchema, ProductTitleSchema,
+  CheckoutPricingModeSchema, PlanDurationSchema, ProductDescriptionSchema, ProductTitleSchema,
   SubscriptionStatusSchema
 } from '../consts.js'
 import { LimitConfigSchema } from './utils.js'
+import { AmountCheckoutPolicySchema, QuantityCheckoutPolicySchema } from './pricing.js'
 
 export const ProductPlanSchema: JSONSchemaType<ProductPlan> = {
   type: 'object',
@@ -42,6 +43,9 @@ export const ProductPlanSchema: JSONSchemaType<ProductPlan> = {
       type: 'object', required: [], nullable: true,
       additionalProperties: LimitConfigSchema
     },
+    pricingMode: { ...CheckoutPricingModeSchema, nullable: true },
+    amountPolicy: { ...AmountCheckoutPolicySchema, nullable: true },
+    quantityPolicy: { ...QuantityCheckoutPolicySchema, nullable: true },
   },
   required: [
     'productSku', 'sku', 'status', 'duration',

package/src/model/pricing.ts

@@ -0,0 +1,34 @@
+import type { JSONSchemaType } from 'ajv'
+import { schema } from '@owlmeans/entrypoint'
+import type { AmountCheckoutPolicy, QuantityCheckoutPolicy } from '../types.js'
+
+export const AmountCheckoutPolicySchema = schema<AmountCheckoutPolicy>({
+  type: 'object',
+  properties: {
+    currency: { type: 'string', minLength: 3, maxLength: 3 },
+    minimumMinor: { type: 'number', minimum: 0, multipleOf: 1 },
+    maximumMinor: { type: 'number', minimum: 0, multipleOf: 1 },
+    defaultMinor: { type: 'number', minimum: 0, multipleOf: 1 },
+    presetsMinor: {
+      type: 'array', items: { type: 'number', minimum: 0, multipleOf: 1 }, uniqueItems: true,
+    },
+    fixedMinor: { type: 'number', minimum: 0, multipleOf: 1 },
+    rateBps: { type: 'number', minimum: 0, maximum: 9999, multipleOf: 1 },
+  },
+  required: [
+    'currency', 'minimumMinor', 'maximumMinor', 'defaultMinor', 'presetsMinor',
+    'fixedMinor', 'rateBps',
+  ],
+  additionalProperties: false,
+} as JSONSchemaType<AmountCheckoutPolicy>)
+
+export const QuantityCheckoutPolicySchema = schema<QuantityCheckoutPolicy>({
+  type: 'object',
+  properties: {
+    minimum: { type: 'number', minimum: 1, multipleOf: 1 },
+    maximum: { type: 'number', minimum: 1, multipleOf: 1 },
+    default: { type: 'number', minimum: 1, multipleOf: 1 },
+  },
+  required: ['minimum', 'maximum', 'default'],
+  additionalProperties: false,
+} as JSONSchemaType<QuantityCheckoutPolicy>)

package/src/model/subscription.ts

@@ -1,6 +1,7 @@
 import type { JSONSchemaType } from 'ajv'
 import type { PlanSubscription, SubscriptionPropagateBody } from '../types.js'
 import { ResourceValueSchema, PermissionSetSchema, DateSchema, EntityValueSchema, IdValueSchema } from '@owlmeans/auth'
+import { schema } from '@owlmeans/entrypoint'
 import { SubscriptionStatusSchema } from '../consts.js'
 import { CapabilityUsageSchema, LimitConfigSchema } from './utils.js'
 
@@ -37,27 +38,23 @@ export const PlanSubscriptionSchema: JSONSchemaType<PlanSubscription> = {
   additionalProperties: false,
 }
 
-export const SubscriptionPropagateBodySchema: JSONSchemaType<SubscriptionPropagateBody> = {
+const { entityId: _entityId, ...SubscriptionWireProperties } =
+  PlanSubscriptionSchema.properties as Record<string, unknown>
+const SubscriptionWireRequired = PlanSubscriptionSchema.required.filter(field => field !== 'entityId')
+
+export const SubscriptionPropagateBodySchema = schema<SubscriptionPropagateBody>({
   type: 'object',
   properties: {
-    ...PlanSubscriptionSchema.properties,
+    ...SubscriptionWireProperties,
+    entitySlug: EntityValueSchema,
     service: { ...ResourceValueSchema, minLength: 2 },
     externalId: IdValueSchema,
   } as any, // @TODO Figure out why it doesn't work (probably different version of ajv)
-  required: ['externalId', 'service', ...PlanSubscriptionSchema.required],
+  required: ['externalId', 'entitySlug', 'service', ...SubscriptionWireRequired],
   additionalProperties: false,
-}
+} as JSONSchemaType<SubscriptionPropagateBody>)
 
 /**
  * @deprecated Use SubscriptionPropogateBodySchema instead
  */
-export const SubscriptionPropogateBodySchema: JSONSchemaType<SubscriptionPropagateBody> = {
-  type: 'object',
-  properties: {
-    ...PlanSubscriptionSchema.properties,
-    service: { ...ResourceValueSchema, minLength: 2 },
-    externalId: IdValueSchema,
-  } as any, // @TODO Figure out why it doesn't work (probably different version of ajv)
-  required: ['externalId', 'service', ...PlanSubscriptionSchema.required],
-  additionalProperties: false,
-}
+export const SubscriptionPropogateBodySchema = SubscriptionPropagateBodySchema

package/src/pricing.ts

@@ -0,0 +1,87 @@
+import { PaymentError } from './errors.js'
+import type { AmountCheckoutPolicy, QuantityCheckoutPolicy } from './types.js'
+
+const integer = (value: number): boolean => Number.isSafeInteger(value)
+
+export const assertAmountCheckoutPolicy = (
+  policy: AmountCheckoutPolicy,
+): AmountCheckoutPolicy => {
+  if (
+    !integer(policy.minimumMinor)
+    || !integer(policy.maximumMinor)
+    || !integer(policy.defaultMinor)
+    || !integer(policy.fixedMinor)
+    || !integer(policy.rateBps)
+    || policy.minimumMinor < 0
+    || policy.minimumMinor > policy.defaultMinor
+    || policy.defaultMinor > policy.maximumMinor
+    || policy.fixedMinor < 0
+    || policy.rateBps < 0
+    || policy.rateBps >= 10_000
+    || policy.currency.trim().length !== 3
+  ) {
+    throw new PaymentError('checkout-policy:amount')
+  }
+
+  const presets = new Set(policy.presetsMinor)
+  if (
+    presets.size !== policy.presetsMinor.length
+    || policy.presetsMinor.some(value =>
+      !integer(value) || value < policy.minimumMinor || value > policy.maximumMinor
+    )
+  ) {
+    throw new PaymentError('checkout-policy:presets')
+  }
+
+  return policy
+}
+
+export const assertQuantityCheckoutPolicy = (
+  policy: QuantityCheckoutPolicy,
+): QuantityCheckoutPolicy => {
+  if (
+    !integer(policy.minimum)
+    || !integer(policy.maximum)
+    || !integer(policy.default)
+    || policy.minimum < 1
+    || policy.minimum > policy.default
+    || policy.default > policy.maximum
+  ) {
+    throw new PaymentError('checkout-policy:quantity')
+  }
+  return policy
+}
+
+export const assertCheckoutAmount = (
+  policy: AmountCheckoutPolicy, amountMinor: number,
+): number => {
+  assertAmountCheckoutPolicy(policy)
+  if (!integer(amountMinor)) {
+    throw new PaymentError('checkout-amount:integer')
+  }
+  if (amountMinor < policy.minimumMinor) {
+    throw new PaymentError('checkout-amount:minimum')
+  }
+  if (amountMinor > policy.maximumMinor) {
+    throw new PaymentError('checkout-amount:maximum')
+  }
+  return amountMinor
+}
+
+/** Gross up a net credit value so the configured adjustment remains outside the credit grant. */
+export const chargeAmountMinor = (
+  amountMinor: number, policy: Pick<AmountCheckoutPolicy, 'fixedMinor' | 'rateBps'>,
+): number => {
+  const adjusted = amountMinor + policy.fixedMinor
+  const numerator = adjusted * 10_000
+  if (
+    !integer(amountMinor) || !integer(policy.fixedMinor) || !integer(policy.rateBps)
+    || amountMinor < 0 || policy.fixedMinor < 0 || policy.rateBps < 0 || policy.rateBps >= 10_000
+    || !integer(adjusted) || !integer(numerator)
+  ) {
+    throw new PaymentError('checkout-charge')
+  }
+  const charge = Math.ceil(numerator / (10_000 - policy.rateBps))
+  if (!integer(charge)) throw new PaymentError('checkout-charge')
+  return charge
+}

package/src/types.ts

@@ -1,6 +1,8 @@
 import type { InitializedService } from '@owlmeans/context'
 
-import type { PaymentEntityType, PlanDuration, PlanStatus, ProductType, SubscriptionStatus } from './consts.js'
+import type {
+  CheckoutPricingMode, PaymentEntityType, PlanDuration, PlanStatus, ProductType, SubscriptionStatus
+} from './consts.js'
 import type { PermissionSet } from '@owlmeans/auth'
 
 export interface Product {
@@ -58,6 +60,25 @@ export interface ProductPlan {
   supsendedAt?: Date
   capabilities?: PermissionSet[]
   limits?: { [key: string]: LimitConfig }
+  pricingMode?: CheckoutPricingMode
+  amountPolicy?: AmountCheckoutPolicy
+  quantityPolicy?: QuantityCheckoutPolicy
+}
+
+export interface AmountCheckoutPolicy {
+  currency: string
+  minimumMinor: number
+  maximumMinor: number
+  defaultMinor: number
+  presetsMinor: number[]
+  fixedMinor: number
+  rateBps: number
+}
+
+export interface QuantityCheckoutPolicy {
+  minimum: number
+  maximum: number
+  default: number
 }
 
 export interface PlanSubscription {
@@ -91,8 +112,11 @@ export interface PlanSubscription {
 export interface CreateCheckoutBody {
   productSku: string
   sku?: string
-  entityId: string
+  /** Renameable organization value carried across a protocol boundary. */
+  entitySlug: string
   service: string
+  /** Net credit value for amount-priced checkouts, in integer currency minor units. */
+  amountMinor?: number
   subscriptionId?: string
   successUrl?: string
   cancelUrl?: string
@@ -102,7 +126,9 @@ export interface CreateCheckoutResponse {
   url: string
 }
 
-export interface SubscriptionPropagateBody extends PlanSubscription {
+export interface SubscriptionPropagateBody extends Omit<PlanSubscription, 'entityId' | 'externalId'> {
+  /** Renameable organization value carried across the propagation protocol. */
+  entitySlug: string
   service: string
   externalId: string
 }

package/tests/entitlement.spec.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from 'bun:test'
+import {
+  CAPABILITY_FEATURE_SCOPE, entitlementList, formatEntitlementParam, hasEntitlement,
+  parseEntitlementParam,
+} from '../src/entitlement.js'
+import type { PermissionSet } from '@owlmeans/auth'
+
+const pro: PermissionSet[] = [
+  { scope: 'renewable', permissions: { production: 1, credits: 5000 } },
+  { scope: CAPABILITY_FEATURE_SCOPE, permissions: { 'branding--whitelabel': true, 'domain--custom': true } },
+]
+
+describe('the parameter grammar', () => {
+  test('a bare permission has no scope and no floor', () => {
+    expect(parseEntitlementParam('domain--custom')).toEqual({ permission: 'domain--custom' })
+  })
+
+  test('a scope is everything before the first colon', () => {
+    expect(parseEntitlementParam('feature:branding--whitelabel'))
+      .toEqual({ scope: 'feature', permission: 'branding--whitelabel' })
+  })
+
+  test('a floor is parsed as a number', () => {
+    expect(parseEntitlementParam('renewable:credits>=100'))
+      .toEqual({ scope: 'renewable', permission: 'credits', atLeast: 100 })
+  })
+
+  test('formatting round-trips', () => {
+    for (const param of ['domain--custom', 'feature:branding--whitelabel', 'renewable:credits>=100']) {
+      expect(formatEntitlementParam(parseEntitlementParam(param))).toBe(param)
+    }
+  })
+})
+
+describe('the predicate', () => {
+  test('a held feature passes', () => {
+    expect(hasEntitlement(pro, 'feature:branding--whitelabel')).toBe(true)
+  })
+
+  test('a feature nobody granted does not', () => {
+    expect(hasEntitlement(pro, 'feature:branding--nonexistent')).toBe(false)
+  })
+
+  test('a scope that does not match is not consulted', () => {
+    expect(hasEntitlement(pro, 'renewable:branding--whitelabel')).toBe(false)
+    // …and without a scope, any set may answer.
+    expect(hasEntitlement(pro, 'branding--whitelabel')).toBe(true)
+  })
+
+  test('a numeric floor compares', () => {
+    expect(hasEntitlement(pro, 'renewable:credits>=5000')).toBe(true)
+    expect(hasEntitlement(pro, 'renewable:credits>=5001')).toBe(false)
+  })
+
+  test('a boolean cannot satisfy a numeric floor', () => {
+    expect(hasEntitlement(pro, 'feature:branding--whitelabel>=1')).toBe(false)
+  })
+
+  test('an explicit false is not a grant', () => {
+    expect(hasEntitlement([{ scope: 'feature', permissions: { x: false } }], 'feature:x')).toBe(false)
+    expect(hasEntitlement([{ scope: 'feature', permissions: { x: null } }], 'feature:x')).toBe(false)
+  })
+
+  test('no capabilities at all is a refusal, never a pass', () => {
+    expect(hasEntitlement(undefined, 'feature:branding--whitelabel')).toBe(false)
+    expect(hasEntitlement([], 'feature:branding--whitelabel')).toBe(false)
+  })
+
+  test('a malformed parameter refuses rather than throwing', () => {
+    // A gate that crashed on a typo would take down the endpoint it guards.
+    expect(() => hasEntitlement(pro, '')).not.toThrow()
+    expect(hasEntitlement(pro, '')).toBe(false)
+    expect(hasEntitlement(pro, 'feature:')).toBe(false)
+    expect(hasEntitlement(pro, 'renewable:credits>=abc')).toBe(true)
+  })
+})
+
+describe('listing', () => {
+  test('unions every granted capability, scoped', () => {
+    expect(entitlementList(pro).sort()).toEqual([
+      'feature:branding--whitelabel', 'feature:domain--custom',
+      'renewable:credits', 'renewable:production',
+    ])
+  })
+
+  test('skips what is not granted', () => {
+    expect(entitlementList([{ scope: 'feature', permissions: { a: true, b: false, c: null } }]))
+      .toEqual(['feature:a'])
+  })
+})

package/tests/pricing.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  assertAmountCheckoutPolicy, assertCheckoutAmount, chargeAmountMinor,
+  type AmountCheckoutPolicy,
+} from '../src/index.js'
+
+const policy: AmountCheckoutPolicy = {
+  currency: 'usd', minimumMinor: 500, maximumMinor: 50_000, defaultMinor: 1_000,
+  presetsMinor: [1_000, 2_000, 5_000, 10_000], fixedMinor: 0, rateBps: 200,
+}
+
+describe('amount checkout pricing', () => {
+  test('accepts exact boundaries and custom cents', () => {
+    expect(assertCheckoutAmount(policy, 500)).toBe(500)
+    expect(assertCheckoutAmount(policy, 501)).toBe(501)
+    expect(assertCheckoutAmount(policy, 50_000)).toBe(50_000)
+  })
+
+  test('rejects values outside the net-credit bounds', () => {
+    expect(() => assertCheckoutAmount(policy, 499)).toThrow()
+    expect(() => assertCheckoutAmount(policy, 50_001)).toThrow()
+  })
+
+  test('grosses ten dollars up to ten dollars and twenty-one cents', () => {
+    expect(chargeAmountMinor(1_000, policy)).toBe(1_021)
+  })
+
+  test('rejects invalid policy ordering, duplicate presets, and a 100% rate', () => {
+    expect(() => assertAmountCheckoutPolicy({ ...policy, defaultMinor: 100 })).toThrow()
+    expect(() => assertAmountCheckoutPolicy({ ...policy, presetsMinor: [1_000, 1_000] })).toThrow()
+    expect(() => assertAmountCheckoutPolicy({ ...policy, rateBps: 10_000 })).toThrow()
+  })
+})

package/tests/protocol.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import { protocols } from '@owlmeans/entrypoint'
+import type { RequestOf, ResponseOf } from '@owlmeans/entrypoint'
+import * as payment from '../src/index.js'
+import { paymentApi } from '../src/index.js'
+
+const checkout = paymentApi.service.checkout.session.external.create
+
+describe('payment checkout protocol', () => {
+  test('infers the organization slug and integer amount request', () => {
+    const request: RequestOf<typeof checkout> = {
+      body: { productSku: 'vib-credits', entitySlug: 'acme', service: 'app', amountMinor: 1_001 },
+    }
+    const response: ResponseOf<typeof checkout> = { url: 'https://checkout.stripe.test/session' }
+
+    expect(request.body.entitySlug).toBe('acme')
+    expect(request.body.amountMinor).toBe(1_001)
+    expect(response.url).toStartWith('https://')
+  })
+
+  test('exposes protocol declarations, never flattened string aliases', () => {
+    expect(Object.isFrozen(checkout)).toBe(true)
+    expect(protocols(paymentApi.service)).toContain(checkout)
+    expect(protocols(paymentApi.service).every(entry => entry.kind === 'entrypoint-protocol')).toBe(true)
+    expect(payment).not.toHaveProperty('serviceEntrypoints')
+    expect(payment).not.toHaveProperty('entrypoints')
+  })
+
+  test('rejects an internal entity id and fractional minor units on the wire', () => {
+    const ajv = new Ajv({ strict: false, validateFormats: false })
+    const validate = ajv.compile(checkout.contract!.requestSchemas.body!)
+
+    expect(validate({ productSku: 'vib-credits', entitySlug: 'acme', service: 'app', amountMinor: 500 })).toBe(true)
+    expect(validate({ productSku: 'vib-credits', entityId: 'internal', service: 'app', amountMinor: 500 })).toBe(false)
+    expect(validate({ productSku: 'vib-credits', entitySlug: 'acme', service: 'app', amountMinor: 500.5 })).toBe(false)
+  })
+
+  test('uses an organization slug on subscription propagation too', () => {
+    const ajv = new Ajv({ strict: false, validateFormats: false })
+    const validate = ajv.compile(paymentApi.subscription.propagate.contract!.requestSchemas.body!)
+    const body = {
+      sku: 'pro-plan', entitySlug: 'acme', service: 'app', externalId: 'sub_1',
+      createdAt: new Date(), startsdAt: new Date(), status: 'active',
+    }
+
+    expect(validate(body)).toBe(true)
+    expect(validate({ ...body, entitySlug: undefined, entityId: 'internal' })).toBe(false)
+    expect(paymentApi.subscription).not.toHaveProperty('propogate')
+  })
+})