@owlmeans/payment 0.1.18-rc.9 → 0.1.18

package/src/limit.ts

@@ -0,0 +1,132 @@
+import { LimitKind, LimitWindow, CAPABILITY_LIMIT_SCOPE, LIFETIME_WINDOW, OCCUPANCY_WINDOW, SUBSCRIPTION_WEEK_MS, SUBSCRIPTION_WEEK_PREFIX } from './consts.js'
+import { entitlementParamHelper } from './entitlement.js'
+import { LimitMisdeclared } from './errors.js'
+import type { EntitlementView, LimitView, LimitParam } from './types.js'
+import type { PermissionSet } from '@owlmeans/auth'
+import type { PlanLimitHelper } from './limit/types.js'
+
+const pad = (value: number): string => String(value).padStart(2, '0')
+
+export const createPlanLimitHelper = (): PlanLimitHelper => {
+  const windowKeyOf = (
+    kind: LimitKind, window?: LimitWindow | null, at: Date = new Date(), anchor?: Date,
+  ): string => {
+    switch (kind) {
+      case LimitKind.Lifetime:
+        return LIFETIME_WINDOW
+      case LimitKind.Occupancy:
+        return OCCUPANCY_WINDOW
+      case LimitKind.Window: {
+        const month = `${at.getUTCFullYear()}-${pad(at.getUTCMonth() + 1)}`
+        switch (window) {
+          case LimitWindow.SubscriptionWeek:
+            return `${SUBSCRIPTION_WEEK_PREFIX}${windowBoundsOf(window, at, anchor).start.toISOString()}`
+          case LimitWindow.Month:
+            return month
+          case LimitWindow.Day:
+            return `${month}-${pad(at.getUTCDate())}`
+        }
+        throw new LimitMisdeclared(`window:${window ?? 'missing'}`)
+      }
+    }
+    throw new LimitMisdeclared(`kind:${kind}`)
+  }
+
+  const windowBoundsOf = (
+    window: LimitWindow, at: Date = new Date(), anchor?: Date,
+  ): { start: Date, resetsAt: Date } => {
+    const year = at.getUTCFullYear()
+    const month = at.getUTCMonth()
+    switch (window) {
+      case LimitWindow.SubscriptionWeek: {
+        const origin = anchor?.getTime()
+        if (origin == null || !Number.isFinite(origin) || !Number.isFinite(at.getTime())) {
+          throw new LimitMisdeclared('subscription-week:anchor')
+        }
+        const start = new Date(origin + Math.floor((at.getTime() - origin) / SUBSCRIPTION_WEEK_MS) * SUBSCRIPTION_WEEK_MS)
+        return { start, resetsAt: new Date(start.getTime() + SUBSCRIPTION_WEEK_MS) }
+      }
+      case LimitWindow.Month:
+        return { start: new Date(Date.UTC(year, month, 1)), resetsAt: new Date(Date.UTC(year, month + 1, 1)) }
+      case LimitWindow.Day: {
+        const day = at.getUTCDate()
+        return {
+          start: new Date(Date.UTC(year, month, day)), resetsAt: new Date(Date.UTC(year, month, day + 1)),
+        }
+      }
+    }
+    throw new LimitMisdeclared(`window:${window}`)
+  }
+
+  const formatLimitParam = (key: string, atLeast?: number): string =>
+    entitlementParamHelper.formatEntitlementParam({ scope: CAPABILITY_LIMIT_SCOPE, permission: key, atLeast })
+
+  const parseLimitParam = (param: string): LimitParam | null => {
+    if (typeof param !== 'string') {
+      return null
+    }
+    const parsed = entitlementParamHelper.parseEntitlementParam(param)
+    if (parsed.scope !== CAPABILITY_LIMIT_SCOPE || parsed.permission === '') {
+      return null
+    }
+    const atLeast = parsed.atLeast ?? 1
+    if (!Number.isFinite(atLeast) || atLeast <= 0) {
+      return null
+    }
+
+    return { key: parsed.permission, atLeast }
+  }
+
+  const hasLimitRoom = (limit: LimitView | null | undefined, atLeast: number = 1): boolean =>
+    limit != null && limit.remaining >= atLeast
+
+  const limitOf = (
+    view: EntitlementView | null | undefined, key: string,
+  ): LimitView | null => view?.limits.find(limit => limit.key === key) ?? null
+
+  const capabilityOf = (view: EntitlementView | null | undefined, param: string): boolean => {
+    if (view == null) {
+      return false
+    }
+    // One set per row, so two grants of one permission are two chances — exactly as the declared
+    // sets they were built from.
+    const sets: PermissionSet[] = view.capabilities
+      .filter(capability => capability.granted)
+      .map(capability => ({
+        scope: capability.scope, permissions: { [capability.permission]: capability.value },
+      }))
+
+    return entitlementParamHelper.hasEntitlement(sets, param)
+  }
+
+  return { windowKeyOf, windowBoundsOf, formatLimitParam, parseLimitParam, hasLimitRoom, limitOf, capabilityOf }
+}
+
+export const planLimitHelper = createPlanLimitHelper()
+
+/** @deprecated compat:factory-refactor — use `planLimitHelper.windowKeyOf(…)` */
+export const windowKeyOf = (kind: LimitKind, window?: LimitWindow | null, at?: Date, anchor?: Date): string =>
+  planLimitHelper.windowKeyOf(kind, window, at, anchor)
+
+/** @deprecated compat:factory-refactor — use `planLimitHelper.windowBoundsOf(…)` */
+export const windowBoundsOf = (window: LimitWindow, at?: Date, anchor?: Date): { start: Date, resetsAt: Date } =>
+  planLimitHelper.windowBoundsOf(window, at, anchor)
+
+/** @deprecated compat:factory-refactor — use `planLimitHelper.formatLimitParam(…)` */
+export const formatLimitParam = (key: string, atLeast?: number): string =>
+  planLimitHelper.formatLimitParam(key, atLeast)
+
+/** @deprecated compat:factory-refactor — use `planLimitHelper.parseLimitParam(…)` */
+export const parseLimitParam = (param: string): LimitParam | null => planLimitHelper.parseLimitParam(param)
+
+/** @deprecated compat:factory-refactor — use `planLimitHelper.hasLimitRoom(…)` */
+export const hasLimitRoom = (limit: LimitView | null | undefined, atLeast?: number): boolean =>
+  planLimitHelper.hasLimitRoom(limit, atLeast)
+
+/** @deprecated compat:factory-refactor — use `planLimitHelper.limitOf(…)` */
+export const limitOf = (view: EntitlementView | null | undefined, key: string): LimitView | null =>
+  planLimitHelper.limitOf(view, key)
+
+/** @deprecated compat:factory-refactor — use `planLimitHelper.capabilityOf(…)` */
+export const capabilityOf = (view: EntitlementView | null | undefined, param: string): boolean =>
+  planLimitHelper.capabilityOf(view, param)

package/src/model/checkout.ts

@@ -1,27 +1,32 @@
 import type { JSONSchemaType } from 'ajv'
 import type { CreateCheckoutBody, CreateCheckoutResponse } from '../types.js'
 import { ResourceValueSchema, EntityValueSchema, IdValueSchema } from '@owlmeans/auth'
+import { schema } from '@owlmeans/entrypoint'
+import { CountrySchema } from '../consts.js'
 
-export const CreateCheckoutBodySchema: JSONSchemaType<CreateCheckoutBody> = {
+export const CreateCheckoutBodySchema = schema<CreateCheckoutBody>({
   type: 'object',
   properties: {
     productSku: ResourceValueSchema,
-    sku: { ...ResourceValueSchema, nullable: true },
-    entityId: EntityValueSchema,
+    planSku: { ...ResourceValueSchema, nullable: true },
+    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 },
+    country: { ...CountrySchema, nullable: true },
+    startRequestId: { ...IdValueSchema, 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/consts.local.ts

@@ -0,0 +1,83 @@
+import type { JSONSchemaType } from 'ajv'
+import { IdValueSchema } from '@owlmeans/auth'
+import type { TaxEstimate, TaxRateEstimate } from '../types.js'
+import { TaxEstimateStatusSchema, TaxTypeSchema, CountrySchema, ConsumerRegion, ConsumerRegionSchema } from '../consts.js'
+
+/**
+ * The consumer-rights schemas describe the WIRE: a date is an ISO string, exactly as in
+ * `model/view.ts` — a response serializer writes a `Date` through it as ISO. A browser revives the
+ * dates with the `revive*` helpers before touching one.
+ */
+export const IsoDateSchema = { type: 'string', format: 'date-time' } as unknown as JSONSchemaType<Date>
+
+export const MinorSchema: JSONSchemaType<number> = { type: 'number', minimum: 0, multipleOf: 1 }
+
+export const CurrencySchema: JSONSchemaType<string> = { type: 'string', minLength: 3, maxLength: 3 }
+
+export const VersionSchema: JSONSchemaType<string> = { type: 'string', minLength: 1, maxLength: 64 }
+
+export const KeySchema: JSONSchemaType<string> = { type: 'string', minLength: 1, maxLength: 128 }
+
+export const UrlSchema: JSONSchemaType<string> = { type: 'string', minLength: 1, maxLength: 2048 }
+
+export const LanguageSchema: JSONSchemaType<string> = {
+  type: 'string', minLength: 2, maxLength: 16, pattern: '^[a-z]{2,3}([-_][A-Za-z0-9]{2,8})?$',
+}
+
+export const NameSchema: JSONSchemaType<string> = { type: 'string', minLength: 1, maxLength: 200 }
+
+export const EmailSchema: JSONSchemaType<string> = {
+  type: 'string', minLength: 3, maxLength: 254, pattern: '^[^\\s@]+@[^\\s@]+$',
+}
+
+export const HoneypotSchema: JSONSchemaType<string> = { type: 'string', maxLength: 256 }
+
+/** A copy variant suffix: `performance-consent.request_<context>`, `subscription-start.request_units`. */
+export const ConsentContextSchema: JSONSchemaType<string> = {
+  type: 'string', minLength: 1, maxLength: 64, pattern: '^[a-z][a-z0-9-]*$',
+}
+
+export const AcknowledgedSchema = { type: 'boolean', const: true } as unknown as JSONSchemaType<true>
+
+export const ReceiptContentSchema = {
+  type: 'object', required: [], additionalProperties: { type: 'string', maxLength: 4096 },
+} as unknown as JSONSchemaType<Record<string, string>>
+
+export const declarationReceiptProperties = {
+  declarationId: IdValueSchema,
+  receivedAt: IsoDateSchema,
+  content: ReceiptContentSchema,
+  mailed: { type: 'boolean' },
+}
+
+export const TaxRateEstimateSchema: JSONSchemaType<TaxRateEstimate> = {
+  type: 'object',
+  properties: {
+    type: TaxTypeSchema,
+    percentage: { type: 'string', minLength: 1, maxLength: 16 },
+    ratePpm: { type: 'number', minimum: 0, multipleOf: 1 },
+    country: { ...CountrySchema, nullable: true },
+    state: { type: 'string', minLength: 1, maxLength: 8, nullable: true },
+  },
+  required: ['type', 'percentage', 'ratePpm'],
+  additionalProperties: false,
+}
+
+export const TaxEstimateSchema: JSONSchemaType<TaxEstimate> = {
+  type: 'object',
+  properties: {
+    status: TaxEstimateStatusSchema,
+    subtotalMinor: { type: 'number', minimum: 0, multipleOf: 1 },
+    taxMinor: { type: 'number', minimum: 0, multipleOf: 1 },
+    totalMinor: { type: 'number', minimum: 0, multipleOf: 1 },
+    scalable: { type: 'boolean' },
+    rates: { type: 'array', items: TaxRateEstimateSchema },
+  },
+  required: ['status', 'subtotalMinor', 'taxMinor', 'totalMinor', 'scalable', 'rates'],
+  additionalProperties: false,
+}
+
+/** A region that may be `null` on the wire — an enum admits `null` only when it lists it. */
+export const NullableRegionSchema = {
+  ...ConsumerRegionSchema, enum: [...ConsumerRegionSchema.enum, null], nullable: true,
+} as unknown as JSONSchemaType<ConsumerRegion | null>

package/src/model/consts.ts

@@ -0,0 +1,206 @@
+import type { JSONSchemaType } from 'ajv'
+import type { CheckoutLimitView, ConsumerRightsLinks, ConsumerRightsMechanisms, PlanPriceView, PlanWithdrawalComponent, PurchaseView, WithdrawalCandidate, WithdrawalEstimate, CapabilityView, EntitlementPlanView, LimitView, PromoView } from '../types.js'
+import { IdValueSchema } from '@owlmeans/auth'
+import { PurchaseKindSchema, TaxBehaviorSchema, LimitKindSchema, LimitWindowSchema, SubscriptionStatusSchema } from '../consts.js'
+import { CurrencySchema, IsoDateSchema, KeySchema, MinorSchema, UrlSchema } from './consts.local.js'
+
+export const ConsumerRightsLinksSchema: JSONSchemaType<ConsumerRightsLinks> = {
+  type: 'object',
+  properties: {
+    billingTerms: UrlSchema,
+    withdrawalInformation: { ...UrlSchema, nullable: true },
+    withdrawalForm: { ...UrlSchema, nullable: true },
+    withdrawalFunction: { ...UrlSchema, nullable: true },
+    cancellation: { ...UrlSchema, nullable: true },
+  },
+  required: ['billingTerms'],
+  additionalProperties: false,
+}
+
+export const ConsumerRightsMechanismsSchema: JSONSchemaType<ConsumerRightsMechanisms> = {
+  type: 'object',
+  properties: {
+    countryLock: { type: 'boolean' },
+    checkoutTerms: { type: 'boolean' },
+    performanceConsent: { type: 'boolean' },
+    subscriptionStart: { type: 'boolean' },
+    withdrawal: { type: 'boolean' },
+    automaticRefunds: { type: 'boolean' },
+    cancellation: { type: 'boolean' },
+    purchaseConfirmation: { type: 'boolean' },
+  },
+  required: [
+    'countryLock', 'checkoutTerms', 'performanceConsent', 'subscriptionStart', 'withdrawal', 'automaticRefunds',
+    'cancellation', 'purchaseConfirmation',
+  ],
+  additionalProperties: false,
+}
+
+export const PlanWithdrawalComponentSchema: JSONSchemaType<PlanWithdrawalComponent> = {
+  type: 'object',
+  properties: {
+    key: KeySchema,
+    basis: { type: 'string', enum: ['time', 'units'] },
+    shareMinor: MinorSchema,
+  },
+  required: ['key', 'basis', 'shareMinor'],
+  additionalProperties: false,
+}
+
+export const PurchaseViewSchema: JSONSchemaType<PurchaseView> = {
+  type: 'object',
+  properties: {
+    purchaseId: IdValueSchema,
+    contractRef: IdValueSchema,
+    kind: PurchaseKindSchema,
+    purchasedAt: IsoDateSchema,
+    deadline: { ...IsoDateSchema, nullable: true },
+    productSku: KeySchema,
+    planSku: { ...KeySchema, nullable: true },
+    amountTotalMinor: MinorSchema,
+    currency: CurrencySchema,
+    consentedAt: { ...IsoDateSchema, nullable: true },
+    withdrawnAt: { ...IsoDateSchema, nullable: true },
+    withdrawable: { type: 'boolean' },
+  },
+  required: [
+    'purchaseId', 'contractRef', 'kind', 'purchasedAt', 'productSku', 'amountTotalMinor', 'currency', 'withdrawable',
+  ],
+  additionalProperties: false,
+}
+
+export const WithdrawalEstimateSchema: JSONSchemaType<WithdrawalEstimate> = {
+  type: 'object',
+  properties: {
+    refundMinor: MinorSchema,
+    currency: CurrencySchema,
+    timeDeductionMinor: MinorSchema,
+    unitsDeductionMinor: MinorSchema,
+    elapsedDays: { ...MinorSchema, nullable: true },
+    periodDays: { ...MinorSchema, nullable: true },
+    unitsUsed: { type: 'number', minimum: 0, nullable: true },
+    unitsGranted: { type: 'number', minimum: 0, nullable: true },
+  },
+  required: ['refundMinor', 'currency', 'timeDeductionMinor', 'unitsDeductionMinor'],
+  additionalProperties: false,
+}
+
+export const WithdrawalCandidateSchema: JSONSchemaType<WithdrawalCandidate> = {
+  type: 'object',
+  properties: {
+    purchaseId: IdValueSchema,
+    contractRef: IdValueSchema,
+    kind: PurchaseKindSchema,
+    purchasedAt: IsoDateSchema,
+    deadline: IsoDateSchema,
+    amountTotalMinor: MinorSchema,
+    currency: CurrencySchema,
+    estimate: { ...WithdrawalEstimateSchema, nullable: true },
+    automatic: { type: 'boolean' },
+  },
+  required: [
+    'purchaseId', 'contractRef', 'kind', 'purchasedAt', 'deadline', 'amountTotalMinor', 'currency', 'estimate',
+    'automatic',
+  ],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<WithdrawalCandidate>
+
+export const CheckoutLimitViewSchema: JSONSchemaType<CheckoutLimitView> = {
+  type: 'object',
+  properties: {
+    productSku: { type: 'string', maxLength: 128 },
+    planSku: { ...KeySchema, nullable: true },
+    currency: CurrencySchema,
+    minimumMinor: MinorSchema,
+    maximumMinor: MinorSchema,
+    narrowed: { type: 'boolean' },
+    blocked: { type: 'boolean' },
+    reason: { ...KeySchema, nullable: true },
+    resetsAt: { ...IsoDateSchema, nullable: true },
+    remainingMinor: { ...MinorSchema, nullable: true },
+  },
+  required: ['productSku', 'currency', 'minimumMinor', 'maximumMinor', 'narrowed', 'blocked'],
+  additionalProperties: false,
+}
+
+export const PlanPriceViewSchema: JSONSchemaType<PlanPriceView> = {
+  type: 'object',
+  properties: {
+    planSku: KeySchema,
+    currency: CurrencySchema,
+    unitAmountMinor: MinorSchema,
+    default: { type: 'boolean' },
+    taxBehavior: { ...TaxBehaviorSchema, nullable: true },
+    interval: { type: 'string', enum: ['month', 'year'], nullable: true },
+  },
+  required: ['planSku', 'currency', 'unitAmountMinor', 'default'],
+  additionalProperties: false,
+} as JSONSchemaType<PlanPriceView>
+
+export const PromoViewSchema: JSONSchemaType<PromoView> = {
+  type: 'object',
+  properties: {
+    until: IsoDateSchema,
+    grandfathered: { type: 'boolean' },
+    active: { type: 'boolean' },
+  },
+  required: ['until', 'grandfathered', 'active'],
+  additionalProperties: false,
+}
+
+export const CapabilityViewSchema: JSONSchemaType<CapabilityView> = {
+  type: 'object',
+  properties: {
+    param: KeySchema,
+    scope: KeySchema,
+    permission: KeySchema,
+    value: { type: ['boolean', 'number'] },
+    granted: { type: 'boolean' },
+    promo: { ...PromoViewSchema, nullable: true },
+  },
+  required: ['param', 'scope', 'permission', 'value', 'granted'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<CapabilityView>
+
+export const LimitViewSchema: JSONSchemaType<LimitView> = {
+  type: 'object',
+  properties: {
+    key: KeySchema,
+    param: KeySchema,
+    kind: LimitKindSchema,
+    window: { ...LimitWindowSchema, nullable: true },
+    limit: { type: 'number' },
+    used: { type: 'number' },
+    remaining: { type: 'number' },
+    windowStart: { ...IsoDateSchema, nullable: true },
+    resetsAt: { ...IsoDateSchema, nullable: true },
+    unit: { type: 'string', nullable: true },
+    promo: { ...PromoViewSchema, nullable: true },
+  },
+  required: ['key', 'param', 'kind', 'limit', 'used', 'remaining'],
+  additionalProperties: false,
+} as JSONSchemaType<LimitView>
+
+export const EntitlementPlanViewSchema: JSONSchemaType<EntitlementPlanView> = {
+  type: 'object',
+  properties: {
+    sku: KeySchema,
+    productSku: KeySchema,
+    title: { type: 'string' },
+    rank: { type: 'number' },
+    free: { type: 'boolean' },
+    status: SubscriptionStatusSchema,
+    paygate: KeySchema,
+    subscriptionId: { type: 'string', nullable: true },
+    subscribedAt: { ...IsoDateSchema, nullable: true },
+    periodStart: { ...IsoDateSchema, nullable: true },
+    periodEnd: { ...IsoDateSchema, nullable: true },
+    cancelAtPeriodEnd: { type: 'boolean', nullable: true },
+    trialEnd: { ...IsoDateSchema, nullable: true },
+    pausedAt: { ...IsoDateSchema, nullable: true },
+    pastDue: { type: 'boolean', nullable: true },
+    fallbackSku: { type: 'string', nullable: true },
+  },
+  required: ['sku', 'productSku', 'title', 'rank', 'free', 'status', 'paygate'],
+  additionalProperties: false,
+} as JSONSchemaType<EntitlementPlanView>