@openlup/platform 0.16.0 → 0.18.0

package/src/promotions/contracts/index.ts

@@ -0,0 +1,387 @@
+/** Promotion-owned preview DTOs. Validation and secrets belong to the server entry. */
+export type PromotionCodeBenefit = {
+    lane: "product";
+    kind: "target_percentage";
+    valueBps: number;
+} | {
+    lane: "product";
+    kind: "fixed_amount";
+    valueMinor: number;
+} | {
+    lane: "shipping";
+    kind: "fixed_amount";
+    valueMinor: number;
+} | {
+    lane: "product";
+    kind: "percentage";
+    valueBps: number;
+} | {
+    lane: "shipping";
+    kind: "percentage";
+    valueBps: number;
+} | {
+    lane: "shipping";
+    kind: "free_shipping";
+} | {
+    lane: "product" | "shipping";
+    kind: "percentage" | "fixed_amount";
+    validationState: "unsupported_legacy_value";
+};
+export interface PromotionCodePreviewRequest {
+    benefits: PromotionCodeBenefit[];
+    scopes: Array<"one_time" | "subscription_initial">;
+    promotionEngineVersion: "promotion-engine.v1" | "promotion-engine.v2";
+    minimumReferenceMinor: number;
+    context: {
+        referenceProductMinor: number;
+        oneTimeProductMinor: number;
+        subscriptionProductMinor: number;
+        shippingMinor: number;
+    };
+}
+export interface PromotionCodePreviewResponse {
+    contractVersion: "commerce.v0";
+    promotionEngineVersion: "promotion-engine.v1" | "promotion-engine.v2";
+    previewProof: string;
+    results: Array<{
+        scope: "one_time" | "subscription_initial";
+        productPayableMinor: number;
+        shippingPayableMinor: number;
+        effectiveProductDiscountBps: number;
+        winner: "code" | "automatic";
+        floorApplied: boolean;
+        adjustments: Array<{
+            lane: "product" | "shipping";
+            kind: "target_percentage" | "percentage" | "fixed_amount" | "free_shipping";
+            amountOffMinor: number;
+            beforeMinor: number;
+            afterMinor: number;
+        }>;
+    }>;
+}
+/** Admin DTOs are schema outputs; validation remains in the server entry. */
+/** Promotion admin output DTOs. Validation and host policy belong to the server entry. */
+export type AdminPromotion = {
+    id: string;
+    code: string | null;
+    name: string;
+    triggerType: "coupon_code" | "automatic" | "referral";
+    discountType: "percentage" | "fixed_amount" | "free_shipping";
+    semanticBenefit: {
+        kind: "target_percentage";
+        valueBps: number;
+        reference: "catalog_list_price";
+        unitTargets: {
+            variantId: string;
+            sku: string | null;
+            referenceMinor: number;
+            targetMinor: number;
+            currency: string;
+        }[];
+    } | {
+        kind: "percentage";
+        valuePercent: number;
+    } | {
+        kind: "fixed_amount";
+        valueMinor: number;
+        currency: string;
+    } | {
+        kind: "free_shipping";
+    } | {
+        kind: "unavailable";
+        reason: "system_managed_metadata_incomplete";
+    };
+    systemManaged: boolean;
+    readOnly: boolean;
+    v2Mirror: {
+        id: string;
+        status: "draft" | "active" | "paused" | "archived";
+    } | null;
+    appliesToKind: "order_total" | "line_with_variant" | "line_with_category";
+    stackingRule: "exclusive" | "stackable_with_any" | "stackable_with_loyalty";
+    eligibility: Record<string, unknown>;
+    validFrom: string;
+    validTo: string | null;
+    status: "draft" | "active" | "paused" | "archived";
+    regionAvailability: string[];
+    redemptionLimitGlobal: number | null;
+    redemptionLimitPerCustomer: number | null;
+};
+export type AdminPromotionV2Mirror = {
+    id: string;
+    status: "draft" | "active" | "paused" | "archived";
+};
+export type AdminPromotionSemanticBenefit = {
+    kind: "target_percentage";
+    valueBps: number;
+    reference: "catalog_list_price";
+    unitTargets: {
+        variantId: string;
+        sku: string | null;
+        referenceMinor: number;
+        targetMinor: number;
+        currency: string;
+    }[];
+} | {
+    kind: "percentage";
+    valuePercent: number;
+} | {
+    kind: "fixed_amount";
+    valueMinor: number;
+    currency: string;
+} | {
+    kind: "free_shipping";
+} | {
+    kind: "unavailable";
+    reason: "system_managed_metadata_incomplete";
+};
+export interface AdminPromotionsListResponse {
+    contractVersion: "commerce.v0";
+    promotions: AdminPromotion[];
+}
+export type AdminPromotionUpdatePayload = {
+    name?: string | undefined;
+    discountValue?: number | undefined;
+    stackingRule?: "exclusive" | "stackable_with_any" | "stackable_with_loyalty" | undefined;
+    status?: "draft" | "active" | "paused" | "archived" | undefined;
+    eligibility?: Record<string, unknown> | undefined;
+    validFrom?: string | undefined;
+    validTo?: string | null | undefined;
+    redemptionLimitGlobal?: number | null | undefined;
+    redemptionLimitPerCustomer?: number | null | undefined;
+};
+export interface AdminPromotionUpdateRequest {
+    id: string;
+    updates: AdminPromotionUpdatePayload;
+}
+export type AdminPromotionUpdateResponse = {
+    contractVersion: "commerce.v0";
+    updated: true;
+    id: string;
+};
+export type PromotionCodeCreateRequest = {
+    name: string;
+    description: string | null;
+    code: {
+        kind: "automatic";
+    } | {
+        kind: "manual";
+        value: string;
+    };
+    benefits: ({
+        lane: "product";
+        kind: "target_percentage";
+        valueBps: number;
+    } | {
+        lane: "product";
+        kind: "fixed_amount";
+        valueMinor: number;
+    } | {
+        lane: "shipping";
+        kind: "percentage";
+        valueBps: number;
+    } | {
+        lane: "shipping";
+        kind: "fixed_amount";
+        valueMinor: number;
+    } | {
+        lane: "shipping";
+        kind: "free_shipping";
+    })[];
+    scopes: ("one_time" | "subscription_initial")[];
+    validFrom: string;
+    validTo: string | null;
+    minimumReferenceMinor: number;
+    redemptionLimitGlobal: number | null;
+    redemptionLimitPerCustomer: number | null;
+    status: "draft" | "active";
+    idempotencyKey: string;
+    previewContext?: {
+        referenceProductMinor: number;
+        oneTimeProductMinor: number;
+        subscriptionProductMinor: number;
+        shippingMinor: number;
+    } | undefined;
+    previewProof?: string | undefined;
+};
+export type PromotionCodeCreateResponse = {
+    contractVersion: "commerce.v0";
+    id: string;
+    code: string;
+    status: "draft" | "active" | "paused" | "archived";
+    revision: number;
+    idempotent: boolean;
+};
+export type PromotionCodeUpdateRequest = {
+    id: string;
+    expectedRevision: number;
+    updates: {
+        status?: "draft" | "active" | "paused" | "archived" | undefined;
+        validFrom?: string | undefined;
+        validTo?: string | null | undefined;
+        redemptionLimitGlobal?: number | null | undefined;
+        redemptionLimitPerCustomer?: number | null | undefined;
+    };
+    idempotencyKey: string;
+    previewContext?: {
+        referenceProductMinor: number;
+        oneTimeProductMinor: number;
+        subscriptionProductMinor: number;
+        shippingMinor: number;
+    } | undefined;
+    previewProof?: string | undefined;
+};
+export type PromotionCodeUpdateResponse = {
+    contractVersion: "commerce.v0";
+    id: string;
+    status: "draft" | "active" | "paused" | "archived";
+    revision: number;
+    idempotent: boolean;
+};
+export type PromotionCodesListRequest = {
+    status: "draft" | "active" | "paused" | "archived" | "scheduled" | "expired" | "expired_or_archived" | "all";
+    scope: "shipping" | "one_time" | "subscription_initial" | "all" | "both";
+    limit: number;
+    q?: string | undefined;
+    cursor?: string | undefined;
+};
+export type PromotionCodeSummary = {
+    id: string;
+    code: string;
+    name: string;
+    description: string | null;
+    benefits: ({
+        lane: "product";
+        kind: "target_percentage";
+        valueBps: number;
+    } | {
+        lane: "product";
+        kind: "fixed_amount";
+        valueMinor: number;
+    } | {
+        lane: "shipping";
+        kind: "percentage";
+        valueBps: number;
+    } | {
+        lane: "shipping";
+        kind: "fixed_amount";
+        valueMinor: number;
+    } | {
+        lane: "shipping";
+        kind: "free_shipping";
+    } | {
+        lane: "product";
+        kind: "percentage";
+        valueBps: number;
+    } | {
+        lane: "shipping";
+        kind: "percentage";
+        valueBps: number;
+    } | {
+        lane: "product";
+        kind: "fixed_amount";
+        valueMinor: number;
+    } | {
+        lane: "shipping";
+        kind: "fixed_amount";
+        valueMinor: number;
+    } | {
+        lane: "product" | "shipping";
+        kind: "percentage" | "fixed_amount";
+        validationState: "unsupported_legacy_value";
+    })[];
+    promotionEngineVersion: "promotion-engine.v1" | "promotion-engine.v2";
+    scopes: ("one_time" | "subscription_initial")[];
+    status: "draft" | "active" | "paused" | "archived";
+    effectiveStatus: "draft" | "active" | "paused" | "archived" | "scheduled" | "expired";
+    validFrom: string;
+    validTo: string | null;
+    minimumReferenceMinor: number;
+    redemptionLimitGlobal: number | null;
+    redemptionLimitPerCustomer: number | null;
+    redeemedCount: number;
+    reservedCount: number;
+    remainingCount: number | null;
+    createdAt: string;
+    revision: number;
+};
+export type PromotionCodesListResponse = {
+    contractVersion: "commerce.v0";
+    codes: {
+        id: string;
+        code: string;
+        name: string;
+        description: string | null;
+        benefits: ({
+            lane: "product";
+            kind: "target_percentage";
+            valueBps: number;
+        } | {
+            lane: "product";
+            kind: "fixed_amount";
+            valueMinor: number;
+        } | {
+            lane: "shipping";
+            kind: "percentage";
+            valueBps: number;
+        } | {
+            lane: "shipping";
+            kind: "fixed_amount";
+            valueMinor: number;
+        } | {
+            lane: "shipping";
+            kind: "free_shipping";
+        } | {
+            lane: "product";
+            kind: "percentage";
+            valueBps: number;
+        } | {
+            lane: "shipping";
+            kind: "percentage";
+            valueBps: number;
+        } | {
+            lane: "product";
+            kind: "fixed_amount";
+            valueMinor: number;
+        } | {
+            lane: "shipping";
+            kind: "fixed_amount";
+            valueMinor: number;
+        } | {
+            lane: "product" | "shipping";
+            kind: "percentage" | "fixed_amount";
+            validationState: "unsupported_legacy_value";
+        })[];
+        promotionEngineVersion: "promotion-engine.v1" | "promotion-engine.v2";
+        scopes: ("one_time" | "subscription_initial")[];
+        status: "draft" | "active" | "paused" | "archived";
+        effectiveStatus: "draft" | "active" | "paused" | "archived" | "scheduled" | "expired";
+        validFrom: string;
+        validTo: string | null;
+        minimumReferenceMinor: number;
+        redemptionLimitGlobal: number | null;
+        redemptionLimitPerCustomer: number | null;
+        redeemedCount: number;
+        reservedCount: number;
+        remainingCount: number | null;
+        createdAt: string;
+        revision: number;
+    }[];
+    nextCursor: string | null;
+    capabilities: {
+        mutationsEnabled: boolean;
+    };
+    legacyCompatibility: {
+        ready: boolean;
+        unprojectedCount: number;
+        collisionGroupCount: number;
+    };
+};
+export type PromotionStatus = "draft" | "active" | "paused" | "archived";
+export interface AdminSubscriptionBandEntry {
+    variantId: string;
+    sku: string | null;
+    oneTimeMinor: number;
+    subscriptionMinor: number;
+    percent: number;
+}

package/src/promotions/index.ts

@@ -0,0 +1,22 @@
+export * from "./quotePromotionV2.js";
+export * from "./quoteAutomaticPromotions.js";
+export * from "./quotePromoDiscounts.js";
+export * from "./quotePromotionCodeAdjustments.js";
+export * from "./promotionBenefitDefinition.js";
+export * from "./promoDataPort.js";
+export * from "./promotionCodeQuotePort.js";
+export * from "./promotionCodePreview.js";
+export * from "./promotionQuoteBinding.js";
+export * from "./promotionQuoteAcceptance.js";
+export * from "./promotionAcceptanceTelemetry.js";
+export * from "./adminBindings.js";
+export * from "./adminPromotionsContracts.js";
+export * from "./adminPromotionCodesContracts.js";
+export * from "./adminPromotionsHandler.js";
+export * from "./adminPromotionCodesHandler.js";
+export * from "./adminPromotionsDataPort.js";
+export * from "./adminPromotionCodesDataPort.js";
+export * from "./promotionClaimSweepPort.js";
+export * from "./promotionClaims.js";
+export * from "./sql.js";
+export type { PromotionStatus, AdminPromotion, AdminPromotionV2Mirror, AdminPromotionSemanticBenefit, AdminPromotionsListResponse, AdminPromotionUpdatePayload, AdminPromotionUpdateRequest, AdminPromotionUpdateResponse } from "./contracts/index.js";

package/src/promotions/promoDataPort.ts

@@ -0,0 +1,65 @@
+import type { PromotionRow } from "@openlup/core/promo";
+
+/**
+ * Read-only data access for promo evaluation in the commerce quote.
+ *
+ * Deliberately thin: `listActivePromotions` returns the active candidate rows and
+ * leaves ALL eligibility filtering (region, validity window, first_purchase,
+ * cart_mode, coupon-code match, stacking) to the pure `evaluatePromos` evaluator —
+ * the single source of truth shared by preview and finalize. `countPaidOrders`
+ * supplies the server-authoritative `client_orders_count` used for `first_purchase`
+ * eligibility; it is resolved from the authenticated clientId (never the client
+ * request body), so a discount cannot be forged by spoofing the count.
+ */
+export interface PromotionRedemptionCount {
+  global: number;
+  perCustomer: number;
+}
+
+/** Paid-order counts split by order mode, for per-mode "first order" eligibility. */
+export interface PaidOrdersByMode {
+  /** Paid `one_time` (bundle) orders. */
+  oneTime: number;
+  /** Paid `subscription_cycle` orders (initial activation + every renewal). */
+  subscription: number;
+}
+
+export interface CommercePromoDataPort {
+  listActivePromotions(): Promise<PromotionRow[]>;
+  countPaidOrders(clientId: string): Promise<number>;
+  /**
+   * Paid-order counts split by `commerce_orders.mode`. Drives `first_subscription_purchase`
+   * (subscription===0) and `first_onetime_purchase` (oneTime===0) independently, so a
+   * prior bundle never blocks a first subscription and vice versa. Server-authoritative
+   * (resolved from the clientId, never client input).
+   */
+  countPaidOrdersByMode(clientId: string): Promise<PaidOrdersByMode>;
+  /**
+   * Per-promotion redemption counts (global + this client's), keyed by promotion id,
+   * for the quote's cap pre-filter. `clientId` null ⇒ perCustomer is 0 (an anonymous
+   * preview cannot resolve a per-customer cap; checkout re-evaluates with the real client).
+   */
+  redemptionCounts(clientId: string | null): Promise<Map<string, PromotionRedemptionCount>>;
+  /**
+   * True when this device's first-party visitor id already has a PAID first-order redemption. Denies
+   * first-order promos to a device that has already completed and paid a first order, even
+   * under a fresh email/client. `null`/empty visitorId ⇒ false (no guard).
+   */
+  deviceFirstOrderRedeemed(visitorId: string | null): Promise<boolean>;
+}
+
+export function promotionRedemptionMap(
+  value: unknown,
+): Map<string, PromotionRedemptionCount> {
+  const rows = Array.isArray(value) ? (value as Array<Record<string, unknown>>) : [];
+  const map = new Map<string, PromotionRedemptionCount>();
+  for (const row of rows) {
+    const id = typeof row.promotion_id === "string" ? row.promotion_id : null;
+    if (!id) continue;
+    map.set(id, {
+      global: Number(row.global_count ?? 0),
+      perCustomer: Number(row.per_customer_count ?? 0),
+    });
+  }
+  return map;
+}

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 };
+}