@voltro/plugin-flags 0.86.0 → 0.87.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ColumnBuilder } from '@voltro/database';
+import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
 import { FieldDefinitions } from '@voltro/database';
@@ -26,6 +27,8 @@ declare interface BufferEntry {
     lastAt: number;
 }
 
+export declare const captureConfigService: (input: ConfigService) => ConfigService;
+
 /**
  * Check every typed flag that names an experiment against the experiments the
  * app declared. Pure — returns the problems rather than throwing, so the same
@@ -42,6 +45,94 @@ export declare const classifyShape: (value: FlagValue, now: number) => {
     readonly reason: string;
 };
 
+export declare interface ConfigEntry<out A> {
+    readonly key: string;
+    readonly flag: TypedFlag<A>;
+    readonly public: boolean;
+    readonly restartRequired: 'room' | 'live';
+    readonly min: number | null;
+    readonly max: number | null;
+}
+
+/** Typed Config failures contain no private value, subject or decode body. */
+export declare class ConfigError extends ConfigError_base {
+}
+
+declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_value", "not_found", "unavailable"]>;
+}>, YieldableError>;
+
+declare interface ConfigKeySummary {
+    readonly key: string;
+    readonly valueType: string;
+    readonly public: boolean;
+    readonly restartRequired: 'room' | 'live';
+    readonly min: number | null;
+    readonly max: number | null;
+}
+
+export declare class ConfigPort extends ConfigPort_base {
+}
+
+declare const ConfigPort_base: Context.ServiceClass<ConfigPort, "@voltro/ConfigPort", ConfigService>;
+
+declare interface ConfigResolutionContext {
+    readonly entry: ConfigEntry<unknown>;
+    readonly value: FlagValue;
+    readonly subject: FlagSubject;
+    readonly now: number;
+}
+
+export declare type ConfigResolver = (context: ConfigResolutionContext) => unknown;
+
+export declare interface ConfigService {
+    readonly get: (key: string, subject: FlagSubject) => Effect.Effect<unknown, ConfigError>;
+    readonly mine: (subject: FlagSubject) => Effect.Effect<Readonly<Record<string, unknown>>, ConfigError>;
+    /** Snapshot outside a Room tick, then pass it through creation or app messages. */
+    readonly snapshot: (subject: FlagSubject, mode: 'room' | 'live') => Effect.Effect<Readonly<Record<string, unknown>>, ConfigError>;
+}
+
+export declare interface ConfigSetInput {
+    readonly key: string;
+    readonly value: unknown;
+    readonly actor?: string | null;
+}
+
+export declare interface ConfigSpec<S extends Schema.Top> {
+    readonly schema: S;
+    readonly default: NoInfer<Schema.Schema.Type<S>>;
+    readonly min?: number;
+    readonly max?: number;
+    readonly public?: boolean;
+    readonly restartRequired?: 'room' | 'live';
+    readonly variants?: DefineFlagSpec<S>['variants'];
+    readonly targeting?: readonly FlagTargetingRule[];
+    readonly rollout?: number;
+    readonly rolloutBy?: 'subject' | 'tenant';
+    readonly schedule?: FlagSchedule;
+}
+
+export declare const configSummary: (config: DefinedConfig) => readonly ConfigKeySummary[];
+
+export declare const configSystemContract: Readonly<{
+    slots: {
+        resolver: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+    };
+    ports: {
+        config: {
+            tagExport: string;
+            fakeLayerExport: string;
+            fixtureExport: string;
+        };
+    };
+    events: readonly string[];
+}>;
+
+export declare const configValue: <Values extends Readonly<Record<string, unknown>>, Key extends keyof Values & string>(catalog: DefinedConfig<Values>, service: ConfigService, key: Key, subject: FlagSubject) => Effect.Effect<Values[Key], ConfigError>;
+
 /** Adapt the framework `DataStore` to a {@link FlagUsageStore}. */
 export declare const dataStoreFlagUsageStore: (store: DataStore) => FlagUsageStore;
 
@@ -50,6 +141,19 @@ export declare const dataStoreFlagUsageStore: (store: DataStore) => FlagUsageSto
  *  per active flag per replica. */
 export declare const DEFAULT_FLAG_USAGE_FLUSH_MS = 300000;
 
+/** Reuse Flag targeting/schedule/bucketing. Off Config always serves its default. */
+export declare const defaultConfigResolver: ConfigResolver;
+
+export declare const defineConfig: <const Schemas extends Readonly<Record<string, Schema.Top>>>(input: { readonly [Key in keyof Schemas]: ConfigSpec<Schemas[Key]>; }) => DefinedConfig<{ readonly [Key in keyof Schemas]: Schema.Schema.Type<Schemas[Key]>; }>;
+
+export declare interface DefinedConfig<Values extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+    readonly entries: {
+        readonly [Key in keyof Values]: ConfigEntry<Values[Key]>;
+    };
+    readonly keys: readonly (keyof Values & string)[];
+    readonly typedFlags: readonly AnyTypedFlag[];
+}
+
 /**
  * Declare a flag with a value type.
  *
@@ -194,6 +298,9 @@ export declare interface FlagAuditRow {
     readonly enabled: boolean;
     readonly previousEnabled: boolean | null;
     readonly actorId: string | null;
+    /** Typed Config changes only: the value set and the previous override variants. */
+    readonly value?: unknown;
+    readonly previousValue?: unknown;
     readonly at: Date;
 }
 
@@ -209,9 +316,22 @@ export declare const flagAuditTable: Table<"_voltro_feature_flag_audit", FieldDe
     readonly previousEnabled: ColumnBuilder<boolean | null, "boolean", boolean>;
     /** The acting subject id (nullable — anonymous / system flip). */
     readonly actorId: ColumnBuilder<string | null, "text", boolean>;
+    /** A typed Config change: the value set and the override variants it replaced (null for a flip). */
+    readonly value: ColumnBuilder<unknown, "json", boolean>;
+    readonly previousValue: ColumnBuilder<unknown, "json", boolean>;
     readonly at: ColumnBuilder<Date, "timestamp", true>;
 }>, true, "byFlagAuditFlag" | "byFlagAuditAt">;
 
+/** A read facade over this plugin instance's actual merged Flag snapshot. */
+export declare const flagConfigService: (input: {
+    readonly catalog: DefinedConfig;
+    readonly flags: () => Readonly<Record<string, FlagValue>>;
+    readonly active: () => boolean;
+    readonly revision: () => number;
+    readonly resolver?: ConfigResolver;
+    readonly replacement?: ConfigService;
+}) => ConfigService;
+
 /** The result of decoding an UNTRUSTED value (a DB override, a dashboard edit)
  *  against a flag's Schema. Deliberately not an exception: the caller's correct
  *  response is to keep the code-declared value and say so, not to unwind. */
@@ -384,9 +504,30 @@ export declare type FlagShape =
 /** Genuinely does work: a partial rollout, targeting, variants, or a ramp. */
 | 'conditional';
 
-export declare const flagsPlugin: (options?: FlagsPluginOptions) => VoltroPlugin;
+export declare interface FlagsPlugin extends VoltroPlugin {
+    readonly config?: () => ConfigService;
+    /** Set a typed Config value for everyone (validated against its schema, min and max): live at
+     *  once, durable and audited with the actor and the previous variants on the postgres tier. */
+    readonly setConfig?: (input: ConfigSetInput) => Effect.Effect<{
+        readonly key: string;
+        readonly value: unknown;
+    }, ConfigError>;
+    /** Flip a flag's kill-switch: live at once, durable and audited (actor) on the postgres tier.
+     *  The same path as the inspect `/toggle` endpoint; typed Config values are refused. */
+    readonly toggle: (input: FlagToggleInput) => Effect.Effect<FlagToggleReceipt, FlagToggleRefused>;
+}
+
+export declare const flagsPlugin: (options?: FlagsPluginOptions) => FlagsPlugin;
 
 export declare interface FlagsPluginOptions {
+    /** Optional typed Config, evaluated through the same Flag machinery. */
+    readonly config?: DefinedConfig;
+    readonly configVersion?: string;
+    readonly configResolver?: ConfigResolver;
+    /** Complete app-owned Config read port; no default override/policy loan. */
+    readonly configService?: ConfigService;
+    /** Full replacement invalidation sources; [] explicitly owns a static view. */
+    readonly configQuerySources?: readonly string[];
     /** Flags as code. The baseline; a postgres store overlays runtime toggles. */
     readonly flags?: Record<string, FlagValue>;
     /**
@@ -478,6 +619,28 @@ export declare interface FlagTargetingRule {
     readonly metadata?: Record<string, string>;
 }
 
+export declare interface FlagToggleInput {
+    readonly key: string;
+    readonly enabled: boolean;
+    readonly actor?: string | null;
+}
+
+export declare interface FlagToggleReceipt {
+    readonly key: string;
+    readonly enabled: boolean;
+    readonly previous: boolean;
+}
+
+/** A refused kill-switch flip: unknown key, a typed Config value (it has its own writer),
+ *  a store that is not bound yet, or a write whose commit could not be confirmed. */
+declare class FlagToggleRefused extends FlagToggleRefused_base {
+}
+
+declare const FlagToggleRefused_base: Schema.Class<FlagToggleRefused, Schema.TaggedStruct<"FlagToggleRefused", {
+    readonly key: Schema.String;
+    readonly reason: Schema.Literals<readonly ["unknown_flag", "config_value", "not_ready", "unconfirmed"]>;
+}>, YieldableError>;
+
 /**
  * Process-wide evaluation buffer.
  *