@salla.sa/twilight-components 2.14.590 → 2.14.591

package/dist/collection/shared/cart-free-gifts.js

@@ -0,0 +1,448 @@
+/*!
+ * Crafted with ❤ by Salla
+ */
+/**
+ * Shared free-gift lookup for the cart.
+ *
+ * The gift feature is twilight-only: no theme passes `added-by-offer` /
+ * `free-gift-quantity` attributes. `salla-conditional-offer` resolves the gift LINES it
+ * lists (read-only, as information) and the cart line count from here, never from theme
+ * attributes.
+ *
+ * Data source: `salla.api.cart.details()` — it hits the `api.cart.show`
+ * route, which IS in `CartPresenter::$routesWithItems`, so the response
+ * carries `data.cart.items[]` with the per-item keys `added_by_offer`
+ * (bool), `offer_id` (int|null) and `free_gift_quantity` (int) set by
+ * `CartItemTransformer.php`. Those three names are a pinned
+ * contract — do not rename them here or on the components that consume them.
+ *
+ * We deliberately never read these fields off a `cart::updated` payload:
+ * that event fires from `latest()` too, and `api.cart.latest` is NOT in
+ * `$routesWithItems`, so a `cart::updated` payload legitimately carries no
+ * `items` at all. Callers must fetch on mount and call
+ * `refreshCartFreeGifts()` on the event — this module never derives from
+ * event payloads.
+ *
+ * The banner asks for the gift lines and the cart line count on the same tick (initial
+ * mount, and again on every `cart::updated`). Concurrent callers share a
+ * single in-flight promise, mirroring `_pendingOffersRequest` in
+ * `twilight/packages/twilight/src/api/cart.js:831-846`.
+ */
+const EMPTY_GIFT_ITEMS = Object.freeze([]);
+/**
+ * The gift LINES from the last parsed response. `null` is the single "nothing has loaded
+ * yet" flag shared with `countCache`, which keeps the two from ever disagreeing about
+ * which response they came from.
+ */
+let itemsCache = null;
+/**
+ * The cart's line count, published in the SAME pass as `itemsCache`. Only meaningful
+ * while `itemsCache` is non-null.
+ */
+let countCache = null;
+/**
+ * Whether what sits in the caches above came from a response we actually PARSED,
+ * as opposed to the graceful fallback a rejected lookup publishes.
+ *
+ * THIS IS THE CACHE'S WARM/COLD FLAG, and it is separate from the values on purpose.
+ *
+ * A failed lookup still has to hand its in-flight callers something usable, so the
+ * `.catch` below publishes `gifts: []` / `count: null`. But `[]` is TRUTHY, so a cache
+ * populated that way used to read as WARM: every later `getCartItemCount()` /
+ * `getCartFreeGiftItems()` short-circuited on it and returned the FAILURE's values
+ * without ever re-asking. One rejected `details()` therefore pinned the count at
+ * "unknown" (or, for `CartNotCreated`, at a hard `0`) for the whole page view, and
+ * `salla-conditional-offer` — which renders nothing until it is POSITIVELY told the cart
+ * holds items — vanished on a populated cart with a live offer. Nothing corrected it:
+ * only `refreshCartFreeGifts()` clears the cache, and that runs from `cart::updated`,
+ * which a shopper who does not touch the cart never emits.
+ *
+ * So a failure now leaves the cache COLD: its fallback values are still handed to the
+ * callers already waiting, and the next caller re-asks. Concurrent callers still share
+ * one request through `pendingRequest`, so the retry costs one lookup per wave, not one
+ * per consumer — and the cheapest failure of all, `CartNotCreated`, never reaches the
+ * network at all (`details()` rejects before it requests).
+ */
+let isAuthoritative = false;
+let pendingRequest = null;
+// De-dupes concurrent `refreshCartFreeGifts()` callers — see that function.
+let pendingRefresh = null;
+// Bumped by `refreshCartFreeGifts()`. A fetch only gets to publish into
+// the caches if the generation it started under is still current when it
+// resolves — otherwise a request that was already in flight when the cart
+// mutated would win the race and cache pre-mutation data as if it were
+// fresh. Mirrors `salla.event.on('cart::updated', () => { Salla.api.cart._pendingOffersRequest = null; })`
+// in `twilight/packages/twilight/src/api/cart.js:81`, which abandons its
+// in-flight promise on cart update so a post-mutation caller gets a fresh
+// request — the same idea, expressed as a generation check instead of
+// nulling the promise (nulling it here would defeat the same-tick dedupe
+// that `refreshCartFreeGifts()` relies on).
+let generation = 0;
+/**
+ * The cart identity the caches (and any in-flight request) belong to. `undefined` until
+ * the first lookup. See `syncCartIdentity`.
+ */
+let cacheIdentity;
+/**
+ * The SDK's own name for "this visitor has no cart at all".
+ *
+ * `salla.api.cart.details()` resolves its id through
+ * `getCurrentCartId(false, …, allowCreate = false)`, which returns `null` for a guest with
+ * no stored cart id rather than creating one server-side; `details()` then throws this
+ * (twilight/src/api/cart.js:192-199). It is a STATEMENT ABOUT THE CART, not a failure to
+ * reach the server — no cart means no items — so it is the one rejection that resolves to
+ * a hard 0 instead of "unknown".
+ *
+ * Matched on `name`, never on message text: the wording is not a contract, the name is.
+ */
+export const CART_NOT_CREATED = 'CartNotCreated';
+export function isCartNotCreated(error) {
+    return error?.name === CART_NOT_CREATED;
+}
+/**
+ * The cart id as the SDK knows it right now, synchronously, or `null` when there is none.
+ * Same sources `salla.api.cart.getStoredCartId()` reads (the in-memory latest cart, then
+ * storage), with a storage fallback for an SDK that predates it.
+ */
+function readCartIdentity() {
+    try {
+        const id = salla.api?.cart?.getStoredCartId
+            ? salla.api.cart.getStoredCartId()
+            : salla.storage?.get?.('cart.id');
+        return id === undefined || id === null || id === '' ? null : String(id);
+    }
+    catch (_) {
+        return null;
+    }
+}
+/**
+ * Drops everything cached for a previous cart when the cart id has changed.
+ *
+ * The caches are otherwise only invalidated by `refreshCartFreeGifts()`, i.e. by
+ * `cart::updated`. A silent cross-store login writes the merged cart id directly and
+ * emits nothing, so without this a mounted banner would keep serving the previous
+ * cart's line count and gifts. Bumping `generation` also stops a request that is still
+ * in flight for the old cart from publishing, and the in-flight slot is released so the
+ * caller asks again under the new identity.
+ */
+function syncCartIdentity() {
+    const current = readCartIdentity();
+    if (cacheIdentity !== undefined && cacheIdentity !== current) {
+        generation++;
+        itemsCache = null;
+        countCache = null;
+        isAuthoritative = false;
+        pendingRequest = null;
+    }
+    cacheIdentity = current;
+}
+function toNumber(v) {
+    if (v === null || v === undefined)
+        return 0;
+    if (typeof v === 'number')
+        return isFinite(v) ? v : 0;
+    if (typeof v === 'string')
+        return parseFloat(v) || 0;
+    return 0;
+}
+function toNullableNumber(v) {
+    if (v === null || v === undefined || v === '')
+        return null;
+    const n = toNumber(v);
+    return isFinite(n) ? n : null;
+}
+/**
+ * `details()`'s envelope nests items under `data.cart.items`.
+ *
+ * Returns `null` — NOT `[]` — when the response carried no items array at all. The two
+ * are different facts: `[]` is the server saying "this cart is empty", `null` is "this
+ * response cannot answer the question". `getCartItemCount()` is built on that
+ * distinction; see `extractCartCount`.
+ */
+function findItemsArray(res) {
+    const items = res?.data?.cart?.items ?? res?.data?.items ?? res?.cart?.items ?? res?.items;
+    return Array.isArray(items) ? items : null;
+}
+/**
+ * How many LINES the cart holds, or `null` when the response could not say.
+ *
+ * `null` is load-bearing and must never be collapsed into `0`: a consumer that hides
+ * itself on an empty cart has to be able to tell "the cart is empty" apart from "the
+ * cart has not loaded yet", or it flickers (or vanishes) on a populated cart while the
+ * first `details()` request is still in flight.
+ *
+ * The items array is the PRIMARY signal because `api.cart.show` is in
+ * `CartPresenter::$routesWithItems` and therefore always emits it. `cart.count` is only
+ * consulted when the array is missing entirely, and it is a QUANTITY total rather than a
+ * line count — close enough for the only question anyone asks of it (is this zero?), and
+ * never reached on a well-formed response.
+ */
+function extractCartCount(res, items) {
+    if (items !== null)
+        return items.length;
+    const raw = res?.data?.cart?.count ?? res?.data?.count ?? res?.cart?.count ?? res?.count;
+    const count = toNullableNumber(raw);
+    return count !== null && count >= 0 ? count : null;
+}
+/**
+ * The price a gift line would have cost.
+ *
+ * Tries the keys in the order `CartItemTransformer` fills them, and accepts both the
+ * `{amount, currency}` shape a serialized `Money` produces and a bare number/string.
+ * A zero is treated as "nothing usable": the gift's own charged price IS zero, so a 0
+ * here means we read the wrong key, and rendering a struck-through "0" would be worse
+ * than rendering no price at all.
+ */
+function extractOriginalPrice(item) {
+    for (const raw of [item?.original_price, item?.product_price, item?.price]) {
+        const value = raw && typeof raw === 'object' ? raw.amount : raw;
+        const amount = toNullableNumber(value);
+        if (amount !== null && amount > 0)
+            return amount;
+    }
+    return null;
+}
+/**
+ * How many units of this line the offer granted, or `0` when the answer is "none".
+ *
+ * The two absent-ish shapes are NOT the same fact and must not collapse:
+ *
+ *  • the key is MISSING (`undefined`/`null`/`''`) — an older payload, or a
+ *    transformer that did not fill it. Nothing contradicts "the whole line is
+ *    the gift" for an unknown line quantity, so fall back to the line.
+ *  • the key is PRESENT and `0` — the server stating there are no free units on
+ *    this line. That is an answer, and it must be believed.
+ */
+function resolveFreeQuantity(item, lineQuantity) {
+    const raw = item?.free_gift_quantity;
+    const stated = raw !== undefined && raw !== null && raw !== '';
+    if (stated)
+        return toNumber(raw);
+    return lineQuantity > 0 ? lineQuantity : 0;
+}
+/**
+ * The gift LINES, in cart order. Only lines the server flagged `added_by_offer` with at
+ * least one granted free unit qualify.
+ */
+function buildGiftItems(items) {
+    const gifts = [];
+    for (const item of items) {
+        if (item?.id === undefined || item?.id === null)
+            continue;
+        if (!item.added_by_offer)
+            continue;
+        const lineQuantity = toNumber(item.quantity);
+        const freeQuantity = resolveFreeQuantity(item, lineQuantity);
+        // No free units ⇒ not a gift LINE, whatever the flag says. Listing it anyway
+        // would put a line the shopper PAID for in full into the gifts card, labelled
+        // "free" — the card states what the offer granted, so a non-positive free count
+        // means it granted nothing here.
+        if (freeQuantity <= 0)
+            continue;
+        gifts.push({
+            id: String(item.id),
+            offerId: toNullableNumber(item.offer_id),
+            quantity: freeQuantity,
+            freeQuantity,
+            lineQuantity,
+            name: String(item.product_name ?? item.name ?? ''),
+            imageUrl: String(item.product_image?.url ?? item.product_image ?? item.image?.url ?? ''),
+            imageAlt: String(item.product_image?.alt ?? item.image?.alt ?? item.product_name ?? ''),
+            url: String(item.url ?? ''),
+            originalPrice: extractOriginalPrice(item),
+        });
+    }
+    return gifts;
+}
+function fetchAndCache() {
+    if (pendingRequest)
+        return pendingRequest;
+    // Snapshot the generation this request started under — see the
+    // `generation` doc comment above for why.
+    const startedAtGeneration = generation;
+    const request = Promise.resolve()
+        .then(() => salla.api?.cart?.details?.())
+        .then((res) => {
+        const found = findItemsArray(res);
+        const items = found ?? [];
+        // Both projections come out of the SAME response, in one pass.
+        return {
+            gifts: buildGiftItems(items),
+            count: extractCartCount(res, found),
+            // The response was reached and parsed — these values are the cart, so the cache
+            // they land in may be short-circuited on. See `isAuthoritative`.
+            ok: true,
+        };
+    })
+        // A failed fetch shouldn't throw into a badge/lock render path — fail
+        // closed to "no gift info" (or whatever we already knew) rather than
+        // breaking the rest of the cart UI.
+        //
+        // The count splits the failures in two. `CartNotCreated` is the SDK
+        // stating there is no cart, which is a definitive EMPTY and resolves to
+        // 0 — without it, the ordinary first-time guest sits on "unknown"
+        // forever, because no request will ever succeed and no `cart::updated`
+        // is coming to correct it. Everything else (network, 5xx) says nothing
+        // about the contents and still fails OPEN to `null`, so a flaky
+        // connection can never claim the cart is empty.
+        .catch((error) => ({
+        gifts: itemsCache ?? [],
+        count: isCartNotCreated(error) ? 0 : countCache,
+        /**
+         * NOT authoritative, `CartNotCreated` included.
+         *
+         * `0` stays the right ANSWER for it — no cart means no items, and a first-time
+         * guest must be told "empty" rather than sitting on "unknown" — but it is no longer
+         * a FINAL one. The very first cart lookup on a page is fired before
+         * `salla.onReady()` has settled, so it can be answered by an SDK that has not yet
+         * installed the cart id (or, earlier still, not yet installed `salla.config`, whose
+         * `isGuest()` the id resolution calls unguarded). Both spell a cart that is merely
+         * unknown as one that is empty. Leaving the cache cold lets the next lookup — from
+         * a bootstrapped SDK — say so, and on a cart that genuinely is empty the retry
+         * rejects again without a request.
+         */
+        ok: false,
+    }))
+        .then(({ gifts, count, ok }) => {
+        // Only publish if nothing invalidated us while we were in flight.
+        // Otherwise this is pre-mutation data racing a newer, authoritative
+        // request — publishing it would make the lookups short-circuit on stale
+        // data until the NEXT mutation happens to come along.
+        if (startedAtGeneration === generation) {
+            itemsCache = gifts;
+            countCache = count;
+            isAuthoritative = ok;
+        }
+    })
+        .finally(() => {
+        // Only release OUR slot: an identity change may already have replaced it.
+        if (pendingRequest === request)
+            pendingRequest = null;
+    });
+    pendingRequest = request;
+    return request;
+}
+/**
+ * Every free-gift LINE currently in the cart, in cart order.
+ *
+ * Shares the cache, the in-flight promise and the generation guard with
+ * `getCartItemCount()` — the banner asking for both still issues exactly ONE
+ * `details()` request per cart mutation.
+ */
+export function getCartFreeGiftItems() {
+    syncCartIdentity();
+    // `isAuthoritative`, not `itemsCache` alone — a failed lookup leaves `itemsCache` a
+    // truthy `[]`, which is not an answer. See `isAuthoritative`.
+    if (isAuthoritative && itemsCache) {
+        return Promise.resolve(itemsCache);
+    }
+    return fetchAndCache().then(() => itemsCache ?? EMPTY_GIFT_ITEMS);
+}
+/**
+ * Whether the cached cart picture came from a response that was actually reached and
+ * parsed, rather than from the fallback a rejected lookup publishes.
+ *
+ * For the ONE consumer that has to tell "the cart is empty" apart from "the lookup could
+ * not say, and guessed empty": `salla-conditional-offer` stops before it even asks for the
+ * offer when the count is `0`, which is unrecoverable if that `0` was a guess. Everything
+ * else should just read the values — they are already the best available answer.
+ *
+ * Synchronous and side-effect free: it reports on what is cached NOW, so a caller that
+ * wants a fresh answer must still await one of the lookups above.
+ */
+export function hasAuthoritativeCartData() {
+    syncCartIdentity();
+    return isAuthoritative;
+}
+/**
+ * How many LINES the cart holds — `null` while that is genuinely UNKNOWN (nothing has
+ * loaded yet, or the lookup failed), never `0` for either.
+ *
+ * The distinction is the whole point: `salla-conditional-offer` hides its banner on an
+ * empty cart, and a `0` that really meant "still loading" would make the banner flicker
+ * or disappear on a populated one. Shares the cache, the in-flight promise and the
+ * generation guard with `getCartFreeGiftItems()`, so asking for the count costs no
+ * request of its own.
+ */
+export function getCartItemCount() {
+    syncCartIdentity();
+    // THE ONE THAT HID THE BANNER. `itemsCache` alone read a failed lookup's `[]` as a warm
+    // cache and handed back its `null`/`0` count for ever — see `isAuthoritative`.
+    if (isAuthoritative && itemsCache) {
+        return Promise.resolve(countCache);
+    }
+    return fetchAndCache().then(() => countCache);
+}
+/**
+ * Invalidates the cache and re-fetches — call this from a `cart::updated`
+ * handler, ignoring the event payload entirely.
+ *
+ * Bumps `generation` first so that any request already in flight (started
+ * before this invalidation) can no longer publish into `cache` when it
+ * settles — mirrors `salla.event.on('cart::updated', () => { Salla.api.cart._pendingOffersRequest = null; })`
+ * in `twilight/packages/twilight/src/api/cart.js:81`, which abandons its
+ * own in-flight promise on cart update for the same reason.
+ *
+ * Then chains a fresh fetch BEHIND whatever was already in flight (rather
+ * than firing a second request in parallel): once that prior request
+ * settles — its result now guaranteed to be discarded by the generation
+ * check above — `fetchAndCache()` starts a request under the new
+ * generation, which is free to publish.
+ *
+ * `pendingRefresh` de-dupes concurrent callers of THIS function the same
+ * way `pendingRequest` de-dupes concurrent fetches: N components all
+ * invalidating within the same synchronous `cart::updated` dispatch share
+ * one refresh chain and therefore, ultimately, one fresh HTTP request.
+ *
+ * That sharing window is deliberately NARROW — it closes the instant the
+ * fresh request goes out, NOT when it comes back. Holding it open for the
+ * whole round trip silently coalesced two DIFFERENT cart mutations into one
+ * refresh: the second `cart::updated` got handed the first one's promise, so
+ * it never bumped `generation` and never issued a request, and the response
+ * that eventually published had been asked for BEFORE the second mutation
+ * happened. The cart then sat on pre-mutation gift data — a merged line
+ * showing yesterday's paid quantity beside yesterday's corrected total —
+ * until some later mutation happened to come along. A shopper clicking "+"
+ * twice inside one round trip is all it took.
+ */
+export function refreshCartFreeGifts() {
+    if (pendingRefresh)
+        return pendingRefresh;
+    generation++;
+    itemsCache = null;
+    countCache = null;
+    isAuthoritative = false;
+    // This invalidation already covers whatever id the cart has now.
+    cacheIdentity = readCartIdentity();
+    const priorRequest = pendingRequest ?? Promise.resolve();
+    const startFreshRequest = () => {
+        // Sharing ends here: everything that invalidated up to this point is
+        // described by the request about to go out, and everything after it is not.
+        if (pendingRefresh === refresh)
+            pendingRefresh = null;
+        return fetchAndCache();
+    };
+    // `.then(f, f)` — a prior request that REJECTED still has to be waited out
+    // before the replacement is issued, or the two overlap.
+    const refresh = priorRequest
+        .then(startFreshRequest, startFreshRequest)
+        .finally(() => {
+        // Only ever clear OUR slot. A later refresh may already own it (it can
+        // only have taken it after `startFreshRequest` released it), and nulling
+        // that one would un-dedupe its same-tick callers.
+        if (pendingRefresh === refresh)
+            pendingRefresh = null;
+    });
+    pendingRefresh = refresh;
+    return refresh;
+}
+/** @internal exported for tests only — resets module-level state between specs. */
+export function __resetCartFreeGiftsForTests() {
+    itemsCache = null;
+    countCache = null;
+    isAuthoritative = false;
+    pendingRequest = null;
+    pendingRefresh = null;
+    generation = 0;
+    cacheIdentity = undefined;
+}