@thejob/schema 2.1.8 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thejob/schema",
-  "version": "2.1.8",
+  "version": "2.2.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/billing/billing.constant.ts

@@ -0,0 +1,179 @@
+/**
+ * Billing vocabulary (Paddle).
+ *
+ * Two conventions in this module differ from the rest of the package, both
+ * deliberately and both load-bearing. Read them before editing:
+ *
+ * 1. **Paddle's wire values win.** `SubscriptionStatus` and `TransactionStatus`
+ *    mirror Paddle verbatim, underscores included (`past_due`). The house style
+ *    is lowercase-hyphen, but these values arrive in webhooks and are compared
+ *    as literals; normalising them would silently stop matching live events.
+ *    Never invent a member Paddle does not send.
+ *
+ * 2. **Money is in MINOR units.** Every other amount in this package (salary) is
+ *    a bare integer in the currency's MAJOR unit. Paddle is the opposite. See
+ *    `MoneySchema` in `billing.schema.ts`.
+ */
+
+// ─── Plans ───────────────────────────────────────────────────────────────────
+
+/** Whether buying this plan starts a recurring subscription or is a one-time purchase. */
+export enum PlanKind {
+  Subscription = "subscription",
+  OneOff = "one-off",
+}
+
+export const SupportedPlanKinds = Object.values(PlanKind);
+
+/** Whether a plan can currently be bought. Archived plans still grant to existing owners. */
+export enum PlanStatus {
+  Draft = "draft",
+  Active = "active",
+  Archived = "archived",
+}
+
+export const SupportedPlanStatuses = Object.values(PlanStatus);
+
+/**
+ * How a grant gives access to a feature.
+ *
+ * - `boolean` — plain on/off for as long as the plan is held.
+ * - `quota` — N uses per period, refreshed each period.
+ * - `credit` — N uses that do not expire, from a one-off purchase.
+ *
+ * Quota is spent before credit, so an included monthly allowance is used up
+ * before a purchased pack is touched.
+ */
+export enum GrantType {
+  Boolean = "boolean",
+  Quota = "quota",
+  Credit = "credit",
+}
+
+export const SupportedGrantTypes = Object.values(GrantType);
+
+/** The window a quota refreshes on, anchored to the subscription's billing date. */
+export enum QuotaPeriod {
+  Month = "month",
+  Year = "year",
+  /** Never refreshes: N uses for the lifetime of the subscription. */
+  Lifetime = "lifetime",
+}
+
+export const SupportedQuotaPeriods = Object.values(QuotaPeriod);
+
+/**
+ * How often a subscription plan BILLS.
+ *
+ * Deliberately NOT `QuotaPeriod`, though the two share `month` and `year`. They
+ * answer different questions: `QuotaPeriod` is how often a grant refreshes,
+ * this is how often the customer is charged, and a plan may bill yearly while
+ * refreshing its quota monthly (`employer-annual` does exactly that). Reusing
+ * `QuotaPeriod` here would also admit `lifetime`, which is not a billing
+ * interval for a subscription.
+ *
+ * Absent on one-off plans, which are not billed on an interval at all.
+ */
+export enum BillingPeriod {
+  Month = "month",
+  Year = "year",
+}
+
+export const SupportedBillingPeriods = Object.values(BillingPeriod);
+
+// ─── Paddle mirrors ──────────────────────────────────────────────────────────
+
+/**
+ * Paddle subscription status, verbatim.
+ *
+ * `active`, `trialing` and `past_due` all currently GRANT access: dunning is a
+ * payment problem, and cutting a paying customer off mid-retry is worse than
+ * carrying them for a few days. `paused` and `canceled` do not grant.
+ */
+export enum SubscriptionStatus {
+  Active = "active",
+  Trialing = "trialing",
+  PastDue = "past_due",
+  Paused = "paused",
+  Canceled = "canceled",
+}
+
+export const SupportedSubscriptionStatuses = Object.values(SubscriptionStatus);
+
+/** Subscription statuses that currently entitle the holder to their plan's grants. */
+export const EntitlingSubscriptionStatuses = [
+  SubscriptionStatus.Active,
+  SubscriptionStatus.Trialing,
+  SubscriptionStatus.PastDue,
+];
+
+/** Paddle transaction status, verbatim. `completed` is where a one-off is fulfilled. */
+export enum TransactionStatus {
+  Draft = "draft",
+  Ready = "ready",
+  Billed = "billed",
+  Paid = "paid",
+  Completed = "completed",
+  Canceled = "canceled",
+  PastDue = "past_due",
+}
+
+export const SupportedTransactionStatuses = Object.values(TransactionStatus);
+
+/** Which Paddle environment an identifier belongs to. Sandbox and live IDs never match. */
+export enum PaddleEnvironment {
+  Sandbox = "sandbox",
+  Production = "production",
+}
+
+export const SupportedPaddleEnvironments = Object.values(PaddleEnvironment);
+
+// ─── Features ────────────────────────────────────────────────────────────────
+
+/**
+ * Feature keys currently known to the platform.
+ *
+ * INFORMATIONAL ONLY — for autocomplete and for grepping who gates what.
+ *
+ * Do NOT constrain a stored field with `.oneOf(SupportedFeatureKeys)`. Feature
+ * keys are data owned by billing-service, and the entire point of the design is
+ * that putting a feature behind a paywall is a database change. Validating
+ * against this enum would make every new paywall a release of this package plus
+ * a redeploy of every service that holds it — exactly what the design avoids.
+ *
+ * Keys are dot-namespaced `<domain>.<capability>` and are permanent once sold:
+ * renaming one orphans the grants already stored against it.
+ */
+export enum FeatureKey {
+  JobPost = "job.post",
+  JobAlerts = "job.alerts",
+  PageCreate = "page.create",
+  GroupCreate = "group.create",
+  CandidateFinder = "candidate.finder",
+  SearchAdvanced = "search.advanced",
+  GetDiscovered = "get-discovered",
+}
+
+export const SupportedFeatureKeys = Object.values(FeatureKey);
+
+/** Why a gate refused, so the UI can tell "buy this" apart from "wait". */
+export enum EntitlementDenialReason {
+  /** No plan grants this feature at all. */
+  NotEntitled = "not-entitled",
+  /** Entitled, but the period's quota is spent. */
+  QuotaExhausted = "quota-exhausted",
+  /** Entitled, but the credit balance is zero. */
+  NoCredits = "no-credits",
+}
+
+export const SupportedEntitlementDenialReasons = Object.values(
+  EntitlementDenialReason,
+);
+
+// ─── Bounds ──────────────────────────────────────────────────────────────────
+
+/** A single grant cannot hand out more than this per period. Guards a typo'd plan. */
+export const GRANT_MAX_LIMIT = 100_000;
+
+/** Ceiling on units consumed in one call. A gate spends one unit in the normal case. */
+export const CONSUME_MAX_UNITS = 1_000;

package/src/billing/billing.schema.ts

@@ -0,0 +1,280 @@
+import { array, boolean, number, object, string } from "yup";
+import {
+  CONSUME_MAX_UNITS,
+  GRANT_MAX_LIMIT,
+  GrantType,
+  PlanKind,
+  PlanStatus,
+  QuotaPeriod,
+  SupportedBillingPeriods,
+  SupportedEntitlementDenialReasons,
+  SupportedGrantTypes,
+  SupportedPlanKinds,
+  SupportedPlanStatuses,
+  SupportedQuotaPeriods,
+  SupportedSubscriptionStatuses,
+  SupportedTransactionStatuses,
+} from "./billing.constant.js";
+
+// ─── Money ───────────────────────────────────────────────────────────────────
+
+/**
+ * An amount of money as Paddle expresses it.
+ *
+ * ⚠️ MINOR UNITS. `999` here is $9.99, not $999. This is the OPPOSITE of every
+ * other amount in this package: `salaryRange.min`, `minSalary` and friends are
+ * bare integers in the currency's MAJOR unit. Mixing the two is a 100x error in
+ * either direction, which is why the field is named `amountMinor` rather than
+ * `amount` — a bare `amount` next to a bare `currency` would read exactly like
+ * the salary fields and be wrong.
+ *
+ * Paddle transmits this as a STRING of minor units; billing-service parses it to
+ * a number on ingest and keeps the unit. Never render it without dividing by the
+ * currency's exponent.
+ */
+export const MoneySchema = object({
+  amountMinor: number()
+    .integer()
+    .min(0)
+    .required()
+    .label("Amount (minor units)"),
+  /**
+   * ISO-4217, as returned by Paddle. Deliberately NOT constrained to
+   * `SupportedSalaryCurrencies`: that list is the job-salary vocabulary, and
+   * Paddle bills in currencies it does not contain. Constraining it here would
+   * reject real payments.
+   */
+  currencyCode: string().trim().uppercase().required().label("Currency"),
+}).label("Money");
+
+// ─── Plans ───────────────────────────────────────────────────────────────────
+
+/**
+ * One thing a plan gives you.
+ *
+ * `limit` applies to quota grants, `amount` to credit grants, and neither to
+ * boolean. They are optional at the schema level and enforced by `.when`, so a
+ * malformed plan is caught when an operator saves it rather than when a user's
+ * entitlements silently resolve to nothing.
+ */
+export const PlanGrantSchema = object({
+  /**
+   * The gated capability, e.g. `job.post`. A free string on purpose: see the
+   * note on `FeatureKey` in `billing.constant.ts`. Adding a feature to the
+   * paywall must not require releasing this package.
+   */
+  feature: string().trim().required().min(1).max(64).label("Feature"),
+  type: string()
+    .oneOf(SupportedGrantTypes)
+    .required()
+    .default(GrantType.Boolean)
+    .label("Grant Type"),
+  /** Uses per period. Required for `quota`, meaningless otherwise. */
+  limit: number()
+    .integer()
+    .min(1)
+    .max(GRANT_MAX_LIMIT)
+    .optional()
+    .label("Limit")
+    .when("type", {
+      is: GrantType.Quota,
+      then: (s) => s.required("A quota grant needs a limit"),
+    }),
+  period: string()
+    .oneOf(SupportedQuotaPeriods)
+    .optional()
+    .default(QuotaPeriod.Month)
+    .label("Period")
+    .when("type", {
+      is: GrantType.Quota,
+      then: (s) => s.required("A quota grant needs a period"),
+    }),
+  /** Non-expiring uses granted per purchase. Required for `credit`. */
+  amount: number()
+    .integer()
+    .min(1)
+    .max(GRANT_MAX_LIMIT)
+    .optional()
+    .label("Amount")
+    .when("type", {
+      is: GrantType.Credit,
+      then: (s) => s.required("A credit grant needs an amount"),
+    }),
+}).label("Plan Grant");
+
+/**
+ * Paddle price identifiers, split by environment.
+ *
+ * Keyed rather than flat because sandbox and live price IDs are different
+ * strings for the same product. Shipping sandbox IDs to production does not fail
+ * at checkout — it fails later, when a webhook arrives carrying a price nothing
+ * maps to, and reads as "plan not found" rather than "wrong environment".
+ */
+export const PaddlePriceIdsSchema = object({
+  sandbox: array().of(string().required()).optional().default([]).label("Sandbox Price IDs"),
+  live: array().of(string().required()).optional().default([]).label("Live Price IDs"),
+}).label("Paddle Price IDs");
+
+/**
+ * What can be bought, and what it grants.
+ *
+ * This document is the paywall. Putting a feature behind it, taking one out, or
+ * changing a quota is an edit here plus a cache bust — no service redeploys.
+ */
+export const PlanSchema = object({
+  /** Stable slug, e.g. `employer-pro`. The identifier everything else references. */
+  key: string()
+    .trim()
+    .lowercase()
+    .required()
+    .min(2)
+    .max(64)
+    .label("Key"),
+  name: string().required().min(1).max(120).label("Name"),
+  description: string().optional().max(500).label("Description"),
+  kind: string()
+    .oneOf(SupportedPlanKinds)
+    .required()
+    .default(PlanKind.Subscription)
+    .label("Kind"),
+  status: string()
+    .oneOf(SupportedPlanStatuses)
+    .required()
+    .default(PlanStatus.Draft)
+    .label("Status"),
+  paddlePriceIds: PaddlePriceIdsSchema.default(() =>
+    PaddlePriceIdsSchema.getDefault(),
+  ),
+  grants: array()
+    .of(PlanGrantSchema.required())
+    .required()
+    .min(1, "A plan must grant at least one feature")
+    .label("Grants"),
+  /** Display price for the pricing page. Billing is always Paddle's own figure. */
+  price: MoneySchema.optional().default(undefined).label("Price"),
+  /**
+   * How often this plan bills, for the pricing page's monthly/yearly toggle and
+   * for rendering `price` with the right suffix.
+   *
+   * Display only: Paddle owns the real billing interval, and this never drives a
+   * charge. It is optional because one-off plans have no interval, and because
+   * plans seeded before this field existed must keep validating. Treat absent on
+   * a subscription as "monthly" at the use site rather than defaulting it here,
+   * so an unset value stays visible as unset.
+   */
+  billingPeriod: string()
+    .oneOf(SupportedBillingPeriods)
+    .optional()
+    .label("Billing Period"),
+  /** Ordering on the pricing page, ascending. */
+  sortOrder: number().integer().optional().default(0).label("Sort Order"),
+  createdAt: number().optional().label("Created At"),
+  updatedAt: number().optional().label("Updated At"),
+}).label("Plan");
+
+// ─── Subscriptions and transactions ──────────────────────────────────────────
+
+/**
+ * A user's Paddle subscription, mirrored locally.
+ *
+ * Paddle is the source of truth; this is a cache kept current by webhooks and
+ * repaired by the reconciler. `lastEventAt` is what makes that safe: Paddle
+ * guarantees no ordering, so every write is conditional on this advancing, and a
+ * late `subscription.updated` cannot resurrect a canceled subscription.
+ */
+export const BillingSubscriptionSchema = object({
+  userId: string().required().label("User ID"),
+  paddleSubscriptionId: string().required().label("Paddle Subscription ID"),
+  paddleCustomerId: string().required().label("Paddle Customer ID"),
+  planKey: string().required().label("Plan Key"),
+  priceIds: array().of(string().required()).required().label("Price IDs"),
+  status: string()
+    .oneOf(SupportedSubscriptionStatuses)
+    .required()
+    .label("Status"),
+  /** Start of the period the quota is anchored to. */
+  currentPeriodStart: number().optional().label("Current Period Start"),
+  currentPeriodEnd: number().optional().label("Current Period End"),
+  /** Set when a cancellation is scheduled; access continues until the period ends. */
+  canceledAt: number().optional().label("Canceled At"),
+  /** `occurred_at` of the newest Paddle event applied. Guards out-of-order writes. */
+  lastEventAt: number().required().default(0).label("Last Event At"),
+  createdAt: number().optional().label("Created At"),
+  updatedAt: number().optional().label("Updated At"),
+}).label("Billing Subscription");
+
+/** A completed Paddle payment. One-off purchases are fulfilled from these. */
+export const BillingTransactionSchema = object({
+  userId: string().required().label("User ID"),
+  paddleTransactionId: string().required().label("Paddle Transaction ID"),
+  paddleCustomerId: string().optional().label("Paddle Customer ID"),
+  paddleSubscriptionId: string().optional().label("Paddle Subscription ID"),
+  planKey: string().optional().label("Plan Key"),
+  priceIds: array().of(string().required()).required().label("Price IDs"),
+  status: string()
+    .oneOf(SupportedTransactionStatuses)
+    .required()
+    .label("Status"),
+  total: MoneySchema.optional().default(undefined).label("Total"),
+  billedAt: number().optional().label("Billed At"),
+  lastEventAt: number().required().default(0).label("Last Event At"),
+  createdAt: number().optional().label("Created At"),
+  updatedAt: number().optional().label("Updated At"),
+}).label("Billing Transaction");
+
+// ─── Entitlements ────────────────────────────────────────────────────────────
+
+/**
+ * The resolved state of one feature for one user.
+ *
+ * Both halves of the answer travel together: `allowed` is what a gate checks,
+ * and the counts are what the UI and the 402 body need. Only `allowed` becomes a
+ * CASL rule — see `defineEntitlementRules` in `@thejob/permission` for why counts
+ * cannot.
+ */
+export const FeatureEntitlementSchema = object({
+  feature: string().required().label("Feature"),
+  type: string().oneOf(SupportedGrantTypes).required().label("Grant Type"),
+  /** Whether the feature may be used AT ALL right now. */
+  allowed: boolean().required().default(false).label("Allowed"),
+  /** Quota ceiling for the period. Absent for boolean grants. */
+  limit: number().integer().optional().label("Limit"),
+  used: number().integer().optional().label("Used"),
+  /** Quota remaining plus any credit balance. Absent for boolean grants. */
+  remaining: number().integer().optional().label("Remaining"),
+  /** Non-expiring balance from one-off purchases. */
+  credits: number().integer().optional().label("Credits"),
+  /** When the quota next refreshes. */
+  resetsAt: number().optional().label("Resets At"),
+}).label("Feature Entitlement");
+
+/** Why a gate refused, with the numbers behind it. The body of a 402. */
+export const EntitlementDenialSchema = object({
+  feature: string().required().label("Feature"),
+  reason: string()
+    .oneOf(SupportedEntitlementDenialReasons)
+    .required()
+    .label("Reason"),
+  limit: number().integer().optional().label("Limit"),
+  used: number().integer().optional().label("Used"),
+  resetsAt: number().optional().label("Resets At"),
+  upgradeUrl: string().optional().label("Upgrade URL"),
+}).label("Entitlement Denial");
+
+/** What a service asks for when spending a unit of a metered feature. */
+export const EntitlementConsumeSchema = object({
+  userId: string().required().label("User ID"),
+  feature: string().trim().required().min(1).max(64).label("Feature"),
+  units: number()
+    .integer()
+    .min(1)
+    .max(CONSUME_MAX_UNITS)
+    .required()
+    .default(1)
+    .label("Units"),
+  /**
+   * Caller-supplied de-duplication key. Makes a spend exactly-once across the
+   * retries that at-least-once delivery and ordinary network failures produce.
+   */
+  idempotencyKey: string().trim().required().min(8).max(128).label("Idempotency Key"),
+}).label("Entitlement Consume");