import type { Params } from "react-router"; import type { EntitlementDecision } from "@toolctrl/entitlements"; import type { SubscriptionEntitlementSubscription, SubscriptionEntitlementTrialState, } from "~/utils/entitlements/.server/subscriptionEntitlements.server"; import { evaluateSubscriptionEntitlement as defaultEvaluateSubscriptionEntitlement } from "~/utils/entitlements/.server/subscriptionEntitlements.server"; import { isFeatureFlagEnabled } from "~/utils/services/.server/featureFlagsRequest.server"; import { getDashboardModuleDefinitions, type DashboardModuleDefinition, type DashboardModuleId } from "./registry.server"; export type DashboardModuleGateSource = "feature-flag" | "plan"; export type DashboardModuleGateReason = "feature-disabled" | "feature-check-failed" | "plan-required"; export interface DashboardModuleGateDiagnostic { readonly moduleId: DashboardModuleId; readonly source: DashboardModuleGateSource; readonly reason: DashboardModuleGateReason; readonly redirectPath?: string; } export interface DashboardModuleGateDecision { readonly module: DashboardModuleDefinition; readonly allowed: boolean; readonly diagnostic?: DashboardModuleGateDiagnostic; } export interface EvaluateDashboardModuleGatesInput { readonly request: Request; readonly params: Params; readonly subscription?: SubscriptionEntitlementSubscription | null; readonly trial?: SubscriptionEntitlementTrialState | null; readonly definitions?: readonly DashboardModuleDefinition[]; readonly redirectPaths?: Partial>; readonly services?: DashboardModuleGateServices; readonly serviceLoaders?: DashboardModuleGateServiceLoaders; } export interface DashboardModuleGateServices { /** * Boolean feature-flag check shimmed against the v2 evaluator * (`isFeatureFlagEnabled`). Tests inject a stub; production wiring * resolves the request + tenant context inside the v2 helper. */ readonly hasFeatureFlag?: (input: { request: Request; params: Params; flagName: string }) => Promise; readonly evaluateSubscriptionEntitlement?: (input: { featureKey: string; subscription?: SubscriptionEntitlementSubscription | null; trial?: SubscriptionEntitlementTrialState | null; }) => EntitlementDecision; } export interface DashboardModuleGateServiceLoaders { readonly featureFlags?: () => Promise, "hasFeatureFlag">>; readonly entitlements?: () => Promise, "evaluateSubscriptionEntitlement">>; } const defaultRedirectPaths = Object.freeze({ "feature-flag": "/feature-disabled", plan: "plan-required", } satisfies Record); function diagnostic(input: { moduleId: DashboardModuleId; source: DashboardModuleGateSource; reason: DashboardModuleGateReason; redirectPath?: string; }): DashboardModuleGateDiagnostic { return { moduleId: input.moduleId, source: input.source, reason: input.reason, ...(input.redirectPath ? { redirectPath: input.redirectPath } : {}), }; } async function evaluateDashboardModuleGate({ module, request, params, subscription, trial, redirectPaths, services, serviceLoaders, }: Omit & { module: DashboardModuleDefinition }): Promise { if (module.featureFlagKey) { try { if (!services?.hasFeatureFlag) { const featureFlagService = serviceLoaders?.featureFlags ? await serviceLoaders.featureFlags() : { hasFeatureFlag: ({ request: req, params: p, flagName }: { request: Request; params: Params; flagName: string }) => isFeatureFlagEnabled(flagName, { request: req, params: p }) }; services = { ...services, hasFeatureFlag: featureFlagService.hasFeatureFlag }; } const hasFeatureFlag = services.hasFeatureFlag; if (!hasFeatureFlag) { throw new Error("Dashboard feature flag service unavailable"); } const enabled = await hasFeatureFlag({ request, params, flagName: module.featureFlagKey, }); if (!enabled) { return { module, allowed: false, diagnostic: diagnostic({ moduleId: module.id, source: "feature-flag", reason: "feature-disabled", redirectPath: redirectPaths?.["feature-flag"] ?? defaultRedirectPaths["feature-flag"], }), }; } } catch { return { module, allowed: false, diagnostic: diagnostic({ moduleId: module.id, source: "feature-flag", reason: "feature-check-failed", redirectPath: redirectPaths?.["feature-flag"] ?? defaultRedirectPaths["feature-flag"], }), }; } } if (module.planFeatureKey) { if (!services?.evaluateSubscriptionEntitlement) { const entitlementService = serviceLoaders?.entitlements ? await serviceLoaders.entitlements() : { evaluateSubscriptionEntitlement: defaultEvaluateSubscriptionEntitlement }; services = { ...services, evaluateSubscriptionEntitlement: entitlementService.evaluateSubscriptionEntitlement }; } const evaluateSubscriptionEntitlement = services.evaluateSubscriptionEntitlement; if (!evaluateSubscriptionEntitlement) { throw new Error("Dashboard entitlement service unavailable"); } const entitlement = evaluateSubscriptionEntitlement({ featureKey: module.planFeatureKey, subscription, trial, }); if (!entitlement.allowed) { return { module, allowed: false, diagnostic: diagnostic({ moduleId: module.id, source: "plan", reason: "plan-required", redirectPath: redirectPaths?.plan ?? defaultRedirectPaths.plan, }), }; } } return { module, allowed: true }; } export async function evaluateDashboardModuleGates({ request, params, subscription, trial, definitions = getDashboardModuleDefinitions(), redirectPaths, services, serviceLoaders, }: EvaluateDashboardModuleGatesInput): Promise { return Promise.all( definitions.map((module) => evaluateDashboardModuleGate({ module, request, params, subscription, trial, redirectPaths, services, serviceLoaders, }), ), ); } export function getVisibleDashboardModules(decisions: readonly DashboardModuleGateDecision[]): DashboardModuleDefinition[] { return decisions.filter((decision) => decision.allowed).map((decision) => decision.module); } export function getDashboardModuleDiagnostics(decisions: readonly DashboardModuleGateDecision[]): DashboardModuleGateDiagnostic[] { return decisions.flatMap((decision) => (decision.diagnostic ? [decision.diagnostic] : [])); }