@adonis-agora/flags 0.0.0-stage → 0.1.0

package/dist/src/dashboard/console_authorize.js

@@ -0,0 +1,104 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+const FORBIDDEN = { allowed: false, status: 403, reason: 'forbidden' };
+function isAuthorizerClass(value) {
+    return (typeof value === 'function' &&
+        typeof value.prototype?.authorize === 'function');
+}
+/** A module namespace whose `default` export is an authorizer class: a lazy import resolved. */
+function lazyModuleClass(value) {
+    if (typeof value !== 'object' || value === null || !('default' in value))
+        return undefined;
+    const candidate = value.default;
+    return isAuthorizerClass(candidate) ? candidate : undefined;
+}
+/**
+ * Normalize an authorizer's answer. Fails closed: only `true` or `{ allowed: true }` passes;
+ * `{ redirectTo }` with a non-empty string is a redirect; anything else is a denial (`401` for
+ * `reason: 'unauthenticated'`, `403` otherwise).
+ */
+export function normalizeConsoleAuthorizeResult(result) {
+    if (result === true)
+        return { allowed: true };
+    if (typeof result !== 'object' || result === null)
+        return FORBIDDEN;
+    const value = result;
+    if (value.allowed === true)
+        return { allowed: true };
+    if (value.allowed === undefined && typeof value.redirectTo === 'string' && value.redirectTo) {
+        return { allowed: false, status: 302, redirectTo: value.redirectTo };
+    }
+    if (value.reason === 'unauthenticated') {
+        return { allowed: false, status: 401, reason: 'unauthenticated' };
+    }
+    return FORBIDDEN;
+}
+async function instantiate(Authorizer, ctx) {
+    const resolver = ctx.containerResolver;
+    if (resolver && typeof resolver.make === 'function') {
+        return (await resolver.make(Authorizer));
+    }
+    return new Authorizer();
+}
+/**
+ * Turn an `authorize` option into one guard function.
+ *
+ * - A class is built through the request's container (`ctx.containerResolver.make`), so
+ *   `@inject()` works, and its `authorize(ctx)` is called.
+ * - A function is called with `ctx`. When it resolves to a module whose `default` is an
+ *   authorizer class, it was a lazy import: the class is remembered (the import runs once per
+ *   returned guard) and used as above.
+ * - A thrown error is a `403` denial, carried on `error` so the caller can log it.
+ */
+export function resolveConsoleAuthorize(authorize) {
+    let lazyClass;
+    const run = async (ctx) => {
+        if (lazyClass)
+            return (await instantiate(lazyClass, ctx)).authorize(ctx);
+        if (isAuthorizerClass(authorize))
+            return (await instantiate(authorize, ctx)).authorize(ctx);
+        const result = await authorize(ctx);
+        const imported = lazyModuleClass(result);
+        if (imported) {
+            lazyClass = imported;
+            return (await instantiate(imported, ctx)).authorize(ctx);
+        }
+        return result;
+    };
+    return async (ctx) => {
+        try {
+            return normalizeConsoleAuthorizeResult(await run(ctx));
+        }
+        catch (error) {
+            return { ...FORBIDDEN, error };
+        }
+    };
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest();
+}
+/**
+ * An `authorize` check for machine access: allows a request whose `Authorization` header is
+ * `Bearer <token>` (compared in constant time), and answers
+ * `{ allowed: false, reason: 'unauthenticated' }` (`401`) otherwise. Only the header is read.
+ *
+ * ```ts
+ * authorize: authorizeByToken({ token: env.get('CONSOLE_TOKEN') }),
+ * ```
+ *
+ * Throws at config time when `token` is empty or undefined.
+ */
+export function authorizeByToken(options) {
+    const token = options?.token;
+    if (typeof token !== 'string' || token === '') {
+        throw new Error('[@adonis-agora/flags] authorizeByToken: `token` must be a non-empty string');
+    }
+    const expected = digest(token);
+    return (ctx) => {
+        const header = ctx.request.header('authorization');
+        const match = typeof header === 'string' ? /^Bearer\s+(.+)$/i.exec(header.trim()) : null;
+        if (match?.[1] && timingSafeEqual(digest(match[1]), expected))
+            return { allowed: true };
+        return { allowed: false, reason: 'unauthenticated' };
+    };
+}
+//# sourceMappingURL=console_authorize.js.map

package/dist/src/dashboard/console_authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console_authorize.js","sourceRoot":"","sources":["../../../src/dashboard/console_authorize.ts"],"names":[],"mappings":"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"}

package/dist/src/dashboard/define_config.d.ts

@@ -0,0 +1,71 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { Actor } from '../stores/store.js';
+import type { AccessDeniedOption as GenericAccessDeniedOption, AccessDeniedRenderer as GenericAccessDeniedRenderer } from './access_denied_page.js';
+import type { ConsoleAuthorize, ConsoleAuthorizeResult } from './console_authorize.js';
+export type { AuthorizeDecision, AuthorizeResult } from './authorize_decision.js';
+export type { AuthorizeByTokenOptions, ConsoleAuthorize, ConsoleAuthorizeResult, ConsoleAuthorizer, ConsoleAuthorizerClass, } from './console_authorize.js';
+/** The function form of {@link FlagsDashboardConfig.accessDenied}. */
+export type AccessDeniedRenderer = GenericAccessDeniedRenderer<HttpContext>;
+/** `accessDenied` in either form — an options object for the built-in page, or a renderer. */
+export type AccessDeniedOption = GenericAccessDeniedOption<HttpContext>;
+/**
+ * The inline-function form of the dashboard's `authorize` option. Runs before every dashboard
+ * route (API + HTML) and may be async. Answer with:
+ *
+ * - `true` / `{ allowed: true }` — let the request through;
+ * - `{ allowed: false, reason: 'unauthenticated' }` — nobody is signed in: `401`;
+ * - `{ allowed: false, reason: 'forbidden' }`, `{ allowed: false }` or `false` — `403`;
+ * - `{ redirectTo: '/login' }` — a page navigation is redirected (`302`), an API call gets `401`.
+ *
+ * A hook that throws is a `403`. `@adonis-agora/authkit-client`'s `authkitDashboardAuthorize` and
+ * `@adonis-agora/authz`'s `authorizeByRoles` fit here as-is.
+ */
+export type AuthorizeHook = (ctx: HttpContext) => ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>;
+/**
+ * Who a console change is attributed to (audit log, change requests). Return an {@link Actor}, a
+ * bare id, or nothing to fall back to `'dashboard'`.
+ */
+export type ActorResolver = (ctx: HttpContext) => Actor | string | null | undefined | Promise<Actor | string | null | undefined>;
+/** Shape of `config/flags_dashboard.ts`. */
+export interface FlagsDashboardConfig {
+    /** Master switch. `false` registers no routes at all. Default `true`. */
+    enabled?: boolean;
+    /**
+     * URL prefix the console and its API mount under. Default `/flags`. The HTML is served at the
+     * prefix root; the JSON API lives under `<path>/api`. Every route is an EXACT path (no SPA
+     * catch-all), so the prefix can sit next to other routes safely.
+     */
+    path?: string;
+    /**
+     * Who may open the console: an inline function, an authorizer class (built through the
+     * container, so `@inject()` works), or a lazy import of one. For machine access use
+     * `authorizeByToken({ token })`.
+     *
+     * Omitted: the console is open outside production and answers every request with `403` in
+     * production; the provider logs a one-time warning at boot saying so.
+     */
+    authorize?: ConsoleAuthorize;
+    /**
+     * Who the acting person is, for the audit log and two-person approvals. Default: the signed-in
+     * user's id (`ctx.auth.user.id`, with `email`/`name` as the display name), else `'dashboard'`.
+     *
+     * With approvals on, two people only count as two when this tells them apart: everyone falling
+     * back to `'dashboard'` means nobody can approve anybody's request.
+     */
+    actor?: ActorResolver;
+    /** What a BROWSER sees when the guard refuses a page navigation. API calls always get JSON. */
+    accessDenied?: AccessDeniedOption;
+}
+/** A fully-resolved config — every field present (defaults applied). */
+export interface ResolvedFlagsDashboardConfig {
+    enabled: boolean;
+    path: string;
+    authorize: ConsoleAuthorize | null;
+    actor: ActorResolver | null;
+    accessDenied: AccessDeniedOption | null;
+}
+/** Apply defaults to a partial config, producing a fully-resolved one. */
+export declare function resolveConfig(config?: FlagsDashboardConfig): ResolvedFlagsDashboardConfig;
+/** Identity helper giving `config/flags_dashboard.ts` full type-checking. */
+export declare function defineConfig(config?: FlagsDashboardConfig): FlagsDashboardConfig;
+//# sourceMappingURL=define_config.d.ts.map

package/dist/src/dashboard/define_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/dashboard/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EACV,kBAAkB,IAAI,yBAAyB,EAC/C,oBAAoB,IAAI,2BAA2B,EACpD,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEvF,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAClF,YAAY,EACV,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,CAAC,WAAW,CAAC,CAAC;AAE5E,8FAA8F;AAC9F,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,CAAC,WAAW,CAAC,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,WAAW,KACb,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,WAAW,KACb,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEpF,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,+FAA+F;IAC/F,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED,wEAAwE;AACxE,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzC;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,GAAE,oBAAyB,GAAG,4BAA4B,CAW7F;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,GAAE,oBAAyB,GAAG,oBAAoB,CAEpF"}

package/dist/src/dashboard/define_config.js

@@ -0,0 +1,18 @@
+/** Apply defaults to a partial config, producing a fully-resolved one. */
+export function resolveConfig(config = {}) {
+    const rawPath = config.path ?? '/flags';
+    // Normalize: ensure a single leading slash and no trailing slash (root stays '').
+    const trimmed = `/${rawPath.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+    return {
+        enabled: config.enabled ?? true,
+        path: trimmed === '/' ? '' : trimmed,
+        authorize: config.authorize ?? null,
+        actor: config.actor ?? null,
+        accessDenied: config.accessDenied ?? null,
+    };
+}
+/** Identity helper giving `config/flags_dashboard.ts` full type-checking. */
+export function defineConfig(config = {}) {
+    return config;
+}
+//# sourceMappingURL=define_config.js.map

package/dist/src/dashboard/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/dashboard/define_config.ts"],"names":[],"mappings":"AAuFA,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,MAAM,GAAyB,EAAE;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAC;IACxC,kFAAkF;IAClF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;IACtE,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,IAAI,EAAE,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO;QACpC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;QACnC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;QAC3B,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;KAC1C,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,MAAM,GAAyB,EAAE;IAC5D,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/dashboard/handlers.d.ts

@@ -0,0 +1,172 @@
+import { type FlagDefinition, type JsonValue } from '@adonis-agora/flags-core';
+import type { FlagDeclaration } from '../declare.js';
+import type { FlagsRuntime } from '../runtime.js';
+import { type Actor } from '../stores/store.js';
+/**
+ * Framework-light JSON handlers for the flags console.
+ *
+ * Each handler takes {@link Deps} (the runtime — `getRuntime()` unless a test hands one over — and
+ * the acting person) and a plain {@link ApiRequest}, and returns a plain {@link ApiResponse}. No
+ * AdonisJS types leak in, so they are unit-testable against a real runtime with no HTTP server.
+ * Same `Deps` / `ApiRequest` / `ApiResponse` convention as the payments and durable consoles.
+ *
+ * Every WRITE goes through `FlagsAdmin` — never the store directly — so the console gets exactly
+ * the validation, authorization, approvals and audit trail the commands get. Errors map to HTTP:
+ * `ValidationError` → `422 { error, issues }`, `ForbiddenError` → `403`, a missing change request
+ * → `404`, one that is no longer pending → `409`.
+ *
+ * Every call takes an `environment` (query string for reads, body for writes); omitted, it is the
+ * environment this app evaluates.
+ */
+/** What the handlers need to answer a request. */
+export interface Deps {
+    /** The booted runtime. Default: {@link getRuntime}. */
+    runtime?: FlagsRuntime;
+    /** Who is acting — the audit log and the two-person rule are keyed on `actor.id`. */
+    actor: Actor;
+    /** Injectable clock (stale report). */
+    now?: () => Date;
+}
+/** The subset of an HTTP request the handlers read. */
+export interface ApiRequest {
+    params: Record<string, string | undefined>;
+    query: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+/** A plain JSON response: an HTTP status and a serializable body. */
+export interface ApiResponse {
+    status: number;
+    body: unknown;
+}
+export declare const ok: (body: unknown) => ApiResponse;
+/** An error that already knows its HTTP answer. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly extra: Record<string, unknown>;
+    constructor(status: number, message: string, extra?: Record<string, unknown>);
+}
+/** Map anything a handler threw to the answer the SPA can show. */
+export declare function errorResponse(error: unknown): ApiResponse;
+/** A declaration as the console shows it: what the code says, and which apps say it. */
+export interface DeclaredFlag extends FlagDeclaration {
+    apps: string[];
+    /** `code`: declared in an app's config (read-only here). `console`: created and edited here. */
+    source: 'code' | 'console';
+}
+/** What a flag serves to someone no rule or override matches. */
+export type Serving = 
+/** Not in the ruleset: everyone gets the default declared in code. */
+{
+    kind: 'default';
+    value: JsonValue | null;
+}
+/** Kill switch: everyone gets `offVariant`. */
+ | {
+    kind: 'off';
+    variant: string;
+} | {
+    kind: 'fixed';
+    variant: string;
+}
+/** An on/off split: `percent`% get `on`. */
+ | {
+    kind: 'rollout';
+    percent: number;
+} | {
+    kind: 'split';
+    arms: Array<{
+        variant: string;
+        percent: number;
+    }>;
+    bucketBy?: string;
+};
+/** The one-line "what does this serve" every flag row shows. */
+export declare function servingSummary(definition: FlagDefinition | undefined, declaration?: FlagDeclaration): Serving;
+/** `GET /api/meta` — what the shell needs: environments, approvals, who you are. */
+export declare function meta(deps: Deps, _req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/flags` — every flag in the ruleset or declared in code, with what it serves. */
+export declare function listFlags(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/flags/:key` — one flag: its definition (stored, or what the declaration implies), its
+ *  audit trail, schedules and pending requests, plus the names the editor offers. */
+export declare function flagDetail(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `PUT /api/flags/:key` `{ definition, note? }` — save the whole definition. */
+export declare function saveFlag(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/flags` `{ key, declaration, note? }` — create a flag here, without code. */
+export declare function createFlag(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `PUT /api/flags/:key/declaration` `{ declaration, note? }` — edit a console flag's declaration. */
+export declare function updateDeclaration(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `DELETE /api/flags/:key` — remove the flag from the ruleset (the code default takes over). */
+export declare function deleteFlag(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/flags/:key/enabled` `{ enabled }` — the kill switch. */
+export declare function setEnabled(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/flags/:key/rollout` `{ percent }` — on/off flags only. */
+export declare function setRollout(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/flags/:key/variant` `{ variant }` — serve one variant to everyone. */
+export declare function setVariant(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/flags/:key/overrides` `{ subject, variant | null }` — force (or clear) one subject. */
+export declare function setOverride(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `POST /api/preview` `{ environment, change }` — would this edit be accepted? Answers `200` either
+ * way (`{ valid, issues }`): the editor calls it on every keystroke, and an invalid draft is the
+ * normal state of a form being typed into, not an error.
+ */
+export declare function preview(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `POST /api/evaluate` `{ environment, context, flag?, definition? }` — what a context would get.
+ *
+ * Evaluates with the engine directly against the environment's STORED ruleset, so it records no
+ * exposure and counts no usage: testing a rule must not enrol a fake user in an experiment. With
+ * `definition`, the unsaved draft is evaluated in place of the stored flag. Without `flag`, every
+ * flag is evaluated.
+ */
+export declare function evaluateContext(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/segments` — every segment and the flags whose rules reference it. */
+export declare function listSegments(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `PUT /api/segments/:key` `{ segment, note? }`. */
+export declare function saveSegment(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `DELETE /api/segments/:key` — refused (422) while a rule still references it. */
+export declare function deleteSegment(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/layers` — layers with their allocations, the global holdout, and every experiment. */
+export declare function listLayers(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `PUT /api/layers/:key` `{ layer, note? }`. */
+export declare function saveLayer(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `DELETE /api/layers/:key`. */
+export declare function deleteLayer(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `PUT /api/holdout` `{ holdout | null, note? }` — `null` removes the global holdout. */
+export declare function saveHoldout(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/experiments` — configured experiments with a summary of their last results. */
+export declare function listExperiments(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/experiments/:key` — the last computed results (the worker refreshes them). */
+export declare function experimentDetail(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/experiments/:key/recompute` — compute the results now instead of at the next tick. */
+export declare function recomputeExperiment(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/change-requests?status=pending|…|all`. */
+export declare function listChangeRequests(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/change-requests/:id/approve` `{ note? }` — the requester cannot approve (403). */
+export declare function approveChangeRequest(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/change-requests/:id/reject` `{ note? }`. */
+export declare function rejectChangeRequest(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/change-requests/:id/cancel` — only the requester can withdraw their request. */
+export declare function cancelChangeRequest(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/audit?entity&key&before&limit` — newest first; page with `before=<at of last row>`. */
+export declare function audit(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/schedules?flag&status`. */
+export declare function listSchedules(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `POST /api/flags/:key/schedules` — either one change at a time
+ * (`{ kind: 'enable' | 'disable' | 'rollout', runAt, percent? }`) or a gradual rollout
+ * (`{ steps: [{ at, percent }] }`, one schedule per step).
+ */
+export declare function createSchedule(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `DELETE /api/schedules/:id` — only a pending schedule can be cancelled. */
+export declare function cancelSchedule(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/export` — the environment's ruleset as JSON. */
+export declare function exportRuleset(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/import` `{ ruleset, note? }` — replaces every flag, segment, layer and the holdout. */
+export declare function importRuleset(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /api/promote` `{ from, to, note? }` — copy one environment's ruleset over another's. */
+export declare function promote(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /api/stale?unusedDays&staticDays` — flags that probably should be removed. */
+export declare function stale(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+export declare function ops(deps: Deps, _req: ApiRequest): Promise<ApiResponse>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/src/dashboard/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/dashboard/handlers.ts"],"names":[],"mappings":"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"}