@salla.sa/twilight-theme-engine 1.0.84 → 1.0.86

package/tailwind/routes/root/beforeLoad.ts.txt

@@ -0,0 +1,354 @@
+import type { QueryClient } from '@tanstack/react-query';
+import { redirect } from '@tanstack/react-router';
+import { createIsomorphicFn } from '@tanstack/react-start';
+import {
+  getCookie,
+  getRequestHeader,
+  getRequestUrl,
+  setCookie,
+} from '@tanstack/react-start/server';
+import type { StoreContext } from '../../api/store';
+import { store as storeApi } from '../../api/store';
+import { apps, type AppSnippet, type AppSettings } from '../../api/apps';
+import { translations } from '../../api/translations';
+import { advertisement } from '../../api/advertisement';
+import { FALLBACK_LOCALE, getLanguageInfo } from '../../providers/locale-constants';
+import { createI18nInstance } from '../../providers/i18n-factory';
+import type { TwilightLocation } from '../../twilight/context';
+import { getTwilightContext, updateTwilightContext } from '../../twilight/context';
+import {
+  AUTH_TOKEN_COOKIE_NAME,
+  extractScopeFromCookies,
+  extractScopeFromUrl,
+  extractTokenFromCookies,
+  resolveRequestScope,
+  sameScope,
+  SCOPE_COOKIE_MAX_AGE,
+  SCOPE_COOKIE_NAME,
+  syncScopeCookie,
+  type ActiveScope,
+} from '../../utils/cookies';
+import { syncSdkLocale, syncSdkThemeVersion } from '../../utils/sdk-helpers';
+import { SettingsError } from '../../utils/errors';
+import { resolveStoreBaseRedirect } from '../../utils/store-identity';
+
+// Reads the `token` cookie from the incoming request on the SERVER. twilightMiddleware
+// extracts the same cookie into a custom ALS, but that ALS does NOT propagate to the
+// route's beforeLoad / React SSR render (they run in a different async scope), so the
+// token must be read again here from the framework's own request context. On the client
+// this is a no-op (the cookie is read from document.cookie below instead). The server
+// import is stripped from the client bundle by createIsomorphicFn.
+const readServerCookieToken = createIsomorphicFn()
+  .server((): string | null => {
+    try {
+      return getCookie(AUTH_TOKEN_COOKIE_NAME) ?? null;
+    } catch {
+      return null;
+    }
+  })
+  .client((): string | null => null);
+
+/**
+ * The scope to write to the `scope` cookie for this request, or null to leave the cookie
+ * as it is.
+ *
+ * Only for a market a `?scope=` URL switched to, and only when the settings were answered
+ * for it: the API falls back to another market when it does not accept the requested one,
+ * and Twig keeps the previous choice then too, rather than recording one the page is not
+ * showing. Its type is the one the settings answered with: a URL names only the id, and
+ * the store-wide type is assumed until the answer says otherwise (a store browsing by
+ * branch or city), so later requests send the type the API matches against.
+ */
+export function scopeCookieUpdate(
+  url: string,
+  cookieHeader: string | null,
+  settings: StoreContext
+): ActiveScope | null {
+  if (!extractScopeFromUrl(url)) return null;
+  const scope = resolveRequestScope(url, cookieHeader);
+  const answered = settings.store?.scope;
+  if (!scope || answered?.id == null || String(answered.id) !== scope.id) return null;
+  const typed = answered.type ? { ...scope, type: answered.type } : scope;
+  return sameScope(extractScopeFromCookies(cookieHeader), typed) ? null : typed;
+}
+
+/**
+ * Gives the request's scope the type its settings answered with, for the rest of this
+ * render, and files the settings and ads under the key the corrected scope makes, so the browser
+ * — which reads the corrected scope from the cookie (see {@link scopeCookieUpdate}) — finds
+ * them dehydrated instead of fetching them again. The entry under the assumed type's key
+ * is removed, so the page carries them once. Server-only; a no-op when the type
+ * already matches or the settings answered another scope.
+ */
+export function alignRequestScopeType(queryClient: QueryClient, settings: StoreContext): void {
+  let scope: ActiveScope | null;
+  try {
+    scope = getTwilightContext().scope;
+  } catch {
+    return;
+  }
+  const answered = settings.store?.scope;
+  if (!scope || !answered?.type || String(answered.id) !== scope.id) return;
+  if (answered.type === scope.type) return;
+  const assumedKey = storeApi.queries.settings().queryKey;
+  const assumedAdsKey = advertisement.queries.list().queryKey;
+  updateTwilightContext({ scope: { ...scope, type: answered.type } });
+  queryClient.setQueryData(storeApi.queries.settings().queryKey, settings);
+  // Moved, not copied: both would be dehydrated, sending the settings twice.
+  queryClient.removeQueries({ queryKey: assumedKey, exact: true });
+  const ads = queryClient.getQueryData(assumedAdsKey);
+  if (ads) queryClient.setQueryData(advertisement.queries.list().queryKey, ads);
+  queryClient.removeQueries({ queryKey: assumedAdsKey, exact: true });
+}
+
+/**
+ * Writes {@link scopeCookieUpdate} to the response. Read from the request itself rather
+ * than the middleware's context, for the same reason as {@link readServerCookieToken}.
+ * Server-only.
+ */
+export const persistRequestScope = createIsomorphicFn()
+  .server((settings: StoreContext): void => {
+    let scope: ActiveScope | null;
+    try {
+      scope = scopeCookieUpdate(
+        String(getRequestUrl()),
+        getRequestHeader('cookie') ?? null,
+        settings
+      );
+    } catch {
+      // Outside a request (prerender): there is no response to write to.
+      return;
+    }
+    if (!scope) return;
+    setCookie(SCOPE_COOKIE_NAME, JSON.stringify(scope), {
+      path: '/',
+      maxAge: SCOPE_COOKIE_MAX_AGE,
+      sameSite: 'lax',
+    });
+  })
+  .client((): void => {});
+
+/** On the server, once the settings are in: {@link alignRequestScopeType}, then {@link persistRequestScope}. */
+function settleRequestScope(queryClient: QueryClient, settings: StoreContext): void {
+  if (typeof window !== 'undefined') return;
+  alignRequestScopeType(queryClient, settings);
+  persistRequestScope(settings);
+}
+
+export interface BeforeLoadResult {
+  settings: StoreContext;
+  locale: string;
+  dir: 'ltr' | 'rtl';
+  authToken: string | null;
+  /** Installed apps' snippets, threaded through the beforeLoad context (and recovered on the
+   *  client via ensureTwilightContextFromMatches) so AppsSnippets can render CDN tags in SSR. */
+  appsSnippets?: AppSnippet[];
+  /** Per-app public `app.*` buckets, threaded the same way so rootHead can install the
+   *  `Salla.appScope` factory inline in the SSR head. */
+  appsSettings?: AppSettings;
+}
+
+/**
+ * The platform's copy for `locale`, with this merchant's own wording over it.
+ *
+ * Returns the platform's copy untouched — and makes no request — unless the
+ * settings say this language has overrides. That gate is the whole reason this
+ * is affordable: the object 404s for most stores, uncached, on the critical
+ * path of an SSR render.
+ *
+ * The entry is found by ISO code rather than by index or key. The API sends
+ * `languages` as an object keyed by **upper-case** ISO, and `storeApi` converts
+ * it to an array on the way through (`languagesToArray`), so neither the
+ * upper-case key nor a position is available here — and matching case-sensitively
+ * on `code` would be a lookup that misses silently, leaving the flag absent and
+ * the feature simply never running.
+ *
+ * Nothing about this is fatal. A failed override read leaves the platform's
+ * copy in place, which is a storefront in the words Salla ships rather than a
+ * storefront that did not render.
+ */
+async function withMerchantTranslations(
+  queryClient: QueryClient,
+  settings: StoreContext,
+  locale: string,
+  common: Awaited<ReturnType<typeof translations.get>>
+): Promise<Awaited<ReturnType<typeof translations.get>>> {
+  const wanted = locale.toLowerCase();
+  const language = settings.languages?.find(
+    (entry) => (entry.iso_code ?? entry.code)?.toLowerCase() === wanted
+  );
+  const storeId = settings.store?.id;
+
+  if (!language?.has_custom_translations || !storeId) return common;
+
+  try {
+    const overrides = await queryClient.ensureQueryData(
+      translations.queries.byStore(storeId, locale)
+    );
+
+    return translations.merge(common, overrides, locale);
+  } catch (error) {
+    console.warn('[salla] merchant translations could not be read; using the platform copy', error);
+    return common;
+  }
+}
+
+export async function rootBeforeLoad(ctx: {
+  params: Record<string, string>;
+  location: TwilightLocation;
+  context: {
+    queryClient: QueryClient;
+    setLocation?: (location: Partial<TwilightLocation>) => void;
+  };
+  serverContext?: {
+    authToken?: string | null;
+  };
+}): Promise<BeforeLoadResult> {
+  const locale = ctx.params.locale || FALLBACK_LOCALE;
+  const { dir } = getLanguageInfo(locale);
+
+  if (ctx.context.setLocation) {
+    ctx.context.setLocation(ctx.location);
+  }
+
+  // Set locale in context before any API calls so interceptor uses correct locale
+  updateTwilightContext({ locale });
+
+  // Re-assert the locale on the Salla SDK on every navigation. The SDK's axios
+  // accept-language header drifts off the route locale (navigator.language default,
+  // account-language override on profile fetch — see syncSdkLocale), which makes
+  // SDK API calls (e.g. the cart's salla.api.cart.details) return wrong-locale data.
+  syncSdkLocale(locale);
+
+  // Mirror the SDK's selected branch into the `scope` cookie. The SDK persists the
+  // selection in localStorage ONLY, so the server — which can only see cookies —
+  // would otherwise compute scope=null for every visitor who picked a branch, and
+  // the dehydrated settings query (keyed on the scope) would never match on the
+  // client. No-op on the server and while the SDK storage API is still hydrating.
+  syncScopeCookie();
+
+  const [settingsResult, translationsResult, snippetsResult, appSettingsResult] = await Promise.all(
+    [
+      ctx.context.queryClient.ensureQueryData(storeApi.queries.settings()),
+      ctx.context.queryClient.ensureQueryData(translations.queries.byLocale(locale)),
+      // Snippets → SSR CDN <script> tags (AppsSnippets.ssrCdnScripts). Non-fatal + logged:
+      // on failure AppsSnippets falls back to its own client-side query for the same data,
+      // so the tags render a paint later instead of being lost for the page load.
+      ctx.context.queryClient.ensureQueryData(apps.queries.snippets()).catch((error): undefined => {
+        console.warn('[salla] apps/snippets prefetch failed; rendering no CDN snippet tags', error);
+        return undefined;
+      }),
+      // Buckets → rootHead installs `Salla.appScope` inline in the SSR head (before any snippet
+      // onReady runs). Non-fatal + logged: the head installs the factory either way, and the
+      // client query seeds the buckets into that install once it resolves.
+      ctx.context.queryClient.ensureQueryData(apps.queries.settings()).catch((error): undefined => {
+        console.warn(
+          '[salla] apps/snippets/settings prefetch failed; appScope buckets unseeded',
+          error
+        );
+        return undefined;
+      }),
+      // Ads → the header's announcement bar renders on the server, so it no longer pushes the
+      // page down when it arrives. Non-fatal: the bar then loads on the client, as before.
+      ctx.context.queryClient
+        .ensureQueryData(advertisement.queries.list())
+        .catch((error): undefined => {
+          console.warn('[salla] advertisements prefetch failed; the ad bar loads late', error);
+          return undefined;
+        }),
+    ]
+  );
+
+  if (!settingsResult) {
+    throw new SettingsError('Failed to load store settings. Make sure VITE_STORE_DOMAIN is set.');
+  }
+
+  // Settings answered for another market name another theme version; the SDK only
+  // read its `s-version-id` at init — see syncSdkThemeVersion.
+  syncSdkThemeVersion(settingsResult.headers);
+
+  settleRequestScope(ctx.context.queryClient, settingsResult);
+
+  // On a host where the store is the root of every URL, a page has one address:
+  // `/<username>/…`. A request that found its store some other way (`?storeId=`,
+  // the preview cookie, `VITE_STORE_DOMAIN`) is sent there now that the settings
+  // say what the username is. A full load rather than a client navigation, because
+  // the router handling this request was built without that root.
+  const storeBaseHref = resolveStoreBaseRedirect(settingsResult.store?.username, ctx.location.href);
+  if (storeBaseHref) {
+    throw redirect({ href: storeBaseHref, reloadDocument: true, replace: true });
+  }
+
+  // The merchant's own wording, laid over the platform's — but only when the
+  // settings say this language has any.
+  //
+  // Sequenced after the `Promise.all` on purpose: the object is keyed by
+  // `settings.store.id`, which the settings query is what produces, so this
+  // cannot join the batch above. The cost of a second round trip is why it is
+  // gated rather than always fetched — see `api/translations.ts` for the two
+  // corrections that shape led to.
+  const messages = await withMerchantTranslations(
+    ctx.context.queryClient,
+    settingsResult,
+    locale,
+    translationsResult
+  );
+
+  // Create i18n instance with loaded translations
+  const i18n = createI18nInstance(locale, messages ?? undefined);
+
+  // Resolve authToken with fallback chain:
+  // 1. SSR context (from middleware extracting cookies on server)
+  // 2. The twilight context token. On the SERVER this is the token twilightMiddleware
+  //    extracted from the `token` cookie into the request ALS — reading it here is
+  //    essential, otherwise this loader's updateTwilightContext() below would
+  //    overwrite the middleware's token with null and every SSR render (e.g. the
+  //    account hub) would be unauthenticated. On the CLIENT it's the clientStore
+  //    token from hydration or a previous navigation.
+  // 3. The `token` cookie read directly — client fallback when clientStore is empty
+  //    and salla.storage hasn't hydrated yet.
+  // 4. Salla SDK storage (salla.storage.get('token'))
+  let existingToken: string | null = null;
+  try {
+    existingToken = getTwilightContext().authToken;
+  } catch {
+    // No request context (e.g. server call outside the middleware ALS) — fall through.
+    existingToken = null;
+  }
+  const cookieToken =
+    typeof document !== 'undefined'
+      ? extractTokenFromCookies(document.cookie, AUTH_TOKEN_COOKIE_NAME)
+      : null;
+  const sallaToken =
+    typeof window !== 'undefined' && typeof window.salla?.storage?.get === 'function'
+      ? (window.salla.storage.get(AUTH_TOKEN_COOKIE_NAME) as string | null)
+      : null;
+  const serverCookieToken = readServerCookieToken();
+  const authToken =
+    ctx.serverContext?.authToken ??
+    serverCookieToken ??
+    existingToken ??
+    cookieToken ??
+    sallaToken ??
+    null;
+
+  updateTwilightContext({
+    queryClient: ctx.context.queryClient,
+    settings: settingsResult,
+    locale,
+    location: ctx.location,
+    i18n,
+    authToken,
+    appsSnippets: snippetsResult,
+    appsSettings: appSettingsResult,
+  });
+
+  return {
+    settings: settingsResult,
+    locale,
+    dir,
+    authToken,
+    appsSnippets: snippetsResult,
+    appsSettings: appSettingsResult,
+  };
+}