@camunda/ccma-shared-types 2.0.0 → 4.0.0

package/dist/dtos/ClusterOwnerMove.dto.d.ts

@@ -0,0 +1,81 @@
+/**
+ * What a move of a cluster to another organization did not repair. The move
+ * keeps going when a warning occurs. A Camundi reads the warnings and decides.
+ */
+export interface MoveClusterWarnings {
+    /**
+     * The plan type of the cluster, when the sales plan of the target
+     * organization does not configure it. The cluster keeps running and stays
+     * manageable. That organization cannot create another cluster of this plan
+     * type and cannot duplicate this one, because only a POST route mounts
+     * `validPlanTypeValidator`. `id` supports a search of a support case.
+     * `name` is what the dialog shows.
+     */
+    planTypeNotConfigured?: {
+        id: string;
+        name: string;
+    };
+    /** True when the cluster holds an external IdP configuration. */
+    externalIdp: boolean;
+    /**
+     * The k8s objects of the cluster that carry the organization in a label:
+     * Backup, BackupSchedule, ExternalMonitoring, and PrivateConnectivity
+     * custom resources. The move patches each one's `orgId` label before it
+     * writes the database row for a backup. `failed` lists each object whose
+     * label patch failed, with its kind and name. For a failed Backup, a watch
+     * reconnect can write the old organization into its database row again. A
+     * Camundi must patch a failed label by hand.
+     *
+     * A cluster does not always have every kind of object. A cluster with no
+     * monitoring, or no private connectivity, counts as nothing for that kind,
+     * the same way a cluster with no backup counts as nothing.
+     */
+    orgLabels: {
+        patched: number;
+        failed: {
+            kind: string;
+            name: string;
+            error: string;
+        }[];
+    };
+    alertSubscriptions: {
+        kept: {
+            report: string;
+            target: string;
+        }[];
+        deleted: {
+            target: string;
+        }[];
+        failed: {
+            target: string;
+            error: string;
+        }[];
+        /**
+         * True when console could not read the subscriptions of the cluster. The
+         * three lists are then empty, and empty is not proof that the cluster holds
+         * no subscription. A Camundi must look at the subscriptions by hand.
+         */
+        readFailed: boolean;
+        /**
+         * True when console read the subscriptions but could not read the members
+         * of the target organization, thus it could not check who still belongs to
+         * it. Every subscription is then kept. A person outside the target
+         * organization can still get alerts for this cluster. A Camundi must check
+         * the membership by hand.
+         */
+        membershipCheckFailed: boolean;
+    };
+}
+export interface MoveClusterOwnerResult {
+    clusterId: string;
+    fromOrgId: string;
+    toOrgId: string;
+    warnings: MoveClusterWarnings;
+    /**
+     * True when the cluster already belonged to `toOrgId` before this request.
+     * The request repaired the k8s org labels and the `Backup.orgId` rows, and
+     * it moved nothing else. It ran no guard, no owner write, no audit entry,
+     * and no alert-subscription prune.
+     */
+    ownerUnchanged: boolean;
+}

package/dist/dtos/ClusterOwnerMove.dto.js

@@ -0,0 +1 @@
+//# sourceMappingURL=ClusterOwnerMove.dto.js.map

package/dist/dtos/ClusterOwnerMove.dto.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/dtos/CommonCluster.dto.d.ts

@@ -124,6 +124,12 @@ export interface CommonClusterDto {
      * primary → secondary order. Prefer this over parsing `backupRegion`.
      */
     backupRegionCodes?: string[];
+    /**
+     * True when console-admin.yaml marks this cluster's backup pairing for
+     * failover. SREs own the flag, per stage. The failover action reads it —
+     * do not infer failover support from the region codes.
+     */
+    backupFailoverSupported?: boolean;
     backupRegionId?: string | null;
     /**
      * True once the operator's initial primary→secondary bucket sync has

package/dist/dtos/ControlV2.dto.d.ts

@@ -1,3 +1,4 @@
+import type { CamundaClusterStage } from '../types/CamundaClusterLabels.type.js';
 import type { SalesPlanType } from '../types/SalesPlanType.type.js';
 import type { LicensingModelType } from './Organization.dto.js';
 /** Generic cursor-paginated response. `nextCursor === null` on the last page. */
@@ -112,6 +113,21 @@ export interface ClusterListItemV2Dto {
     orgName: string;
     /** Normalized server-side; augmented on the fly from the K8s watcher (§9.4 B1). */
     status: string;
+    /**
+     * The `metadata.generation` of the ZeebeCluster CR, from the K8s watcher at
+     * the time of the read, as in `ClusterLiveStateV2Entry`. A row thus carries
+     * the baseline that a poll of `GET /v2/clusters/live-state` compares with.
+     * Absent when the watcher does not know the cluster, or on an older
+     * console-backend.
+     */
+    specGeneration?: number;
+    /**
+     * Cluster environment stage (dev/test/stage/prod), from the single `camunda`
+     * label. Absent when the cluster has no camunda label or more than one, so a
+     * surface can only trust it when it is set — the same guard the cluster
+     * detail page and accounts use.
+     */
+    stageTag?: CamundaClusterStage;
     /** Plan type name (`ClusterPlanType.name`). Backs the "Plan type" column. */
     planTypeName: string;
     /**
@@ -129,6 +145,11 @@ export interface ClusterListItemV2Dto {
     numberOfAllocatedHwPackages?: number;
     /** Concrete plan name (`ClusterPlan.name`). Backs the "Plan" column. */
     planName?: string;
+    /**
+     * Concrete plan uuid (`ClusterPlan.uuid`). Names are not unique, so this is
+     * the key to compare a cluster with a target plan.
+     */
+    planId?: string;
     /** Generation name, for display. Group and filter by `generationId`. */
     generation: string;
     /** Generation uuid. Names are not unique, so this is the grouping key. */
@@ -149,6 +170,14 @@ export interface ClusterListItemV2Dto {
      * suspend and not the total time that the cluster was asleep.
      */
     suspendedAt?: string;
+    /** The "Authorizations" toggle of cluster create. */
+    identityBackendChecksEnabled?: boolean;
+    multiTenancyEnabled?: boolean;
+    /** BYOIDP. */
+    externalIdpEnabled?: boolean;
+    /** Session idle timeout. */
+    sessionMaxInactiveIntervalMinutes?: number;
+    sessionHeartbeatEnabled?: boolean;
 }
 /** Detail extends the list shape; richer fields are added in Phase 3. */
 export type ClusterDetailV2Dto = ClusterListItemV2Dto;
@@ -213,10 +242,11 @@ export interface ListClustersV2Params extends CursorParams {
      * by the DB-backed columns behind these list columns (the values are the
      * frontend column `key`s, mapped to SQL expressions in the controller):
      * `orgName` (owner id), `autoUpdate`, `planName`, `planTypeName`, `generation`,
-     * `channel`. `status`/`region` are intentionally excluded — they're computed
-     * from live K8s state / context config, not SQL columns.
+     * `channel`, `stageTag` (the single `camunda` label). `status`/`region` are
+     * intentionally excluded — they're computed from live K8s state / context
+     * config, not SQL columns.
      */
-    sort?: 'name' | 'created' | 'orgName' | 'autoUpdate' | 'planName' | 'planTypeName' | 'generation' | 'channel';
+    sort?: 'name' | 'created' | 'orgName' | 'autoUpdate' | 'planName' | 'planTypeName' | 'generation' | 'channel' | 'stageTag';
     order?: 'asc' | 'desc';
     filter?: {
         status?: string;
@@ -332,6 +362,28 @@ export interface ClusterParametersV2Dto {
     generations: ClusterParameterOptionV2Dto[];
     datacenters: ClusterDatacenterOptionV2Dto[];
 }
+/**
+ * One cluster in the watcher memory of console-backend: `[id, status,
+ * specGeneration]`. `status` is lowercase, as in `ClusterListItemV2Dto`.
+ * `specGeneration` is the `metadata.generation` of the ZeebeCluster CR.
+ * Kubernetes increments it on each change of the spec, for example a new
+ * generation or a new plan. It is `0` when the CR does not give one.
+ */
+export type ClusterLiveStateV2Entry = [
+    id: string,
+    status: string,
+    specGeneration: number
+];
+/**
+ * The whole fleet as the watcher sees it (GET /v2/clusters/live-state). The
+ * route reads memory only, never the database, thus a client can poll it every
+ * second. The entries are sorted by id, thus two equal states give the same
+ * body and the same ETag, also on two pods. A pod that is late gives a
+ * different body until it gets the same watch events.
+ */
+export interface ClusterLiveStateV2Dto {
+    items: ClusterLiveStateV2Entry[];
+}
 /**
  * Aggregated cluster distribution counts (GET /v2/clusters/facets), backing
  * the list page's distribution charts and quick-filter tiles without a

package/dist/dtos/FeatureFlagOverride.dto.d.ts

@@ -0,0 +1,226 @@
+import type { Stage } from '../constants/misc.const.js';
+/**
+ * The wire shapes of the feature flag surface of control-backend.
+ *
+ * They are here and not in `@camunda-cloud/featureflags`, because
+ * `@camunda/ccma-api` is published and cannot name a type from that private
+ * package. The RULES stay there: `resolveFlag` decides a value, and
+ * `FLAG_REGISTRY` holds the metadata. This file carries the answer over HTTP.
+ *
+ * `flagPath` is a `string` in every shape below. The typed `FlagPath` needs
+ * `Features`, and a caller of the API names a flag that the SERVER validates
+ * against its own registry. A type that the browser holds cannot do that job,
+ * because the server can be older or newer than the bundle.
+ */
+/** Which readers an override reaches. It is `FlagOverrideScope`. */
+export declare const FEATURE_FLAG_OVERRIDE_SCOPES: readonly ["stage", "org"];
+export type FeatureFlagOverrideScope = (typeof FEATURE_FLAG_OVERRIDE_SCOPES)[number];
+/** Why a flag has the value that it has. It is `FlagReason`. */
+export declare const FEATURE_FLAG_REASONS: readonly ["DEFAULT", "OVERRIDE_STAGE", "OVERRIDE_ORG", "OVERRIDE_REFUSED"];
+export type FeatureFlagReason = (typeof FEATURE_FLAG_REASONS)[number];
+/** How long a flag is meant to live. It is `FlagType`. */
+export declare const FEATURE_FLAG_TYPES: readonly ["release", "ops", "perm"];
+export type FeatureFlagType = (typeof FEATURE_FLAG_TYPES)[number];
+/**
+ * One condition of the code rule of a flag.
+ *
+ * The code rule is a LIST of these, and a reader gets the flag when ANY one
+ * matches. An empty list is off for every reader. `FLAG_RULES` of
+ * `@camunda-cloud/featureflags` holds the rules, and `defaults` evaluates the
+ * same objects, thus the description cannot drift from the value.
+ */
+export type FeatureFlagCondition = 
+/** On for every reader. */
+{
+    kind: 'always';
+}
+/** On when the stage of the reader is one of `stages`. */
+ | {
+    kind: 'stage';
+    stages: Stage[];
+}
+/** On when the email address of the reader is a Camundi address. */
+ | {
+    kind: 'camundiEmail';
+}
+/** On when the email address of the reader has one of `domains`. */
+ | {
+    kind: 'emailDomain';
+    domains: string[];
+}
+/** On when the organization of the reader is one of `orgIds`. */
+ | {
+    kind: 'org';
+    orgIds: string[];
+};
+/** One stored override, as a reader of the API sees it. */
+export interface FeatureFlagOverrideDto {
+    id: string;
+    flagPath: string;
+    scope: FeatureFlagOverrideScope;
+    /** The stage for `stage`, and the organization id for `org`. */
+    target: string;
+    enabled: boolean;
+    /** Why the person asked for it. The approval request demands one. */
+    reason: string;
+    /** The approval request that wrote this row. Every row names one. */
+    approvalId: string;
+    createdBy: {
+        userId: string;
+        email: string;
+    };
+    createdAt: string;
+    /** When the override stops by itself. */
+    expiresAt: string;
+}
+/**
+ * One flag, with everything a person needs to decide about it.
+ *
+ * The row carries the code value AND the effective value on purpose. A page
+ * that showed only the effective value would hide the drift, which is the one
+ * thing an override makes easy to lose.
+ */
+export interface FeatureFlagRowDto {
+    flagPath: string;
+    label: string;
+    type: FeatureFlagType;
+    owner: string;
+    reason: string;
+    /** Whether an override can move this flag at all. */
+    overridable: boolean;
+    /** The date after which a `release` flag is late. */
+    expiresAt?: string;
+    /**
+     * What the code answers for the stage of this service, for NOBODY.
+     *
+     * The evaluation carries the stage alone: no email address and no
+     * organization id. A flag whose condition reads one of those answers
+     * something else for a real reader — `console.clusterSuspendButton` is
+     * `false` here on prod and `true` for a Camundi, and
+     * `console.privateLink87` is `false` here and `true` for an allowlisted
+     * organization.
+     *
+     * It is a BASELINE, and that is the right answer for this surface: one
+     * value that every reader of the page sees, which is what makes two
+     * Camundis able to talk about it. A per-viewer value would answer a
+     * different thing to each of them, and a per-organization value needs an
+     * organization that the route does not take.
+     */
+    codeValue: boolean;
+    /**
+     * The code rule of the flag: it is on when ANY condition matches.
+     *
+     * This is what `codeValue` cannot say. It names the stages, the email
+     * rules and the organization allowlist that decide the value for a real
+     * reader.
+     */
+    rule: FeatureFlagCondition[];
+    /**
+     * The code value on each known stage, for NOBODY.
+     *
+     * The same baseline as `codeValue`, for every stage and not only this one.
+     * It shows how far the flag stands on its rollout ladder.
+     */
+    codeValueByStage: Record<Stage, boolean>;
+    /**
+     * The baseline of `codeValue` with a live override in front of it.
+     *
+     * Same evaluation context, thus the same limit: it is what a reader with
+     * no email address and no organization gets. Use it to see the DRIFT
+     * between the store and the source, which is what this surface exists
+     * for, and not as the answer for one person.
+     */
+    effectiveValue: boolean;
+    /** Why `effectiveValue` is what it is. */
+    effectiveReason: FeatureFlagReason;
+    /** The live override of the stage, if there is one. */
+    stageOverride?: FeatureFlagOverrideDto;
+    /**
+     * How many live overrides name an organization.
+     *
+     * A COUNT, and not the rows. The rows carry an organization id, an email
+     * address and a reason for every organization that holds an override, and
+     * this answer has no page, thus it would grow with the number of customers
+     * and hand all of it to every reader. The page shows the number.
+     */
+    orgOverrideCount: number;
+}
+/** The answer of `GET /api/feature-flags`. */
+export interface FeatureFlagsDto {
+    /** The stage that this service runs on. It decides `codeValue`. */
+    stage: string;
+    /** The moment when the service built this answer. */
+    observedAt: string;
+    flags: FeatureFlagRowDto[];
+}
+/**
+ * The permissions that one override payload needs, on top of nothing.
+ *
+ * It is here, and shared, because BOTH sides run it: `permissionsFor` of the
+ * use case stores the answer on the row, and the dialog of control-frontend
+ * passes the same answer to `canCreate`. Two copies of this rule would let a
+ * button offer an override that the service then refuses with a 403.
+ *
+ * A prod stage override reaches every customer, thus it asks for the narrower
+ * permission as well — to approve AND to ask.
+ */
+export declare function featureFlagOverridePermissions(payload: {
+    scope: FeatureFlagOverrideScope;
+    target: string;
+}): string[];
+/**
+ * The one written form of a target.
+ *
+ * A GUID reads the same in either case, and `ABC…` and `abc…` are the same
+ * organization. The store and the resolver compare TEXT, so two forms of one
+ * id would be two overrides: the unique index would allow both to be live,
+ * and a row written in capitals would never match the id that a reader
+ * carries. Everything that writes a target passes it through here first, so
+ * only one form ever reaches the table.
+ *
+ * A stage name is lowercase already, thus this does not change one.
+ */
+export declare function normalizeFeatureFlagOverrideTarget(target: string): string;
+/**
+ * What is wrong with the target of an override, if anything.
+ *
+ * It answers `undefined` when the target is good, and a sentence for a person
+ * when it is not.
+ *
+ * It is here, and shared, for the same reason as
+ * `featureFlagOverridePermissions` above: BOTH sides run it. The dialog of
+ * control-frontend keeps the button disabled while it answers, and the create
+ * route of control-backend refuses the call. The dialog accepted any text
+ * that was not empty before this, thus it offered `prod` on dev and
+ * `not-an-org` as an organization, and both ended in a 400 after the person
+ * had filled the whole form.
+ *
+ * TWO rules, and the first surprises people:
+ *
+ * 1. A stage override names THE STAGE OF THE SERVICE, and no other. Each
+ *    deployed stage of control-backend holds its own database, thus an
+ *    override written on dev reaches dev readers alone. A request for
+ *    another stage would collect its approvals and move nothing.
+ * 2. An org override names a GUID.
+ */
+export declare function featureFlagOverrideTargetProblem(args: {
+    scope: FeatureFlagOverrideScope;
+    target: string;
+    /** The stage that the service runs on. `FeatureFlagsDto.stage` carries it. */
+    stage: string;
+}): string | undefined;
+/** The payload of a `feature-flag-override` approval request. */
+export interface FeatureFlagOverridePayloadDto {
+    flagPath: string;
+    scope: FeatureFlagOverrideScope;
+    target: string;
+    enabled: boolean;
+    /**
+     * How many days the override holds, from the moment the action RUNS.
+     *
+     * A number of days and not a date, for the same reason as `extend-trial`:
+     * days pass between the request and the run, and a stored date would lose
+     * part of its life while the request waited for its approvals.
+     */
+    days: number;
+}

package/dist/dtos/FeatureFlagOverride.dto.js

@@ -0,0 +1,38 @@
+import { AccountsPermissions } from "../permissions/accounts.permissions.js";
+const ACCOUNTS_CONTROL_FLAG_OVERRIDE = AccountsPermissions.CONTROL_FLAG_OVERRIDE;
+const ACCOUNTS_CONTROL_FLAG_OVERRIDE_PROD = AccountsPermissions.CONTROL_FLAG_OVERRIDE_PROD;
+const FEATURE_FLAG_OVERRIDE_SCOPES = ["stage", "org"];
+const FEATURE_FLAG_REASONS = [
+  "DEFAULT",
+  "OVERRIDE_STAGE",
+  "OVERRIDE_ORG",
+  "OVERRIDE_REFUSED"
+];
+const FEATURE_FLAG_TYPES = ["release", "ops", "perm"];
+function featureFlagOverridePermissions(payload) {
+  const base = [ACCOUNTS_CONTROL_FLAG_OVERRIDE];
+  return payload.scope === "stage" && payload.target === "prod" ? [...base, ACCOUNTS_CONTROL_FLAG_OVERRIDE_PROD] : base;
+}
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function normalizeFeatureFlagOverrideTarget(target) {
+  return target.trim().toLowerCase();
+}
+function featureFlagOverrideTargetProblem(args) {
+  const target = normalizeFeatureFlagOverrideTarget(args.target);
+  if (target.length === 0) {
+    return args.scope === "stage" ? "Name the stage to move." : "Name the organization to move.";
+  }
+  if (args.scope === "stage") {
+    return target === args.stage ? void 0 : `This Camunda Control runs on ${args.stage} and can move only that stage. Open the request on the Camunda Control of ${target}.`;
+  }
+  return GUID.test(target) ? void 0 : "An organization id is a GUID, like 11111111-1111-1111-1111-111111111111.";
+}
+export {
+  FEATURE_FLAG_OVERRIDE_SCOPES,
+  FEATURE_FLAG_REASONS,
+  FEATURE_FLAG_TYPES,
+  featureFlagOverridePermissions,
+  featureFlagOverrideTargetProblem,
+  normalizeFeatureFlagOverrideTarget
+};
+//# sourceMappingURL=FeatureFlagOverride.dto.js.map

package/dist/dtos/FeatureFlagOverride.dto.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/dtos/FeatureFlagOverride.dto.ts"],
+  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\nimport type { Stage } from '../constants/misc.const.js'\nimport { AccountsPermissions } from '../permissions/accounts.permissions.js'\n\nconst ACCOUNTS_CONTROL_FLAG_OVERRIDE = AccountsPermissions.CONTROL_FLAG_OVERRIDE\nconst ACCOUNTS_CONTROL_FLAG_OVERRIDE_PROD =\n  AccountsPermissions.CONTROL_FLAG_OVERRIDE_PROD\n\n/**\n * The wire shapes of the feature flag surface of control-backend.\n *\n * They are here and not in `@camunda-cloud/featureflags`, because\n * `@camunda/ccma-api` is published and cannot name a type from that private\n * package. The RULES stay there: `resolveFlag` decides a value, and\n * `FLAG_REGISTRY` holds the metadata. This file carries the answer over HTTP.\n *\n * `flagPath` is a `string` in every shape below. The typed `FlagPath` needs\n * `Features`, and a caller of the API names a flag that the SERVER validates\n * against its own registry. A type that the browser holds cannot do that job,\n * because the server can be older or newer than the bundle.\n */\n\n/** Which readers an override reaches. It is `FlagOverrideScope`. */\nexport const FEATURE_FLAG_OVERRIDE_SCOPES = ['stage', 'org'] as const\n\nexport type FeatureFlagOverrideScope =\n  (typeof FEATURE_FLAG_OVERRIDE_SCOPES)[number]\n\n/** Why a flag has the value that it has. It is `FlagReason`. */\nexport const FEATURE_FLAG_REASONS = [\n  'DEFAULT',\n  'OVERRIDE_STAGE',\n  'OVERRIDE_ORG',\n  'OVERRIDE_REFUSED',\n] as const\n\nexport type FeatureFlagReason = (typeof FEATURE_FLAG_REASONS)[number]\n\n/** How long a flag is meant to live. It is `FlagType`. */\nexport const FEATURE_FLAG_TYPES = ['release', 'ops', 'perm'] as const\n\nexport type FeatureFlagType = (typeof FEATURE_FLAG_TYPES)[number]\n\n/**\n * One condition of the code rule of a flag.\n *\n * The code rule is a LIST of these, and a reader gets the flag when ANY one\n * matches. An empty list is off for every reader. `FLAG_RULES` of\n * `@camunda-cloud/featureflags` holds the rules, and `defaults` evaluates the\n * same objects, thus the description cannot drift from the value.\n */\nexport type FeatureFlagCondition =\n  /** On for every reader. */\n  | { kind: 'always' }\n  /** On when the stage of the reader is one of `stages`. */\n  | { kind: 'stage'; stages: Stage[] }\n  /** On when the email address of the reader is a Camundi address. */\n  | { kind: 'camundiEmail' }\n  /** On when the email address of the reader has one of `domains`. */\n  | { kind: 'emailDomain'; domains: string[] }\n  /** On when the organization of the reader is one of `orgIds`. */\n  | { kind: 'org'; orgIds: string[] }\n\n/** One stored override, as a reader of the API sees it. */\nexport interface FeatureFlagOverrideDto {\n  id: string\n  flagPath: string\n  scope: FeatureFlagOverrideScope\n  /** The stage for `stage`, and the organization id for `org`. */\n  target: string\n  enabled: boolean\n  /** Why the person asked for it. The approval request demands one. */\n  reason: string\n  /** The approval request that wrote this row. Every row names one. */\n  approvalId: string\n  createdBy: { userId: string; email: string }\n  createdAt: string\n  /** When the override stops by itself. */\n  expiresAt: string\n}\n\n/**\n * One flag, with everything a person needs to decide about it.\n *\n * The row carries the code value AND the effective value on purpose. A page\n * that showed only the effective value would hide the drift, which is the one\n * thing an override makes easy to lose.\n */\nexport interface FeatureFlagRowDto {\n  flagPath: string\n  label: string\n  type: FeatureFlagType\n  owner: string\n  reason: string\n  /** Whether an override can move this flag at all. */\n  overridable: boolean\n  /** The date after which a `release` flag is late. */\n  expiresAt?: string\n  /**\n   * What the code answers for the stage of this service, for NOBODY.\n   *\n   * The evaluation carries the stage alone: no email address and no\n   * organization id. A flag whose condition reads one of those answers\n   * something else for a real reader \u2014 `console.clusterSuspendButton` is\n   * `false` here on prod and `true` for a Camundi, and\n   * `console.privateLink87` is `false` here and `true` for an allowlisted\n   * organization.\n   *\n   * It is a BASELINE, and that is the right answer for this surface: one\n   * value that every reader of the page sees, which is what makes two\n   * Camundis able to talk about it. A per-viewer value would answer a\n   * different thing to each of them, and a per-organization value needs an\n   * organization that the route does not take.\n   */\n  codeValue: boolean\n  /**\n   * The code rule of the flag: it is on when ANY condition matches.\n   *\n   * This is what `codeValue` cannot say. It names the stages, the email\n   * rules and the organization allowlist that decide the value for a real\n   * reader.\n   */\n  rule: FeatureFlagCondition[]\n  /**\n   * The code value on each known stage, for NOBODY.\n   *\n   * The same baseline as `codeValue`, for every stage and not only this one.\n   * It shows how far the flag stands on its rollout ladder.\n   */\n  codeValueByStage: Record<Stage, boolean>\n  /**\n   * The baseline of `codeValue` with a live override in front of it.\n   *\n   * Same evaluation context, thus the same limit: it is what a reader with\n   * no email address and no organization gets. Use it to see the DRIFT\n   * between the store and the source, which is what this surface exists\n   * for, and not as the answer for one person.\n   */\n  effectiveValue: boolean\n  /** Why `effectiveValue` is what it is. */\n  effectiveReason: FeatureFlagReason\n  /** The live override of the stage, if there is one. */\n  stageOverride?: FeatureFlagOverrideDto\n  /**\n   * How many live overrides name an organization.\n   *\n   * A COUNT, and not the rows. The rows carry an organization id, an email\n   * address and a reason for every organization that holds an override, and\n   * this answer has no page, thus it would grow with the number of customers\n   * and hand all of it to every reader. The page shows the number.\n   */\n  orgOverrideCount: number\n}\n\n/** The answer of `GET /api/feature-flags`. */\nexport interface FeatureFlagsDto {\n  /** The stage that this service runs on. It decides `codeValue`. */\n  stage: string\n  /** The moment when the service built this answer. */\n  observedAt: string\n  flags: FeatureFlagRowDto[]\n}\n\n/**\n * The permissions that one override payload needs, on top of nothing.\n *\n * It is here, and shared, because BOTH sides run it: `permissionsFor` of the\n * use case stores the answer on the row, and the dialog of control-frontend\n * passes the same answer to `canCreate`. Two copies of this rule would let a\n * button offer an override that the service then refuses with a 403.\n *\n * A prod stage override reaches every customer, thus it asks for the narrower\n * permission as well \u2014 to approve AND to ask.\n */\nexport function featureFlagOverridePermissions(payload: {\n  scope: FeatureFlagOverrideScope\n  target: string\n}): string[] {\n  const base = [ACCOUNTS_CONTROL_FLAG_OVERRIDE]\n  return payload.scope === 'stage' && payload.target === 'prod'\n    ? [...base, ACCOUNTS_CONTROL_FLAG_OVERRIDE_PROD]\n    : base\n}\n\n/**\n * A GUID, as the create route reads one.\n *\n * The server says `z.guid()`. This is the same shape for the browser, which\n * holds no zod: 8-4-4-4-12 hexadecimal characters.\n */\nconst GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\n\n/**\n * The one written form of a target.\n *\n * A GUID reads the same in either case, and `ABC\u2026` and `abc\u2026` are the same\n * organization. The store and the resolver compare TEXT, so two forms of one\n * id would be two overrides: the unique index would allow both to be live,\n * and a row written in capitals would never match the id that a reader\n * carries. Everything that writes a target passes it through here first, so\n * only one form ever reaches the table.\n *\n * A stage name is lowercase already, thus this does not change one.\n */\nexport function normalizeFeatureFlagOverrideTarget(target: string): string {\n  return target.trim().toLowerCase()\n}\n\n/**\n * What is wrong with the target of an override, if anything.\n *\n * It answers `undefined` when the target is good, and a sentence for a person\n * when it is not.\n *\n * It is here, and shared, for the same reason as\n * `featureFlagOverridePermissions` above: BOTH sides run it. The dialog of\n * control-frontend keeps the button disabled while it answers, and the create\n * route of control-backend refuses the call. The dialog accepted any text\n * that was not empty before this, thus it offered `prod` on dev and\n * `not-an-org` as an organization, and both ended in a 400 after the person\n * had filled the whole form.\n *\n * TWO rules, and the first surprises people:\n *\n * 1. A stage override names THE STAGE OF THE SERVICE, and no other. Each\n *    deployed stage of control-backend holds its own database, thus an\n *    override written on dev reaches dev readers alone. A request for\n *    another stage would collect its approvals and move nothing.\n * 2. An org override names a GUID.\n */\nexport function featureFlagOverrideTargetProblem(args: {\n  scope: FeatureFlagOverrideScope\n  target: string\n  /** The stage that the service runs on. `FeatureFlagsDto.stage` carries it. */\n  stage: string\n}): string | undefined {\n  const target = normalizeFeatureFlagOverrideTarget(args.target)\n  if (target.length === 0) {\n    return args.scope === 'stage'\n      ? 'Name the stage to move.'\n      : 'Name the organization to move.'\n  }\n  if (args.scope === 'stage') {\n    return target === args.stage\n      ? undefined\n      : `This Camunda Control runs on ${args.stage} and can move only that ` +\n          `stage. Open the request on the Camunda Control of ${target}.`\n  }\n  return GUID.test(target)\n    ? undefined\n    : 'An organization id is a GUID, like 11111111-1111-1111-1111-111111111111.'\n}\n\n/** The payload of a `feature-flag-override` approval request. */\nexport interface FeatureFlagOverridePayloadDto {\n  flagPath: string\n  scope: FeatureFlagOverrideScope\n  target: string\n  enabled: boolean\n  /**\n   * How many days the override holds, from the moment the action RUNS.\n   *\n   * A number of days and not a date, for the same reason as `extend-trial`:\n   * days pass between the request and the run, and a stored date would lose\n   * part of its life while the request waited for its approvals.\n   */\n  days: number\n}\n"],
+  "mappings": "AAOA,SAAS,2BAA2B;AAEpC,MAAM,iCAAiC,oBAAoB;AAC3D,MAAM,sCACJ,oBAAoB;AAiBf,MAAM,+BAA+B,CAAC,SAAS,KAAK;AAMpD,MAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAKO,MAAM,qBAAqB,CAAC,WAAW,OAAO,MAAM;AAuIpD,SAAS,+BAA+B,SAGlC;AACX,QAAM,OAAO,CAAC,8BAA8B;AAC5C,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW,SACnD,CAAC,GAAG,MAAM,mCAAmC,IAC7C;AACN;AAQA,MAAM,OAAO;AAcN,SAAS,mCAAmC,QAAwB;AACzE,SAAO,OAAO,KAAK,EAAE,YAAY;AACnC;AAwBO,SAAS,iCAAiC,MAK1B;AACrB,QAAM,SAAS,mCAAmC,KAAK,MAAM;AAC7D,MAAI,OAAO,WAAW,GAAG;AACvB,WAAO,KAAK,UAAU,UAClB,4BACA;AAAA,EACN;AACA,MAAI,KAAK,UAAU,SAAS;AAC1B,WAAO,WAAW,KAAK,QACnB,SACA,gCAAgC,KAAK,KAAK,6EACa,MAAM;AAAA,EACnE;AACA,SAAO,KAAK,KAAK,MAAM,IACnB,SACA;AACN;",
+  "names": []
+}

package/dist/dtos/FeatureFlags.dto.d.ts

@@ -2,52 +2,65 @@
  * This type gives the shape of the feature flags of the management apps. It is
  * also the body of `GET external/feature-flags` on accounts-backend.
  *
- * The shape is here, but the evaluation is not. `features({stage, orgId,
- * email})` in `@camunda-cloud/featureflags` stays the only place that decides
- * if a flag is on. That package is private, thus a published package
- * (`@camunda/ccma-api`, `@camunda/ccma-saas-frontend`) cannot name the type
- * from there. `@camunda-cloud/featureflags` re-exports `Features` from here.
- * Thus the type has one definition, and every existing import path still works.
+ * The GROUP is typed and the FLAG is not. A flag can be made at run time, from
+ * the Feature flags page of Control, thus no interface can name every flag. A
+ * new GROUP is still a code change, in `FLAG_GROUPS` below.
+ *
+ * CAUTION: A wrong flag name is no longer a compile error.
+ * `FEATURES.console.byoidpp` reads `undefined`, which is falsy, so the
+ * feature turns off in silence. One thing answers that TODAY:
+ *
+ * - `readFlag(features, 'console.byoidp')` of `@camunda-cloud/featureflags`
+ *   answers a strict `boolean` for any path. Prefer it at a new call site.
+ *
+ * A second answer is PLANNED and does not exist yet:
+ * `packages/checks/src/feature-flag-check` finds a flag that no source
+ * declares but some source reads, and fails the build. It must land before
+ * wave R2 moves a reader onto the table. Until then the compiler catches a
+ * wrong GROUP and nothing catches a wrong flag name. See section 5.3 of
+ * `docs/superpowers/specs/2026-09-23-runtime-feature-flags-design.md`.
+ *
+ * The value is not here. `FLAG_RULES` in `@camunda-cloud/featureflags` holds
+ * the rule of each flag as DATA, `defaults(context)` evaluates it, and
+ * `resolveFeatures` puts a stored override in front of the answer for one
+ * organization, one mail domain or one person. `defaults` is the floor, and
+ * not the runtime answer.
+ *
+ * What a flag gates, who owns it and why it exists live in `FLAG_REGISTRY` of
+ * the same package while the code still holds the flags, and in the
+ * `feature_flag` table of control-backend after that. They used to be here,
+ * one comment for each field, and that list cannot survive a flag that no
+ * field declares.
+ *
+ * This type is here and not in `@camunda-cloud/featureflags` because that
+ * package is private, thus a published package (`@camunda/ccma-api`,
+ * `@camunda/ccma-saas-frontend`) cannot name the type from there.
+ * `@camunda-cloud/featureflags` re-exports `Features` from here.
  *
  * A c4 host reads one flag with `useC4FeatureFlag('console.appIntegrations')`
  * — a dot path into this object.
  */
-export interface Features {
-    console: {
-        admin: {
-            overrideOrgRole: boolean;
-        };
-        clusterSuspendButton: boolean;
-        clusterSleepWarning: boolean;
-        backupRestore: boolean;
-        failover: boolean;
-        privateLink87: boolean;
-        byoidp: boolean;
-        optimizeUnsetOnDisable: boolean;
-        appIntegrations: boolean;
-        orgClusterDefaults: boolean;
-        releaseTrainSanityFix: boolean;
-        hubHelpCenterLinks: boolean;
-        legacyModelerApiNaming: boolean;
-        backupScheduleApi: boolean;
-        clusterCreationBlocked: boolean;
-        deferSpecChangeWhileAsleep: boolean;
-        clusterDuplication: boolean;
-    };
-    control: {
-        frontendTelemetry: boolean;
-        sendToExpiredTrialApproval: boolean;
-    };
-    accounts: {
-        moveClusterOrg: boolean;
-        orgLimitAuditLog: boolean;
-        orgReservationAuditLog: boolean;
-        deleteLiteLLMKeyOnTrialExpiry: boolean;
-    };
-    shared: {
-        cyberpunkBrutalism: boolean;
-        tenantsValueMetric: boolean;
-        hdpValueMetricsFor2025: boolean;
-        permissionsRework: boolean;
-    };
-}
+/**
+ * Every group of flags.
+ *
+ * A group is a code change, because it is the one part of the shape that a
+ * reader names in a type.
+ *
+ * `hub` carries the flags of Camunda Hub, which embeds c4 widgets and reads
+ * them with `useC4FeatureFlag`. Nothing in this repository reads a `hub`
+ * flag, thus the group holds no code rule and only ever holds rows. The
+ * stale-flag check therefore skips it: a check that looks for a reader finds
+ * none, and that is correct and not a fault.
+ */
+export declare const FLAG_GROUPS: readonly ["console", "control", "accounts", "shared", "hub"];
+export type FlagGroup = (typeof FLAG_GROUPS)[number];
+/**
+ * The flags of one group.
+ *
+ * The key is a plain `string` and not a union, because a person can make a
+ * flag at run time. The value is a `boolean` and never `any`: `any` would
+ * also accept `features.console.foo.bar`, and the tree is one level deep
+ * under its group.
+ */
+export type FlagValues = Record<string, boolean>;
+export type Features = Record<FlagGroup, FlagValues>;

package/dist/dtos/FeatureFlags.dto.js

@@ -1 +1,11 @@
+const FLAG_GROUPS = [
+  "console",
+  "control",
+  "accounts",
+  "shared",
+  "hub"
+];
+export {
+  FLAG_GROUPS
+};
 //# sourceMappingURL=FeatureFlags.dto.js.map

package/dist/dtos/FeatureFlags.dto.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": [],
-  "sourcesContent": [],
-  "mappings": "",
+  "sources": ["../../src/dtos/FeatureFlags.dto.ts"],
+  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\n/**\n * This type gives the shape of the feature flags of the management apps. It is\n * also the body of `GET external/feature-flags` on accounts-backend.\n *\n * The GROUP is typed and the FLAG is not. A flag can be made at run time, from\n * the Feature flags page of Control, thus no interface can name every flag. A\n * new GROUP is still a code change, in `FLAG_GROUPS` below.\n *\n * CAUTION: A wrong flag name is no longer a compile error.\n * `FEATURES.console.byoidpp` reads `undefined`, which is falsy, so the\n * feature turns off in silence. One thing answers that TODAY:\n *\n * - `readFlag(features, 'console.byoidp')` of `@camunda-cloud/featureflags`\n *   answers a strict `boolean` for any path. Prefer it at a new call site.\n *\n * A second answer is PLANNED and does not exist yet:\n * `packages/checks/src/feature-flag-check` finds a flag that no source\n * declares but some source reads, and fails the build. It must land before\n * wave R2 moves a reader onto the table. Until then the compiler catches a\n * wrong GROUP and nothing catches a wrong flag name. See section 5.3 of\n * `docs/superpowers/specs/2026-09-23-runtime-feature-flags-design.md`.\n *\n * The value is not here. `FLAG_RULES` in `@camunda-cloud/featureflags` holds\n * the rule of each flag as DATA, `defaults(context)` evaluates it, and\n * `resolveFeatures` puts a stored override in front of the answer for one\n * organization, one mail domain or one person. `defaults` is the floor, and\n * not the runtime answer.\n *\n * What a flag gates, who owns it and why it exists live in `FLAG_REGISTRY` of\n * the same package while the code still holds the flags, and in the\n * `feature_flag` table of control-backend after that. They used to be here,\n * one comment for each field, and that list cannot survive a flag that no\n * field declares.\n *\n * This type is here and not in `@camunda-cloud/featureflags` because that\n * package is private, thus a published package (`@camunda/ccma-api`,\n * `@camunda/ccma-saas-frontend`) cannot name the type from there.\n * `@camunda-cloud/featureflags` re-exports `Features` from here.\n *\n * A c4 host reads one flag with `useC4FeatureFlag('console.appIntegrations')`\n * \u2014 a dot path into this object.\n */\n\n/**\n * Every group of flags.\n *\n * A group is a code change, because it is the one part of the shape that a\n * reader names in a type.\n *\n * `hub` carries the flags of Camunda Hub, which embeds c4 widgets and reads\n * them with `useC4FeatureFlag`. Nothing in this repository reads a `hub`\n * flag, thus the group holds no code rule and only ever holds rows. The\n * stale-flag check therefore skips it: a check that looks for a reader finds\n * none, and that is correct and not a fault.\n */\nexport const FLAG_GROUPS = [\n  'console',\n  'control',\n  'accounts',\n  'shared',\n  'hub',\n] as const\n\nexport type FlagGroup = (typeof FLAG_GROUPS)[number]\n\n/**\n * The flags of one group.\n *\n * The key is a plain `string` and not a union, because a person can make a\n * flag at run time. The value is a `boolean` and never `any`: `any` would\n * also accept `features.console.foo.bar`, and the tree is one level deep\n * under its group.\n */\nexport type FlagValues = Record<string, boolean>\n\nexport type Features = Record<FlagGroup, FlagValues>\n"],
+  "mappings": "AA6DO,MAAM,cAAc;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;",
   "names": []
 }