@openlup/core 0.0.0 → 0.7.0

package/dist/risk/core/rules.js

@@ -0,0 +1,118 @@
+const SEVERITY_WEIGHT = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+};
+/** @beta */
+export function collectRiskRuleMatches(input) {
+    const matches = [];
+    const add = (match) => 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) {
+    const present = countries.filter((country) => Boolean(country));
+    return new Set(present).size > 1;
+}

package/dist/risk/core/types.d.ts

@@ -0,0 +1,65 @@
+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/dist/risk/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/risk/index.d.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/dist/risk/index.js

@@ -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/dist/risk/types.d.ts

@@ -0,0 +1,32 @@
+/** @beta */
+export declare const RISK_CONTRACT_VERSION: "risk.v1";
+/** @beta */
+export declare const RISK_RULESET_VERSION: "risk-rules.v1";
+/** @beta */
+export declare const RISK_DECISIONS: readonly ["allow", "manual_review", "block"];
+/** @beta */
+export declare const RISK_ENFORCEMENT_MODES: readonly ["shadow", "hold", "checkout_blocklist"];
+/** @beta */
+export declare const RISK_CASE_STATUSES: readonly ["open", "in_review", "approved", "blocked", "escalated", "closed"];
+/** @beta */
+export declare const RISK_CASE_DECISIONS: readonly ["approve", "block", "escalate", "note"];
+/** @beta */
+export declare const RISK_SEVERITIES: readonly ["low", "medium", "high", "critical"];
+/** @beta */
+export declare const RISK_SUBJECT_KINDS: readonly ["client", "email", "phone", "ip", "device", "payment_method", "shipping_address", "billing_tax_id", "identity_cluster"];
+/** @beta */
+export declare const RISK_REASON_CODES: readonly ["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"];
+/** @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/dist/risk/types.js

@@ -0,0 +1,43 @@
+/** @beta */
+export const RISK_CONTRACT_VERSION = "risk.v1";
+/** @beta */
+export const RISK_RULESET_VERSION = "risk-rules.v1";
+/** @beta */
+export const RISK_DECISIONS = ["allow", "manual_review", "block"];
+/** @beta */
+export const RISK_ENFORCEMENT_MODES = ["shadow", "hold", "checkout_blocklist"];
+/** @beta */
+export const RISK_CASE_STATUSES = ["open", "in_review", "approved", "blocked", "escalated", "closed"];
+/** @beta */
+export const RISK_CASE_DECISIONS = ["approve", "block", "escalate", "note"];
+/** @beta */
+export const RISK_SEVERITIES = ["low", "medium", "high", "critical"];
+/** @beta */
+export const RISK_SUBJECT_KINDS = [
+    "client",
+    "email",
+    "phone",
+    "ip",
+    "device",
+    "payment_method",
+    "shipping_address",
+    "billing_tax_id",
+    "identity_cluster",
+];
+/** @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",
+];

package/dist/shipping/index.d.ts

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

package/dist/shipping/index.js

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

package/dist/shipping/shippingResolver.d.ts

@@ -0,0 +1,26 @@
+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 declare function resolveShipping(cart: ShippingResolverCart, rules: ReadonlyArray<ShippingRule>, now: string): ResolvedShipping | null;

package/dist/shipping/shippingResolver.js

@@ -0,0 +1,88 @@
+/**
+ * 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, rules, now) {
+    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, cart) {
+    if (rule.free_threshold_minor !== null && cart.subtotal_minor >= rule.free_threshold_minor) {
+        return 0;
+    }
+    return rule.fixed_cost_minor ?? 0;
+}
+function resolveVatRate(rule, cart) {
+    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();
+            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/dist/shipping/types.d.ts

@@ -0,0 +1,45 @@
+/** @beta */
+export declare const SHIPPING_MODE_AT_CART: readonly ["one_time", "subscription", "any"];
+/** @beta */
+export type ShippingModeAtCart = (typeof SHIPPING_MODE_AT_CART)[number];
+/** @beta */
+export declare const SHIPPING_VAT_RATE_KINDS: readonly ["fixed", "inherit_main_goods", "highest_in_cart"];
+/** @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/dist/shipping/types.js

@@ -0,0 +1,4 @@
+/** @beta */
+export const SHIPPING_MODE_AT_CART = ["one_time", "subscription", "any"];
+/** @beta */
+export const SHIPPING_VAT_RATE_KINDS = ["fixed", "inherit_main_goods", "highest_in_cart"];

package/dist/subscription/cycleHardening.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+/** @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 declare const DEFAULT_CYCLE_RETRY_CADENCE: CycleRetryCadence;
+/** @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 declare function ladderTerminatedByClass(failureClass: string | null | undefined, cadence?: CycleRetryCadence): boolean;
+/** @beta */
+export declare function nextRetryAttemptAt(failedAtIso: string, attemptNumber: number, cadence?: CycleRetryCadence, failureClass?: string | null): string | null;
+/** @beta */
+export declare function shouldScheduleRetry(cycleStatus: CycleHandlerStatus, attemptNumber: number, cadence?: CycleRetryCadence, failureClass?: string | null): boolean;
+/** @beta */
+export declare function maxRetryAttempts(cadence?: CycleRetryCadence): number;
+/**
+ * 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 declare function isDunningLadderExhausted(cycle: {
+    readonly status: CycleHandlerStatus;
+    readonly retryAttempt: number;
+    readonly nextRetryAt: string | null;
+}, cadence?: CycleRetryCadence): boolean;