Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,70 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import { featureKeys } from "@toolctrl/entitlements";
const dbMock = {
tenantProductConfiguration: {
findUnique: vi.fn(),
},
tenantFeatureOverride: {
findUnique: vi.fn(),
},
};
const getPermissionsByUserMock = vi.fn();
describe("resolveTenantProductAccess", () => {
beforeEach(() => {
vi.resetModules();
vi.clearAllMocks();
vi.doMock("~/utils/db.server", () => ({ db: dbMock }));
vi.doMock("~/utils/db/permissions/userRoles.db.server", () => ({ getPermissionsByUser: getPermissionsByUserMock }));
vi.doMock("~/utils/loaders.middleware", () => ({ getIsSuperAdminByUserId: vi.fn().mockResolvedValue(false) }));
dbMock.tenantProductConfiguration.findUnique.mockResolvedValue({ blueprintId: "crm-saas" });
dbMock.tenantFeatureOverride.findUnique.mockResolvedValue({ override: "inherit" });
getPermissionsByUserMock.mockResolvedValue(["app.settings.roles.set"]);
});
it(
"combines tenant blueprint config, custom plan features, tenant override, and tenant role permissions",
async () => {
const { resolveTenantProductAccess } = await import("./productAccess.server");
await expect(
resolveTenantProductAccess({
tenantId: "tenant_1",
userId: "user_1",
featureKey: featureKeys.workflowEngine,
subscription: {
products: [{ customEntitlementPlanId: "business", features: [] }],
},
}),
).resolves.toMatchObject({ allowed: true, reason: "monthly-remaining", limit: 10000 });
expect(dbMock.tenantProductConfiguration.findUnique).toHaveBeenCalledWith({
where: { tenantId: "tenant_1" },
select: { blueprintId: true },
});
expect(dbMock.tenantFeatureOverride.findUnique).toHaveBeenCalledWith({
where: { tenantId_featureKey: { tenantId: "tenant_1", featureKey: featureKeys.workflowEngine } },
select: { override: true },
});
expect(getPermissionsByUserMock).toHaveBeenCalledWith("user_1", "tenant_1");
},
15000,
);
it("lets tenant overrides disable toggleable features even when the plan allows them", async () => {
const { resolveTenantProductAccess } = await import("./productAccess.server");
dbMock.tenantFeatureOverride.findUnique.mockResolvedValue({ override: "disabled" });
await expect(
resolveTenantProductAccess({
tenantId: "tenant_1",
userId: "user_1",
featureKey: featureKeys.workflowEngine,
subscription: {
products: [{ customEntitlementPlanId: "business", features: [] }],
},
}),
).resolves.toMatchObject({ allowed: false, reason: "tenant-override-disabled" });
});
});
@@ -0,0 +1,107 @@
import { getDefaultProductBlueprint, getProductBlueprint, type ProductAccessDecision, type ProductBlueprintId, type TenantFeatureOverride } from "@toolctrl/entitlements";
import { redirect, type Params } from "react-router";
import { appTenantPlanRequiredPath } from "~/utils/app/AppTenantStatusPaths";
import { buildPermissionDeniedUrl } from "~/utils/helpers/.server/PermissionsService";
import { getIsSuperAdminByUserId } from "~/utils/loaders.middleware";
import { getTenantIdFromUrl } from "~/utils/services/.server/urlService";
import { getUserInfo } from "~/utils/session.server";
import { getActiveTenantSubscriptions } from "~/utils/services/.server/subscriptionService";
import { db } from "~/utils/db.server";
import { getPermissionsByUser } from "~/utils/db/permissions/userRoles.db.server";
import {
evaluateProductSubscriptionAccess,
type SubscriptionEntitlementSubscription,
} from "./subscriptionEntitlements.server";
export type ResolveTenantProductAccessInput = {
tenantId: string;
userId: string;
featureKey: string;
subscription?: SubscriptionEntitlementSubscription | null;
used?: number | null;
period?: string;
tenantRolePermissionNames?: readonly string[];
bypassTenantRolePermission?: boolean;
};
function normalizeTenantOverride(value: string | null | undefined): TenantFeatureOverride {
if (value === "enabled" || value === "disabled" || value === "inherit") {
return value;
}
return "inherit";
}
export async function resolveTenantProductAccess(input: ResolveTenantProductAccessInput): Promise<ProductAccessDecision> {
const [configuration, override, tenantRolePermissionNames, isSuperAdmin] = await Promise.all([
db.tenantProductConfiguration.findUnique({
where: { tenantId: input.tenantId },
select: { blueprintId: true },
}),
db.tenantFeatureOverride.findUnique({
where: { tenantId_featureKey: { tenantId: input.tenantId, featureKey: input.featureKey } },
select: { override: true },
}),
input.tenantRolePermissionNames ? Promise.resolve([...input.tenantRolePermissionNames]) : getPermissionsByUser(input.userId, input.tenantId),
input.bypassTenantRolePermission === undefined ? getIsSuperAdminByUserId(input.userId) : Promise.resolve(input.bypassTenantRolePermission),
]);
const blueprintId = (configuration?.blueprintId as ProductBlueprintId | undefined) ?? getDefaultProductBlueprint().id;
const rolePermissionNames = [...tenantRolePermissionNames];
if (isSuperAdmin || input.bypassTenantRolePermission) {
for (const permissionName of getProductBlueprint(blueprintId)?.features.map((feature) => feature.requiresTenantRolePermission).filter((value): value is string => Boolean(value)) ?? []) {
if (!rolePermissionNames.includes(permissionName)) {
rolePermissionNames.push(permissionName);
}
}
}
return evaluateProductSubscriptionAccess({
blueprintId,
featureKey: input.featureKey,
subscription: input.subscription,
used: input.used,
period: input.period,
tenantOverride: normalizeTenantOverride(override?.override),
tenantRolePermissionNames: rolePermissionNames,
});
}
export async function requireTenantProductAccess({
request,
params,
featureKey,
}: {
request: Request;
params: Params;
featureKey: string;
}): Promise<ProductAccessDecision> {
const tenantId = await getTenantIdFromUrl(params);
const userInfo = await getUserInfo(request);
if (!userInfo.userId) {
const searchParams = new URLSearchParams([["redirect", new URL(request.url).pathname]]);
throw redirect(`/login?${searchParams}`);
}
const subscription = await getActiveTenantSubscriptions(tenantId);
const decision = await resolveTenantProductAccess({
tenantId,
userId: userInfo.userId,
featureKey,
subscription,
});
if (decision.allowed) {
return decision;
}
if (decision.reason === "tenant-role-missing" && decision.requiredTenantRolePermission) {
throw redirect(
buildPermissionDeniedUrl({
permissionName: decision.requiredTenantRolePermission as never,
tenantId,
requestUrl: request.url,
})
);
}
throw redirect(appTenantPlanRequiredPath(params));
}
@@ -0,0 +1,255 @@
import { describe, expect, it } from "vitest";
import fs from "node:fs";
import path from "node:path";
import { featureKeys, productBlueprintIds } from "@toolctrl/entitlements";
import type { EntitlementDecisionReason } from "@toolctrl/entitlements";
import { DefaultFeatures } from "~/application/dtos/shared/DefaultFeatures";
import type { SubscriptionFeatureDto } from "~/application/dtos/subscriptions/SubscriptionFeatureDto";
import { SubscriptionFeatureLimitType } from "~/application/enums/subscriptions/SubscriptionFeatureLimitType";
import { evaluateProductSubscriptionAccess, evaluateSubscriptionEntitlement } from "./subscriptionEntitlements.server";
const stableReasonCodes = [
"included",
"not-included",
"max-remaining",
"max-exhausted",
"monthly-remaining",
"monthly-exhausted",
"unlimited",
"trial-active",
"trial-expired",
"missing-subscription",
"unknown-feature",
] as const satisfies readonly EntitlementDecisionReason[];
const apiFeature = {
order: 0,
title: "API access",
name: DefaultFeatures.API,
type: SubscriptionFeatureLimitType.INCLUDED,
value: 0,
accumulate: false,
};
const prioritySupportFeature = {
order: 1,
title: "Priority support",
name: DefaultFeatures.PrioritySupport,
type: SubscriptionFeatureLimitType.NOT_INCLUDED,
value: 0,
accumulate: false,
};
function subscriptionWithFeatures(...features: SubscriptionFeatureDto[]) {
return {
products: [{ features }],
};
}
describe("evaluateSubscriptionEntitlement", () => {
it("uses semantic translation keys for trial entitlement copy", () => {
const source = fs.readFileSync(path.resolve(process.cwd(), "apps/web/app/utils/entitlements/.server/subscriptionEntitlements.server.ts"), "utf8");
expect(source).toContain("entitlements.trial.access");
expect(source).not.toContain("ui.autogenerated");
});
it("allows active trial access without subscription products", () => {
expect(
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.API,
subscription: { products: [] },
trial: {
active: true,
period: "trial-day-7",
message: "Trial access",
},
})
).toEqual({
allowed: true,
reason: "trial-active",
featureKey: DefaultFeatures.API,
limitType: SubscriptionFeatureLimitType.INCLUDED,
period: undefined,
trialPeriod: "trial-day-7",
message: "Trial access",
});
});
it("denies expired trial access without a subscription", () => {
expect(
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.API,
subscription: null,
trial: {
active: false,
period: "trial-ended",
},
})
).toMatchObject({
allowed: false,
reason: "trial-expired",
featureKey: DefaultFeatures.API,
limitType: undefined,
trialPeriod: "trial-ended",
});
});
it("denies access when neither subscription nor trial exists", () => {
expect(
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.API,
subscription: { products: [] },
trial: null,
})
).toMatchObject({
allowed: false,
reason: "missing-subscription",
featureKey: DefaultFeatures.API,
limitType: undefined,
});
});
it("allows subscription product feature inclusion", () => {
expect(
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.API,
subscription: subscriptionWithFeatures(apiFeature),
})
).toEqual({
allowed: true,
reason: "included",
featureKey: DefaultFeatures.API,
limitType: SubscriptionFeatureLimitType.INCLUDED,
period: undefined,
message: undefined,
});
});
it("denies product features that are explicitly not included", () => {
expect(
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.PrioritySupport,
subscription: subscriptionWithFeatures(prioritySupportFeature),
message: "Upgrade required",
})
).toMatchObject({
allowed: false,
reason: "not-included",
featureKey: DefaultFeatures.PrioritySupport,
limitType: SubscriptionFeatureLimitType.NOT_INCLUDED,
message: "Upgrade required",
});
});
it("denies unknown features even with an active subscription and trial", () => {
expect(
evaluateSubscriptionEntitlement({
featureKey: "unknown-feature",
subscription: subscriptionWithFeatures(apiFeature),
trial: { active: true },
})
).toMatchObject({
allowed: false,
reason: "unknown-feature",
featureKey: "unknown-feature",
limitType: SubscriptionFeatureLimitType.INCLUDED,
});
});
it("keeps denied diagnostic serialization redacted", () => {
const decisions = [
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.API,
subscription: { products: [] },
trial: null,
}),
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.API,
subscription: null,
trial: { active: false, period: "trial-ended" },
}),
evaluateSubscriptionEntitlement({
featureKey: DefaultFeatures.PrioritySupport,
subscription: subscriptionWithFeatures(prioritySupportFeature),
}),
evaluateSubscriptionEntitlement({
featureKey: "unknown-feature",
subscription: subscriptionWithFeatures(apiFeature),
}),
];
const unsafeDiagnosticPattern = /tenant|customer|subscription id|user id|api key|secret|sk_[a-z0-9]/i;
for (const decision of decisions) {
expect(decision.allowed).toBe(false);
expect(JSON.stringify(decision)).not.toMatch(unsafeDiagnosticPattern);
}
});
it("keeps reason codes stable for app subscription consumers", () => {
expect(stableReasonCodes).toEqual([
"included",
"not-included",
"max-remaining",
"max-exhausted",
"monthly-remaining",
"monthly-exhausted",
"unlimited",
"trial-active",
"trial-expired",
"missing-subscription",
"unknown-feature",
]);
});
it("evaluates Product Core access through custom plan id, tenant override, and tenant role permissions", () => {
expect(
evaluateProductSubscriptionAccess({
blueprintId: productBlueprintIds.crmSaas,
featureKey: featureKeys.workflowEngine,
subscription: {
products: [
{
customEntitlementPlanId: "business",
features: [],
},
],
},
tenantRolePermissionNames: ["app.settings.roles.set"],
})
).toMatchObject({ allowed: true, reason: "monthly-remaining", limit: 10000 });
expect(
evaluateProductSubscriptionAccess({
blueprintId: productBlueprintIds.crmSaas,
featureKey: featureKeys.workflowEngine,
subscription: {
products: [
{
customEntitlementPlanId: "business",
features: [],
},
],
},
tenantOverride: "disabled",
tenantRolePermissionNames: ["app.settings.roles.set"],
})
).toMatchObject({ allowed: false, reason: "tenant-override-disabled" });
expect(
evaluateProductSubscriptionAccess({
blueprintId: productBlueprintIds.crmSaas,
featureKey: featureKeys.workflowEngine,
subscription: {
products: [
{
customEntitlementPlanId: "business",
features: [],
},
],
},
})
).toMatchObject({ allowed: false, reason: "tenant-role-missing", requiredTenantRolePermission: "app.settings.roles.set" });
});
});
@@ -0,0 +1,151 @@
import {
entitlementLimitTypes,
evaluateEntitlement,
evaluateProductAccess,
getDefaultProductBlueprint,
getStandardEntitlementPlan,
type EntitlementDecision,
type EntitlementLimitType,
type EvaluateEntitlementInput,
type ProductAccessDecision,
type ProductBlueprintId,
type TenantFeatureOverride,
} from "@toolctrl/entitlements";
import { DefaultFeatures } from "~/application/dtos/shared/DefaultFeatures";
import type { SubscriptionFeatureDto } from "~/application/dtos/subscriptions/SubscriptionFeatureDto";
import type { SubscriptionProductDto } from "~/application/dtos/subscriptions/SubscriptionProductDto";
import { SubscriptionFeatureLimitType } from "~/application/enums/subscriptions/SubscriptionFeatureLimitType";
import { t as i18nT } from "i18next";
export interface SubscriptionEntitlementTrialState {
readonly active: boolean;
readonly period?: string;
readonly message?: string;
}
export interface EvaluateSubscriptionEntitlementInput {
readonly featureKey: DefaultFeatures | string;
readonly subscription?: SubscriptionEntitlementSubscription | null;
readonly trial?: SubscriptionEntitlementTrialState | null;
readonly used?: number | null;
readonly period?: string;
readonly message?: string;
}
export interface EvaluateProductSubscriptionAccessInput extends EvaluateSubscriptionEntitlementInput {
readonly blueprintId?: ProductBlueprintId | string;
readonly tenantOverride?: TenantFeatureOverride;
readonly tenantRolePermissionNames?: readonly string[];
}
export interface SubscriptionEntitlementSubscription {
readonly products?: readonly SubscriptionEntitlementProduct[] | null;
}
export interface SubscriptionEntitlementProduct {
readonly features?: readonly SubscriptionFeatureDto[] | null;
readonly subscriptionProduct?: Pick<SubscriptionProductDto, "features"> | null;
readonly customEntitlementPlanId?: string | null;
}
const appLimitTypeToEntitlementLimitType = Object.freeze({
[SubscriptionFeatureLimitType.NOT_INCLUDED]: entitlementLimitTypes.notIncluded,
[SubscriptionFeatureLimitType.INCLUDED]: entitlementLimitTypes.included,
[SubscriptionFeatureLimitType.MONTHLY]: entitlementLimitTypes.monthly,
[SubscriptionFeatureLimitType.MAX]: entitlementLimitTypes.max,
[SubscriptionFeatureLimitType.UNLIMITED]: entitlementLimitTypes.unlimited,
} as const satisfies Record<SubscriptionFeatureLimitType, EntitlementLimitType>);
const defaultIncludedTrialFeature: SubscriptionFeatureDto = Object.freeze({
order: 0,
title: i18nT("entitlements.trial.access"),
name: DefaultFeatures.API,
type: SubscriptionFeatureLimitType.INCLUDED,
value: 0,
accumulate: false,
});
function getSubscriptionProductFeatures(product: SubscriptionEntitlementProduct): readonly SubscriptionFeatureDto[] {
return product.features ?? product.subscriptionProduct?.features ?? [];
}
function getCustomPlanFeature(product: SubscriptionEntitlementProduct, featureKey: string): SubscriptionFeatureDto | undefined {
if (!product.customEntitlementPlanId) {
return undefined;
}
const customPlan = getStandardEntitlementPlan(product.customEntitlementPlanId);
const assignment = customPlan?.features.find((feature) => feature.featureKey === featureKey);
if (!assignment) {
return undefined;
}
return {
order: assignment.order,
title: assignment.label,
name: assignment.featureKey,
type: assignment.limitType,
value: assignment.limit ?? 0,
accumulate: assignment.limitType === entitlementLimitTypes.monthly,
};
}
function findSubscriptionFeature(
products: readonly SubscriptionEntitlementProduct[] | null | undefined,
featureKey: string
): SubscriptionFeatureDto | undefined {
for (const product of products ?? []) {
const customFeature = getCustomPlanFeature(product, featureKey);
if (customFeature) {
return customFeature;
}
const feature = getSubscriptionProductFeatures(product).find((item) => item.name === featureKey);
if (feature) {
return feature;
}
}
return undefined;
}
function toEvaluateEntitlementInput({
featureKey,
subscription,
trial,
used,
period,
message,
}: EvaluateSubscriptionEntitlementInput): EvaluateEntitlementInput {
const products = subscription?.products ?? [];
const hasSubscription = products.length > 0;
const feature = findSubscriptionFeature(products, featureKey) ?? (trial?.active === true ? defaultIncludedTrialFeature : undefined);
return {
featureKey,
hasSubscription,
trialActive: hasSubscription ? undefined : trial?.active,
trialPeriod: hasSubscription ? undefined : trial?.period,
trialMessage: hasSubscription ? undefined : trial?.message,
limitType: feature ? appLimitTypeToEntitlementLimitType[feature.type] : undefined,
limit: feature?.value,
used,
period,
message,
};
}
export function evaluateSubscriptionEntitlement(input: EvaluateSubscriptionEntitlementInput): EntitlementDecision {
return evaluateEntitlement(toEvaluateEntitlementInput(input));
}
export function evaluateProductSubscriptionAccess(input: EvaluateProductSubscriptionAccessInput): ProductAccessDecision {
const entitlementInput = toEvaluateEntitlementInput(input);
return evaluateProductAccess({
blueprintId: input.blueprintId ?? getDefaultProductBlueprint().id,
featureKey: entitlementInput.featureKey,
hasSubscription: entitlementInput.hasSubscription ?? false,
limitType: entitlementInput.limitType,
limit: entitlementInput.limit,
used: entitlementInput.used,
period: entitlementInput.period,
tenantOverride: input.tenantOverride ?? "inherit",
tenantRolePermissionNames: input.tenantRolePermissionNames,
});
}