@zenxdigitalholdings/zenflags 0.2.0

package/README.md

@@ -0,0 +1,54 @@
+# @zenxdigitalholdings/zenflags
+
+Feature flags for Zen products — evaluated **in-process** from the Zen flags
+server ([atlasrails.online](https://atlasrails.online)). The flag set loads
+once at boot and refreshes in the background; a flag check never makes a
+network call.
+
+## Install
+
+```bash
+npm install @zenxdigitalholdings/zenflags
+```
+
+## Use (any Node ≥18 service)
+
+```js
+import { createFlags } from '@zenxdigitalholdings/zenflags'
+
+const flags = await createFlags() // API key from ZEN_FLAGS_KEY
+
+const d = await flags.evaluate(
+  { vertical: 'zenotc', microservice: 'otc-rfq', component: 'block-trade' },
+  { entityId: userId },
+)
+if (!d.allowsWrite()) return featureUnavailable()
+```
+
+Set one environment variable: `ZEN_FLAGS_KEY` — the API key issued for your
+product + environment in the Zen Flags console. The server endpoint is
+platform-managed (baked in); `ZEN_FLAGS_URL` exists only as an ops override.
+
+## NestJS
+
+```ts
+import { FlagsModule, FlagsService, FlagGuard, RequireFlag } from '@zenxdigitalholdings/zenflags/nestjs'
+
+@Module({ imports: [FlagsModule.forRoot({})] })
+export class AppModule {}
+
+// declarative route gating:
+@UseGuards(FlagGuard)
+@RequireFlag({ vertical: 'zenotc', microservice: 'otc-rfq', component: 'block-trade', op: 'write' })
+```
+
+## Guarantees
+
+- **No network per check** — snapshot at boot (~35 ms), in-memory evaluation,
+  jittered conditional refresh (304s when nothing changed).
+- **Never takes your service down** — on outage the last snapshot serves until
+  `maxStaleMs`; then protected flags fail **closed**, others use their fallback.
+- Unknown flags resolve to `DISABLED_HARD`. Deterministic DRAIN ramp bucketing,
+  identical to the Go SDK.
+
+Internal to Zen Atlas Group. Console & docs: https://atlasrails.online

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import { Evaluator } from './evaluator';
+import { type CachedZenOptions } from './zen';
+export interface CreateFlagsOptions extends CachedZenOptions {
+    /** How long to block for the boot snapshot (ms). Default 5000. */
+    readyTimeoutMs?: number;
+}
+/**
+ * The one-liner for plain Node/TS services:
+ *
+ *   const flags = await createFlags()          // key from ZEN_FLAGS_KEY
+ *
+ * Loads the flag set once at boot, evaluates from memory, refreshes in the
+ * background. The server endpoint is platform-managed — consumers never
+ * configure a URL.
+ */
+export declare function createFlags(opts?: CreateFlagsOptions): Promise<Evaluator>;

package/dist/client.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFlags = createFlags;
+const evaluator_1 = require("./evaluator");
+const zen_1 = require("./zen");
+/**
+ * The one-liner for plain Node/TS services:
+ *
+ *   const flags = await createFlags()          // key from ZEN_FLAGS_KEY
+ *
+ * Loads the flag set once at boot, evaluates from memory, refreshes in the
+ * background. The server endpoint is platform-managed — consumers never
+ * configure a URL.
+ */
+async function createFlags(opts = {}) {
+    const provider = new zen_1.CachedZenProvider(opts);
+    const ok = await provider.ready(opts.readyTimeoutMs ?? 5000);
+    if (!ok) {
+        // eslint-disable-next-line no-console
+        console.warn('[zen-flags] snapshot not loaded before timeout — flags fail closed until it arrives');
+    }
+    return new evaluator_1.Evaluator(provider);
+}

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+export type Op = 'read' | 'write';
+/**
+ * Per-request signals the provider targets on, and the stable identity the
+ * DRAIN ramp buckets by.
+ */
+export interface RequestContext {
+    environment: string;
+    entityId?: string;
+    region?: string;
+    kycTier?: string;
+    attributes?: Record<string, string>;
+}

package/dist/context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/decision.d.ts

@@ -0,0 +1,19 @@
+import type { State } from './state';
+import type { Op } from './context';
+/**
+ * The result of evaluating a Spec against a RequestContext. Always safe to act
+ * on: every degraded path yields a conservative state.
+ */
+export declare class Decision {
+    readonly key: string;
+    readonly state: State;
+    readonly isProtected: boolean;
+    readonly variant: string;
+    readonly inRamp: boolean;
+    readonly reason: string;
+    readonly err?: unknown | undefined;
+    constructor(key: string, state: State, isProtected: boolean, variant: string, inRamp: boolean, reason: string, err?: unknown | undefined);
+    allowsRead(): boolean;
+    allowsWrite(): boolean;
+    allows(op: Op): boolean;
+}

package/dist/decision.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Decision = void 0;
+/**
+ * The result of evaluating a Spec against a RequestContext. Always safe to act
+ * on: every degraded path yields a conservative state.
+ */
+class Decision {
+    constructor(key, state, isProtected, variant, inRamp, reason, err) {
+        this.key = key;
+        this.state = state;
+        this.isProtected = isProtected;
+        this.variant = variant;
+        this.inRamp = inRamp;
+        this.reason = reason;
+        this.err = err;
+    }
+    allowsRead() {
+        switch (this.state) {
+            case 'ENABLED':
+            case 'READ_ONLY':
+                return true;
+            case 'DRAIN':
+                return this.inRamp;
+            default:
+                return false;
+        }
+    }
+    allowsWrite() {
+        switch (this.state) {
+            case 'ENABLED':
+                return true;
+            case 'DRAIN':
+                return this.inRamp;
+            default:
+                return false;
+        }
+    }
+    allows(op) {
+        return op === 'write' ? this.allowsWrite() : this.allowsRead();
+    }
+}
+exports.Decision = Decision;

package/dist/evaluator.d.ts

@@ -0,0 +1,19 @@
+import type { Provider } from './provider';
+import type { Spec } from './spec';
+import type { RequestContext, Op } from './context';
+import { Decision } from './decision';
+/**
+ * Applies the Zen policy on top of a Provider: taxonomy, ramp bucketing, and —
+ * the crux — fail-closed handling for the PROTECTED class. evaluate never
+ * rejects: failures fold into a conservative Decision with `err` set.
+ */
+export declare class Evaluator {
+    private readonly provider;
+    constructor(provider: Provider);
+    evaluate(spec: Spec, rc: RequestContext): Promise<Decision>;
+    allow(spec: Spec, rc: RequestContext, op: Op): Promise<{
+        allowed: boolean;
+        decision: Decision;
+    }>;
+    close(): Promise<void>;
+}

package/dist/evaluator.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Evaluator = void 0;
+const spec_1 = require("./spec");
+const decision_1 = require("./decision");
+const state_1 = require("./state");
+const ramp_1 = require("./ramp");
+/**
+ * Applies the Zen policy on top of a Provider: taxonomy, ramp bucketing, and —
+ * the crux — fail-closed handling for the PROTECTED class. evaluate never
+ * rejects: failures fold into a conservative Decision with `err` set.
+ */
+class Evaluator {
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async evaluate(spec, rc) {
+        const key = (0, spec_1.specKey)(spec);
+        try {
+            const res = await this.provider.evaluate(spec, rc);
+            if (!(0, state_1.isValidState)(res.state)) {
+                return new decision_1.Decision(key, 'DISABLED_HARD', !!spec.protected, '', false, `invalid state "${res.state}" -> DISABLED_HARD`, new Error('invalid state'));
+            }
+            if (res.state === 'DRAIN') {
+                const ramped = (0, ramp_1.inRamp)(key, rc.entityId ?? '', res.rampPercent ?? 0);
+                return new decision_1.Decision(key, 'DRAIN', !!spec.protected, res.variant ?? '', ramped, `DRAIN ${res.rampPercent ?? 0}%: inRamp=${ramped}`);
+            }
+            return new decision_1.Decision(key, res.state, !!spec.protected, res.variant ?? '', false, res.reason ?? '');
+        }
+        catch (err) {
+            if (spec.protected) {
+                return new decision_1.Decision(key, 'DISABLED_HARD', true, '', false, 'protected flag: provider error -> fail-closed DENY', err);
+            }
+            const fb = spec.fallbackState ?? 'DISABLED_HARD';
+            return new decision_1.Decision(key, fb, false, '', false, `provider error -> fallback ${fb}`, err);
+        }
+    }
+    async allow(spec, rc, op) {
+        const decision = await this.evaluate(spec, rc);
+        return { allowed: decision.allows(op), decision };
+    }
+    close() {
+        return this.provider.close();
+    }
+}
+exports.Evaluator = Evaluator;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './state';
+export * from './spec';
+export * from './context';
+export * from './decision';
+export * from './provider';
+export * from './memory';
+export * from './zen';
+export * from './evaluator';
+export { inRamp } from './ramp';
+export * from './client';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inRamp = void 0;
+__exportStar(require("./state"), exports);
+__exportStar(require("./spec"), exports);
+__exportStar(require("./context"), exports);
+__exportStar(require("./decision"), exports);
+__exportStar(require("./provider"), exports);
+__exportStar(require("./memory"), exports);
+__exportStar(require("./zen"), exports);
+__exportStar(require("./evaluator"), exports);
+var ramp_1 = require("./ramp");
+Object.defineProperty(exports, "inRamp", { enumerable: true, get: function () { return ramp_1.inRamp; } });
+__exportStar(require("./client"), exports);

package/dist/memory.d.ts

@@ -0,0 +1,16 @@
+import type { Provider, EvalResult } from './provider';
+import type { Spec } from './spec';
+import type { RequestContext } from './context';
+/**
+ * In-process Provider for tests and offline runs. Unknown flags resolve to
+ * DISABLED_HARD (baseline off), never an error. setError simulates an outage
+ * to exercise the fail-closed path.
+ */
+export declare class MemoryProvider implements Provider {
+    private readonly results;
+    private failErr?;
+    set(env: string, spec: Spec, res: EvalResult): void;
+    setError(err?: Error): void;
+    evaluate(spec: Spec, rc: RequestContext): Promise<EvalResult>;
+    close(): Promise<void>;
+}

package/dist/memory.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryProvider = void 0;
+const spec_1 = require("./spec");
+/**
+ * In-process Provider for tests and offline runs. Unknown flags resolve to
+ * DISABLED_HARD (baseline off), never an error. setError simulates an outage
+ * to exercise the fail-closed path.
+ */
+class MemoryProvider {
+    constructor() {
+        this.results = new Map();
+    }
+    set(env, spec, res) {
+        this.results.set(`${env}|${(0, spec_1.specKey)(spec)}`, res);
+    }
+    setError(err) {
+        this.failErr = err;
+    }
+    async evaluate(spec, rc) {
+        if (this.failErr)
+            throw this.failErr;
+        return (this.results.get(`${rc.environment}|${(0, spec_1.specKey)(spec)}`) ?? {
+            state: 'DISABLED_HARD',
+            reason: 'unknown flag -> baseline DISABLED_HARD',
+        });
+    }
+    async close() { }
+}
+exports.MemoryProvider = MemoryProvider;

package/dist/nestjs/flag.guard.d.ts

@@ -0,0 +1,14 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { FlagsService } from './flags.service';
+/**
+ * Enforces @RequireFlag on a route. Pulls the ramp/targeting context from the
+ * request (authenticated user id, then x-entity-id / x-region / x-kyc-tier
+ * headers) and throws ForbiddenException when the flag denies the operation.
+ */
+export declare class FlagGuard implements CanActivate {
+    private readonly reflector;
+    private readonly flags;
+    constructor(reflector: Reflector, flags: FlagsService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}

package/dist/nestjs/flag.guard.js

@@ -0,0 +1,61 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlagGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const flags_service_1 = require("./flags.service");
+const require_flag_decorator_1 = require("./require-flag.decorator");
+/**
+ * Enforces @RequireFlag on a route. Pulls the ramp/targeting context from the
+ * request (authenticated user id, then x-entity-id / x-region / x-kyc-tier
+ * headers) and throws ForbiddenException when the flag denies the operation.
+ */
+let FlagGuard = class FlagGuard {
+    constructor(reflector, flags) {
+        this.reflector = reflector;
+        this.flags = flags;
+    }
+    async canActivate(context) {
+        const meta = this.reflector.getAllAndOverride(require_flag_decorator_1.FLAG_META, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if (!meta)
+            return true;
+        const req = context.switchToHttp().getRequest();
+        const { allowed, decision } = await this.flags.allow({
+            vertical: meta.vertical,
+            microservice: meta.microservice,
+            component: meta.component,
+            protected: meta.protected,
+        }, meta.op ?? 'read', {
+            entityId: req.user?.id ?? req.headers['x-entity-id'],
+            region: req.headers['x-region'],
+            kycTier: req.headers['x-kyc-tier'],
+        });
+        if (!allowed) {
+            throw new common_1.ForbiddenException({
+                error: 'feature unavailable',
+                key: decision.key,
+                state: decision.state,
+                reason: decision.reason,
+            });
+        }
+        return true;
+    }
+};
+exports.FlagGuard = FlagGuard;
+exports.FlagGuard = FlagGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        flags_service_1.FlagsService])
+], FlagGuard);

package/dist/nestjs/flags.module.d.ts

@@ -0,0 +1,32 @@
+import { DynamicModule } from '@nestjs/common';
+import type { Provider } from '../provider';
+export declare const FLAGS_OPTIONS = "ZEN_FLAGS_OPTIONS";
+export interface FlagsModuleOptions {
+    /** Per-service API key (zfk_…). Falls back to ZEN_FLAGS_KEY. */
+    apiKey?: string;
+    /** Ops override only — the endpoint is platform-managed (baked default + ZEN_FLAGS_URL). */
+    serverUrl?: string;
+    /**
+     * 'cached' (default) loads the flag set once at boot and keeps it fresh in
+     * the background — no network call per flag check; 'direct' calls
+     * /v1/evaluate per check (debugging only); 'memory' for tests; or pass a
+     * custom Provider instance.
+     */
+    mode?: 'cached' | 'direct' | 'memory' | Provider;
+    /** Snapshot refresh interval (ms) in cached mode. Default 5000. */
+    refreshMs?: number;
+    /**
+     * In cached mode, how long module init waits for the first snapshot
+     * (load-once-at-boot). Default 5000; on timeout the app still starts and
+     * flags fail closed / fall back until the snapshot loads.
+     */
+    readyTimeoutMs?: number;
+}
+/**
+ * FlagsModule.forRoot({...}) wires an Evaluator + FlagsService for the app.
+ * Register once (global); inject FlagsService anywhere, or gate routes with
+ * @RequireFlag + FlagGuard.
+ */
+export declare class FlagsModule {
+    static forRoot(options: FlagsModuleOptions): DynamicModule;
+}

package/dist/nestjs/flags.module.js

@@ -0,0 +1,61 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var FlagsModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlagsModule = exports.FLAGS_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+const evaluator_1 = require("../evaluator");
+const zen_1 = require("../zen");
+const memory_1 = require("../memory");
+const flags_service_1 = require("./flags.service");
+exports.FLAGS_OPTIONS = 'ZEN_FLAGS_OPTIONS';
+/**
+ * FlagsModule.forRoot({...}) wires an Evaluator + FlagsService for the app.
+ * Register once (global); inject FlagsService anywhere, or gate routes with
+ * @RequireFlag + FlagGuard.
+ */
+let FlagsModule = FlagsModule_1 = class FlagsModule {
+    static forRoot(options) {
+        const evaluatorProvider = {
+            provide: evaluator_1.Evaluator,
+            useFactory: async () => {
+                let provider;
+                if (options.mode && typeof options.mode !== 'string') {
+                    provider = options.mode;
+                }
+                else if (options.mode === 'memory') {
+                    provider = new memory_1.MemoryProvider();
+                }
+                else if (options.mode === 'direct') {
+                    provider = new zen_1.ZenProvider(options);
+                }
+                else {
+                    const cached = new zen_1.CachedZenProvider(options);
+                    // Load-once-at-boot: block init until the first snapshot (bounded).
+                    const ok = await cached.ready(options.readyTimeoutMs ?? 5000);
+                    if (!ok) {
+                        // eslint-disable-next-line no-console
+                        console.warn('[zen-flags] snapshot not loaded before timeout — flags fail closed until it arrives');
+                    }
+                    provider = cached;
+                }
+                return new evaluator_1.Evaluator(provider);
+            },
+        };
+        return {
+            module: FlagsModule_1,
+            global: true,
+            providers: [{ provide: exports.FLAGS_OPTIONS, useValue: options }, evaluatorProvider, flags_service_1.FlagsService],
+            exports: [flags_service_1.FlagsService],
+        };
+    }
+};
+exports.FlagsModule = FlagsModule;
+exports.FlagsModule = FlagsModule = FlagsModule_1 = __decorate([
+    (0, common_1.Module)({})
+], FlagsModule);

package/dist/nestjs/flags.service.d.ts

@@ -0,0 +1,18 @@
+import { Evaluator } from '../evaluator';
+import type { Spec } from '../spec';
+import type { RequestContext, Op } from '../context';
+import type { Decision } from '../decision';
+/**
+ * Injectable wrapper over the Evaluator. The environment is pinned by the API
+ * key server-side; callers pass only per-request context (entityId for DRAIN
+ * bucketing, region/kycTier for future targeting).
+ */
+export declare class FlagsService {
+    private readonly evaluator;
+    constructor(evaluator: Evaluator);
+    evaluate(spec: Spec, ctx?: Partial<RequestContext>): Promise<Decision>;
+    allow(spec: Spec, op: Op, ctx?: Partial<RequestContext>): Promise<{
+        allowed: boolean;
+        decision: Decision;
+    }>;
+}

package/dist/nestjs/flags.service.js

@@ -0,0 +1,36 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlagsService = void 0;
+const common_1 = require("@nestjs/common");
+const evaluator_1 = require("../evaluator");
+/**
+ * Injectable wrapper over the Evaluator. The environment is pinned by the API
+ * key server-side; callers pass only per-request context (entityId for DRAIN
+ * bucketing, region/kycTier for future targeting).
+ */
+let FlagsService = class FlagsService {
+    constructor(evaluator) {
+        this.evaluator = evaluator;
+    }
+    evaluate(spec, ctx = {}) {
+        return this.evaluator.evaluate(spec, { environment: '', ...ctx });
+    }
+    async allow(spec, op, ctx = {}) {
+        const decision = await this.evaluate(spec, ctx);
+        return { allowed: decision.allows(op), decision };
+    }
+};
+exports.FlagsService = FlagsService;
+exports.FlagsService = FlagsService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [evaluator_1.Evaluator])
+], FlagsService);

package/dist/nestjs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './flags.module';
+export * from './flags.service';
+export * from './require-flag.decorator';
+export * from './flag.guard';

package/dist/nestjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./flags.module"), exports);
+__exportStar(require("./flags.service"), exports);
+__exportStar(require("./require-flag.decorator"), exports);
+__exportStar(require("./flag.guard"), exports);

package/dist/nestjs/require-flag.decorator.d.ts

@@ -0,0 +1,18 @@
+import type { Op } from '../context';
+export declare const FLAG_META = "zen:require-flag";
+export interface RequireFlagMeta {
+    vertical: string;
+    microservice: string;
+    component?: string;
+    /** Operation being gated (default 'read'). */
+    op?: Op;
+    /** Mark the compliance class — fails closed on backend error. */
+    protected?: boolean;
+}
+/**
+ * Route-level flag gate. Pair with FlagGuard:
+ *
+ *   @RequireFlag({ vertical: 'zenotc', microservice: 'otc-rfq', component: 'block-trade', op: 'write' })
+ *   @UseGuards(FlagGuard)
+ */
+export declare const RequireFlag: (meta: RequireFlagMeta) => import("@nestjs/common").CustomDecorator<string>;

package/dist/nestjs/require-flag.decorator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequireFlag = exports.FLAG_META = void 0;
+const common_1 = require("@nestjs/common");
+exports.FLAG_META = 'zen:require-flag';
+/**
+ * Route-level flag gate. Pair with FlagGuard:
+ *
+ *   @RequireFlag({ vertical: 'zenotc', microservice: 'otc-rfq', component: 'block-trade', op: 'write' })
+ *   @UseGuards(FlagGuard)
+ */
+const RequireFlag = (meta) => (0, common_1.SetMetadata)(exports.FLAG_META, meta);
+exports.RequireFlag = RequireFlag;

package/dist/provider.d.ts

@@ -0,0 +1,15 @@
+import type { State } from './state';
+import type { Spec } from './spec';
+import type { RequestContext } from './context';
+/** Raw evaluation a Provider returns, before ramp/fail-closed policy is applied. */
+export interface EvalResult {
+    state: State;
+    rampPercent?: number;
+    variant?: string;
+    reason?: string;
+}
+/** Pluggable flag backend. FliptProvider is production; MemoryProvider backs tests. */
+export interface Provider {
+    evaluate(spec: Spec, rc: RequestContext): Promise<EvalResult>;
+    close(): Promise<void>;
+}

package/dist/provider.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ramp.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deterministic FNV-1a (32-bit) bucketing over UTF-8 bytes. Matches the Go
+ * flag-sdk exactly, so a given entity lands in the same DRAIN cohort whether it
+ * is evaluated by a Go service or a TypeScript one.
+ */
+export declare function inRamp(key: string, entityId: string, percent: number): boolean;

package/dist/ramp.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inRamp = inRamp;
+/**
+ * Deterministic FNV-1a (32-bit) bucketing over UTF-8 bytes. Matches the Go
+ * flag-sdk exactly, so a given entity lands in the same DRAIN cohort whether it
+ * is evaluated by a Go service or a TypeScript one.
+ */
+function inRamp(key, entityId, percent) {
+    if (percent <= 0)
+        return false;
+    if (percent >= 100)
+        return true;
+    const bytes = new TextEncoder().encode(`${key}:${entityId}`);
+    let h = 0x811c9dc5;
+    for (const b of bytes) {
+        h ^= b;
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h % 100 < percent;
+}

package/dist/spec.d.ts

@@ -0,0 +1,17 @@
+import type { State } from './state';
+/**
+ * Spec identifies a flag on the three kill-switch axes and declares its class.
+ * Key format: vertical.microservice[.component]  (vertical maps to a Flipt namespace).
+ */
+export interface Spec {
+    vertical: string;
+    microservice: string;
+    component?: string;
+    /** Compliance class (AML/KYC/sanctions/MPC): fails CLOSED on any error. */
+    protected?: boolean;
+    /** Fallback for NON-protected flags on provider error (default DISABLED_HARD). */
+    fallbackState?: State;
+}
+export declare function specKey(s: Spec): string;
+export declare function specNamespace(s: Spec): string;
+export declare function specFlagKey(s: Spec): string;

package/dist/spec.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specKey = specKey;
+exports.specNamespace = specNamespace;
+exports.specFlagKey = specFlagKey;
+function specKey(s) {
+    return s.component
+        ? `${s.vertical}.${s.microservice}.${s.component}`
+        : `${s.vertical}.${s.microservice}`;
+}
+function specNamespace(s) {
+    return s.vertical;
+}
+function specFlagKey(s) {
+    return s.component ? `${s.microservice}.${s.component}` : s.microservice;
+}

package/dist/state.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The five operational states used across the Zen ecosystem. Orthogonal to the
+ * PROTECTED class (a property of the Spec): PROTECTED describes error behaviour,
+ * State describes what an evaluated flag permits.
+ */
+export type State = 'ENABLED' | 'READ_ONLY' | 'DRAIN' | 'MAINTENANCE' | 'DISABLED_HARD';
+export declare function isValidState(s: string): s is State;

package/dist/state.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidState = isValidState;
+const ALL = ['ENABLED', 'READ_ONLY', 'DRAIN', 'MAINTENANCE', 'DISABLED_HARD'];
+function isValidState(s) {
+    return ALL.includes(s);
+}

package/dist/zen.d.ts

@@ -0,0 +1,72 @@
+import type { Provider, EvalResult } from './provider';
+import type { Spec } from './spec';
+import type { RequestContext } from './context';
+/**
+ * Evaluates flags against the Zen flags server's read plane. Authentication is
+ * a per-service API key; the key pins the environment (and optionally the
+ * vertical) server-side — the SDK never sends an environment. Flipt is an
+ * internal detail of the server; consumers never see it.
+ *
+ * Prefer CachedZenProvider in services: it loads the flag set once at boot and
+ * keeps it fresh in the background — no network call per flag check.
+ */
+/**
+ * The canonical Zen flags server. Consumers never configure a URL — the
+ * platform team owns this endpoint. Resolution order (highest wins):
+ * explicit option → ZEN_FLAGS_URL env (local dev / ops override) → default.
+ */
+export declare const DEFAULT_SERVER_URL = "https://atlasrails.online";
+export interface ZenOptions {
+    /** Service API key (zfk_…). Falls back to ZEN_FLAGS_KEY. */
+    apiKey?: string;
+    /** Ops override only — consumers should not set this. Falls back to ZEN_FLAGS_URL. */
+    serverUrl?: string;
+    timeoutMs?: number;
+}
+export interface CachedZenOptions extends ZenOptions {
+    /** Background refresh interval (ms). Default 5000. */
+    refreshMs?: number;
+    /** How long a stale snapshot keeps serving in an outage (ms). Default 5min. */
+    maxStaleMs?: number;
+}
+export declare class ZenProvider implements Provider {
+    readonly baseURL: string;
+    readonly apiKey: string;
+    private readonly timeoutMs;
+    constructor(opts?: ZenOptions);
+    evaluate(spec: Spec, _rc: RequestContext): Promise<EvalResult>;
+    close(): Promise<void>;
+}
+/**
+ * Load-once + background-refresh provider. The full flag set for the key's
+ * scope is fetched at construction (await ready() during service boot), then
+ * kept fresh with jittered conditional polls — unchanged snapshots cost a
+ * 0-byte 304. Every evaluation is served from memory; no network on the hot
+ * path. A server outage keeps serving the last snapshot until maxStaleMs,
+ * after which evaluations throw and the Evaluator's fail-closed/fallback
+ * policy takes over.
+ */
+export declare class CachedZenProvider implements Provider {
+    private snapshot;
+    private fetchedAt;
+    private etag;
+    private timer;
+    private stopped;
+    private readonly zen;
+    private readonly intervalMs;
+    private readonly maxStaleMs;
+    private readonly readyPromise;
+    private markReady;
+    constructor(opts?: CachedZenOptions);
+    /**
+     * Resolves once the first snapshot has loaded — await this at service boot
+     * (the load-once pattern). Pass a timeout to bound startup: on timeout the
+     * provider keeps retrying in the background and evaluations fail closed /
+     * fall back until it recovers.
+     */
+    ready(timeoutMs?: number): Promise<boolean>;
+    private schedule;
+    private refresh;
+    evaluate(spec: Spec, _rc: RequestContext): Promise<EvalResult>;
+    close(): Promise<void>;
+}

package/dist/zen.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedZenProvider = exports.ZenProvider = exports.DEFAULT_SERVER_URL = void 0;
+const spec_1 = require("./spec");
+/**
+ * Evaluates flags against the Zen flags server's read plane. Authentication is
+ * a per-service API key; the key pins the environment (and optionally the
+ * vertical) server-side — the SDK never sends an environment. Flipt is an
+ * internal detail of the server; consumers never see it.
+ *
+ * Prefer CachedZenProvider in services: it loads the flag set once at boot and
+ * keeps it fresh in the background — no network call per flag check.
+ */
+/**
+ * The canonical Zen flags server. Consumers never configure a URL — the
+ * platform team owns this endpoint. Resolution order (highest wins):
+ * explicit option → ZEN_FLAGS_URL env (local dev / ops override) → default.
+ */
+exports.DEFAULT_SERVER_URL = 'https://atlasrails.online';
+const env = (k) => typeof process !== 'undefined' ? process.env?.[k] : undefined;
+class ZenProvider {
+    constructor(opts = {}) {
+        this.baseURL = (opts.serverUrl ?? env('ZEN_FLAGS_URL') ?? exports.DEFAULT_SERVER_URL).replace(/\/+$/, '');
+        this.apiKey = opts.apiKey ?? env('ZEN_FLAGS_KEY') ?? '';
+        this.timeoutMs = opts.timeoutMs ?? 2000;
+    }
+    async evaluate(spec, _rc) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(`${this.baseURL}/v1/evaluate`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${this.apiKey}` },
+                body: JSON.stringify({
+                    vertical: spec.vertical,
+                    microservice: spec.microservice,
+                    component: spec.component ?? '',
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok)
+                throw new Error(`zen flags: status ${res.status}`);
+            const out = (await res.json());
+            return { state: out.state, rampPercent: out.rampPercent, reason: out.reason };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async close() { }
+}
+exports.ZenProvider = ZenProvider;
+/**
+ * Load-once + background-refresh provider. The full flag set for the key's
+ * scope is fetched at construction (await ready() during service boot), then
+ * kept fresh with jittered conditional polls — unchanged snapshots cost a
+ * 0-byte 304. Every evaluation is served from memory; no network on the hot
+ * path. A server outage keeps serving the last snapshot until maxStaleMs,
+ * after which evaluations throw and the Evaluator's fail-closed/fallback
+ * policy takes over.
+ */
+class CachedZenProvider {
+    constructor(opts = {}) {
+        this.snapshot = null;
+        this.fetchedAt = 0;
+        this.etag = '';
+        this.timer = null;
+        this.stopped = false;
+        this.intervalMs = opts.refreshMs ?? 5000;
+        this.maxStaleMs = opts.maxStaleMs ?? 5 * 60_000;
+        this.zen = new ZenProvider(opts);
+        this.readyPromise = new Promise((resolve) => {
+            this.markReady = resolve;
+        });
+        void this.refresh();
+        this.schedule();
+    }
+    /**
+     * Resolves once the first snapshot has loaded — await this at service boot
+     * (the load-once pattern). Pass a timeout to bound startup: on timeout the
+     * provider keeps retrying in the background and evaluations fail closed /
+     * fall back until it recovers.
+     */
+    ready(timeoutMs) {
+        if (!timeoutMs)
+            return this.readyPromise.then(() => true);
+        return Promise.race([
+            this.readyPromise.then(() => true),
+            new Promise((r) => setTimeout(() => r(false), timeoutMs)),
+        ]);
+    }
+    schedule() {
+        if (this.stopped)
+            return;
+        // ±20% jitter so a fleet of instances doesn't poll in lockstep.
+        const jitter = (Math.random() - 0.5) * 0.4 * this.intervalMs;
+        this.timer = setTimeout(() => {
+            void this.refresh().finally(() => this.schedule());
+        }, this.intervalMs + jitter);
+        if (typeof this.timer === 'object' && 'unref' in this.timer)
+            this.timer.unref();
+    }
+    async refresh() {
+        try {
+            const headers = { authorization: `Bearer ${this.zen.apiKey}` };
+            if (this.etag)
+                headers['if-none-match'] = this.etag;
+            const res = await fetch(`${this.zen.baseURL}/v1/snapshot`, { headers });
+            if (res.status === 304) {
+                this.fetchedAt = Date.now(); // unchanged — refresh the staleness clock
+                this.markReady();
+                return;
+            }
+            if (!res.ok)
+                return;
+            const out = (await res.json());
+            const next = new Map();
+            for (const f of out.flags ?? []) {
+                next.set(f.key, { state: f.state, rampPercent: f.rampPercent, reason: 'snapshot' });
+            }
+            this.snapshot = next;
+            this.fetchedAt = Date.now();
+            this.etag = res.headers.get('etag') ?? '';
+            this.markReady();
+        }
+        catch {
+            /* keep last snapshot; staleness guard below handles prolonged outages */
+        }
+    }
+    async evaluate(spec, _rc) {
+        if (!this.snapshot || Date.now() - this.fetchedAt > this.maxStaleMs) {
+            throw new Error('zen flags: snapshot unavailable or stale');
+        }
+        return (this.snapshot.get((0, spec_1.specKey)(spec)) ?? {
+            state: 'DISABLED_HARD',
+            reason: 'unknown flag -> baseline',
+        });
+    }
+    async close() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+}
+exports.CachedZenProvider = CachedZenProvider;

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@zenxdigitalholdings/zenflags",
+  "version": "0.2.0",
+  "description": "Zen Flags SDK \u2014 feature flags for Zen products, evaluated in-process from the Zen flags server.",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs/index.d.ts",
+      "default": "./dist/nestjs/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/evaluator.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10",
+    "@nestjs/core": ">=10",
+    "reflect-metadata": ">=0.1",
+    "rxjs": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.4.0",
+    "@nestjs/core": "^10.4.0",
+    "@types/node": "^22.9.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/zenrails/featureflagging.git",
+    "directory": "sdks/ts"
+  },
+  "homepage": "https://atlasrails.online",
+  "keywords": [
+    "feature-flags",
+    "zen",
+    "zenrails"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}