@saasicat/ui-vue 0.2.0

package/src/use-promotions.ts

@@ -0,0 +1,126 @@
+// usePromotions — Vue 3 composable for SuperAdmin promotions management
+// (backend: PromotionsController under /admin/catalog/promotions).
+//
+// **The admin endpoint prefix is mandatory** and is supplied by the consumer
+// (e.g. `/api/admin` or `/api/v1/admin`).
+
+import { ref, type Ref } from 'vue';
+import type {
+    CreatePromotionData,
+    PromotionRow,
+    UpdatePromotionData,
+} from '@saasicat/types';
+import { defaultHttpClient, type HttpClient } from './types.js';
+
+export interface UsePromotionsOptions {
+    adminEndpoint: string;
+    http?: HttpClient;
+    getAuthToken?: () => string | null;
+    projectKey: string;
+    autoLoad?: boolean;
+}
+
+export class PromotionsApiError extends Error {
+    constructor(
+        public readonly status: number,
+        public readonly body: unknown,
+        message: string,
+    ) {
+        super(message);
+        this.name = 'PromotionsApiError';
+    }
+}
+
+export interface UsePromotionsResult {
+    promotions: Ref<PromotionRow[]>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    load: () => Promise<void>;
+    create: (data: CreatePromotionData) => Promise<PromotionRow>;
+    update: (id: string, data: UpdatePromotionData) => Promise<PromotionRow>;
+    remove: (id: string) => Promise<void>;
+}
+
+export function usePromotions(options: UsePromotionsOptions): UsePromotionsResult {
+    if (!options?.adminEndpoint) {
+        throw new Error('usePromotions: `adminEndpoint` ist Pflicht.');
+    }
+    if (!options?.projectKey) {
+        throw new Error('usePromotions: `projectKey` ist Pflicht.');
+    }
+
+    const http = options.http ?? defaultHttpClient();
+    const promotions = ref<PromotionRow[]>([]);
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    const baseUrl = `${options.adminEndpoint}/catalog/promotions`;
+    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 PromotionsApiError(
+                res.status,
+                body,
+                `Promotions-API antwortete mit HTTP ${res.status}`,
+            );
+        }
+        return body as T;
+    }
+
+    async function load(): Promise<void> {
+        loading.value = true;
+        error.value = null;
+        try {
+            const data = await fetchJson<PromotionRow[]>(`${baseUrl}?projectKey=${pk}`);
+            promotions.value = data ?? [];
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function create(data: CreatePromotionData): Promise<PromotionRow> {
+        const created = await fetchJson<PromotionRow>(baseUrl, {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+        if (!created) throw new PromotionsApiError(0, null, 'Create gab keinen Body zurück');
+        promotions.value = [...promotions.value, created];
+        return created;
+    }
+
+    async function update(id: string, data: UpdatePromotionData): Promise<PromotionRow> {
+        const updated = await fetchJson<PromotionRow>(`${baseUrl}/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+        });
+        if (!updated) throw new PromotionsApiError(0, null, 'Update gab keinen Body zurück');
+        promotions.value = promotions.value.map((p) => (p.id === id ? updated : p));
+        return updated;
+    }
+
+    async function remove(id: string): Promise<void> {
+        await fetchJson<null>(`${baseUrl}/${id}`, { method: 'DELETE' });
+        promotions.value = promotions.value.filter((p) => p.id !== id);
+    }
+
+    if (options.autoLoad) {
+        void load();
+    }
+
+    return { promotions, loading, error, load, create, update, remove };
+}

package/src/use-public-boot.ts

@@ -0,0 +1,40 @@
+// usePublicBoot — Vue 3 composable over BootLoader.
+//
+// Usage in the login layout:
+//
+//     const { boot, loading, error, load } = usePublicBoot();
+//     await load();
+//     // boot.value now contains project.{key,displayName,logoUrl}.
+
+import { ref, type Ref } from 'vue';
+import type { PublicBootResponse } from '@saasicat/types';
+import { BootLoader, type BootLoaderOptions } from './boot-loader.js';
+
+export interface UsePublicBootResult {
+    boot: Ref<PublicBootResponse | null>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    load: () => Promise<void>;
+}
+
+export function usePublicBoot(options: BootLoaderOptions): UsePublicBootResult {
+    const loader = new BootLoader(options);
+    const boot = ref<PublicBootResponse | null>(null);
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    async function load() {
+        loading.value = true;
+        error.value = null;
+        try {
+            boot.value = await loader.load();
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+            boot.value = null;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    return { boot, loading, error, load };
+}

package/src/use-subscription-draft.ts

@@ -0,0 +1,355 @@
+// useSubscriptionDraft — Vue composable for the reactive configuration state
+// of the onboarding configurator (and the plan-change wizard).
+//
+// State: Plan + Cycle + selected catalog bundles + promo-code status.
+// Output: derived prices per cycle, breakdown per block (Plan / Bundles),
+//         active feature set, API payload for
+//         `POST /billing/onboarding/initial-subscription`.
+//
+// Intentionally HTTP-free — the consumer wires in `previewPromo()` and
+// `submit()` externally and feeds the result in via `setPromoState`.
+// This keeps the composable testable without network mocks.
+
+import { computed, ref, type ComputedRef, type Ref } from 'vue';
+import type { CatalogPlan } from './use-tenant-billing-catalog.js';
+import type { BillingCycleStr } from './use-tenant-billing.js';
+import {
+    selectChargeableBundles,
+    type OnboardingSelectionRequest,
+    type PromoPreviewResponse,
+    type PromoPreviewValidResponse,
+    type PublicMarketingBundle,
+} from '@saasicat/types';
+
+// For yearly payment, the mockup applies 10x the monthly price (= 2 months free).
+// If the catalog already provides a `yearlyNet`, that one is used;
+// if it is missing, the composable falls back to `monthly * 10`.
+export const DEFAULT_YEARLY_FACTOR = 10;
+
+export type PromoStatus = 'idle' | 'checking' | 'valid' | 'invalid' | 'restricted';
+
+export interface PromoState {
+    status: PromoStatus;
+    /** Backend response (only set when status === 'valid' or 'restricted'). */
+    preview: PromoPreviewResponse | null;
+    /** Display text for the UI (confirmation or error message). */
+    message: string;
+}
+
+export interface UseSubscriptionDraftOptions {
+    plans: Ref<CatalogPlan[] | null> | ComputedRef<CatalogPlan[] | null>;
+    subscriptionBundles?:
+        | Ref<PublicMarketingBundle[] | null>
+        | ComputedRef<PublicMarketingBundle[] | null>;
+    initialPlan?: string | null;
+    initialCycle?: BillingCycleStr;
+    initialBundleVersionIds?: ReadonlyArray<string>;
+    /** Override for the `yearlyNet` fallback if the catalog provides no yearlyNet. */
+    yearlyFactor?: number;
+}
+
+export interface PriceLineItem {
+    /** Stable key for UI `v-for`. */
+    key: string;
+    label: string;
+    /** Raw catalog value in the selected cycle unit. */
+    net: number;
+    /** Optional: additional text. */
+    sublabel?: string;
+}
+
+export interface DraftPricing {
+    cycle: BillingCycleStr;
+    /** Plan base without bundles. */
+    planNet: number;
+    /** Sum of all selected catalog bundles. */
+    bundlesNet: number;
+    /** Plan + Bundles. */
+    subtotalNet: number;
+    /** Discount derived from the promo preview (on subtotalNet, not plan-only). */
+    discountNet: number;
+    /** subtotalNet - discountNet. */
+    totalNet: number;
+    /** Savings per year vs. monthly payment. */
+    yearSavings: number;
+    /** Structured breakdown for the sticky sidebar. */
+    breakdown: {
+        plan: PriceLineItem | null;
+        bundles: PriceLineItem[];
+    };
+}
+
+export interface SubscriptionDraft {
+    // ─── State (writable) ─────────────────────────────────────────────
+    plan: Ref<string | null>;
+    cycle: Ref<BillingCycleStr>;
+    selectedBundleVersionIds: Ref<Set<string>>;
+    promoCode: Ref<string>;
+    promoState: Ref<PromoState>;
+
+    // ─── Derived ─────────────────────────────────────────────────────
+    selectedPlan: ComputedRef<CatalogPlan | null>;
+    /** Plan-included ∪ features of the selected catalog bundles. */
+    activeFeatures: ComputedRef<Set<string>>;
+    pricing: ComputedRef<DraftPricing>;
+    isDirty: ComputedRef<boolean>;
+
+    // ─── Mutators ────────────────────────────────────────────────────
+    setPlan(planId: string): void;
+    setCycle(c: BillingCycleStr): void;
+    toggleSubscriptionBundle(bundleVersionId: string): void;
+    setPromoCode(code: string): void;
+    setPromoState(state: PromoState): void;
+    clearPromo(): void;
+
+    // ─── Serialization ───────────────────────────────────────────────
+    toApiPayload(): OnboardingSelectionRequest;
+}
+
+function unwrap<T>(source: Ref<T> | ComputedRef<T> | T): T {
+    if (source && typeof source === 'object' && 'value' in source) {
+        return (source as Ref<T>).value;
+    }
+    return source as T;
+}
+
+function priceForCycle(
+    monthlyNet: number,
+    yearlyNet: number | null | undefined,
+    cycle: BillingCycleStr,
+    yearlyFactor: number,
+): number {
+    if (cycle === 'YEARLY') {
+        return yearlyNet != null ? yearlyNet : monthlyNet * yearlyFactor;
+    }
+    return monthlyNet;
+}
+
+export function useSubscriptionDraft(options: UseSubscriptionDraftOptions): SubscriptionDraft {
+    const yearlyFactor = options.yearlyFactor ?? DEFAULT_YEARLY_FACTOR;
+
+    const plansRef = computed<CatalogPlan[]>(() => unwrap(options.plans) ?? []);
+    const subscriptionBundlesRef = computed<PublicMarketingBundle[]>(
+        () => unwrap(options.subscriptionBundles ?? null) ?? [],
+    );
+
+    const plan = ref<string | null>(options.initialPlan ?? null);
+    const cycle = ref<BillingCycleStr>(options.initialCycle ?? 'MONTHLY');
+    const selectedBundleVersionIds = ref<Set<string>>(
+        new Set(options.initialBundleVersionIds ?? []),
+    );
+    const promoCode = ref('');
+    const promoState = ref<PromoState>({ status: 'idle', preview: null, message: '' });
+
+    const selectedPlan = computed(() => {
+        if (!plan.value) return null;
+        return plansRef.value.find((p) => p.id === plan.value) ?? null;
+    });
+
+    const selectedBundles = computed<PublicMarketingBundle[]>(() =>
+        subscriptionBundlesRef.value.filter((b) =>
+            selectedBundleVersionIds.value.has(b.bundleVersionId),
+        ),
+    );
+
+    // Selected bundles whose features are fully covered by Plan ∪ the other
+    // selected bundles would be sold twice. They flow into neither price nor
+    // payload — reactive, so that deselecting the covering bundle recomputes
+    // the redundant bundle again. Shared, iterative redundancy derivation
+    // (`selectChargeableBundles`): under mutual/cyclic coverage it deterministically
+    // keeps exactly one bundle instead of discarding all involved. Display
+    // order follows the catalog — the helper only determines WHICH bundles
+    // remain, not their sort order.
+    const chargeableBundles = computed<PublicMarketingBundle[]>(() => {
+        const planFeatures = selectedPlan.value?.features ?? [];
+        const selected = selectedBundles.value;
+        const keptIds = new Set(
+            selectChargeableBundles(planFeatures, selected).map((b) => b.bundleVersionId),
+        );
+        return selected.filter((b) => keptIds.has(b.bundleVersionId));
+    });
+
+    const activeFeatures = computed<Set<string>>(() => {
+        const result = new Set<string>();
+        const planObj = selectedPlan.value;
+        if (planObj) {
+            for (const f of planObj.features) result.add(f);
+        }
+        for (const bundle of selectedBundles.value) {
+            for (const f of bundle.features) result.add(f);
+        }
+        return result;
+    });
+
+    const pricing = computed<DraftPricing>(() => {
+        const cyc = cycle.value;
+        const planObj = selectedPlan.value;
+
+        // Plan
+        const planNet = planObj
+            ? priceForCycle(planObj.monthlyNet ?? 0, planObj.yearlyNet, cyc, yearlyFactor)
+            : 0;
+
+        // Independently bookable catalog bundles from the public marketing catalog.
+        // Redundant (fully covered) bundles are excluded here.
+        const bundleItems: PriceLineItem[] = [];
+        let bundlesNet = 0;
+        for (const b of chargeableBundles.value) {
+            const net = priceForCycle(b.monthlyNet ?? 0, b.yearlyNet, cyc, yearlyFactor);
+            bundlesNet += net;
+            bundleItems.push({
+                key: `subscription-bundle:${b.bundleVersionId}`,
+                label: b.label,
+                net,
+            });
+        }
+
+        const subtotalNet = planNet + bundlesNet;
+
+        // Derive discount from the promo preview (PERCENT logic is mirrored on the
+        // frontend; ABSOLUTE is deducted absolutely). The backend recomputes the
+        // final truth at redeem time — the sidebar shows only the preview value.
+        let discountNet = 0;
+        const preview = promoState.value.preview;
+        if (preview && preview.valid && promoState.value.status === 'valid') {
+            const valid = preview as PromoPreviewValidResponse;
+            const value = Number(valid.discount.value);
+            if (Number.isFinite(value) && value > 0) {
+                if (valid.discount.valueType === 'PERCENT') {
+                    discountNet = (subtotalNet * value) / 100;
+                } else {
+                    discountNet = Math.min(value, subtotalNet);
+                }
+            }
+        }
+
+        const totalNet = Math.max(0, subtotalNet - discountNet);
+
+        // yearSavings: 12 × monthly — yearly. Only meaningful when the catalog
+        // knows both prices; otherwise 0.
+        let yearSavings = 0;
+        if (planObj) {
+            const monthlyTotal =
+                priceForCycle(planObj.monthlyNet ?? 0, planObj.yearlyNet, 'MONTHLY', yearlyFactor) *
+                12;
+            const yearlyTotal = priceForCycle(
+                planObj.monthlyNet ?? 0,
+                planObj.yearlyNet,
+                'YEARLY',
+                yearlyFactor,
+            );
+            yearSavings = Math.max(0, monthlyTotal - yearlyTotal);
+        }
+
+        return {
+            cycle: cyc,
+            planNet,
+            bundlesNet,
+            subtotalNet,
+            discountNet,
+            totalNet,
+            yearSavings,
+            breakdown: {
+                plan: planObj
+                    ? {
+                          key: `plan:${planObj.id}`,
+                          label: planObj.name,
+                          net: planNet,
+                          sublabel: `${planObj.features.length} Basis-Module`,
+                      }
+                    : null,
+                bundles: bundleItems,
+            },
+        };
+    });
+
+    const isDirty = computed(() => {
+        return selectedBundleVersionIds.value.size > 0 || promoState.value.status === 'valid';
+    });
+
+    function setPlan(planId: string): void {
+        if (plan.value === planId) return;
+        plan.value = planId;
+        // Reduce the bundle selection to those compatible with the new plan.
+        const compatibleBundleVersions = new Set<string>();
+        for (const bundle of subscriptionBundlesRef.value) {
+            if (
+                bundle.compatiblePlanKeys.length === 0 ||
+                bundle.compatiblePlanKeys.includes(planId)
+            ) {
+                compatibleBundleVersions.add(bundle.bundleVersionId);
+            }
+        }
+        selectedBundleVersionIds.value = new Set(
+            [...selectedBundleVersionIds.value].filter((id) => compatibleBundleVersions.has(id)),
+        );
+    }
+
+    function setCycle(c: BillingCycleStr): void {
+        cycle.value = c;
+        // Promo restrictions may change — the caller re-runs preview if needed.
+    }
+
+    function toggleSubscriptionBundle(bundleVersionId: string): void {
+        const next = new Set(selectedBundleVersionIds.value);
+        if (next.has(bundleVersionId)) next.delete(bundleVersionId);
+        else next.add(bundleVersionId);
+        selectedBundleVersionIds.value = next;
+    }
+
+    function setPromoCode(code: string): void {
+        promoCode.value = code.toUpperCase();
+        // Reset status — the caller re-validates via preview().
+        if (promoState.value.status !== 'idle') {
+            promoState.value = { status: 'idle', preview: null, message: '' };
+        }
+    }
+
+    function setPromoState(state: PromoState): void {
+        promoState.value = state;
+    }
+
+    function clearPromo(): void {
+        promoCode.value = '';
+        promoState.value = { status: 'idle', preview: null, message: '' };
+    }
+
+    function toApiPayload(): OnboardingSelectionRequest {
+        if (!plan.value) {
+            throw new Error('useSubscriptionDraft: plan ist nicht gesetzt');
+        }
+        const payload: OnboardingSelectionRequest = {
+            plan: plan.value,
+            billingCycle: cycle.value,
+        };
+        if (promoState.value.status === 'valid' && promoCode.value) {
+            payload.promoCode = promoCode.value;
+        }
+        // Send only actually charged bundles — redundant (fully covered) ones
+        // would otherwise be booked twice.
+        const chargeableIds = chargeableBundles.value.map((b) => b.bundleVersionId);
+        if (chargeableIds.length > 0) {
+            payload.bundleVersionIds = chargeableIds;
+        }
+        return payload;
+    }
+
+    return {
+        plan,
+        cycle,
+        selectedBundleVersionIds,
+        promoCode,
+        promoState,
+        selectedPlan,
+        activeFeatures,
+        pricing,
+        isDirty,
+        setPlan,
+        setCycle,
+        toggleSubscriptionBundle,
+        setPromoCode,
+        setPromoState,
+        clearPromo,
+        toApiPayload,
+    };
+}

package/src/use-super-admin-context.ts

@@ -0,0 +1,93 @@
+// Composables for the platform maps provided() via `createSuperAdminApp()`.
+// Components inside the shell call these instead of direct inject() calls,
+// so that type safety and default behavior stay centralized.
+
+import { inject } from 'vue';
+import type { AdminManifest } from '@saasicat/types';
+import {
+    SUPER_ADMIN_ACTIONS_KEY,
+    SUPER_ADMIN_BRAND_KEY,
+    SUPER_ADMIN_ENDPOINTS_KEY,
+    SUPER_ADMIN_EXTENSIONS_KEY,
+    SUPER_ADMIN_HTTP_KEY,
+    SUPER_ADMIN_LOGIN_ADAPTER_KEY,
+    SUPER_ADMIN_MANIFEST_KEY,
+    type ActionsMap,
+    type ExtensionsMap,
+    type SuperAdminBrand,
+    type SuperAdminEndpoints,
+    type SuperAdminLoginAdapter,
+} from './create-super-admin-app.js';
+import { defaultHttpClient, type HttpClient } from './types.js';
+
+/** Returns the `extensions:` map registered in `createSuperAdminApp()`. */
+export function useSuperAdminExtensions(): ExtensionsMap {
+    return inject(SUPER_ADMIN_EXTENSIONS_KEY, {} as ExtensionsMap);
+}
+
+/** Returns the `actions:` map registered in `createSuperAdminApp()`. */
+export function useSuperAdminActions(): ActionsMap {
+    return inject(SUPER_ADMIN_ACTIONS_KEY, {} as ActionsMap);
+}
+
+/**
+ * Returns the app branding. Throws when the component is rendered outside a
+ * `createSuperAdminApp()` shell — that is a setup bug, not a runtime
+ * problem.
+ */
+export function useSuperAdminBrand(): SuperAdminBrand {
+    const brand = inject(SUPER_ADMIN_BRAND_KEY);
+    if (!brand) {
+        throw new Error(
+            'useSuperAdminBrand(): kein SuperAdmin-Branding im Inject-Scope. Wurde die Komponente innerhalb createSuperAdminApp() gemounted?',
+        );
+    }
+    return brand;
+}
+
+/** Returns the app endpoints (apiBase, publicBootEndpoint, manifestEndpoint). */
+export function useSuperAdminEndpoints(): Required<SuperAdminEndpoints> {
+    const endpoints = inject(SUPER_ADMIN_ENDPOINTS_KEY);
+    if (!endpoints) {
+        throw new Error(
+            'useSuperAdminEndpoints(): keine Endpoints im Inject-Scope. Wurde die Komponente innerhalb createSuperAdminApp() gemounted?',
+        );
+    }
+    return endpoints;
+}
+
+/**
+ * Returns the manifest accessor that was provided via
+ * `createSuperAdminApp({ manifestGuard: { getManifest } })`.
+ * Returns `null` if the app did not pass an accessor — components
+ * (e.g. `<ProjectPageHost>`) must handle the null case cleanly, because
+ * the accessor is optional.
+ */
+export function useSuperAdminManifest(): AdminManifest | null {
+    const accessor = inject(SUPER_ADMIN_MANIFEST_KEY, null);
+    return accessor ? accessor() : null;
+}
+
+/**
+ * Returns the login adapter the app registered via
+ * `createSuperAdminApp({ loginAdapter })`. Throws when none was
+ * set — the shared `<SuperAdminLoginPage>` needs it.
+ */
+export function useSuperAdminLoginAdapter(): SuperAdminLoginAdapter {
+    const adapter = inject(SUPER_ADMIN_LOGIN_ADAPTER_KEY);
+    if (!adapter) {
+        throw new Error(
+            'useSuperAdminLoginAdapter(): kein Login-Adapter registriert. Reiche ihn via createSuperAdminApp({ loginAdapter }) ein.',
+        );
+    }
+    return adapter;
+}
+
+/**
+ * Returns the pre-login `HttpClient` (boot, first-run setup) the app registered
+ * via `createSuperAdminApp({ http })`. Falls back to `defaultHttpClient()`
+ * if none was provided (e.g. in isolated tests).
+ */
+export function useSuperAdminHttp(): HttpClient {
+    return inject(SUPER_ADMIN_HTTP_KEY, defaultHttpClient());
+}