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

package/src/context/frakContext.test.ts

@@ -584,6 +584,61 @@ describe("FrakContextManager", () => {
         });
     });
 
+    describe("case-insensitive fCtx key", () => {
+        const context: FrakContextV2 = {
+            v: 2,
+            c: "550e8400-e29b-41d4-a716-446655440001",
+            m: "550e8400-e29b-41d4-a716-446655440000",
+            t: 1709654400,
+        };
+
+        it("should parse a lowercased fctx key with an intact value", () => {
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fctx=${compressed}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toEqual(context);
+        });
+
+        it("should parse an uppercased FCTX key with an intact value", () => {
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?FCTX=${compressed}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toEqual(context);
+        });
+
+        it("should prefer the exact-case fCtx key when both variants exist", () => {
+            const canonical = FrakContextManager.compress(context);
+            const url = `https://example.com?fctx=stale&fCtx=${canonical}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toEqual(context);
+        });
+
+        it("should remove a lowercased fctx key", () => {
+            const url = "https://example.com?fctx=abc&keep=me";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).not.toContain("fctx");
+            expect(result).toContain("keep=me");
+        });
+
+        it("should not leave a stale lowercased fctx variant on update", () => {
+            const url = "https://example.com?fctx=stale";
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("fCtx=");
+            expect(result).not.toContain("fctx=stale");
+            expect(FrakContextManager.parse({ url: result! })).toEqual(context);
+        });
+    });
+
     describe("replaceUrl", () => {
         const mockAddress =
             "0x1234567890123456789012345678901234567890" as Address;

package/src/context/frakContext.ts

@@ -6,6 +6,10 @@ import type {
 } from "../types";
 import { isV2Context } from "../types";
 import { base64urlDecode, base64urlEncode } from "../utils/compression/b64";
+import {
+    deleteQueryParamCaseInsensitive,
+    getQueryParamCaseInsensitive,
+} from "../utils/url/queryParams";
 import { addressToBytes, bytesToAddress, isAddress } from "./address";
 import { decodeFrakContextV2, encodeFrakContextV2 } from "./frakContextV2Codec";
 
@@ -77,6 +81,9 @@ function decompress(context?: string): FrakContext | undefined {
 /**
  * Parse a URL to extract the Frak referral context from the `fCtx` query parameter.
  *
+ * The key is matched case-insensitively: some link channels (emails, messaging
+ * apps) lowercase query-param keys in transit, so `fCtx` can arrive as `fctx`.
+ *
  * @param args
  * @param args.url - The URL to parse
  * @returns The parsed FrakContext, or null if absent
@@ -85,7 +92,10 @@ function parse({ url }: { url: string }): FrakContext | null | undefined {
     if (!url) return null;
 
     const urlObj = new URL(url);
-    const frakContext = urlObj.searchParams.get(contextKey);
+    const frakContext = getQueryParamCaseInsensitive(
+        urlObj.searchParams,
+        contextKey
+    );
     if (!frakContext) return null;
 
     return decompress(frakContext);
@@ -165,6 +175,7 @@ function update({
     if (!compressedContext) return null;
 
     const urlObj = new URL(url);
+    deleteQueryParamCaseInsensitive(urlObj.searchParams, contextKey);
     urlObj.searchParams.set(contextKey, compressedContext);
     applyAttributionParams(urlObj, attribution);
     return urlObj.toString();
@@ -178,7 +189,7 @@ function update({
  */
 function remove(url: string): string {
     const urlObj = new URL(url);
-    urlObj.searchParams.delete(contextKey);
+    deleteQueryParamCaseInsensitive(urlObj.searchParams, contextKey);
     return urlObj.toString();
 }
 

package/src/index.ts

@@ -23,6 +23,8 @@ export type {
     AttributionParams,
     ClientLifecycleEvent,
     CompressedData,
+    ConditionGroup,
+    ConditionOperator,
     Currency,
     // RPC Embedded wallet
     DisplayEmbeddedWalletParamsType,
@@ -61,6 +63,7 @@ export type {
     LoggedOutEmbeddedView,
     LoginModalStepType,
     MerchantConfigResponse,
+    MerchantReward,
     ModalRpcMetadata,
     ModalRpcStepsInput,
     ModalRpcStepsResultType,
@@ -75,6 +78,9 @@ export type {
     ResolvedPlacement,
     ResolvedSdkConfig,
     RewardTier,
+    RuleCondition,
+    RuleConditions,
+    RuleField,
     SdkResolvedConfig,
     // RPC Interaction
     SendInteractionParamsType,
@@ -107,11 +113,13 @@ export {
     compressJsonToB64,
     type DeepLinkFallbackOptions,
     decompressJsonFromB64,
+    deleteQueryParamCaseInsensitive,
     type FullSsoParams,
     findIframeInOpener,
     formatAmount,
     generateSsoUrl,
     getCurrencyAmountKey,
+    getQueryParamCaseInsensitive,
     getSupportedCurrency,
     isInAppBrowser,
     isIOS,

package/src/rewards/conditions.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { extractMinPurchaseAmount, extractStartDate } from "./conditions";
+
+const unix = (iso: string) => Math.floor(new Date(iso).getTime() / 1000);
+
+describe("extractMinPurchaseAmount", () => {
+    it("reads a flat purchase.amount gte condition", () => {
+        expect(
+            extractMinPurchaseAmount([
+                { field: "purchase.amount", operator: "gte", value: 50 },
+            ])
+        ).toBe(50);
+    });
+
+    it("walks nested groups and keeps the lowest threshold", () => {
+        expect(
+            extractMinPurchaseAmount({
+                logic: "all",
+                conditions: [
+                    { field: "purchase.amount", operator: "gte", value: 80 },
+                    {
+                        logic: "any",
+                        conditions: [
+                            {
+                                field: "purchase.amount",
+                                operator: "gt",
+                                value: 30,
+                            },
+                        ],
+                    },
+                ],
+            })
+        ).toBe(30);
+    });
+
+    it("returns undefined without a purchase gate", () => {
+        expect(
+            extractMinPurchaseAmount([
+                { field: "user.isNew", operator: "eq", value: true },
+            ])
+        ).toBeUndefined();
+    });
+});
+
+describe("extractStartDate", () => {
+    it("reads a time.timestamp gte condition (unix seconds)", () => {
+        const start = extractStartDate([
+            {
+                field: "time.timestamp",
+                operator: "gte",
+                value: unix("2025-02-01T00:00:00Z"),
+            },
+        ]);
+        expect(start?.toISOString()).toBe("2025-02-01T00:00:00.000Z");
+    });
+
+    it("returns undefined without a start gate", () => {
+        expect(extractStartDate([])).toBeUndefined();
+    });
+});

package/src/rewards/conditions.ts

@@ -0,0 +1,72 @@
+import type { ConditionGroup, RuleCondition, RuleConditions } from "../types";
+
+type ConditionNode = RuleCondition | ConditionGroup;
+
+function conditionNodes(conditions: RuleConditions): ConditionNode[] {
+    return Array.isArray(conditions) ? conditions : conditions.conditions;
+}
+
+function conditionValueToNumber(
+    value: RuleCondition["value"]
+): number | undefined {
+    if (typeof value === "number") return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+
+// Conditions arrive as a flat list or recursive groups; collect every numeric
+// value whose field + operator match, descending into nested groups.
+function collectConditionValues(
+    conditions: RuleConditions,
+    field: string,
+    operators: ReadonlySet<RuleCondition["operator"]>
+): number[] {
+    const values: number[] = [];
+    for (const node of conditionNodes(conditions)) {
+        if ("logic" in node) {
+            values.push(...collectConditionValues(node, field, operators));
+            continue;
+        }
+        if (node.field === field && operators.has(node.operator)) {
+            const value = conditionValueToNumber(node.value);
+            if (value != null) values.push(value);
+        }
+    }
+    return values;
+}
+
+const MIN_PURCHASE_OPERATORS: ReadonlySet<RuleCondition["operator"]> = new Set([
+    "gt",
+    "gte",
+    "between",
+]);
+const START_DATE_OPERATORS: ReadonlySet<RuleCondition["operator"]> = new Set([
+    "gt",
+    "gte",
+]);
+
+export function extractMinPurchaseAmount(
+    conditions: RuleConditions
+): number | undefined {
+    const values = collectConditionValues(
+        conditions,
+        "purchase.amount",
+        MIN_PURCHASE_OPERATORS
+    );
+    return values.length > 0 ? Math.min(...values) : undefined;
+}
+
+// The business app encodes a campaign start as a `time.timestamp >= <unix s>`
+// rule condition; the endpoint returns it verbatim inside `conditions`.
+export function extractStartDate(conditions: RuleConditions): Date | undefined {
+    const values = collectConditionValues(
+        conditions,
+        "time.timestamp",
+        START_DATE_OPERATORS
+    );
+    if (values.length === 0) return undefined;
+    return new Date(Math.min(...values) * 1000);
+}

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.replace("{REWARD}", reward)
+        : text.replace("{REWARD}", "");
+}

package/src/rewards/index.ts

@@ -0,0 +1,27 @@
+// 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 DisplayCampaign,
+    formatBestReward,
+    type RewardAudience,
+    type SelectDisplayCampaignOptions,
+    selectDisplayCampaign,
+} from "./select";
+export { getRewardValue } from "./value";