@mohasinac/appkit 4.71.0 → 4.71.2

package/dist/jobs.d.ts

@@ -20,7 +20,7 @@
  *     listingProcessorHandler,
  *   } from "@mohasinac/appkit/jobs";
  */
-export { couponExpiryHandler, offerExpiryHandler, cartPruneHandler, notificationPruneHandler, pageViewRollupHandler, pageViewPruneHandler, dailyDataCleanupHandler, cleanupRtdbEventsHandler, auctionSettlementHandler, autoPayoutEligibilityHandler, countersReconcileHandler, onOrderCreateHandler, onOrderStatusChangeHandler, onReviewWriteHandler, promotionsHandler, mediaTmpCleanupHandler, pendingOrderTimeoutHandler, productStatsSyncHandler, positionsReconcileHandler, weeklyPayoutEligibilityHandler, onCategoryWriteHandler, onProductWriteHandler, onStoreWriteHandler, adminAnalyticsHandler, storeAnalyticsHandler, listingProcessorHandler, supportedListingCollections, onPrizeDrawPaymentConfirmedHandler, prizeDrawSoldOutRevealHandler, prizeDrawExpiryRevealHandler, bundleStockSyncHandler, onProductStockChangeHandler, triggerEventRaffleHandler, assignSpinPrizeHandler, draftPruneHandler, onSupportTicketCreateHandler, onSupportTicketUpdateHandler, onUserBanChangeHandler, onScamReportCreateHandler, onScamReportUpdateHandler, bindSchedule, bindDocumentWritten, bindDocumentCreated, bindDocumentUpdated, bindCallable, bindHttps, bindToFirebase, } from "./_internal/server/jobs/index.js";
+export { couponExpiryHandler, offerExpiryHandler, cartPruneHandler, notificationPruneHandler, pageViewRollupHandler, pageViewPruneHandler, dailyDataCleanupHandler, cleanupRtdbEventsHandler, collectorDropSettlementHandler, autoPayoutEligibilityHandler, countersReconcileHandler, onOrderCreateHandler, onOrderStatusChangeHandler, onReviewWriteHandler, promotionsHandler, mediaTmpCleanupHandler, pendingOrderTimeoutHandler, productStatsSyncHandler, positionsReconcileHandler, weeklyPayoutEligibilityHandler, onCategoryWriteHandler, onProductWriteHandler, onStoreWriteHandler, adminAnalyticsHandler, storeAnalyticsHandler, listingProcessorHandler, supportedListingCollections, onClearancePaymentConfirmedHandler, clearanceSoldOutRevealHandler, clearanceExpiryRevealHandler, bundleStockSyncHandler, onProductStockChangeHandler, triggerEventRaffleHandler, assignSpinPrizeHandler, draftPruneHandler, onSupportTicketCreateHandler, onSupportTicketUpdateHandler, onUserBanChangeHandler, onScamReportCreateHandler, onScamReportUpdateHandler, bindSchedule, bindDocumentWritten, bindDocumentCreated, bindDocumentUpdated, bindCallable, bindHttps, bindToFirebase, } from "./_internal/server/jobs/index.js";
 export { defineFunction, mergeFunctionRegistries, bindAllFromRegistry, APPKIT_FUNCTIONS, APPKIT_FUNCTIONS_BY_NAME, } from "./_internal/server/functions/index.js";
 export { orderRepository, siteSettingsRepository } from "./repositories/index.js";
 export type { OrderDocument, OrderDocumentItem } from "./features/orders/index.js";

package/dist/jobs.js

@@ -22,9 +22,9 @@
  */
 export { 
 // S4–S5: Job handlers (pure, framework-agnostic)
-couponExpiryHandler, offerExpiryHandler, cartPruneHandler, notificationPruneHandler, pageViewRollupHandler, pageViewPruneHandler, dailyDataCleanupHandler, cleanupRtdbEventsHandler, auctionSettlementHandler, autoPayoutEligibilityHandler, countersReconcileHandler, onOrderCreateHandler, onOrderStatusChangeHandler, onReviewWriteHandler, promotionsHandler, mediaTmpCleanupHandler, pendingOrderTimeoutHandler, productStatsSyncHandler, positionsReconcileHandler, weeklyPayoutEligibilityHandler, onCategoryWriteHandler, onProductWriteHandler, onStoreWriteHandler, adminAnalyticsHandler, storeAnalyticsHandler, listingProcessorHandler, supportedListingCollections, 
-// SB1-L (S7-PrizeDraws) — prize-draw reveal redesigned to a fully-automatic model.
-onPrizeDrawPaymentConfirmedHandler, prizeDrawSoldOutRevealHandler, prizeDrawExpiryRevealHandler, bundleStockSyncHandler, 
+couponExpiryHandler, offerExpiryHandler, cartPruneHandler, notificationPruneHandler, pageViewRollupHandler, pageViewPruneHandler, dailyDataCleanupHandler, cleanupRtdbEventsHandler, collectorDropSettlementHandler, autoPayoutEligibilityHandler, countersReconcileHandler, onOrderCreateHandler, onOrderStatusChangeHandler, onReviewWriteHandler, promotionsHandler, mediaTmpCleanupHandler, pendingOrderTimeoutHandler, productStatsSyncHandler, positionsReconcileHandler, weeklyPayoutEligibilityHandler, onCategoryWriteHandler, onProductWriteHandler, onStoreWriteHandler, adminAnalyticsHandler, storeAnalyticsHandler, listingProcessorHandler, supportedListingCollections, 
+// SB1-L (S7-PrizeDraws) — clearance reveal redesigned to a fully-automatic model.
+onClearancePaymentConfirmedHandler, clearanceSoldOutRevealHandler, clearanceExpiryRevealHandler, bundleStockSyncHandler, 
 // SB-UNI-V — Firestore onWrite trigger for product stock changes.
 onProductStockChangeHandler, triggerEventRaffleHandler, assignSpinPrizeHandler, 
 // SB-UNI-Y-1 — daily draft prune for store form drafts

package/dist/next/api/api-response.d.ts

@@ -5,7 +5,7 @@
  * No app-specific dependencies — safe to use in any project.
  */
 import { NextResponse } from "next/server";
-import type { JsonValue } from "@mohasinac/appkit";
+import type { JsonValue } from "../../schemas/types";
 import type { ApiIssue } from "../../client/api/ApiError";
 import { type ApiErrorEnvelope } from "../../errors/error-envelope";
 export interface ApiSuccessResponse<T = unknown> {

package/dist/next/api/parseJsonBody.d.ts

@@ -1,4 +1,4 @@
-import type { FirestoreDocument } from "@mohasinac/appkit";
+import type { FirestoreDocument } from "../../schemas/types";
 /**
  * Strict JSON body parser for createRouteHandler handlers that need a body
  * but don't yet use the wrapper's `schema` option. Replaces the silent

package/dist/next/api/routeHandler.d.ts

@@ -16,7 +16,12 @@ export interface RouteUser {
     email?: string | null;
     displayName?: string;
     name?: string | null;
+    /** Legacy scalar — the highest-ranked held role. Never gate on it alone. */
     role?: string;
+    /** THE role authority from the token claims. Read it via `rolesOf`. */
+    roles?: string[];
+    /** Display label only. */
+    primaryRole?: string;
     [key: string]: FirestoreValue;
 }
 interface RouteHandlerOptions<TInput = unknown, TParams = Record<string, string>> {

package/dist/next/api/routeHandler.js

@@ -30,7 +30,7 @@ import { normalizeError } from "../../errors/normalize.js";
  */
 import { NextResponse } from "next/server.js";
 import { getProviders } from "../../contracts/index.js";
-import { isEffectiveAdminUser, isTesterUser, canTestAdminSurfaces } from "../../features/auth/role-predicates.js";
+import { isEffectiveAdminUser, isTesterUser, canTestAdminSurfaces, holdsAnyRole } from "../../features/auth/role-predicates.js";
 import { mapToHttpError, HTTP_ERROR_CODES } from "../../errors/error-mapping.js";
 import { describeCauseChain } from "../../errors/describe-cause.js";
 import { buildErrorEnvelope, toApiIssues } from "../../errors/error-envelope.js";
@@ -64,7 +64,16 @@ async function verifySession(request) {
         return {
             uid: payload.uid,
             email: payload.email,
+            /*
+             * 🛑 Both shapes, and `...payload.claims` can no longer overwrite them —
+             * the session provider strips the three role keys out of the claims bag
+             * precisely because this spread comes last. `roles` is the authority;
+             * `role` is the derived highest-ranked scalar for anything not yet
+             * converted.
+             */
             role: payload.role,
+            roles: payload.roles,
+            primaryRole: payload.primaryRole,
             emailVerified: payload.emailVerified,
             ...payload.claims,
         };
@@ -210,7 +219,20 @@ export function createRouteHandler(options) {
                 : options.permission
                     ? ["admin", "employee"]
                     : [];
-            if (effectiveRoles.length > 0 && (!user || !effectiveRoles.includes(user.role ?? ""))) {
+            /*
+             * ── The gate reads the SET, not the scalar (1.43) ──────────────────
+             *
+             * Was `effectiveRoles.includes(user.role ?? "")`. With one scalar a
+             * seller who is also an employee passed whichever gate matched the
+             * single stored value and was refused by the other — a 403 on a route
+             * they are entitled to, with no error anywhere explaining it.
+             *
+             * `holdsAnyRole` intersects the user's full role set with the route's
+             * allowed set and also folds `moderator` → `employee`, so a stored
+             * moderator clears an `employee`-gated route without waiting on the
+             * backfill.
+             */
+            if (effectiveRoles.length > 0 && (!user || !holdsAnyRole(user, effectiveRoles))) {
                 const testerEligible = await isTesterEligibleForAdminRoute(user, effectiveRoles);
                 if (!testerEligible || !user) {
                     return errorJson(403, HTTP_ERROR_CODES.FORBIDDEN, "Insufficient permissions", requestId);

package/dist/next/components/UnauthorizedView.d.ts

@@ -11,6 +11,7 @@
  *     return <UnauthorizedView loginHref="/en/auth/login" />;
  *   }
  */
+import type { DashboardCard } from "../../_internal/shared/features/dashboard/recent-entry";
 export interface UnauthorizedViewProps {
     /** Override the heading text. */
     heading?: string;
@@ -24,5 +25,7 @@ export interface UnauthorizedViewProps {
     homeLabel?: string;
     /** href for the home link. */
     homeHref?: string;
+    /** Admin-curated page-region cards (Phase 12). Omit for no extra content. */
+    pageRegionCards?: DashboardCard[];
 }
-export declare function UnauthorizedView({ heading, description, loginLabel, loginHref, homeLabel, homeHref, }: UnauthorizedViewProps): import("react").JSX.Element;
+export declare function UnauthorizedView({ heading, description, loginLabel, loginHref, homeLabel, homeHref, pageRegionCards, }: UnauthorizedViewProps): import("react").JSX.Element;

package/dist/next/components/UnauthorizedView.js

@@ -16,7 +16,8 @@ import { Row } from "../../ui/components/Layout.js";
 import { Heading, Text } from "../../ui/components/Typography.js";
 import { TextLink } from "../../ui/components/TextLink.js";
 import { DEFAULT_ROUTE_MAP } from "../routing/route-map.js";
+import { AdminComposableRegion } from "../../features/dashboard/components/AdminComposableRegion.js";
 import { Stack } from "@mohasinac/appkit/client";
-export function UnauthorizedView({ heading = "401 — Unauthorized", description = "You need to be signed in to view this page.", loginLabel = "Sign in", loginHref = DEFAULT_ROUTE_MAP.AUTH.LOGIN, homeLabel = "Go home", homeHref = DEFAULT_ROUTE_MAP.HOME, }) {
-    return (_jsxs(Stack, { justify: "center", className: "min-h-[60vh] text-center", padding: "x-xl", align: "center", children: [_jsx(Heading, { level: 1, variant: "primary", size: "7xl", className: "mb-2", weight: "bold", children: "401" }), _jsx(Heading, { level: 2, className: "mb-3", children: heading }), _jsx(Text, { variant: "secondary", className: "mb-8", children: description }), _jsxs(Row, { gap: "md", children: [_jsx(TextLink, { href: loginHref, children: loginLabel }), _jsx(TextLink, { href: homeHref, children: homeLabel })] })] }));
+export function UnauthorizedView({ heading = "401 — Unauthorized", description = "You need to be signed in to view this page.", loginLabel = "Sign in", loginHref = DEFAULT_ROUTE_MAP.AUTH.LOGIN, homeLabel = "Go home", homeHref = DEFAULT_ROUTE_MAP.HOME, pageRegionCards = [], }) {
+    return (_jsxs(Stack, { justify: "center", className: "min-h-[60vh] text-center", padding: "x-xl", align: "center", children: [_jsx(Heading, { level: 1, variant: "primary", size: "7xl", className: "mb-2", weight: "bold", children: "401" }), _jsx(Heading, { level: 2, className: "mb-3", children: heading }), _jsx(Text, { variant: "secondary", className: "mb-8", children: description }), _jsxs(Row, { gap: "md", children: [_jsx(TextLink, { href: loginHref, children: loginLabel }), _jsx(TextLink, { href: homeHref, children: homeLabel })] }), _jsx(AdminComposableRegion, { pageId: "unauthorized", initialCards: pageRegionCards })] }));
 }

package/dist/next/index.d.ts

@@ -12,8 +12,10 @@ export { createApiHandlerFactory } from "./api/apiHandler";
 export { createRouteHandler as createApiHandler } from "./api/routeHandler";
 export type { ApiHandlerOptions, ApiHandlerFactoryDeps, ApiRateLimitResult, } from "./api/apiHandler";
 export { getSearchParams, getOptionalSessionCookie, getRequiredSessionCookie, getBooleanParam, getStringParam, getNumberParam, } from "./request-helpers";
-export { DEFAULT_ROUTE_MAP, createRouteMap, ROUTES, PUBLIC_ROUTES, PROTECTED_ROUTES, AUTH_ROUTES, } from "./routing/route-map";
+export { DEFAULT_ROUTE_MAP, createRouteMap, routesForPortal, ROUTES, PUBLIC_ROUTES, PROTECTED_ROUTES, AUTH_ROUTES, } from "./routing/route-map";
 export type { RouteMap, RoutePath } from "./routing/route-map";
+export { PORTAL_DEFINITIONS, PORTAL_SECTIONS, portalForHost, portalSectionForHost, portalHostFor, portalSectionForRoles, isPortalSectionPath, resolvePortalPath, portalHref, canonicalHostFromSiteUrl, resolveCanonicalSite, canonicalSiteHref, mainSiteOriginFromPortalHost, isNonPublicHost, isOffCanonicalHost, } from "./routing/portals";
+export type { PortalDefinition, ResolvedCanonicalSite } from "./routing/portals";
 export { withCache, invalidateCache } from "./cache-middleware";
 export type { CacheConfig } from "./cache-middleware";
 export { createApiMiddleware, runChain, buildBaseContext, } from "./middleware/chain";

package/dist/next/index.js

@@ -13,7 +13,11 @@ export { createRouteHandler as createApiHandler } from "./api/routeHandler.js";
 // Request parsing helpers
 export { getSearchParams, getOptionalSessionCookie, getRequiredSessionCookie, getBooleanParam, getStringParam, getNumberParam, } from "./request-helpers.js";
 // Shared route-map primitives (SSR apps can extend/override)
-export { DEFAULT_ROUTE_MAP, createRouteMap, ROUTES, PUBLIC_ROUTES, PROTECTED_ROUTES, AUTH_ROUTES, } from "./routing/route-map.js";
+export { DEFAULT_ROUTE_MAP, createRouteMap, routesForPortal, ROUTES, PUBLIC_ROUTES, PROTECTED_ROUTES, AUTH_ROUTES, } from "./routing/route-map.js";
+// Portal hosts — the `role.<domain>` convention, derived rather than listed.
+// Zero-import and pure, so `src/proxy.ts` (Edge) and the ROUTES layer share
+// ONE definition instead of the two hand-synced hostname lists this replaced.
+export { PORTAL_DEFINITIONS, PORTAL_SECTIONS, portalForHost, portalSectionForHost, portalHostFor, portalSectionForRoles, isPortalSectionPath, resolvePortalPath, portalHref, canonicalHostFromSiteUrl, resolveCanonicalSite, canonicalSiteHref, mainSiteOriginFromPortalHost, isNonPublicHost, isOffCanonicalHost, } from "./routing/portals.js";
 // Response caching middleware
 export { withCache, invalidateCache } from "./cache-middleware.js";
 // PII-aware composable middleware chain (Phase 21)

package/dist/next/routing/portals.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Portal hosts — THE one definition of the `role.<domain>` convention.
+ *
+ * `src/proxy.ts` used to carry three hardcoded hostname literals
+ * (`admin.letitrip.in`, `seller.letitrip.in`, `auth.letitrip.in`) and
+ * `appkit.config.js` carried a hand-synced second copy of the same three.
+ * Three times in one day a new subdomain went live with no entry in either
+ * list and silently fell through to the public homepage. This module replaces
+ * both lists with a DERIVATION, so a new portal is one row of data and a new
+ * *domain* is zero rows.
+ *
+ * ── Why the base domain is not configured here ───────────────────────────────
+ *
+ * A portal is identified by its FIRST HOSTNAME LABEL, not by a full hostname.
+ * `admin.letitrip.in`, `admin.someotherclient.com` and `admin.localhost` all
+ * resolve to the same portal with no configuration at all. That is what makes
+ * this domain-independent in the sense the plan requires: a different client on
+ * a different domain gets correct portal routing without editing Edge code or
+ * setting an env var, and the same code is testable against a local dev server
+ * with nothing but a `Host:` header.
+ *
+ * The canonical host IS configured (`seo.siteUrl` / `NEXT_PUBLIC_SITE_URL`),
+ * because "where do I send a visitor who is on the wrong host" genuinely needs
+ * an answer this module cannot derive. See `canonicalHostFromSiteUrl`.
+ *
+ * ── Constraints this file must keep ──────────────────────────────────────────
+ *
+ * 1. **Zero imports.** It is consumed by `src/proxy.ts`, which runs on the Edge
+ *    runtime and deliberately imports no config module (see that file's own
+ *    header). A pure, dependency-free module is safe there, in RSC, and in the
+ *    browser alike — which is also what lets the proxy and the `ROUTES` layer
+ *    share ONE definition instead of drifting apart as the old pair did.
+ * 2. **Locale-agnostic.** `routing.locales` lives in the host app, so every
+ *    function here takes an already-locale-stripped path. The caller owns the
+ *    locale split; see `src/proxy.ts`.
+ * 3. **No role equality in a consumer.** The role -> portal mapping is the DATA
+ *    in `PORTAL_DEFINITIONS` below. A consumer asks
+ *    `portalSectionForRoles(roles)`; it never compares a role string itself.
+ */
+/** One portal: a subdomain label, the route section it serves, who lands there. */
+export interface PortalDefinition {
+    /**
+     * The first hostname label. `<label>.<anything>` resolves to this portal.
+     */
+    label: string;
+    /**
+     * The route section this portal serves, with a leading slash and no
+     * trailing one. `admin.<domain>/` renders exactly what `/admin` renders.
+     */
+    section: string;
+    /**
+     * Roles that land on this portal. Empty means the portal is not role-backed
+     * (`auth` is a flow, not a dashboard).
+     *
+     * 🛑 The role value is `seller`, never `vendor` — "vendor" is the
+     * external-facing word only, and introducing it as a second literal is a
+     * standing project prohibition.
+     */
+    roles: readonly string[];
+    /**
+     * The catch-all portal: every role not claimed by an earlier definition
+     * lands here. Exactly one definition may set it.
+     *
+     * Owner, 2026-11-07: "3 main and rest go to employee". So `employee.` is an
+     * ENTRY POINT, not a fixed page — `moderator`, `tester`, and the future
+     * auditor / bookkeeping / management roles all arrive there.
+     */
+    roleCatchAll?: boolean;
+    /**
+     * Where a bare `/` on this portal's host LANDS, when that is not the section
+     * root. Defaults to `section`.
+     *
+     * 🛑 Exists because `auth.<domain>/` measured a hard 404: `/auth` is a
+     * directory of flows (`login`, `register`, `reset-password`) with no index
+     * page, so resolving the host root to the section root sent every visitor to
+     * the auth portal's front door to "404 — Page not found". A portal host that
+     * 404s at its root is indistinguishable from a broken domain.
+     *
+     * Kept as DATA on the definition rather than a special case in the resolver,
+     * so the next portal whose section has no index page is one field, not
+     * another branch.
+     */
+    home?: string;
+}
+/**
+ * 🛑 ORDER IS SIGNIFICANT — it is the resolution priority for a user holding
+ * several roles, and `maxRolesPerUser` is 3 today and configured to grow.
+ * `admin` first encodes "admin sees everything everywhere": an admin who also
+ * holds `employee` gets the admin dashboard at `employee.<domain>`, not the
+ * employee one. Reordering this list changes that behaviour, which is the
+ * point — it is data, editable without touching a mechanism.
+ */
+export declare const PORTAL_DEFINITIONS: readonly PortalDefinition[];
+/** Every route section a portal serves. Derived; never hand-maintained. */
+export declare const PORTAL_SECTIONS: readonly string[];
+/** True for a dev/preview origin that no public-host rule should police. */
+export declare function isNonPublicHost(hostname: string): boolean;
+/**
+ * The portal a hostname resolves to, by its first label — or null when the
+ * host is not a portal host.
+ *
+ * Deliberately does NOT require the rest of the hostname to match a configured
+ * base domain: see this module's header. The consequence worth naming is that
+ * a client whose real public host begins with one of these labels (a site
+ * genuinely living at `user.example.com`) would be read as a portal. That is
+ * the cost of the convention itself, and the convention is the owner's.
+ */
+export declare function portalForHost(hostname: string): PortalDefinition | null;
+/** The route section a hostname's portal serves, or null for a non-portal host. */
+export declare function portalSectionForHost(hostname: string): string | null;
+/** `admin` + `letitrip.in` -> `admin.letitrip.in`. For building outbound links. */
+export declare function portalHostFor(label: string, baseDomain: string): string;
+/**
+ * Which dashboard a visitor sees, computed from their ROLE SET.
+ *
+ * 🛑 Keyed on the UNION of roles, never on a single `primaryRole` scalar: the
+ * role -> portal mapping is many-to-one, so a scalar would silently strand
+ * anyone holding two roles. Resolution order is `PORTAL_DEFINITIONS`' order,
+ * which is why `admin` is first.
+ *
+ * Returns the catch-all portal's section for a role the table does not name —
+ * that is what makes a NEW role (auditor, bookkeeper) land somewhere real
+ * without a code change. Returns null only when there is no catch-all, which
+ * the data above makes impossible today.
+ */
+export declare function portalSectionForRoles(roles: readonly string[]): string | null;
+/**
+ * True when a locale-stripped path already addresses a portal section
+ * explicitly.
+ *
+ * 🛑 This is what stops the host rewrite from double-prefixing, and the bare
+ * `startsWith(portalPrefix)` it replaces was wrong in two directions:
+ *
+ *   · `admin.<domain>/auth/login` — the RBAC gate's own redirect target — was
+ *     rewritten to `/admin/auth/login`, a 404. An admin bounced to the login
+ *     page from the admin host could not reach it.
+ *   · `admin.<domain>/user/profile` — the sidebar's "My Profile" link —
+ *     became `/admin/user/profile`, also a 404.
+ *
+ * Both were live, and both are fixed by asking "is this ANY portal section"
+ * rather than "is this MY portal section".
+ */
+export declare function isPortalSectionPath(path: string): boolean;
+/**
+ * Resolve a requested (locale-stripped) path to the path the app should
+ * render, given the portal section the HOST implies.
+ *
+ * `/` -> the section itself, so `admin.<domain>/` renders the admin dashboard.
+ * Already-portal-addressed and escape-hatch paths pass through untouched.
+ *
+ * Pure and idempotent: feeding the output back in returns it unchanged.
+ */
+export declare function resolvePortalPath(path: string, section: string | null): string;
+/**
+ * The 1.28 helper: render an internal href the way it should LOOK on the host
+ * the page is being served from.
+ *
+ * `ROUTES.*` bake the portal segment in (`ROUTES.ADMIN.PRODUCTS` is
+ * `/admin/products`) because that is the real app path and must stay so on the
+ * canonical host. On `admin.<domain>` the segment is already implied by the
+ * host, so the URL a visitor should see is `admin.<domain>/products`. This
+ * strips exactly the active section and nothing else — a `/user/profile` link
+ * rendered on the admin host keeps its prefix, because it genuinely leaves the
+ * admin section.
+ *
+ * Server-safe and pure, so it works unchanged in RSC, in a client component,
+ * and in the Edge proxy. `section` is null on the canonical host, where this
+ * is the identity function and today's behaviour is preserved byte-for-byte.
+ */
+export declare function portalHref(path: string, section: string | null): string;
+/** The canonical hostname a `siteUrl` names, or null when it cannot be parsed. */
+export declare function canonicalHostFromSiteUrl(siteUrl: string): string | null;
+/** What `resolveCanonicalSite` concluded, and where the answer came from. */
+export interface ResolvedCanonicalSite {
+    /** Absolute origin to redirect to. */
+    siteUrl: string;
+    /** Its hostname, normalised — what `isOffCanonicalHost` compares against. */
+    host: string;
+    /**
+     * `"declared"` when the configured canonical host answered; `"inferred"`
+     * when a platform-provided fallback did. A caller may want to log the
+     * difference: running on an inferred host means the configured one is
+     * missing, which is a misconfiguration even though the guard still works.
+     */
+    source: "declared" | "inferred";
+}
+/**
+ * Resolve the canonical site — the host an off-canonical request is sent to.
+ *
+ * ── Why this takes candidates instead of reading the environment ────────────
+ *
+ * appkit is a domain-independent product: it must not know a particular
+ * platform's env var names, and it must NEVER carry a fallback domain literal.
+ * The caller supplies the candidates; this function owns which ones are
+ * acceptable.
+ *
+ * ── `declared` vs `inferred`, and why they are not one list ─────────────────
+ *
+ * `declared` is the project's configured canonical host and is taken at its
+ * word, including a localhost origin — that is the correct canonical host on a
+ * development machine, and a guard that refused it would be untestable
+ * locally, i.e. unverifiable.
+ *
+ * `inferred` candidates are platform guesses and are held to a stricter rule:
+ * 🛑 an inferred candidate resolving to a dev/preview host is REJECTED. On
+ * Vercel the natural fallback is the platform's own production-URL variable,
+ * and if a project's production domain assignment resolves to
+ * `<project>.vercel.app`, accepting it would make the real public host look
+ * off-canonical and 301 `www.<domain>` → `<project>.vercel.app`. That is
+ * strictly WORSE than no guard: it would hand the canonical signal for the
+ * whole site to a preview origin. Rejecting preview hosts is what makes
+ * offering a platform fallback safe at all.
+ *
+ * Returning null means MISCONFIGURED, not "use a default". The caller must say
+ * so loudly rather than degrade in silence — see `src/proxy.ts`, where a null
+ * here is logged as an error on the first request of each instance.
+ */
+export declare function resolveCanonicalSite(declared: string | undefined | null, inferred?: readonly (string | undefined | null)[]): ResolvedCanonicalSite | null;
+/**
+ * True when this request should be redirected to the canonical host.
+ *
+ * The GENERAL rule the plan asks for, not a list of offending hostnames: any
+ * host that is neither the canonical host nor a mapped portal nor a
+ * dev/preview origin is serving a duplicate of the canonical site and gets a
+ * 301. `audit.`, `tools.` and every subdomain added later are covered the day
+ * they are attached, with no code change.
+ */
+export declare function isOffCanonicalHost(hostname: string, canonicalHost: string | null): boolean;
+/**
+ * An absolute href on the canonical host — the "Back to main site" link.
+ *
+ * 🛑 Absolute BY NECESSITY. A relative `/` rendered on `admin.<domain>` keeps
+ * the visitor on the portal subdomain and, because `/` resolves to the
+ * section, lands them straight back on the dashboard they were trying to
+ * leave. Leaving a subdomain requires naming the host.
+ */
+export declare function canonicalSiteHref(path: string, siteUrl: string): string;
+/**
+ * The main site's origin, derived from a PORTAL hostname by dropping the
+ * portal label — `https://admin.letitrip.in` -> `https://letitrip.in`, and
+ * `http://admin.localhost:3001` -> `http://localhost:3001`. Returns null when
+ * the host is not a portal host (there is nothing to go back FROM).
+ *
+ * ── Why derive instead of reading the configured canonical host ─────────────
+ *
+ * This is what lets the "Back to main site" link live in SHARED CHROME with no
+ * per-layout plumbing and no env var: appkit is a domain-independent product,
+ * and a chrome component that needs the host app's `siteUrl` threaded into it
+ * would have to be wired separately in every portal layout — four files today
+ * and one more per portal added, which is the per-site editing this module
+ * exists to remove.
+ *
+ * ⚠ TWO honest costs, both deliberate:
+ *   1. It targets the APEX (`letitrip.in`), not the canonical `www` host, so
+ *      in production the link takes one extra 308 hop through the apex->www
+ *      redirect Vercel already serves. A nav link can afford one hop; what it
+ *      cannot afford is pointing at a host that does not exist on a different
+ *      client's domain.
+ *   2. A client whose main site genuinely lives on a deeper host would need the
+ *      override. `canonicalOrigin` on the consuming component exists for that
+ *      and wins whenever it is supplied.
+ *
+ * The port is preserved, which is what makes this verifiable against a local
+ * dev server rather than only in production.
+ */
+export declare function mainSiteOriginFromPortalHost(hostOrigin: string): string | null;