@frak-labs/core-sdk 1.1.3 → 1.1.5-beta.5b65e64f

package/src/rewards/select.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, it } from "vitest";
+import type { InteractionTypeKey } from "../constants/interactionTypes";
+import type { EstimatedReward, MerchantReward, RuleConditions } from "../types";
+import { formatBestReward, 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 %");
+    });
+});

package/src/rewards/select.ts

@@ -0,0 +1,132 @@
+import type { InteractionTypeKey } from "../constants/interactionTypes";
+import type { Currency, MerchantReward, TokenAmountType } from "../types";
+import { getCurrencyAmountKey } from "../utils/format/getCurrencyAmountKey";
+import { getSupportedCurrency } from "../utils/format/getSupportedCurrency";
+import { 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,
+    };
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function formatBestReward(
+    rewards: readonly MerchantReward[],
+    options: SelectDisplayCampaignOptions = {}
+): string | undefined {
+    const selected = selectDisplayCampaign(rewards, options);
+    if (!selected) return undefined;
+    const reward = audienceReward(
+        selected.campaign,
+        options.audience ?? "referrer"
+    );
+    return formatRewardOrHide(reward, options.currency);
+}

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/rpc/merchantInformation.ts

@@ -12,13 +12,20 @@ export type TokenAmountType = {
 };
 
 /**
- * A tier definition for tiered rewards
+ * A tier definition for tiered rewards — pays either a flat token amount
+ * or a percent of the tier field value
  */
-export type RewardTier = {
-    minValue: number;
-    maxValue?: number;
-    amount: TokenAmountType;
-};
+export type RewardTier =
+    | {
+          minValue: number;
+          maxValue?: number;
+          amount: TokenAmountType;
+      }
+    | {
+          minValue: number;
+          maxValue?: number;
+          percent: number;
+      };
 
 /**
  * Estimated reward amount — discriminated union by payout type
@@ -45,6 +52,112 @@ export type EstimatedReward =
           tiers: RewardTier[];
       };
 
+/**
+ * Comparison operators usable in a {@link RuleCondition}.
+ * @group RPC Schema
+ */
+export type ConditionOperator =
+    | "eq"
+    | "neq"
+    | "gt"
+    | "gte"
+    | "lt"
+    | "lte"
+    | "in"
+    | "not_in"
+    | "contains"
+    | "starts_with"
+    | "ends_with"
+    | "exists"
+    | "not_exists"
+    | "between";
+
+/**
+ * Dot-path of the rule-evaluation context field a {@link RuleCondition} targets.
+ *
+ * Only the paths the SDK actually reads are listed (for editor autocompletion);
+ * the trailing `string` member keeps the type open to any other path the backend
+ * may emit, so it never lies at runtime. Custom interaction data is addressed
+ * through `custom.${string}`.
+ * @group RPC Schema
+ */
+export type RuleField =
+    // Minimum-purchase gating (read by `extractMinPurchaseAmount`)
+    | "purchase.amount"
+    // Campaign start gating (read by `extractStartDate`)
+    | "time.timestamp"
+    // Referrer attribution
+    | "attribution.referrerIdentityGroupId"
+    // Custom interaction context
+    | `custom.${string}`
+    // Escape hatch — any other context path (kept assignable to/from `string`)
+    | (string & Record<never, never>);
+
+/**
+ * A single leaf rule condition. Compares the value found at {@link RuleField}
+ * in the evaluation context against `value` (and `valueTo` for `between`).
+ * @group RPC Schema
+ */
+export type RuleCondition = {
+    field: RuleField;
+    operator: ConditionOperator;
+    value: string | number | boolean | null;
+    valueTo?: string | number | boolean | null;
+};
+
+/**
+ * A recursive group of conditions combined through a boolean `logic`.
+ * @group RPC Schema
+ */
+export type ConditionGroup = {
+    logic: "all" | "any" | "none";
+    conditions: (RuleCondition | ConditionGroup)[];
+};
+
+/**
+ * Campaign gating rules: a flat list of {@link RuleCondition} (implicitly
+ * AND-ed) or a nested {@link ConditionGroup} tree. Surfaced raw so integrators
+ * can inspect the rules and derive their own display (start date, minimum
+ * purchase, …) instead of relying on pre-computed fields.
+ * @group RPC Schema
+ */
+export type RuleConditions = RuleCondition[] | ConditionGroup;
+
+/**
+ * A reward offer exposed by a merchant campaign.
+ *
+ * Mirrors the backend `EstimatedRewardItem` one-to-one — a static parity
+ * assertion on the backend keeps its runtime-validated schema in lockstep with
+ * this published contract.
+ * @group RPC Schema
+ */
+export type MerchantReward = {
+    /** Reward token address; falls back to the merchant token when omitted. */
+    token?: Address;
+    /** Identifier of the campaign rule this reward originates from. */
+    campaignId: string;
+    /** Campaign display name. */
+    name: string;
+    /** Interaction that triggers the reward. */
+    interactionTypeKey: InteractionTypeKey;
+    /** Reward paid to the referrer, when the campaign defines one. */
+    referrer?: EstimatedReward;
+    /** Reward paid to the referee, when the campaign defines one. */
+    referee?: EstimatedReward;
+    /** Raw gating rules — inspect to derive start date, minimum purchase, … */
+    conditions: RuleConditions;
+    /** Seconds a reward stays locked before settlement. */
+    defaultLockupSeconds?: number;
+    /** Days before a pending reward expires. */
+    pendingRewardExpirationDays?: number;
+    /** Per-user reward cap for this campaign. */
+    maxRewardsPerUser?: number;
+    /** Merchant-wide per-user reward cap across every campaign. */
+    merchantMaxRewardsPerUser?: number;
+    /** ISO-8601 campaign end date, or `null` when open-ended. */
+    expiresAt?: string | null;
+};
+
 /**
  * Response of the `frak_getMerchantInformation` RPC method
  * @group RPC Schema
@@ -67,11 +180,5 @@ export type GetMerchantInformationReturnType = {
          */
         domain: string;
     };
-    rewards: {
-        token?: Address;
-        campaignId: string;
-        interactionTypeKey: InteractionTypeKey;
-        referrer?: EstimatedReward;
-        referee?: EstimatedReward;
-    }[];
+    rewards: MerchantReward[];
 };

package/src/utils/analytics/events/lifecycle.ts

@@ -6,7 +6,7 @@ export type SdkHandshakeFailureReason =
 
 export type SdkLifecycleEventMap = {
     sdk_initialized: {
-        sdkVersion?: string;
+        sdk_version?: string;
     };
     sdk_iframe_connected: {
         handshake_duration_ms: number;

package/src/utils/analytics/events/referral.ts

@@ -1,9 +1,9 @@
 export type SdkReferralEventMap = {
     user_referred_started: {
         referrer?: string;
-        referrerClientId?: string;
-        referrerWallet?: string;
-        walletStatus?: string;
+        referrer_client_id?: string;
+        referrer_wallet?: string;
+        wallet_status?: string;
     };
     user_referred_completed: {
         status: "success";