@coolms/core-angular 2.0.0-alpha.4 → 2.0.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coolms/core-angular",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-alpha.6",
   "description": "The CoolMS client runtime for Angular: session and token refresh, boot manifest and app configuration, theme, user preferences, error handling, HTTP interceptors, and the wire types the CoolMS API emits.",
   "license": "MIT",
   "author": {
@@ -17,7 +17,7 @@
     "rxjs": "^7.8.0"
   },
   "engines": {
-    "node": "^22.22.3 || ^24.15.0 || >=26"
+    "node": "^22.22.3 || ^24.15.0 || ^26.0.0"
   },
   "keywords": [
     "coolms",

package/types/coolms-core-angular.d.ts

@@ -3,7 +3,7 @@ import * as i0 from "@angular/core";
 import { EnvironmentProviders, InjectionToken, Provider, Type } from "@angular/core";
 import { StateContext } from "@ngxs/store";
 import { CanActivateFn, CanMatchFn, Routes } from "@angular/router";
-import { HttpContextToken, HttpInterceptorFn } from "@angular/common/http";
+import { HttpContextToken, HttpInterceptorFn, HttpRequest } from "@angular/common/http";
 export interface AuthApiManifest {
   readonly login: string;
   readonly logout: string;
@@ -277,6 +277,15 @@ export interface ApiManifest {
   }>;
   readonly platformDefaults?: PlatformDefaults;
 }
+/**
+ * GET /api/v1/admin/manifest -- the admin's endpoint map, answered to every signed-in account
+ * since 2026-10-06 (no host groups: each call it names is decided by its own route). A server
+ * from before that answers at /api/v1/console/manifest, to the console group only. Read once
+ * signed in.
+ */
+export interface ConsoleManifestResponse {
+  readonly manifest: ApiManifest;
+}
 export interface ThemeConfigResponse {
   readonly slug?: string | null;
   readonly feStack?: string | null;
@@ -536,10 +545,28 @@ export interface CentrifugoSubscriptionTokenDto {
  *
  * `ApiService` keeps its identical signatures and delegates here, so nothing
  * calling it had to change.
+ *
+ * !! Access first, then realtime (Dmitry, 2026-09-28): "The console opens a realtime
+ * connection before the access check. Reverse the order ... A refused account opens no
+ * socket." The socket cannot open without the connection token, and anything may ask for
+ * one early -- the ring subscription is built at app init and asks as soon as a user is
+ * set, before the guard's answer is in. So the token waits for the console's answer (the
+ * guard's own request, not a second one) and a refused sign-in gets none: no request, no
+ * socket. A failure to ask is not a refusal, as at the guard.
+ *
+ * Since 2026-10-06 the connection token is every signed-in account's (Dmitry: "The connection
+ * token only opens a socket; each channel is authorized when it is subscribed to"), and a
+ * current server answers the admin manifest to every signed-in account, so no
+ * sign-in is refused and every one gets its token; each subscription is then decided by its
+ * channel. The wait stays for a server from before that, where a refused sign-in still opens
+ * no socket.
  */
 export declare class RealtimeTokenClient {
+  /** The error a refused sign-in's connection-token request ends with. */
+  static readonly REFUSED = "no console access: no realtime connection";
   private readonly http;
   private readonly store;
+  private readonly injector;
   private get manifest();
   connectionToken(): Observable<CentrifugoConnectionTokenDto>;
   subscriptionToken(channel: string): Observable<CentrifugoSubscriptionTokenDto>;
@@ -607,6 +634,12 @@ export declare class AuthState {
  * will have placed a non-null (but expired) token in state, causing the guard
  * to pass even though the subsequent config/refresh requests will fail and
  * dispatch Logout.  Waiting for ready$ guarantees the auth state is settled.
+ *
+ * Signed in is not enough: the console is granted, and the server says to whom
+ * (ConsoleAccessService). An account it refuses -- a customer who registered on the
+ * public site -- is signed out of this sign-in, on the server as well as here, and
+ * sent to the login page, which says why. A failure to ask is not a refusal: the console opens, and every request it
+ * makes is still decided by the server.
  */
 export declare const authGuard: CanActivateFn;
 /**
@@ -784,10 +817,15 @@ export interface ElevationState {
   lifetimeCeilingSeconds: number;
   /** Whether the CURRENT elevation was confirmed by a second factor; absent or null when not elevated. */
   factorConfirmed?: boolean | null;
-  /** Whether a grant made now must carry a code from the admin authenticator. */
+  /** Whether a grant made now must carry a code from the person's own authenticator. */
   mfaRequired: boolean;
-  /** What the prompt shows before asking; two of the codes mean the installation cannot elevate yet. */
+  /** What the prompt shows before asking; two of the codes mean this account cannot elevate yet. */
   warnings: ElevationWarning[];
+  /**
+   * Whether this account may elevate at all -- a member of the admin group, elevated or not. The one source a
+   * client offers "Elevate session" from; absent (an older server) reads as false.
+   */
+  mayElevate?: boolean;
 }
 /**
  * `closed` is the beacon (the panel was closed or reloaded), `dropped_by_user`
@@ -801,8 +839,9 @@ export interface ElevationEnded {
   at: string | null;
 }
 /**
- * `elevation.password_not_set` and `elevation.factor_missing` mean the
- * installation cannot elevate and the message names the server command;
+ * `elevation.password_not_set` and `elevation.factor_missing` mean this
+ * account cannot elevate (it has no password, or no confirmed factor, of its
+ * own) and the message says which;
  * `elevation.mfa_off` is the recommendation carried while the switch is off.
  */
 export interface ElevationWarning {
@@ -826,8 +865,8 @@ export type ElevationDropReason = 'dropped_by_user' | 'closed';
  *
  * `state` is the server's answer at the moment of asking -- `ended.reason` is
  * rendered first (a person asked for a password again after F5
- * with no explanation reads it as a fault), `warnings` may say the
- * installation cannot elevate yet, `mfaRequired` decides whether a code field
+ * with no explanation reads it as a fault), `warnings` may say this
+ * account cannot elevate yet, `mfaRequired` decides whether a code field
  * shows from the start.
  *
  * `refusal` is the server's own sentence for the action that was refused
@@ -837,6 +876,8 @@ export type ElevationDropReason = 'dropped_by_user' | 'closed';
 export interface ElevationPromptRequest {
   state: ElevationState;
   refusal?: string;
+  /** The refused action in words ("Saving navi nodes"), when a refused request opened the prompt. */
+  action?: string;
 }
 /**
  * The prompt itself is a dialog, and dialogs are the kit's -- a layer above
@@ -858,6 +899,31 @@ export interface ElevationPromptPort {
  * prompt to show and loses nothing.
  */
 export declare const ELEVATION_PROMPT: InjectionToken<ElevationPromptPort>;
+/**
+ * Told when an action a person took was refused for want of elevation: a
+ * write (not a read, not a background request) answered by a stamped 403.
+ *
+ * It must not open the prompt. The prompt opens only when the person asks for
+ * it -- the application shows the refusal and offers elevation as something to
+ * click (a notice with an Elevate button), and the click is what calls
+ * {@link ElevationService.offerFor}. A refused action is not repeated by
+ * itself after a grant: the person repeats it.
+ *
+ * `refusal` is the server's sentence for the refused action, already made
+ * readable by the error service.
+ */
+export interface ElevationNoticePort {
+  /** `action` names what the person did ("Saving navi nodes"); absent from older callers. */
+  refused(refusal: string, action?: string): void;
+}
+/**
+ * What a write IS, in the person's words, for the elevation prompt and notice when the server refuses it -- set by a
+ * caller that knows better than the URL ("Saving the menu entry"). Without it the interceptor names the method's verb
+ * and the resource the URL names.
+ */
+export declare const ELEVATION_ACTION: HttpContextToken<string | null>;
+/** Optional, like {@link ELEVATION_PROMPT}: with nothing bound, a refusal is only a 403. */
+export declare const ELEVATION_NOTICE: InjectionToken<ElevationNoticePort>;
 /**
  * Set on a request that must never open the elevation prompt: the elevation
  * endpoint's own calls (a wrong password is a 403 and is not a refused action),
@@ -900,6 +966,19 @@ export declare const BYPASS_ELEVATION: HttpContextToken<boolean>;
  * path (media, document and word templates, content distribution).
  */
 export declare const ELEVATION_REQUIRED_HEADER = "X-Elevation-Required";
+/**
+ * Set on a request no person asked for: a realtime token, a preferences sync, a
+ * poll. Its refusal is never announced -- not by a dialog and not by a notice --
+ * because nobody is waiting on it and nobody can act on it. The caller still
+ * receives the 403 and decides what its own state shows.
+ */
+export declare const BACKGROUND_REQUEST: HttpContextToken<boolean>;
+/**
+ * Whether a failed request was refused for want of elevation: a 403 carrying
+ * the server's stamp. The one test every reader of a refusal uses -- the
+ * interceptor, a page's inline state, the error text -- so they cannot disagree.
+ */
+export declare function isElevationRefusal(err: unknown): boolean;
 export declare class ElevationService {
   private readonly http;
   private readonly store;
@@ -923,6 +1002,8 @@ export declare class ElevationService {
   readonly state: () => ElevationState | null;
   /** Convenience over `state`: false until the server has said otherwise. */
   readonly elevated: () => boolean;
+  /** Whether this account may elevate at all, as the server answered it: what "Elevate session" is offered from. */
+  readonly mayElevate: () => boolean;
   /** `expiresAt` as a Date, null when not elevated. */
   readonly expiresAt: () => Date | null;
   /**
@@ -937,6 +1018,10 @@ export declare class ElevationService {
   private expiryAnnouncePending;
   private lastReconcileAt;
   constructor();
+  /** Whether a prompt can be opened at all: this install offers elevation and a prompt is bound. */
+  get canPrompt(): boolean;
+  /** The manifest's API base, as {@link isThisApi} reads it. */
+  get apiBase(): string;
   /** The manifest carries the URL; without it the service is inert, not broken. */
   get available(): boolean;
   private get url();
@@ -951,20 +1036,23 @@ export declare class ElevationService {
   /** Ask the server. Applies the answer and announces it when it differs. */
   refresh(): Observable<ElevationState>;
   /**
-   * Elevate with the admin password and, when the switch is on, a code from
-   * the admin authenticator. Errors are the dialog's to branch on: 403 wrong
-   * password or wrong / replayed code, 428 a code is required, 409 the
-   * installation cannot elevate yet, 429 throttled. They pass through
+   * Elevate with the person's own password and, when the switch is on, a
+   * code from their own authenticator. Errors are the dialog's to branch on:
+   * 403 not a member of the admin group, wrong password, or wrong / replayed
+   * code, 428 a code is required, 409 this account cannot elevate yet, 429
+   * throttled. They pass through
    * untouched, and never open the prompt (BYPASS_ELEVATION).
    */
   elevate(password: string, code?: string): Observable<ElevationState>;
   /** Drop the elevation now. Idempotent on the server: nothing live is still a 204. */
   drop(reason?: ElevationDropReason): Observable<ElevationState>;
   /**
-   * What the interceptor calls on a 403: ask the server whether this session
-   * is elevated, and only when it is not, offer the prompt. A 403 while
-   * elevated is a real refusal -- elevation would not change it -- and is
-   * handed back as such (false, no prompt).
+   * What a person's explicit request for elevation calls -- an Elevate button,
+   * or a control that already knows its action needs elevation: ask the
+   * server whether this session is elevated, and only when it is not, open
+   * the prompt. Nothing calls it on a response by itself (the interceptor
+   * only tells {@link ELEVATION_NOTICE}). Elevated already is false, no
+   * prompt: elevation would change nothing.
    */
   offerFor(refusal?: string): Observable<boolean>;
   /**
@@ -1042,36 +1130,54 @@ export declare class ElevationService {
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
 /**
- * The elevation prompt hangs off the 403, not off the listing's flags
- * (the elevation client requirement, point 1) -- and off the 403 that SAYS it
- * was refused for want of elevation: the server stamps `X-Elevation-Required`
- * with the gate's name where its gate refused a member who has not elevated.
- * Any route of this API can carry it -- the VFS, a media asset's
- * permissions, a document template, an account's deletion -- so nothing here
- * lists URLs; the list that stood here lagged the server by every route whose
- * refusal came from the VFS permission service under another module's path.
- *
- * On the stamp: ask the server whether this session is elevated, and only when
- * it is NOT open the prompt; on a grant send the refused request again, once.
- * A 403 without the stamp is a refusal for another reason and is handed back
- * as it came; so are a 403 while elevated, a declined prompt, and an
- * installation that cannot elevate -- nothing here swallows a refusal. A
- * stamped 403 from anywhere but this API is ignored: the header is the
- * server's word, and only this server's counts.
- *
- * Order in the chain: BEFORE the auth interceptor, so the retry re-enters it
- * and carries the token current at that moment (the prompt may have outlived
- * a refresh). The elevation endpoint's own calls carry BYPASS_ELEVATION: a
- * wrong password is a 403 and is not a refused action.
+ * A refusal for want of elevation is a 403 the server stamps `X-Elevation-Required`
+ * where its gate refused a member who has not elevated ({@link isElevationRefusal}).
+ *
+ * What it does with a stamped 403 (decided 2026-10-20 for a person's write):
+ * - On a write a person made (POST, PUT, PATCH, DELETE without {@link BACKGROUND_REQUEST}):
+ *   the prompt opens THERE, above whatever the person is in -- an edit dialog stays open
+ *   beneath it with its input -- and the request is HELD. If the person elevates, it is
+ *   sent once more and the caller receives that answer, as if the first had been accepted;
+ *   if the session turns out to be elevated already (another tab), it is sent once more
+ *   without asking. If the person declines, {@link ELEVATION_NOTICE} is told -- "Elevation
+ *   required", naming the action, with an Elevate button -- and the caller receives the 403.
+ *   The repeat is sent past this interceptor, so a second refusal is a 403, never a second
+ *   prompt.
+ * - On a read: nothing. Reads are what a page makes as it loads and what polls make in
+ *   the background, and the page shows its own state for a refused one -- an inline
+ *   "needs an elevated session" with an Elevate button, or the feature hidden.
+ * - On a background request: nothing. Nobody is waiting on it.
+ *
+ * !! Why reads and background requests still open nothing. Until 2026-10-08 any stamped 403
+ * opened the prompt, so the setup reads of almost every console page, and a realtime token at
+ * every load, opened it for an administrator who had not elevated: 13 of 15 pages on a menu
+ * click, 15 of 15 on a reload (measured). From then until 2026-10-20 a person's write opened
+ * nothing either, only a toast -- which, with a dialog open, rendered under it, so the edit had
+ * to be thrown away to elevate (measured on the served admin, Edit Node). A person's write is
+ * the one refusal somebody is waiting on, which is why it is the one that asks.
+ *
+ * The elevation endpoint's own calls carry {@link BYPASS_ELEVATION}: a wrong password is a
+ * 403 and is not a refused action. A stamped 403 from anywhere but this API is ignored:
+ * the header is the server's word, and only this server's counts.
  */
 export declare const elevationInterceptor: HttpInterceptorFn;
+/**
+ * The action a refused write was, in words for the person: what its caller said it is
+ * ({@link ELEVATION_ACTION}), or else the method's verb and the resource the URL names --
+ * "Saving navi nodes" for `PATCH /api/v1/navi/nodes/{id}`. Identifiers and the API base
+ * are left out; they say nothing to the person who pressed the button.
+ */
+export declare function actionOf(req: HttpRequest<unknown>, apiBase?: string): string;
 export declare class LoginComponent {
   identifier: string;
   password: string;
-  loading: boolean;
-  error: string | null;
+  readonly loading: import("@angular/core").WritableSignal<boolean>;
+  readonly error: import("@angular/core").WritableSignal<string | null>;
   private readonly store;
   private readonly router;
+  /** Shown when the guard signed an account out because the console is not granted to it. */
+  static readonly NO_CONSOLE_ACCESS = "This account has no access to the console.";
+  constructor();
   submit(): void;
   static ɵfac: i0.ɵɵFactoryDeclaration<LoginComponent, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<LoginComponent, "coolms-admin-login", never, {}, {}, never, never, true, never>;
@@ -1113,6 +1219,62 @@ export declare class AppInitService {
   static ɵfac: i0.ɵɵFactoryDeclaration<AppInitService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
+/** What the server said about this sign-in and the console. */
+export type ConsoleAccess = 'granted' | 'refused' | 'unknown';
+/**
+ * Whether the signed-in account may use the console, and the console's endpoint
+ * map when it may.
+ *
+ * The server decides: `GET /api/v1/admin/manifest` answers the map. Since 2026-10-06
+ * (Dmitry: "no host groups"; access is decided by module groups alone) it answers every
+ * signed-in account: the map grants nothing, each call it names is decided by its own
+ * route, and an account in no group sees the admin with an empty menu. A server from
+ * before that answers only at `/api/v1/console/manifest`, to the `console` group, and
+ * 403 to anyone else -- there a refused sign-in is still signed out; this asks the new
+ * address first and the old one only on its 404. The public theme config
+ * read before sign-in carries only what the sign-in page needs; the rest arrives
+ * here, once per sign-in, and is merged into the app config key by key: a key the
+ * console's map carries replaces the public one whole, so the console's copy of a
+ * section is always the complete one.
+ *
+ * `unknown` is a failure to ask (the network, a 5xx), not an answer: it is not kept,
+ * so while the endpoint fails every navigation asks again.
+ *
+ * !! An answer belongs to the sign-in it was asked for. A sign-in, a sign-out or a
+ * restored session starts a new generation; an answer that arrives for a generation
+ * that is gone is kept for nobody -- A's late 403 must not sign B out -- and whoever
+ * is waiting on it is answered for the sign-in there is now.
+ *
+ * !! With nobody signed in there is nothing to ask, and nothing is asked. Without
+ * that, the re-ask after a sign-out went out with no token, its 401 made the
+ * interceptor dispatch Logout, which started another generation, which re-asked:
+ * a loop for as long as the tab lived (found in review).
+ */
+export declare class ConsoleAccessService {
+  /** The admin manifest's URL: fixed, like the theme config's, because nothing is known before it. */
+  static readonly URL = "/api/v1/admin/manifest";
+  /** The address before 2026-10-06, asked only when a server older than that answers 404 at {@link URL}. */
+  static readonly LEGACY_URL = "/api/v1/console/manifest";
+  /** The login page's query parameter value for "signed out: no console access". */
+  static readonly REFUSED_REASON = "no-console-access";
+  private readonly http;
+  private readonly store;
+  private answer;
+  private pending;
+  private generation;
+  constructor();
+  /** Ask once per sign-in; the manifest is merged into the app config when granted. */
+  ensure(): Promise<ConsoleAccess>;
+  /**
+   * Sign a refused account out: this sign-in ends on the server (its refresh token
+   * with it), as the account menu's sign-out does, and then in this browser --
+   * whatever the server answered, so a refused request cannot leave it signed in.
+   */
+  signOut(): Observable<void>;
+  private merge;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ConsoleAccessService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
 /**
  * Layout config DTO -- the shape served from
  * `GET /api/v1/config/layout/{id}`. Mirrors the YAML at
@@ -1230,7 +1392,8 @@ export interface DatagridConfig {
  * Fetches config YAMLs (served as JSON) from GET /api/v1/config/{type}/{id}.
  *
  * Responses are cached for the lifetime of the service (Map + shareReplay(1))
- * so repeated calls never re-fetch the same resource.
+ * so repeated calls never re-fetch the same resource. A failed read is dropped
+ * from the cache, so the next call asks the server again.
  *
  * configBase is read from the API manifest (manifest.configBase) and falls
  * back to '/api/v1/config' when the manifest is not yet loaded.
@@ -1259,6 +1422,8 @@ export interface AppConfigStateModel {
 }
 export declare class AppConfigState {
   set(ctx: StateContext<AppConfigStateModel>, { config }: SetAppConfig): void;
+  /** The whole config as last set: the public theme config, with the console's manifest once granted. */
+  static config(state: AppConfigStateModel): ThemeConfigResponse | null;
   static manifest(state: AppConfigStateModel): ApiManifest | null;
   /**
    * The viewer manifest. Null when the backend didn't ship a viewers
@@ -1658,6 +1823,14 @@ export interface NaviGraphMeta {
   readonly contributor?: string;
   readonly [key: string]: unknown;
 }
+/**
+ * What the server says this account may do with a node, as it answered the graph:
+ *   'allowed' -- its own rights open it; shown as usual;
+ *   'elevate' -- a member of admin, not elevated, whose own rights refuse it and whom elevation would let in;
+ *                shown with a lock, and opening it asks for elevation first.
+ * A node anyone else may not open is not in the answer at all. Absent (an older server) reads as 'allowed'.
+ */
+export type NaviAccess = 'allowed' | 'elevate';
 /** Flat node as returned from GET /navi/trees/{slug}/graph */
 export interface NaviGraphNodeFlat {
   readonly id: string;
@@ -1668,7 +1841,10 @@ export interface NaviGraphNodeFlat {
   readonly isActive: boolean;
   readonly isVisible: boolean;
   readonly meta: NaviGraphMeta;
+  readonly access?: NaviAccess;
 }
+/** The node's access as the server answered it; 'allowed' when the server said nothing (an older server). */
+export declare function naviAccessOf(node: Pick<NaviGraphNodeFlat, 'access'>): NaviAccess;
 /** Same node enriched with resolved children after client-side tree build */
 export interface NaviGraphNode extends NaviGraphNodeFlat {
   readonly children: NaviGraphNode[];
@@ -1691,7 +1867,14 @@ export declare class NaviGraphService {
   /** Resolved root nodes for navi.admin.topbar. */
   readonly topbarNav: import("@angular/core").WritableSignal<NaviGraphNode[]>;
   private readonly cache;
-  loadAdminNav(url: string): Observable<NaviGraphNode[]>;
+  /**
+   * `fresh` asks the server again instead of answering from this service's cache: the answer is per account AND
+   * per elevation state (a node is 'elevate' before a grant and 'allowed' after it), so a change of elevation must
+   * re-ask, or a lock would outlive the grant -- or come back only after a reload.
+   */
+  loadAdminNav(url: string, options?: {
+    fresh?: boolean;
+  }): Observable<NaviGraphNode[]>;
   loadTopbarNav(url: string): Observable<NaviGraphNode[]>;
   /**
    * Handle a nav-node click.
@@ -1724,7 +1907,7 @@ export declare class NaviGraphService {
    * the legacy Hydra key (`hydra:member`).
    * Results are cached by URL for the lifetime of the service instance.
    */
-  loadTree(url: string): Observable<NaviGraphNode[]>;
+  loadTree(url: string, fresh?: boolean): Observable<NaviGraphNode[]>;
   /**
    * Build a nested tree from a flat array of nodes.
    * Nodes are sorted by sortOrder at each level.
@@ -1936,6 +2119,14 @@ export declare class ConsoleActivation {
  * landed on the dashboard (measured 2026-09-22: no chunk requested for the
  * mount, the dashboard's instead). `ready$` is what the auth guard waits on
  * too, and it fires whether or not the config fetch succeeded.
+ *
+ * !! Then the console's own manifest, when someone is signed in: `ui.modules` is
+ * the console's, not the public config's, and arrives with it
+ * ({@link ConsoleAccessService}). canMatch runs before the layout's auth guard,
+ * which asks the same question, so answering from the public config alone said
+ * "no" to every module once that config stopped carrying them. Nobody signed in:
+ * nothing is asked, the answer is the public config's, and the layout's guard
+ * sends the person to sign in. A refusal merges nothing, so the answer is no.
  */
 export declare function consoleModuleInstalled(module: string): CanMatchFn;
 /**