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 { getOnboardingStepDefinitions, type OnboardingRegisteredStepDefinition, type OnboardingRegisteredStepId } from "./registry.server"; export type OnboardingStepGateSource = "feature-flag" | "plan"; export type OnboardingStepGateReason = "feature-disabled" | "feature-check-failed" | "plan-required"; export interface OnboardingStepGateDiagnostic { readonly stepId: OnboardingRegisteredStepId; readonly source: OnboardingStepGateSource; readonly reason: OnboardingStepGateReason; readonly redirectPath?: string; } export interface OnboardingStepGateDecision { readonly step: OnboardingRegisteredStepDefinition; readonly allowed: boolean; readonly diagnostic?: OnboardingStepGateDiagnostic; } export interface EvaluateOnboardingStepGatesInput { readonly request: Request; readonly params: Params; readonly subscription?: SubscriptionEntitlementSubscription | null; readonly trial?: SubscriptionEntitlementTrialState | null; readonly definitions?: readonly OnboardingRegisteredStepDefinition[]; readonly redirectPaths?: Partial>; readonly services?: OnboardingStepGateServices; readonly serviceLoaders?: OnboardingStepGateServiceLoaders; } export interface OnboardingStepGateServices { /** * Boolean feature-flag check shimmed against the v2 evaluator * (`isFeatureFlagEnabled`). Callers may inject a stub for tests; * 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 OnboardingStepGateServiceLoaders { readonly featureFlags?: () => Promise, "hasFeatureFlag">>; readonly entitlements?: () => Promise, "evaluateSubscriptionEntitlement">>; } const defaultRedirectPaths = Object.freeze({ "feature-flag": "/feature-disabled", plan: "plan-required", } satisfies Record); function diagnostic(input: { stepId: OnboardingRegisteredStepId; source: OnboardingStepGateSource; reason: OnboardingStepGateReason; redirectPath?: string; }): OnboardingStepGateDiagnostic { return { stepId: input.stepId, source: input.source, reason: input.reason, ...(input.redirectPath ? { redirectPath: input.redirectPath } : {}), }; } async function evaluateOnboardingStepGate({ step, request, params, subscription, trial, redirectPaths, services, serviceLoaders, }: Omit & { step: OnboardingRegisteredStepDefinition }): Promise { if (step.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("Onboarding feature flag service unavailable"); } const enabled = await hasFeatureFlag({ request, params, flagName: step.featureFlagKey, }); if (!enabled) { return { step, allowed: false, diagnostic: diagnostic({ stepId: step.id, source: "feature-flag", reason: "feature-disabled", redirectPath: redirectPaths?.["feature-flag"] ?? defaultRedirectPaths["feature-flag"], }), }; } } catch { return { step, allowed: false, diagnostic: diagnostic({ stepId: step.id, source: "feature-flag", reason: "feature-check-failed", redirectPath: redirectPaths?.["feature-flag"] ?? defaultRedirectPaths["feature-flag"], }), }; } } if (step.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("Onboarding entitlement service unavailable"); } const entitlement = evaluateSubscriptionEntitlement({ featureKey: step.planFeatureKey, subscription, trial, }); if (!entitlement.allowed) { return { step, allowed: false, diagnostic: diagnostic({ stepId: step.id, source: "plan", reason: "plan-required", redirectPath: redirectPaths?.plan ?? defaultRedirectPaths.plan, }), }; } } return { step, allowed: true }; } export async function evaluateOnboardingStepGates({ request, params, subscription, trial, definitions = getOnboardingStepDefinitions(), redirectPaths, services, serviceLoaders, }: EvaluateOnboardingStepGatesInput): Promise { return Promise.all( definitions.map((step) => evaluateOnboardingStepGate({ step, request, params, subscription, trial, redirectPaths, services, serviceLoaders, }), ), ); } export function getVisibleOnboardingSteps(decisions: readonly OnboardingStepGateDecision[]): OnboardingRegisteredStepDefinition[] { return decisions.filter((decision) => decision.allowed).map((decision) => decision.step); } export function getOnboardingStepDiagnostics(decisions: readonly OnboardingStepGateDecision[]): OnboardingStepGateDiagnostic[] { return decisions.flatMap((decision) => (decision.diagnostic ? [decision.diagnostic] : [])); }