@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/features/FeaturesContext.js

@@ -0,0 +1,217 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * FeaturesContext
+ *
+ * Central context for feature gating on the frontend.
+ *
+ * Responsibilities:
+ * - Receives the merged FeatureConfiguration (core + custom) from app initialization
+ * - Builds a definitions map for fast lookup
+ * - Fetches resolved features from backend API: GET /api/v1/features/resolved
+ * - Caches resolved features in context state
+ * - Invalidates on WebSocket events (FEATURES_CHANGED, BILLING_STATUS_CHANGED, etc.)
+ * - Exposes raw resolved features + definitions + unavailability policy
+ *
+ * Frontend limit checking is ADVISORY — backend gate is authoritative.
+ * Stale usage data means the frontend might allow a click that the backend rejects
+ * (which is acceptable — the error is caught and displayed).
+ */
+import { createContext, useEffect, useState, useCallback, useMemo, useRef } from 'react';
+import { CoreWebSocketEvent, FEATURES_UNLIMITED, } from '@wildo-ai/saas-models';
+import { useWebSocket } from '../../core/requests/websockets/useWebSocket.js';
+import { useAuthSession } from '../../core/security/useAuthSession.js';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { getManualCallsHttpClient } from '../../core/requests/wildo-http-client-manual-calls.frontend.service.js';
+import { useAppScopeSafe } from '../../core/scope/useAppScope.js';
+// ================================
+// Logger
+// ================================
+const featuresLogger = LoggerFrontendService.getLogger();
+const logDebug = featuresLogger.debugByType('FeaturesContext');
+featuresLogger.setDebugTypeLogging('FeaturesContext', false);
+// ================================
+// Constants
+// ================================
+const FEATURES_API_URL = '/api/v1/features/resolved';
+/** WebSocket events that trigger a refetch of resolved features */
+const INVALIDATION_EVENTS = [
+    CoreWebSocketEvent.BILLING_STATUS_CHANGED,
+    CoreWebSocketEvent.BILLING_SUBSCRIPTION_UPDATED,
+    CoreWebSocketEvent.BILLING_ACCOUNT_CHANGED,
+    CoreWebSocketEvent.BILLING_FEATURES_UPDATED,
+];
+// ── Default empty state ──
+const EMPTY_RESOLVED = {
+    features: [],
+    limits: {},
+    currentUsage: {},
+};
+export const FeaturesContext = createContext(undefined);
+export function FeaturesProvider({ featureConfiguration, children }) {
+    // ── State ──
+    const [resolvedFeaturesResponse, setResolvedFeaturesResponse] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // ── Refs for stable callbacks ──
+    const fetchInFlightRef = useRef(false);
+    const mountedRef = useRef(true);
+    const debounceTimerRef = useRef(null);
+    // ── Auth — features are user-scoped, only fetch when authenticated ──
+    const { isAuthenticated } = useAuthSession();
+    const authenticated = isAuthenticated();
+    const appScope = useAppScopeSafe();
+    const currentOrganizationId = appScope?.currentOrganizationId ?? null;
+    // ── WebSocket ──
+    const { on } = useWebSocket();
+    // ── Build definitions map from configuration ──
+    const featureDefinitions = useMemo(() => {
+        const map = new Map();
+        for (const def of featureConfiguration.definitions) {
+            map.set(def.identifier, def);
+        }
+        logDebug('Feature definitions map built', { count: map.size });
+        return map;
+    }, [featureConfiguration.definitions]);
+    // ── Unavailability policy ──
+    const unavailabilityPolicy = useMemo(() => featureConfiguration.unavailabilityPolicy, [featureConfiguration.unavailabilityPolicy]);
+    // ── Derived resolved features ──
+    const resolvedFeatures = useMemo(() => {
+        if (!resolvedFeaturesResponse)
+            return EMPTY_RESOLVED;
+        return {
+            features: resolvedFeaturesResponse.features,
+            limits: resolvedFeaturesResponse.limits,
+            currentUsage: resolvedFeaturesResponse.currentUsage,
+        };
+    }, [resolvedFeaturesResponse]);
+    const clearResolvedFeatures = useCallback(() => {
+        setResolvedFeaturesResponse(null);
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    // ── Fetch resolved features from backend ──
+    const fetchResolvedFeatures = useCallback(async () => {
+        if (fetchInFlightRef.current)
+            return;
+        fetchInFlightRef.current = true;
+        try {
+            logDebug('Fetching resolved features from backend');
+            const httpClient = getManualCallsHttpClient();
+            const response = await httpClient.get(FEATURES_API_URL);
+            if (mountedRef.current) {
+                setResolvedFeaturesResponse(response);
+                setError(null);
+                logDebug('Resolved features fetched', {
+                    featureCount: response.features.length,
+                    limitCount: Object.keys(response.limits).length,
+                    usageCount: Object.keys(response.currentUsage).length,
+                });
+            }
+        }
+        catch (err) {
+            if (mountedRef.current) {
+                setError(err instanceof Error ? err : new Error(err?.message ?? 'Failed to fetch features'));
+                logDebug('Failed to fetch resolved features', { error: err?.message });
+            }
+        }
+        finally {
+            if (mountedRef.current) {
+                setIsLoading(false);
+            }
+            fetchInFlightRef.current = false;
+        }
+    }, []);
+    // ── Fetch when authenticated (and refetch on auth change) ──
+    useEffect(() => {
+        mountedRef.current = true;
+        if (authenticated) {
+            setIsLoading(true);
+            fetchResolvedFeatures();
+        }
+        else {
+            clearResolvedFeatures();
+        }
+        return () => {
+            mountedRef.current = false;
+        };
+    }, [authenticated, currentOrganizationId, fetchResolvedFeatures, clearResolvedFeatures]);
+    // ── WebSocket invalidation (debounced to coalesce rapid events) ──
+    useEffect(() => {
+        if (!authenticated)
+            return;
+        const unsubscribers = [];
+        const debouncedRefetch = () => {
+            if (debounceTimerRef.current) {
+                clearTimeout(debounceTimerRef.current);
+            }
+            debounceTimerRef.current = setTimeout(() => {
+                debounceTimerRef.current = null;
+                fetchResolvedFeatures();
+            }, 300);
+        };
+        for (const event of INVALIDATION_EVENTS) {
+            const unsub = on(event, () => {
+                logDebug('WebSocket invalidation event received, scheduling refetch', { event });
+                debouncedRefetch();
+            });
+            unsubscribers.push(unsub);
+        }
+        return () => {
+            if (debounceTimerRef.current) {
+                clearTimeout(debounceTimerRef.current);
+            }
+            for (const unsub of unsubscribers) {
+                unsub();
+            }
+        };
+    }, [authenticated, on, fetchResolvedFeatures]);
+    // ── Derived features set for O(1) lookups ──
+    const resolvedFeaturesSet = useMemo(() => new Set(resolvedFeatures.features), [resolvedFeatures.features]);
+    // ── Convenience accessors ──
+    const isFeatureEnabled = useCallback((featureId) => {
+        return resolvedFeaturesSet.has(featureId);
+    }, [resolvedFeaturesSet]);
+    const getLimit = useCallback((featureId) => {
+        return resolvedFeatures.limits[featureId];
+    }, [resolvedFeatures.limits]);
+    const getCurrentUsage = useCallback((featureId) => {
+        return resolvedFeatures.currentUsage[featureId];
+    }, [resolvedFeatures.currentUsage]);
+    const getRemainingCapacity = useCallback((featureId) => {
+        const limit = resolvedFeatures.limits[featureId];
+        if (limit === undefined)
+            return undefined;
+        if (limit === FEATURES_UNLIMITED)
+            return undefined; // unlimited → no meaningful remaining
+        const usage = resolvedFeatures.currentUsage[featureId] ?? 0;
+        return Math.max(0, limit - usage);
+    }, [resolvedFeatures.limits, resolvedFeatures.currentUsage]);
+    // ── Context value (memoized for stable reference) ──
+    const contextValue = useMemo(() => ({
+        resolvedFeatures,
+        resolvedFeaturesResponse,
+        featureDefinitions,
+        unavailabilityPolicy,
+        isFeatureEnabled,
+        getLimit,
+        getCurrentUsage,
+        getRemainingCapacity,
+        isLoading,
+        error,
+        refetch: fetchResolvedFeatures,
+    }), [
+        resolvedFeatures,
+        resolvedFeaturesResponse,
+        featureDefinitions,
+        unavailabilityPolicy,
+        isFeatureEnabled,
+        getLimit,
+        getCurrentUsage,
+        getRemainingCapacity,
+        isLoading,
+        error,
+        fetchResolvedFeatures,
+    ]);
+    return (_jsx(FeaturesContext.Provider, { value: contextValue, children: children }));
+}
+//# sourceMappingURL=FeaturesContext.js.map

package/dist/esm/core/features/FeaturesContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeaturesContext.js","sourceRoot":"","sources":["../../../../src/core/features/FeaturesContext.tsx"],"names":[],"mappings":"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"}

package/dist/esm/core/features/feature-unavailability.frontend.utils.d.ts

@@ -0,0 +1,29 @@
+import { FeatureUnavailabilityBehavior, type FeatureConfiguration, type FeatureDefinition } from '@wildo-ai/saas-models';
+interface FeaturePolicyPermissions {
+    appLevel?: string[] | null;
+    organizations?: Record<string, string[]> | null;
+}
+interface ResolveFeatureUnavailabilityBehaviorParams {
+    billingEnabled: boolean;
+    featureDef: FeatureDefinition | undefined;
+    policy: FeatureConfiguration['unavailabilityPolicy'];
+    reason: string;
+    userRoles: string[];
+}
+/**
+ * Merge app-level roles with the current organization's membership roles.
+ * The frontend policy contract can target either layer, so availability
+ * checks must resolve against the same effective role surface the user sees.
+ */
+export declare function buildFeaturePolicyRoles(permissions: FeaturePolicyPermissions | null | undefined, currentOrganizationId: string | null | undefined): string[];
+/**
+ * Resolve the final unavailability behavior with a single cascade shared by
+ * feature-level and operation-level checks.
+ */
+export declare function resolveFeatureUnavailabilityBehavior(params: ResolveFeatureUnavailabilityBehaviorParams): {
+    behavior: FeatureUnavailabilityBehavior;
+    suggestedProductRef?: string;
+    debugTrace: string[];
+};
+export {};
+//# sourceMappingURL=feature-unavailability.frontend.utils.d.ts.map

package/dist/esm/core/features/feature-unavailability.frontend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-unavailability.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../src/core/features/feature-unavailability.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,UAAU,wBAAwB;IAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACjD;AAED,UAAU,0CAA0C;IAClD,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC1C,MAAM,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAQD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,wBAAwB,GAAG,IAAI,GAAG,SAAS,EACxD,qBAAqB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/C,MAAM,EAAE,CAYV;AAgBD;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,0CAA0C,GACjD;IACD,QAAQ,EAAE,6BAA6B,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAsFA"}

package/dist/esm/core/features/feature-unavailability.frontend.utils.js

@@ -0,0 +1,84 @@
+import { FeatureUnavailabilityBehavior, } from '@wildo-ai/saas-models';
+const BILLING_PROMPT_BEHAVIORS = new Set([
+    FeatureUnavailabilityBehavior.UPGRADE_PROMPT,
+    FeatureUnavailabilityBehavior.LIMIT_UPGRADE_PROMPT,
+    FeatureUnavailabilityBehavior.ADDON_PROMPT,
+]);
+/**
+ * Merge app-level roles with the current organization's membership roles.
+ * The frontend policy contract can target either layer, so availability
+ * checks must resolve against the same effective role surface the user sees.
+ */
+export function buildFeaturePolicyRoles(permissions, currentOrganizationId) {
+    const roles = [];
+    if (permissions?.appLevel?.length) {
+        roles.push(...permissions.appLevel);
+    }
+    if (currentOrganizationId && permissions?.organizations?.[currentOrganizationId]?.length) {
+        roles.push(...permissions.organizations[currentOrganizationId]);
+    }
+    return [...new Set(roles)];
+}
+function applyBillingDisabledBehaviorOverride(behavior, billingEnabled, policy, trace) {
+    if (billingEnabled || !BILLING_PROMPT_BEHAVIORS.has(behavior)) {
+        return behavior;
+    }
+    trace.push(`[billing-disabled] Replacing ${behavior} with ${policy.whenBillingDisabled}`);
+    return policy.whenBillingDisabled;
+}
+/**
+ * Resolve the final unavailability behavior with a single cascade shared by
+ * feature-level and operation-level checks.
+ */
+export function resolveFeatureUnavailabilityBehavior(params) {
+    const { billingEnabled, featureDef, policy, reason, userRoles, } = params;
+    const trace = [];
+    if (featureDef?.unavailability?.behavior) {
+        trace.push(`[1] Per-feature override: ${featureDef.unavailability.behavior}`);
+        return {
+            behavior: applyBillingDisabledBehaviorOverride(featureDef.unavailability.behavior, billingEnabled, policy, trace),
+            suggestedProductRef: featureDef.unavailability.suggestedProductRef,
+            debugTrace: trace,
+        };
+    }
+    if (featureDef?.unavailability?.byRole) {
+        for (const role of userRoles) {
+            const roleBehavior = featureDef.unavailability.byRole[role];
+            if (roleBehavior) {
+                trace.push(`[2] Per-feature role override (${role}): ${roleBehavior}`);
+                return {
+                    behavior: applyBillingDisabledBehaviorOverride(roleBehavior, billingEnabled, policy, trace),
+                    suggestedProductRef: featureDef.unavailability.suggestedProductRef,
+                    debugTrace: trace,
+                };
+            }
+        }
+        trace.push('[2] Per-feature role override: no match');
+    }
+    for (const role of userRoles) {
+        const globalRoleBehavior = policy.roleDefaults[role];
+        if (globalRoleBehavior) {
+            trace.push(`[3] Global role default (${role}): ${globalRoleBehavior}`);
+            return {
+                behavior: applyBillingDisabledBehaviorOverride(globalRoleBehavior, billingEnabled, policy, trace),
+                debugTrace: trace,
+            };
+        }
+    }
+    trace.push('[3] Global role default: no match');
+    const reasonBehavior = policy.reasonDefaults[reason];
+    if (reasonBehavior) {
+        trace.push(`[4] Global reason default (${reason}): ${reasonBehavior}`);
+        return {
+            behavior: applyBillingDisabledBehaviorOverride(reasonBehavior, billingEnabled, policy, trace),
+            debugTrace: trace,
+        };
+    }
+    trace.push(`[4] Global reason default (${reason}): no match`);
+    trace.push(`[5] Global default: ${policy.defaultBehavior}`);
+    return {
+        behavior: applyBillingDisabledBehaviorOverride(policy.defaultBehavior, billingEnabled, policy, trace),
+        debugTrace: trace,
+    };
+}
+//# sourceMappingURL=feature-unavailability.frontend.utils.js.map

package/dist/esm/core/features/feature-unavailability.frontend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-unavailability.frontend.utils.js","sourceRoot":"","sources":["../../../../src/core/features/feature-unavailability.frontend.utils.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/features/useFeatureAvailability.d.ts

@@ -0,0 +1,47 @@
+/**
+ * useFeatureAvailability Hook
+ *
+ * Resolves "is this feature available, and if not, what to do about it" for a single feature.
+ * Uses the FeaturesContext (resolved features + definitions + unavailability policy) and
+ * UserOrgsContext (for role) to resolve the complete availability state.
+ *
+ * Policy cascade (first match wins):
+ *   1. Per-feature override → feature.unavailability.behavior
+ *   2. Per-feature role override → feature.unavailability.byRole[role]
+ *   3. Global role default → policy.roleDefaults[role]
+ *   4. Global reason default → policy.reasonDefaults[reason]
+ *   5. Global default → policy.defaultBehavior
+ *
+ * Includes dev-only debugTrace for debugging policy resolution.
+ */
+import { FeatureUnavailabilityBehavior, FeatureUnavailabilityReason, type FeatureUpgradeOption } from '@wildo-ai/saas-models';
+export interface FeatureAvailability {
+    /** Whether the feature is available for the current context */
+    isAvailable: boolean;
+    /** Why the feature is unavailable */
+    reason?: FeatureUnavailabilityReason;
+    /** What behavior the UI should adopt */
+    behavior: FeatureUnavailabilityBehavior;
+    /** Which feature(s) are missing (for boolean OR/AND modes) */
+    missingFeatures?: string[];
+    /** Limit information (for limit features) */
+    limitInfo?: {
+        featureId: string;
+        current: number;
+        limit: number;
+    };
+    /** Upgrade options from the backend (from resolved features response) */
+    upgradeOptions?: FeatureUpgradeOption[];
+    /** Suggested product reference (from per-feature override) */
+    suggestedProductRef?: string;
+    /** Policy resolution trace — only populated in development mode */
+    debugTrace?: string[];
+}
+/**
+ * Resolve availability + behavior for a single feature.
+ *
+ * @param featureId - The feature identifier to check
+ * @returns FeatureAvailability — the resolved availability, behavior, and metadata
+ */
+export declare function useFeatureAvailability(featureId: string): FeatureAvailability;
+//# sourceMappingURL=useFeatureAvailability.d.ts.map

package/dist/esm/core/features/useFeatureAvailability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFeatureAvailability.d.ts","sourceRoot":"","sources":["../../../../src/core/features/useFeatureAvailability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAGL,6BAA6B,EAC7B,2BAA2B,EAE3B,KAAK,oBAAoB,EAC1B,MAAM,uBAAuB,CAAC;AAmB/B,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IAGrB,qCAAqC;IACrC,MAAM,CAAC,EAAE,2BAA2B,CAAC;IACrC,wCAAwC;IACxC,QAAQ,EAAE,6BAA6B,CAAC;IACxC,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,6CAA6C;IAC7C,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,yEAAyE;IACzE,cAAc,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACxC,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAG7B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAwJ7E"}

package/dist/esm/core/features/useFeatureAvailability.js

@@ -0,0 +1,160 @@
+/**
+ * useFeatureAvailability Hook
+ *
+ * Resolves "is this feature available, and if not, what to do about it" for a single feature.
+ * Uses the FeaturesContext (resolved features + definitions + unavailability policy) and
+ * UserOrgsContext (for role) to resolve the complete availability state.
+ *
+ * Policy cascade (first match wins):
+ *   1. Per-feature override → feature.unavailability.behavior
+ *   2. Per-feature role override → feature.unavailability.byRole[role]
+ *   3. Global role default → policy.roleDefaults[role]
+ *   4. Global reason default → policy.reasonDefaults[reason]
+ *   5. Global default → policy.defaultBehavior
+ *
+ * Includes dev-only debugTrace for debugging policy resolution.
+ */
+import { useEffect, useMemo } from 'react';
+import { FEATURES_UNLIMITED, FeatureValueType, FeatureUnavailabilityBehavior, FeatureUnavailabilityReason, } from '@wildo-ai/saas-models';
+import { useFeatures } from './useFeatures.js';
+import { useUserOrgs } from '../../core/security/useUserOrgs.js';
+import { useAnalytics } from '../../core/monitoring/analytics/useAnalytics.js';
+import { envLoader } from '../../core/runtime/env-variable-loader.frontend.service.js';
+import { useBillingSafe } from '../../core/billing/useBilling.js';
+import { useAppScopeSafe } from '../../core/scope/useAppScope.js';
+import { buildFeaturePolicyRoles, resolveFeatureUnavailabilityBehavior, } from './feature-unavailability.frontend.utils.js';
+// Cross-instance dedup for feature gate analytics
+const reportedFeatures = new Set();
+/**
+ * Resolve availability + behavior for a single feature.
+ *
+ * @param featureId - The feature identifier to check
+ * @returns FeatureAvailability — the resolved availability, behavior, and metadata
+ */
+export function useFeatureAvailability(featureId) {
+    const { resolvedFeatures, resolvedFeaturesResponse, featureDefinitions, unavailabilityPolicy, isLoading, } = useFeatures();
+    const { permissions } = useUserOrgs();
+    const { track, isActive } = useAnalytics();
+    const billing = useBillingSafe();
+    const appScope = useAppScopeSafe();
+    const result = useMemo(() => {
+        // While loading, treat as available (optimistic — prevents flash of locked UI)
+        if (isLoading) {
+            return { isAvailable: true, behavior: FeatureUnavailabilityBehavior.DISABLE };
+        }
+        const featureDef = featureDefinitions.get(featureId);
+        // Feature not registered → NOT_CONFIGURED
+        if (!featureDef) {
+            const { behavior, debugTrace } = resolveFeatureUnavailabilityBehavior({
+                reason: FeatureUnavailabilityReason.NOT_CONFIGURED,
+                featureDef: undefined,
+                policy: unavailabilityPolicy,
+                userRoles: [],
+                billingEnabled: billing?.isEnabled ?? false,
+            });
+            return {
+                isAvailable: false,
+                reason: FeatureUnavailabilityReason.NOT_CONFIGURED,
+                behavior,
+                missingFeatures: [featureId],
+                debugTrace: envLoader.isDevelopment() ? debugTrace : undefined,
+            };
+        }
+        // Build user roles array for policy resolution
+        const userRoles = buildFeaturePolicyRoles(permissions, appScope?.currentOrganizationId ?? null);
+        // ── Boolean feature check ──
+        if (featureDef.valueType === FeatureValueType.BOOLEAN) {
+            const resolvedSet = new Set(resolvedFeatures.features);
+            const isEnabled = resolvedSet.has(featureId);
+            if (isEnabled) {
+                return { isAvailable: true, behavior: FeatureUnavailabilityBehavior.DISABLE };
+            }
+            // Not enabled → resolve behavior
+            const reason = FeatureUnavailabilityReason.FEATURE_NOT_ENABLED;
+            const { behavior, suggestedProductRef, debugTrace } = resolveFeatureUnavailabilityBehavior({
+                reason,
+                featureDef,
+                policy: unavailabilityPolicy,
+                userRoles,
+                billingEnabled: billing?.isEnabled ?? false,
+            });
+            // Get upgrade options from backend response
+            const upgradeOptions = resolvedFeaturesResponse?.upgradeOptions?.[featureId]?.availableVia;
+            return {
+                isAvailable: false,
+                reason,
+                behavior,
+                missingFeatures: [featureId],
+                upgradeOptions,
+                suggestedProductRef,
+                debugTrace: envLoader.isDevelopment() ? debugTrace : undefined,
+            };
+        }
+        // ── Limit feature check ──
+        if (featureDef.valueType === FeatureValueType.LIMIT) {
+            const limit = resolvedFeatures.limits[featureId];
+            // No limit set → available (no restriction configured)
+            if (limit === undefined) {
+                return { isAvailable: true, behavior: FeatureUnavailabilityBehavior.DISABLE };
+            }
+            // Unlimited → always available
+            if (limit === FEATURES_UNLIMITED) {
+                return { isAvailable: true, behavior: FeatureUnavailabilityBehavior.DISABLE };
+            }
+            const currentUsage = resolvedFeatures.currentUsage[featureId] ?? 0;
+            // Under the limit → available
+            if (currentUsage < limit) {
+                return { isAvailable: true, behavior: FeatureUnavailabilityBehavior.DISABLE };
+            }
+            // At or over limit → resolve behavior
+            const reason = FeatureUnavailabilityReason.LIMIT_EXCEEDED;
+            const { behavior, suggestedProductRef, debugTrace } = resolveFeatureUnavailabilityBehavior({
+                reason,
+                featureDef,
+                policy: unavailabilityPolicy,
+                userRoles,
+                billingEnabled: billing?.isEnabled ?? false,
+            });
+            const upgradeOptions = resolvedFeaturesResponse?.upgradeOptions?.[featureId]?.availableVia;
+            return {
+                isAvailable: false,
+                reason,
+                behavior,
+                limitInfo: { featureId, current: currentUsage, limit },
+                upgradeOptions,
+                suggestedProductRef,
+                debugTrace: envLoader.isDevelopment() ? debugTrace : undefined,
+            };
+        }
+        // Unknown value type → treat as available (defensive)
+        return { isAvailable: true, behavior: FeatureUnavailabilityBehavior.DISABLE };
+    }, [
+        featureId,
+        isLoading,
+        resolvedFeatures,
+        resolvedFeaturesResponse,
+        featureDefinitions,
+        unavailabilityPolicy,
+        permissions,
+        appScope?.currentOrganizationId,
+        billing?.isEnabled,
+    ]);
+    useEffect(() => {
+        if (!isActive)
+            return;
+        const dedupKey = `${featureId}:${result.isAvailable}`;
+        if (reportedFeatures.has(dedupKey))
+            return;
+        reportedFeatures.add(dedupKey);
+        track('feature_gate', {
+            featureRef: featureId,
+            isAvailable: result.isAvailable,
+            reason: result.reason,
+        });
+        if (result.isAvailable) {
+            track('feature_accessed', { featureId });
+        }
+    }, [featureId, result.isAvailable, result.reason, isActive, track]);
+    return result;
+}
+//# sourceMappingURL=useFeatureAvailability.js.map

package/dist/esm/core/features/useFeatureAvailability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFeatureAvailability.js","sourceRoot":"","sources":["../../../../src/core/features/useFeatureAvailability.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/features/useFeatureGate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * useFeatureGate Hook
+ *
+ * Separated from FeatureGate.tsx for React Fast Refresh compatibility.
+ */
+import { type FeatureAvailability } from './useFeatureAvailability.js';
+/**
+ * Programmatic hook for checking a single feature's availability.
+ * Equivalent to useFeatureAvailability — provides both the availability state and
+ * a convenience `isAvailable` boolean.
+ */
+export declare function useFeatureGate(featureId: string): FeatureAvailability;
+//# sourceMappingURL=useFeatureGate.d.ts.map

package/dist/esm/core/features/useFeatureGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFeatureGate.d.ts","sourceRoot":"","sources":["../../../../src/core/features/useFeatureGate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE5F;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAErE"}

package/dist/esm/core/features/useFeatureGate.js

@@ -0,0 +1,15 @@
+/**
+ * useFeatureGate Hook
+ *
+ * Separated from FeatureGate.tsx for React Fast Refresh compatibility.
+ */
+import { useFeatureAvailability } from './useFeatureAvailability.js';
+/**
+ * Programmatic hook for checking a single feature's availability.
+ * Equivalent to useFeatureAvailability — provides both the availability state and
+ * a convenience `isAvailable` boolean.
+ */
+export function useFeatureGate(featureId) {
+    return useFeatureAvailability(featureId);
+}
+//# sourceMappingURL=useFeatureGate.js.map

package/dist/esm/core/features/useFeatureGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFeatureGate.js","sourceRoot":"","sources":["../../../../src/core/features/useFeatureGate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,sBAAsB,EAA4B,MAAM,0BAA0B,CAAC;AAE5F;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,sBAAsB,CAAC,SAAS,CAAC,CAAC;AAC3C,CAAC"}

package/dist/esm/core/features/useFeatures.d.ts

@@ -0,0 +1,14 @@
+/**
+ * useFeatures Hook
+ *
+ * Separated from FeaturesContext.tsx for React Fast Refresh compatibility.
+ * Provides access to the feature context: resolved features, definitions, policy, and convenience methods.
+ */
+import { type FeaturesContextType } from './FeaturesContext.js';
+/**
+ * Hook to access the Features context.
+ * @returns FeaturesContextType with resolved features, definitions, policy, and convenience methods.
+ * @throws Error if used outside of FeaturesProvider.
+ */
+export declare const useFeatures: () => FeaturesContextType;
+//# sourceMappingURL=useFeatures.d.ts.map

package/dist/esm/core/features/useFeatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFeatures.d.ts","sourceRoot":"","sources":["../../../../src/core/features/useFeatures.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,mBAM9B,CAAC"}