@happyvertical/smrt-features 0.30.0

package/AGENTS.md

@@ -0,0 +1,28 @@
+# smrt-features
+
+Code-first feature flag system with global, app-level, and tenant-hierarchy resolution.
+
+## Core pieces
+
+- `FeatureDefinition` (`_smrt_feature_definitions` table) — code-owned definition mirrored to DB at registration
+- `FeatureOverride` (`_smrt_feature_overrides` table) — runtime override state, scoped by `(featureKey, scopeType, scopeId)`
+- `FeatureResolver` — resolves the effective state of a feature in a given context, walking the scope chain
+- `FeatureSyncService` — keeps `_smrt_feature_definitions` in sync with code-registered defaults at boot
+
+## Resolution chain (priority high → low)
+
+1. User scope (`scopeType: 'user'`) — when context includes a userId
+2. Tenant scope (`scopeType: 'tenant'`) — walks up the tenant hierarchy when a `FeatureTenantHierarchyProvider` is configured (DI); otherwise resolves a flat tenant scope
+3. Global scope (`scopeType: 'global'`, `scopeId: GLOBAL_FEATURE_SCOPE_ID`)
+4. Definition default (registered in code)
+
+## Conventions
+
+- Feature keys should be namespaced by package or domain, e.g. `commerce.invoice.draft-mode`, `content.editor.ai-suggestions`
+- Definitions are code-owned. Don't write `FeatureDefinition` rows directly — use `FeatureSyncService.syncDefinitions()` at startup with the manifest of expected features
+- Overrides are write-time validated against the matching definition (effect must be a known `FeatureOverrideEffect`, scope must be valid for the definition's `allowedScopes`)
+- Tenant-hierarchy resolution is an optional integration wired by dependency injection (`FeatureTenantHierarchyProvider`), not a static dependency — `smrt-features` never imports `@happyvertical/smrt-users`. Without a configured provider, tenant-hierarchy resolution falls back to a flat tenant scope. (The consumer that wants hierarchy installs `smrt-users` itself and supplies the provider; `smrt-users` is a dev-only dependency here for tests.)
+
+## Integration with `@happyvertical/smrt-users`
+
+When `smrt-users` is present, `FeatureResolver` uses it to walk the tenant hierarchy (parent → grandparent → root). Configure via `FeatureTenantHierarchyProvider`. Without it, tenant lookup is single-level.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @happyvertical/smrt-features
+
+Code-first feature flags for SMRT applications, with global, app-level, and tenant-hierarchy resolution.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-features
+```
+
+## Quick start
+
+```typescript
+import {
+  FeatureDefinition,
+  FeatureResolver,
+  FeatureSyncService,
+} from '@happyvertical/smrt-features';
+
+// 1. Sync code-defined feature definitions at startup
+await FeatureSyncService.syncDefinitions({
+  manifest: [
+    {
+      key: 'commerce.invoice.draft-mode',
+      description: 'Allow users to save invoices as drafts before sending',
+      defaultEffect: 'enabled',
+      allowedScopes: ['global', 'tenant', 'user'],
+    },
+    // ...
+  ],
+});
+
+// 2. Resolve at runtime
+const enabled = await FeatureResolver.isEnabled('commerce.invoice.draft-mode', {
+  tenantId: currentTenantId,
+  userId: currentUserId,
+});
+```
+
+## Resolution
+
+Features resolve in this priority order:
+
+1. **User override** (most specific) — `FeatureOverride` row with `scopeType: 'user'` for the active user
+2. **Tenant override** — `FeatureOverride` row with `scopeType: 'tenant'`. Walks the tenant hierarchy if `@happyvertical/smrt-users` is installed.
+3. **Global override** — `FeatureOverride` row with `scopeType: 'global'`
+4. **Code default** — registered via `FeatureSyncService` from the manifest
+
+The first match wins.
+
+## Storage
+
+- `_smrt_feature_definitions` — code-owned feature shape (default effect, allowed scopes, metadata)
+- `_smrt_feature_overrides` — runtime overrides at any scope level
+
+## Documentation
+
+- See [`AGENTS.md`](./AGENTS.md) for package-internal patterns
+- See [`docs/standards.md`](../../docs/standards.md) for monorepo conventions
+- See [`docs/architecture/`](../../docs/architecture/) for cross-package architecture

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+import { SmartObjectManifest } from '@happyvertical/smrt-core/manifest';
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+
+export declare function createFeatureKey(qualifiedClassName: string, localId: string): string;
+
+export declare class FeatureDefinition extends SmrtObject {
+    featureKey: string;
+    packageName: string;
+    qualifiedClassName: string;
+    className: string;
+    localId: string;
+    defaultEnabled: boolean;
+    label: string;
+    description: string;
+    metadata: string;
+    visibility: string;
+    constructor(options?: FeatureDefinitionOptions);
+    getMetadata(): FeatureMetadata;
+    setMetadata(metadata: FeatureMetadata | null): void;
+}
+
+export declare class FeatureDefinitionCollection extends SmrtCollection<FeatureDefinition> {
+    static readonly _itemClass: typeof FeatureDefinition;
+    findByFeatureKey(featureKey: string): Promise<FeatureDefinition | null>;
+    findByPackageName(packageName: string): Promise<FeatureDefinition[]>;
+    upsertDefinition(seed: FeatureDefinitionSeed): Promise<{
+        definition: FeatureDefinition;
+        status: 'created' | 'updated' | 'unchanged';
+    }>;
+}
+
+export declare interface FeatureDefinitionOptions {
+    id?: string;
+    featureKey?: string;
+    packageName?: string;
+    qualifiedClassName?: string;
+    className?: string;
+    localId?: string;
+    defaultEnabled?: boolean;
+    label?: string;
+    description?: string;
+    metadata?: FeatureMetadata | string | null;
+    visibility?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+export declare interface FeatureDefinitionSeed {
+    featureKey: string;
+    packageName: string;
+    qualifiedClassName: string;
+    className: string;
+    localId: string;
+    defaultEnabled: boolean;
+    label?: string;
+    description?: string;
+    metadata?: FeatureMetadata;
+    visibility?: string;
+}
+
+export declare interface FeatureMetadata {
+    [key: string]: unknown;
+}
+
+export declare class FeatureOverride extends SmrtObject {
+    featureKey: string;
+    scopeType: FeatureScopeType;
+    scopeId: string;
+    effect: FeatureOverrideEffect;
+    constructor(options?: FeatureOverrideOptions);
+    isInherit(): boolean;
+    isEnabled(): boolean;
+    isDisabled(): boolean;
+}
+
+export declare class FeatureOverrideCollection extends SmrtCollection<FeatureOverride> {
+    static readonly _itemClass: typeof FeatureOverride;
+    findByFeatureKey(featureKey: string): Promise<FeatureOverride[]>;
+    findByFeatureAndScope(featureKey: string, scopeType: FeatureScopeType, scopeId: string): Promise<FeatureOverride | null>;
+    getGlobalOverride(featureKey: string): Promise<FeatureOverride | null>;
+    getTenantOverride(featureKey: string, tenantId: string): Promise<FeatureOverride | null>;
+    getOverrideMap(featureKey: string, scopeType: FeatureScopeType, scopeIds: string[]): Promise<Map<string, FeatureOverride>>;
+    setOverride(featureKey: string, scopeType: FeatureScopeType, scopeId: string, effect: FeatureOverrideEffect): Promise<FeatureOverride>;
+    setGlobalOverride(featureKey: string, effect: FeatureOverrideEffect): Promise<FeatureOverride>;
+    setTenantOverride(featureKey: string, tenantId: string, effect: FeatureOverrideEffect): Promise<FeatureOverride>;
+    removeOverride(featureKey: string, scopeType: FeatureScopeType, scopeId: string): Promise<boolean>;
+}
+
+export declare enum FeatureOverrideEffect {
+    INHERIT = "inherit",
+    ENABLE = "enable",
+    DISABLE = "disable"
+}
+
+export declare interface FeatureOverrideOptions {
+    id?: string;
+    featureKey?: string;
+    scopeType?: FeatureScopeType;
+    scopeId?: string;
+    effect?: FeatureOverrideEffect;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+export declare interface FeatureResolutionContext {
+    tenantId?: string;
+}
+
+export declare class FeatureResolver {
+    private readonly options;
+    private readonly resolverOptions;
+    private featureDefinitions;
+    private featureOverrides;
+    private initializationPromise;
+    private tenantHierarchyPromise;
+    constructor(options?: SmrtClassOptions, resolverOptions?: FeatureResolverOptions);
+    isEnabled(featureKey: string, context?: FeatureResolutionContext): Promise<boolean>;
+    isEnabledFor(classOrInstance: object | (new (...args: any[]) => any), localId: string, context?: FeatureResolutionContext): Promise<boolean>;
+    private ensureInitialized;
+    private resolveBaseState;
+    private applyOverride;
+    private getTenantHierarchy;
+}
+
+export declare interface FeatureResolverOptions {
+    tenantHierarchyLoader?: FeatureTenantHierarchyLoader;
+}
+
+export declare type FeatureScopeType = 'global' | 'tenant';
+
+export declare interface FeatureSyncResult {
+    total: number;
+    created: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+    featureKeys: string[];
+}
+
+export declare class FeatureSyncService {
+    private readonly options;
+    private featureDefinitions;
+    private initializationPromise;
+    constructor(options?: SmrtClassOptions);
+    syncDefinitions(options?: SyncDefinitionsOptions): Promise<FeatureSyncResult>;
+    syncManifest(manifest: SmartObjectManifest, options?: SyncManifestOptions): Promise<FeatureSyncResult>;
+    private ensureInitialized;
+    private collectDefinitionsFromRegistrations;
+    private collectTouchedPackagesFromRegistrations;
+    private collectRegistrations;
+    private applyDefinitions;
+}
+
+export declare type FeatureTenantHierarchyLoader = (options: SmrtClassOptions) => Promise<FeatureTenantHierarchyProvider | null>;
+
+export declare interface FeatureTenantHierarchyProvider {
+    getChain(tenantId: string): Promise<FeatureTenantNode[]>;
+}
+
+export declare interface FeatureTenantNode {
+    id: string;
+    inheritPermissions: boolean;
+    cascadePermissions: boolean;
+}
+
+export declare interface FeatureUsersModule {
+    TenantCollection: {
+        create(options: SmrtClassOptions): Promise<{
+            get(criteria: {
+                id: string;
+            }): Promise<any>;
+            getAncestorsFromRoot(tenantId: string): Promise<any[]>;
+        }>;
+    };
+}
+
+export declare function findFeatureDefaultInRegistry(featureKey: string): boolean | undefined;
+
+export declare const GLOBAL_FEATURE_SCOPE_ID = "*";
+
+export declare function parseFeatureKey(featureKey: string): {
+    qualifiedClassName: string;
+    localId: string;
+};
+
+export declare function resolveFeatureKeyForTarget(classOrInstance: object | (new (...args: any[]) => any), localId: string): {
+    featureKey: string;
+    defaultEnabled: boolean;
+};
+
+export declare interface SyncDefinitionsOptions {
+    classNames?: string[];
+    constructors?: Array<new (...args: any[]) => any>;
+    pruneStale?: boolean;
+}
+
+export declare interface SyncManifestOptions {
+    pruneStale?: boolean;
+}
+
+export { }