@openlup/core 0.0.0 → 0.7.0

package/src/risk/core/rules.ts

@@ -0,0 +1,128 @@
+import type { RiskSeverity } from "../types.js";
+import type {
+  RiskEvaluationInput,
+  RiskRuleMatch,
+} from "./types.js";
+
+const SEVERITY_WEIGHT: Record<RiskSeverity, number> = {
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4,
+};
+
+/** @beta */
+export function collectRiskRuleMatches(input: RiskEvaluationInput): RiskRuleMatch[] {
+  const matches: RiskRuleMatch[] = [];
+  const add = (match: RiskRuleMatch) => matches.push(match);
+  const { checkout, payment, signals } = input;
+
+  if (signals.exactBlocklistMatches.length > 0) {
+    add({
+      code: "exact_blocklist_match",
+      score: 100,
+      severity: "critical",
+      evidence: { matchCount: signals.exactBlocklistMatches.length },
+    });
+  }
+  if (signals.recentCheckoutAttemptsByIdentity >= 3) {
+    add({
+      code: "velocity_checkout_attempts",
+      score: 35,
+      severity: "medium",
+      evidence: { attempts: signals.recentCheckoutAttemptsByIdentity, window: "1h" },
+    });
+  }
+  if (signals.distinctEmailsByIp24h >= 3) {
+    add({
+      code: "velocity_email_cluster",
+      score: 45,
+      severity: "high",
+      evidence: { distinctEmails: signals.distinctEmailsByIp24h, window: "24h" },
+    });
+  }
+  if (signals.discountedPaidOrders30d >= 2) {
+    add({
+      code: "velocity_discount_reuse",
+      score: 40,
+      severity: "medium",
+      evidence: { discountedPaidOrders: signals.discountedPaidOrders30d, window: "30d" },
+    });
+  }
+  if (signals.clientsSharingPaymentMethod7d >= 2) {
+    add({
+      code: "duplicate_payment_method",
+      score: 50,
+      severity: "high",
+      evidence: { clients: signals.clientsSharingPaymentMethod7d, window: "7d" },
+    });
+  }
+  if (signals.priorDisputes > 0) {
+    add({
+      code: "prior_dispute",
+      score: 80,
+      severity: "critical",
+      evidence: { disputes: signals.priorDisputes },
+    });
+  }
+  if (checkout?.checkoutKind === "subscription_initial" && checkout.promoCodeCount > 0 && signals.discountedPaidOrders30d > 0) {
+    add({
+      code: "subscription_promo_reuse",
+      score: 45,
+      severity: "high",
+      evidence: { promoCodeCount: checkout.promoCodeCount, priorDiscounts: signals.discountedPaidOrders30d },
+    });
+  }
+  if (checkout?.bundleDiscountApplied && signals.discountedPaidOrders30d > 0) {
+    add({
+      code: "bundle_discount_review",
+      score: 30,
+      severity: "medium",
+      evidence: { priorDiscounts: signals.discountedPaidOrders30d },
+    });
+  }
+  if (payment?.avsResult === "mismatch") {
+    add({ code: "avs_mismatch", score: 25, severity: "medium", evidence: { avsResult: "mismatch" } });
+  }
+  if (payment?.cvcResult === "mismatch") {
+    add({ code: "cvc_mismatch", score: 35, severity: "high", evidence: { cvcResult: "mismatch" } });
+  }
+  if (checkout && hasCountryMismatch(checkout.shippingCountry, checkout.billingCountry, checkout.ipCountry)) {
+    add({
+      code: "country_signal_mismatch",
+      score: 30,
+      severity: "medium",
+      evidence: {
+        shippingCountry: checkout.shippingCountry ?? null,
+        billingCountry: checkout.billingCountry ?? null,
+        ipCountry: checkout.ipCountry ?? null,
+      },
+    });
+  }
+  if (checkout && signals.highRiskCountries.some((country) => [checkout.shippingCountry, checkout.billingCountry, checkout.ipCountry].includes(country))) {
+    add({ code: "high_risk_country", score: 70, severity: "critical", evidence: { highRiskCountries: signals.highRiskCountries } });
+  }
+  if (payment?.localAmountMinor != null && payment.providerAmountMinor != null && payment.localAmountMinor !== payment.providerAmountMinor) {
+    add({
+      code: "payment_amount_mismatch",
+      score: 80,
+      severity: "critical",
+      evidence: { localAmountMinor: payment.localAmountMinor, providerAmountMinor: payment.providerAmountMinor },
+    });
+  }
+  if (payment?.localCurrency && payment.providerCurrency && payment.localCurrency !== payment.providerCurrency) {
+    add({
+      code: "payment_currency_mismatch",
+      score: 80,
+      severity: "critical",
+      evidence: { localCurrency: payment.localCurrency, providerCurrency: payment.providerCurrency },
+    });
+  }
+
+  return matches.sort((a, b) => b.score - a.score || SEVERITY_WEIGHT[b.severity] - SEVERITY_WEIGHT[a.severity] || a.code.localeCompare(b.code));
+}
+
+function hasCountryMismatch(...countries: Array<string | null | undefined>): boolean {
+  const present = countries.filter((country): country is string => Boolean(country));
+  return new Set(present).size > 1;
+}

package/src/risk/core/types.ts

@@ -0,0 +1,73 @@
+import type {
+  RiskDecision,
+  RiskEnforcementMode,
+  RiskReasonCode,
+  RiskSeverity,
+} from "../types.js";
+
+/** @beta */
+export interface RiskCheckoutFacts {
+  checkoutKind: "one_time" | "subscription_initial";
+  totalMinor: number;
+  currency: string;
+  promoCodeCount: number;
+  bundleDiscountApplied: boolean;
+  shippingCountry?: string | null;
+  billingCountry?: string | null;
+  ipCountry?: string | null;
+  saveForFutureUse?: boolean;
+}
+
+/** @beta */
+export interface RiskPaymentFacts {
+  resultStatus?: "succeeded" | "failed" | "refunded" | "partially_refunded" | "disputed" | null;
+  localAmountMinor?: number | null;
+  providerAmountMinor?: number | null;
+  localCurrency?: string | null;
+  providerCurrency?: string | null;
+  avsResult?: "match" | "mismatch" | "unavailable" | null;
+  cvcResult?: "match" | "mismatch" | "unavailable" | null;
+}
+
+/** @beta */
+export interface RiskSignalFacts {
+  exactBlocklistMatches: Array<{ subjectKind: string; reasonCode?: string | null }>;
+  recentCheckoutAttemptsByIdentity: number;
+  distinctEmailsByIp24h: number;
+  discountedPaidOrders30d: number;
+  clientsSharingPaymentMethod7d: number;
+  priorDisputes: number;
+  highRiskCountries: string[];
+}
+
+/** @beta */
+export interface RiskEvaluationInput {
+  source: "checkout" | "paid_order" | "payment_webhook" | "admin_replay";
+  mode: RiskEnforcementMode;
+  checkout?: RiskCheckoutFacts;
+  payment?: RiskPaymentFacts;
+  signals: RiskSignalFacts;
+}
+
+/** @beta */
+export interface RiskRuleMatch {
+  code: RiskReasonCode;
+  score: number;
+  severity: RiskSeverity;
+  evidence: Record<string, unknown>;
+}
+
+/** @beta */
+export interface RiskEvaluationOutput {
+  decision: RiskDecision;
+  score: number;
+  severity: RiskSeverity;
+  reasonCodes: RiskReasonCode[];
+  matchedRules: RiskRuleMatch[];
+  enforcement: {
+    mode: RiskEnforcementMode;
+    applied: boolean;
+    checkoutBlocked: boolean;
+    holdRequested: boolean;
+  };
+}

package/src/risk/index.ts

@@ -0,0 +1,8 @@
+/** @beta */
+export * from "./types.js";
+/** @beta */
+export * from "./core/types.js";
+/** @beta */
+export * from "./core/rules.js";
+/** @beta */
+export * from "./core/evaluator.js";

package/src/risk/types.ts

@@ -0,0 +1,60 @@
+/** @beta */
+export const RISK_CONTRACT_VERSION = "risk.v1" as const;
+/** @beta */
+export const RISK_RULESET_VERSION = "risk-rules.v1" as const;
+
+/** @beta */
+export const RISK_DECISIONS = ["allow", "manual_review", "block"] as const;
+/** @beta */
+export const RISK_ENFORCEMENT_MODES = ["shadow", "hold", "checkout_blocklist"] as const;
+/** @beta */
+export const RISK_CASE_STATUSES = ["open", "in_review", "approved", "blocked", "escalated", "closed"] as const;
+/** @beta */
+export const RISK_CASE_DECISIONS = ["approve", "block", "escalate", "note"] as const;
+/** @beta */
+export const RISK_SEVERITIES = ["low", "medium", "high", "critical"] as const;
+/** @beta */
+export const RISK_SUBJECT_KINDS = [
+  "client",
+  "email",
+  "phone",
+  "ip",
+  "device",
+  "payment_method",
+  "shipping_address",
+  "billing_tax_id",
+  "identity_cluster",
+] as const;
+
+/** @beta */
+export const RISK_REASON_CODES = [
+  "exact_blocklist_match",
+  "velocity_checkout_attempts",
+  "velocity_email_cluster",
+  "velocity_discount_reuse",
+  "duplicate_payment_method",
+  "subscription_promo_reuse",
+  "bundle_discount_review",
+  "avs_mismatch",
+  "cvc_mismatch",
+  "country_signal_mismatch",
+  "high_risk_country",
+  "payment_amount_mismatch",
+  "payment_currency_mismatch",
+  "prior_dispute",
+] as const;
+
+/** @beta */
+export type RiskDecision = (typeof RISK_DECISIONS)[number];
+/** @beta */
+export type RiskEnforcementMode = (typeof RISK_ENFORCEMENT_MODES)[number];
+/** @beta */
+export type RiskCaseStatus = (typeof RISK_CASE_STATUSES)[number];
+/** @beta */
+export type RiskCaseDecision = (typeof RISK_CASE_DECISIONS)[number];
+/** @beta */
+export type RiskSeverity = (typeof RISK_SEVERITIES)[number];
+/** @beta */
+export type RiskSubjectKind = (typeof RISK_SUBJECT_KINDS)[number];
+/** @beta */
+export type RiskReasonCode = (typeof RISK_REASON_CODES)[number];

package/src/shipping/index.ts

@@ -0,0 +1,4 @@
+/** @beta */
+export * from "./shippingResolver.js";
+/** @beta */
+export * from "./types.js";

package/src/shipping/shippingResolver.ts

@@ -0,0 +1,101 @@
+import type {
+  ResolvedShipping,
+  ShippingResolverCart,
+  ShippingRule,
+} from "./types.js";
+
+/**
+ * Pure shipping resolver. It picks the most specific active shipping rule for a
+ * cart's region, currency, and cart mode, then computes the shipping amount and
+ * VAT-rate snapshot. Provider selection, pickup points, labels, and fulfillment
+ * side effects stay outside this package.
+ *
+ * Resolution order:
+ * 1. Filter by active + region + currency + validity window.
+ * 2. Prefer an exact cart-mode rule over an `any` fallback.
+ * 3. Within the same mode bucket, lower priority wins.
+ * 4. Return null when no rule matches; the host application owns fallback UI or
+ *    operational errors.
+ *
+ * Amount:
+ * - A configured free threshold makes shipping free once the cart subtotal meets
+ *   or exceeds it.
+ * - Otherwise, fixed_cost_minor is used; null means this rule is always free.
+ *
+ * VAT rate snapshot:
+ * - `fixed` uses the rule's vat_rate_bps.
+ * - `inherit_main_goods` uses the most common line VAT rate.
+ * - `highest_in_cart` uses the max line VAT rate as a defensive accounting rule.
+ */
+/** @beta */
+export function resolveShipping(
+  cart: ShippingResolverCart,
+  rules: ReadonlyArray<ShippingRule>,
+  now: string,
+): ResolvedShipping | null {
+  const eligible = rules
+    .filter((r) => r.active)
+    .filter((r) => r.region_code === cart.region_code)
+    .filter((r) => r.currency === cart.currency)
+    .filter((r) => r.valid_from <= now && (r.valid_to === null || r.valid_to >= now))
+    .filter((r) => r.mode_at_cart === cart.cart_mode || r.mode_at_cart === "any");
+
+  if (eligible.length === 0) return null;
+
+  const sorted = [...eligible].sort((a, b) => {
+    // Exact mode match beats the cross-mode fallback.
+    const aSpecific = a.mode_at_cart === cart.cart_mode ? 0 : 1;
+    const bSpecific = b.mode_at_cart === cart.cart_mode ? 0 : 1;
+    if (aSpecific !== bSpecific) return aSpecific - bSpecific;
+    return a.priority - b.priority;
+  });
+
+  const rule = sorted[0];
+  const amount = computeAmount(rule, cart);
+  const vatRate = resolveVatRate(rule, cart);
+
+  return {
+    amount_minor: amount,
+    carrier_kind: rule.carrier_kind,
+    delivery_estimate_days: rule.delivery_estimate_days,
+    applied_rule_id: rule.id,
+    applied_rule_name: rule.name,
+    vat_rate_bps: vatRate,
+  };
+}
+
+function computeAmount(rule: ShippingRule, cart: ShippingResolverCart): number {
+  if (rule.free_threshold_minor !== null && cart.subtotal_minor >= rule.free_threshold_minor) {
+    return 0;
+  }
+  return rule.fixed_cost_minor ?? 0;
+}
+
+function resolveVatRate(rule: ShippingRule, cart: ShippingResolverCart): number {
+  switch (rule.vat_rate_kind) {
+    case "fixed":
+      return rule.vat_rate_bps;
+    case "highest_in_cart":
+      return cart.line_vat_rates_bps.length === 0
+        ? rule.vat_rate_bps
+        : Math.max(...cart.line_vat_rates_bps);
+    case "inherit_main_goods": {
+      if (cart.line_vat_rates_bps.length === 0) return rule.vat_rate_bps;
+      const counts = new Map<number, number>();
+      for (const rate of cart.line_vat_rates_bps) {
+        counts.set(rate, (counts.get(rate) ?? 0) + 1);
+      }
+      let dominantRate = rule.vat_rate_bps;
+      let dominantCount = 0;
+      for (const [rate, count] of counts) {
+        if (count > dominantCount) {
+          dominantRate = rate;
+          dominantCount = count;
+        }
+      }
+      return dominantRate;
+    }
+    default:
+      return rule.vat_rate_bps;
+  }
+}

package/src/shipping/types.ts

@@ -0,0 +1,49 @@
+/** @beta */
+export const SHIPPING_MODE_AT_CART = ["one_time", "subscription", "any"] as const;
+/** @beta */
+export type ShippingModeAtCart = (typeof SHIPPING_MODE_AT_CART)[number];
+
+/** @beta */
+export const SHIPPING_VAT_RATE_KINDS = ["fixed", "inherit_main_goods", "highest_in_cart"] as const;
+/** @beta */
+export type ShippingVatRateKind = (typeof SHIPPING_VAT_RATE_KINDS)[number];
+
+/** @beta */
+export interface ShippingRule {
+  id: string;
+  name: string;
+  region_code: string;
+  currency: string;
+  mode_at_cart: ShippingModeAtCart;
+  carrier_kind: string;
+  free_threshold_minor: number | null;
+  fixed_cost_minor: number | null;
+  weight_threshold_g: number | null;
+  delivery_estimate_days: number | null;
+  priority: number;
+  vat_rate_bps: number;
+  vat_rate_kind: ShippingVatRateKind;
+  active: boolean;
+  valid_from: string;
+  valid_to: string | null;
+}
+
+/** @beta */
+export interface ShippingResolverCart {
+  region_code: string;
+  currency: string;
+  cart_mode: "one_time" | "subscription";
+  subtotal_minor: number;
+  line_vat_rates_bps: ReadonlyArray<number>;
+  weight_total_g?: number;
+}
+
+/** @beta */
+export interface ResolvedShipping {
+  amount_minor: number;
+  carrier_kind: string;
+  delivery_estimate_days: number | null;
+  applied_rule_id: string;
+  applied_rule_name: string;
+  vat_rate_bps: number;
+}

package/src/subscription/cycleHardening.ts

@@ -0,0 +1,174 @@
+/**
+ * Subscription cycle hardening helpers — the canonical retry ladder a renewal
+ * payment failure follows.
+ *
+ * This module is the SINGLE authority on the ladder. It answers four questions:
+ *
+ *   - `nextRetryAttemptAt(failedAt, attemptNumber, cadence?, failureClass?)` —
+ *     when the next charge is due, or `null` when no next charge is due.
+ *   - `shouldScheduleRetry(cycleStatus, attemptNumber, cadence?, failureClass?)`
+ *     — whether a failed payment may move into `retry_scheduled`.
+ *   - `ladderTerminatedByClass(failureClass, cadence?)` — whether the REASON for
+ *     the refusal, rather than the rung reached, ends the ladder.
+ *   - `isDunningLadderExhausted(cycle, cadence?)` — whether a refused cycle has
+ *     run past the last rung, the only non-payment reason to pause.
+ *
+ * TERMINATING, not capping. An attempt past the end of the ladder answers
+ * `null`, which is the pause signal; it does not answer "the last slot again".
+ * Callers therefore never need a `attempt <= maxRetryAttempts()` guard of their
+ * own — asking for the next slot IS the decision, and a second copy of the
+ * budget check is exactly how two rails drift apart.
+ *
+ * The cadence is injectable so a deployment can publish its own ladder, and the
+ * default is frozen so nobody can mutate the shipped one in place.
+ *
+ * All helpers are PURE — they never schedule local jobs, never touch payment
+ * adapters, never persist a cycle.
+ */
+
+import {
+  PAYMENT_FAILURE_CLASSES,
+  failureClassDecision,
+  type PaymentFailureClass,
+} from "../payment/paymentFailureTaxonomyContracts.js";
+
+/** @beta */
+export interface CycleRetryCadence {
+  /**
+   * Hours after the failure at which each successive retry is due, in order.
+   * Its length IS the retry budget: `maxRetryAttempts()` reports it and
+   * `nextRetryAttemptAt` terminates past it.
+   */
+  readonly backoffHours: readonly number[];
+  /**
+   * Refusal classes for which this deployment publishes no ladder at all, named
+   * as {@link PaymentFailureClass} values. Typed as strings because the same set
+   * is read back out of a nullable `text` column written by an older deployment,
+   * and an unrecognised value must be ignored rather than crash a schedule.
+   *
+   * Omitting it means "no class ends the ladder early", which is the behaviour
+   * every deployment had before this field existed.
+   */
+  readonly terminatingFailureClasses?: readonly string[];
+}
+
+/** @beta */
+export const DEFAULT_CYCLE_RETRY_CADENCE: CycleRetryCadence = Object.freeze({
+  backoffHours: Object.freeze([24, 72, 168]) as readonly number[], // 1d, 3d, 7d
+  // ONE member. `hard_do_not_retry` is the taxonomy's statement that the issuer
+  // refused the INSTRUMENT rather than this charge, so no rung below can change
+  // the answer and three more attempts only promise the customer eleven days of
+  // charges that cannot land. Every other class keeps the full cadence. Its SQL
+  // twin is `v_terminating_classes` in the canonical apply body;
+  // scripts/retry-ladder-terminating-classes.test.ts reads that literal out of
+  // the latest declaring migration and fails if the two sets ever differ.
+  terminatingFailureClasses: Object.freeze(["hard_do_not_retry"]) as readonly string[],
+});
+
+/** @beta */
+export type CycleHandlerStatus =
+  | "planned"
+  | "payment_pending"
+  | "paid"
+  | "payment_failed"
+  | "retry_scheduled"
+  | "skipped"
+  | "cancelled";
+
+/**
+ * Whether the class of a refusal, rather than the rung it reached, ends the
+ * ladder.
+ *
+ * Fails OPEN in three separate ways, because a wrong `true` here withholds a
+ * charge the customer expected while a wrong `false` merely retries as before:
+ * an absent class does not terminate, a class the cadence does not list does not
+ * terminate, and a listed class the taxonomy does not recognise does not
+ * terminate. The last check is why a typo in configuration cannot stop a ladder.
+ *
+ * The final word belongs to {@link failureClassDecision}, not to the list: a
+ * cadence that lists a class the decision table still permits retrying is
+ * incoherent, and the table wins. That keeps the schedule from ever contradicting
+ * the kernel that already ruled on whether the instrument may be charged again.
+ *
+ * @beta
+ */
+export function ladderTerminatedByClass(
+  failureClass: string | null | undefined,
+  cadence: CycleRetryCadence = DEFAULT_CYCLE_RETRY_CADENCE,
+): boolean {
+  if (failureClass === null || failureClass === undefined) return false;
+  if (!(cadence.terminatingFailureClasses ?? []).includes(failureClass)) return false;
+  if (!(PAYMENT_FAILURE_CLASSES as readonly string[]).includes(failureClass)) return false;
+  return !failureClassDecision(failureClass as PaymentFailureClass).retryAllowed;
+}
+
+/** @beta */
+export function nextRetryAttemptAt(
+  failedAtIso: string,
+  attemptNumber: number,
+  cadence: CycleRetryCadence = DEFAULT_CYCLE_RETRY_CADENCE,
+  failureClass?: string | null,
+): string | null {
+  if (ladderTerminatedByClass(failureClass, cadence)) return null;
+  const hours = cadence.backoffHours[attemptNumber - 1];
+  // Covers both ends at once: an attempt below 1 and an attempt past the last
+  // ladder slot are equally "no next charge is due".
+  if (attemptNumber < 1 || hours === undefined) return null;
+  const failedAt = new Date(failedAtIso);
+  if (Number.isNaN(failedAt.getTime())) return null;
+  const next = new Date(failedAt.getTime() + hours * 60 * 60 * 1000);
+  return next.toISOString();
+}
+
+/** @beta */
+export function shouldScheduleRetry(
+  cycleStatus: CycleHandlerStatus,
+  attemptNumber: number,
+  cadence: CycleRetryCadence = DEFAULT_CYCLE_RETRY_CADENCE,
+  failureClass?: string | null,
+): boolean {
+  if (cycleStatus !== "payment_failed") return false;
+  if (attemptNumber < 1) return false;
+  // Asked and answered by the same predicate the schedule uses, so this helper
+  // cannot say "schedule one" about a refusal for which the ladder answers none.
+  if (ladderTerminatedByClass(failureClass, cadence)) return false;
+  return attemptNumber <= maxRetryAttempts(cadence);
+}
+
+/** @beta */
+export function maxRetryAttempts(
+  cadence: CycleRetryCadence = DEFAULT_CYCLE_RETRY_CADENCE,
+): number {
+  return cadence.backoffHours.length;
+}
+
+/**
+ * Whether a refused cycle has EXHAUSTED the ladder: it failed, nothing is
+ * scheduled after it, and the attempt that failed sits past the last rung.
+ *
+ * This is the one condition under which the platform may pause a live
+ * subscription for non-payment. Both halves are required. An absent schedule on
+ * its own is not exhaustion: a class-terminated refusal on rung one also leaves
+ * nothing scheduled, and treating it as exhaustion would pause a subscription on
+ * the day of its first refusal. The rung is derived from the cadence, so pass
+ * the same cadence here and to `recordPaymentFailure`. The managed SQL dunning
+ * boundary spells the shipped ladder's rung as a fixed constant
+ * (`v_ladder_exhausted_from`, 4); a deployment that publishes a different
+ * ladder must move that constant with it.
+ *
+ * @beta
+ */
+export function isDunningLadderExhausted(
+  cycle: {
+    readonly status: CycleHandlerStatus;
+    readonly retryAttempt: number;
+    readonly nextRetryAt: string | null;
+  },
+  cadence: CycleRetryCadence = DEFAULT_CYCLE_RETRY_CADENCE,
+): boolean {
+  return (
+    cycle.status === "payment_failed" &&
+    cycle.nextRetryAt === null &&
+    cycle.retryAttempt > maxRetryAttempts(cadence)
+  );
+}

package/src/subscription/index.ts

@@ -0,0 +1,14 @@
+/** @beta */
+export * from "./cycleHardening.js";
+/** @beta */
+export * from "./subscriptionEngineCore.js";
+/** @beta */
+export * from "./subscriptionEngineLifecycle.js";
+/** @beta */
+export * from "./subscriptionEnginePayment.js";
+/** @beta */
+export * from "./subscriptionEngineTypes.js";
+/** @beta */
+export * from "./subscriptionEngineUtils.js";
+/** @beta */
+export * from "./types.js";