Feature Checker Service Reference

Service Overview

The Feature Checker service evaluates feature values at runtime. Every method enforces the hierarchy:

subscription override → plan value → feature default

The service answers questions at both subscription and customer levels, exposes plan-access helpers, and can summarize usage patterns. Results draw from FeatureValueResolver, so the hierarchy is consistent everywhere.

Accessing the Service

import { Subscrio } from '@subscrio/core';

const subscrio = new Subscrio({ database: { connectionString: process.env.DATABASE_URL! } });
const featureChecker = subscrio.featureChecker;

Method Catalog

Method Reference

getValueForSubscription

Description

Resolves a feature value for a single subscription using override → plan value → feature default precedence.

Signature

getValueForSubscription<T = string>(
  subscriptionKey: string,
  featureKey: string,
  defaultValue?: T
): Promise<T | null>

Inputs

Returns

Promise<T | null> – resolved value (cast to T when provided) or defaultValue ?? null.

Expected Results

• Loads subscription, plan, and feature.
• Applies resolver hierarchy; if any entity is missing returns fallback rather than throwing.

Potential Errors

• None.

Example

const seats = await featureChecker.getValueForSubscription<number>(
  'sub_1001',
  'seat-limit',
  0
);

isEnabledForSubscription

Description

Convenience helper for toggle features at the subscription level.

Signature

isEnabledForSubscription(subscriptionKey: string, featureKey: string): Promise<boolean>

Returns

Promise<boolean> – true when the resolved value equals 'true' (case-insensitive).

Example

const hasBranding = await featureChecker.isEnabledForSubscription(
  'sub_enterprise',
  'custom-branding'
);

getAllFeaturesForSubscription

Description

Resolves every feature for the subscription’s product, returning a map of featureKey → value.

Signature

getAllFeaturesForSubscription(subscriptionKey: string): Promise<Map<string, string>>

Inputs

Returns

Promise<Map<string, string>>

Expected Results

• Loads subscription, plan, and product, then queries all product features.
• Resolves each feature via the hierarchy and populates the map.
• Returns empty map when the plan cannot be resolved.

Potential Errors

Example

const resolved = await featureChecker.getAllFeaturesForSubscription('sub_1001');
console.log(resolved.get('max-projects'));

getValueForCustomer

Description

Resolves a feature for a customer/product pair by scanning active/trial subscriptions (up to MAX_SUBSCRIPTIONS_PER_CUSTOMER).

Signature

getValueForCustomer<T = string>(
  customerKey: string,
  productKey: string,
  featureKey: string,
  defaultValue?: T
): Promise<T | null>

Inputs

Returns

Promise<T | null>

Expected Results

• Loads customer, product, and feature; returns fallback when any missing.
• Fetches subscriptions for the customer, filters to active/trial entries for the product.
• Applies resolver across subscriptions, honoring override precedence if multiple subscriptions exist.

Potential Errors

• None.

Example

const maxProjects = await featureChecker.getValueForCustomer<number>(
  'acme-corp',
  'projecthub',
  'max-projects',
  0
);

isEnabledForCustomer

Description

Boolean helper that wraps getValueForCustomer.

Signature

isEnabledForCustomer(
  customerKey: string,
  productKey: string,
  featureKey: string
): Promise<boolean>

Returns

Promise<boolean> – true when the resolved value equals 'true'.

Example

const hasApiAccess = await featureChecker.isEnabledForCustomer(
  'acme-corp',
  'projecthub',
  'api-access'
);

getAllFeaturesForCustomer

Description

Aggregates every feature value for a customer/product pair by considering all active/trial subscriptions.

Signature

getAllFeaturesForCustomer(
  customerKey: string,
  productKey: string
): Promise<Map<string, string>>

Inputs

Returns

Promise<Map<string, string>> – defaults when no matching subscriptions exist.

Expected Results

• Loads customer/product; returns empty map when either missing.
• Resolves all product features using the resolver across relevant subscriptions.

Potential Errors

• None.

Example

const customerFeatures = await featureChecker.getAllFeaturesForCustomer(
  'acme-corp',
  'projecthub'
);

hasPlanAccess

Description

Checks whether a customer currently holds an active or trial subscription for a given plan.

Signature

hasPlanAccess(
  customerKey: string,
  productKey: string,
  planKey: string
): Promise<boolean>

Inputs

Returns

Promise<boolean> – false when customer/product/plan missing or no qualifying subscription is found.

Expected Results

• Validates all entities exist.
• Loads subscriptions for the customer and searches for an active/trial entry referencing the plan.

Potential Errors

• None.

Example

const hasPro = await featureChecker.hasPlanAccess('acme-corp', 'projecthub', 'professional');

getActivePlans

Description

Lists plan keys for every active/trial subscription held by a customer (across all products).

Signature

getActivePlans(customerKey: string): Promise<string[]>

Inputs

Returns

Promise<string[]> – empty array when customer missing or no active/trial subscriptions exist.

Expected Results

• Loads customer and their subscriptions.
• Batch-fetches plans to avoid N+1 queries and returns plan keys.

Example

const plans = await featureChecker.getActivePlans('acme-corp');

getFeatureUsageSummary

Description

Produces a usage rollup showing how features resolve (enabled/disabled/numeric/text) for a customer/product pair and includes the customer’s subscription count.

Signature

getFeatureUsageSummary(
  customerKey: string,
  productKey: string
): Promise<{
  activeSubscriptions: number;
  enabledFeatures: string[];
  disabledFeatures: string[];
  numericFeatures: Map<string, number>;
  textFeatures: Map<string, string>;
}>

Inputs

Returns

Object containing counts and maps classified by feature type.

Expected Results

• Counts the customer’s subscriptions (regardless of product filter).
• Resolves all product features (using defaults when customer/product missing) and classifies values by FeatureDto.valueType.

Potential Errors

• None.

Example

const summary = await featureChecker.getFeatureUsageSummary('acme-corp', 'projecthub');
console.log(summary.enabledFeatures);

Related Workflows

• Products must associate features and plans must set feature values for meaningful results; otherwise values fall back to feature defaults.
• Subscription-level overrides come from SubscriptionManagementService.addFeatureOverride.
• Cache high-traffic queries such as getAllFeaturesForCustomer to avoid recalculating the same maps repeatedly.