@shoppexio/storefront 1.0.77 → 1.0.79

package/dist/index.d.cts

@@ -591,6 +591,33 @@ interface AffiliateValidation {
     discount_active: boolean;
     discount_percent: number;
     message?: string;
+    /**
+     * The attribution policy that governs this code (ADR-0067).
+     *
+     * Absent when the code did not resolve, or when an older API answered. A
+     * caller storing the code itself must apply these rather than the 30-day
+     * last-click default, or a first-click tier and any non-30-day window are
+     * silently lost.
+     */
+    attribution_mode?: 'LAST_CLICK' | 'FIRST_CLICK';
+    attribution_window_days?: number;
+    /**
+     * The policy of the attribution the browser already holds, when one was sent.
+     * Null when that code no longer resolves — the stored mode is then the only
+     * information left.
+     */
+    held_attribution_mode?: 'LAST_CLICK' | 'FIRST_CLICK' | null;
+    /**
+     * `applyAffiliateCode` only: whether the code you passed is the one now
+     * attributed.
+     *
+     * False when an unexpired first-click attribution kept the sale — the code
+     * you passed is still valid, it just did not win. `affiliate_code` then
+     * carries the code that DID, because the documented integration feeds that
+     * field straight into `checkout({ affiliateCode })` and an explicit checkout
+     * code overrides storage.
+     */
+    applied?: boolean;
 }
 interface ProductGroup {
     id?: string;
@@ -1576,7 +1603,26 @@ interface SearchOptions {
 declare function searchCatalogItems(query: string, options?: SearchOptions): Promise<SDKResponse<StorefrontCatalogSearchItem[]>>;
 declare function searchProducts(query: string, options?: SearchOptions): Promise<SDKResponse<Product[]>>;
 
-declare function setAffiliateCode(code: string | null | undefined, ttlDays?: number): string | null;
+type AffiliateAttributionMode = 'LAST_CLICK' | 'FIRST_CLICK';
+declare function setAffiliateCode(code: string | null | undefined, ttlDays?: number, mode?: AffiliateAttributionMode): string | null;
+/**
+ * The stored attribution, or null when nothing valid is held.
+ *
+ * Unlike `getAffiliateCode()` this also reports the mode the entry was written
+ * under, which is what `captureAffiliateFromUrl` needs BEFORE it decides
+ * whether it may overwrite.
+ */
+declare function getStoredAffiliate(): {
+    code: string;
+    mode: AffiliateAttributionMode;
+    windowDays: number;
+    /**
+     * When this entry expires, as written. Reported so a hold that has to be put
+     * back after an early overwrite keeps its original expiry — the window runs
+     * from the click that earned it, not from the landing that failed to take it.
+     */
+    expiresAt: number;
+} | null;
 declare function clearAffiliateCode(): void;
 declare function getAffiliateCode(): string | null;
 declare function trackAffiliateEvent(eventType: 'add_to_cart' | 'checkout_started', options?: {
@@ -1597,13 +1643,44 @@ declare function trackAffiliateEvent(eventType: 'add_to_cart' | 'checkout_starte
     dedupeKey?: string;
 }): Promise<void>;
 declare function validateAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
+/**
+ * Validate a manually entered code and store it (ADR-0067).
+ *
+ * Attribution is governed by the same rules as a `?ref=` landing, deliberately:
+ * a themed "apply code" box must not be a way around first-click, or the rule
+ * is bypassed by any storefront that offers one. So a still-protected hold
+ * keeps the sale, and the stored entry always carries the mode and window the
+ * server just reported — the old unconditional `setAffiliateCode(code)` wrote
+ * a 30-day last-click entry whatever the shop or tier had configured.
+ *
+ * The result reports what is now ATTRIBUTED, not merely what was validated:
+ * `affiliate_code` carries the winning code and `applied` says whether that is
+ * the one you passed. The documented integration hands `affiliate_code`
+ * straight to `checkout({ affiliateCode })`, and an explicit checkout code
+ * overrides storage — so returning the losing code here would credit it and
+ * walk right around the hold this function just honoured.
+ */
 declare function applyAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
 /**
- * Capture an affiliate code from the current URL and store it for 30 days (last-click).
+ * Capture an affiliate code from the current URL and store it (ADR-0067).
  *
  * Example:
  * - URL: https://mystore.com/product/abc?ref=deadbeef
  * - captureAffiliateFromUrl() stores "deadbeef" and returns it.
+ *
+ * Under LAST_CLICK (the default, and the only behaviour before ADR-0067) a new
+ * `?ref=` replaces whatever was stored. Under FIRST_CLICK an existing,
+ * unexpired attribution wins and the new code is NOT stored — the landing is
+ * still reported to the server so the affiliate's click statistics stay
+ * honest, but the credit stays with whoever was there first.
+ *
+ * The mode comes from the server, which means the FIRST landing in a browser
+ * can never be blocked by it — correct, because there is nothing to protect
+ * yet. From then on the mode travels with the stored entry.
+ *
+ * Enforcement is client-side. A buyer who edits localStorage can re-attribute
+ * their own visit; this is the same trust level as the window itself and must
+ * not be presented to merchants as fraud protection.
  */
 declare function captureAffiliateFromUrl(param?: string): Promise<string | null>;
 
@@ -1926,6 +2003,7 @@ declare const shoppex: {
     validateAffiliateCode: typeof validateAffiliateCode;
     applyAffiliateCode: typeof applyAffiliateCode;
     getAffiliateCode: typeof getAffiliateCode;
+    getStoredAffiliate: typeof getStoredAffiliate;
     setAffiliateCode: typeof setAffiliateCode;
     clearAffiliateCode: typeof clearAffiliateCode;
     trackAffiliateEvent: typeof trackAffiliateEvent;

package/dist/index.d.ts

@@ -591,6 +591,33 @@ interface AffiliateValidation {
     discount_active: boolean;
     discount_percent: number;
     message?: string;
+    /**
+     * The attribution policy that governs this code (ADR-0067).
+     *
+     * Absent when the code did not resolve, or when an older API answered. A
+     * caller storing the code itself must apply these rather than the 30-day
+     * last-click default, or a first-click tier and any non-30-day window are
+     * silently lost.
+     */
+    attribution_mode?: 'LAST_CLICK' | 'FIRST_CLICK';
+    attribution_window_days?: number;
+    /**
+     * The policy of the attribution the browser already holds, when one was sent.
+     * Null when that code no longer resolves — the stored mode is then the only
+     * information left.
+     */
+    held_attribution_mode?: 'LAST_CLICK' | 'FIRST_CLICK' | null;
+    /**
+     * `applyAffiliateCode` only: whether the code you passed is the one now
+     * attributed.
+     *
+     * False when an unexpired first-click attribution kept the sale — the code
+     * you passed is still valid, it just did not win. `affiliate_code` then
+     * carries the code that DID, because the documented integration feeds that
+     * field straight into `checkout({ affiliateCode })` and an explicit checkout
+     * code overrides storage.
+     */
+    applied?: boolean;
 }
 interface ProductGroup {
     id?: string;
@@ -1576,7 +1603,26 @@ interface SearchOptions {
 declare function searchCatalogItems(query: string, options?: SearchOptions): Promise<SDKResponse<StorefrontCatalogSearchItem[]>>;
 declare function searchProducts(query: string, options?: SearchOptions): Promise<SDKResponse<Product[]>>;
 
-declare function setAffiliateCode(code: string | null | undefined, ttlDays?: number): string | null;
+type AffiliateAttributionMode = 'LAST_CLICK' | 'FIRST_CLICK';
+declare function setAffiliateCode(code: string | null | undefined, ttlDays?: number, mode?: AffiliateAttributionMode): string | null;
+/**
+ * The stored attribution, or null when nothing valid is held.
+ *
+ * Unlike `getAffiliateCode()` this also reports the mode the entry was written
+ * under, which is what `captureAffiliateFromUrl` needs BEFORE it decides
+ * whether it may overwrite.
+ */
+declare function getStoredAffiliate(): {
+    code: string;
+    mode: AffiliateAttributionMode;
+    windowDays: number;
+    /**
+     * When this entry expires, as written. Reported so a hold that has to be put
+     * back after an early overwrite keeps its original expiry — the window runs
+     * from the click that earned it, not from the landing that failed to take it.
+     */
+    expiresAt: number;
+} | null;
 declare function clearAffiliateCode(): void;
 declare function getAffiliateCode(): string | null;
 declare function trackAffiliateEvent(eventType: 'add_to_cart' | 'checkout_started', options?: {
@@ -1597,13 +1643,44 @@ declare function trackAffiliateEvent(eventType: 'add_to_cart' | 'checkout_starte
     dedupeKey?: string;
 }): Promise<void>;
 declare function validateAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
+/**
+ * Validate a manually entered code and store it (ADR-0067).
+ *
+ * Attribution is governed by the same rules as a `?ref=` landing, deliberately:
+ * a themed "apply code" box must not be a way around first-click, or the rule
+ * is bypassed by any storefront that offers one. So a still-protected hold
+ * keeps the sale, and the stored entry always carries the mode and window the
+ * server just reported — the old unconditional `setAffiliateCode(code)` wrote
+ * a 30-day last-click entry whatever the shop or tier had configured.
+ *
+ * The result reports what is now ATTRIBUTED, not merely what was validated:
+ * `affiliate_code` carries the winning code and `applied` says whether that is
+ * the one you passed. The documented integration hands `affiliate_code`
+ * straight to `checkout({ affiliateCode })`, and an explicit checkout code
+ * overrides storage — so returning the losing code here would credit it and
+ * walk right around the hold this function just honoured.
+ */
 declare function applyAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
 /**
- * Capture an affiliate code from the current URL and store it for 30 days (last-click).
+ * Capture an affiliate code from the current URL and store it (ADR-0067).
  *
  * Example:
  * - URL: https://mystore.com/product/abc?ref=deadbeef
  * - captureAffiliateFromUrl() stores "deadbeef" and returns it.
+ *
+ * Under LAST_CLICK (the default, and the only behaviour before ADR-0067) a new
+ * `?ref=` replaces whatever was stored. Under FIRST_CLICK an existing,
+ * unexpired attribution wins and the new code is NOT stored — the landing is
+ * still reported to the server so the affiliate's click statistics stay
+ * honest, but the credit stays with whoever was there first.
+ *
+ * The mode comes from the server, which means the FIRST landing in a browser
+ * can never be blocked by it — correct, because there is nothing to protect
+ * yet. From then on the mode travels with the stored entry.
+ *
+ * Enforcement is client-side. A buyer who edits localStorage can re-attribute
+ * their own visit; this is the same trust level as the window itself and must
+ * not be presented to merchants as fraud protection.
  */
 declare function captureAffiliateFromUrl(param?: string): Promise<string | null>;
 
@@ -1926,6 +2003,7 @@ declare const shoppex: {
     validateAffiliateCode: typeof validateAffiliateCode;
     applyAffiliateCode: typeof applyAffiliateCode;
     getAffiliateCode: typeof getAffiliateCode;
+    getStoredAffiliate: typeof getStoredAffiliate;
     setAffiliateCode: typeof setAffiliateCode;
     clearAffiliateCode: typeof clearAffiliateCode;
     trackAffiliateEvent: typeof trackAffiliateEvent;

package/dist/index.js

@@ -3890,6 +3890,9 @@ var SESSION_STORAGE_KEY = "shoppex:affiliate_session:v1";
 var DEFAULT_TTL_DAYS = 30;
 var FALLBACK_SESSION_KEY_LENGTH = 24;
 var SESSION_KEY_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+function normalizeMode(value) {
+  return value === "FIRST_CLICK" ? "FIRST_CLICK" : "LAST_CLICK";
+}
 function nowMs() {
   return Date.now();
 }
@@ -3907,7 +3910,7 @@ function safeRead() {
     if (!raw) return null;
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed.code !== "string" || typeof parsed.expiresAt !== "number") return null;
-    return parsed;
+    return parsed.mode === void 0 ? parsed : { ...parsed, mode: normalizeMode(parsed.mode) };
   } catch {
     return null;
   }
@@ -3919,15 +3922,35 @@ function safeWrite(value) {
   } catch {
   }
 }
-function setAffiliateCode(code, ttlDays = DEFAULT_TTL_DAYS) {
+function restoreStoredAffiliate(value) {
+  safeWrite(value);
+}
+function setAffiliateCode(code, ttlDays = DEFAULT_TTL_DAYS, mode) {
   const normalized = normalizeAffiliateCode(code);
   if (!normalized) {
     clearAffiliateCode();
     return null;
   }
-  safeWrite({ code: normalized, expiresAt: nowMs() + ttlMs(ttlDays) });
+  safeWrite({
+    code: normalized,
+    expiresAt: nowMs() + ttlMs(ttlDays),
+    windowDays: ttlDays,
+    ...mode ? { mode } : {}
+  });
   return normalized;
 }
+function getStoredAffiliate() {
+  const stored = safeRead();
+  if (!stored) return null;
+  if (stored.expiresAt <= nowMs()) {
+    clearAffiliateCode();
+    return null;
+  }
+  const code = normalizeAffiliateCode(stored.code);
+  if (!code) return null;
+  const windowDays = typeof stored.windowDays === "number" && stored.windowDays > 0 ? stored.windowDays : DEFAULT_TTL_DAYS;
+  return { code, mode: normalizeMode(stored.mode), windowDays, expiresAt: stored.expiresAt };
+}
 function clearAffiliateCode() {
   if (typeof window === "undefined") return;
   try {
@@ -4017,11 +4040,13 @@ async function validateAffiliateCode(code) {
     };
   }
   const config = getConfig();
+  const held = getStoredAffiliate();
   const response = await post(
     "/v1/storefront/affiliates/resolve",
     {
       shop_slug: config.storeSlug,
-      code: normalizedCode
+      code: normalizedCode,
+      ...held && held.code !== normalizedCode ? { held_code: held.code } : {}
     },
     { retries: 0 }
   );
@@ -4049,15 +4074,36 @@ async function validateAffiliateCode(code) {
       ...response.data.program_enabled !== void 0 ? { program_enabled: response.data.program_enabled } : {},
       affiliate_code: normalizeAffiliateCode(response.data.affiliate_code),
       discount_active: Boolean(response.data.discount_active),
-      discount_percent: Number(response.data.discount_percent ?? 0)
+      discount_percent: Number(response.data.discount_percent ?? 0),
+      // Passed through rather than dropped: a caller that stores the code has
+      // no other way to learn the policy, and defaulting to 30-day last-click
+      // would quietly discard a first-click tier and any custom window.
+      attribution_mode: normalizeMode(response.data.attribution_mode),
+      attribution_window_days: typeof response.data.attribution_window_days === "number" && response.data.attribution_window_days >= 1 ? Math.trunc(response.data.attribution_window_days) : DEFAULT_TTL_DAYS,
+      held_attribution_mode: response.data.held_attribution_mode === "FIRST_CLICK" || response.data.held_attribution_mode === "LAST_CLICK" ? response.data.held_attribution_mode : null
     },
     ...response.message ? { message: response.message } : {}
   };
 }
 async function applyAffiliateCode(code) {
+  const held = getStoredAffiliate();
   const result = await validateAffiliateCode(code);
   if (result.success && result.data?.affiliate_code) {
-    setAffiliateCode(result.data.affiliate_code);
+    const applied = result.data.affiliate_code;
+    const holdsOtherCode = held !== null && held.code !== applied;
+    const heldMode = holdsOtherCode ? result.data.held_attribution_mode ?? held.mode : null;
+    if (heldMode === "FIRST_CLICK" && held) {
+      return {
+        ...result,
+        data: { ...result.data, affiliate_code: held.code, applied: false }
+      };
+    }
+    setAffiliateCode(
+      applied,
+      result.data.attribution_window_days ?? DEFAULT_TTL_DAYS,
+      result.data.attribution_mode
+    );
+    return { ...result, data: { ...result.data, applied: true } };
   }
   return result;
 }
@@ -4073,29 +4119,56 @@ async function captureAffiliateFromUrl(param = "ref") {
   }
   code = normalizeAffiliateCode(code);
   if (!code) return null;
-  setAffiliateCode(code);
+  const held = getStoredAffiliate();
+  const holdsOtherCode = held !== null && held.code !== code;
+  const mayHoldFirstClick = holdsOtherCode && held.mode === "FIRST_CLICK";
+  if (!mayHoldFirstClick) {
+    setAffiliateCode(code, held?.windowDays ?? DEFAULT_TTL_DAYS, held?.mode);
+  }
   if (isInitialized()) {
     try {
       const config = getConfig();
       const res = await post(
         "/v1/storefront/affiliates/attribution",
-        { shop_slug: config.storeSlug, code },
+        {
+          shop_slug: config.storeSlug,
+          code,
+          // Sent so the server can report the policy of the attribution we
+          // already hold. Its mode — not the arriving code's — decides whether
+          // that hold may be released.
+          ...held ? { held_code: held.code } : {}
+        },
         { retries: 0 }
       );
+      const serverMode = res.success && res.data?.attribution_mode ? normalizeMode(res.data.attribution_mode) : null;
+      const serverWindow = res.success && typeof res.data?.attribution_window_days === "number" ? res.data.attribution_window_days : DEFAULT_TTL_DAYS;
+      const heldMode = res.success && res.data?.held_attribution_mode ? normalizeMode(res.data.held_attribution_mode) : null;
+      const holdsFirstClick = holdsOtherCode && (heldMode ?? held?.mode) === "FIRST_CLICK";
+      if (holdsFirstClick && held) {
+        if (!mayHoldFirstClick) {
+          restoreStoredAffiliate({
+            code: held.code,
+            expiresAt: held.expiresAt,
+            windowDays: held.windowDays,
+            mode: heldMode ?? "FIRST_CLICK"
+          });
+        }
+        return held.code;
+      }
       if (res.success && res.data?.accepted && res.data.affiliate_code) {
-        setAffiliateCode(res.data.affiliate_code);
+        setAffiliateCode(res.data.affiliate_code, serverWindow, serverMode ?? void 0);
         return res.data.affiliate_code;
       }
       if (res.success && res.data && res.data.accepted === false) {
         clearAffiliateCode();
         return null;
       }
-      return code;
+      return mayHoldFirstClick ? held.code : code;
     } catch {
-      return code;
+      return mayHoldFirstClick ? held.code : code;
     }
   }
-  return code;
+  return mayHoldFirstClick ? held.code : code;
 }
 
 // ../sdk/src/utils/cart-line-id.ts
@@ -6180,6 +6253,7 @@ var shoppex = {
   validateAffiliateCode,
   applyAffiliateCode,
   getAffiliateCode,
+  getStoredAffiliate,
   setAffiliateCode,
   clearAffiliateCode,
   trackAffiliateEvent,