@cqrs-ddd/pipeline-feature-flags 0.0.0-stage → 0.5.0

package/dist/helpers/build-attributes.js

@@ -0,0 +1,63 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { getPipelineItem } from '@cqrs-ddd/pipeline';
+import { FEATURE_FLAG_DECISION_ITEM_TOKEN } from '../feature-flag.behavior.js';
+/**
+ * The feature-flag decision of one execution as flat attributes, named after
+ * the OpenTelemetry feature-flag conventions: `feature_flag.key` and
+ * `feature_flag.enabled`, plus `feature_flag.variant` and `feature_flag.reason`
+ * when the provider reported them, and `feature_flag.error_code` only when
+ * evaluation failed. `{}` when `FeatureFlagBehavior` did not run. The targeting
+ * key and the provider's error message are never included.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `FeatureFlagBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildFeatureFlagAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example Audit metadata
+ * `audit()` is declared outside `featureFlag()`, so the record is built after its decision:
+ * ```ts
+ * @pipeline.wrap(
+ *   { kind: 'command' },
+ *   audit({ action: 'order.create', metadata: buildFeatureFlagAttributes }),
+ *   featureFlag({ flag: 'checkout' }),
+ * )
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildFeatureFlagAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export function buildFeatureFlagAttributes(context) {
+    const decision = getPipelineItem(context, FEATURE_FLAG_DECISION_ITEM_TOKEN);
+    if (!decision)
+        return {};
+    return {
+        'feature_flag.key': decision.flagKey,
+        'feature_flag.enabled': decision.enabled,
+        ...(decision.variant ? { 'feature_flag.variant': decision.variant } : {}),
+        ...(decision.reason ? { 'feature_flag.reason': decision.reason } : {}),
+        ...(decision.errorCode
+            ? { 'feature_flag.error_code': decision.errorCode }
+            : {}),
+    };
+}
+//# sourceMappingURL=build-attributes.js.map

package/dist/helpers/build-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.js","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,eAAe,EAAyB,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,gCAAgC,EAAE,MAAM,6BAA6B,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAyB;IAEzB,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC;IAC5E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,OAAO;QACL,kBAAkB,EAAE,QAAQ,CAAC,OAAO;QACpC,sBAAsB,EAAE,QAAQ,CAAC,OAAO;QACxC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,sBAAsB,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,QAAQ,CAAC,SAAS;YACpB,CAAC,CAAC,EAAE,yBAAyB,EAAE,QAAQ,CAAC,SAAS,EAAE;YACnD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC"}

package/dist/helpers/evaluation-context.d.ts

@@ -0,0 +1,17 @@
+import type { IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { EvaluationContext } from '@openfeature/server-sdk';
+import type { EvaluationContextFactory, TargetingKeyFactory } from '../interfaces/feature-flags-options.interface.js';
+/**
+ * Base OpenFeature attributes derived from the live pipeline request. It sets no
+ * `targetingKey`; that comes from `targetingKeyFactory`.
+ */
+export declare function baseEvaluationContext(context: IPipelineContext): EvaluationContext;
+/**
+ * Builds an evaluation context in this order:
+ * base pipeline attributes → module context → handler context → targeting-key factory.
+ *
+ * A targeting key already provided by module/handler context is preserved when
+ * the factory returns `undefined`. A non-empty factory result wins when present.
+ */
+export declare function buildEvaluationContext(context: IPipelineContext, moduleContext?: EvaluationContext, handlerContext?: EvaluationContextFactory, targetingKeyFactory?: TargetingKeyFactory): EvaluationContext;
+//# sourceMappingURL=evaluation-context.d.ts.map

package/dist/helpers/evaluation-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation-context.d.ts","sourceRoot":"","sources":["../../src/helpers/evaluation-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,kDAAkD,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,GACxB,iBAAiB,CAQnB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,gBAAgB,EACzB,aAAa,CAAC,EAAE,iBAAiB,EACjC,cAAc,CAAC,EAAE,wBAAwB,EACzC,mBAAmB,CAAC,EAAE,mBAAmB,GACxC,iBAAiB,CAWnB"}

package/dist/helpers/evaluation-context.js

@@ -0,0 +1,33 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Base OpenFeature attributes derived from the live pipeline request. It sets no
+ * `targetingKey`; that comes from `targetingKeyFactory`.
+ */
+export function baseEvaluationContext(context) {
+    return {
+        'pipeline.request.kind': context.requestKind,
+        'pipeline.request.name': context.requestName,
+        'pipeline.handler.name': context.handlerName,
+        'pipeline.correlation_id': context.correlationId,
+        ...(context.tenantId ? { 'pipeline.tenant_id': context.tenantId } : {}),
+    };
+}
+/**
+ * Builds an evaluation context in this order:
+ * base pipeline attributes → module context → handler context → targeting-key factory.
+ *
+ * A targeting key already provided by module/handler context is preserved when
+ * the factory returns `undefined`. A non-empty factory result wins when present.
+ */
+export function buildEvaluationContext(context, moduleContext, handlerContext, targetingKeyFactory) {
+    const result = {
+        ...baseEvaluationContext(context),
+        ...moduleContext,
+        ...handlerContext?.(context),
+    };
+    const targetingKey = targetingKeyFactory?.(context)?.trim();
+    if (targetingKey)
+        result.targetingKey = targetingKey;
+    return result;
+}
+//# sourceMappingURL=evaluation-context.js.map

package/dist/helpers/evaluation-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation-context.js","sourceRoot":"","sources":["../../src/helpers/evaluation-context.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAStE;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAyB;IAEzB,OAAO;QACL,uBAAuB,EAAE,OAAO,CAAC,WAAW;QAC5C,uBAAuB,EAAE,OAAO,CAAC,WAAW;QAC5C,uBAAuB,EAAE,OAAO,CAAC,WAAW;QAC5C,yBAAyB,EAAE,OAAO,CAAC,aAAa;QAChD,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAyB,EACzB,aAAiC,EACjC,cAAyC,EACzC,mBAAyC;IAEzC,MAAM,MAAM,GAAsB;QAChC,GAAG,qBAAqB,CAAC,OAAO,CAAC;QACjC,GAAG,aAAa;QAChB,GAAG,cAAc,EAAE,CAAC,OAAO,CAAC;KAC7B,CAAC;IAEF,MAAM,YAAY,GAAG,mBAAmB,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC;IAC5D,IAAI,YAAY;QAAE,MAAM,CAAC,YAAY,GAAG,YAAY,CAAC;IAErD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/helpers/feature-flag-client.d.ts

@@ -0,0 +1,27 @@
+import { type Client } from '@openfeature/server-sdk';
+import type { FeatureFlagClientOptions } from '../interfaces/feature-flags-options.interface.js';
+/**
+ * Resolves the OpenFeature client a {@link FeatureFlagBehavior} evaluates with: the given
+ * `client`, or the client of `domain` (the default client without one) after registering
+ * `provider`, waiting for it to be ready unless `waitForReady` is `false`.
+ *
+ * @example
+ * ```ts
+ * const client = await createFeatureFlagClient({ provider: new UnleashProvider(config) });
+ * const behavior = new FeatureFlagBehavior(client);
+ * ```
+ */
+export declare function createFeatureFlagClient(options?: FeatureFlagClientOptions): Promise<Client>;
+/**
+ * Unregisters the provider that {@link createFeatureFlagClient} registered for the same
+ * `options`, for shutdown: the domain falls back to OpenFeature's no-op provider. Does
+ * nothing when `options` gave a `client`, gave no `provider`, or another provider has
+ * replaced it since.
+ *
+ * @example
+ * ```ts
+ * process.on('SIGTERM', () => releaseFeatureFlagProvider(options));
+ * ```
+ */
+export declare function releaseFeatureFlagProvider(options?: FeatureFlagClientOptions): Promise<void>;
+//# sourceMappingURL=feature-flag-client.d.ts.map

package/dist/helpers/feature-flag-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag-client.d.ts","sourceRoot":"","sources":["../../src/helpers/feature-flag-client.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,MAAM,EAGZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kDAAkD,CAAC;AAEjG;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/helpers/feature-flag-client.js

@@ -0,0 +1,57 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { NOOP_PROVIDER, OpenFeature, } from '@openfeature/server-sdk';
+/**
+ * Resolves the OpenFeature client a {@link FeatureFlagBehavior} evaluates with: the given
+ * `client`, or the client of `domain` (the default client without one) after registering
+ * `provider`, waiting for it to be ready unless `waitForReady` is `false`.
+ *
+ * @example
+ * ```ts
+ * const client = await createFeatureFlagClient({ provider: new UnleashProvider(config) });
+ * const behavior = new FeatureFlagBehavior(client);
+ * ```
+ */
+export async function createFeatureFlagClient(options = {}) {
+    if (options.client)
+        return options.client;
+    if (options.provider) {
+        if (options.waitForReady === false) {
+            options.domain
+                ? OpenFeature.setProvider(options.domain, options.provider)
+                : OpenFeature.setProvider(options.provider);
+        }
+        else {
+            await (options.domain
+                ? OpenFeature.setProviderAndWait(options.domain, options.provider)
+                : OpenFeature.setProviderAndWait(options.provider));
+        }
+    }
+    return options.domain
+        ? OpenFeature.getClient(options.domain)
+        : OpenFeature.getClient();
+}
+/**
+ * Unregisters the provider that {@link createFeatureFlagClient} registered for the same
+ * `options`, for shutdown: the domain falls back to OpenFeature's no-op provider. Does
+ * nothing when `options` gave a `client`, gave no `provider`, or another provider has
+ * replaced it since.
+ *
+ * @example
+ * ```ts
+ * process.on('SIGTERM', () => releaseFeatureFlagProvider(options));
+ * ```
+ */
+export async function releaseFeatureFlagProvider(options = {}) {
+    const { client, provider, domain } = options;
+    if (client || !provider)
+        return;
+    const current = domain
+        ? OpenFeature.getProvider(domain)
+        : OpenFeature.getProvider();
+    if (current !== provider)
+        return;
+    await (domain
+        ? OpenFeature.setProviderAndWait(domain, NOOP_PROVIDER)
+        : OpenFeature.setProviderAndWait(NOOP_PROVIDER));
+}
+//# sourceMappingURL=feature-flag-client.js.map

package/dist/helpers/feature-flag-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag-client.js","sourceRoot":"","sources":["../../src/helpers/feature-flag-client.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAEL,aAAa,EACb,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAGjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAO,GAA6B,EAAE;IAEtC,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC;IAC1C,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,IAAI,OAAO,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;YACnC,OAAO,CAAC,MAAM;gBACZ,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC;gBAC3D,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,OAAO,CAAC,MAAM;gBACnB,CAAC,CAAC,WAAW,CAAC,kBAAkB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC;gBAClE,CAAC,CAAC,WAAW,CAAC,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC,MAAM;QACnB,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC;QACvC,CAAC,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,OAAO,GAA6B,EAAE;IAEtC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC7C,IAAI,MAAM,IAAI,CAAC,QAAQ;QAAE,OAAO;IAChC,MAAM,OAAO,GAAG,MAAM;QACpB,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC;QACjC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;IAC9B,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO;IACjC,MAAM,CAAC,MAAM;QACX,CAAC,CAAC,WAAW,CAAC,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC;QACvD,CAAC,CAAC,WAAW,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/helpers/feature-flag.intent.d.ts

@@ -0,0 +1,22 @@
+import type { PipelineBehaviorTuple } from '@cqrs-ddd/pipeline';
+import { FeatureFlagBehavior } from '../feature-flag.behavior.js';
+import type { FeatureFlagBehaviorOptions } from '../interfaces/feature-flags-options.interface.js';
+export type FeatureFlagIntentOptions = FeatureFlagBehaviorOptions & {
+    flag: string;
+};
+/**
+ * Returns a feature-flag behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options Required flag key plus evaluation and fallback options.
+ * @returns The behavior class and options tuple. A disabled flag prevents handler
+ * execution; the behavior returns the configured fallback or throws FeatureDisabledError.
+ * @example
+ * ```ts
+ * @pipeline.wrap({ kind: 'command' }, featureFlag({
+ *   flag: 'user-registration',
+ *   defaultValue: false,
+ *   fallback: () => ({ disabled: true }),
+ * }))
+ * ```
+ */
+export declare function featureFlag(options: FeatureFlagIntentOptions): PipelineBehaviorTuple<FeatureFlagBehavior, FeatureFlagBehaviorOptions>;
+//# sourceMappingURL=feature-flag.intent.d.ts.map

package/dist/helpers/feature-flag.intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.intent.d.ts","sourceRoot":"","sources":["../../src/helpers/feature-flag.intent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kDAAkD,CAAC;AAEnG,MAAM,MAAM,wBAAwB,GAAG,0BAA0B,GAAG;IAClE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,wBAAwB,GAChC,qBAAqB,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CAExE"}

package/dist/helpers/feature-flag.intent.js

@@ -0,0 +1,20 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { FeatureFlagBehavior } from '../feature-flag.behavior.js';
+/**
+ * Returns a feature-flag behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options Required flag key plus evaluation and fallback options.
+ * @returns The behavior class and options tuple. A disabled flag prevents handler
+ * execution; the behavior returns the configured fallback or throws FeatureDisabledError.
+ * @example
+ * ```ts
+ * @pipeline.wrap({ kind: 'command' }, featureFlag({
+ *   flag: 'user-registration',
+ *   defaultValue: false,
+ *   fallback: () => ({ disabled: true }),
+ * }))
+ * ```
+ */
+export function featureFlag(options) {
+    return [FeatureFlagBehavior, options];
+}
+//# sourceMappingURL=feature-flag.intent.js.map

package/dist/helpers/feature-flag.intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.intent.js","sourceRoot":"","sources":["../../src/helpers/feature-flag.intent.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAOlE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CACzB,OAAiC;IAEjC,OAAO,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,21 @@
+import type { FeatureDisabledError } from './errors/feature-disabled.error.js';
+/** An HTTP answer for an error: status, JSON body and headers. */
+export interface HttpResponse {
+    status: number;
+    body: Record<string, unknown>;
+    headers: Record<string, string>;
+}
+/**
+ * The HTTP answer for a {@link FeatureDisabledError}: `403 Forbidden` naming the flag, or
+ * with `hideFeature` a plain `404 Not Found` that does not reveal the feature exists.
+ *
+ * @example
+ * ```ts
+ * const { status, body } = toHttpResponse(error, { hideFeature: true });
+ * res.status(status).json(body);
+ * ```
+ */
+export declare function toHttpResponse(error: FeatureDisabledError, options?: {
+    hideFeature?: boolean;
+}): HttpResponse;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE/E,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,oBAAoB,EAC3B,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,YAAY,CAkBd"}

package/dist/http.js

@@ -0,0 +1,31 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * The HTTP answer for a {@link FeatureDisabledError}: `403 Forbidden` naming the flag, or
+ * with `hideFeature` a plain `404 Not Found` that does not reveal the feature exists.
+ *
+ * @example
+ * ```ts
+ * const { status, body } = toHttpResponse(error, { hideFeature: true });
+ * res.status(status).json(body);
+ * ```
+ */
+export function toHttpResponse(error, options = {}) {
+    if (options.hideFeature) {
+        return {
+            status: 404,
+            body: { statusCode: 404, error: 'Not Found', message: 'Not Found' },
+            headers: {},
+        };
+    }
+    return {
+        status: 403,
+        body: {
+            statusCode: 403,
+            error: 'Forbidden',
+            message: error.message,
+            flag: error.flag,
+        },
+        headers: {},
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAWtE;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,KAA2B,EAC3B,OAAO,GAA8B,EAAE;IAEvC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO;YACL,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE;YACnE,OAAO,EAAE,EAAE;SACZ,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,GAAG;QACX,IAAI,EAAE;YACJ,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,WAAW;YAClB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;SACjB;QACD,OAAO,EAAE,EAAE;KACZ,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenFeature gates for wrapped functions and methods: the behavior, the client factory and `featureFlag()`. The HTTP mapping of its errors is the `@cqrs-ddd/pipeline-feature-flags/http` entry point.
+ *
+ * @module main
+ */
+export { FeatureDisabledError } from './errors/feature-disabled.error.js';
+export { FeatureFlagEvaluationError } from './errors/feature-flag-evaluation.error.js';
+export { FEATURE_FLAG_DECISION_ITEM, FEATURE_FLAG_DECISION_ITEM_TOKEN, FEATURE_FLAG_ITEM, FEATURE_FLAG_ITEM_TOKEN, FEATURE_FLAG_KEY_ITEM, FEATURE_FLAG_KEY_ITEM_TOKEN, FeatureFlagBehavior, } from './feature-flag.behavior.js';
+export { buildFeatureFlagAttributes } from './helpers/build-attributes.js';
+export { baseEvaluationContext, buildEvaluationContext, } from './helpers/evaluation-context.js';
+export { type FeatureFlagIntentOptions, featureFlag, } from './helpers/feature-flag.intent.js';
+export { createFeatureFlagClient, releaseFeatureFlagProvider, } from './helpers/feature-flag-client.js';
+export type { EvaluationContextFactory, FeatureFallbackFactory, FeatureFlagBehaviorOptions, FeatureFlagClientOptions, FeatureFlagDecision, FeatureFlagErrorPolicy, TargetingKeyFactory, } from './interfaces/feature-flags-options.interface.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACvF,OAAO,EACL,0BAA0B,EAC1B,gCAAgC,EAChC,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,KAAK,wBAAwB,EAC7B,WAAW,GACZ,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,iDAAiD,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * OpenFeature gates for wrapped functions and methods: the behavior, the client factory and `featureFlag()`. The HTTP mapping of its errors is the `@cqrs-ddd/pipeline-feature-flags/http` entry point.
+ *
+ * @module main
+ */
+export { FeatureDisabledError } from './errors/feature-disabled.error.js';
+export { FeatureFlagEvaluationError } from './errors/feature-flag-evaluation.error.js';
+export { FEATURE_FLAG_DECISION_ITEM, FEATURE_FLAG_DECISION_ITEM_TOKEN, FEATURE_FLAG_ITEM, FEATURE_FLAG_ITEM_TOKEN, FEATURE_FLAG_KEY_ITEM, FEATURE_FLAG_KEY_ITEM_TOKEN, FeatureFlagBehavior, } from './feature-flag.behavior.js';
+export { buildFeatureFlagAttributes } from './helpers/build-attributes.js';
+export { baseEvaluationContext, buildEvaluationContext, } from './helpers/evaluation-context.js';
+export { featureFlag, } from './helpers/feature-flag.intent.js';
+export { createFeatureFlagClient, releaseFeatureFlagProvider, } from './helpers/feature-flag-client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACvF,OAAO,EACL,0BAA0B,EAC1B,gCAAgC,EAChC,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,WAAW,GACZ,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,kCAAkC,CAAC"}

package/dist/interfaces/feature-flags-options.interface.d.ts

@@ -0,0 +1,154 @@
+import type { IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { Client, EvaluationContext, Provider } from '@openfeature/server-sdk';
+/**
+ * Builds an OpenFeature {@link EvaluationContext} from the current pipeline
+ * request — letting flag targeting rules key off the live request/handler.
+ */
+export type EvaluationContextFactory = (context: IPipelineContext) => EvaluationContext;
+/**
+ * Resolves a stable OpenFeature targeting key from the current pipeline request.
+ *
+ * For percentage rollouts this should normally be a user, account, tenant or
+ * device identifier that stays stable across requests.
+ */
+export type TargetingKeyFactory = (context: IPipelineContext) => string | undefined;
+/**
+ * Returns a fallback value to emit when the gating flag is disabled, instead of
+ * throwing {@link FeatureDisabledError}. Receives the pipeline context so the
+ * fallback can be request-aware.
+ */
+export type FeatureFallbackFactory = (context: IPipelineContext) => unknown | Promise<unknown>;
+/** Controls how OpenFeature provider evaluation failures are handled. */
+export type FeatureFlagErrorPolicy = 'use-default' | 'throw';
+/**
+ * Detailed result of a feature-flag evaluation, recorded on the pipeline
+ * context so logging/audit/telemetry or later behaviors can inspect the exact
+ * provider decision without re-evaluating the flag.
+ */
+export interface FeatureFlagDecision {
+    /** Evaluated OpenFeature flag key. */
+    flagKey: string;
+    /** Raw boolean value returned by OpenFeature (or its configured default value). */
+    value: boolean;
+    /** Final gate decision after optional variant filtering. */
+    enabled: boolean;
+    /** Provider-selected variant, when the provider reports one. */
+    variant?: string;
+    /** OpenFeature resolution reason, when reported by the provider. */
+    reason?: string;
+    /** OpenFeature provider error code, if evaluation failed. */
+    errorCode?: string;
+    /** Provider error message, if evaluation failed. */
+    errorMessage?: string;
+    /** Stable targeting key used for this evaluation, if one was supplied. */
+    targetingKey?: string;
+}
+/**
+ * Per-handler feature-flag options, supplied through
+ * `pipeline.wrap(options, [FeatureFlagBehavior, options])` and/or as defaults,
+ * the second argument of the {@link FeatureFlagBehavior} constructor.
+ */
+export interface FeatureFlagBehaviorOptions {
+    /**
+     * Boolean flag key that gates the handler. When omitted the behavior is a
+     * no-op (the handler always runs) — useful for setting only constructor defaults.
+     */
+    flag?: string;
+    /**
+     * Value used when the flag cannot be resolved (provider error, unknown key,
+     * not yet ready). Defaults to `false` (fail-closed).
+     */
+    defaultValue?: boolean;
+    /**
+     * When the flag resolves to disabled, return this value instead of throwing
+     * {@link FeatureDisabledError}. Use it to degrade gracefully, for example by
+     * returning an empty read model or another explicitly supported fallback.
+     */
+    fallback?: FeatureFallbackFactory;
+    /**
+     * Builds extra OpenFeature targeting context for this handler, merged on top
+     * of the base context (derived from the request) and the constructor's context.
+     *
+     * @example
+     * ```ts
+     * @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, {
+     *   flag: 'new-checkout',
+     *   context: (ctx) => ({
+     *     plan: ctx.items.get('plan') as string,
+     *     country: ctx.items.get('country') as string,
+     *   }),
+     * }])
+     * ```
+     */
+    context?: EvaluationContextFactory;
+    /**
+     * Stable identity used for percentage rollouts / sticky targeting.
+     *
+     * Handler-level `targetingKeyFactory` overrides the constructor's resolver.
+     * Correlation IDs are intentionally **not** used automatically because they
+     * normally change on every request and can move the same user between rollout
+     * cohorts.
+     *
+     * @example User-sticky rollout
+     * ```ts
+     * @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, {
+     *   flag: 'new-checkout',
+     *   targetingKeyFactory: (ctx) =>
+     *     ctx.items.get('userId') as string | undefined,
+     * }])
+     * ```
+     */
+    targetingKeyFactory?: TargetingKeyFactory;
+    /**
+     * Optional allow-list of provider variants. When set, a boolean `true` only
+     * enables the handler if the provider also resolved one of these variants.
+     *
+     * This is useful when one boolean flag carries named cohorts such as
+     * `control`, `treatment-a`, and `treatment-b`.
+     *
+     * @example
+     * ```ts
+     * @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, {
+     *   flag: 'checkout-experiment',
+     *   allowedVariants: ['treatment-a'],
+     * }])
+     * ```
+     */
+    allowedVariants?: readonly string[];
+    /**
+     * Provider evaluation-error handling.
+     *
+     * - `use-default` — follow OpenFeature's default-value semantics and continue
+     *   evaluating the final gate using `defaultValue` (default).
+     * - `throw` — surface {@link FeatureFlagEvaluationError} instead of silently
+     *   treating a provider failure like an ordinary disabled flag.
+     *
+     * @default 'use-default'
+     */
+    errorPolicy?: FeatureFlagErrorPolicy;
+}
+/** Where {@link createFeatureFlagClient} takes the OpenFeature client from. */
+export interface FeatureFlagClientOptions {
+    /**
+     * Escape hatch: a fully constructed OpenFeature {@link Client}. Takes
+     * precedence over {@link provider}.
+     */
+    client?: Client;
+    /**
+     * An OpenFeature {@link Provider} to register — e.g. an Unleash or Flagsmith
+     * provider. Registered with `setProviderAndWait`, or `setProvider` when
+     * {@link waitForReady} is `false`, before the client is resolved.
+     */
+    provider?: Provider;
+    /**
+     * OpenFeature domain (named client) to bind the provider/client to. Lets you
+     * run multiple providers side by side. Defaults to the unnamed default client.
+     */
+    domain?: string;
+    /**
+     * Whether to await provider readiness via `setProviderAndWait`. Defaults to
+     * `true`. Ignored when {@link client} is supplied.
+     */
+    waitForReady?: boolean;
+}
+//# sourceMappingURL=feature-flags-options.interface.d.ts.map

package/dist/interfaces/feature-flags-options.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags-options.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/feature-flags-options.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EACV,MAAM,EACN,iBAAiB,EACjB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,gBAAgB,KACtB,iBAAiB,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,SAAS,CAAC;AAExB;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,OAAO,EAAE,gBAAgB,KACtB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,yEAAyE;AACzE,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,OAAO,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,KAAK,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAElC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAEnC;;;;;;;;;;;;;;;;OAgBG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAE1C;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,sBAAsB,CAAC;CACtC;AAED,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB"}

package/dist/interfaces/feature-flags-options.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=feature-flags-options.interface.js.map

package/dist/interfaces/feature-flags-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags-options.interface.js","sourceRoot":"","sources":["../../src/interfaces/feature-flags-options.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@cqrs-ddd/pipeline-feature-flags",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "Feature flags for @cqrs-ddd/pipeline through OpenFeature: an operation runs only while its flag is on",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "pipeline",
+    "cqrs",
+    "feature-flags",
+    "feature-toggles",
+    "openfeature",
+    "unleash",
+    "flagsmith",
+    "behavior"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/ddd-cqrs.git",
+    "directory": "packages/pipeline-feature-flags"
+  },
+  "homepage": "https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-feature-flags/",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@openfeature/server-sdk": "^1.13.0",
+    "@cqrs-ddd/pipeline": "^0.5.0"
+  },
+  "devDependencies": {
+    "@openfeature/server-sdk": "^1.23.0",
+    "@vitest/coverage-v8": "^5.0.3",
+    "vitest": "^5.0.3",
+    "@cqrs-ddd/pipeline": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }