@adonis-agora/flags 0.0.0-stage → 0.1.0

package/dist/src/admin.d.ts

@@ -0,0 +1,189 @@
+import { type FlagDefinition, type JsonValue, type Ruleset, type RulesetIssue } from '@adonis-agora/flags-core';
+import { type FlagDeclaration } from './declare.js';
+import { type Actor, type ChangeRequest, type FlagsStore, type RulesetChange, type ScheduledChange } from './stores/store.js';
+/** What an admin action is about, for authorization. */
+export type AdminAction = 'read' | 'write' | 'approve';
+/**
+ * Decides whether `actor` may do `action`. Wire `@adonis-agora/authz` here (e.g. a `flags.write`
+ * permission scoped by environment). Default: allow — protect the console and commands themselves.
+ */
+export type AdminAuthorizer = (actor: Actor, action: AdminAction, target: {
+    environment: string;
+    change?: RulesetChange;
+    request?: ChangeRequest;
+}) => boolean | Promise<boolean>;
+export interface ApprovalsConfig {
+    /** Environments whose changes need a second person. `true` = all. Default: none. */
+    environments: string[] | true;
+}
+export declare class ValidationError extends Error {
+    readonly issues: RulesetIssue[];
+    readonly code = "E_FLAGS_INVALID";
+    constructor(issues: RulesetIssue[]);
+}
+export declare class ForbiddenError extends Error {
+    readonly code = "E_FLAGS_FORBIDDEN";
+}
+export type ProposeResult = {
+    status: 'applied';
+    version: string;
+} | {
+    status: 'pending';
+    request: ChangeRequest;
+};
+/** The definition a declared flag starts with when it is first edited. */
+export declare function definitionFromDeclaration(declaration: FlagDeclaration): FlagDefinition;
+/** Issues where a ruleset contradicts what the code declares (types, variant names). */
+export declare function checkAgainstDeclarations(ruleset: Ruleset, declarations: Record<string, FlagDeclaration>): RulesetIssue[];
+export interface StaleFlag {
+    key: string;
+    reasons: Array<'unused' | 'expired' | 'static' | 'undeclared'>;
+    lastEvaluated?: string;
+    expiresAt?: string;
+    owner?: string;
+}
+/**
+ * Every write to the ruleset goes through here: validation (structure and declared types),
+ * authorization, approvals, and the audit trail the store writes.
+ */
+export declare class FlagsAdmin {
+    #private;
+    readonly store: FlagsStore;
+    private readonly options;
+    constructor(store: FlagsStore, options: {
+        environment: string;
+        declarations: Record<string, FlagDeclaration>;
+        approvals?: ApprovalsConfig;
+        authorize?: AdminAuthorizer;
+        onApplied?: (environment: string, version: string) => void;
+    });
+    get environment(): string;
+    get declarations(): Record<string, FlagDeclaration<JsonValue>>;
+    requiresApproval(environment: string): boolean;
+    /** The ruleset after `change`, validated. Throws {@link ValidationError}. */
+    preview(change: RulesetChange, environment?: string): Promise<Ruleset>;
+    /** Applies a change, or files a change request when the environment needs approval. */
+    propose(change: RulesetChange, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /** Approves and applies a pending request. The requester cannot approve their own. */
+    approve(id: string, actor: Actor, note?: string): Promise<{
+        version: string;
+        request: ChangeRequest;
+    }>;
+    reject(id: string, actor: Actor, note?: string): Promise<ChangeRequest>;
+    cancel(id: string, actor: Actor): Promise<ChangeRequest>;
+    /** The stored definition, or the one the declaration implies. */
+    definition(key: string, environment?: string): Promise<FlagDefinition>;
+    /**
+     * Saves a flag's targeting. A console declaration already stored on the flag is kept when the new
+     * definition does not carry one, so editing targeting never drops a flag's type and default.
+     */
+    saveFlag(key: string, definition: FlagDefinition, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /**
+     * Creates a flag from the console: its declaration (type, default, metadata) and a starting
+     * targeting that serves the default to everyone. Refused when the key is declared in code or
+     * already exists in this environment.
+     */
+    createFlag(key: string, declaration: FlagDeclaration, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /** Changes a console flag's declaration (description, owner, expiry, default, …). */
+    updateDeclaration(key: string, patch: Partial<FlagDeclaration>, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    deleteFlag(key: string, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /**
+     * The kill switch: `false` serves `offVariant` to everyone regardless of targeting; `true` turns
+     * targeting back on. To serve `on` to everyone, use {@link turnOn}.
+     */
+    setEnabled(key: string, enabled: boolean, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /** Boolean flags: serves `on` to everyone (targeting rules and overrides still apply first). */
+    turnOn(key: string, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /** Boolean flags: serves `off` to everyone not matched by a rule or override. */
+    turnOff(key: string, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /** Serves one variant to everyone (clears any split on the fallthrough). */
+    setVariant(key: string, variant: string, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /**
+     * Serves `value` to everyone: the variant with that value when there is one, else a new variant
+     * named after it. For number, string and JSON flags without a variant for the value yet
+     * (`node ace flags:set max_uploads 25`).
+     */
+    setValue(key: string, value: JsonValue, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /**
+     * Percentage rollout of a boolean flag: `percent`% get `on`. Keeps the `on` arm first so raising
+     * the percentage only adds people (see `pickVariant`).
+     */
+    setRollout(key: string, percent: number, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /** Forces a variant for one subject (`null` removes the override). */
+    setOverride(key: string, subject: string, variant: string | null, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    schedule(input: Omit<ScheduledChange, 'id' | 'status' | 'createdBy' | 'environment'> & {
+        environment?: string;
+    }, actor: Actor): Promise<ScheduledChange>;
+    /** A gradual rollout: one schedule per step (`[{ at, percent }]`). */
+    scheduleRollout(key: string, steps: Array<{
+        at: Date;
+        percent: number;
+    }>, actor: Actor, options?: {
+        environment?: string;
+    }): Promise<ScheduledChange[]>;
+    cancelSchedule(id: string, actor: Actor): Promise<ScheduledChange>;
+    /**
+     * Executes due schedules. Each is claimed atomically, so replicas running this concurrently apply
+     * each step once. Scheduled changes skip approvals: they were authorized when scheduled.
+     */
+    runDueSchedules(now?: Date): Promise<Array<{
+        id: string;
+        ok: boolean;
+        error?: string;
+    }>>;
+    exportRuleset(environment?: string): Promise<Ruleset>;
+    importRuleset(ruleset: Pick<Ruleset, 'flags'> & Partial<Ruleset>, actor: Actor, options?: {
+        environment?: string;
+        note?: string;
+    }): Promise<ProposeResult>;
+    /** Copies one environment's ruleset over another's (staging → production). */
+    promote(from: string, to: string, actor: Actor, note?: string): Promise<ProposeResult>;
+    /**
+     * Flags that probably should be removed: not evaluated for `unusedDays` (`unused`), past their
+     * declared expiry (`expired`), serving one value to everyone for `staticDays` — fully rolled out
+     * or killed (`static`), or in the ruleset but declared by no app (`undeclared`).
+     */
+    stale(options?: {
+        environment?: string;
+        unusedDays?: number;
+        staticDays?: number;
+        now?: Date;
+    }): Promise<StaleFlag[]>;
+}
+//# sourceMappingURL=admin.d.ts.map

package/dist/src/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/admin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,SAAS,EAEd,KAAK,OAAO,EACZ,KAAK,YAAY,EAElB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,cAAc,CAAC;AACtE,OAAO,EACL,KAAK,KAAK,EAEV,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAA;CAAE,KAC7E,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC/B;AAKD,qBAAa,eAAgB,SAAQ,KAAK;IAE5B,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE;IAD3C,QAAQ,CAAC,IAAI,qBAAqB;IAClC,YAAqB,MAAM,EAAE,YAAY,EAAE,EAE1C;CACF;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,uBAAuB;CACrC;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAElD,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,eAAe,GAAG,cAAc,CAwBtF;AAED,wFAAwF;AACxF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAC5C,YAAY,EAAE,CA4BhB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAC,CAAC;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,UAAU;;IAEnB,QAAQ,CAAC,KAAK,EAAE,UAAU;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAF1B,YACW,KAAK,EAAE,UAAU,EACT,OAAO,EAAE;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QAC9C,SAAS,CAAC,EAAE,eAAe,CAAC;QAC5B,SAAS,CAAC,EAAE,eAAe,CAAC;QAC5B,SAAS,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KAC5D,EACC;IAEJ,IAAI,WAAW,WAEd;IAED,IAAI,YAAY,+CAEf;IAED,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAG7C;IAkBD,6EAA6E;IACvE,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,SAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAarF;IAED,uFAAuF;IACjF,OAAO,CACX,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GACpD,OAAO,CAAC,aAAa,CAAC,CAkBxB;IAED,sFAAsF;IAChF,OAAO,CACX,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,KAAK,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAE,CAAC,CAgCtD;IAEK,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAY5E;IAEK,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,CAO7D;IAED,iEAAiE;IAC3D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,SAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQrF;IAED;;;OAGG;IACG,QAAQ,CACZ,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAUtD;IAED;;;;OAIG;IACG,UAAU,CACd,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GACpD,OAAO,CAAC,aAAa,CAAC,CAsBxB;IAED,qFAAqF;IAC/E,iBAAiB,CACrB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,EAC/B,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GACpD,OAAO,CAAC,aAAa,CAAC,CAwBxB;IAED,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,0BAEtF;IAED;;;OAGG;IACG,UAAU,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAItD;IAED,gGAAgG;IAChG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAEtF;IAED,iFAAiF;IACjF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAEvF;IAED,4EAA4E;IACtE,UAAU,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAStD;IAED;;;;OAIG;IACG,QAAQ,CACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAkBtD;IAED;;;OAGG;IACG,UAAU,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAoBtD;IAED,sEAAsE;IAChE,WAAW,CACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,0BAOtD;IAIK,QAAQ,CACZ,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC,GAAG;QAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,EACD,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,eAAe,CAAC,CAU1B;IAED,sEAAsE;IAChE,eAAe,CACnB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,EAC3C,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB5B;IAEK,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,eAAe,CAAC,CAMvE;IAED;;;OAGG;IACG,eAAe,CACnB,GAAG,OAAa,GACf,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CA2D7D;IAIK,aAAa,CAAC,WAAW,SAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpE;IAEK,aAAa,CACjB,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,EAClD,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GACpD,OAAO,CAAC,aAAa,CAAC,CAmBxB;IAED,8EAA8E;IACxE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAI3F;IAID;;;;OAIG;IACG,KAAK,CACT,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,IAAI,CAAA;KAAO,GAC3F,OAAO,CAAC,SAAS,EAAE,CAAC,CA+DtB;CACF"}