@saasicat/ui-vue 0.2.0

package/src/manifest-loader.ts

@@ -0,0 +1,139 @@
+// ManifestLoader — fetches the admin manifest endpoint with an ETag cache.
+//
+// **The endpoint is mandatory** and is supplied by the app consumer, because
+// apps have different `globalPrefix` conventions (e.g. `api`
+// or `api/v1`).
+//
+// Cache behavior:
+//   - First call: GET without If-None-Match → read body + ETag header,
+//     persist both in `KvStore` (key suffix `manifest:body` and
+//     `manifest:etag`).
+//   - Subsequent call: GET with `If-None-Match: <etag>` → on 304 the
+//     cached body is returned, no re-parse needed. On 200 the
+//     cache is overwritten.
+//
+// Spec: admin-api.openapi.yaml `GET /admin/manifest`.
+
+import type { AdminManifest } from '@saasicat/types';
+import { defaultHttpClient, defaultKvStore, type HttpClient, type KvStore } from './types.js';
+
+export interface ManifestLoaderOptions {
+    /**
+     * Fully-qualified manifest endpoint incl. app globalPrefix
+     * (`/api/admin/manifest`, `/api/v1/admin/manifest`, …). Mandatory.
+     */
+    endpoint: string;
+    http?: HttpClient;
+    storage?: KvStore;
+    /**
+     * Storage key prefix — consumers with multiple apps under one domain
+     * set this to e.g. `'ma:'` or `'da:'`, so that the caches
+     * are separated.
+     */
+    storageKeyPrefix?: string;
+    /**
+     * Auth header for `Authorization: Bearer <token>`. Sent with every
+     * request. The consumer supplies a function that pulls the
+     * current token from the auth store.
+     */
+    getAuthToken?: () => string | null;
+}
+
+export class ManifestLoadError extends Error {
+    constructor(
+        public readonly status: number,
+        message: string,
+    ) {
+        super(message);
+        this.name = 'ManifestLoadError';
+    }
+}
+
+export interface CachedManifestEntry {
+    etag: string;
+    body: AdminManifest;
+}
+
+export class ManifestLoader {
+    private readonly endpoint: string;
+    private readonly http: HttpClient;
+    private readonly storage: KvStore;
+    private readonly bodyKey: string;
+    private readonly etagKey: string;
+    private readonly getAuthToken?: () => string | null;
+
+    constructor(options: ManifestLoaderOptions) {
+        if (!options?.endpoint) {
+            throw new Error(
+                'ManifestLoader: `endpoint` ist Pflicht (z. B. "/api/admin/manifest" ' +
+                    'oder "/api/v1/admin/manifest"). Plattform hat keinen Default, ' +
+                    'weil Apps unterschiedliche globalPrefix-Konventionen haben.',
+            );
+        }
+        this.endpoint = options.endpoint;
+        this.http = options.http ?? defaultHttpClient();
+        this.storage = options.storage ?? defaultKvStore();
+        const prefix = options.storageKeyPrefix ?? '';
+        this.bodyKey = `${prefix}manifest:body`;
+        this.etagKey = `${prefix}manifest:etag`;
+        this.getAuthToken = options.getAuthToken;
+    }
+
+    /**
+     * Loads the current manifest. On a cache hit (304) the cached
+     * body is returned — otherwise the fresh server body.
+     */
+    async load(): Promise<AdminManifest> {
+        const cachedEtag = this.storage.get(this.etagKey);
+        const headers: Record<string, string> = {};
+        const token = this.getAuthToken?.();
+        if (token) headers.Authorization = `Bearer ${token}`;
+        if (cachedEtag) headers['If-None-Match'] = cachedEtag;
+
+        const res = await this.http(this.endpoint, { method: 'GET', headers });
+
+        if (res.status === 304) {
+            const cachedBody = this.readCachedBody();
+            if (!cachedBody) {
+                throw new ManifestLoadError(
+                    304,
+                    'Server lieferte 304, aber Cache-Body fehlt — bitte clearCache() + reload',
+                );
+            }
+            return cachedBody.body;
+        }
+
+        if (res.status !== 200) {
+            throw new ManifestLoadError(
+                res.status,
+                `Manifest-Endpunkt antwortete HTTP ${res.status}`,
+            );
+        }
+
+        const body = (await res.json()) as AdminManifest;
+        const etag = res.headers.get('ETag') ?? res.headers.get('etag');
+        if (etag) {
+            this.storage.set(this.etagKey, etag);
+            this.storage.set(this.bodyKey, JSON.stringify(body));
+        }
+        return body;
+    }
+
+    /** Reads the cached manifest body from storage; null if absent. */
+    readCachedBody(): CachedManifestEntry | null {
+        const etag = this.storage.get(this.etagKey);
+        const bodyStr = this.storage.get(this.bodyKey);
+        if (!etag || !bodyStr) return null;
+        try {
+            return { etag, body: JSON.parse(bodyStr) as AdminManifest };
+        } catch {
+            return null;
+        }
+    }
+
+    /** Clears the cache — e.g. on logout or after `manifest reload`. */
+    clearCache(): void {
+        this.storage.remove(this.etagKey);
+        this.storage.remove(this.bodyKey);
+    }
+}

package/src/manifest-store-factory.ts

@@ -0,0 +1,114 @@
+// createManifestStore — Pinia store factory that standardizes the
+// `loaded`/`inflight`/`ensureLoaded()`/`reload()`/`clearCache()` boilerplate.
+//
+// Apps define their manifest store from this factory:
+//
+//     import { createManifestStore } from '@saasicat/ui-vue';
+//     import { manifestLoader } from '@/services/platform-loaders';
+//     export const useManifestStore = createManifestStore({ loader: manifestLoader });
+//
+// This keeps the cache/inflight logic in a single place, and apps no
+// longer duplicate identical Pinia setups.
+
+import { defineStore, type StoreDefinition } from 'pinia';
+import { ref, type Ref } from 'vue';
+import type { AdminManifest } from '@saasicat/types';
+import type { ManifestLoader } from './manifest-loader.js';
+
+export interface ManifestStoreState {
+    manifest: Ref<AdminManifest | null>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    loaded: Ref<boolean>;
+}
+
+export interface ManifestStoreActions {
+    /**
+     * Loads once per session. Concurrent calls share the promise.
+     *
+     * **Behavior on loader error:** the store caches the error in
+     * `error.value` and resets `loaded = false`/`manifest = null`, and the
+     * promise REJECTS with the original error. Callers must either
+     * call `.catch(...)` (defensive behavior) or let the rejection
+     * propagate. The platform router guard
+     * (`createSuperAdminApp({ manifestGuard.errorRoute })`) provides a
+     * fail-closed path with a redirect to a dedicated error route.
+     */
+    ensureLoaded: () => Promise<void>;
+    /** Discards cache + state (logout path). */
+    clearCache: () => void;
+    /** Forces a server refresh (e.g. after `manifest reload`). */
+    reload: () => Promise<void>;
+}
+
+export interface CreateManifestStoreOptions {
+    /** Platform `ManifestLoader` instance (typically via `createPlatformLoaders()`). */
+    loader: ManifestLoader;
+    /** Pinia store ID. Default `admin-manifest`. */
+    id?: string;
+}
+
+export type ManifestStoreDefinition = StoreDefinition<
+    string,
+    ManifestStoreState,
+    Record<string, never>,
+    ManifestStoreActions
+>;
+
+/**
+ * Returns a `useStore` function for the manifest store. Apps call the
+ * factory once at module top level and export the result as
+ * `useManifestStore`.
+ */
+export function createManifestStore(options: CreateManifestStoreOptions): ManifestStoreDefinition {
+    return defineStore(options.id ?? 'admin-manifest', () => {
+        const manifest = ref<AdminManifest | null>(null);
+        const loading = ref(false);
+        const error = ref<Error | null>(null);
+        const loaded = ref(false);
+        let inflight: Promise<void> | null = null;
+
+        async function load(): Promise<void> {
+            loading.value = true;
+            error.value = null;
+            try {
+                manifest.value = await options.loader.load();
+                loaded.value = true;
+            } catch (err) {
+                const wrapped = err instanceof Error ? err : new Error(String(err));
+                error.value = wrapped;
+                manifest.value = null;
+                loaded.value = false;
+                // Re-throw so callers (router guard, page setups) see the
+                // error and can decide (fallback route, notification,
+                // etc.). The state (`error.value`) is retained and can be
+                // displayed reactively by components.
+                throw wrapped;
+            } finally {
+                loading.value = false;
+                inflight = null;
+            }
+        }
+
+        function ensureLoaded(): Promise<void> {
+            if (loaded.value) return Promise.resolve();
+            if (inflight) return inflight;
+            inflight = load();
+            return inflight;
+        }
+
+        function clearCache(): void {
+            options.loader.clearCache();
+            manifest.value = null;
+            loaded.value = false;
+            inflight = null;
+        }
+
+        async function reload(): Promise<void> {
+            clearCache();
+            await ensureLoaded();
+        }
+
+        return { manifest, loading, error, loaded, ensureLoaded, clearCache, reload };
+    }) as ManifestStoreDefinition;
+}

package/src/nav-builder.ts

@@ -0,0 +1,274 @@
+// NavBuilder — derives the sidebar structure and the router mount points from
+// a loaded `AdminManifest`. Platform standard pages have known
+// routes (`/admin/tenants`, `/admin/subscriptions`, …); consumer
+// `projectPages` are resolved to Vue components via the static
+// `extensions:` map.
+//
+// Capability filter: sidebar items are only delivered when the
+// respective `requiredCapability` in the manifest is set to `true` (or is
+// not required at all). The manifest is Discovery, not security — the server
+// enforces the routes independently.
+
+import type {
+    AdminManifest,
+    StandardPageDef,
+    StandardPageKey,
+} from '@saasicat/types';
+
+/**
+ * Default routes for the platform standard pages. Consumers may override this
+ * via the `standardPageRoutes` option (e.g. `/admin/users` →
+ * `/admin/team`).
+ */
+export const DEFAULT_STANDARD_PAGE_ROUTES: Record<StandardPageKey, string> = {
+    dashboard: '/admin/dashboard',
+    tenants: '/admin/tenants',
+    subscriptions: '/admin/subscriptions',
+    promoCodes: '/admin/promo-codes',
+    plans: '/admin/plans',
+    planVersions: '/admin/plan-versions',
+    audit: '/admin/audit',
+    users: '/admin/users',
+    pilots: '/admin/pilots',
+    discovery: '/admin/discovery',
+    bundles: '/admin/bundles',
+    businessTypes: '/admin/business-types',
+    marketingCatalog: '/admin/marketing-catalog',
+    platformEmail: '/admin/platform-email',
+    platformEmailHistory: '/admin/platform-email-history',
+};
+
+export interface BuildRouteEntry {
+    /** Stable identifier — the key for standard pages, the `id` for project pages. */
+    id: string;
+    /** Route path (`/admin/...`). */
+    path: string;
+    /** Visible for the UI. */
+    label: string;
+    icon?: string;
+    /** Sort key for drawer groups. */
+    navSection?: string;
+    /** Lookup key in the `extensions:` map (project) or the platform standard map. */
+    componentKey: string;
+    /** Required capability or null. */
+    requiredCapability: string | null;
+    /** Platform standard page (`true`) or project page (`false`). */
+    isStandard: boolean;
+    /** Hint for anticipatory lazy loading. */
+    prefetchOnIdle?: boolean;
+}
+
+export interface NavBuilderOptions {
+    /**
+     * Optional: overrides the default routes for certain standard pages.
+     * Consumers set this if they want an alternative URL structure.
+     */
+    standardPageRoutes?: Partial<Record<StandardPageKey, string>>;
+    /**
+     * Default labels for standard pages — consumers may localize.
+     */
+    standardPageLabels?: Partial<Record<StandardPageKey, string>>;
+    /** Default icons for standard pages. */
+    standardPageIcons?: Partial<Record<StandardPageKey, string>>;
+    /** Default `navSection` for standard pages. */
+    standardPageNavSection?: Partial<Record<StandardPageKey, string>>;
+    /**
+     * Optional: set of known `componentKey`s from the shell's `extensions:`
+     * map. ProjectPages whose `componentKey` is not contained here
+     * are filtered out — they would otherwise appear in the sidebar but on
+     * click be redirected by the catch-all (silent dead link).
+     * Consumers without an `extensions:` map omit the field → as before.
+     */
+    availableExtensions?: Set<string>;
+}
+
+const DEFAULT_LABELS: Record<StandardPageKey, string> = {
+    dashboard: 'Dashboard',
+    tenants: 'Mandanten',
+    subscriptions: 'Abonnements',
+    promoCodes: 'Promo-Codes',
+    plans: 'Pläne & Versionen',
+    planVersions: 'Plan-Versionen',
+    audit: 'Audit-Log',
+    users: 'Benutzer',
+    pilots: 'Piloten',
+    discovery: 'Discovery',
+    bundles: 'Bundles',
+    businessTypes: 'Geschäftstypen',
+    marketingCatalog: 'Marketing-Catalog',
+    platformEmail: 'Plattform-E-Mail',
+    platformEmailHistory: 'E-Mail-Verlauf',
+};
+
+const DEFAULT_ICONS: Record<StandardPageKey, string> = {
+    dashboard: 'dashboard',
+    tenants: 'business',
+    subscriptions: 'card_membership',
+    promoCodes: 'local_activity',
+    plans: 'workspace_premium',
+    planVersions: 'history_edu',
+    audit: 'history',
+    users: 'people',
+    pilots: 'flight_takeoff',
+    discovery: 'travel_explore',
+    bundles: 'inventory_2',
+    businessTypes: 'category',
+    marketingCatalog: 'campaign',
+    platformEmail: 'mail',
+    platformEmailHistory: 'mark_email_read',
+};
+
+const DEFAULT_NAV_SECTIONS: Partial<Record<StandardPageKey, string>> = {
+    dashboard: 'Übersicht',
+    discovery: 'Produktkatalog',
+    businessTypes: 'Produktkatalog',
+    bundles: 'Produktkatalog',
+    plans: 'Produktkatalog',
+    planVersions: 'Produktkatalog',
+    marketingCatalog: 'Produktkatalog',
+    promoCodes: 'Produktkatalog',
+    tenants: 'Kunden',
+    subscriptions: 'Kunden',
+    users: 'Kunden',
+    pilots: 'Kunden',
+    audit: 'System',
+    platformEmail: 'System',
+    platformEmailHistory: 'System',
+};
+
+export const DEFAULT_SECTION_ORDER: readonly string[] = [
+    'Übersicht',
+    'Produktkatalog',
+    'Kunden',
+    'System',
+];
+
+/**
+ * Returns the list of all routes defined by the current manifest —
+ * filtered to the capabilities that the logged-in user has.
+ *
+ * The consumer shell then builds its Vue router configuration and its
+ * sidebar drawer from it.
+ */
+export function buildRoutes(
+    manifest: AdminManifest,
+    options: NavBuilderOptions = {},
+): BuildRouteEntry[] {
+    const routes: BuildRouteEntry[] = [];
+    const capabilities = manifest.capabilities ?? {};
+
+    // StandardPages
+    const standard = manifest.navigation?.standardPages ?? {};
+    const overrideRoutes = { ...DEFAULT_STANDARD_PAGE_ROUTES, ...options.standardPageRoutes };
+    const overrideLabels = { ...DEFAULT_LABELS, ...options.standardPageLabels };
+    const overrideIcons = { ...DEFAULT_ICONS, ...options.standardPageIcons };
+    const overrideNavSection = { ...DEFAULT_NAV_SECTIONS, ...options.standardPageNavSection };
+
+    for (const key of Object.keys(standard) as StandardPageKey[]) {
+        const def = standard[key] as StandardPageDef | undefined;
+        if (!def?.enabled) continue;
+        const cap = def.requiredCapability ?? null;
+        if (cap && capabilities[cap] !== true) continue;
+        routes.push({
+            id: key,
+            path: overrideRoutes[key],
+            label: overrideLabels[key],
+            icon: overrideIcons[key],
+            navSection: overrideNavSection[key],
+            componentKey: `platform-${key}`,
+            requiredCapability: cap,
+            isStandard: true,
+        });
+    }
+
+    // ProjectPages
+    const projectPages = manifest.navigation?.projectPages ?? [];
+    const exts = options.availableExtensions;
+    for (const p of projectPages) {
+        const cap = p.requiredCapability ?? null;
+        if (cap && capabilities[cap] !== true) continue;
+        if (exts && !exts.has(p.componentKey)) continue;
+        routes.push({
+            id: p.id,
+            path: p.route,
+            label: p.label,
+            icon: p.icon,
+            navSection: p.navSection,
+            componentKey: p.componentKey,
+            requiredCapability: cap,
+            isStandard: false,
+            prefetchOnIdle: p.prefetchOnIdle,
+        });
+    }
+
+    return routes;
+}
+
+export interface SidebarItem {
+    id: string;
+    path: string;
+    label: string;
+    icon?: string;
+}
+
+export interface SidebarSection {
+    /** `null` for the default section (items without `navSection`). */
+    section: string | null;
+    items: SidebarItem[];
+}
+
+/**
+ * Groups the routes by `navSection` for the drawer.
+ *
+ * Section order:
+ *   1. Default section (`null`) — items without `navSection`.
+ *   2. Sections from `sectionOrder` in exactly this order.
+ *   3. Remaining sections alphabetically.
+ *
+ * The default order matches the plan simulation layout (Übersicht →
+ * Produktkatalog → Kunden → System); consumers can override it.
+ */
+export function buildSidebar(
+    routes: BuildRouteEntry[],
+    sectionOrder: readonly string[] = DEFAULT_SECTION_ORDER,
+): SidebarSection[] {
+    const bySection = new Map<string | null, SidebarItem[]>();
+    for (const r of routes) {
+        const section = r.navSection ?? null;
+        const list = bySection.get(section) ?? [];
+        list.push({ id: r.id, path: r.path, label: r.label, icon: r.icon });
+        bySection.set(section, list);
+    }
+    const sections: SidebarSection[] = [];
+    if (bySection.has(null)) {
+        sections.push({ section: null, items: bySection.get(null)! });
+    }
+    const ordered = new Set<string>();
+    for (const name of sectionOrder) {
+        if (bySection.has(name)) {
+            sections.push({ section: name, items: bySection.get(name)! });
+            ordered.add(name);
+        }
+    }
+    const remaining = [...bySection.entries()]
+        .filter(([s]) => s !== null && !ordered.has(s as string))
+        .sort((a, b) => (a[0] as string).localeCompare(b[0] as string));
+    for (const [section, items] of remaining) {
+        sections.push({ section: section as string, items });
+    }
+    return sections;
+}
+
+/**
+ * Returns the Vue component registered for the given `componentKey`.
+ * The consumer shell calls this function with its own `extensions:` map.
+ * For unknown keys → `null` (the UI then renders a fallback
+ * component, e.g. "Component not found in shell build").
+ *
+ * `extensions` is `Record<string, T>` — `T` is typically a
+ * Vue component (either imported directly or as a
+ * `defineAsyncComponent` wrapper).
+ */
+export function resolveExtension<T>(componentKey: string, extensions: Record<string, T>): T | null {
+    return extensions[componentKey] ?? null;
+}