@frak-labs/core-sdk 1.1.5 → 1.1.6

package/src/rewards/example.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import type { EstimatedReward } from "../types";
+import {
+    buildPercentageExample,
+    buildTierExample,
+    pickFlatBasket,
+    pickTierBasket,
+} from "./example";
+
+type PercentageReward = Extract<EstimatedReward, { payoutType: "percentage" }>;
+
+function percentage(
+    percent: number,
+    bounds?: { min?: number; max?: number }
+): PercentageReward {
+    const toAmount = (eur: number) => ({
+        amount: eur,
+        eurAmount: eur,
+        usdAmount: eur,
+        gbpAmount: eur,
+    });
+    return {
+        payoutType: "percentage",
+        percent,
+        percentOf: "purchase_amount",
+        minAmount: bounds?.min != null ? toAmount(bounds.min) : undefined,
+        maxAmount: bounds?.max != null ? toAmount(bounds.max) : undefined,
+    };
+}
+
+describe("pickFlatBasket", () => {
+    it("defaults to the reference basket of 100", () => {
+        expect(pickFlatBasket(undefined)).toBe(100);
+        expect(pickFlatBasket(40)).toBe(100);
+    });
+
+    it("uses the minimum purchase when it exceeds the reference", () => {
+        expect(pickFlatBasket(150)).toBe(150);
+    });
+});
+
+describe("pickTierBasket", () => {
+    it("uses the reference when it fits the tier range", () => {
+        expect(pickTierBasket(80, 200)).toBe(100);
+    });
+
+    it("uses the lower bound for an open-ended tier", () => {
+        expect(pickTierBasket(80, undefined)).toBe(80);
+    });
+
+    it("picks a round number inside a bounded tier excluding the reference", () => {
+        expect(pickTierBasket(0, 30)).toBe(20);
+        expect(pickTierBasket(30, 80)).toBe(60);
+    });
+});
+
+describe("buildPercentageExample", () => {
+    it("computes percent of the basket", () => {
+        const example = buildPercentageExample(percentage(8), undefined);
+        expect(example?.basket).toBe(100);
+        expect(example?.reward).toBeCloseTo(8);
+    });
+
+    it("clamps the reward to the configured max amount", () => {
+        const example = buildPercentageExample(
+            percentage(8, { max: 4.8 }),
+            undefined
+        );
+        expect(example?.basket).toBe(100);
+        expect(example?.reward).toBeCloseTo(4.8);
+    });
+
+    it("uses the minimum purchase as the basket when higher", () => {
+        const example = buildPercentageExample(percentage(5), 200);
+        expect(example?.basket).toBe(200);
+        expect(example?.reward).toBeCloseTo(10);
+    });
+});
+
+describe("buildTierExample", () => {
+    it("computes percent of the open tier lower bound", () => {
+        const example = buildTierExample(12, 80, undefined);
+        expect(example?.basket).toBe(80);
+        expect(example?.reward).toBeCloseTo(9.6);
+    });
+
+    it("computes percent of a round basket inside a bounded tier", () => {
+        const example = buildTierExample(5, 30, 80);
+        expect(example?.basket).toBe(60);
+        expect(example?.reward).toBeCloseTo(3);
+    });
+});

package/src/rewards/example.ts

@@ -0,0 +1,57 @@
+import type { EstimatedReward } from "../types";
+
+type PercentageReward = Extract<EstimatedReward, { payoutType: "percentage" }>;
+
+// Reference order total used to turn a "% of basket" reward into a concrete
+// example amount. The campaign's minimum purchase overrides it when higher.
+const REFERENCE_BASKET = 100;
+
+export type RewardExample = {
+    basket: number;
+    reward: number;
+};
+
+function roundWithinRange(min: number, max: number): number {
+    const rounded = Math.round((min + max) / 2 / 10) * 10;
+    return Math.min(max, Math.max(min, rounded));
+}
+
+export function pickFlatBasket(minPurchase: number | undefined): number {
+    return Math.max(REFERENCE_BASKET, minPurchase ?? 0);
+}
+
+// Basket for a percentage tier: the reference when it sits inside the tier
+// range, a round number within the range otherwise, or the lower bound for an
+// open-ended (uncapped) top tier.
+export function pickTierBasket(
+    minValue: number,
+    maxValue: number | undefined
+): number {
+    if (maxValue == null) return minValue;
+    if (minValue <= REFERENCE_BASKET && REFERENCE_BASKET <= maxValue) {
+        return REFERENCE_BASKET;
+    }
+    return roundWithinRange(minValue, maxValue);
+}
+
+export function buildPercentageExample(
+    reward: PercentageReward,
+    minPurchase: number | undefined
+): RewardExample | undefined {
+    const basket = pickFlatBasket(minPurchase);
+    if (basket <= 0) return undefined;
+    let amount = (reward.percent / 100) * basket;
+    if (reward.minAmount) amount = Math.max(amount, reward.minAmount.eurAmount);
+    if (reward.maxAmount) amount = Math.min(amount, reward.maxAmount.eurAmount);
+    return { basket, reward: amount };
+}
+
+export function buildTierExample(
+    percent: number,
+    minValue: number,
+    maxValue: number | undefined
+): RewardExample | undefined {
+    const basket = pickTierBasket(minValue, maxValue);
+    if (basket <= 0) return undefined;
+    return { basket, reward: (percent / 100) * basket };
+}

package/src/rewards/format.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+import type { EstimatedReward } from "../types";
+import {
+    applyRewardPlaceholder,
+    formatEstimatedReward,
+    formatRewardOrHide,
+} from "./format";
+
+const amount = (eur: number) => ({
+    amount: eur,
+    eurAmount: eur,
+    usdAmount: eur,
+    gbpAmount: eur,
+});
+
+describe("formatEstimatedReward", () => {
+    it("formats a fixed reward in the default currency, rounded", () => {
+        const reward: EstimatedReward = {
+            payoutType: "fixed",
+            amount: amount(5.4),
+        };
+        // Intl renders a narrow no-break space before "€" — assert content.
+        const formatted = formatEstimatedReward(reward);
+        expect(formatted).toContain("5");
+        expect(formatted).not.toContain("6");
+        expect(formatted).toContain("€");
+    });
+
+    it("renders a percentage reward as a percent string (never a basket amount)", () => {
+        const reward: EstimatedReward = {
+            payoutType: "percentage",
+            percent: 10,
+            percentOf: "purchase_amount",
+            maxAmount: amount(50),
+        };
+        expect(formatEstimatedReward(reward)).toBe("10 %");
+    });
+
+    it("uses the richest token tier for a tiered reward", () => {
+        const reward: EstimatedReward = {
+            payoutType: "tiered",
+            tierField: "purchase.amount",
+            tiers: [
+                { minValue: 0, maxValue: 50, amount: amount(2) },
+                { minValue: 50, amount: amount(8) },
+            ],
+        };
+        const formatted = formatEstimatedReward(reward);
+        expect(formatted).toContain("8");
+        expect(formatted).toContain("€");
+    });
+
+    it("falls back to the max percent when tiers carry no token amount", () => {
+        const reward: EstimatedReward = {
+            payoutType: "tiered",
+            tierField: "purchase.amount",
+            tiers: [
+                { minValue: 0, maxValue: 50, percent: 5 },
+                { minValue: 50, percent: 12 },
+            ],
+        };
+        expect(formatEstimatedReward(reward)).toBe("12 %");
+    });
+
+    it("respects the requested currency", () => {
+        const reward: EstimatedReward = {
+            payoutType: "fixed",
+            amount: amount(5),
+        };
+        const formatted = formatEstimatedReward(reward, "usd");
+        expect(formatted).toContain("5");
+        expect(formatted).toContain("$");
+    });
+});
+
+describe("formatRewardOrHide", () => {
+    it("returns undefined for a missing reward", () => {
+        expect(formatRewardOrHide(undefined)).toBeUndefined();
+    });
+
+    it("formats a fixed reward that carries money value", () => {
+        const formatted = formatRewardOrHide({
+            payoutType: "fixed",
+            amount: amount(5),
+        });
+        expect(formatted).toContain("5");
+        expect(formatted).toContain("€");
+    });
+
+    it("hides a fixed reward with no money value", () => {
+        expect(
+            formatRewardOrHide({ payoutType: "fixed", amount: amount(0) })
+        ).toBeUndefined();
+    });
+
+    it("always shows a capped percentage as a percent string", () => {
+        expect(
+            formatRewardOrHide({
+                payoutType: "percentage",
+                percent: 10,
+                percentOf: "purchase_amount",
+                maxAmount: amount(50),
+            })
+        ).toBe("10 %");
+    });
+
+    it("shows an uncapped percentage as a percent string (no money value)", () => {
+        expect(
+            formatRewardOrHide({
+                payoutType: "percentage",
+                percent: 8,
+                percentOf: "purchase_amount",
+            })
+        ).toBe("8 %");
+    });
+
+    it("shows a percent-only tiered reward instead of hiding it", () => {
+        expect(
+            formatRewardOrHide({
+                payoutType: "tiered",
+                tierField: "purchase.amount",
+                tiers: [
+                    { minValue: 0, maxValue: 50, percent: 5 },
+                    { minValue: 50, percent: 12 },
+                ],
+            })
+        ).toBe("12 %");
+    });
+});
+
+describe("applyRewardPlaceholder", () => {
+    it("substitutes the reward into the placeholder", () => {
+        expect(applyRewardPlaceholder("Earn {REWARD} now", "5 €")).toBe(
+            "Earn 5 € now"
+        );
+    });
+
+    it("strips the placeholder when no reward is provided", () => {
+        expect(applyRewardPlaceholder("Earn {REWARD} now", undefined)).toBe(
+            "Earn  now"
+        );
+    });
+});

package/src/rewards/format.ts

@@ -0,0 +1,81 @@
+import type { Currency, EstimatedReward } from "../types";
+import { formatAmount } from "../utils/format/formatAmount";
+import { getCurrencyAmountKey } from "../utils/format/getCurrencyAmountKey";
+import { getSupportedCurrency } from "../utils/format/getSupportedCurrency";
+import { getRewardRank, getRewardValue, maxRewardPercent } from "./value";
+
+/**
+ * Format an {@link EstimatedReward} into a human-readable string.
+ *
+ * - `fixed`      → e.g. `"5 €"`
+ * - `percentage` → e.g. `"10 %"`
+ * - `tiered`     → the richest tier: max token amount (e.g. `"50 €"`) or, when
+ *                  tiers only carry percentages, the max percent (e.g. `"10 %"`)
+ *
+ * Percentages are always rendered as a `"X %"` string: the backend never sends
+ * a reference basket, so the reward cannot be resolved to a concrete amount
+ * here. Callers that need a worked example use the `example` helpers instead.
+ */
+export function formatEstimatedReward(
+    reward: EstimatedReward,
+    currency?: Currency
+): string {
+    const supportedCurrency = getSupportedCurrency(currency);
+    const key = getCurrencyAmountKey(supportedCurrency);
+
+    switch (reward.payoutType) {
+        case "fixed":
+            return formatAmount(
+                Math.round(reward.amount[key]),
+                supportedCurrency
+            );
+
+        case "percentage":
+            return `${reward.percent} %`;
+
+        case "tiered": {
+            const maxAmount = getRewardValue(reward, key);
+            if (maxAmount > 0) {
+                return formatAmount(Math.round(maxAmount), supportedCurrency);
+            }
+            const maxPercent = maxRewardPercent(reward);
+            if (maxPercent > 0) {
+                return `${maxPercent} %`;
+            }
+            return formatAmount(0, supportedCurrency);
+        }
+    }
+}
+
+/**
+ * Format a reward for display, or return `undefined` when it is not worth
+ * advertising. Callers rely on `undefined` to hide a badge / fall back to
+ * other copy.
+ *
+ * A reward is hidden only when it carries no displayable value — a `fixed` or
+ * `tiered` reward whose money value is `0` (e.g. an unknown token price). An
+ * uncapped percentage always renders as `"X %"`, since the percent itself is
+ * meaningful even without a money value.
+ */
+export function formatRewardOrHide(
+    reward: EstimatedReward | undefined,
+    currency?: Currency
+): string | undefined {
+    if (!reward) return undefined;
+    const key = getCurrencyAmountKey(getSupportedCurrency(currency));
+    if (getRewardRank(reward, key) <= 0) return undefined;
+    return formatEstimatedReward(reward, currency);
+}
+
+/**
+ * Replace the `{REWARD}` placeholder in a text string with a reward value.
+ * If no reward is provided, returns the text with `{REWARD}` stripped.
+ */
+export function applyRewardPlaceholder(
+    text: string,
+    reward: string | undefined
+): string {
+    return reward
+        ? text.replaceAll("{REWARD}", reward)
+        : text.replaceAll("{REWARD}", "");
+}

package/src/rewards/index.ts

@@ -0,0 +1,29 @@
+// Framework-agnostic reward display logic shared across the SDK, listener,
+// wallet and wallet-shared. Depends only on `@frak-labs/core-sdk`'s own reward
+// types (`EstimatedReward`, `MerchantReward`, `RuleConditions`) — no backend or
+// framework coupling — so it stays safe to ship inside the published SDK and
+// lets core-sdk consume its own reward logic without a dependency cycle.
+
+export { extractMinPurchaseAmount, extractStartDate } from "./conditions";
+export {
+    buildPercentageExample,
+    buildTierExample,
+    pickFlatBasket,
+    pickTierBasket,
+    type RewardExample,
+} from "./example";
+export {
+    applyRewardPlaceholder,
+    formatEstimatedReward,
+    formatRewardOrHide,
+} from "./format";
+export {
+    type BestReward,
+    type DisplayCampaign,
+    formatBestReward,
+    type RewardAudience,
+    type SelectDisplayCampaignOptions,
+    selectBestReward,
+    selectDisplayCampaign,
+} from "./select";
+export { getRewardValue } from "./value";

package/src/rewards/select.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, it } from "vitest";
+import type { InteractionTypeKey } from "../constants/interactionTypes";
+import type { EstimatedReward, MerchantReward, RuleConditions } from "../types";
+import {
+    formatBestReward,
+    selectBestReward,
+    selectDisplayCampaign,
+} from "./select";
+
+const NOW = new Date("2025-01-15T00:00:00Z");
+const unix = (iso: string) => Math.floor(new Date(iso).getTime() / 1000);
+
+function fixedReward(eur: number): EstimatedReward {
+    return {
+        payoutType: "fixed",
+        amount: { amount: eur, eurAmount: eur, usdAmount: eur, gbpAmount: eur },
+    };
+}
+
+function uncappedPercentage(percent: number): EstimatedReward {
+    return { payoutType: "percentage", percent, percentOf: "purchase_amount" };
+}
+
+function startsAtCondition(iso: string): RuleConditions {
+    return [{ field: "time.timestamp", operator: "gte", value: unix(iso) }];
+}
+
+function campaign(opts: {
+    id: string;
+    interactionTypeKey?: InteractionTypeKey;
+    referrer?: EstimatedReward;
+    referee?: EstimatedReward;
+    conditions?: RuleConditions;
+    expiresAt?: string | null;
+    defaultLockupSeconds?: number;
+}): MerchantReward {
+    return {
+        campaignId: opts.id,
+        name: opts.id,
+        interactionTypeKey: opts.interactionTypeKey ?? "purchase",
+        conditions: opts.conditions ?? [],
+        referrer: opts.referrer,
+        referee: opts.referee,
+        expiresAt: opts.expiresAt,
+        defaultLockupSeconds: opts.defaultLockupSeconds,
+    };
+}
+
+describe("selectDisplayCampaign", () => {
+    it("returns undefined for an empty set", () => {
+        expect(selectDisplayCampaign([], { now: NOW })).toBeUndefined();
+    });
+
+    it("picks the highest-reward live campaign", () => {
+        const result = selectDisplayCampaign(
+            [
+                campaign({ id: "low", referrer: fixedReward(2) }),
+                campaign({ id: "high", referrer: fixedReward(9) }),
+            ],
+            { now: NOW }
+        );
+        expect(result?.status).toBe("live");
+        expect(result?.campaign.campaignId).toBe("high");
+    });
+
+    it("prefers a live campaign over a richer upcoming one", () => {
+        const result = selectDisplayCampaign(
+            [
+                campaign({
+                    id: "upcoming-rich",
+                    referrer: fixedReward(50),
+                    conditions: startsAtCondition("2025-03-01T00:00:00Z"),
+                }),
+                campaign({ id: "live-poor", referrer: fixedReward(3) }),
+            ],
+            { now: NOW }
+        );
+        expect(result?.status).toBe("live");
+        expect(result?.campaign.campaignId).toBe("live-poor");
+    });
+
+    it("falls back to the soonest-starting upcoming campaign", () => {
+        const result = selectDisplayCampaign(
+            [
+                campaign({
+                    id: "later",
+                    referrer: fixedReward(50),
+                    conditions: startsAtCondition("2025-04-01T00:00:00Z"),
+                }),
+                campaign({
+                    id: "sooner",
+                    referrer: fixedReward(5),
+                    conditions: startsAtCondition("2025-02-01T00:00:00Z"),
+                }),
+            ],
+            { now: NOW }
+        );
+        expect(result?.status).toBe("upcoming");
+        expect(result?.campaign.campaignId).toBe("sooner");
+        expect(result?.startsAt?.toISOString()).toBe(
+            "2025-02-01T00:00:00.000Z"
+        );
+    });
+
+    it("skips expired campaigns", () => {
+        const result = selectDisplayCampaign(
+            [
+                campaign({
+                    id: "expired",
+                    referrer: fixedReward(99),
+                    expiresAt: "2025-01-01T00:00:00Z",
+                }),
+                campaign({ id: "active", referrer: fixedReward(4) }),
+            ],
+            { now: NOW }
+        );
+        expect(result?.campaign.campaignId).toBe("active");
+    });
+
+    it("only considers campaigns matching targetInteraction", () => {
+        const result = selectDisplayCampaign(
+            [
+                campaign({
+                    id: "referral-rich",
+                    interactionTypeKey: "referral",
+                    referrer: fixedReward(50),
+                }),
+                campaign({
+                    id: "purchase-poor",
+                    interactionTypeKey: "purchase",
+                    referrer: fixedReward(4),
+                }),
+            ],
+            { now: NOW, targetInteraction: "purchase" }
+        );
+        expect(result?.campaign.campaignId).toBe("purchase-poor");
+    });
+
+    it("ranks by the referee side when audience is 'referee'", () => {
+        const rewards = [
+            campaign({
+                id: "rich-referrer",
+                referrer: fixedReward(50),
+                referee: fixedReward(2),
+            }),
+            campaign({
+                id: "rich-referee",
+                referrer: fixedReward(1),
+                referee: fixedReward(9),
+            }),
+        ];
+        expect(
+            selectDisplayCampaign(rewards, { now: NOW })?.campaign.campaignId
+        ).toBe("rich-referrer");
+        expect(
+            selectDisplayCampaign(rewards, { now: NOW, audience: "referee" })
+                ?.campaign.campaignId
+        ).toBe("rich-referee");
+    });
+});
+
+describe("formatBestReward", () => {
+    it("returns undefined for an empty set", () => {
+        expect(formatBestReward([], { now: NOW })).toBeUndefined();
+    });
+
+    it("formats the selected campaign's referrer reward by default", () => {
+        const formatted = formatBestReward(
+            [
+                campaign({ id: "low", referrer: fixedReward(2) }),
+                campaign({ id: "high", referrer: fixedReward(50) }),
+            ],
+            { now: NOW }
+        );
+        expect(formatted).toContain("50");
+    });
+
+    it("formats the referee reward when audience is 'referee'", () => {
+        const formatted = formatBestReward(
+            [
+                campaign({
+                    id: "c",
+                    referrer: fixedReward(50),
+                    referee: fixedReward(3),
+                }),
+            ],
+            { now: NOW, audience: "referee" }
+        );
+        expect(formatted).toContain("3");
+        expect(formatted).not.toContain("50");
+    });
+
+    it("ignores expired campaigns (does not advertise a stale reward)", () => {
+        expect(
+            formatBestReward(
+                [
+                    campaign({
+                        id: "expired",
+                        referrer: fixedReward(99),
+                        expiresAt: "2025-01-01T00:00:00Z",
+                    }),
+                ],
+                { now: NOW }
+            )
+        ).toBeUndefined();
+    });
+
+    it("renders an uncapped percentage reward as a percent string", () => {
+        expect(
+            formatBestReward(
+                [campaign({ id: "c", referrer: uncappedPercentage(10) })],
+                { now: NOW }
+            )
+        ).toBe("10 %");
+    });
+});
+
+describe("selectBestReward", () => {
+    it("returns undefined for an empty set", () => {
+        expect(selectBestReward([], { now: NOW })).toBeUndefined();
+    });
+
+    it("exposes the formatted reward and its payout type", () => {
+        const best = selectBestReward(
+            [campaign({ id: "c", referrer: fixedReward(50) })],
+            { now: NOW }
+        );
+        expect(best?.formatted).toContain("50");
+        expect(best?.payoutType).toBe("fixed");
+        expect(best?.minPurchaseAmount).toBeUndefined();
+        expect(best?.lockupDurationDays).toBeUndefined();
+    });
+
+    it("surfaces the minimum purchase amount when the campaign gates on one", () => {
+        const best = selectBestReward(
+            [
+                campaign({
+                    id: "c",
+                    referrer: fixedReward(50),
+                    conditions: [
+                        {
+                            field: "purchase.amount",
+                            operator: "gte",
+                            value: 25,
+                        },
+                    ],
+                }),
+            ],
+            { now: NOW }
+        );
+        expect(best?.minPurchaseAmount).toContain("25");
+    });
+
+    it("surfaces the lockup duration in whole days", () => {
+        const best = selectBestReward(
+            [
+                campaign({
+                    id: "c",
+                    referrer: fixedReward(50),
+                    defaultLockupSeconds: 7 * 86_400,
+                }),
+            ],
+            { now: NOW }
+        );
+        expect(best?.lockupDurationDays).toBe(7);
+    });
+
+    it("omits a zero lockup", () => {
+        const best = selectBestReward(
+            [
+                campaign({
+                    id: "c",
+                    referrer: fixedReward(50),
+                    defaultLockupSeconds: 0,
+                }),
+            ],
+            { now: NOW }
+        );
+        expect(best?.lockupDurationDays).toBeUndefined();
+    });
+});