@trackunit/react-core-hooks 1.17.59-alpha-df0e8d549b3.0 → 1.17.59

package/index.cjs.js

@@ -1,11 +1,162 @@
 'use strict';
 
-var reactCoreContextsApi = require('@trackunit/react-core-contexts-api');
 var react = require('react');
+var reactCoreContextsApi = require('@trackunit/react-core-contexts-api');
 var esToolkit = require('es-toolkit');
 var irisAppRuntimeCore = require('@trackunit/iris-app-runtime-core');
 var zod = require('zod');
 
+/**
+ * This is a hook to use the FeatureFlagContext.
+ *
+ * @requires FeatureFlagContext
+ * @example
+ * import { useFeatureFlags } from "@trackunit/react-core-hooks";
+ * const { flags } = useFeatureFlags();
+ * // use flags to control visibility/access ...
+ * @see (@link FeatureFlagContext)
+ */
+const useFeatureFlags = () => {
+    const context = react.useContext(reactCoreContextsApi.FeatureFlagContext);
+    if (!context) {
+        throw new Error("useFeatureFlags must be used within a FeatureFlagContext");
+    }
+    return context;
+};
+
+/**
+ * This is a hook to use the UserSubscriptionContext.
+ *
+ * @requires UserSubscriptionContext
+ * @example
+ * import { useUserSubscription } from "@trackunit/react-core-hooks";
+ * const { numberOfDaysWithAccessToHistoricalData, packageType } = useUserSubscription();
+ * // use it for something
+ * const data = fetchData(numberOfDaysWithAccessToHistoricalData)
+ * @see { UserSubscription}
+ */
+const useUserSubscription = () => {
+    const context = react.useContext(reactCoreContextsApi.UserSubscriptionContext);
+    if (!context) {
+        throw new Error("useUserSubscription must be used within the UserSubscriptionContext");
+    }
+    return context;
+};
+
+/**
+ * Hook providing the authenticated user's profile, account, and permission data
+ * from the CurrentUserContext.
+ *
+ * ### When to use
+ * Use `useCurrentUser` when you need the user's identity or account context — displaying
+ * the user's name, resolving the effective account ID, or branching logic based on
+ * `isAssuming` or `isTrackunitUser`.
+ *
+ * ### When not to use
+ * - If you only need a boolean check for a single permission — use `useUserPermission`.
+ * - To gate entire routes — prefer server-side access control or `hasAccessTo` from
+ *   `useNavigateInHost`.
+ *
+ * @example
+ * import { useCurrentUser } from "@trackunit/react-core-hooks";
+ * const { assumedUser, accountId } = useCurrentUser();
+ *
+ * const { data, loading } = useGetAccountByIdQuery({
+ *    variables: { accountId: assumedUser?.accountId || accountId || "" },
+ * });
+ * @see { CurrentUserContext}
+ */
+const useCurrentUser = () => {
+    const context = react.useContext(reactCoreContextsApi.CurrentUserContext);
+    if (!context) {
+        throw new Error("useCurrentUser must be used within the CurrentUserProvider");
+    }
+    return context;
+};
+
+/**
+ * Async wrapper around {@link useValidateAccess}. Each helper awaits until the
+ * underlying user, subscription, and feature-flag data has finished loading
+ * before resolving, so callers such as router guards can check access without
+ * having to observe the synchronous `loading` flag themselves.
+ */
+const useValidateAccessAsync = () => {
+    const { hasAccessTo, hasFeatureFlag, hasPermission, loading } = useValidateAccess();
+    const hasAccessToRef = react.useRef(hasAccessTo);
+    hasAccessToRef.current = hasAccessTo;
+    const hasFeatureFlagRef = react.useRef(hasFeatureFlag);
+    hasFeatureFlagRef.current = hasFeatureFlag;
+    const hasPermissionRef = react.useRef(hasPermission);
+    hasPermissionRef.current = hasPermission;
+    const loadingRef = react.useRef(loading);
+    loadingRef.current = loading;
+    return react.useMemo(() => {
+        const waitForLoading = async () => {
+            if (loadingRef.current) {
+                await new Promise(resolve => {
+                    const intervalId = setInterval(() => {
+                        if (!loadingRef.current) {
+                            clearInterval(intervalId);
+                            resolve();
+                        }
+                    }, 10);
+                });
+            }
+        };
+        return {
+            hasAccessTo: async (requiredAccessTo) => {
+                await waitForLoading();
+                return hasAccessToRef.current(requiredAccessTo);
+            },
+            hasFeatureFlag: async (flag) => {
+                await waitForLoading();
+                return hasFeatureFlagRef.current(flag);
+            },
+            hasPermission: async (permission) => {
+                await waitForLoading();
+                return hasPermissionRef.current(permission);
+            },
+        };
+    }, [loadingRef, hasAccessToRef, hasFeatureFlagRef, hasPermissionRef]);
+};
+/**
+ * Synchronously evaluates the current user's access via subscription features,
+ * feature flags, and permissions. Returns predicate helpers plus a `loading`
+ * flag that stays true until user, subscription, and flag data are all present.
+ */
+const useValidateAccess = () => {
+    const { isAuthenticated, permissions: userPermissions } = useCurrentUser();
+    const { features, loading: featuresLoading } = useUserSubscription();
+    const { flags: allFlags } = useFeatureFlags();
+    const loading = react.useMemo(() => allFlags === null || featuresLoading || !userPermissions, [allFlags, featuresLoading, userPermissions]);
+    const hasFeatureFlag = react.useCallback((flag) => {
+        return allFlags?.find(({ key }) => key === flag)?.state ?? null;
+    }, [allFlags]);
+    const hasAccessTo = react.useCallback((requiredAccessTo) => {
+        if (isAuthenticated) {
+            return hasAccessToFeature(features, requiredAccessTo);
+        }
+        return false;
+    }, [features, isAuthenticated]);
+    const hasPermission = react.useCallback((permission) => {
+        if (isAuthenticated) {
+            return userPermissions?.includes(permission) ?? false;
+        }
+        return false;
+    }, [isAuthenticated, userPermissions]);
+    return react.useMemo(() => {
+        return {
+            hasAccessTo,
+            hasFeatureFlag,
+            hasPermission,
+            loading,
+        };
+    }, [hasAccessTo, hasFeatureFlag, hasPermission, loading]);
+};
+const hasAccessToFeature = (myFeatures, feature) => {
+    return myFeatures?.some(x => x.id === feature) ?? null;
+};
+
 /**
  * Hook to get the analytics context.
  *
@@ -219,21 +370,39 @@ const useExportDataContext = () => {
 };
 
 /**
- * This is a hook to use the FeatureFlagContext.
+ * Reads a host feature flag by key.
+ *
+ * Return values:
+ * - `null` while the host feature flags have not loaded yet.
+ * - the flag's boolean `state` when the flag exists in the loaded set.
+ * - `null` when the flags are loaded but the requested flag is not present,
+ *   unless `options.defaultValueWhenMissing` is provided, in which case that
+ *   value is returned.
+ *
+ * The hook is generic so callers can narrow the accepted key. Internal callers
+ * pass the strongly-typed `Flag` union for type safety, e.g.
+ * `useHostFeatureFlag<Flag>(Flags.SOME_FLAG, { defaultValueWhenMissing: true })`.
+ * External callers may pass any string.
+ *
+ * Must be used within a `FeatureFlagContext` (provided by `TrackunitProviders`).
  *
- * @requires FeatureFlagContext
  * @example
- * import { useFeatureFlags } from "@trackunit/react-core-hooks";
- * const { flags } = useFeatureFlags();
- * // use flags to control visibility/access ...
- * @see (@link FeatureFlagContext)
+ * import { useHostFeatureFlag } from "@trackunit/react-core-hooks";
+ * const isEnabled = useHostFeatureFlag("my_flag", { defaultValueWhenMissing: true });
+ * @see useFeatureFlags
  */
-const useFeatureFlags = () => {
-    const context = react.useContext(reactCoreContextsApi.FeatureFlagContext);
-    if (!context) {
-        throw new Error("useFeatureFlags must be used within a FeatureFlagContext");
-    }
-    return context;
+const useHostFeatureFlag = (flag, options) => {
+    const { flags } = useFeatureFlags();
+    return react.useMemo(() => {
+        const found = flags?.find(({ key }) => key === flag);
+        if (found) {
+            return found.state;
+        }
+        if (flags && options.defaultValueWhenMissing !== undefined) {
+            return options.defaultValueWhenMissing;
+        }
+        return null;
+    }, [flags, flag, options.defaultValueWhenMissing]);
 };
 
 /**
@@ -896,25 +1065,6 @@ const useSiteRuntime = () => {
     return react.useMemo(() => ({ siteInfo, loading, error }), [siteInfo, loading, error]);
 };
 
-/**
- * This is a hook to use the UserSubscriptionContext.
- *
- * @requires UserSubscriptionContext
- * @example
- * import { useUserSubscription } from "@trackunit/react-core-hooks";
- * const { numberOfDaysWithAccessToHistoricalData, packageType } = useUserSubscription();
- * // use it for something
- * const data = fetchData(numberOfDaysWithAccessToHistoricalData)
- * @see { UserSubscription}
- */
-const useUserSubscription = () => {
-    const context = react.useContext(reactCoreContextsApi.UserSubscriptionContext);
-    if (!context) {
-        throw new Error("useUserSubscription must be used within the UserSubscriptionContext");
-    }
-    return context;
-};
-
 /**
  * This is a hook to use the TimeRangeProvider.
  *
@@ -960,37 +1110,6 @@ const useToast = () => {
     return toastContext;
 };
 
-/**
- * Hook providing the authenticated user's profile, account, and permission data
- * from the CurrentUserContext.
- *
- * ### When to use
- * Use `useCurrentUser` when you need the user's identity or account context — displaying
- * the user's name, resolving the effective account ID, or branching logic based on
- * `isAssuming` or `isTrackunitUser`.
- *
- * ### When not to use
- * - If you only need a boolean check for a single permission — use `useUserPermission`.
- * - To gate entire routes — prefer server-side access control or `hasAccessTo` from
- *   `useNavigateInHost`.
- *
- * @example
- * import { useCurrentUser } from "@trackunit/react-core-hooks";
- * const { assumedUser, accountId } = useCurrentUser();
- *
- * const { data, loading } = useGetAccountByIdQuery({
- *    variables: { accountId: assumedUser?.accountId || accountId || "" },
- * });
- * @see { CurrentUserContext}
- */
-const useCurrentUser = () => {
-    const context = react.useContext(reactCoreContextsApi.CurrentUserContext);
-    if (!context) {
-        throw new Error("useCurrentUser must be used within the CurrentUserProvider");
-    }
-    return context;
-};
-
 /**
  * This is a hook providing the Current User language.
  *
@@ -1429,6 +1548,7 @@ exports.useFeatureFlags = useFeatureFlags;
 exports.useFilterBarContext = useFilterBarContext;
 exports.useGeolocation = useGeolocation;
 exports.useHasAccessTo = useHasAccessTo;
+exports.useHostFeatureFlag = useHostFeatureFlag;
 exports.useImageUploader = useImageUploader;
 exports.useIrisAppId = useIrisAppId;
 exports.useIrisAppImage = useIrisAppImage;
@@ -1443,5 +1563,7 @@ exports.useToast = useToast;
 exports.useToken = useToken;
 exports.useUserPermission = useUserPermission;
 exports.useUserSubscription = useUserSubscription;
+exports.useValidateAccess = useValidateAccess;
+exports.useValidateAccessAsync = useValidateAccessAsync;
 exports.useWidgetConfig = useWidgetConfig;
 exports.useWidgetConfigAsync = useWidgetConfigAsync;

package/index.esm.js

@@ -1,9 +1,160 @@
-import { AnalyticsContext, AssetSortingContext, ConfirmationDialogContext, EnvironmentContext, ErrorHandlingContext, ExportDataContext, FeatureFlagContext, FilterBarContext, GeolocationContext, TokenContext, ModalDialogContext, NavigationContext, OemBrandingContext, UserSubscriptionContext, TimeRangeContext, ToastContext, CurrentUserContext, CurrentUserPreferenceContext, WidgetConfigContext } from '@trackunit/react-core-contexts-api';
-import { useContext, useMemo, useState, useCallback, useEffect, useReducer, useRef } from 'react';
+import { useContext, useMemo, useCallback, useRef, useState, useEffect, useReducer } from 'react';
+import { FeatureFlagContext, UserSubscriptionContext, CurrentUserContext, AnalyticsContext, AssetSortingContext, ConfirmationDialogContext, EnvironmentContext, ErrorHandlingContext, ExportDataContext, FilterBarContext, GeolocationContext, TokenContext, ModalDialogContext, NavigationContext, OemBrandingContext, TimeRangeContext, ToastContext, CurrentUserPreferenceContext, WidgetConfigContext } from '@trackunit/react-core-contexts-api';
 import { isEqual } from 'es-toolkit';
 import { AssetRuntime, CustomerRuntime, EventRuntime, ParamsRuntime, SiteRuntime, WidgetConfigRuntime } from '@trackunit/iris-app-runtime-core';
 import { z } from 'zod';
 
+/**
+ * This is a hook to use the FeatureFlagContext.
+ *
+ * @requires FeatureFlagContext
+ * @example
+ * import { useFeatureFlags } from "@trackunit/react-core-hooks";
+ * const { flags } = useFeatureFlags();
+ * // use flags to control visibility/access ...
+ * @see (@link FeatureFlagContext)
+ */
+const useFeatureFlags = () => {
+    const context = useContext(FeatureFlagContext);
+    if (!context) {
+        throw new Error("useFeatureFlags must be used within a FeatureFlagContext");
+    }
+    return context;
+};
+
+/**
+ * This is a hook to use the UserSubscriptionContext.
+ *
+ * @requires UserSubscriptionContext
+ * @example
+ * import { useUserSubscription } from "@trackunit/react-core-hooks";
+ * const { numberOfDaysWithAccessToHistoricalData, packageType } = useUserSubscription();
+ * // use it for something
+ * const data = fetchData(numberOfDaysWithAccessToHistoricalData)
+ * @see { UserSubscription}
+ */
+const useUserSubscription = () => {
+    const context = useContext(UserSubscriptionContext);
+    if (!context) {
+        throw new Error("useUserSubscription must be used within the UserSubscriptionContext");
+    }
+    return context;
+};
+
+/**
+ * Hook providing the authenticated user's profile, account, and permission data
+ * from the CurrentUserContext.
+ *
+ * ### When to use
+ * Use `useCurrentUser` when you need the user's identity or account context — displaying
+ * the user's name, resolving the effective account ID, or branching logic based on
+ * `isAssuming` or `isTrackunitUser`.
+ *
+ * ### When not to use
+ * - If you only need a boolean check for a single permission — use `useUserPermission`.
+ * - To gate entire routes — prefer server-side access control or `hasAccessTo` from
+ *   `useNavigateInHost`.
+ *
+ * @example
+ * import { useCurrentUser } from "@trackunit/react-core-hooks";
+ * const { assumedUser, accountId } = useCurrentUser();
+ *
+ * const { data, loading } = useGetAccountByIdQuery({
+ *    variables: { accountId: assumedUser?.accountId || accountId || "" },
+ * });
+ * @see { CurrentUserContext}
+ */
+const useCurrentUser = () => {
+    const context = useContext(CurrentUserContext);
+    if (!context) {
+        throw new Error("useCurrentUser must be used within the CurrentUserProvider");
+    }
+    return context;
+};
+
+/**
+ * Async wrapper around {@link useValidateAccess}. Each helper awaits until the
+ * underlying user, subscription, and feature-flag data has finished loading
+ * before resolving, so callers such as router guards can check access without
+ * having to observe the synchronous `loading` flag themselves.
+ */
+const useValidateAccessAsync = () => {
+    const { hasAccessTo, hasFeatureFlag, hasPermission, loading } = useValidateAccess();
+    const hasAccessToRef = useRef(hasAccessTo);
+    hasAccessToRef.current = hasAccessTo;
+    const hasFeatureFlagRef = useRef(hasFeatureFlag);
+    hasFeatureFlagRef.current = hasFeatureFlag;
+    const hasPermissionRef = useRef(hasPermission);
+    hasPermissionRef.current = hasPermission;
+    const loadingRef = useRef(loading);
+    loadingRef.current = loading;
+    return useMemo(() => {
+        const waitForLoading = async () => {
+            if (loadingRef.current) {
+                await new Promise(resolve => {
+                    const intervalId = setInterval(() => {
+                        if (!loadingRef.current) {
+                            clearInterval(intervalId);
+                            resolve();
+                        }
+                    }, 10);
+                });
+            }
+        };
+        return {
+            hasAccessTo: async (requiredAccessTo) => {
+                await waitForLoading();
+                return hasAccessToRef.current(requiredAccessTo);
+            },
+            hasFeatureFlag: async (flag) => {
+                await waitForLoading();
+                return hasFeatureFlagRef.current(flag);
+            },
+            hasPermission: async (permission) => {
+                await waitForLoading();
+                return hasPermissionRef.current(permission);
+            },
+        };
+    }, [loadingRef, hasAccessToRef, hasFeatureFlagRef, hasPermissionRef]);
+};
+/**
+ * Synchronously evaluates the current user's access via subscription features,
+ * feature flags, and permissions. Returns predicate helpers plus a `loading`
+ * flag that stays true until user, subscription, and flag data are all present.
+ */
+const useValidateAccess = () => {
+    const { isAuthenticated, permissions: userPermissions } = useCurrentUser();
+    const { features, loading: featuresLoading } = useUserSubscription();
+    const { flags: allFlags } = useFeatureFlags();
+    const loading = useMemo(() => allFlags === null || featuresLoading || !userPermissions, [allFlags, featuresLoading, userPermissions]);
+    const hasFeatureFlag = useCallback((flag) => {
+        return allFlags?.find(({ key }) => key === flag)?.state ?? null;
+    }, [allFlags]);
+    const hasAccessTo = useCallback((requiredAccessTo) => {
+        if (isAuthenticated) {
+            return hasAccessToFeature(features, requiredAccessTo);
+        }
+        return false;
+    }, [features, isAuthenticated]);
+    const hasPermission = useCallback((permission) => {
+        if (isAuthenticated) {
+            return userPermissions?.includes(permission) ?? false;
+        }
+        return false;
+    }, [isAuthenticated, userPermissions]);
+    return useMemo(() => {
+        return {
+            hasAccessTo,
+            hasFeatureFlag,
+            hasPermission,
+            loading,
+        };
+    }, [hasAccessTo, hasFeatureFlag, hasPermission, loading]);
+};
+const hasAccessToFeature = (myFeatures, feature) => {
+    return myFeatures?.some(x => x.id === feature) ?? null;
+};
+
 /**
  * Hook to get the analytics context.
  *
@@ -217,21 +368,39 @@ const useExportDataContext = () => {
 };
 
 /**
- * This is a hook to use the FeatureFlagContext.
+ * Reads a host feature flag by key.
+ *
+ * Return values:
+ * - `null` while the host feature flags have not loaded yet.
+ * - the flag's boolean `state` when the flag exists in the loaded set.
+ * - `null` when the flags are loaded but the requested flag is not present,
+ *   unless `options.defaultValueWhenMissing` is provided, in which case that
+ *   value is returned.
+ *
+ * The hook is generic so callers can narrow the accepted key. Internal callers
+ * pass the strongly-typed `Flag` union for type safety, e.g.
+ * `useHostFeatureFlag<Flag>(Flags.SOME_FLAG, { defaultValueWhenMissing: true })`.
+ * External callers may pass any string.
+ *
+ * Must be used within a `FeatureFlagContext` (provided by `TrackunitProviders`).
  *
- * @requires FeatureFlagContext
  * @example
- * import { useFeatureFlags } from "@trackunit/react-core-hooks";
- * const { flags } = useFeatureFlags();
- * // use flags to control visibility/access ...
- * @see (@link FeatureFlagContext)
+ * import { useHostFeatureFlag } from "@trackunit/react-core-hooks";
+ * const isEnabled = useHostFeatureFlag("my_flag", { defaultValueWhenMissing: true });
+ * @see useFeatureFlags
  */
-const useFeatureFlags = () => {
-    const context = useContext(FeatureFlagContext);
-    if (!context) {
-        throw new Error("useFeatureFlags must be used within a FeatureFlagContext");
-    }
-    return context;
+const useHostFeatureFlag = (flag, options) => {
+    const { flags } = useFeatureFlags();
+    return useMemo(() => {
+        const found = flags?.find(({ key }) => key === flag);
+        if (found) {
+            return found.state;
+        }
+        if (flags && options.defaultValueWhenMissing !== undefined) {
+            return options.defaultValueWhenMissing;
+        }
+        return null;
+    }, [flags, flag, options.defaultValueWhenMissing]);
 };
 
 /**
@@ -894,25 +1063,6 @@ const useSiteRuntime = () => {
     return useMemo(() => ({ siteInfo, loading, error }), [siteInfo, loading, error]);
 };
 
-/**
- * This is a hook to use the UserSubscriptionContext.
- *
- * @requires UserSubscriptionContext
- * @example
- * import { useUserSubscription } from "@trackunit/react-core-hooks";
- * const { numberOfDaysWithAccessToHistoricalData, packageType } = useUserSubscription();
- * // use it for something
- * const data = fetchData(numberOfDaysWithAccessToHistoricalData)
- * @see { UserSubscription}
- */
-const useUserSubscription = () => {
-    const context = useContext(UserSubscriptionContext);
-    if (!context) {
-        throw new Error("useUserSubscription must be used within the UserSubscriptionContext");
-    }
-    return context;
-};
-
 /**
  * This is a hook to use the TimeRangeProvider.
  *
@@ -958,37 +1108,6 @@ const useToast = () => {
     return toastContext;
 };
 
-/**
- * Hook providing the authenticated user's profile, account, and permission data
- * from the CurrentUserContext.
- *
- * ### When to use
- * Use `useCurrentUser` when you need the user's identity or account context — displaying
- * the user's name, resolving the effective account ID, or branching logic based on
- * `isAssuming` or `isTrackunitUser`.
- *
- * ### When not to use
- * - If you only need a boolean check for a single permission — use `useUserPermission`.
- * - To gate entire routes — prefer server-side access control or `hasAccessTo` from
- *   `useNavigateInHost`.
- *
- * @example
- * import { useCurrentUser } from "@trackunit/react-core-hooks";
- * const { assumedUser, accountId } = useCurrentUser();
- *
- * const { data, loading } = useGetAccountByIdQuery({
- *    variables: { accountId: assumedUser?.accountId || accountId || "" },
- * });
- * @see { CurrentUserContext}
- */
-const useCurrentUser = () => {
-    const context = useContext(CurrentUserContext);
-    if (!context) {
-        throw new Error("useCurrentUser must be used within the CurrentUserProvider");
-    }
-    return context;
-};
-
 /**
  * This is a hook providing the Current User language.
  *
@@ -1404,4 +1523,4 @@ const useWidgetConfig = () => {
     return result;
 };
 
-export { fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserFavoriteAdvancedSensors, useCurrentUserFavoriteInsights, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeFormat, useCurrentUserTimeZonePreference, useCustomerRuntime, useEnvironment, useErrorHandler, useErrorHandlerOrNull, useEventRuntime, useExportDataContext, useFeatureBranchQueryString, useFeatureFlags, useFilterBarContext, useGeolocation, useHasAccessTo, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useModalDialogContext, useNavigateInHost, useOemBrandingContext, useSettingsUtils, useSiteRuntime, useTimeRange, useToast, useToken, useUserPermission, useUserSubscription, useWidgetConfig, useWidgetConfigAsync };
+export { fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserFavoriteAdvancedSensors, useCurrentUserFavoriteInsights, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeFormat, useCurrentUserTimeZonePreference, useCustomerRuntime, useEnvironment, useErrorHandler, useErrorHandlerOrNull, useEventRuntime, useExportDataContext, useFeatureBranchQueryString, useFeatureFlags, useFilterBarContext, useGeolocation, useHasAccessTo, useHostFeatureFlag, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useModalDialogContext, useNavigateInHost, useOemBrandingContext, useSettingsUtils, useSiteRuntime, useTimeRange, useToast, useToken, useUserPermission, useUserSubscription, useValidateAccess, useValidateAccessAsync, useWidgetConfig, useWidgetConfigAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-core-hooks",
-  "version": "1.17.59-alpha-df0e8d549b3.0",
+  "version": "1.17.59",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,9 +8,9 @@
   },
   "dependencies": {
     "es-toolkit": "^1.39.10",
-    "@trackunit/iris-app-runtime-core": "1.17.54-alpha-df0e8d549b3.0",
-    "@trackunit/iris-app-runtime-core-api": "1.16.53-alpha-df0e8d549b3.0",
-    "@trackunit/react-core-contexts-api": "1.17.53-alpha-df0e8d549b3.0",
+    "@trackunit/iris-app-runtime-core": "1.17.54",
+    "@trackunit/iris-app-runtime-core-api": "1.16.53",
+    "@trackunit/react-core-contexts-api": "1.17.53",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/access/ExtensionRouterContext.d.ts

@@ -0,0 +1,6 @@
+import type { HasAccess, ValidateAccess } from "./useValidateAccessAsync";
+export interface ExtensionRouterContext {
+    hasAccessToRoute: (requiredAccessTo: ValidateAccess) => Promise<HasAccess>;
+    hasFeatureFlag: (flag: string) => Promise<HasAccess>;
+    hasPermission: (permission: string) => Promise<HasAccess>;
+}

package/src/access/useValidateAccessAsync.d.ts

@@ -0,0 +1,25 @@
+import { LegacyFeature } from "@trackunit/iris-app-runtime-core-api";
+export type HasAccess = boolean | null;
+export type ValidateAccess = LegacyFeature;
+/**
+ * Async wrapper around {@link useValidateAccess}. Each helper awaits until the
+ * underlying user, subscription, and feature-flag data has finished loading
+ * before resolving, so callers such as router guards can check access without
+ * having to observe the synchronous `loading` flag themselves.
+ */
+export declare const useValidateAccessAsync: () => {
+    hasAccessTo: (requiredAccessTo: ValidateAccess) => Promise<HasAccess>;
+    hasFeatureFlag: (flag: string) => Promise<HasAccess>;
+    hasPermission: (permission: string) => Promise<HasAccess>;
+};
+/**
+ * Synchronously evaluates the current user's access via subscription features,
+ * feature flags, and permissions. Returns predicate helpers plus a `loading`
+ * flag that stays true until user, subscription, and flag data are all present.
+ */
+export declare const useValidateAccess: () => {
+    hasAccessTo: (requiredAccessTo: ValidateAccess) => HasAccess;
+    hasFeatureFlag: (flag: string) => HasAccess;
+    hasPermission: (permission: string) => HasAccess;
+    loading: boolean;
+};

package/src/featureFlags/useHostFeatureFlag.d.ts

@@ -0,0 +1,34 @@
+export interface UseHostFeatureFlagOptions {
+    /**
+     * Value returned when the feature flags have loaded but the requested flag is
+     * not present in the loaded set. When omitted, a missing flag resolves to
+     * `null` (the historical behaviour).
+     *
+     * Note: this only applies once flags are loaded. While flags are still
+     * loading the hook always returns `null` regardless of this option.
+     */
+    defaultValueWhenMissing?: boolean;
+}
+/**
+ * Reads a host feature flag by key.
+ *
+ * Return values:
+ * - `null` while the host feature flags have not loaded yet.
+ * - the flag's boolean `state` when the flag exists in the loaded set.
+ * - `null` when the flags are loaded but the requested flag is not present,
+ *   unless `options.defaultValueWhenMissing` is provided, in which case that
+ *   value is returned.
+ *
+ * The hook is generic so callers can narrow the accepted key. Internal callers
+ * pass the strongly-typed `Flag` union for type safety, e.g.
+ * `useHostFeatureFlag<Flag>(Flags.SOME_FLAG, { defaultValueWhenMissing: true })`.
+ * External callers may pass any string.
+ *
+ * Must be used within a `FeatureFlagContext` (provided by `TrackunitProviders`).
+ *
+ * @example
+ * import { useHostFeatureFlag } from "@trackunit/react-core-hooks";
+ * const isEnabled = useHostFeatureFlag("my_flag", { defaultValueWhenMissing: true });
+ * @see useFeatureFlags
+ */
+export declare const useHostFeatureFlag: <TFlag extends string = string>(flag: TFlag, options: UseHostFeatureFlagOptions) => boolean | null;

package/src/index.d.ts

@@ -1,3 +1,6 @@
+export * from "./access/ExtensionRouterContext";
+export { useValidateAccess, useValidateAccessAsync } from "./access/useValidateAccessAsync";
+export type { ValidateAccess } from "./access/useValidateAccessAsync";
 export * from "./analytics/useAnalytics";
 export * from "./assetSorting/useAssetSorting";
 export * from "./confirmationDialog/useConfirmationDialog";
@@ -5,6 +8,7 @@ export * from "./environment/useEnvironment";
 export * from "./errorHandling/useErrorHandler";
 export * from "./exportData/useExportDataContext";
 export * from "./featureFlags/useFeatureFlags";
+export * from "./featureFlags/useHostFeatureFlag";
 export * from "./fetchAssetBlobUrl";
 export * from "./filterBar/useFilterBarContext";
 export * from "./geolocation/useGeolocation";