@mohasinac/appkit 4.73.0 → 4.75.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.73.0",
-  "head": "be53458929a89f0a763476ca3082d1bfe65b3bcb",
+  "version": "4.75.0",
+  "head": "c5426d7535f8b4331464486d52298a6f668168ee",
   "branch": "main",
   "dirty": true,
-  "builtAt": "2026-11-09T00:57:51.740Z"
+  "builtAt": "2026-11-09T07:08:58.762Z"
 }

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/next/routing/portals.js

@@ -64,6 +64,29 @@ export const PORTAL_DEFINITIONS = [
      * this module exists to end.
      */
     { label: "auth", section: "/auth", roles: [], home: "/auth/login" },
+    /*
+     * ── help: a PORTAL, not a deployment (owner, 2026-11-09) ──────────────
+     *
+     * The plan had `help.<domain>` down as its own app alongside blogs and
+     * events. The owner's answer was "do like dashboards" — i.e. a host rewrite
+     * onto the main app, the same treatment `admin.`/`seller.`/`user.` get, and
+     * NOT a deployment.
+     *
+     * It is the right call for this surface: `/help` is six content pages with
+     * ZERO API routes (measured 2026-11-09). Everything the subdomain split buys
+     * — an independently deployable owner of its own data, exposing CRUD over
+     * HTTP — is worth nothing when there is no data and no CRUD. It would be a
+     * whole deployment, Vercel project, env set and CORS gate to serve six static
+     * pages the shop already renders.
+     *
+     * Consequently `help` is REMOVED from DEPLOYMENT_LABELS below. A label must
+     * be in exactly one of the two lists: in both, the deployment check wins and
+     * the rewrite silently never fires.
+     *
+     * `roles: []` like `auth` — the help centre is public, and a visitor with no
+     * account is precisely who needs it.
+     */
+    { label: "help", section: "/help", roles: [] },
 ];
 /**
  * Hosts that are their OWN DEPLOYMENT, not a portal of this app.
@@ -93,8 +116,20 @@ export const DEPLOYMENT_LABELS = [
     "blogs",
     "live",
     "media",
-    "help",
-    "chat",
+    /*
+     * 🛑 `help` WAS HERE and has moved to PORTAL_DEFINITIONS above — the
+     * owner chose a host rewrite over a deployment for it (2026-11-09). A label
+     * in BOTH lists is the bug this note exists to prevent: `isDeploymentHost`
+     * is consulted first, so the portal rewrite would silently never fire and
+     * `help.<domain>` would fall through to the homepage — exactly the duplicate
+     * content CLAUDE.md records for `audit.` and `tools.`.
+     *
+     * ⚠ `chat` IS ALSO ABSENT, and for a different reason: there is nothing to
+     * serve. `/chat` has ZERO pages in the shop (measured 2026-11-09), so making
+     * it a portal would rewrite `chat.<domain>` onto a 404, and making it a
+     * deployment would point a hostname at an app that does not exist. It joins
+     * one list or the other when it has a surface — not before.
+     */
 ];
 /** Is this hostname a separate deployment rather than a portal of this app? */
 export function isDeploymentHost(hostname) {

package/package.json

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