@m6d/cerebro 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# Cerebro JavaScript SDK
+
+Reusable frontend licensing primitives for JavaScript/TypeScript clients.
+
+## What This SDK Covers
+
+The SDK focuses on generic client-side licensing patterns.
+
+It provides framework-agnostic building blocks for:
+
+- Loading licensed features and checking feature availability
+- Evaluating route access constraints (features only)
+- Filtering navigation trees by access requirements
+
+## Install
+
+```bash
+bun add @m6d/cerebro
+```
+
+For local development in this repository:
+
+```bash
+bun install
+```
+
+## Development Scripts
+
+```bash
+bun lint
+bun check
+bun test
+bun run build
+bun run sample:feature-store
+```
+
+## CI/CD and Publishing
+
+- PRs targeting `main` run quality checks via `.github/workflows/pr-checks.yml`
+- Pushes to `main` run semantic-release via `.github/workflows/release.yml`
+- Releases use npm trusted publishing (OIDC), not long-lived npm tokens
+
+To enable trusted publishing for `@m6d/cerebro`:
+
+1. Open the package settings on npmjs.com for `@m6d/cerebro`
+2. Add a Trusted Publisher for GitHub Actions
+3. Set Organization/User, Repository, and workflow filename to `release.yml`
+4. Ensure publishes run on GitHub-hosted runners (this workflow uses `ubuntu-latest`)
+
+## Documentation
+
+- `docs/README.md`
+- `docs/licensing/README.md`
+- `docs/routing/README.md`
+
+## Samples
+
+- `samples/README.md`
+- `samples/vanilla-feature-store-sample/README.md`
+
+## Generic Example
+
+```ts
+import {
+  createFeatureStore,
+  createLicenseFeatureLoader,
+  evaluateRouteAccess,
+} from "@m6d/cerebro";
+
+const featureStore = createFeatureStore({
+  loadFeatures: createLicenseFeatureLoader({
+    url: "https://example.com/licenses/features",
+  }),
+});
+
+await featureStore.load();
+
+const decision = evaluateRouteAccess(
+  {
+    featureIds: ["kpis", "plans"],
+  },
+  {
+    features: featureStore.getState().features,
+  },
+);
+
+if (!decision.allowed) {
+  console.log("Blocked", decision.reason, decision);
+}
+```
+
+## Use Cases Coverage
+
+These are common licensing use cases and how they map to this SDK:
+
+- Route feature guard (`featureIds`) -> `evaluateRouteAccess(...)` or `canAccessRoute(...)`
+- Filtering navigation/app lists by licensed modules -> `filterAccessibleItems(...)`
+- Inline checks inside components/pages -> `featureStore.hasFeature(...)`, `featureStore.hasAnyFeature(...)`, `hasFeature(...)`
+- Bootstrapping and refreshing licensed features -> `createLicenseFeatureLoader(...)` + `featureStore.load()`
+
+This SDK intentionally does not include permission logic, notifications, router bindings, or framework-specific state wrappers.
+
+## Angular Example
+
+```ts
+// app/core/licensing.service.ts
+import { Injectable } from "@angular/core";
+import {
+  createFeatureStore,
+  createLicenseFeatureLoader,
+  evaluateRouteAccess,
+} from "@m6d/cerebro";
+
+@Injectable({ providedIn: "root" })
+export class LicensingService {
+  private featureStore = createFeatureStore({
+    loadFeatures: createLicenseFeatureLoader({
+      url: "/licenses/features",
+      credentials: "include",
+    }),
+  });
+
+  async init() {
+    await this.featureStore.load();
+  }
+
+  hasFeature(featureId: string) {
+    return this.featureStore.hasFeature(featureId);
+  }
+
+  canAccess(featureIds: readonly string[]) {
+    return evaluateRouteAccess(
+      { featureIds },
+      { features: this.featureStore.getState().features },
+    ).allowed;
+  }
+}
+```
+
+```ts
+// app/core/feature.guard.ts
+import { inject } from "@angular/core";
+import { CanActivateFn } from "@angular/router";
+import { LicensingService } from "./licensing.service";
+
+export const featureGuard: CanActivateFn = (route) => {
+  const licensing = inject(LicensingService);
+  const featureIds = (route.data?.["featureIds"] as string[] | undefined) ?? [];
+  return licensing.canAccess(featureIds);
+};
+```
+
+```ts
+// app/app.config.ts (or APP_INITIALIZER module setup)
+import { APP_INITIALIZER } from "@angular/core";
+import { LicensingService } from "./core/licensing.service";
+
+export const licensingInitializer = {
+  provide: APP_INITIALIZER,
+  multi: true,
+  deps: [LicensingService],
+  useFactory: (licensing: LicensingService) => () => licensing.init(),
+};
+```
+
+## React Example
+
+```tsx
+import {
+  createFeatureStore,
+  createLicenseFeatureLoader,
+  evaluateRouteAccess,
+} from "@m6d/cerebro";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from "react";
+
+const featureStore = createFeatureStore({
+  loadFeatures: createLicenseFeatureLoader({
+    url: "/licenses/features",
+    credentials: "include",
+  }),
+});
+
+type LicensingContextValue = {
+  features: string[];
+  isLoading: boolean;
+  hasFeature: (featureId: string) => boolean;
+  canAccess: (featureIds: readonly string[]) => boolean;
+};
+
+const LicensingContext = createContext<LicensingContextValue | null>(null);
+
+export function LicensingProvider({ children }: { children: React.ReactNode }) {
+  const state = useSyncExternalStore(
+    featureStore.subscribe,
+    featureStore.getState,
+  );
+
+  useEffect(() => {
+    featureStore.load().catch(() => undefined);
+  }, []);
+
+  const value = useMemo<LicensingContextValue>(() => {
+    return {
+      features: state.features,
+      isLoading: state.isLoading,
+      hasFeature: (featureId) => featureStore.hasFeature(featureId),
+      canAccess: (featureIds) => {
+        return evaluateRouteAccess({ featureIds }, { features: state.features })
+          .allowed;
+      },
+    };
+  }, [state.features, state.isLoading]);
+
+  return <LicensingContext value={value}>{children}</LicensingContext>;
+}
+
+export function useLicensing() {
+  const value = useContext(LicensingContext);
+  if (!value) {
+    throw new Error("useLicensing must be used inside <LicensingProvider>");
+  }
+  return value;
+}
+```
+
+```tsx
+// any component
+import { useLicensing } from "./licensing-context";
+
+function KpiPage() {
+  const licensing = useLicensing();
+
+  if (!licensing.canAccess(["kpis"])) {
+    return <div>Feature not available in your license.</div>;
+  }
+
+  return <div>KPI content</div>;
+}
+```
+
+## Notes
+
+- Response parsers support both direct payloads and `Result<T>`-style payloads (`{ extra: ... }`)
+- Feature checks default to case-insensitive matching
+- Route `featureIds` default to `any` mode

package/dist/access/navigation.d.ts

@@ -0,0 +1,21 @@
+import { type RouteAccessContext, type RouteAccessRequirement } from "./route-access";
+/**
+ * Navigation item shape that supports feature-gated filtering.
+ */
+export type AccessControlledItem = RouteAccessRequirement & {
+    /** Child items that should be recursively filtered. */
+    children?: readonly AccessControlledItem[];
+    /** Additional consumer-defined fields. */
+    [key: string]: unknown;
+};
+/**
+ * Options used while filtering navigation items.
+ */
+export type FilterAccessibleItemsOptions = RouteAccessContext & {
+    /** Keep a parent item visible when any child remains visible. Defaults to `true`. */
+    keepParentWhenAnyChildAccessible?: boolean;
+};
+/**
+ * Filters a navigation tree and keeps only accessible items.
+ */
+export declare const filterAccessibleItems: (items: readonly AccessControlledItem[], options?: FilterAccessibleItemsOptions) => AccessControlledItem[];

package/dist/access/route-access.d.ts

@@ -0,0 +1,45 @@
+import { type AccessRequirementMode } from "../internal/access-keys";
+import { type FeatureCheckOptions } from "../licensing/feature-utils";
+/**
+ * Feature constraints attached to a route-like object.
+ */
+export type RouteAccessRequirement = {
+    /** Feature codes required for this route. */
+    featureIds?: readonly string[];
+    /** Matching strategy for `featureIds`. Defaults to `any`. */
+    featureMode?: AccessRequirementMode;
+};
+/**
+ * Runtime values used when evaluating route access.
+ */
+export type RouteAccessContext = FeatureCheckOptions & {
+    /** Active feature list for the current license/session. */
+    features?: readonly string[];
+};
+/**
+ * Result returned by route access evaluators.
+ */
+export type RouteAccessDecision = {
+    /** Whether access is granted. */
+    allowed: boolean;
+    /** Primary reason that explains the decision. */
+    reason: "allowed" | "missing_feature";
+    /** Missing required features when denied. */
+    missingFeatures: string[];
+};
+/**
+ * Evaluates feature access for a single route requirement.
+ */
+export declare const evaluateRouteAccess: (requirement: RouteAccessRequirement, context?: RouteAccessContext) => {
+    allowed: false;
+    reason: "missing_feature";
+    missingFeatures: string[];
+} | {
+    allowed: true;
+    reason: "allowed";
+    missingFeatures: never[];
+};
+/**
+ * Convenience wrapper that only returns a boolean decision.
+ */
+export declare const canAccessRoute: (requirement: RouteAccessRequirement, context?: RouteAccessContext) => boolean;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { filterAccessibleItems, type AccessControlledItem, type FilterAccessibleItemsOptions, } from "./access/navigation";
+export { canAccessRoute, evaluateRouteAccess, type RouteAccessContext, type RouteAccessDecision, type RouteAccessRequirement, } from "./access/route-access";
+export { createLicenseFeatureLoader, defaultLicenseFeatureResponseParser, type CreateLicenseFeatureLoaderOptions, type LicenseFeatureResponseParser, } from "./licensing/feature-http-loader";
+export { createFeatureStore, type CreateFeatureStoreOptions, type FeatureStoreState, } from "./licensing/feature-store";
+export { getMissingFeatures, hasAllFeatures, hasAnyFeature, hasFeature, hasFeatures, normalizeFeatureList, type FeatureCheckOptions, type FeatureRequirementOptions, } from "./licensing/feature-utils";
+export { type AccessRequirementMode } from "./internal/access-keys";

package/dist/index.js

@@ -0,0 +1,381 @@
+// src/internal/access-keys.ts
+var normalizeAccessKey = (rawValue, options = {}) => {
+  const trimmedValue = rawValue.trim();
+  if (trimmedValue.length === 0) {
+    return "";
+  }
+  if (options.caseSensitive) {
+    return trimmedValue;
+  }
+  return trimmedValue.toLowerCase();
+};
+var normalizeAccessKeys = (rawValues, options = {}) => {
+  const dedupedValues = new Set;
+  for (const rawValue of rawValues) {
+    const normalizedValue = normalizeAccessKey(rawValue, options);
+    if (normalizedValue.length === 0) {
+      continue;
+    }
+    dedupedValues.add(normalizedValue);
+  }
+  return Array.from(dedupedValues);
+};
+var createAccessLookup = (rawValues, options = {}) => {
+  return new Set(normalizeAccessKeys(rawValues, options));
+};
+var hasAccessKey = (rawValues, targetValue, options = {}) => {
+  const normalizedTargetValue = normalizeAccessKey(targetValue, options);
+  if (normalizedTargetValue.length === 0) {
+    return false;
+  }
+  const lookup = createAccessLookup(rawValues, options);
+  return lookup.has(normalizedTargetValue);
+};
+var getMissingAccessKeys = (rawValues, requiredValues, options = {}) => {
+  const lookup = createAccessLookup(rawValues, options);
+  const normalizedRequiredValues = normalizeAccessKeys(requiredValues, options);
+  return normalizedRequiredValues.filter((requiredValue) => {
+    return !lookup.has(requiredValue);
+  });
+};
+
+// src/licensing/feature-utils.ts
+var normalizeFeatureList = (features, options = {}) => {
+  return normalizeAccessKeys(features, options);
+};
+var hasFeature = (features, requiredFeature, options = {}) => {
+  return hasAccessKey(features, requiredFeature, options);
+};
+var hasAnyFeature = (features, requiredFeatures, options = {}) => {
+  const normalizedRequiredFeatures = normalizeAccessKeys(requiredFeatures, options);
+  if (normalizedRequiredFeatures.length === 0) {
+    return true;
+  }
+  const lookup = createAccessLookup(features, options);
+  return normalizedRequiredFeatures.some((requiredFeature) => {
+    return lookup.has(requiredFeature);
+  });
+};
+var hasAllFeatures = (features, requiredFeatures, options = {}) => {
+  const normalizedRequiredFeatures = normalizeAccessKeys(requiredFeatures, options);
+  if (normalizedRequiredFeatures.length === 0) {
+    return true;
+  }
+  const lookup = createAccessLookup(features, options);
+  return normalizedRequiredFeatures.every((requiredFeature) => {
+    return lookup.has(requiredFeature);
+  });
+};
+var hasFeatures = (features, requiredFeatures, options = {}) => {
+  if ((options.mode ?? "all") === "any") {
+    return hasAnyFeature(features, requiredFeatures, options);
+  }
+  return hasAllFeatures(features, requiredFeatures, options);
+};
+var getMissingFeatures = (features, requiredFeatures, options = {}) => {
+  return getMissingAccessKeys(features, requiredFeatures, options);
+};
+
+// src/access/route-access.ts
+var evaluateRouteAccess = (requirement, context = {}) => {
+  const features = context.features ?? [];
+  const requiredFeatureIds = requirement.featureIds ?? [];
+  if (requiredFeatureIds.length > 0) {
+    const isFeatureAccessAllowed = hasFeatures(features, requiredFeatureIds, {
+      caseSensitive: context.caseSensitive,
+      mode: requirement.featureMode ?? "any"
+    });
+    if (!isFeatureAccessAllowed) {
+      return {
+        allowed: false,
+        reason: "missing_feature",
+        missingFeatures: getMissingFeatures(features, requiredFeatureIds, {
+          caseSensitive: context.caseSensitive
+        })
+      };
+    }
+  }
+  return {
+    allowed: true,
+    reason: "allowed",
+    missingFeatures: []
+  };
+};
+var canAccessRoute = (requirement, context = {}) => {
+  return evaluateRouteAccess(requirement, context).allowed;
+};
+
+// src/access/navigation.ts
+var filterAccessibleItems = (items, options = {}) => {
+  const keepParentWhenAnyChildAccessible = options.keepParentWhenAnyChildAccessible ?? true;
+  const context = {
+    features: options.features,
+    caseSensitive: options.caseSensitive
+  };
+  const filteredItems = [];
+  for (const item of items) {
+    const decision = evaluateRouteAccess(item, context);
+    const filteredChildren = item.children ? filterAccessibleItems(item.children, options) : undefined;
+    const hasVisibleChildren = (filteredChildren?.length ?? 0) > 0;
+    const shouldIncludeItem = decision.allowed || keepParentWhenAnyChildAccessible && hasVisibleChildren;
+    if (!shouldIncludeItem) {
+      continue;
+    }
+    const nextItem = {
+      ...item,
+      ...filteredChildren ? { children: filteredChildren } : {}
+    };
+    filteredItems.push(nextItem);
+  }
+  return filteredItems;
+};
+// src/internal/records.ts
+var isRecord = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var toStringArray = (value) => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const values = [];
+  for (const entry of value) {
+    if (typeof entry === "string") {
+      values.push(entry);
+    }
+  }
+  return values;
+};
+
+// src/licensing/feature-http-loader.ts
+var resolveHeaders = async (headerProvider) => {
+  if (!headerProvider) {
+    return;
+  }
+  if (typeof headerProvider === "function") {
+    return await headerProvider();
+  }
+  return headerProvider;
+};
+var tryReadStringArray = (payload) => {
+  const values = toStringArray(payload);
+  if (values.length > 0) {
+    return values;
+  }
+  if (Array.isArray(payload)) {
+    return [];
+  }
+  return null;
+};
+var defaultLicenseFeatureResponseParser = (payload) => {
+  const directArray = tryReadStringArray(payload);
+  if (directArray) {
+    return directArray;
+  }
+  if (!isRecord(payload)) {
+    throw new Error("Unable to parse feature response payload");
+  }
+  const payloadRecord = payload;
+  const directFeatures = tryReadStringArray(payloadRecord.features);
+  if (directFeatures) {
+    return directFeatures;
+  }
+  const directExtra = tryReadStringArray(payloadRecord.extra);
+  if (directExtra) {
+    return directExtra;
+  }
+  if (isRecord(payloadRecord.data)) {
+    const dataRecord = payloadRecord.data;
+    const nestedFeatures = tryReadStringArray(dataRecord.features);
+    if (nestedFeatures) {
+      return nestedFeatures;
+    }
+    const nestedExtra = tryReadStringArray(dataRecord.extra);
+    if (nestedExtra) {
+      return nestedExtra;
+    }
+  }
+  throw new Error("Unable to parse feature response payload");
+};
+var createLicenseFeatureLoader = (options) => {
+  const parser = options.parser ?? defaultLicenseFeatureResponseParser;
+  const fetcher = options.fetch ?? fetch;
+  const loadFeatures = async () => {
+    const response = await fetcher(options.url, {
+      method: "GET",
+      credentials: options.credentials,
+      headers: await resolveHeaders(options.headers)
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to load license features (${response.status} ${response.statusText})`);
+    }
+    const payload = await response.json();
+    return parser(payload);
+  };
+  return loadFeatures;
+};
+// src/internal/store.ts
+var createStore = (initialState) => {
+  let currentState = initialState;
+  const listeners = new Set;
+  const getState = () => {
+    return currentState;
+  };
+  const setState = (updater) => {
+    currentState = typeof updater === "function" ? updater(currentState) : updater;
+    for (const listener of listeners) {
+      listener(currentState);
+    }
+    return currentState;
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+  return {
+    getState,
+    setState,
+    subscribe
+  };
+};
+
+// src/licensing/feature-store.ts
+var createFeatureStore = (options = {}) => {
+  const initialFeatures = normalizeFeatureList(options.initialFeatures ?? [], options);
+  const store = createStore({
+    features: initialFeatures,
+    loaded: initialFeatures.length > 0,
+    isLoading: false,
+    lastLoadedAt: initialFeatures.length > 0 ? Date.now() : null,
+    error: null
+  });
+  let inFlightLoad = null;
+  const getState = () => {
+    return store.getState();
+  };
+  const subscribe = store.subscribe;
+  const setFeatures = (features) => {
+    const normalizedFeatures = normalizeFeatureList(features, options);
+    store.setState((state) => {
+      return {
+        ...state,
+        features: normalizedFeatures,
+        loaded: true,
+        isLoading: false,
+        lastLoadedAt: Date.now(),
+        error: null
+      };
+    });
+    return normalizedFeatures;
+  };
+  const clear = () => {
+    store.setState((state) => {
+      return {
+        ...state,
+        features: [],
+        loaded: false,
+        isLoading: false,
+        lastLoadedAt: null,
+        error: null
+      };
+    });
+  };
+  const load = async () => {
+    if (!options.loadFeatures) {
+      const state = getState();
+      if (!state.loaded) {
+        store.setState((currentState) => {
+          return {
+            ...currentState,
+            loaded: true,
+            lastLoadedAt: currentState.lastLoadedAt ?? Date.now()
+          };
+        });
+      }
+      return getState().features;
+    }
+    if (inFlightLoad) {
+      return inFlightLoad;
+    }
+    store.setState((state) => {
+      return {
+        ...state,
+        isLoading: true,
+        error: null
+      };
+    });
+    inFlightLoad = options.loadFeatures().then((features) => {
+      return setFeatures(features);
+    }).catch((error) => {
+      const shouldResetToEmpty = options.resetToEmptyOnError ?? true;
+      store.setState((state) => {
+        return {
+          ...state,
+          features: shouldResetToEmpty ? [] : state.features,
+          loaded: true,
+          isLoading: false,
+          lastLoadedAt: Date.now(),
+          error
+        };
+      });
+      throw error;
+    }).finally(() => {
+      inFlightLoad = null;
+    });
+    return inFlightLoad;
+  };
+  const hasOneFeature = (requiredFeature) => {
+    return hasFeature(getState().features, requiredFeature, options);
+  };
+  const hasAnyRequiredFeature = (requiredFeatures) => {
+    return hasAnyFeature(getState().features, requiredFeatures, options);
+  };
+  const hasAllRequiredFeatures = (requiredFeatures) => {
+    return hasAllFeatures(getState().features, requiredFeatures, options);
+  };
+  const hasRequiredFeatures = (requiredFeatures, requirementOptions = {}) => {
+    return hasFeatures(getState().features, requiredFeatures, {
+      ...options,
+      ...requirementOptions
+    });
+  };
+  const getMissingRequiredFeatures = (requiredFeatures, requirementOptions = {}) => {
+    return getMissingFeatures(getState().features, requiredFeatures, {
+      ...options,
+      ...requirementOptions
+    });
+  };
+  if (options.autoLoad) {
+    load().catch(() => {
+      return;
+    });
+  }
+  const featureStore = {
+    getState,
+    subscribe,
+    setFeatures,
+    clear,
+    load,
+    hasFeature: hasOneFeature,
+    hasAnyFeature: hasAnyRequiredFeature,
+    hasAllFeatures: hasAllRequiredFeatures,
+    hasFeatures: hasRequiredFeatures,
+    getMissingFeatures: getMissingRequiredFeatures
+  };
+  return featureStore;
+};
+export {
+  normalizeFeatureList,
+  hasFeatures,
+  hasFeature,
+  hasAnyFeature,
+  hasAllFeatures,
+  getMissingFeatures,
+  filterAccessibleItems,
+  evaluateRouteAccess,
+  defaultLicenseFeatureResponseParser,
+  createLicenseFeatureLoader,
+  createFeatureStore,
+  canAccessRoute
+};

package/dist/internal/access-keys.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Determines whether a check requires any or all values to match.
+ */
+export type AccessRequirementMode = "any" | "all";
+export type AccessKeyOptions = {
+    caseSensitive?: boolean;
+};
+export declare const normalizeAccessKey: (rawValue: string, options?: AccessKeyOptions) => string;
+export declare const normalizeAccessKeys: (rawValues: readonly string[], options?: AccessKeyOptions) => string[];
+export declare const createAccessLookup: (rawValues: readonly string[], options?: AccessKeyOptions) => Set<string>;
+export declare const hasAccessKey: (rawValues: readonly string[], targetValue: string, options?: AccessKeyOptions) => boolean;
+export declare const getMissingAccessKeys: (rawValues: readonly string[], requiredValues: readonly string[], options?: AccessKeyOptions) => string[];

package/dist/internal/records.d.ts

@@ -0,0 +1,2 @@
+export declare const isRecord: (value: unknown) => boolean;
+export declare const toStringArray: (value: unknown) => string[];

package/dist/internal/store.d.ts

@@ -0,0 +1,8 @@
+export type StoreListener<TState> = (state: TState) => void;
+type StateUpdater<TState> = TState | ((state: TState) => TState);
+export declare const createStore: <TState>(initialState: TState) => {
+    getState: () => TState;
+    setState: (updater: StateUpdater<TState>) => TState;
+    subscribe: (listener: StoreListener<TState>) => () => void;
+};
+export {};

package/dist/licensing/feature-http-loader.d.ts

@@ -0,0 +1,37 @@
+type HeaderProvider = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+/**
+ * Parses an unknown HTTP payload into a list of feature codes.
+ */
+export type LicenseFeatureResponseParser = (payload: unknown) => readonly string[];
+/**
+ * A function that loads the active feature list.
+ */
+export type LicenseFeatureLoader = () => Promise<readonly string[]>;
+/**
+ * Configuration used by `createLicenseFeatureLoader`.
+ */
+export type CreateLicenseFeatureLoaderOptions = {
+    /** Full endpoint URL that returns the active feature list. */
+    url: string;
+    /** Optional custom `fetch` implementation. */
+    fetch?: typeof fetch;
+    /** Optional static/dynamic request headers. */
+    headers?: HeaderProvider;
+    /** Optional `fetch` credentials mode. */
+    credentials?: RequestCredentials;
+    /** Optional custom payload parser. */
+    parser?: LicenseFeatureResponseParser;
+};
+export declare const defaultLicenseFeatureResponseParser: LicenseFeatureResponseParser;
+/**
+ * Creates an HTTP-based feature loader.
+ *
+ * The default parser supports these payload shapes:
+ * - `string[]`
+ * - `{ features: string[] }`
+ * - `{ extra: string[] }`
+ * - `{ data: { features: string[] } }`
+ * - `{ data: { extra: string[] } }`
+ */
+export declare const createLicenseFeatureLoader: (options: CreateLicenseFeatureLoaderOptions) => LicenseFeatureLoader;
+export {};

package/dist/licensing/feature-store.d.ts

@@ -0,0 +1,73 @@
+import { type FeatureCheckOptions, type FeatureRequirementOptions } from "./feature-utils";
+/**
+ * Async feature loader used by the store.
+ */
+export type FeatureLoader = () => Promise<readonly string[]>;
+/**
+ * Runtime state exposed by the feature store.
+ */
+export type FeatureStoreState = {
+    /** Current normalized feature list. */
+    features: string[];
+    /** Indicates if the store has completed at least one initialization/load step. */
+    loaded: boolean;
+    /** Indicates if a load operation is currently in progress. */
+    isLoading: boolean;
+    /** Unix timestamp (ms) of the last successful/failed load attempt. */
+    lastLoadedAt: number | null;
+    /** Last load error value, if any. */
+    error: unknown | null;
+};
+/**
+ * Options used to create a feature store.
+ */
+export type CreateFeatureStoreOptions = FeatureCheckOptions & {
+    /** Optional async loader used by `load()`. */
+    loadFeatures?: FeatureLoader;
+    /** Optional initial feature list. */
+    initialFeatures?: readonly string[];
+    /** Automatically call `load()` on store creation. */
+    autoLoad?: boolean;
+    /** Reset `features` to `[]` when loading fails. Defaults to `true`. */
+    resetToEmptyOnError?: boolean;
+};
+/**
+ * Public API returned by `createFeatureStore`.
+ */
+export type FeatureStore = {
+    /** Returns current store state. */
+    getState: () => FeatureStoreState;
+    /** Subscribes to state changes. Returns an unsubscribe function. */
+    subscribe: (listener: (state: FeatureStoreState) => void) => () => void;
+    /** Replaces current features after normalization. */
+    setFeatures: (features: readonly string[]) => string[];
+    /** Clears all features and resets load markers. */
+    clear: () => void;
+    /** Loads features from `loadFeatures` when configured. */
+    load: () => Promise<string[]>;
+    /** Checks a single required feature. */
+    hasFeature: (requiredFeature: string) => boolean;
+    /** Checks that at least one required feature exists. */
+    hasAnyFeature: (requiredFeatures: readonly string[]) => boolean;
+    /** Checks that all required features exist. */
+    hasAllFeatures: (requiredFeatures: readonly string[]) => boolean;
+    /** Checks required features with configurable mode. */
+    hasFeatures: (requiredFeatures: readonly string[], requirementOptions?: FeatureRequirementOptions) => boolean;
+    /** Returns required feature codes that are currently missing. */
+    getMissingFeatures: (requiredFeatures: readonly string[], requirementOptions?: FeatureCheckOptions) => string[];
+};
+/**
+ * Creates a lightweight in-memory feature store.
+ */
+export declare const createFeatureStore: (options?: CreateFeatureStoreOptions) => {
+    getState: () => FeatureStoreState;
+    subscribe: (listener: import("../internal/store").StoreListener<FeatureStoreState>) => () => void;
+    setFeatures: (features: readonly string[]) => string[];
+    clear: () => void;
+    load: () => Promise<string[]>;
+    hasFeature: (requiredFeature: string) => boolean;
+    hasAnyFeature: (requiredFeatures: readonly string[]) => boolean;
+    hasAllFeatures: (requiredFeatures: readonly string[]) => boolean;
+    hasFeatures: (requiredFeatures: readonly string[], requirementOptions?: FeatureRequirementOptions) => boolean;
+    getMissingFeatures: (requiredFeatures: readonly string[], requirementOptions?: FeatureCheckOptions) => string[];
+};

package/dist/licensing/feature-utils.d.ts

@@ -0,0 +1,39 @@
+import { type AccessKeyOptions, type AccessRequirementMode } from "../internal/access-keys";
+/**
+ * Options shared by all feature-check helpers.
+ *
+ * @property caseSensitive Set to `true` to keep original casing during checks.
+ */
+export type FeatureCheckOptions = AccessKeyOptions;
+/**
+ * Options for checking multiple required features.
+ *
+ * @property mode `all` requires every feature, `any` requires at least one.
+ */
+export type FeatureRequirementOptions = FeatureCheckOptions & {
+    mode?: AccessRequirementMode;
+};
+/**
+ * Normalizes and deduplicates feature codes.
+ */
+export declare const normalizeFeatureList: (features: readonly string[], options?: FeatureCheckOptions) => string[];
+/**
+ * Returns `true` when a single feature is available.
+ */
+export declare const hasFeature: (features: readonly string[], requiredFeature: string, options?: FeatureCheckOptions) => boolean;
+/**
+ * Returns `true` when at least one required feature is available.
+ */
+export declare const hasAnyFeature: (features: readonly string[], requiredFeatures: readonly string[], options?: FeatureCheckOptions) => boolean;
+/**
+ * Returns `true` when all required features are available.
+ */
+export declare const hasAllFeatures: (features: readonly string[], requiredFeatures: readonly string[], options?: FeatureCheckOptions) => boolean;
+/**
+ * Checks required features using the provided `mode`.
+ */
+export declare const hasFeatures: (features: readonly string[], requiredFeatures: readonly string[], options?: FeatureRequirementOptions) => boolean;
+/**
+ * Returns normalized required feature codes that are currently missing.
+ */
+export declare const getMissingFeatures: (features: readonly string[], requiredFeatures: readonly string[], options?: FeatureCheckOptions) => string[];

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@m6d/cerebro",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun build ./src/index.ts --outdir ./dist --format esm --target browser && bunx --bun tsc -p tsconfig.build.json",
+    "check": "bunx --bun tsc --noEmit",
+    "clean": "rm -rf dist",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint",
+    "prepare": "husky",
+    "release": "semantic-release",
+    "sample:feature-store": "bun run ./samples/vanilla-feature-store-sample/index.ts",
+    "spellcheck": "cspell \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/bun": "latest",
+    "cspell": "^9.6.4",
+    "eslint": "^9",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.6.2",
+    "semantic-release": "^24.2.3",
+    "sort-package-json": "^3.6.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}