@saasicat/ui-vue 0.2.0

package/src/use-catalog-entries.ts

@@ -0,0 +1,243 @@
+// useCatalogEntries — Vue 3 composable for the Discovery review
+// (Backend: CatalogEntriesController under /admin/catalog/{capabilities,
+// features,quotas} + /admin/catalog/discovery/sync).
+//
+// Discovery (`/admin/discovery`) is the code's actual state; this composable
+// reads/writes the persisted review status + the translations.
+//
+// **Admin endpoint prefix is required** and is supplied by the consumer
+// (e.g. `/api/admin` or `/api/v1/admin`).
+
+import { ref, type Ref } from 'vue';
+import type {
+    CapabilityCatalogEntryRow,
+    CatalogEntryI18n,
+    DiscoverySnapshot,
+    FeatureCatalogEntryRow,
+    QuotaCatalogEntryRow,
+    ReviewCatalogEntryData,
+    SyncDiscoveryResult,
+    UpdateCatalogEntryBaseData,
+} from '@saasicat/types';
+import { defaultHttpClient, type HttpClient } from './types.js';
+
+export interface UseCatalogEntriesOptions {
+    /** Admin endpoint prefix incl. globalPrefix (`/api/admin`, `/api/v1/admin`). */
+    adminEndpoint: string;
+    http?: HttpClient;
+    getAuthToken?: () => string | null;
+    /** projectKey the catalog entries are filtered against. */
+    projectKey: string;
+    autoLoad?: boolean;
+}
+
+export class CatalogEntriesApiError extends Error {
+    constructor(
+        public readonly status: number,
+        public readonly body: unknown,
+        message: string,
+    ) {
+        super(message);
+        this.name = 'CatalogEntriesApiError';
+    }
+}
+
+export interface UseCatalogEntriesResult {
+    capabilities: Ref<CapabilityCatalogEntryRow[]>;
+    features: Ref<FeatureCatalogEntryRow[]>;
+    quotas: Ref<QuotaCatalogEntryRow[]>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+
+    load: () => Promise<void>;
+    /** Approval transition of a feature (#20): PATCH …/features/:key/review. */
+    reviewFeature: (
+        featureKey: string,
+        data: ReviewCatalogEntryData,
+    ) => Promise<FeatureCatalogEntryRow>;
+    /** Approval transition of a quota (#20): PATCH …/quotas/:key/review. */
+    reviewQuota: (quotaKey: string, data: ReviewCatalogEntryData) => Promise<QuotaCatalogEntryRow>;
+    setFeatureI18n: (featureKey: string, i18n: CatalogEntryI18n) => Promise<FeatureCatalogEntryRow>;
+    setQuotaI18n: (quotaKey: string, i18n: CatalogEntryI18n) => Promise<QuotaCatalogEntryRow>;
+    /** Sets the editable default-locale label/description of a feature. */
+    setFeatureBase: (
+        featureKey: string,
+        data: UpdateCatalogEntryBaseData,
+    ) => Promise<FeatureCatalogEntryRow>;
+    /** Sets the editable default-locale label/description of a quota. */
+    setQuotaBase: (
+        quotaKey: string,
+        data: UpdateCatalogEntryBaseData,
+    ) => Promise<QuotaCatalogEntryRow>;
+    /** Upserts the catalog entries from a discovery snapshot and reloads. */
+    syncDiscovery: (snapshot: DiscoverySnapshot) => Promise<SyncDiscoveryResult>;
+}
+
+export function useCatalogEntries(options: UseCatalogEntriesOptions): UseCatalogEntriesResult {
+    if (!options?.adminEndpoint) {
+        throw new Error('useCatalogEntries: `adminEndpoint` ist Pflicht.');
+    }
+    if (!options?.projectKey) {
+        throw new Error('useCatalogEntries: `projectKey` ist Pflicht.');
+    }
+
+    const http = options.http ?? defaultHttpClient();
+    const capabilities = ref<CapabilityCatalogEntryRow[]>([]);
+    const features = ref<FeatureCatalogEntryRow[]>([]);
+    const quotas = ref<QuotaCatalogEntryRow[]>([]);
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    const base = `${options.adminEndpoint}/catalog`;
+    const pk = encodeURIComponent(options.projectKey);
+
+    function authHeaders(): Record<string, string> {
+        const token = options.getAuthToken?.();
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    }
+
+    async function fetchJson<T>(url: string, init?: Parameters<HttpClient>[1]): Promise<T | null> {
+        const res = await http(url, {
+            method: init?.method ?? 'GET',
+            headers: { 'content-type': 'application/json', ...authHeaders(), ...init?.headers },
+            body: init?.body,
+        });
+        if (res.status === 204) return null;
+        const body = await res.json().catch(() => null);
+        if (res.status >= 400) {
+            throw new CatalogEntriesApiError(
+                res.status,
+                body,
+                `Catalog-Entries-API antwortete mit HTTP ${res.status}`,
+            );
+        }
+        return body as T;
+    }
+
+    async function load(): Promise<void> {
+        loading.value = true;
+        error.value = null;
+        try {
+            const [caps, feats, qs] = await Promise.all([
+                fetchJson<CapabilityCatalogEntryRow[]>(`${base}/capabilities?projectKey=${pk}`),
+                fetchJson<FeatureCatalogEntryRow[]>(`${base}/features?projectKey=${pk}`),
+                fetchJson<QuotaCatalogEntryRow[]>(`${base}/quotas?projectKey=${pk}`),
+            ]);
+            capabilities.value = caps ?? [];
+            features.value = feats ?? [];
+            quotas.value = qs ?? [];
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function reviewFeature(
+        featureKey: string,
+        data: ReviewCatalogEntryData,
+    ): Promise<FeatureCatalogEntryRow> {
+        const updated = await fetchJson<FeatureCatalogEntryRow>(
+            `${base}/features/${encodeURIComponent(featureKey)}/review?projectKey=${pk}`,
+            { method: 'PATCH', body: JSON.stringify(data) },
+        );
+        if (!updated) throw new CatalogEntriesApiError(0, null, 'Review gab keinen Body zurück');
+        features.value = features.value.map((f) => (f.featureKey === featureKey ? updated : f));
+        return updated;
+    }
+
+    async function reviewQuota(
+        quotaKey: string,
+        data: ReviewCatalogEntryData,
+    ): Promise<QuotaCatalogEntryRow> {
+        const updated = await fetchJson<QuotaCatalogEntryRow>(
+            `${base}/quotas/${encodeURIComponent(quotaKey)}/review?projectKey=${pk}`,
+            { method: 'PATCH', body: JSON.stringify(data) },
+        );
+        if (!updated) throw new CatalogEntriesApiError(0, null, 'Review gab keinen Body zurück');
+        quotas.value = quotas.value.map((q) => (q.quotaKey === quotaKey ? updated : q));
+        return updated;
+    }
+
+    async function setFeatureI18n(
+        featureKey: string,
+        i18n: CatalogEntryI18n,
+    ): Promise<FeatureCatalogEntryRow> {
+        const updated = await fetchJson<FeatureCatalogEntryRow>(
+            `${base}/features/${encodeURIComponent(featureKey)}/i18n?projectKey=${pk}`,
+            { method: 'PATCH', body: JSON.stringify({ i18n }) },
+        );
+        if (!updated) throw new CatalogEntriesApiError(0, null, 'i18n gab keinen Body zurück');
+        features.value = features.value.map((f) => (f.featureKey === featureKey ? updated : f));
+        return updated;
+    }
+
+    async function setQuotaI18n(
+        quotaKey: string,
+        i18n: CatalogEntryI18n,
+    ): Promise<QuotaCatalogEntryRow> {
+        const updated = await fetchJson<QuotaCatalogEntryRow>(
+            `${base}/quotas/${encodeURIComponent(quotaKey)}/i18n?projectKey=${pk}`,
+            { method: 'PATCH', body: JSON.stringify({ i18n }) },
+        );
+        if (!updated) throw new CatalogEntriesApiError(0, null, 'i18n gab keinen Body zurück');
+        quotas.value = quotas.value.map((q) => (q.quotaKey === quotaKey ? updated : q));
+        return updated;
+    }
+
+    async function setFeatureBase(
+        featureKey: string,
+        data: UpdateCatalogEntryBaseData,
+    ): Promise<FeatureCatalogEntryRow> {
+        const updated = await fetchJson<FeatureCatalogEntryRow>(
+            `${base}/features/${encodeURIComponent(featureKey)}?projectKey=${pk}`,
+            { method: 'PATCH', body: JSON.stringify(data) },
+        );
+        if (!updated) throw new CatalogEntriesApiError(0, null, 'Base gab keinen Body zurück');
+        features.value = features.value.map((f) => (f.featureKey === featureKey ? updated : f));
+        return updated;
+    }
+
+    async function setQuotaBase(
+        quotaKey: string,
+        data: UpdateCatalogEntryBaseData,
+    ): Promise<QuotaCatalogEntryRow> {
+        const updated = await fetchJson<QuotaCatalogEntryRow>(
+            `${base}/quotas/${encodeURIComponent(quotaKey)}?projectKey=${pk}`,
+            { method: 'PATCH', body: JSON.stringify(data) },
+        );
+        if (!updated) throw new CatalogEntriesApiError(0, null, 'Base gab keinen Body zurück');
+        quotas.value = quotas.value.map((q) => (q.quotaKey === quotaKey ? updated : q));
+        return updated;
+    }
+
+    async function syncDiscovery(snapshot: DiscoverySnapshot): Promise<SyncDiscoveryResult> {
+        const result = await fetchJson<SyncDiscoveryResult>(`${base}/discovery/sync`, {
+            method: 'POST',
+            body: JSON.stringify({ snapshot }),
+        });
+        if (!result) throw new CatalogEntriesApiError(0, null, 'Sync gab keinen Body zurück');
+        await load();
+        return result;
+    }
+
+    if (options.autoLoad) {
+        void load();
+    }
+
+    return {
+        capabilities,
+        features,
+        quotas,
+        loading,
+        error,
+        load,
+        reviewFeature,
+        reviewQuota,
+        setFeatureI18n,
+        setQuotaI18n,
+        setFeatureBase,
+        setQuotaBase,
+        syncDiscovery,
+    };
+}

package/src/use-discovery.ts

@@ -0,0 +1,158 @@
+// useDiscovery — Vue 3 composable over the discovery endpoint
+// (`GET /admin/discovery`).
+//
+// Returns the boot-time snapshot of the running backend — capabilities,
+// features, bundles and quotas that are annotated in code via
+// @ImplementsCapability, @DefinesQuota etc. ETag caching: on follow-up
+// requests `If-None-Match: <hash>` is sent along; on 304 the cached
+// snapshot stays in place, no re-parse needed.
+//
+// **The endpoint is mandatory** and is supplied by the consumer
+// (e.g. `/api/admin/discovery` or `/api/v1/admin/discovery`).
+
+import { ref, type Ref } from 'vue';
+import type { DiscoverySnapshot } from '@saasicat/types';
+import { defaultHttpClient, type HttpClient } from './types.js';
+
+export interface UseDiscoveryOptions {
+    /**
+     * Fully qualified discovery endpoint including the app globalPrefix
+     * (`/api/admin/discovery`, `/api/v1/admin/discovery`, …). Mandatory.
+     */
+    endpoint: string;
+    http?: HttpClient;
+    /**
+     * Auth header for `Authorization: Bearer <token>`. Sent along with every
+     * request. The consumer supplies a function that pulls the current token
+     * from the auth store.
+     */
+    getAuthToken?: () => string | null;
+    /**
+     * When `true`, loads automatically on composable init. Default
+     * `false` — the consumer triggers `load()` itself (e.g. after page mount).
+     */
+    autoLoad?: boolean;
+}
+
+export class DiscoveryLoadError extends Error {
+    constructor(
+        public readonly status: number,
+        message: string,
+    ) {
+        super(message);
+        this.name = 'DiscoveryLoadError';
+    }
+}
+
+export interface UseDiscoveryResult {
+    snapshot: Ref<DiscoverySnapshot | null>;
+    /** ETag header of the last 200 response, or null. */
+    etag: Ref<string | null>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    /**
+     * Loads fresh. On a cache hit (HTTP 304) `snapshot` stays unchanged,
+     * as does `etag`.
+     */
+    load: () => Promise<void>;
+    /**
+     * Discards the cache (etag = null) and loads without If-None-Match. Useful
+     * after code deploys, when a new snapshot is expected.
+     */
+    reload: () => Promise<void>;
+    /**
+     * `POST <endpoint>/rescan` — forces a fresh code scan in the backend
+     * (new `scannedAt`) and adopts the snapshot.
+     */
+    rescan: () => Promise<void>;
+}
+
+export function useDiscovery(options: UseDiscoveryOptions): UseDiscoveryResult {
+    if (!options?.endpoint) {
+        throw new Error(
+            'useDiscovery: `endpoint` ist Pflicht (z. B. "/api/admin/discovery" ' +
+                'oder "/api/v1/admin/discovery"). Plattform hat keinen Default, ' +
+                'weil Apps unterschiedliche globalPrefix-Konventionen haben.',
+        );
+    }
+
+    const http = options.http ?? defaultHttpClient();
+    const snapshot = ref<DiscoverySnapshot | null>(null);
+    const etag = ref<string | null>(null);
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    async function fetchSnapshot(includeEtag: boolean): Promise<void> {
+        loading.value = true;
+        error.value = null;
+        try {
+            const headers: Record<string, string> = {};
+            const token = options.getAuthToken?.();
+            if (token) headers.Authorization = `Bearer ${token}`;
+            if (includeEtag && etag.value) {
+                headers['If-None-Match'] = etag.value;
+            }
+
+            const res = await http(options.endpoint, { method: 'GET', headers });
+
+            if (res.status === 304) {
+                // Cache hit: snapshot stays unchanged, no re-parse.
+                return;
+            }
+            if (res.status !== 200) {
+                throw new DiscoveryLoadError(
+                    res.status,
+                    `Discovery-Endpoint antwortete mit HTTP ${res.status}`,
+                );
+            }
+
+            const body = (await res.json()) as DiscoverySnapshot;
+            snapshot.value = body;
+            etag.value = res.headers.get('ETag');
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function load(): Promise<void> {
+        await fetchSnapshot(true);
+    }
+
+    async function reload(): Promise<void> {
+        etag.value = null;
+        await fetchSnapshot(false);
+    }
+
+    async function rescan(): Promise<void> {
+        loading.value = true;
+        error.value = null;
+        try {
+            const headers: Record<string, string> = { 'content-type': 'application/json' };
+            const token = options.getAuthToken?.();
+            if (token) headers.Authorization = `Bearer ${token}`;
+
+            const res = await http(`${options.endpoint}/rescan`, { method: 'POST', headers });
+            if (res.status !== 200 && res.status !== 201) {
+                throw new DiscoveryLoadError(
+                    res.status,
+                    `Discovery-Rescan antwortete mit HTTP ${res.status}`,
+                );
+            }
+            const body = (await res.json()) as DiscoverySnapshot;
+            snapshot.value = body;
+            etag.value = res.headers.get('ETag');
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    if (options.autoLoad) {
+        void load();
+    }
+
+    return { snapshot, etag, loading, error, load, reload, rescan };
+}

package/src/use-entitlement.ts

@@ -0,0 +1,87 @@
+// useEntitlement — Vue composable over the tenant entitlement endpoint.
+//
+// **Endpoint is mandatory** and is supplied by the app consumer
+// (e.g. `/api/billing/entitlement` or `/api/v1/billing/entitlement`).
+//
+// Returns a tenant's effective limits as a reactive Ref. The consumer
+// backend exposes the endpoint via the platform `EntitlementService.computeLimits`
+// (see @saasicat/nest).
+//
+// Output is the `EffectiveLimitsSnapshot` shape from saas-platform-nest —
+// mapped here as a generic shape because the platform types package does not
+// expose the snapshot (it lives in saas-platform-nest/entitlement).
+
+import { ref, type Ref } from 'vue';
+import { defaultHttpClient, type HttpClient } from './types.js';
+
+export interface EntitlementSnapshotShape {
+    plan: string;
+    quotas: Record<string, number>;
+    features: string[];
+}
+
+export interface UseEntitlementOptions {
+    /**
+     * Fully-qualified entitlement endpoint including the app globalPrefix
+     * (`/api/billing/entitlement`, `/api/v1/billing/entitlement`, …). Mandatory.
+     */
+    endpoint: string;
+    http?: HttpClient;
+    getAuthToken?: () => string | null;
+    /** Default `true`. */
+    autoLoad?: boolean;
+}
+
+export interface UseEntitlementResult {
+    entitlement: Ref<EntitlementSnapshotShape | null>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    load: () => Promise<void>;
+    /** Convenience: checks whether a FeatureKey is in the set. */
+    hasFeature: (key: string) => boolean;
+}
+
+export function useEntitlement(options: UseEntitlementOptions): UseEntitlementResult {
+    if (!options?.endpoint) {
+        throw new Error(
+            'useEntitlement: `endpoint` ist Pflicht (z. B. "/api/billing/entitlement" ' +
+                'oder "/api/v1/billing/entitlement"). Plattform hat keinen Default, weil ' +
+                'Apps unterschiedliche globalPrefix-Konventionen haben.',
+        );
+    }
+    const endpoint = options.endpoint;
+    const http = options.http ?? defaultHttpClient();
+    const entitlement = ref<EntitlementSnapshotShape | null>(null);
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    async function load() {
+        loading.value = true;
+        error.value = null;
+        try {
+            const headers: Record<string, string> = {};
+            const token = options.getAuthToken?.();
+            if (token) headers.Authorization = `Bearer ${token}`;
+            const res = await http(endpoint, { method: 'GET', headers });
+            if (res.status !== 200) {
+                throw new Error(`Entitlement-Endpoint → HTTP ${res.status}`);
+            }
+            entitlement.value = (await res.json()) as EntitlementSnapshotShape;
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+            entitlement.value = null;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    function hasFeature(key: string): boolean {
+        return entitlement.value?.features.includes(key) ?? false;
+    }
+
+    if (options.autoLoad !== false) {
+        Promise.resolve().then(() => void load());
+    }
+
+    return { entitlement, loading, error, load, hasFeature };
+}

package/src/use-live-plan-versions.ts

@@ -0,0 +1,126 @@
+// useLivePlanVersions — loads, per plan stem, the currently "live" plan version
+// (publishedAt != null && supersededAt == null && latest by validFrom) and
+// builds a mapping `planKey → PlanVersionRow | null`. Consumed by the
+// BundlesPage (Plan↔Bundle overlap check in the compat picker).
+//
+// Implementation: 1 + N HTTP requests (plan list + versions/ per plan).
+// Acceptable for SuperAdmin setups with few plans (3-10); a backend
+// optimization via `GET /admin/catalog/plans?include=liveVersion`
+// can be added later, additively.
+
+import { ref, watch, type Ref } from 'vue';
+import type { PlanRow, PlanVersionRow } from '@saasicat/types';
+import { defaultHttpClient, type HttpClient } from './types.js';
+
+export interface UseLivePlanVersionsOptions {
+    adminEndpoint: string;
+    /** Reactive list of plan stems — the watcher reloads when the list changes. */
+    plans: Ref<PlanRow[]>;
+    http?: HttpClient;
+    getAuthToken?: () => string | null;
+}
+
+export interface UseLivePlanVersionsResult {
+    /** `planKey → live PlanVersion` (or null when the plan has no live version). */
+    livePlanVersions: Ref<Record<string, PlanVersionRow | null>>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    /** Forces a reload of all live versions. */
+    refresh: () => Promise<void>;
+}
+
+export function useLivePlanVersions(
+    options: UseLivePlanVersionsOptions,
+): UseLivePlanVersionsResult {
+    if (!options?.adminEndpoint) {
+        throw new Error('useLivePlanVersions: `adminEndpoint` ist Pflicht.');
+    }
+    if (!options?.plans) {
+        throw new Error('useLivePlanVersions: `plans` ist Pflicht.');
+    }
+
+    const http = options.http ?? defaultHttpClient();
+    const livePlanVersions = ref<Record<string, PlanVersionRow | null>>({});
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    function authHeaders(): Record<string, string> {
+        const token = options.getAuthToken?.();
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    }
+
+    async function loadForPlan(planId: string): Promise<PlanVersionRow | null> {
+        const res = await http(`${options.adminEndpoint}/catalog/plans/${planId}/versions`, {
+            method: 'GET',
+            headers: { 'content-type': 'application/json', ...authHeaders() },
+        });
+        if (res.status >= 400) {
+            throw new Error(`HTTP ${res.status} beim Laden der Versionen für Plan '${planId}'`);
+        }
+        const versions = (await res.json().catch(() => null)) as PlanVersionRow[] | null;
+        if (!versions || versions.length === 0) return null;
+        return findLatestLive(versions);
+    }
+
+    async function refresh(): Promise<void> {
+        loading.value = true;
+        error.value = null;
+        try {
+            const entries = await Promise.all(
+                options.plans.value.map(async (plan) => {
+                    try {
+                        const live = await loadForPlan(plan.id);
+                        return [plan.planKey, live] as const;
+                    } catch (err) {
+                        // Do not aggregate per-plan errors — the other plans
+                        // should keep working; just set the mapping entry to null.
+                        console.warn(
+                            `useLivePlanVersions: Plan '${plan.planKey}' Versions-Load failed`,
+                            err,
+                        );
+                        return [plan.planKey, null] as const;
+                    }
+                }),
+            );
+            livePlanVersions.value = Object.fromEntries(entries);
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    // Auto-refresh when the plan list changes (e.g. after creating a
+    // new plan). The first load happens on the first plan entry.
+    watch(
+        () => options.plans.value.map((p) => p.id).join(','),
+        () => {
+            if (options.plans.value.length > 0) void refresh();
+            else livePlanVersions.value = {};
+        },
+        { immediate: true },
+    );
+
+    return { livePlanVersions, loading, error, refresh };
+}
+
+/**
+ * Returns the currently "live" PlanVersion from a versions list:
+ *   - publishedAt != null
+ *   - supersededAt == null
+ *   - highest validFrom (= most recently activated)
+ *
+ * If no published version exists or all are superseded: null.
+ * Intentionally ignores validUntil — here the UI needs the "newest
+ * contract content" for overlap calculations, not the asOf-now check.
+ */
+function findLatestLive(versions: PlanVersionRow[]): PlanVersionRow | null {
+    const candidates = versions.filter((v) => v.publishedAt !== null && v.supersededAt === null);
+    if (candidates.length === 0) return null;
+    return [...candidates].sort((a, b) => {
+        const av = a.validFrom ?? '';
+        const bv = b.validFrom ?? '';
+        if (av === bv) return b.version - a.version;
+        return bv.localeCompare(av);
+    })[0];
+}

package/src/use-manifest.ts

@@ -0,0 +1,57 @@
+// useManifest — Vue 3 composable over ManifestLoader with ETag cache.
+//
+// Usage in the shell app after login:
+//
+//     const { manifest, loading, error, load, reload } = useManifest({
+//       getAuthToken: () => authStore.token,
+//     });
+//     await load();
+
+import { ref, type Ref } from 'vue';
+import type { AdminManifest } from '@saasicat/types';
+import { ManifestLoader, type ManifestLoaderOptions } from './manifest-loader.js';
+
+export interface UseManifestResult {
+    manifest: Ref<AdminManifest | null>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    /** Loads once (or returns the cache); does not abort on re-call. */
+    load: () => Promise<void>;
+    /** Discards the cache and loads fresh (e.g. after manifest/reload). */
+    reload: () => Promise<void>;
+    /** Clears the cache — e.g. on logout. */
+    clearCache: () => void;
+}
+
+export function useManifest(options: ManifestLoaderOptions): UseManifestResult {
+    const loader = new ManifestLoader(options);
+    const manifest = ref<AdminManifest | null>(null);
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    async function load() {
+        loading.value = true;
+        error.value = null;
+        try {
+            manifest.value = await loader.load();
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+            manifest.value = null;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function reload() {
+        loader.clearCache();
+        manifest.value = null;
+        await load();
+    }
+
+    function clearCache() {
+        loader.clearCache();
+        manifest.value = null;
+    }
+
+    return { manifest, loading, error, load, reload, clearCache };
+}