@autobusal/providers 1.40.6 → 1.40.7

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.40.7 (2026-08-28)
+
+- useReferralTouch: the web finally reads ?ref= - touch on landing, token in localStorage (referral_token field: the BFF strips top-level token); storedReferral() exported for checkout replay.
+
 ## 1.40.6 (2026-08-26)
 
 - settings types: addons gains `flex` and `seats` entries (both optional).

package/Setup/Setup.tsx

@@ -2,6 +2,7 @@ import Preload from './Preload';
 import languages from './languages';
 import analytics from './analytics';
 import useUserBootstrap from './useUserBootstrap';
+import useReferralTouch from './useReferralTouch';
 import { useGetSettings, useGetMenu } from '../services';
 
 interface Props {
@@ -15,6 +16,10 @@ const Setup = ({ type, children }: Props): JSX.Element => {
   useGetMenu();
   useUserBootstrap();
 
+  // records ?ref= arrivals so checkout can attribute the affiliate - see
+  // the hook for why this is the web's only referral read
+  useReferralTouch();
+
   languages(type, data.preferences.languages.default, data.preferences.languages.available);
 
   // Edited: Ferjolt Ozuni - Date: 2026-08-01

package/Setup/useReferralTouch.ts

@@ -0,0 +1,97 @@
+import { useEffect } from 'react';
+import apiClient from '../Queries/apiClient';
+
+/**
+ * The web half of referral attribution (P4/P8).
+ *
+ * Edited: Claude - Date: 2026-08-28
+ *
+ * The backend has carried the whole pipeline since P4 - POST
+ * /api/referrals/touch mints a token, Orders\Make replays it as `referral`
+ * and Attribution stamps the order - but only the MOBILE app ever called
+ * it: nothing on the web read ?ref= at all, so a shared link or an
+ * embedded search widget (P8) could never pay its affiliate. This hook is
+ * that missing read.
+ *
+ * Fired once per app mount, and only when ?ref= is actually present -
+ * the endpoint writes a row and is throttled, so it must never become a
+ * page-view beacon (the same reasoning that kept it out of /settings/get
+ * server-side). A NEW code overwrites a stored touch: last shared link
+ * wins, which is the only order two competing affiliates would both
+ * recognise as fair.
+ *
+ * The token is stored, not the code: the token is what checkout replays
+ * (routes-order usePostOrder), and the server already knows everything
+ * else. localStorage survives the tab - a visitor who arrives from a
+ * partner site today and buys tomorrow still attributes, up to the
+ * server-declared expiry, which is stored alongside so the client never
+ * replays a token the server would ignore.
+ *
+ * An unknown or retired code answers 404 and stores nothing - a token the
+ * checkout cannot use is worse than none. Failures are silent: attribution
+ * is the affiliate's concern, never the buyer's problem.
+ */
+const STORAGE_KEY = 'referral';
+
+export interface StoredReferral {
+  token: string
+  expires_at: string
+}
+
+export const storedReferral = (): (StoredReferral | null) => {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+
+    if (raw === null) {
+      return null;
+    }
+
+    const parsed = JSON.parse(raw) as StoredReferral;
+
+    if (!parsed.token || !parsed.expires_at || new Date(parsed.expires_at) <= new Date()) {
+      localStorage.removeItem(STORAGE_KEY);
+
+      return null;
+    }
+
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+const useReferralTouch = (): void => {
+  useEffect(() => {
+    const code = new URLSearchParams(window.location.search).get('ref');
+
+    if (code === null || code.trim() === '') {
+      return;
+    }
+
+    apiClient
+      .post('/api/referrals/touch', { code: code.trim() })
+      .then(response => {
+        // `referral_token` first: the BFF strips any top-level `token` from
+        // proxied JSON (it looks exactly like a leaked bearer), so the web
+        // reads the duplicate field the API added for it. Bearer-mode
+        // clients see both; `token` alone is the pre-rename mobile wire.
+        const data = response?.data ?? {};
+        const token = data.referral_token ?? data.token;
+        const expires_at = data.expires_at;
+
+        if (token && expires_at) {
+          try {
+            localStorage.setItem(STORAGE_KEY, JSON.stringify({ token, expires_at }));
+          } catch {
+            // storage unavailable - the visit still works, it just cannot attribute
+          }
+        }
+      })
+      .catch(() => {
+        // dead code, throttle, or offline - nothing to store, nothing to say
+      });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+};
+
+export default useReferralTouch;

package/index.ts

@@ -1,5 +1,6 @@
 import Providers from './Providers';
 import apiClient, { isBffMode } from './Queries/apiClient';
+import { storedReferral } from './Setup/useReferralTouch';
 import ErrorBoundary from './Errors/ErrorBoundary';
 import Message from './Errors/Message';
 import useMenuStore from './stores/menu';
@@ -7,6 +8,7 @@ import { useUserStore } from './stores/user';
 import registerStaleChunkRecovery from './Setup/staleChunk';
 
 export {
+  storedReferral,
   apiClient,
   isBffMode,
   ErrorBoundary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/providers",
-  "version": "1.40.6",
+  "version": "1.40.7",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"