@openlup/platform 0.17.0 → 0.18.0

package/dist/pricing/ports.d.ts

@@ -0,0 +1,13 @@
+import type { CommercePriceAuthorityQuery, CommercePriceAuthorityResult, CommercePriceAuthorityRefusal } from "./contracts/index.js";
+/** Named refusal from the strict current-money authority. */
+export declare class CommercePriceAuthorityError extends Error {
+    readonly code: CommercePriceAuthorityRefusal;
+    constructor(code: CommercePriceAuthorityRefusal);
+}
+/**
+ * Resolves one current, exact base anchor and either a validated policy-derived
+ * subscription amount or the narrowly permitted pre-cutover legacy observation.
+ */
+export interface CommercePriceAuthorityPort {
+    resolvePrice(query: CommercePriceAuthorityQuery): Promise<CommercePriceAuthorityResult>;
+}

package/dist/pricing/ports.js

@@ -0,0 +1,9 @@
+/** Named refusal from the strict current-money authority. */
+export class CommercePriceAuthorityError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "CommercePriceAuthorityError";
+    }
+}

package/dist/pricing/pricingPolicyToken.d.ts

@@ -0,0 +1,39 @@
+import { type OfferPolicyVersion, type PromotionEngineVersion } from "./contracts/index.js";
+export interface PricingPolicyTokenPayload {
+    assignmentKeyHash: string;
+    issuedAtMs: number;
+    expiresAtMs: number;
+    offerPolicyVersion: OfferPolicyVersion;
+    promotionEngineVersion: PromotionEngineVersion;
+}
+interface CreateTokenInput extends Omit<PricingPolicyTokenPayload, "assignmentKeyHash"> {
+    assignmentKey: string;
+}
+export declare function createPricingPolicyToken(input: CreateTokenInput, secret: string): string;
+export declare function verifyPricingPolicyToken(token: string, secret: string, nowMs?: number): PricingPolicyTokenPayload | null;
+export declare function resolvePricingPolicy(input: {
+    assignmentKey?: string;
+    capability?: string;
+    token?: string;
+    secret: string;
+    v2Enabled: boolean;
+    rolloutBps: number;
+    nowMs?: number;
+    ttlMs?: number;
+}): {
+    pricingPolicyToken: string | undefined;
+    assignmentKeyHash: string;
+    issuedAtMs: number;
+    expiresAtMs: number;
+    offerPolicyVersion: OfferPolicyVersion;
+    promotionEngineVersion: PromotionEngineVersion;
+} | {
+    offerPolicyVersion: "commerce.offer-policy.v1" | "commerce.offer-policy.v2";
+    promotionEngineVersion: "promotion-engine.v2" | "promotion-engine.v1";
+    pricingPolicyToken?: undefined;
+} | {
+    offerPolicyVersion: "commerce.offer-policy.v1" | "commerce.offer-policy.v2";
+    promotionEngineVersion: "promotion-engine.v2" | "promotion-engine.v1";
+    pricingPolicyToken: string;
+};
+export {};

package/dist/pricing/pricingPolicyToken.js

@@ -0,0 +1,84 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { OFFER_POLICY_V1, OFFER_POLICY_V2, OFFER_POLICY_V2_CAPABILITY, PROMOTION_ENGINE_V1, PROMOTION_ENGINE_V2, } from "./contracts/index.js";
+const TOKEN_PREFIX = "pp1";
+// Rollout contract: an already-started checkout keeps its assigned policy for
+// at least the 72-hour compatibility window, including during a rollback.
+const DEFAULT_TTL_MS = 72 * 60 * 60 * 1_000;
+export function createPricingPolicyToken(input, secret) {
+    assertSecret(secret);
+    const payload = {
+        assignmentKeyHash: assignmentHash(input.assignmentKey, secret),
+        issuedAtMs: input.issuedAtMs,
+        expiresAtMs: input.expiresAtMs,
+        offerPolicyVersion: input.offerPolicyVersion,
+        promotionEngineVersion: input.promotionEngineVersion,
+    };
+    const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+    return `${TOKEN_PREFIX}.${encoded}.${sign(encoded, secret)}`;
+}
+export function verifyPricingPolicyToken(token, secret, nowMs = Date.now()) {
+    if (secret.trim().length < 32)
+        return null;
+    const [prefix, encoded, signature, extra] = token.split(".");
+    if (prefix !== TOKEN_PREFIX || !encoded || !signature || extra)
+        return null;
+    if (!safeEqual(signature, sign(encoded, secret)))
+        return null;
+    try {
+        const value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        const pairIsValid = (value.offerPolicyVersion === OFFER_POLICY_V1 && value.promotionEngineVersion === PROMOTION_ENGINE_V1) ||
+            (value.offerPolicyVersion === OFFER_POLICY_V2 && value.promotionEngineVersion === PROMOTION_ENGINE_V2);
+        if (!pairIsValid || typeof value.assignmentKeyHash !== "string" ||
+            typeof value.issuedAtMs !== "number" || typeof value.expiresAtMs !== "number" ||
+            value.issuedAtMs > nowMs || value.expiresAtMs < nowMs)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolvePricingPolicy(input) {
+    const nowMs = input.nowMs ?? Date.now();
+    const existing = input.token ? verifyPricingPolicyToken(input.token, input.secret, nowMs) : null;
+    const boundExisting = existing && input.assignmentKey &&
+        existing.assignmentKeyHash === assignmentHash(input.assignmentKey, input.secret)
+        ? existing : null;
+    if (boundExisting)
+        return { ...boundExisting, pricingPolicyToken: input.token };
+    const eligible = input.v2Enabled && input.capability === OFFER_POLICY_V2_CAPABILITY &&
+        Boolean(input.assignmentKey) && input.secret.trim().length >= 32;
+    const rolloutBps = Math.max(0, Math.min(10_000, Math.trunc(input.rolloutBps)));
+    const v2 = eligible && cohort(input.assignmentKey, input.secret) < rolloutBps;
+    const offerPolicyVersion = v2 ? OFFER_POLICY_V2 : OFFER_POLICY_V1;
+    const promotionEngineVersion = v2 ? PROMOTION_ENGINE_V2 : PROMOTION_ENGINE_V1;
+    if (!eligible)
+        return { offerPolicyVersion, promotionEngineVersion };
+    return {
+        offerPolicyVersion,
+        promotionEngineVersion,
+        pricingPolicyToken: createPricingPolicyToken({
+            assignmentKey: input.assignmentKey, issuedAtMs: nowMs,
+            expiresAtMs: nowMs + (input.ttlMs ?? DEFAULT_TTL_MS),
+            offerPolicyVersion, promotionEngineVersion,
+        }, input.secret),
+    };
+}
+function assignmentHash(value, secret) {
+    return createHmac("sha256", secret).update(`pricing-policy-identity:${value}`).digest("hex");
+}
+function cohort(value, secret) {
+    return Number.parseInt(createHmac("sha256", secret).update(`pricing-policy-cohort:${value}`).digest("hex").slice(0, 8), 16) % 10_000;
+}
+function sign(value, secret) {
+    return createHmac("sha256", secret).update(`${TOKEN_PREFIX}.${value}`).digest("base64url");
+}
+function safeEqual(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function assertSecret(secret) {
+    if (secret.trim().length < 32)
+        throw new Error("pricing_policy_token_secret_too_short");
+}

package/dist/pricing/quoteAcquisitionTerms.d.ts

@@ -0,0 +1,2 @@
+import type { AcquisitionTermsExpectation, ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+export declare function acquisitionExpectationChanged(expected: AcquisitionTermsExpectation | undefined, actual: ResolvedAcquisitionTerms | undefined): boolean;

package/dist/pricing/quoteAcquisitionTerms.js

@@ -0,0 +1,4 @@
+export function acquisitionExpectationChanged(expected, actual) {
+    return expected !== undefined && (expected.revision !== actual?.revision ||
+        expected.delivery2DiscountBps !== actual?.delivery2DiscountBps);
+}

package/dist/pricing/quoteCodeRejectionDetails.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare const quoteCodeRejectionDetailSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    code: z.ZodString;
+    reason: z.ZodLiteral<"scope_not_applicable">;
+    allowedScopes: z.ZodArray<z.ZodEnum<{
+        one_time: "one_time";
+        subscription_initial: "subscription_initial";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    code: z.ZodString;
+    reason: z.ZodLiteral<"minimum_not_met">;
+    minimumReferenceMinor: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    code: z.ZodString;
+    reason: z.ZodLiteral<"not_yet_active">;
+    validFrom: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    code: z.ZodString;
+    reason: z.ZodLiteral<"global_limit_reached">;
+}, z.core.$strict>], "reason">;

package/dist/pricing/quoteCodeRejectionDetails.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export const quoteCodeRejectionDetailSchema = z.discriminatedUnion("reason", [
+    z.object({
+        code: z.string().trim().min(1).max(80),
+        reason: z.literal("scope_not_applicable"),
+        allowedScopes: z.array(z.enum(["one_time", "subscription_initial"])).min(1).max(2),
+    }).strict(),
+    z.object({
+        code: z.string().trim().min(1).max(80),
+        reason: z.literal("minimum_not_met"),
+        minimumReferenceMinor: z.number().int().nonnegative(),
+    }).strict(),
+    z.object({
+        code: z.string().trim().min(1).max(80),
+        reason: z.literal("not_yet_active"),
+        validFrom: z.string().datetime({ offset: true }),
+    }).strict(),
+    z.object({
+        code: z.string().trim().min(1).max(80),
+        reason: z.literal("global_limit_reached"),
+    }).strict(),
+]);

package/dist/pricing/quotePorts.d.ts

@@ -0,0 +1,30 @@
+import type { CreateQuoteRequest, CreateQuoteResponse } from "./contracts/quote.js";
+import type { PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+/**
+ * Server-resolved options for promo evaluation. Passed OUT-OF-BAND by the caller
+ * (orchestration -> provisioned.clientId; preview -> session/null) — NEVER sourced
+ * from the client request body — so `first_purchase` eligibility cannot be forged.
+ */
+export interface CreateQuoteOptions {
+    clientId?: string | null;
+    pricingPolicy?: PricingPolicySnapshot;
+}
+export interface CommerceQuotePort<Request = CreateQuoteRequest, Response = CreateQuoteResponse> {
+    createQuote(request: Request, options?: CreateQuoteOptions): Promise<Response>;
+    createServerAuthoritativeQuote?(request: Request, options?: CreateQuoteOptions): Promise<Response>;
+}
+export interface CommerceQuoteSnapshotVerifierPort<Response = CreateQuoteResponse> {
+    verifyQuoteSnapshot(snapshot: Response): Promise<Response | void>;
+}
+export type CommerceQuoteSnapshotErrorCode = "QUOTE_SNAPSHOT_MISMATCH";
+export declare class CommerceQuoteSnapshotError extends Error {
+    readonly code: CommerceQuoteSnapshotErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: CommerceQuoteSnapshotErrorCode, message: string, details?: Record<string, unknown>);
+}
+export type CommerceQuoteErrorCode = "UNKNOWN_SKU" | "PRICE_NOT_CONFIGURED" | "UNSUPPORTED_TAX_PROFILE" | "PRICING_INVARIANT_VIOLATION";
+export declare class CommerceQuoteError extends Error {
+    readonly code: CommerceQuoteErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: CommerceQuoteErrorCode, message: string, details?: Record<string, unknown>);
+}

package/dist/pricing/quotePorts.js

@@ -0,0 +1,20 @@
+export class CommerceQuoteSnapshotError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "CommerceQuoteSnapshotError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export class CommerceQuoteError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "CommerceQuoteError";
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/pricing/quotePrimitives.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/** Currency acceptance belongs to the host's settlement profile. */
+export declare function createCommerceQuotePrimitives(commerceCurrencySchema: z.ZodType<string>): {
+    commerceCurrencySchema: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    commerceTaxCountrySchema: z.ZodString;
+    commerceTaxCategorySchema: z.ZodString;
+    commerceTaxLegalBasisSchema: z.ZodString;
+    commerceSkuSchema: z.ZodString;
+    commerceMoneySchema: z.ZodObject<{
+        amountMinor: z.ZodNumber;
+        currency: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    }, z.core.$strip>;
+};

package/dist/pricing/quotePrimitives.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/** Currency acceptance belongs to the host's settlement profile. */
+export function createCommerceQuotePrimitives(commerceCurrencySchema) {
+    const commerceTaxCountrySchema = z.string().trim().regex(/^[A-Z]{2}$/);
+    const commerceTaxCategorySchema = z.string().trim().regex(/^[a-z][a-z0-9_]*$/);
+    const commerceTaxLegalBasisSchema = z.string().trim().min(1).max(200);
+    const commerceSkuSchema = z
+        .string()
+        .trim()
+        .min(1)
+        .max(128)
+        .regex(/^[a-zA-Z0-9._:-]+$/);
+    const commerceMoneySchema = z.object({
+        amountMinor: z.number().int().nonnegative(),
+        currency: commerceCurrencySchema,
+    });
+    return { commerceCurrencySchema, commerceTaxCountrySchema, commerceTaxCategorySchema, commerceTaxLegalBasisSchema, commerceSkuSchema, commerceMoneySchema };
+}

package/dist/pricing/quotePromotionEvidence.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { QuotePromotionEvidence } from "./contracts/evidence.js";
+export declare const quoteDiscountSchema: z.ZodObject<{
+    promotionId: z.ZodString;
+    code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    label: z.ZodOptional<z.ZodString>;
+    appliesTo: z.ZodEnum<{
+        line: "line";
+        shipping: "shipping";
+        order_total: "order_total";
+    }>;
+    amountOffMinor: z.ZodNumber;
+    reasonCode: z.ZodString;
+    customerSemantic: z.ZodOptional<z.ZodEnum<{
+        first_purchase_10: "first_purchase_10";
+        first_subscription_50: "first_subscription_50";
+        bundle_5: "bundle_5";
+    }>>;
+    promotionEngineVersion: z.ZodOptional<z.ZodLiteral<"promotion-engine.v2">>;
+    promotionCodeId: z.ZodOptional<z.ZodString>;
+    promotionCodeRevision: z.ZodOptional<z.ZodNumber>;
+    promotionDefinitionFingerprint: z.ZodOptional<z.ZodString>;
+    promotionCodeScopes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        one_time: "one_time";
+        subscription_initial: "subscription_initial";
+    }>>>;
+    promotionMinimumReferenceMinor: z.ZodOptional<z.ZodNumber>;
+    promotionCodeValidTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    promotionBenefitKind: z.ZodOptional<z.ZodEnum<{
+        target_percentage: "target_percentage";
+        percentage: "percentage";
+        fixed_amount: "fixed_amount";
+        free_shipping: "free_shipping";
+    }>>;
+    promotionBenefitValueBps: z.ZodOptional<z.ZodNumber>;
+    promotionBenefitValueMinor: z.ZodOptional<z.ZodNumber>;
+    floorApplied: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare function hasValidV2PromotionEvidence(discount: QuotePromotionEvidence): boolean;

package/dist/pricing/quotePromotionEvidence.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+const uuidSchema = z.string().uuid();
+export const quoteDiscountSchema = z
+    .object({
+    promotionId: z.string().trim().min(1).max(120),
+    code: z.string().trim().min(1).max(80).nullable().optional(),
+    label: z.string().trim().min(1).max(200).optional(),
+    appliesTo: z.enum(["order_total", "line", "shipping"]),
+    amountOffMinor: z.number().int().positive(),
+    reasonCode: z.string().trim().min(1).max(120),
+    customerSemantic: z.enum([
+        "first_purchase_10", "first_subscription_50", "bundle_5",
+    ]).optional(),
+    promotionEngineVersion: z.literal("promotion-engine.v2").optional(),
+    promotionCodeId: z.string().uuid().optional(),
+    promotionCodeRevision: z.number().int().positive().optional(),
+    promotionDefinitionFingerprint: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    promotionCodeScopes: z.array(z.enum(["one_time", "subscription_initial"])).min(1).max(2).optional(),
+    promotionMinimumReferenceMinor: z.number().int().nonnegative().optional(),
+    promotionCodeValidTo: z.string().datetime({ offset: true }).nullable().optional(),
+    promotionBenefitKind: z.enum([
+        "target_percentage", "percentage", "fixed_amount", "free_shipping",
+    ]).optional(),
+    promotionBenefitValueBps: z.number().int().min(1).max(9_999).optional(),
+    promotionBenefitValueMinor: z.number().int().positive().optional(),
+    floorApplied: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((discount, context) => {
+    if (!hasValidV2PromotionEvidence(discount)) {
+        context.addIssue({ code: "custom", message: "v2 promotion discount evidence is incomplete" });
+    }
+});
+export function hasValidV2PromotionEvidence(discount) {
+    const carriesEvidence = discount.promotionEngineVersion !== undefined ||
+        discount.promotionCodeId !== undefined ||
+        discount.promotionCodeRevision !== undefined ||
+        discount.promotionDefinitionFingerprint !== undefined ||
+        discount.promotionCodeScopes !== undefined ||
+        discount.promotionMinimumReferenceMinor !== undefined ||
+        discount.promotionCodeValidTo !== undefined ||
+        discount.promotionBenefitKind !== undefined ||
+        discount.promotionBenefitValueBps !== undefined ||
+        discount.promotionBenefitValueMinor !== undefined || discount.floorApplied !== undefined;
+    return !carriesEvidence || (discount.promotionEngineVersion === "promotion-engine.v2" &&
+        discount.reasonCode === "promotion_code_v2" &&
+        Boolean(discount.code) &&
+        uuidSchema.safeParse(discount.promotionCodeId).success &&
+        discount.promotionCodeRevision !== undefined &&
+        /^[0-9a-f]{64}$/.test(discount.promotionDefinitionFingerprint ?? "") &&
+        validScopes(discount.promotionCodeScopes) &&
+        (discount.promotionMinimumReferenceMinor ?? -1) >= 0 &&
+        discount.promotionCodeValidTo !== undefined &&
+        discount.promotionBenefitKind !== undefined &&
+        benefitValueMatchesKind(discount) &&
+        discount.floorApplied !== undefined &&
+        uuidSchema.safeParse(discount.promotionId).success);
+}
+function validScopes(scopes) {
+    return Boolean(scopes?.length && scopes.length <= 2 &&
+        new Set(scopes).size === scopes.length &&
+        scopes.every((scope) => scope === "one_time" || scope === "subscription_initial"));
+}
+function benefitValueMatchesKind(discount) {
+    const percentage = discount.promotionBenefitKind === "target_percentage" ||
+        discount.promotionBenefitKind === "percentage";
+    return percentage === (discount.promotionBenefitValueBps !== undefined) &&
+        (discount.promotionBenefitKind === "fixed_amount") ===
+            (discount.promotionBenefitValueMinor !== undefined) &&
+        (discount.promotionBenefitKind !== "free_shipping" ||
+            (discount.promotionBenefitValueBps === undefined &&
+                discount.promotionBenefitValueMinor === undefined));
+}