Files
HiveGrid-Wireframes/hivegrid-cloud/apps/web/app/modules/onboarding/services/step-registry/gating.server.ts
T

200 lines
6.8 KiB
TypeScript

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<Record<OnboardingStepGateSource, string>>;
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<boolean>;
readonly evaluateSubscriptionEntitlement?: (input: {
featureKey: string;
subscription?: SubscriptionEntitlementSubscription | null;
trial?: SubscriptionEntitlementTrialState | null;
}) => EntitlementDecision;
}
export interface OnboardingStepGateServiceLoaders {
readonly featureFlags?: () => Promise<Pick<Required<OnboardingStepGateServices>, "hasFeatureFlag">>;
readonly entitlements?: () => Promise<Pick<Required<OnboardingStepGateServices>, "evaluateSubscriptionEntitlement">>;
}
const defaultRedirectPaths = Object.freeze({
"feature-flag": "/feature-disabled",
plan: "plan-required",
} satisfies Record<OnboardingStepGateSource, string>);
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<EvaluateOnboardingStepGatesInput, "definitions"> & { step: OnboardingRegisteredStepDefinition }): Promise<OnboardingStepGateDecision> {
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<OnboardingStepGateDecision[]> {
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] : []));
}