@frak-labs/core-sdk 1.1.4 → 1.1.5-beta.1700e6ec

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

package/src/rewards/select.ts

@@ -0,0 +1,197 @@
+import type { InteractionTypeKey } from "../constants/interactionTypes";
+import type {
+    Currency,
+    EstimatedReward,
+    MerchantReward,
+    TokenAmountType,
+} from "../types";
+import { formatAmount } from "../utils/format/formatAmount";
+import { getCurrencyAmountKey } from "../utils/format/getCurrencyAmountKey";
+import { getSupportedCurrency } from "../utils/format/getSupportedCurrency";
+import { extractMinPurchaseAmount, extractStartDate } from "./conditions";
+import { formatRewardOrHide } from "./format";
+import { getRewardRank } from "./value";
+
+/** Reward side a surface cares about: the sharer (`referrer`) or the referred
+ * user (`referee`). Drives both campaign ranking and which side is displayed. */
+export type RewardAudience = "referrer" | "referee";
+
+export type DisplayCampaign = {
+    campaign: MerchantReward;
+    status: "live" | "upcoming";
+    startsAt?: Date;
+};
+
+export type SelectDisplayCampaignOptions = {
+    /** Reference "now" for expiry / start gating; defaults to the current time. */
+    now?: Date;
+    /** Currency the ranking is expressed in; defaults to EUR. */
+    currency?: Currency;
+    /** When set, only campaigns triggered by this interaction are considered. */
+    targetInteraction?: InteractionTypeKey;
+    /** Reward side to rank campaigns by; defaults to `"referrer"`. */
+    audience?: RewardAudience;
+};
+
+function isExpired(campaign: MerchantReward, nowMs: number): boolean {
+    return (
+        campaign.expiresAt != null &&
+        new Date(campaign.expiresAt).getTime() <= nowMs
+    );
+}
+
+function hasStarted(campaign: MerchantReward, nowMs: number): boolean {
+    const startsAt = extractStartDate(campaign.conditions);
+    return startsAt == null || startsAt.getTime() <= nowMs;
+}
+
+function audienceReward(campaign: MerchantReward, audience: RewardAudience) {
+    return audience === "referee" ? campaign.referee : campaign.referrer;
+}
+
+function campaignRank(
+    campaign: MerchantReward,
+    key: keyof TokenAmountType,
+    audience: RewardAudience
+): number {
+    const reward = audienceReward(campaign, audience);
+    return reward ? getRewardRank(reward, key) : 0;
+}
+
+/**
+ * Pick the single campaign a merchant surface should display.
+ *
+ * Filters out expired (and, when `targetInteraction` is set, non-matching)
+ * campaigns, then prefers the highest-ranked *live* campaign — ranked by the
+ * `audience` reward side in the requested currency. When none has started yet
+ * it falls back to the soonest-starting upcoming campaign (the endpoint does
+ * not gate on the start-date condition, so future-start campaigns come
+ * through).
+ */
+export function selectDisplayCampaign(
+    rewards: readonly MerchantReward[],
+    options: SelectDisplayCampaignOptions = {}
+): DisplayCampaign | undefined {
+    const nowMs = (options.now ?? new Date()).getTime();
+    const audience = options.audience ?? "referrer";
+    const key = getCurrencyAmountKey(getSupportedCurrency(options.currency));
+
+    const matching = options.targetInteraction
+        ? rewards.filter(
+              (campaign) =>
+                  campaign.interactionTypeKey === options.targetInteraction
+          )
+        : rewards;
+    const active = matching.filter((campaign) => !isExpired(campaign, nowMs));
+
+    const live = active.filter((campaign) => hasStarted(campaign, nowMs));
+    if (live.length > 0) {
+        const best = live.reduce((a, b) =>
+            campaignRank(b, key, audience) > campaignRank(a, key, audience)
+                ? b
+                : a
+        );
+        return { campaign: best, status: "live" };
+    }
+
+    const upcoming = active
+        .map((campaign) => ({
+            campaign,
+            startsAt: extractStartDate(campaign.conditions),
+        }))
+        .filter(
+            (entry): entry is { campaign: MerchantReward; startsAt: Date } =>
+                entry.startsAt != null
+        );
+    if (upcoming.length === 0) return undefined;
+
+    const soonest = upcoming.reduce((a, b) =>
+        b.startsAt.getTime() < a.startsAt.getTime() ? b : a
+    );
+    return {
+        campaign: soonest.campaign,
+        status: "upcoming",
+        startsAt: soonest.startsAt,
+    };
+}
+
+/**
+ * The single reward a merchant surface should display: its formatted string
+ * plus the `payoutType` of the underlying reward, so surfaces can adapt their
+ * presentation (e.g. hide percentage rewards, prefix tiered ones with "Up to").
+ */
+export type BestReward = {
+    /** Display-ready reward string (e.g. `"5 €"`, `"10 %"`). */
+    formatted: string;
+    /** Payout type of the selected reward. */
+    payoutType: EstimatedReward["payoutType"];
+    /**
+     * Minimum purchase amount gating the reward, formatted with the requested
+     * currency (e.g. `"10 €"`), or `undefined` when the campaign sets no
+     * minimum.
+     */
+    minPurchaseAmount?: string;
+    /**
+     * Whole-day lockup applied before the reward settles, or `undefined` when
+     * the campaign has no lockup.
+     */
+    lockupDurationDays?: number;
+};
+
+/**
+ * Pick the best campaign for `options` and resolve its `audience`-side reward
+ * to a formatted string plus its `payoutType`, or `undefined` when there is
+ * nothing worth showing.
+ *
+ * Single entry point shared by every "headline reward" surface (share button,
+ * wallet modal, sharing/install screens) so they all show the same number for
+ * a given merchant and can branch on the payout type.
+ */
+export function selectBestReward(
+    rewards: readonly MerchantReward[],
+    options: SelectDisplayCampaignOptions = {}
+): BestReward | undefined {
+    const selected = selectDisplayCampaign(rewards, options);
+    if (!selected) return undefined;
+    const reward = audienceReward(
+        selected.campaign,
+        options.audience ?? "referrer"
+    );
+    if (!reward) return undefined;
+    const formatted = formatRewardOrHide(reward, options.currency);
+    if (!formatted) return undefined;
+
+    const minPurchase = extractMinPurchaseAmount(selected.campaign.conditions);
+    const minPurchaseAmount =
+        minPurchase != null
+            ? formatAmount(minPurchase, options.currency)
+            : undefined;
+
+    const lockupSeconds = selected.campaign.defaultLockupSeconds;
+    const lockupDurationDays =
+        lockupSeconds && lockupSeconds > 0
+            ? Math.round(lockupSeconds / 86_400)
+            : undefined;
+
+    return {
+        formatted,
+        payoutType: reward.payoutType,
+        minPurchaseAmount,
+        lockupDurationDays,
+    };
+}
+
+/**
+ * Headline reward string for a merchant: picks the best campaign for `options`
+ * and formats its `audience`-side reward, or returns `undefined` when there is
+ * nothing worth showing.
+ *
+ * Thin wrapper over {@link selectBestReward} for callers that only need the
+ * formatted string.
+ */
+export function formatBestReward(
+    rewards: readonly MerchantReward[],
+    options: SelectDisplayCampaignOptions = {}
+): string | undefined {
+    return selectBestReward(rewards, options)?.formatted;
+}

package/src/rewards/value.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import type { EstimatedReward } from "../types";
+import { getRewardRank, getRewardValue } from "./value";
+
+const amount = (eur: number) => ({
+    amount: eur,
+    eurAmount: eur,
+    usdAmount: eur,
+    gbpAmount: eur,
+});
+
+const fixed = (eur: number): EstimatedReward => ({
+    payoutType: "fixed",
+    amount: amount(eur),
+});
+
+const cappedPercentage = (percent: number, cap: number): EstimatedReward => ({
+    payoutType: "percentage",
+    percent,
+    percentOf: "purchase_amount",
+    maxAmount: amount(cap),
+});
+
+const uncappedPercentage = (percent: number): EstimatedReward => ({
+    payoutType: "percentage",
+    percent,
+    percentOf: "purchase_amount",
+});
+
+describe("getRewardValue", () => {
+    it("returns the fixed amount in the requested currency", () => {
+        expect(getRewardValue(fixed(5), "eurAmount")).toBe(5);
+    });
+
+    it("uses the capped maxAmount for a percentage reward", () => {
+        expect(getRewardValue(cappedPercentage(8, 4.8), "eurAmount")).toBe(4.8);
+    });
+
+    it("returns 0 for an uncapped percentage reward", () => {
+        expect(getRewardValue(uncappedPercentage(8), "eurAmount")).toBe(0);
+    });
+
+    it("returns the richest token tier for a tiered reward", () => {
+        expect(
+            getRewardValue(
+                {
+                    payoutType: "tiered",
+                    tierField: "purchase.amount",
+                    tiers: [
+                        { minValue: 0, maxValue: 50, amount: amount(2) },
+                        { minValue: 50, amount: amount(9) },
+                    ],
+                },
+                "eurAmount"
+            )
+        ).toBe(9);
+    });
+});
+
+describe("getRewardRank", () => {
+    it("ranks a reward with real money by its money value", () => {
+        expect(getRewardRank(fixed(5), "eurAmount")).toBe(5);
+        expect(getRewardRank(cappedPercentage(8, 4.8), "eurAmount")).toBe(4.8);
+    });
+
+    it("gives an uncapped percentage a positive weight (never buried at 0)", () => {
+        expect(
+            getRewardRank(uncappedPercentage(8), "eurAmount")
+        ).toBeGreaterThan(0);
+    });
+
+    it("keeps real money ranked above any uncapped percentage", () => {
+        expect(getRewardRank(fixed(1), "eurAmount")).toBeGreaterThan(
+            getRewardRank(uncappedPercentage(50), "eurAmount")
+        );
+    });
+
+    it("keeps an uncapped percentage ranked above a zero-value reward", () => {
+        expect(
+            getRewardRank(uncappedPercentage(8), "eurAmount")
+        ).toBeGreaterThan(getRewardRank(fixed(0), "eurAmount"));
+    });
+
+    it("ranks a higher uncapped percentage above a lower one", () => {
+        expect(
+            getRewardRank(uncappedPercentage(20), "eurAmount")
+        ).toBeGreaterThan(getRewardRank(uncappedPercentage(5), "eurAmount"));
+    });
+});

package/src/rewards/value.ts

@@ -0,0 +1,73 @@
+import type { EstimatedReward, TokenAmountType } from "../types";
+
+/**
+ * Comparable fiat value of a single reward, used to rank rewards against each
+ * other.
+ *
+ * - `fixed`      → the token amount in the requested currency
+ * - `tiered`     → the highest token amount across tiers
+ * - `percentage` → the capped (`maxAmount`) value when present, otherwise `0`
+ *                  (an uncapped percentage has no comparable fiat value)
+ */
+export function getRewardValue(
+    reward: EstimatedReward,
+    key: keyof TokenAmountType
+): number {
+    switch (reward.payoutType) {
+        case "fixed":
+            return reward.amount[key];
+        case "percentage":
+            return reward.maxAmount?.[key] ?? 0;
+        case "tiered":
+            return reward.tiers.reduce(
+                (max, tier) =>
+                    "amount" in tier ? Math.max(max, tier.amount[key]) : max,
+                0
+            );
+    }
+}
+
+/**
+ * Highest percent a reward exposes: the flat `percentage` percent, or the
+ * richest percent across `tiered` tiers, or `0` when it carries none.
+ *
+ * Shared by {@link getRewardRank} (to weight a percentage-only reward) and
+ * `formatEstimatedReward` (to render it as `"X %"`), so the value the UI ranks
+ * by and the value it prints stay derived from one tier traversal.
+ */
+export function maxRewardPercent(reward: EstimatedReward): number {
+    if (reward.payoutType === "percentage") return reward.percent;
+    if (reward.payoutType === "tiered") {
+        return reward.tiers.reduce(
+            (max, tier) =>
+                "percent" in tier ? Math.max(max, tier.percent) : max,
+            0
+        );
+    }
+    return 0;
+}
+
+// A reward with no money value (an uncapped percentage, or a percent-only
+// tier set) still renders as "X %", so it is worth surfacing. We give it a
+// positive ranking weight derived from its percent but scaled far below any
+// real-money reward, so the two invariants the UI relies on hold: (1) a reward
+// with real money always outranks a percentage-only reward, and (2) a
+// percentage-only reward still outranks a zero-value reward. Together they
+// guarantee the reward the ranking picks is always one we can display.
+const PERCENT_ONLY_RANK_WEIGHT = 1e-6;
+
+/**
+ * Ranking weight used to pick the single most attractive reward to surface.
+ *
+ * Mirrors {@link getRewardValue} (money value) but lifts a percentage-only
+ * reward to a tiny positive weight instead of `0`, so it is never buried
+ * behind a zero-value reward when choosing what to display.
+ */
+export function getRewardRank(
+    reward: EstimatedReward,
+    key: keyof TokenAmountType
+): number {
+    const value = getRewardValue(reward, key);
+    if (value > 0) return value;
+    return maxRewardPercent(reward) * PERCENT_ONLY_RANK_WEIGHT;
+}

package/src/types/index.ts

@@ -53,9 +53,15 @@ export type {
 } from "./rpc/embedded";
 export type { SendInteractionParamsType } from "./rpc/interaction";
 export type {
+    ConditionGroup,
+    ConditionOperator,
     EstimatedReward,
     GetMerchantInformationReturnType,
+    MerchantReward,
     RewardTier,
+    RuleCondition,
+    RuleConditions,
+    RuleField,
     TokenAmountType,
 } from "./rpc/merchantInformation";
 export type {

package/src/types/resolvedConfig.ts

@@ -43,6 +43,8 @@ export type ResolvedPlacement = {
             referrerNoRewardText?: string;
             ctaText?: string;
             ctaNoRewardText?: string;
+            /** Custom illustration URL replacing the built-in gift icon. */
+            imageUrl?: string;
             css?: string;
         };
         banner?: {
@@ -52,6 +54,8 @@ export type ResolvedPlacement = {
             inappTitle?: string;
             inappDescription?: string;
             inappCta?: string;
+            /** Custom illustration URL replacing the built-in gift icon. */
+            imageUrl?: string;
             css?: string;
         };
     };