orionplace-react 0.5.0 → 0.6.1

package/templates/app/_storefront/CategoryPage.tsx

@@ -4,7 +4,8 @@ import { StorefrontCategory } from '@/components/orionplace/categories/Storefron
 import { useOrionplaceStorefront } from '@/hooks/useOrionplaceStorefront';
 import { useOrionplaceCatalog } from '@/providers/OrionplaceProvider';
 import { catalogBranchIds } from '@/lib/orionplace/catalog';
-import type { ProductSearchPage } from '@/lib/orionplace/productSearch';
+import type { ProductListLocation } from '@/lib/orionplace/productListLocation';
+import type { ProductListPage } from '@/lib/orionplace/productSearch';
 import { useProductSearch } from './useProductSearch';
 import { useStorefrontNavigation } from './useStorefrontNavigation';
 
@@ -12,10 +13,12 @@ export function CategoryPage({
   categoryId,
   initial,
   initialError = '',
+  location,
 }: {
   categoryId: number;
-  initial?: ProductSearchPage;
+  initial?: ProductListPage;
   initialError?: string;
+  location?: ProductListLocation;
 }) {
   const navigation = useStorefrontNavigation();
   const controls   = useOrionplaceStorefront();
@@ -24,6 +27,7 @@ export function CategoryPage({
     { categoryId, categoryIds: catalogBranchIds(catalog, categoryId) },
     initial,
     initialError,
+    { location },
   );
   const pagination = search.data?.products?.rpag;
 

package/templates/app/_storefront/SearchPage.tsx

@@ -15,10 +15,11 @@ import { OrionplaceEmptyState } from '@/components/orionplace/shared/OrionplaceE
 import { useOrionplaceStorefront } from '@/hooks/useOrionplaceStorefront';
 import { browseLabels } from '@/lib/orionplace/browseLabels';
 import { featuredLabels } from '@/lib/orionplace/featuredLabels';
+import type { ProductListLocation } from '@/lib/orionplace/productListLocation';
 import {
   productSearchHeading,
   productSearchTrail,
-  type ProductSearchPage as ProductSearchData,
+  type ProductListPage as ProductSearchData,
   type ProductSearchScope,
 } from '@/lib/orionplace/productSearch';
 import { useProductSearch } from './useProductSearch';
@@ -41,10 +42,12 @@ export function SearchPage({
   scope,
   initial,
   initialError = '',
+  location,
 }: {
   scope: ProductSearchScope;
   initial?: ProductSearchData;
   initialError?: string;
+  location?: ProductListLocation;
 }) {
   const locale     = useOrionplaceSelections((state) => state.localeCode);
   const labels     = browseLabels(locale);
@@ -55,7 +58,9 @@ export function SearchPage({
   const guest      = Boolean(scope.featured && ready && !init?.is_authenticated);
   const navigation = useStorefrontNavigation();
   const controls   = useOrionplaceStorefront();
-  const search     = useProductSearch(scope, initial, initialError);
+  const search     = useProductSearch(scope, initial, initialError, {
+    location,
+  });
   const pagination = search.data?.products?.rpag;
   const api = useOrionplaceApi();
   const directory = directoryLabels(locale);

package/templates/app/_storefront/SellersPage.tsx

@@ -12,7 +12,8 @@ import { useOrionplaceApi } from '@/hooks/useOrionplaceApi';
 import { useOrionplaceReviews } from '@/hooks/useOrionplaceReviews';
 import { useOrionplaceStorefront } from '@/hooks/useOrionplaceStorefront';
 import { directoryLabels } from '@/lib/orionplace/directoryLabels';
-import type { ProductSearchPage } from '@/lib/orionplace/productSearch';
+import type { ProductListLocation } from '@/lib/orionplace/productListLocation';
+import type { ProductListPage } from '@/lib/orionplace/productSearch';
 import { useOrionplaceSelections } from '@/providers/OrionplaceProvider';
 import { useProductSearch } from './useProductSearch';
 import { useStorefrontNavigation } from './useStorefrontNavigation';
@@ -25,11 +26,13 @@ export function SellersPage({
   initial,
   initialProducts,
   initialError = '',
+  location,
 }: {
   sellerId?: number;
   initial?: SellerPageData;
-  initialProducts?: ProductSearchPage;
+  initialProducts?: ProductListPage;
   initialError?: string;
+  location?: ProductListLocation;
 }) {
   const api = useOrionplaceApi();
   const locale = useOrionplaceSelections((state) => state.localeCode);
@@ -38,6 +41,7 @@ export function SellersPage({
   const labels = directoryLabels(locale);
   const search = useProductSearch({ sellerId }, initialProducts, '', {
     scrollToTop: false,
+    location,
   });
   const reviews = useOrionplaceReviews({
     sellerId,
@@ -112,7 +116,9 @@ export function SellersPage({
               products={search.data?.products?.data ?? []}
               facets={search.facets}
               filters={search.filters}
-              fixedFilters={['product_owner']}
+              // The seller scope fixes the seller and its rating, as in the
+              // Nuxt and Svelte packages.
+              fixedFilters={['product_owner', 'owner_rating_from']}
               page={search.page}
               pages={pagination?.pages}
               total={total}

package/templates/app/_storefront/storefrontRoutes.tsx

@@ -67,10 +67,11 @@ import {
   type ManufacturerSearchData,
 } from '@/lib/orionplace/manufacturerDirectory';
 import {
-  loadProductSearch,
-  type ProductSearchPage,
+  loadProductListPage,
+  type ProductListPage,
   type ProductSearchScope,
 } from '@/lib/orionplace/productSearch';
+import { productListLocationFromQuery } from '@/lib/orionplace/productListLocation';
 import {
   emptySellerFilters,
   sellerDirectoryRequest,
@@ -212,8 +213,11 @@ const routes: Record<string, Loader> = {
       !scope.query ||
       scope.query.length >= 3 ||
       Object.values(scope).some((value) => typeof value === 'number');
+    const location                  = productListLocationFromQuery(query);
     const { initial, initialError } = searched
-      ? await initialData(context, (api) => loadProductSearch(api, scope))
+      ? await initialData(context, (api) =>
+          loadProductListPage(api, scope, location.filters, location.page),
+        )
       : { initial: undefined, initialError: '' };
     return {
       page: (
@@ -221,6 +225,7 @@ const routes: Record<string, Loader> = {
           scope={scope}
           initial={initial}
           initialError={initialError}
+          location={location}
         />
       ),
     };
@@ -254,11 +259,17 @@ const routes: Record<string, Loader> = {
     if (!categoryId || !findCatalogCategory(catalog, categoryId)) {
       return { notFound: true };
     }
+    const location                  = productListLocationFromQuery(context.query);
     const { initial, initialError } = await initialData(context, (api) =>
-      loadProductSearch(api, {
-        categoryId,
-        categoryIds: catalogBranchIds(catalog, categoryId),
-      }),
+      loadProductListPage(
+        api,
+        {
+          categoryId,
+          categoryIds: catalogBranchIds(catalog, categoryId),
+        },
+        location.filters,
+        location.page,
+      ),
     );
     return {
       page: (
@@ -266,6 +277,7 @@ const routes: Record<string, Loader> = {
           categoryId={categoryId}
           initial={initial}
           initialError={initialError}
+          location={location}
         />
       ),
     };
@@ -275,8 +287,9 @@ const routes: Record<string, Loader> = {
 
   '/featured': async (context) => {
     const scope                     = { featured: true } as const;
+    const location                  = productListLocationFromQuery(context.query);
     const { initial, initialError } = await initialData(context, (api) =>
-      loadProductSearch(api, scope),
+      loadProductListPage(api, scope, location.filters, location.page),
     );
     return {
       page: (
@@ -284,6 +297,7 @@ const routes: Record<string, Loader> = {
           scope={scope}
           initial={initial}
           initialError={initialError}
+          location={location}
         />
       ),
     };
@@ -487,8 +501,9 @@ const routes: Record<string, Loader> = {
       return { redirect: `/catalog?locale=${encodeURIComponent(text(query.locale))}` };
     }
     const sellerId  = positive(text(query.seller) || undefined);
+    const location  = productListLocationFromQuery(query);
     let initial;
-    let initialProducts: ProductSearchPage | undefined;
+    let initialProducts: ProductListPage | undefined;
     let initialError = '';
     try {
       const api = await context.api();
@@ -499,7 +514,12 @@ const routes: Record<string, Loader> = {
           : sellerDirectoryRequest(emptySellerFilters(), 1),
       );
       if (sellerId && initial.sellers.data[0]) {
-        initialProducts = await loadProductSearch(api, { sellerId }, {}, 1);
+        initialProducts = await loadProductListPage(
+          api,
+          { sellerId },
+          location.filters,
+          location.page,
+        );
       }
     } catch (reason) {
       initialError = await context.errorText(reason);
@@ -511,6 +531,7 @@ const routes: Record<string, Loader> = {
           initial={initial}
           initialProducts={initialProducts}
           initialError={initialError}
+          location={location}
         />
       ),
     };

package/templates/app/_storefront/useProductSearch.ts

@@ -9,14 +9,19 @@ import {
 import type { ProductFacetSelection } from '@/interfaces/orionplace/products/IProductSearchFacets';
 import { useOrionplaceApi } from '@/hooks/useOrionplaceApi';
 import {
-  loadProductSearch,
-  productSearchFacetData,
-  type ProductSearchPage,
+  loadProductListPage,
+  productListFacetData,
+  type ProductListPage,
   type ProductSearchScope,
 } from '@/lib/orionplace/productSearch';
-import { initialSearchFacets } from '@/lib/orionplace/searchFilters';
 import { apiErrorMessage } from '@/lib/orionplace/api';
 import { featureLabels } from '@/lib/orionplace/featureLabels';
+import {
+  productListLocationFromQuery,
+  productListLocationQuery,
+  sameProductListLocation,
+  type ProductListLocation,
+} from '@/lib/orionplace/productListLocation';
 
 /*
  * A search needs a category, a fixed scope or a 3-letter query, as in the
@@ -30,35 +35,77 @@ function searchable(scope: ProductSearchScope) {
   );
 }
 
+const firstListPage: ProductListLocation = { page: 1, filters: {} };
+
+function listSignature(location: ProductListLocation) {
+  return JSON.stringify(productListLocationQuery({}, location));
+}
+
+function addressQuery(): Record<string, string> {
+  return Object.fromEntries(new URL(window.location.href).searchParams);
+}
+
 /*
  * `scrollToTop: false` keeps the scroll position on a page turn, for a page
  * whose pagination scrolls to its own list (the seller page).
+ * `location` is the page and filters `initial` was loaded with (the URL of the
+ * server render). The page and filters stay in the URL, so Back from a
+ * product or a reload opens the list the visitor left; `rememberInAddress:
+ * false` keeps them out of it.
  */
 export function useProductSearch(
   scope: ProductSearchScope,
-  initial?: ProductSearchPage,
+  initial?: ProductListPage,
   initialError = '',
-  options: { scrollToTop?: boolean } = {},
+  options: {
+    scrollToTop?: boolean;
+    location?: ProductListLocation;
+    rememberInAddress?: boolean;
+  } = {},
 ) {
+  const remember              = options.rememberInAddress !== false;
+  const serverLocation        = remember
+    ? (options.location ?? firstListPage)
+    : firstListPage;
+  // The page and filters in the URL; the server render reads them from the
+  // request, the browser from the address bar.
+  function addressLocation(): ProductListLocation {
+    if (!remember) {
+      return firstListPage;
+    }
+    return typeof window === 'undefined'
+      ? serverLocation
+      : productListLocationFromQuery(addressQuery());
+  }
+  // `initial` belongs to the URL it was loaded for.
+  function fromServer(location: ProductListLocation) {
+    return listSignature(location) === listSignature(serverLocation);
+  }
+  const [opening]             = useState(addressLocation);
+  const openedFromServer      = fromServer(opening);
   const api                   = useOrionplaceApi();
   const locale                = useOrionplaceSelections(
     (state) => state.localeCode,
   );
   const productsStore         = useOrionplaceProductsStore();
   const browseStore           = useOrionplaceBrowseStore();
-  const [data, setData]       = useState(initial);
-  const [filters, setFilters] = useState<ProductFacetSelection>({});
-  const [page, setPage]       = useState(initial?.products?.rpag.page ?? 1);
+  const [data, setData]       = useState(openedFromServer ? initial : undefined);
+  const [filters, setFilters] = useState<ProductFacetSelection>(opening.filters);
+  const [page, setPage]       = useState(
+    openedFromServer ? (initial?.products?.rpag.page ?? opening.page) : opening.page,
+  );
   const [pending, setPending] = useState(false);
-  const [loaded, setLoaded]   = useState(Boolean(initial));
-  const [error, setError]     = useState(initialError);
+  const [loaded, setLoaded]   = useState(openedFromServer && Boolean(initial));
+  const [error, setError]     = useState(openedFromServer ? initialError : '');
   // Filter choices of the scope's first response; a filtered response must
   // not shrink them, so the visitor can still pick another seller or price.
-  const [facets, setFacets]   = useState(() => productSearchFacetData(initial));
+  const [facets, setFacets]   = useState(() =>
+    productListFacetData(openedFromServer ? initial : undefined),
+  );
   const request               = useRef<AbortController | undefined>(undefined);
   const signature             = JSON.stringify(scope);
 
-  function apply(next: ProductSearchPage) {
+  function apply(next: ProductListPage) {
     // The backend sends the unfiltered total with the first page only;
     // later pages keep it, as in the Nuxt and Svelte packages.
     setData((previous) =>
@@ -80,10 +127,10 @@ export function useProductSearch(
         : next,
     );
     setLoaded(true);
-    const incoming = productSearchFacetData(next);
+    const incoming = productListFacetData(next);
     if (incoming) {
       browseStore.getState().preserveSearchFacets(incoming);
-      setFacets((previous) => initialSearchFacets(previous, incoming));
+      setFacets((previous) => productListFacetData(next, previous));
     }
     for (const product of next.products?.data ?? []) {
       productsStore
@@ -92,19 +139,39 @@ export function useProductSearch(
     }
   }
 
+  // Replaces the URL, so Back from the list still leaves it in one step.
+  function rememberLocation(next: ProductListLocation) {
+    const query = addressQuery();
+    if (
+      !remember ||
+      sameProductListLocation(productListLocationFromQuery(query), next)
+    ) {
+      return;
+    }
+    const search = new URLSearchParams(productListLocationQuery(query, next));
+    window.history.replaceState(
+      null,
+      '',
+      `${window.location.pathname}?${search}${window.location.hash}`,
+    );
+  }
+
   async function load(nextPage = page, nextFilters = filters) {
+    rememberLocation({ page: nextPage, filters: nextFilters });
     request.current?.abort();
     const controller = new AbortController();
     request.current  = controller;
     setPending(true);
     setError('');
     try {
-      const next = await loadProductSearch(
+      const next = await loadProductListPage(
         api,
         scope,
         nextFilters,
         nextPage,
         controller.signal,
+        // Only a list without its filter choices yet needs the full ones.
+        !browseStore.getState().searchFacets,
       );
       if (!controller.signal.aborted) {
         setPage(nextPage);
@@ -122,18 +189,22 @@ export function useProductSearch(
     }
   }
 
+  // A new scope starts from the page and filters of its URL: none after a
+  // link, the ones the visitor left after Back or a reload.
   useEffect(() => {
+    const location = addressLocation();
+    const server   = fromServer(location) ? initial : undefined;
     browseStore.getState().setSearchQuery(scope.query ?? '');
-    browseStore.getState().setSearchFilters({});
-    browseStore.getState().setSearchFacets(productSearchFacetData(initial));
-    setFacets(productSearchFacetData(initial));
-    setData(initial);
-    setFilters({});
-    setPage(initial?.products?.rpag.page ?? 1);
-    setLoaded(Boolean(initial));
-    setError(initialError);
-    if (!initial && searchable(scope)) {
-      void load(1, {});
+    browseStore.getState().setSearchFilters(location.filters);
+    browseStore.getState().setSearchFacets(productListFacetData(server));
+    setFacets(productListFacetData(server));
+    setData(server);
+    setFilters(location.filters);
+    setPage(server?.products?.rpag.page ?? location.page);
+    setLoaded(Boolean(server));
+    setError(fromServer(location) ? initialError : '');
+    if (!server && searchable(scope)) {
+      void load(location.page, location.filters);
     }
     return () => request.current?.abort();
   }, [signature]);

package/templates/app/robots.txt/route.ts

@@ -0,0 +1,11 @@
+// robots.txt of the storefront domain; it points crawlers to the sitemap.
+import { marketplaceRobotsResponse } from '@orionplace-runtime/marketplace.mjs';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+export function GET(request: Request): Promise<Response> {
+  return marketplaceRobotsResponse(request, {
+    mimicFrontDomain: process.env.MIMIC_FRONT_DOMAIN ?? '',
+  });
+}

package/templates/app/sitemap.xml/route.ts

@@ -0,0 +1,12 @@
+// The storefront sitemap: public pages, categories, products and journal
+// publications in every language, built from the backend for an hour.
+import { marketplaceSitemapResponse } from '@orionplace-runtime/marketplace.mjs';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+export function GET(request: Request): Promise<Response> {
+  return marketplaceSitemapResponse(request, {
+    mimicFrontDomain: process.env.MIMIC_FRONT_DOMAIN ?? '',
+  });
+}

package/templates/components/orionplace/account/ProfileDetailsForm.README.md

@@ -7,6 +7,8 @@ date of birth. Application Load supplies the initial values. Dates in
 `day.month.year` or `day/month/year` form are converted to the ISO value required
 by the native date field and the request. The sign-in phone number is read-only.
 
+Under the phone the hint names its country: `user.origin_country` from the application load, shown with the browser's country name («Its country, Russia, decides which payment methods you can use»). Without a country the plain hint stays.
+
 Submit is enabled only after an editable value changes and `state.loaded` is
 true with no pending request. Submission trims the two names and calls
 `onRequest` with `{ action: 'details', data: { first_name, last_name, dob } }`.
@@ -28,6 +30,8 @@ the latest Application Load profile values. Field messages come from
 `день.месяц.год` или `день/месяц/год` преобразуется в ISO-значение для системного
 поля даты и запроса. Номер телефона для входа доступен только для чтения.
 
+Под телефоном подсказка называет его страну: `user.origin_country` из загрузки приложения с названием страны от браузера («Его страна, Россия, определяет доступные способы оплаты»). Без страны остаётся обычная подсказка.
+
 Кнопка сохранения становится доступной только после изменения редактируемого
 значения, когда `state.loaded` равен `true` и нет выполняемого запроса. При
 отправке внешние пробелы в имени и фамилии удаляются, затем `onRequest` получает

package/templates/components/orionplace/account/ProfileDetailsForm.tsx

@@ -11,7 +11,7 @@ import type {
   IStorefrontProfileState,
 } from '@/interfaces/orionplace/accounts/IStorefrontProfile';
 import { profileLabels } from '@/lib/orionplace/profileLabels';
-import { profileDate } from '@/lib/orionplace/profile';
+import { profileCountryName, profileDate } from '@/lib/orionplace/profile';
 import styles from './ProfileDetailsForm.module.css';
 
 export interface ProfileDetailsFormProps {
@@ -26,6 +26,11 @@ export function ProfileDetailsForm({
   const profile             = useOrionplace(selectProfile);
   const locale              = useOrionplaceSelections((value) => value.localeCode);
   const labels              = profileLabels(locale);
+  // The phone country decides which payment methods the customer gets at checkout.
+  const country             = profileCountryName(profile?.origin_country, locale);
+  const phoneHint           = country
+    ? labels.phoneCountryHint.replace('{country}', country)
+    : labels.phoneHint;
   const busy                = Boolean(state.pending) || !state.loaded;
   const synchronized        = {
     first_name: profile?.first_name ?? '',
@@ -148,7 +153,7 @@ export function ProfileDetailsForm({
             autoComplete="tel"
             readOnly
           />
-          <small>{labels.phoneHint}</small>
+          <small>{phoneHint}</small>
         </label>
         <label>
           <span>{labels.dob}</span>

package/templates/components/orionplace/cart/CartCheckoutDetails.README.md

@@ -30,6 +30,8 @@ The comment field takes up to 1024 characters; its own Save action sends
 `cart_customer_commentary_set` with `cart_commentary`. New cart data replaces the local recipient and comment
 drafts.
 
+When `payment_methods` is empty, the payment block shows «No payment method is available for this order…» instead of a select. The backend offers a method limited by country only to customers whose phone number is from one of its countries (`origin_country`), not by the delivery address.
+
 On the Russian storefront a phone number typed without «+» the way it is written in Russia — «8 900 555-01-72» or «900 555-01-72» — becomes «+79005550172» when the field loses focus and before it is sent: the backend accepts only international numbers. A number typed with «+», other numbers and other languages are sent as typed (`phoneWithCountryCode()`).
 
 ### Props
@@ -77,6 +79,8 @@ On the Russian storefront a phone number typed without «+» the way it is writt
 `cart_commentary`. Новые данные корзины
 заменяют локальные значения получателя и комментария.
 
+Когда `payment_methods` пуст, вместо списка показывается «Для этого заказа нет доступных способов оплаты…». Способ, ограниченный по странам, бэкенд предлагает только покупателям с номером телефона одной из этих стран (`origin_country`), а не по адресу доставки.
+
 В русской витрине номер без «+», набранный по-российски — «8 900 555-01-72» или «900 555-01-72», — при выходе из поля и перед отправкой становится «+79005550172»: бэкенд принимает только международный формат. Номер с «+», другие номера и другие языки отправляются как набраны (`phoneWithCountryCode()`).
 
 ### Свойства

package/templates/components/orionplace/cart/CartCheckoutDetails.tsx

@@ -269,15 +269,26 @@ export function CartCheckoutDetails({
         <>
           <section className={styles.panel}>
             <h2>{labels.payment}</h2>
-            <OrionplaceSelect
-              value={String(summary?.selected_payment ?? 0)}
-              options={payments}
-              icons={paymentIcons}
-              label={labels.payment}
-              disabled={disabled}
-              required
-              onValueChange={selectPayment}
-            />
+            {/* Methods depend on the order and on the customer's phone country:
+                an empty list is said, not shown as a select with only the prompt. */}
+            {methods.length ? (
+              <OrionplaceSelect
+                value={String(summary?.selected_payment ?? 0)}
+                options={payments}
+                icons={paymentIcons}
+                label={labels.payment}
+                disabled={disabled}
+                required
+                onValueChange={selectPayment}
+              />
+            ) : (
+              <p
+                className={styles.muted}
+                role="status"
+              >
+                {labels.noPayment}
+              </p>
+            )}
           </section>
 
           <section className={styles.panel}>

package/templates/interfaces/orionplace/accounts/IProfileData.ts

@@ -31,6 +31,8 @@ export interface IApiDateTime {
 export interface IProfileData {
   id: number;
   phone: string;
+  /** ISO 3166-1 alpha-2 country of the phone number; null when the number has none. */
+  origin_country: string | null;
   first_name: string;
   last_name: string;
   email: string;

package/templates/interfaces/orionplace/appBase/IApploadUserProfile.ts

@@ -6,6 +6,8 @@ export interface IApploadUserProfile {
 	last_login: string | null;
 	date_joined: string;
 	phone: string;
+	/** ISO 3166-1 alpha-2 country of the phone number; null when the number has none. */
+	origin_country: string | null;
 	password: boolean;
 	dob: string | null;
 	notifications_enabled: boolean;

package/templates/lib/orionplace/cartLabels.ts

@@ -17,6 +17,7 @@ const en = {
     'The address is saved, but there is no delivery to this country. Choose another address.',
   payment: 'Payment method',
   choosePayment: 'Choose payment method',
+  noPayment: 'No payment method is available for this order. Available methods depend on the order and on the country of your phone number.',
   recipient: 'Recipient',
   myself: 'Myself',
   myselfHint: 'Myself: I will receive the order',
@@ -143,6 +144,7 @@ const ru: typeof en = {
     'Адрес сохранён, но доставки в эту страну нет. Выберите другой адрес.',
   payment: 'Способ оплаты',
   choosePayment: 'Выберите способ оплаты',
+  noPayment: 'Для этого заказа нет доступных способов оплаты. Они зависят от заказа и от страны вашего номера телефона.',
   recipient: 'Получатель',
   myself: 'Себе',
   myselfHint: 'Себе: получу заказ самостоятельно',

package/templates/lib/orionplace/pageMetadata.ts

@@ -13,6 +13,8 @@ import type { ICategoryLocale } from '@/interfaces/orionplace/category/ICategory
 import type { IPromoDefinition } from '@/interfaces/orionplace/cart/ICartData';
 import { promoName } from '@/lib/orionplace/promoPresentation';
 import {
+  storefrontAbsoluteUrl,
+  storefrontCanonicalUrl,
   storefrontPageMetadata,
   type StorefrontSeoPage,
 } from '@/lib/orionplace/pageSeo';
@@ -111,6 +113,8 @@ export function storefrontMetadata(
   locale: string,
   url: URL,
   records: StorefrontPageRecords = {},
+  // The public origin (the proxy's host on the server, the page's own in the browser).
+  origin = url.origin,
 ) {
   const segments               = url.pathname.split('/').filter(Boolean);
   let page                     = records.pageKind ?? storefrontSeoPage(url.pathname);
@@ -125,7 +129,13 @@ export function storefrontMetadata(
   let image: string | undefined;
   const tags: MetaTags         = [];
   let robots: string | undefined;
-  if (privatePages.has(page) || page === 'notFound' || page === 'error') {
+  // A private product link (`key`) stays out of search results, loaded or not.
+  if (
+    privatePages.has(page) ||
+    page === 'notFound' ||
+    page === 'error' ||
+    (page === 'product' && url.searchParams.get('key'))
+  ) {
     robots = 'noindex, nofollow';
   } else if (page === 'browse') {
     robots = 'noindex, follow';
@@ -177,9 +187,6 @@ export function storefrontMetadata(
       field('meta_description') || field('short_description'),
     ).slice(0, 160);
     image              = product.images?.full?.[0] ?? product.images?.small?.[0];
-    if (url.searchParams.get('key')) {
-      robots = 'noindex, nofollow';
-    }
   } else if (page === 'publication' && records.post) {
     values.title       = getAvailableNestedValueFromObject(
       records.post.locale,
@@ -210,12 +217,24 @@ export function storefrontMetadata(
     values.title       = promoName(records.promo, locale);
   }
   const content                = storefrontPageMetadata(page, locale, values);
+  // Link previews load only complete image addresses; the canonical address
+  // is the sitemap's one for this page.
+  image                        = storefrontAbsoluteUrl(image, origin);
+  const canonical              = storefrontCanonicalUrl(
+    origin,
+    url.pathname,
+    url.search,
+    locale,
+    robots,
+  );
   const metadata: Metadata     = {
     ...content,
     ...(robots ? { robots } : {}),
+    ...(canonical ? { alternates: { canonical } } : {}),
     openGraph: {
       title: content.title,
       description: content.description,
+      ...(canonical ? { url: canonical } : {}),
       ...(image ? { images: [image] } : {}),
     },
   };
@@ -230,6 +249,7 @@ export function storefrontMetadata(
     'og:title': content.title,
     'og:description': content.description,
     'og:image': image,
+    'og:url': canonical,
   })) {
     headTags.set(name, {
       ...(name.startsWith('og:') ? { property: name } : { name }),