@openlup/platform 0.17.0 → 0.19.0

package/src/promotions/promotionAcceptanceTelemetry.ts

@@ -0,0 +1,73 @@
+import type { PromotionPurchaseScope } from "@openlup/core/promo";
+import type { PromotionQuoteMismatchField } from "./promotionQuoteBinding.js";
+
+export const PROMOTION_ACCEPTANCE_STAGES = [
+  "quote_issue",
+  "quote_honor",
+  "checkout_verify",
+] as const;
+export const PROMOTION_ACCEPTANCE_OUTCOMES = ["issued", "accepted", "rejected", "skipped"] as const;
+export const PROMOTION_ACCEPTANCE_REASONS = [
+  "issued",
+  "accepted",
+  "no_v2_adjustment",
+  "secret_unavailable",
+  "malformed",
+  "unknown_key",
+  "signature_invalid",
+  "not_yet_valid",
+  "expired",
+  "ttl_invalid",
+  "request_mismatch",
+  "code_mismatch",
+  "quote_mismatch",
+  "total_mismatch",
+  "currency_mismatch",
+  "no_v2_adjustment_in_quote",
+] as const;
+export const PROMOTION_ACCEPTANCE_KEY_SLOTS = ["current", "previous", "none"] as const;
+export const PROMOTION_ACCEPTANCE_EXPIRY_BUCKETS = [
+  "expired",
+  "lt_1h",
+  "1_24h",
+  "24_72h",
+  "none",
+] as const;
+
+export type PromotionAcceptanceTelemetry = {
+  stage: (typeof PROMOTION_ACCEPTANCE_STAGES)[number];
+  outcome: (typeof PROMOTION_ACCEPTANCE_OUTCOMES)[number];
+  reason: (typeof PROMOTION_ACCEPTANCE_REASONS)[number];
+  keySlot: (typeof PROMOTION_ACCEPTANCE_KEY_SLOTS)[number];
+  purchaseScope: PromotionPurchaseScope;
+  expiryBucket: (typeof PROMOTION_ACCEPTANCE_EXPIRY_BUCKETS)[number];
+  promotionEngineVersion: "promotion-engine.v2";
+  /**
+   * Only a `quote_mismatch` carries one: which section of the bound money
+   * projection diverged, so the next divergence names its field in the log
+   * drain without a redeploy. `other` = the token predates section bindings.
+   */
+  mismatchField?: PromotionQuoteMismatchField;
+};
+
+export type PromotionAcceptanceRecorder = (event: {
+  name: "commerce_promotion_acceptance_outcome"; domain: "commerce";
+  surface: "public" | "hidden"; details: PromotionAcceptanceTelemetry;
+}) => void;
+
+export function recordPromotionAcceptanceOutcome(
+  details: PromotionAcceptanceTelemetry,
+  surface: "public" | "hidden",
+  recorder: PromotionAcceptanceRecorder,
+): void {
+  try {
+    recorder({
+      name: "commerce_promotion_acceptance_outcome",
+      domain: "commerce",
+      surface,
+      details,
+    });
+  } catch {
+    // Telemetry is passive evidence. It must never change quote/checkout truth.
+  }
+}

package/src/promotions/promotionBenefitDefinition.ts

@@ -0,0 +1,48 @@
+export type PromotionBenefitDefinition =
+  | { kind: "legacy_percentage"; percentage: number }
+  | { kind: "legacy_fixed_amount"; amount: number }
+  | { kind: "legacy_free_shipping" }
+  | { kind: "target_percentage"; lane: "product"; valueBps: number }
+  | { kind: "percentage"; lane: "shipping"; valueBps: number }
+  | { kind: "fixed_amount"; lane: "product" | "shipping"; valueMinor: number }
+  | { kind: "free_shipping"; lane: "shipping" };
+
+/**
+ * Explicit dual-read boundary. Legacy rows only use legacy columns; v2 rows
+ * only use explicit v2 benefit columns. There is intentionally no inference.
+ */
+export function resolvePromotionBenefitDefinition(row: {
+  promotion_engine_version?: unknown;
+  discount_type: unknown;
+  discount_value: unknown;
+  benefit_lane?: unknown;
+  benefit_kind?: unknown;
+  benefit_value_bps?: unknown;
+  benefit_value_minor?: unknown;
+}): PromotionBenefitDefinition {
+  if (row.promotion_engine_version !== "promotion-engine.v2") {
+    const value = finite(row.discount_value);
+    if (row.discount_type === "percentage" && value > 0 && value < 100) return { kind: "legacy_percentage", percentage: value };
+    if (row.discount_type === "fixed_amount" && value > 0) return { kind: "legacy_fixed_amount", amount: value };
+    if (row.discount_type === "free_shipping") return { kind: "legacy_free_shipping" };
+    throw new Error("promotion_v1_benefit_invalid");
+  }
+
+  const lane = row.benefit_lane;
+  const kind = row.benefit_kind;
+  if (lane === "product" && kind === "target_percentage" && safeBps(row.benefit_value_bps)) {
+    return { kind, lane, valueBps: row.benefit_value_bps };
+  }
+  if (lane === "shipping" && kind === "percentage" && safeBps(row.benefit_value_bps)) {
+    return { kind, lane, valueBps: row.benefit_value_bps };
+  }
+  if ((lane === "product" || lane === "shipping") && kind === "fixed_amount" && positiveInt(row.benefit_value_minor)) {
+    return { kind, lane, valueMinor: row.benefit_value_minor };
+  }
+  if (lane === "shipping" && kind === "free_shipping") return { kind, lane };
+  throw new Error("promotion_v2_benefit_invalid");
+}
+
+function finite(value: unknown): number { return typeof value === "number" && Number.isFinite(value) ? value : Number.NaN; }
+function safeBps(value: unknown): value is number { return Number.isInteger(value) && Number(value) > 0 && Number(value) < 10_000; }
+function positiveInt(value: unknown): value is number { return Number.isInteger(value) && Number(value) > 0; }

package/src/promotions/promotionClaimSweepPort.ts

@@ -0,0 +1,23 @@
+export interface PromotionClaimSweepCounts {
+  checked: number;
+  cancelled: number;
+  skipped: number;
+}
+
+export interface PromotionClaimSweepPort {
+  sweep(input: {
+    now: string;
+    limit: number;
+    claimLeaseMinutes: number;
+    graceMinutes: number;
+  }): Promise<PromotionClaimSweepCounts>;
+}
+
+export function parsePromotionClaimSweepCounts(value: unknown): PromotionClaimSweepCounts {
+  const result = value as Partial<PromotionClaimSweepCounts> | null;
+  if (!result || !Number.isInteger(result.checked) || !Number.isInteger(result.cancelled)
+    || !Number.isInteger(result.skipped)) {
+    throw new Error("promotion_claim_sweep_invalid_response");
+  }
+  return result as PromotionClaimSweepCounts;
+}

package/src/promotions/promotionClaims.ts

@@ -0,0 +1,70 @@
+import type { PromotionRow } from "@openlup/core/promo";
+import type {
+  CommercePromoDataPort,
+  PaidOrdersByMode,
+  PromotionRedemptionCount,
+} from "./promoDataPort.js";
+import { promotionRedemptionMap } from "./promoDataPort.js";
+import {
+  parsePromotionClaimSweepCounts,
+  type PromotionClaimSweepPort,
+} from "./promotionClaimSweepPort.js";
+import type { PgQueryExecutor } from "../data/index.js";
+
+const ACTIVE_SQL = "SELECT public.commerce_promotion_active_definitions() AS result";
+const COUNTS_SQL = "SELECT public.commerce_promotion_paid_order_counts($1::uuid) AS result";
+const REDEMPTIONS_SQL = "SELECT * FROM public.commerce_promotion_redemption_counts($1::uuid)";
+const DEVICE_SQL = "SELECT public.commerce_promotion_device_first_order_redeemed($1) AS result";
+const SWEEP_SQL = "SELECT public.commerce_sweep_stale_promotion_claims($1,$2,$3,$4) AS result";
+
+export function createPostgresCommercePromoDataPort(executor: PgQueryExecutor): CommercePromoDataPort {
+  return {
+    async listActivePromotions(): Promise<PromotionRow[]> {
+      const value = scalar(await executor.query(ACTIVE_SQL));
+      if (!Array.isArray(value)) throw new Error("promotions_list_invalid_response");
+      return value as PromotionRow[];
+    },
+    async countPaidOrders(clientId): Promise<number> {
+      const counts = paidCounts(scalar(await executor.query(COUNTS_SQL, [clientId])));
+      return counts.oneTime + counts.subscription;
+    },
+    async countPaidOrdersByMode(clientId): Promise<PaidOrdersByMode> {
+      return paidCounts(scalar(await executor.query(COUNTS_SQL, [clientId])));
+    },
+    async redemptionCounts(clientId): Promise<Map<string, PromotionRedemptionCount>> {
+      return promotionRedemptionMap((await executor.query(REDEMPTIONS_SQL, [clientId])).rows);
+    },
+    async deviceFirstOrderRedeemed(visitorId): Promise<boolean> {
+      if (!visitorId?.trim()) return false;
+      return scalar(await executor.query(DEVICE_SQL, [visitorId])) === true;
+    },
+  };
+}
+
+export function createPostgresPromotionClaimSweepPort(executor: PgQueryExecutor): PromotionClaimSweepPort {
+  return {
+    async sweep(input) {
+      return parsePromotionClaimSweepCounts(scalar(await executor.query(SWEEP_SQL, [
+        input.now, input.limit, input.claimLeaseMinutes, input.graceMinutes,
+      ])));
+    },
+  };
+}
+
+function scalar(result: { rows: Record<string, unknown>[] }): unknown {
+  if (result.rows.length !== 1 || !("result" in result.rows[0]!)) {
+    throw new Error("promotion_claim_response_invalid");
+  }
+  return result.rows[0]!.result;
+}
+
+function paidCounts(value: unknown): PaidOrdersByMode {
+  const row = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  const oneTime = Number(row.oneTime ?? -1);
+  const subscription = Number(row.subscription ?? -1);
+  if (!Number.isSafeInteger(oneTime) || oneTime < 0
+    || !Number.isSafeInteger(subscription) || subscription < 0) {
+    throw new Error("promotion_paid_order_counts_invalid_response");
+  }
+  return { oneTime, subscription };
+}

package/src/promotions/promotionCodePreview.ts

@@ -0,0 +1,183 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import type {
+  PromotionCodeBenefit,
+  PromotionCodePreviewRequest,
+  PromotionCodePreviewResponse,
+} from "./contracts/index.js";
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+import {
+  evaluatePromotionAdjustmentsV2,
+  type PromotionAdjustmentCandidate,
+} from "@openlup/core/promo";
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const PROMOTION_ENGINE_VERSION = "promotion-engine.v2" as const;
+
+export function createPromotionCodePreview({ minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR }: { minimumProductPayableMinor: number }) {
+  function generatePromotionCode(): string {
+    const bytes = randomBytes(10);
+    let bits = 0;
+    let buffer = 0;
+    let code = "";
+    for (const byte of bytes) {
+      buffer = (buffer << 8) | byte;
+      bits += 8;
+      while (bits >= 5) {
+        bits -= 5;
+        code += CROCKFORD_BASE32[(buffer >>> bits) & 31];
+        buffer &= (1 << bits) - 1;
+      }
+    }
+    return code;
+  }
+
+  function normalizePromotionCode(code: string): string {
+    return code.trim().toUpperCase();
+  }
+
+  function promotionPreviewProof(input: PromotionCodePreviewRequest, secret: string): string {
+    assertPreviewSecret(secret);
+    assertSupportedPreviewBenefits(input);
+    return createHmac("sha256", secret).update(previewProofPayload(input)).digest("base64url");
+  }
+
+  function verifyPromotionPreviewProof(
+    input: PromotionCodePreviewRequest,
+    proof: string,
+    secret: string,
+  ): boolean {
+    const expected = promotionPreviewProof(input, secret);
+    const expectedBytes = Buffer.from(expected);
+    const actualBytes = Buffer.from(proof);
+    return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+  }
+
+  function previewPromotionCode(
+    input: PromotionCodePreviewRequest,
+    secret: string,
+  ): PromotionCodePreviewResponse {
+    assertSupportedPreviewBenefits(input);
+    const eligible = input.context.referenceProductMinor >= input.minimumReferenceMinor;
+    const results = (["one_time", "subscription_initial"] as const).map((scope) => {
+      const currentProductMinor =
+        scope === "one_time"
+          ? input.context.oneTimeProductMinor
+          : input.context.subscriptionProductMinor;
+      const candidates = eligible
+        ? input.benefits
+          .map((benefit) => toCandidate(benefit, input.scopes, currentProductMinor))
+          .filter((candidate): candidate is PromotionAdjustmentCandidate => candidate !== null)
+        : [];
+      const result = evaluatePromotionAdjustmentsV2(
+        {
+          purchaseScope: scope,
+          referenceProductMinor: input.context.referenceProductMinor,
+          currentProductMinor,
+          shippingMinor: input.context.shippingMinor,
+          minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+        },
+        candidates,
+      );
+      return {
+        scope,
+        productPayableMinor: result.productPayableMinor,
+        shippingPayableMinor: result.shippingPayableMinor,
+        effectiveProductDiscountBps: result.effectiveProductDiscountBps,
+        winner: result.adjustments.some((adjustment) => adjustment.source === "code")
+          ? ("code" as const)
+          : ("automatic" as const),
+        floorApplied: result.adjustments.some((adjustment) => adjustment.floorApplied),
+        adjustments: result.adjustments.map((adjustment) => ({
+          lane: adjustment.lane,
+          kind: input.promotionEngineVersion === "promotion-engine.v1"
+            && adjustment.promotionId === "preview-product"
+            && input.benefits.some((benefit) => benefit.lane === "product" && benefit.kind === "percentage")
+            ? ("percentage" as const)
+            : adjustment.kind,
+          amountOffMinor: adjustment.amountOffMinor,
+          beforeMinor: adjustment.beforeMinor,
+          afterMinor: adjustment.afterMinor,
+        })),
+      };
+    });
+    return {
+      contractVersion: COMMERCE_CONTRACT_VERSION,
+      promotionEngineVersion: input.promotionEngineVersion,
+      previewProof: promotionPreviewProof(input, secret),
+      results,
+    };
+  }
+
+  function previewProofPayload(input: PromotionCodePreviewRequest): string {
+    return stableJson({
+      promotionEngineVersion: input.promotionEngineVersion,
+      minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+      minimumReferenceMinor: input.minimumReferenceMinor,
+      benefits: input.benefits,
+      scopes: input.scopes,
+      context: input.context,
+    });
+  }
+
+  function assertPreviewSecret(secret: string): void {
+    if (Buffer.byteLength(secret, "utf8") < 32) {
+      throw new RangeError("promotion_preview_secret_too_short");
+    }
+  }
+
+  function assertSupportedPreviewBenefits(input: PromotionCodePreviewRequest): void {
+    if (input.benefits.some((benefit) => "validationState" in benefit)) {
+      throw new RangeError("promotion_preview_unsupported_legacy_value");
+    }
+  }
+
+  function toCandidate(
+    benefit: PromotionCodeBenefit,
+    scopes: PromotionCodePreviewRequest["scopes"],
+    currentProductMinor: number,
+  ): PromotionAdjustmentCandidate | null {
+    const base = {
+      promotionId: `preview-${benefit.lane}`,
+      codeId: "preview-code",
+      source: "code" as const,
+      name: "Promotion code preview",
+      scopes,
+    };
+    if ("validationState" in benefit) {
+      throw new RangeError("promotion_preview_unsupported_legacy_value");
+    }
+    if (("valueBps" in benefit && benefit.valueBps === 0)
+        || ("valueMinor" in benefit && benefit.valueMinor === 0)) return null;
+    if (benefit.kind === "target_percentage") return { ...base, ...benefit };
+    if (benefit.kind === "percentage" && benefit.lane === "product") {
+      const valueMinor = benefit.valueBps >= 10_000
+        ? currentProductMinor
+        : Number((BigInt(currentProductMinor) * BigInt(benefit.valueBps)) / 10_000n);
+      return {
+        ...base,
+        lane: "product",
+        kind: "fixed_amount",
+        valueMinor,
+      };
+    }
+    if (benefit.kind === "percentage" && benefit.lane === "shipping" && benefit.valueBps >= 10_000) {
+      return { ...base, lane: "shipping", kind: "free_shipping" };
+    }
+    if (benefit.kind === "percentage") return { ...base, ...benefit };
+    if (benefit.kind === "fixed_amount") return { ...base, ...benefit };
+    return { ...base, ...benefit };
+  }
+
+  function stableJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+      const record = value as Record<string, unknown>;
+      return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+        .join(",")}}`;
+    }
+    return JSON.stringify(value);
+  }
+
+  return { generatePromotionCode, normalizePromotionCode, promotionPreviewProof, verifyPromotionPreviewProof, previewPromotionCode };
+}

package/src/promotions/promotionCodeQuotePort.ts

@@ -0,0 +1,35 @@
+import type {
+  PromotionAdjustmentCandidate,
+  PromotionPurchaseScope,
+} from "@openlup/core/promo";
+import type {
+  CommerceCodeRejection,
+  CommerceCodeRejectionDetail,
+} from "../pricing/index.js";
+
+export type ResolvedPromotionCodeCandidate = PromotionAdjustmentCandidate & {
+  codeRevision: number;
+  definitionFingerprint: string;
+  minimumReferenceMinor: number;
+  validTo: string | null;
+};
+
+export interface ResolvePromotionCodeQuoteInput {
+  codes: readonly string[];
+  clientId: string | null;
+  purchaseScope: PromotionPurchaseScope;
+  referenceProductMinor: number;
+  atTime: string;
+}
+
+export interface PromotionCodeQuoteResolution {
+  candidates: ResolvedPromotionCodeCandidate[];
+  codeRejections: CommerceCodeRejection[];
+  /** Additive v2 RPC detail; old RPC fallback returns an empty array. */
+  codeRejectionDetails: CommerceCodeRejectionDetail[];
+}
+
+/** Advisory quote read only. Capacity is authoritatively claimed by the order transaction. */
+export interface PromotionCodeQuotePort {
+  resolve(input: ResolvePromotionCodeQuoteInput): Promise<PromotionCodeQuoteResolution>;
+}