@mohasinac/appkit 4.72.0 → 4.74.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.72.0",
-  "head": "575e897961a5c80f9a04fbbf12f3f78346e9d654",
+  "version": "4.74.0",
+  "head": "69eb1a743d0233ce42a9b2836042d71958494e63",
   "branch": "main",
   "dirty": true,
-  "builtAt": "2026-11-09T00:00:40.787Z"
+  "builtAt": "2026-11-09T01:51:49.655Z"
 }

package/dist/_internal/server/features/seo/sitemap.d.ts

@@ -1,5 +1,62 @@
 import type { MetadataRoute } from "next";
+/**
+ * Every section this builder can emit. The names are the same keys the
+ * per-section count digest logs and `scripts/deploy.mjs` asserts against, so
+ * there is one vocabulary for "which part of the sitemap".
+ */
+export declare const SITEMAP_SECTIONS: readonly ["static", "category", "brand", "franchise", "bundle", "group", "blog", "product", "collectorDrop", "preOrder", "clearance", "classified", "digitalCode", "live", "event", "store", "scammer"];
+export type SitemapSection = (typeof SITEMAP_SECTIONS)[number];
 export interface SitemapOptions {
     baseUrl: string;
+    /**
+     * Emit ONLY these sections. Omit for all of them, which is what the main
+     * shop wants.
+     *
+     * ## 🛑 Why this exists, and why it is not a nice-to-have
+     *
+     * The blog and events surfaces now live on their own deployments
+     * (`blogs.`/`events.`). Each needs a sitemap carrying **its own** URLs on
+     * **its own** host, and the shop needs to stop advertising them — because the
+     * moment the shop 301s `/blog/*` to the subdomain, every `/blog` URL left in
+     * the shop's sitemap becomes a redirecting entry.
+     *
+     * That is not a hypothetical. This file's own note at the `disabledRoutes`
+     * filter records the measured version: on 2026-10-27 the production sitemap
+     * advertised **17 `/blog` URLs and one `/reviews` URL** that already 404'd at
+     * the edge — 18 crawl errors on pages we had explicitly asked Google to
+     * fetch. And `seo.server.ts` in the consumer records the worse outcome, when
+     * half the URL surface followed one host and half another: *every URL in the
+     * sitemap 307-redirected and Google dropped the site.*
+     *
+     * So a host must be able to say "my sitemap is these sections and nothing
+     * else", and the two halves must be derived from one list rather than two
+     * hand-maintained ones. Hence an allowlist here instead of a second sitemap
+     * builder in each extracted app.
+     *
+     * 🛑 A section NOT selected is not fetched at all — the point is to avoid the
+     * Firestore reads too, not merely to filter the result. A subdomain querying
+     * the entire product catalogue to throw it away would make every sitemap
+     * request pay for sixteen collections it never emits.
+     *
+     * 🛑 `static` is a section like any other, so an allowlist that omits it
+     * emits no static pages. That is deliberate: the shop's static pages
+     * (`/about`, `/contact`, the browse routes) belong to the shop, and a
+     * subdomain advertising them under its own host would be inventing URLs that
+     * do not exist there.
+     */
+    sections?: readonly SitemapSection[];
+    /**
+     * Emit everything EXCEPT these. Mutually exclusive with `sections` in
+     * practice; if both are given, `sections` is applied first and this narrows
+     * it further.
+     *
+     * This is the shop's half of the split — `excludeSections: ["blog", "event"]`
+     * — and it is spelled as an exclusion rather than a 15-name allowlist so that
+     * a NEW section added to this file is carried by the shop automatically. An
+     * allowlist there would silently drop the next surface somebody adds, which
+     * is the same "measured as empty → looks intentional" failure the digest
+     * below exists to catch.
+     */
+    excludeSections?: readonly SitemapSection[];
 }
-export declare function buildSitemap({ baseUrl }: SitemapOptions): Promise<MetadataRoute.Sitemap>;
+export declare function buildSitemap({ baseUrl, sections: only, excludeSections, }: SitemapOptions): Promise<MetadataRoute.Sitemap>;

package/dist/_internal/server/features/seo/sitemap.js

@@ -67,6 +67,30 @@ function sitemapSectionFailed(label, err) {
     serverLogger.error(`sitemap: section "${label}" failed and returned 0 URLs`, { section: label, error: err });
     return [];
 }
+/**
+ * Every section this builder can emit. The names are the same keys the
+ * per-section count digest logs and `scripts/deploy.mjs` asserts against, so
+ * there is one vocabulary for "which part of the sitemap".
+ */
+export const SITEMAP_SECTIONS = [
+    "static",
+    "category",
+    "brand",
+    "franchise",
+    "bundle",
+    "group",
+    "blog",
+    "product",
+    "collectorDrop",
+    "preOrder",
+    "clearance",
+    "classified",
+    "digitalCode",
+    "live",
+    "event",
+    "store",
+    "scammer",
+];
 /**
  * Read every document a query matches, in pages.
  *
@@ -512,26 +536,39 @@ async function fetchScammerUrls(baseUrl) {
         return sitemapSectionFailed("scammer", err);
     }
 }
-export async function buildSitemap({ baseUrl }) {
+export async function buildSitemap({ baseUrl, sections: only, excludeSections, }) {
+    /*
+     * Which sections this host emits. See `SitemapOptions.sections` for why a
+     * host must be able to answer this at all.
+     *
+     * 🛑 `wants()` gates the FETCH, not the output. An unselected section issues
+     * no Firestore query — a subdomain must not pay for sixteen collections it
+     * throws away on every sitemap request.
+     */
+    const excluded = new Set(excludeSections ?? []);
+    const allowed = only ? new Set(only) : null;
+    const wants = (s) => !excluded.has(s) && (allowed === null || allowed.has(s));
+    /** `[]` for a section this host does not emit, without running its query. */
+    const ifWanted = (s, run) => wants(s) ? run() : Promise.resolve([]);
     const [productUrls, categoryUrls, brandUrls, franchiseUrls, bundleUrls, groupedListingUrls, eventUrls, blogUrls, collectorDropUrls, preOrderUrls, clearanceUrls, classifiedUrls, digitalCodeUrls, liveUrls, storeUrls, scammerUrls,] = await Promise.all([
-        fetchProductUrls(baseUrl),
-        fetchCategoryUrls(baseUrl),
-        fetchBrandUrls(baseUrl),
-        fetchFranchiseUrls(baseUrl),
-        fetchBundleUrls(baseUrl),
-        fetchGroupedListingUrls(baseUrl),
-        fetchEventUrls(baseUrl),
-        fetchBlogPostUrls(baseUrl),
-        fetchCollectorDropUrls(baseUrl),
-        fetchPreOrderUrls(baseUrl),
-        fetchClearanceUrls(baseUrl),
-        fetchClassifiedUrls(baseUrl),
-        fetchDigitalCodeUrls(baseUrl),
-        fetchLiveUrls(baseUrl),
-        fetchStoreUrls(baseUrl),
-        fetchScammerUrls(baseUrl),
+        ifWanted("product", () => fetchProductUrls(baseUrl)),
+        ifWanted("category", () => fetchCategoryUrls(baseUrl)),
+        ifWanted("brand", () => fetchBrandUrls(baseUrl)),
+        ifWanted("franchise", () => fetchFranchiseUrls(baseUrl)),
+        ifWanted("bundle", () => fetchBundleUrls(baseUrl)),
+        ifWanted("group", () => fetchGroupedListingUrls(baseUrl)),
+        ifWanted("event", () => fetchEventUrls(baseUrl)),
+        ifWanted("blog", () => fetchBlogPostUrls(baseUrl)),
+        ifWanted("collectorDrop", () => fetchCollectorDropUrls(baseUrl)),
+        ifWanted("preOrder", () => fetchPreOrderUrls(baseUrl)),
+        ifWanted("clearance", () => fetchClearanceUrls(baseUrl)),
+        ifWanted("classified", () => fetchClassifiedUrls(baseUrl)),
+        ifWanted("digitalCode", () => fetchDigitalCodeUrls(baseUrl)),
+        ifWanted("live", () => fetchLiveUrls(baseUrl)),
+        ifWanted("store", () => fetchStoreUrls(baseUrl)),
+        ifWanted("scammer", () => fetchScammerUrls(baseUrl)),
     ]);
-    const staticUrls = staticPages(baseUrl);
+    const staticUrls = wants("static") ? staticPages(baseUrl) : [];
     // Per-section count digest. A section that drops to zero is otherwise
     // indistinguishable from a site that genuinely has none of that thing — which
     // is exactly how `category: 0` survived unnoticed while every other section
@@ -715,6 +752,28 @@ export async function buildSitemap({ baseUrl }) {
         if (page && closed.has(page))
             sections[name] = 0;
     }
+    /*
+     * 🛑 A section this host does not EMIT is dropped from the digest entirely,
+     * not reported as zero.
+     *
+     * The comment above this block is the reason, and it was written about the
+     * `closed` case: *"a warning that fires every build for a reason everyone
+     * knows about is how the next real zero gets ignored. 'Closed on purpose'
+     * and 'broken' must not look the same in the log."* Section scoping is the
+     * same hazard one axis over — without this, the blogs deployment would warn
+     * about fifteen empty sections on every single sitemap request, and the shop
+     * would warn about `blog` and `event` forever. Two permanent false alarms is
+     * how the alarm stops being read.
+     *
+     * Deleting the key rather than zeroing it also keeps the digest honest for
+     * `scripts/deploy.mjs`, which asserts these counts against the deployed
+     * sitemap: a section that is absent from the response should be absent here
+     * too, not present-and-zero.
+     */
+    for (const name of Object.keys(sections)) {
+        if (!wants(name))
+            delete sections[name];
+    }
     const empty = Object.entries(sections)
         .filter(([name, n]) => n === 0 && !closed.has(sectionPage[name]))
         .map(([name]) => name);
@@ -724,6 +783,18 @@ export async function buildSitemap({ baseUrl }) {
             closed: [...closed],
         });
     }
+    /*
+     * Logged so a host's scope is visible in production, not just in its source.
+     * "Why is /blog missing from the sitemap" is otherwise answerable only by
+     * reading the caller.
+     */
+    if (only || excludeSections?.length) {
+        serverLogger.info("sitemap: section scope applied", {
+            ...(only ? { only: [...only] } : {}),
+            ...(excludeSections?.length ? { excluded: [...excludeSections] } : {}),
+            emitting: Object.keys(sections),
+        });
+    }
     if (empty.length > 0) {
         serverLogger.warn(`sitemap: ${empty.length} section(s) produced 0 URLs`, { empty, sections, total });
     }

package/dist/http/ApiClient.js

@@ -1,3 +1,4 @@
+import { serviceOriginFor } from "./service-origins.js";
 /**
  * ApiClient — @mohasinac/http
  *
@@ -34,7 +35,25 @@ export class ApiClient {
         this.defaultTimeout = options?.defaultTimeout ?? 120000;
     }
     buildURL(endpoint, params) {
-        const origin = this.baseURL ||
+        /*
+         * 🛑 A registered SERVICE ORIGIN wins over this client's own base.
+         *
+         * `/api/blog/*` and `/api/events/*` are served by their own deployments
+         * now. A consumer that wants its data from the owning subdomain registers
+         * the prefix once at boot and every call site is routed without edit —
+         * which is the point of the seam (owner, 2026-11-09): the consumer keeps
+         * its presentation and changes only where the DATA comes from.
+         *
+         * Order matters. The service map is consulted FIRST because it is the more
+         * specific statement: `baseURL` says "where this client points by
+         * default", the map says "who owns this path", and a path with a declared
+         * owner is owned regardless of which client asked.
+         *
+         * An unregistered prefix returns `undefined` and nothing below changes —
+         * an install that has not adopted the seam behaves exactly as before.
+         */
+        const origin = serviceOriginFor(endpoint) ||
+            this.baseURL ||
             (typeof window !== "undefined"
                 ? window.location.origin
                 : (process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000"));

package/dist/http/index.d.ts

@@ -7,4 +7,6 @@
  */
 export { ApiClient, ApiClientError, apiClient } from "./ApiClient";
 export type { ApiClientOptions, RequestConfig, ApiResponse } from "./ApiClient";
+export { configureServiceOrigins, getServiceOrigins, serviceOriginFor, _resetServiceOrigins, } from "./service-origins";
+export type { ServiceOriginMap } from "./service-origins";
 export { withRetry } from "./retry";

package/dist/http/index.js

@@ -6,4 +6,11 @@
  * Accepts baseURL as a constructor option instead.
  */
 export { ApiClient, ApiClientError, apiClient } from "./ApiClient.js";
+/*
+ * The subdomain seam. `configureServiceOrigins` is how a consumer points
+ * `/api/blog/*` or `/api/events/*` at the deployment that OWNS them without
+ * editing a single call site. Registering nothing keeps same-origin behaviour
+ * exactly, so adoption is opt-in per deployment and per prefix.
+ */
+export { configureServiceOrigins, getServiceOrigins, serviceOriginFor, _resetServiceOrigins, } from "./service-origins.js";
 export { withRetry } from "./retry.js";

package/dist/http/service-origins.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Which ORIGIN serves a given API path prefix.
+ *
+ * ## Why this exists
+ *
+ * `/api/blog/*` and `/api/events/*` are no longer served by the shop — they
+ * moved to their own deployments, and the owner's rule for the split is
+ * (2026-11-09):
+ *
+ * > *"let the events or subdomains give APIs for the CRUD operations so
+ * > anywhere can use them, while keeping the carousel slide logic in the
+ * > main."*
+ *
+ * So a consumer keeps its own presentation and changes only where the DATA
+ * comes from. That is a one-line change at the data source — **if** the client
+ * knows which host owns which prefix. This registry is that knowledge.
+ *
+ * ## 🛑 It is CONFIG, not code
+ *
+ * There is no hostname in this file and there must never be one. A deployment
+ * registers its own map at boot from env; an install that registers nothing
+ * keeps today's behaviour exactly — every path resolves against the current
+ * origin, which is what every consumer did before this existed.
+ *
+ * That "registers nothing" default is the whole safety story. Adopting the
+ * seam is opt-in per deployment and per prefix, so the shop can move `/api/blog`
+ * to the subdomain while `/api/events` still resolves locally, verify, and then
+ * move the second one. Three small commits instead of one risky switch.
+ *
+ * ## 🛑 Longest prefix wins, and the trailing-boundary check is not optional
+ *
+ * `/api/blog` must not match `/api/blogger`. Matching on a bare
+ * `startsWith(prefix)` would route an unrelated endpoint to a host that has
+ * never heard of it, and the failure is a 404 from the WRONG server — which
+ * reads as "the data is gone" rather than "the routing is wrong". So a match
+ * requires the next character to be `/` or `?` or end-of-string.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not make the request cross-origin-safe. Pointing a browser at
+ * another origin needs CORS on that origin and credentials handling for the
+ * session cookie. Both subdomains sit under one registrable domain and the
+ * session cookie is widened to it, so a `credentials: "include"` call works —
+ * but the CORS headers are the receiving app's job, not this file's.
+ */
+/** `{ "/api/blog": "https://blogs.example.com" }` — prefix → absolute origin. */
+export type ServiceOriginMap = Readonly<Record<string, string>>;
+/**
+ * Register the prefix → origin map. Idempotent; last call wins.
+ *
+ * Entries with a blank value are DROPPED rather than registered, because the
+ * value normally comes straight from an env var and an unset var must mean
+ * "same origin" — not "resolve against the empty string". A deployment that
+ * has not configured the seam yet must behave exactly as it did before.
+ */
+export declare function configureServiceOrigins(map: ServiceOriginMap): void;
+/** Current map, for diagnostics and admin screens. */
+export declare function getServiceOrigins(): ServiceOriginMap;
+/**
+ * The origin that serves `path`, or `undefined` for "this origin".
+ *
+ * `undefined` rather than a default is deliberate: the caller already has a
+ * correct same-origin fallback, and returning one from here would hide an
+ * unconfigured prefix behind a plausible value.
+ */
+export declare function serviceOriginFor(path: string): string | undefined;
+/** Drop all registrations. Tests only. */
+export declare function _resetServiceOrigins(): void;

package/dist/http/service-origins.js

@@ -0,0 +1,106 @@
+/**
+ * Which ORIGIN serves a given API path prefix.
+ *
+ * ## Why this exists
+ *
+ * `/api/blog/*` and `/api/events/*` are no longer served by the shop — they
+ * moved to their own deployments, and the owner's rule for the split is
+ * (2026-11-09):
+ *
+ * > *"let the events or subdomains give APIs for the CRUD operations so
+ * > anywhere can use them, while keeping the carousel slide logic in the
+ * > main."*
+ *
+ * So a consumer keeps its own presentation and changes only where the DATA
+ * comes from. That is a one-line change at the data source — **if** the client
+ * knows which host owns which prefix. This registry is that knowledge.
+ *
+ * ## 🛑 It is CONFIG, not code
+ *
+ * There is no hostname in this file and there must never be one. A deployment
+ * registers its own map at boot from env; an install that registers nothing
+ * keeps today's behaviour exactly — every path resolves against the current
+ * origin, which is what every consumer did before this existed.
+ *
+ * That "registers nothing" default is the whole safety story. Adopting the
+ * seam is opt-in per deployment and per prefix, so the shop can move `/api/blog`
+ * to the subdomain while `/api/events` still resolves locally, verify, and then
+ * move the second one. Three small commits instead of one risky switch.
+ *
+ * ## 🛑 Longest prefix wins, and the trailing-boundary check is not optional
+ *
+ * `/api/blog` must not match `/api/blogger`. Matching on a bare
+ * `startsWith(prefix)` would route an unrelated endpoint to a host that has
+ * never heard of it, and the failure is a 404 from the WRONG server — which
+ * reads as "the data is gone" rather than "the routing is wrong". So a match
+ * requires the next character to be `/` or `?` or end-of-string.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not make the request cross-origin-safe. Pointing a browser at
+ * another origin needs CORS on that origin and credentials handling for the
+ * session cookie. Both subdomains sit under one registrable domain and the
+ * session cookie is widened to it, so a `credentials: "include"` call works —
+ * but the CORS headers are the receiving app's job, not this file's.
+ */
+/**
+ * Module state, like appkit's brand and baseline resolvers. Server and browser
+ * are two module graphs, so each registers its own copy at boot — see the note
+ * in any consumer's `providers.config.ts` about why both injection points are
+ * required and neither is redundant.
+ */
+let originsByPrefix = {};
+/** Longest-first, so `/api/blog/admin` beats `/api/blog` when both are set. */
+let prefixesByLength = [];
+/**
+ * Register the prefix → origin map. Idempotent; last call wins.
+ *
+ * Entries with a blank value are DROPPED rather than registered, because the
+ * value normally comes straight from an env var and an unset var must mean
+ * "same origin" — not "resolve against the empty string". A deployment that
+ * has not configured the seam yet must behave exactly as it did before.
+ */
+export function configureServiceOrigins(map) {
+    const cleaned = {};
+    for (const [prefix, origin] of Object.entries(map)) {
+        const p = prefix.trim();
+        const o = origin?.trim();
+        if (!p.startsWith("/") || !o)
+            continue;
+        cleaned[p.replace(/\/+$/, "")] = o.replace(/\/+$/, "");
+    }
+    originsByPrefix = cleaned;
+    prefixesByLength = Object.keys(cleaned).sort((a, b) => b.length - a.length);
+}
+/** Current map, for diagnostics and admin screens. */
+export function getServiceOrigins() {
+    return originsByPrefix;
+}
+/**
+ * The origin that serves `path`, or `undefined` for "this origin".
+ *
+ * `undefined` rather than a default is deliberate: the caller already has a
+ * correct same-origin fallback, and returning one from here would hide an
+ * unconfigured prefix behind a plausible value.
+ */
+export function serviceOriginFor(path) {
+    if (!prefixesByLength.length)
+        return undefined;
+    // Compare on the pathname only — a query string must not affect routing.
+    const pathname = path.split(/[?#]/)[0] ?? path;
+    for (const prefix of prefixesByLength) {
+        if (!pathname.startsWith(prefix))
+            continue;
+        // 🛑 Boundary check — see the header. `/api/blog` must not claim
+        // `/api/blogger`.
+        const next = pathname.charAt(prefix.length);
+        if (next === "" || next === "/")
+            return originsByPrefix[prefix];
+    }
+    return undefined;
+}
+/** Drop all registrations. Tests only. */
+export function _resetServiceOrigins() {
+    originsByPrefix = {};
+    prefixesByLength = [];
+}

package/dist/server.d.ts

@@ -520,7 +520,8 @@ export { buildSitemap } from "./_internal/server/features/seo/sitemap";
 export { buildRobots } from "./_internal/server/features/seo/robots";
 export { buildManifest } from "./_internal/server/features/seo/manifest";
 export { buildDefaultOgImage, DEFAULT_OG_SIZE, resolveOgImageUrl } from "./_internal/server/features/seo/og";
-export type { SitemapOptions } from "./_internal/server/features/seo/sitemap";
+export type { SitemapOptions, SitemapSection } from "./_internal/server/features/seo/sitemap";
+export { SITEMAP_SECTIONS } from "./_internal/server/features/seo/sitemap";
 export type { RobotsOptions } from "./_internal/server/features/seo/robots";
 export type { ManifestOptions } from "./_internal/server/features/seo/manifest";
 export type { DefaultOgOptions } from "./_internal/server/features/seo/og";

package/dist/server.js

@@ -1475,6 +1475,7 @@ export { buildSitemap } from "./_internal/server/features/seo/sitemap.js";
 export { buildRobots } from "./_internal/server/features/seo/robots.js";
 export { buildManifest } from "./_internal/server/features/seo/manifest.js";
 export { buildDefaultOgImage, DEFAULT_OG_SIZE, resolveOgImageUrl } from "./_internal/server/features/seo/og.js";
+export { SITEMAP_SECTIONS } from "./_internal/server/features/seo/sitemap.js";
 // -- generateStaticParams slug enumerators --
 // Prerendering a detail route is what puts its <title> in <head> instead of
 // streaming it into <body>; see static-params.ts for the measurement.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.72.0",
+  "version": "4.74.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"