orionplace-react 0.5.0 → 0.6.0

package/README.md

@@ -8,7 +8,7 @@ account, journal and support, in English and Russian. The package includes a
 setup CLI and the full storefront source, so every page and component in your
 project is yours to change.
 
-- **Setup CLI:** `init`, `set backend`, `add frontend`, `set mimic` and `update`.
+- **Setup CLI:** `init`, `set backend`, `add frontend`, `set mimic`, `sitemap rebuild` and `update`.
 - **Server install:** `install` builds the storefront on your Linux server and
   runs it as a system service behind nginx with HTTPS.
 - **API gateway:** the browser calls `/api/...` on your own domain; the server
@@ -318,6 +318,8 @@ npx orionplace-react add frontend shop.example.com
 npx orionplace-react add frontend www.shop.example.com
 npx orionplace-react remove frontend www.shop.example.com
 npx orionplace-react set mimic shop.example.com
+npx orionplace-react sitemap rebuild [shop.example.com]
+npx orionplace-react sitemap status
 sudo npx orionplace-react install
 npx orionplace-react status
 sudo npx orionplace-react restart
@@ -334,8 +336,15 @@ npm run orionplace:remove-frontend -- www.shop.example.com
 npm run orionplace:mimic -- shop.example.com
 npm run orionplace:help
 npm run orionplace:update
+npm run orionplace:sitemap
 ```
 
+The storefront serves `/robots.txt` and `/sitemap.xml` (public pages, categories,
+products and journal publications in every language). The sitemap is rebuilt
+from the backend once an hour; `npm run orionplace:sitemap` rebuilds it at once,
+for example after new publications, and the running storefront serves it without
+a restart.
+
 `npm set` belongs to npm's own configuration system; use the commands above.
 The setup commands configure local integration files. They do not provision a
 backend, change your account or create DNS records. `install` deploys the

package/bin/orionplace-react.mjs

@@ -3,6 +3,7 @@ import { setupProject } from '../src/setup.mjs';
 import { updateProject } from '../src/update.mjs';
 import { installService } from '../src/install.mjs';
 import { SERVICE_ACTIONS, SERVICE_ALIASES, controlService, findApp, printService } from '../src/service.mjs';
+import { sitemapCommand } from '../src/sitemap.mjs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -30,6 +31,9 @@ Commands for an existing project (run from its root):
   npx orionplace-react remove frontend <shop.example.com>
   npx orionplace-react set mimic <existing-frontend.example.com>
   npx orionplace-react set frontend <shop.example.com>
+  npx orionplace-react sitemap rebuild [domain]   rebuild /sitemap.xml now (every frontend, or one);
+                                       the running storefront serves it at once
+  npx orionplace-react sitemap status [domain]    when each sitemap was built
 
 On your Linux server (run from the project root):
   sudo npx orionplace-react install
@@ -131,6 +135,9 @@ try {
       }
       const done       = await controlService({ action: command, cwd, name: install.name, lines: positional[1] ?? 100, follow, dryRun });
       process.exitCode = printService(done);
+    } else if (command === 'sitemap' && positional.length <= 3) {
+      if (dryRun) throw new Error('--dry-run is not a sitemap option; sitemap status shows the state without changes.');
+      process.exitCode = await sitemapCommand({ cwd, action: target, domain: positional[2] });
     } else if (command === 'init' && positional.length <= 2) {
       result = await setupProject({ cwd: target ? resolve(cwd, target) : cwd, dryRun });
     } else if (command === 'update' && positional.length === 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionplace-react",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Next.js 16 storefront for your Orionplace marketplace: setup CLI, server API gateway, typed store and ready-made catalog, cart, checkout and account components in English and Russian, plus an Android app build.",
   "type": "module",
   "license": "MIT",

package/runtime/marketplace.d.mts

@@ -25,3 +25,88 @@ export declare function forwardMarketplace(
   request: Request,
   configuration?: MarketplaceConfiguration,
 ): Promise<Response>;
+
+export interface MarketplaceSitemapPage {
+  path: string;
+  lastmod?: string | null;
+  locales?: string[];
+}
+
+export declare function marketplacePublicOrigin(
+  request: Request,
+  tenantDomain?: string,
+): string;
+
+export declare function marketplaceRobots(origin: string): string;
+
+export declare function marketplaceRobotsResponse(
+  request: Request,
+  configuration?: MarketplaceConfiguration,
+): Promise<Response>;
+
+export declare function sitemapLocales(locales: unknown): string[];
+
+export declare function sitemapLastmod(
+  value: unknown,
+  now?: number,
+): string | null;
+
+export declare function sitemapApiPath(
+  paths: unknown,
+  name: string,
+): string | null;
+
+export declare function sitemapCategoryIds(categories: unknown): number[];
+
+export declare function marketplaceSitemapXml(
+  origin: string,
+  pages: MarketplaceSitemapPage[],
+  locales: string[],
+): string;
+
+export declare function marketplaceSitemapResponse(
+  request: Request,
+  configuration?: MarketplaceConfiguration,
+): Promise<Response>;
+
+export interface MarketplaceSitemap {
+  version: number;
+  domain: string;
+  built: string;
+  locales: string[];
+  pages: MarketplaceSitemapPage[];
+}
+
+export interface MarketplaceSitemapRebuild {
+  domain: string;
+  path: string;
+  built: string;
+  urls: number;
+  pages: number;
+  publications: number;
+}
+
+export declare const SITEMAP_LIFETIME: number;
+
+export declare function readMarketplaceDomain(
+  domain: string,
+  options?: { root?: string },
+): Promise<MarketplaceTenant>;
+
+export declare function marketplaceConfigDirectory(root?: string): string;
+
+export declare function marketplaceDomains(root?: string): Promise<string[]>;
+
+export declare function sitemapCacheDirectory(root?: string): string;
+
+export declare function readSitemapCache(
+  domain: string,
+  root?: string,
+): Promise<MarketplaceSitemap | null>;
+
+export declare function sitemapUrlCount(sitemap: MarketplaceSitemap): number;
+
+export declare function rebuildMarketplaceSitemap(
+  domain: string,
+  options?: { root?: string },
+): Promise<MarketplaceSitemapRebuild>;

package/runtime/marketplace.mjs

@@ -1,5 +1,5 @@
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { chown, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
 import {
   getDefaultAutoSelectFamilyAttemptTimeout,
   isIP,
@@ -81,8 +81,20 @@ export async function readMarketplace(request, configuration = {}) {
   if (!domain) {
     throw new Error('Invalid storefront domain');
   }
+  return readMarketplaceDomain(domain);
+}
 
-  const directory = environment.SITEMAPS_DIR || resolve('sitemaps');
+/**
+ * The marketplace of one storefront domain: its `sitemaps/<domain>.cfg` in
+ * the project (`root`, the working directory by default).
+ * @param {string} name @param {{root?: string}} options
+ */
+export async function readMarketplaceDomain(name, options = {}) {
+  const domain    = normalizeFrontDomain(name);
+  if (!domain) {
+    throw new Error('Invalid storefront domain');
+  }
+  const directory = marketplaceConfigDirectory(options.root);
   const source    = await readFile(resolve(directory, `${domain}.cfg`), 'utf8');
   const lines     = source
     .split(/\r?\n/)
@@ -111,6 +123,13 @@ export async function readMarketplace(request, configuration = {}) {
   return { domain, api };
 }
 
+/** The folder of the domain files (`SITEMAPS_DIR`, or `sitemaps`). */
+export function marketplaceConfigDirectory(root = process.cwd()) {
+  return environment.SITEMAPS_DIR
+    ? resolve(root, environment.SITEMAPS_DIR)
+    : resolve(root, 'sitemaps');
+}
+
 /** @param {number} status @param {string} message */
 function failure(status, message) {
   return Response.json(
@@ -297,3 +316,471 @@ export async function forwardMarketplace(request, configuration = {}) {
     headers: responseHeaders,
   });
 }
+
+// ---------------------------------------------------------------------------
+// robots.txt and sitemap.xml
+//
+// The sitemap lists the storefront's public pages in every language the
+// marketplace offers (`?locale=<code>` links, with hreflang alternates): the
+// home, catalog and directory pages, the journal and its publications when
+// the blog is on, the subscription plans when there are any, every public
+// category and every product on sale. It is built from the backend's public
+// API and kept for an hour per storefront domain in
+// node_modules/.cache/orionplace/sitemaps/<domain>.json (ORIONPLACE_CACHE_DIR
+// moves it). "orionplace-<framework> sitemap rebuild" rebuilds that file at
+// once; the running storefront serves the new file without a restart.
+
+export const SITEMAP_LIFETIME = 60 * 60 * 1000;
+const sitemapPageSize = 100;
+const sitemapMaxPages = 500;
+const sitemapMaxUrls  = 50_000;
+const sitemapVersion  = 1;
+/** Built sitemaps of this process, for when the cache folder is read-only. */
+const sitemapMemory   = new Map();
+/** @type {Map<string, Promise<object>>} */
+const sitemapBuilds   = new Map();
+
+/** The public origin a crawler used: the storefront host, or a local one. */
+export function marketplacePublicOrigin(request, tenantDomain = '') {
+  const url  = new URL(request.url);
+  const host = normalizeFrontDomain(
+    request.headers.get('x-forwarded-host') ?? request.headers.get('host') ?? '',
+  );
+  if (host) {
+    return `https://${host}`;
+  }
+  const local = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/.test(url.hostname);
+  return local || !tenantDomain ? url.origin : `https://${tenantDomain}`;
+}
+
+/** @param {string} origin */
+export function marketplaceRobots(origin) {
+  return `User-agent: *\nDisallow: /api/\nAllow: /\n\nSitemap: ${origin}/sitemap.xml\n`;
+}
+
+/** @param {Request} request @param {{mimicFrontDomain?: string}} configuration */
+export async function marketplaceRobotsResponse(request, configuration = {}) {
+  let domain = '';
+  try {
+    domain = (await readMarketplace(request, configuration)).domain;
+  } catch {
+    domain = '';
+  }
+  return new Response(
+    marketplaceRobots(marketplacePublicOrigin(request, domain)),
+    {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'public, max-age=3600',
+        'Vary': 'Host, X-Forwarded-Host, X-Front-Domain',
+      },
+    },
+  );
+}
+
+/** @param {string} value */
+function escapeXml(value) {
+  return value.replace(/[<>&"']/g, (character) => ({
+    '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;',
+  })[character]);
+}
+
+/** @param {unknown} value */
+function publicId(value) {
+  const id = Number(value);
+  return Number.isSafeInteger(id) && id > 0 ? id : null;
+}
+
+/** The marketplace's languages from /appload `init.locale`. */
+export function sitemapLocales(locales) {
+  const codes = Object.entries(locales && typeof locales === 'object' ? locales : {})
+    .map(([key, item]) => String(item?.code || key).trim().toLowerCase())
+    .filter((code) => /^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$/.test(code));
+  return [...new Set(codes)].sort();
+}
+
+/** A product edit time (ISO 8601) or a blog post day ({date: 'DD.MM.YYYY'}). */
+export function sitemapLastmod(value, now = Date.now()) {
+  if (typeof value === 'string' && value) {
+    const time = Date.parse(value);
+    return Number.isFinite(time) && time <= now + 60_000
+      ? new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z')
+      : null;
+  }
+  const match = /^(\d{2})\.(\d{2})\.(\d{4})$/.exec(value?.date ?? '');
+  if (!match) {
+    return null;
+  }
+  const [, day, month, year] = match;
+  const time  = Date.UTC(Number(year), Number(month) - 1, Number(day));
+  const date  = new Date(time);
+  return date.getUTCDate() === Number(day) &&
+    date.getUTCMonth() === Number(month) - 1 &&
+    time <= now + 24 * 60 * 60 * 1000
+    ? `${year}-${month}-${day}`
+    : null;
+}
+
+/** The API path (under /api) of a route named in /appload `unauth.paths`. */
+export function sitemapApiPath(paths, name) {
+  for (const group of Object.values(paths ?? {})) {
+    for (const route of Object.values(group ?? {})) {
+      if (route?.url_name === name) {
+        const target = String(route.target ?? '').split('/{')[0].replace(/^\/+/, '');
+        return target.startsWith('api/') ? `/${target}` : null;
+      }
+    }
+  }
+  return null;
+}
+
+/** Public categories, parents before children. */
+export function sitemapCategoryIds(categories) {
+  const ids   = [];
+  const visit = (category) => {
+    const id = publicId(category?.id);
+    if (id && category?.is_public) {
+      ids.push(id);
+    }
+    (category?.childs ?? []).forEach(visit);
+  };
+  (Array.isArray(categories) ? categories : []).forEach(visit);
+  return [...new Set(ids)];
+}
+
+/**
+ * One <url> per page and language, each with alternates for its languages.
+ * A page with its own `locales` (a publication written in some languages
+ * only) is listed in those of the marketplace's languages.
+ * @param {string} origin
+ * @param {{path: string, lastmod?: string | null, locales?: string[]}[]} pages
+ * @param {string[]} locales
+ */
+export function marketplaceSitemapXml(origin, pages, locales) {
+  const href  = (path, code) => {
+    const url = new URL(path, `${origin}/`);
+    if (code) {
+      url.searchParams.set('locale', code);
+    }
+    return escapeXml(url.toString());
+  };
+  const urls  = [];
+  for (const page of pages) {
+    const own        = page.locales
+      ? locales.filter((code) => page.locales.includes(code))
+      : locales;
+    if (page.locales && !own.length) {
+      continue;
+    }
+    const codes      = own.length ? own : [''];
+    const alternates = own.length > 1
+      ? own.map((code) =>
+        `    <xhtml:link rel="alternate" hreflang="${escapeXml(code)}" href="${href(page.path, code)}" />\n`).join('')
+      : '';
+    const lastmod    = page.lastmod ? `    <lastmod>${escapeXml(page.lastmod)}</lastmod>\n` : '';
+    for (const code of codes) {
+      if (urls.length >= sitemapMaxUrls) {
+        break;
+      }
+      urls.push(`  <url>\n    <loc>${href(page.path, code)}</loc>\n${lastmod}${alternates}  </url>\n`);
+    }
+  }
+  return '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">\n' +
+    urls.join('') +
+    '</urlset>\n';
+}
+
+/** @param {{domain: string, api: URL}} tenant @param {string} path @param {unknown} body */
+async function sitemapRequest(tenant, path, body) {
+  const response = await fetch(new URL(path, tenant.api.origin), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'X-Front-Domain': tenant.domain,
+    },
+    body: JSON.stringify(body),
+    cache: 'no-store',
+    signal: AbortSignal.timeout(requestTimeout),
+  });
+  if (!response.ok) {
+    throw new Error(`${path} answered ${response.status}`);
+  }
+  return response.json();
+}
+
+/** Every record of a paginated list (`page_data[key].data` + `rpag`). */
+async function sitemapList(tenant, path, key, filters = {}) {
+  const records = new Map();
+  let page      = 1;
+  for (let count = 0; count < sitemapMaxPages; count++) {
+    const payload = await sitemapRequest(tenant, path, {
+      filters,
+      paginate: { page, pp_items: sitemapPageSize },
+    });
+    const list    = payload?.page_data?.[key];
+    if (!Array.isArray(list?.data)) {
+      throw new Error(`${path} returned no ${key} list`);
+    }
+    for (const record of list.data) {
+      const id = publicId(record?.id);
+      if (id) {
+        records.set(id, record);
+      }
+    }
+    const next    = Number(list.rpag?.next_page_number);
+    if (!list.rpag?.has_next || !Number.isSafeInteger(next) || next <= page) {
+      return [...records.values()];
+    }
+    page          = next;
+  }
+  throw new Error(`${path} has more than ${sitemapMaxPages} pages`);
+}
+
+/** Products on sale and in stock states a shopper can open. */
+function productOnSale(product) {
+  const status = Number(product?.status?.status ?? product?.status);
+  return [2, -2, -3].includes(status);
+}
+
+/** Blog publications that are published. */
+function postPublished(post) {
+  const state = post?.publishing_state?.int ?? post?.publishing_state;
+  return state === undefined || state === null || Number(state) === 1;
+}
+
+/** The languages a publication is written in (it has a title there). */
+function postLocales(post) {
+  return Object.entries(post?.locale && typeof post.locale === 'object' ? post.locale : {})
+    .filter(([, text]) => typeof text?.post_title === 'string' && text.post_title.trim())
+    .map(([code]) => code.toLowerCase());
+}
+
+/** @param {{domain: string, api: URL}} tenant */
+async function buildMarketplaceSitemap(tenant) {
+  const appload    = await sitemapRequest(tenant, '/api/appload', {
+    detalize_mode: 'light',
+    ignore_cache: false,
+  });
+  const init       = appload?.page_data?.init;
+  const paths      = appload?.page_data?.unauth?.paths;
+  if (!init || !Array.isArray(init.catalog)) {
+    throw new Error('appload returned no catalog');
+  }
+  const locales    = sitemapLocales(init.locale);
+  const categories = sitemapCategoryIds(init.catalog);
+  const blogPath   = sitemapApiPath(paths, 'blog_posts_get');
+  const searchPath = sitemapApiPath(paths, 'products_search');
+  const [products, posts] = await Promise.all([
+    searchPath && categories.length
+      ? sitemapList(tenant, searchPath, 'products', { categories })
+      : [],
+    blogPath ? sitemapList(tenant, blogPath, 'posts') : [],
+  ]);
+  const postPages  = posts
+    .filter(postPublished)
+    .sort((left, right) => left.id - right.id)
+    .map((post) => ({
+      path: `/journal/${post.id}`,
+      lastmod: sitemapLastmod(post.date_updated),
+      locales: postLocales(post),
+    }));
+  const newestPost = postPages.map((page) => page.lastmod).filter(Boolean).sort().at(-1) ?? null;
+  const pages      = [
+    { path: '/' },
+    { path: '/catalog' },
+    ...(blogPath ? [{ path: '/journal', lastmod: newestPost }] : []),
+    ...(init.tariffs?.data?.length ? [{ path: '/tariffs' }] : []),
+    { path: '/manufacturers' },
+    ...(init.visual_settings?.single_seller_mode ? [] : [{ path: '/sellers' }]),
+    { path: '/stores' },
+    { path: '/contact' },
+    { path: '/privacy' },
+    ...categories.map((id) => ({ path: `/category/${id}` })),
+    ...products
+      .filter(productOnSale)
+      .map((product) => ({
+        path: `/product/${product.id}`,
+        lastmod: sitemapLastmod(product.date_updated),
+      })),
+    ...postPages,
+  ];
+  return {
+    version: sitemapVersion,
+    domain: tenant.domain,
+    built: new Date().toISOString(),
+    locales,
+    pages,
+  };
+}
+
+/** How many <url> entries a built sitemap has. */
+export function sitemapUrlCount(sitemap) {
+  let count = 0;
+  for (const page of sitemap.pages) {
+    const own = page.locales
+      ? sitemap.locales.filter((code) => page.locales.includes(code))
+      : sitemap.locales;
+    count    += page.locales ? own.length : Math.max(own.length, 1);
+  }
+  return Math.min(count, sitemapMaxUrls);
+}
+
+/** The cache folder of built sitemaps. */
+export function sitemapCacheDirectory(root = process.cwd()) {
+  return environment.ORIONPLACE_CACHE_DIR
+    ? resolve(root, environment.ORIONPLACE_CACHE_DIR, 'sitemaps')
+    : resolve(root, 'node_modules', '.cache', 'orionplace', 'sitemaps');
+}
+
+/** @param {string} domain @param {string} root */
+function sitemapCachePath(domain, root) {
+  return resolve(sitemapCacheDirectory(root), `${domain}.json`);
+}
+
+/** A cached sitemap of the domain, or null. @param {string} domain */
+export async function readSitemapCache(domain, root = process.cwd()) {
+  let sitemap;
+  try {
+    sitemap = JSON.parse(await readFile(sitemapCachePath(domain, root), 'utf8'));
+  } catch {
+    return null;
+  }
+  return sitemap?.version === sitemapVersion &&
+    sitemap.domain === domain &&
+    Number.isFinite(Date.parse(sitemap.built)) &&
+    Array.isArray(sitemap.locales) &&
+    Array.isArray(sitemap.pages)
+    ? sitemap
+    : null;
+}
+
+/**
+ * Write the cache file. When root writes it (sudo), the folders it creates
+ * and the file go to the project owner, so the storefront service can
+ * replace them later.
+ */
+async function writeSitemapCache(sitemap, root) {
+  const path      = sitemapCachePath(sitemap.domain, root);
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await mkdir(dirname(path), { recursive: true });
+  try {
+    await writeFile(temporary, JSON.stringify(sitemap), { mode: 0o644 });
+    await rename(temporary, path);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+  if (process.getuid?.() === 0) {
+    const owner = await stat(root);
+    if (owner.uid !== 0) {
+      let cursor = path;
+      while (cursor !== root && !relative(root, cursor).startsWith('..')) {
+        const info = await stat(cursor);
+        if (info.uid === 0) {
+          await chown(cursor, owner.uid, owner.gid);
+        }
+        cursor = dirname(cursor);
+      }
+    }
+  }
+  return path;
+}
+
+/** @param {{domain: string, api: URL}} tenant @param {string} root */
+function buildOnce(tenant, root) {
+  let build = sitemapBuilds.get(tenant.domain);
+  if (!build) {
+    build = buildMarketplaceSitemap(tenant)
+      .then(async (sitemap) => {
+        sitemapMemory.set(tenant.domain, sitemap);
+        try {
+          await writeSitemapCache(sitemap, root);
+        } catch (error) {
+          console.error(`[orionplace] Sitemap cache not written: ${error?.code ?? error?.message ?? error}`);
+        }
+        return sitemap;
+      })
+      .finally(() => sitemapBuilds.delete(tenant.domain));
+    sitemapBuilds.set(tenant.domain, build);
+  }
+  return build;
+}
+
+/**
+ * Rebuild the sitemap of one storefront domain now and store it where the
+ * running storefront reads it (the "sitemap rebuild" command).
+ * @param {string} domain @param {{root?: string}} options
+ */
+export async function rebuildMarketplaceSitemap(domain, options = {}) {
+  const root    = resolve(options.root ?? process.cwd());
+  const tenant  = await readMarketplaceDomain(domain, { root });
+  const sitemap = await buildMarketplaceSitemap(tenant);
+  const path    = await writeSitemapCache(sitemap, root);
+  return {
+    domain: tenant.domain,
+    path,
+    built: sitemap.built,
+    urls: sitemapUrlCount(sitemap),
+    pages: sitemap.pages.length,
+    publications: sitemap.pages.filter((page) => page.path.startsWith('/journal/')).length,
+  };
+}
+
+/** The storefront domains of the project (its `sitemaps/*.cfg` files). */
+export async function marketplaceDomains(root = process.cwd()) {
+  let names;
+  try {
+    names = await readdir(marketplaceConfigDirectory(root));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+  return names
+    .filter((name) => name.endsWith('.cfg'))
+    .map((name) => normalizeFrontDomain(name.slice(0, -4)))
+    .filter(Boolean)
+    .sort();
+}
+
+/** @param {Request} request @param {{mimicFrontDomain?: string}} configuration */
+export async function marketplaceSitemapResponse(request, configuration = {}) {
+  let tenant;
+  try {
+    tenant = await readMarketplace(request, configuration);
+  } catch {
+    return failure(503, 'Storefront domain configuration is missing or invalid');
+  }
+  const root    = process.cwd();
+  const fresh   = (sitemap) =>
+    sitemap && Date.now() - Date.parse(sitemap.built) < SITEMAP_LIFETIME;
+  // The file wins when it is newer: a "sitemap rebuild" replaced it.
+  const file    = await readSitemapCache(tenant.domain, root);
+  const memory  = sitemapMemory.get(tenant.domain);
+  const newest  = [file, memory]
+    .filter(Boolean)
+    .sort((left, right) => Date.parse(right.built) - Date.parse(left.built))[0];
+  let sitemap   = fresh(newest) ? newest : null;
+  if (!sitemap) {
+    try {
+      sitemap = await buildOnce(tenant, root);
+    } catch (error) {
+      console.error(`[orionplace] Sitemap build failed: ${error?.message ?? error}`);
+      if (!newest) {
+        return failure(502, 'Marketplace backend is unavailable');
+      }
+      sitemap = newest;
+    }
+  }
+  const origin  = marketplacePublicOrigin(request, tenant.domain);
+  return new Response(marketplaceSitemapXml(origin, sitemap.pages, sitemap.locales), {
+    headers: {
+      'Content-Type': 'application/xml; charset=utf-8',
+      'Cache-Control': 'public, max-age=3600',
+      'Vary': 'Host, X-Forwarded-Host, X-Front-Domain',
+    },
+  });
+}

package/src/project-readme.mjs

@@ -89,6 +89,7 @@ and Next.js configuration are preserved.
 | \`../${base}app/_storefront/\` | Route controllers that connect components, navigation and API actions. |
 | \`../${base}app/api/[...orionplace]/route.ts\` | The route handler serving \`/api/...\` from your project. |
 | \`../${base}app/ps3/blog/[...orionplace]/route.ts\` | The route handler serving guarded blog images and videos under \`/ps3/blog/...\`. |
+| \`../${base}app/robots.txt/route.ts\`, \`../${base}app/sitemap.xml/route.ts\` | \`/robots.txt\` and the storefront sitemap. |
 | \`../${base}proxy.ts\` | Marks personalized pages private and answers HTTP 503 when Application Load fails. |
 | \`../sitemaps/${frontend}.cfg\` | The backend URL used for this frontend domain. |
 | \`../.env\` | Local MIMIC setting; keep secrets out of version control. |
@@ -389,8 +390,22 @@ location / {
 
 Here localhost is your frontend process on your VPS. That process selects the
 remote personal API from the domain file. The proxy must overwrite those headers.
-An unknown domain never falls back to another tenant. This setup does not generate
-sitemap XML or add analytics.
+An unknown domain never falls back to another tenant. \`/robots.txt\` points
+crawlers to \`/sitemap.xml\`, which lists the public pages, categories, products
+on sale and journal publications in every storefront language (each publication
+only in the languages it is written in). The sitemap is built from the backend
+and kept for an hour in \`node_modules/.cache/orionplace/sitemaps/\`
+(\`ORIONPLACE_CACHE_DIR\` moves it). After you publish or change content, rebuild
+it at once from the project folder; the running storefront serves the new
+sitemap without a restart:
+
+\`\`\`bash
+npm run orionplace:sitemap                          # every frontend domain
+npx orionplace-react sitemap rebuild shop.example.com  # one domain
+npx orionplace-react sitemap status                  # when each was built
+\`\`\`
+
+This setup does not add analytics.
 
 ## Android app
 

package/src/setup.mjs

@@ -187,6 +187,7 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   pkg.scripts['orionplace:remove-frontend'] ||= 'orionplace-react remove frontend';
   pkg.scripts['orionplace:mimic']           ||= 'orionplace-react set mimic';
   pkg.scripts['orionplace:help']            ||= 'orionplace-react help';
+  pkg.scripts['orionplace:sitemap']         ||= 'orionplace-react sitemap rebuild';
   pkg.scripts['orionplace:update']          ||= 'orionplace-react update';
   pkg.dependencies                          ||= {};
   pkg.dependencies.zustand                  ||= dependencies.zustand || '^5.0.15';

package/src/sitemap.mjs

@@ -0,0 +1,93 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const metadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const cli      = metadata.name;
+
+/**
+ * The project's own gateway runtime (orionplace/runtime/marketplace.mjs): the
+ * sitemap is built with the code the running storefront uses.
+ */
+async function projectRuntime(root) {
+  const path    = resolve(root, 'orionplace/runtime/marketplace.mjs');
+  if (!existsSync(path)) {
+    throw new Error(`No orionplace/runtime/marketplace.mjs in ${root}. Run this in the storefront project (or pass --cwd).`);
+  }
+  const runtime = await import(pathToFileURL(path).href);
+  if (typeof runtime.rebuildMarketplaceSitemap !== 'function') {
+    throw new Error(`This project's runtime has no sitemap support. Run npx ${cli} update first.`);
+  }
+  return runtime;
+}
+
+/**
+ * The storefront reads SITEMAPS_DIR and ORIONPLACE_CACHE_DIR from the
+ * project's .env; the command uses the same folders. Variables already set
+ * in the shell win.
+ */
+async function projectEnvironment(root) {
+  let source = '';
+  try { source = await readFile(resolve(root, '.env'), 'utf8'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  for (const line of source.split(/\r?\n/)) {
+    const match = /^\s*(?:export\s+)?(SITEMAPS_DIR|ORIONPLACE_CACHE_DIR)\s*=\s*(.*?)\s*$/.exec(line);
+    if (!match || process.env[match[1]] !== undefined) continue;
+    const value = match[2].replace(/^(['"])(.*)\1$/, '$2');
+    if (value) process.env[match[1]] = resolve(root, value);
+  }
+}
+
+async function domainsFor(runtime, root, domain) {
+  if (domain) {
+    const normalized = runtime.normalizeFrontDomain(domain);
+    if (!normalized) throw new Error(`Invalid frontend domain: ${domain}`);
+    return [normalized];
+  }
+  const domains = await runtime.marketplaceDomains(root);
+  if (!domains.length) throw new Error(`No frontend domains yet. Add one: npx ${cli} add frontend <shop.example.com>`);
+  return domains;
+}
+
+function age(built, now = Date.now()) {
+  const minutes = Math.max(0, Math.round((now - Date.parse(built)) / 60_000));
+  return minutes < 60 ? `${minutes} min ago` : `${Math.floor(minutes / 60)} h ${minutes % 60} min ago`;
+}
+
+/**
+ * `sitemap rebuild [domain]`: build the sitemap of every frontend domain (or
+ * one) now. `sitemap status [domain]`: show when each was built.
+ * @param {{cwd: string, action: string, domain?: string, log?: (line: string) => void}} options
+ * @returns {Promise<number>} exit code
+ */
+export async function sitemapCommand({ cwd, action, domain, log = console.log }) {
+  if (!['rebuild', 'status'].includes(action)) {
+    throw new Error(`Use: npx ${cli} sitemap rebuild [domain] | sitemap status [domain]`);
+  }
+  const root    = resolve(cwd);
+  await projectEnvironment(root);
+  const runtime = await projectRuntime(root);
+  const domains = await domainsFor(runtime, root, domain);
+  let failed    = 0;
+  for (const name of domains) {
+    if (action === 'status') {
+      const sitemap = await runtime.readSitemapCache(name, root);
+      const stale   = sitemap && Date.now() - Date.parse(sitemap.built) >= runtime.SITEMAP_LIFETIME;
+      log(sitemap
+        ? `${name}: built ${sitemap.built} (${age(sitemap.built)}), ${runtime.sitemapUrlCount(sitemap)} URLs${stale ? '; rebuilt at the next crawl' : ''}`
+        : `${name}: not built yet; built at the first /sitemap.xml request or with: npx ${cli} sitemap rebuild`);
+      continue;
+    }
+    const started = Date.now();
+    try {
+      const done = await runtime.rebuildMarketplaceSitemap(name, { root });
+      log(`${name}: ${done.urls} URLs (${done.pages} pages, ${done.publications} journal publications) in ${((Date.now() - started) / 1000).toFixed(1)} s`);
+      log(`  saved ${relative(root, done.path)}; the running storefront serves it now at https://${name}/sitemap.xml`);
+    } catch (error) {
+      failed++;
+      log(`${name}: not rebuilt: ${error?.message ?? error}`);
+    }
+  }
+  return failed ? 1 : 0;
+}

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/profile.ts

@@ -34,6 +34,18 @@ export function profileDate(value: string | null | undefined) {
     : '';
 }
 
+/** The name of a phone country code (`RU` → «Россия» / «Russia»); the code itself when the browser has no name. */
+export function profileCountryName(code: string | null | undefined, locale: string) {
+  if (!code) {
+    return '';
+  }
+  try {
+    return new Intl.DisplayNames([locale], { type: 'region' }).of(code) || code;
+  } catch {
+    return code;
+  }
+}
+
 export class ProfileRequestError extends Error {
   readonly kind = 'profile-request';
   readonly fields: Record<string, string>;

package/templates/lib/orionplace/profileLabels.ts

@@ -15,6 +15,7 @@ export function profileLabels(locale: string) {
         lastName: 'Фамилия',
         phone: 'Номер телефона',
         phoneHint: 'Номер телефона для входа.',
+        phoneCountryHint: 'Номер телефона для входа. Его страна, {country}, определяет доступные способы оплаты.',
         dob: 'Дата рождения',
         save: 'Сохранить',
         pending: 'Сохраняем…',
@@ -89,6 +90,7 @@ export function profileLabels(locale: string) {
         lastName: 'Last name',
         phone: 'Phone number',
         phoneHint: 'Your sign-in phone number.',
+        phoneCountryHint: 'Your sign-in phone number. Its country, {country}, decides which payment methods you can use.',
         dob: 'Date of birth',
         save: 'Save',
         pending: 'Saving…',

package/templates/proxy.ts

@@ -50,7 +50,8 @@ export async function proxy(request: NextRequest) {
   return response;
 }
 
-// The gateway sets its own headers for /api; static assets keep their caching.
+// The gateway sets its own headers for /api, robots.txt and the sitemap;
+// static assets keep their caching.
 export const config = {
-  matcher: ['/((?!api/|_next/static|_next/image|favicon.ico).*)'],
+  matcher: ['/((?!api/|_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)'],
 };