@camunda/ccma-shared-types 5.0.0 → 6.0.0

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

@@ -0,0 +1,336 @@
+import type { ChartGrain, ChartSpec, ChartUnit, ChartWindowUnit } from '../charts/chart-spec.js';
+import type { SearchFieldCapability, SearchFieldType } from '../search/fields.js';
+import type { AnnotationEntityKind, AnnotationKind } from './Annotation.dto.js';
+/**
+ * The wire types of the dashboards of Camunda Control.
+ *
+ * A dashboard stores QUESTIONS and never answers. A tile holds the filters of
+ * the page that it came from, and the dashboard runs them again each time a
+ * reader opens it. So a stored dashboard stays small, and it never holds a
+ * copy of fleet data that can go stale or leak.
+ *
+ * control-backend and control-frontend both read this file, so it holds no
+ * logic with I/O and no dependency.
+ */
+/** DASHBOARD_TILES_MAX is the most tiles that one dashboard can hold. */
+export declare const DASHBOARD_TILES_MAX = 20;
+/** DASHBOARD_GRID_COLUMNS is the width of the tile grid, in columns. */
+export declare const DASHBOARD_GRID_COLUMNS = 12;
+/** DASHBOARD_TILE_ROWS_MAX is the tallest tile, in grid rows. */
+export declare const DASHBOARD_TILE_ROWS_MAX = 24;
+/**
+ * DASHBOARD_GRID_ROWS_MAX is the lowest row that a tile can start on. It is
+ * the height of 20 tiles of the tallest size, one under the other, so a
+ * compact grid never reaches it.
+ */
+export declare const DASHBOARD_GRID_ROWS_MAX: number;
+/** DASHBOARD_TITLE_MAX is the longest title of a dashboard or of a tile. */
+export declare const DASHBOARD_TITLE_MAX = 120;
+/**
+ * DASHBOARD_DEFINITION_BYTES_MAX is the largest definition that the backend
+ * stores, as JSON text. Twenty tiles of filters need a few kilobytes, so a
+ * larger body is a client that tries to store data and not filters.
+ */
+export declare const DASHBOARD_DEFINITION_BYTES_MAX = 32768;
+/** DASHBOARD_PAGE_SIZE_MAX is the most dashboards that one list page holds. */
+export declare const DASHBOARD_PAGE_SIZE_MAX = 200;
+/** DASHBOARD_PAGE_SIZE_DEFAULT is the list page size when a caller sends none. */
+export declare const DASHBOARD_PAGE_SIZE_DEFAULT = 200;
+/**
+ * DASHBOARD_DEFINITION_VERSION is the `schemaVersion` that this code writes.
+ *
+ * Raise it when the shape of the definition changes, add the old shape to
+ * `StoredDashboardDefinition`, and teach `upgradeDashboardDefinition` to read
+ * it. A row is never rewritten in place: it moves to the new version on its
+ * next save.
+ */
+export declare const DASHBOARD_DEFINITION_VERSION = 3;
+/**
+ * Every kind of tile.
+ *
+ * `fleet-query` and `annotations` run saved filters. `cluster-detail` and
+ * `org-detail` show one card of the page of one cluster or one organization.
+ * `heading`, `note` and `link` hold text that a person wrote, and fetch
+ * nothing. `chart` runs a chart query on HDP.
+ */
+export declare const DASHBOARD_TILE_KINDS: readonly ["fleet-query", "annotations", "cluster-detail", "org-detail", "heading", "note", "link", "chart"];
+export type DashboardTileKind = (typeof DASHBOARD_TILE_KINDS)[number];
+/** Where a tile sits on the grid, in columns and rows from the top left. */
+export interface DashboardTileLayout {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * The search params of a Fleet query page, as that page writes them.
+ *
+ * The backend stores them as they are and checks only their shape: flat
+ * values, no objects. The keys belong to the Fleet query page, so the
+ * frontend validates them on read with the same function that validates the
+ * URL. A tile with a key that this function drops does not run, because the
+ * query would be wider than the one that was saved.
+ */
+export type DashboardFleetQuery = Record<string, string | number | boolean | string[]>;
+/** The filters of the Notes & tags page. */
+export interface DashboardAnnotationsQuery {
+    kind?: AnnotationKind;
+    entityKind?: AnnotationEntityKind;
+    tag?: string;
+    q?: string;
+}
+/**
+ * The cards of the Overview tab of a cluster that a dashboard can show.
+ *
+ * The id names the card and never its content. The tile reads the cluster
+ * again each time it is in view, so it shows the current state.
+ */
+export declare const DASHBOARD_CLUSTER_CARDS: readonly ["identity", "component-status", "datacenter", "generation", "plan", "backup-encryption", "settings-flags", "external-idp", "data-filters", "auto-pause", "change-history", "disk-usage"];
+export type DashboardClusterCard = (typeof DASHBOARD_CLUSTER_CARDS)[number];
+/** The cards of the Overview tab of an organization. */
+export declare const DASHBOARD_ORG_CARDS: readonly ["summary", "details", "sales-plan", "queued-operations", "clusters", "managed-llm", "recent-activity"];
+export type DashboardOrgCard = (typeof DASHBOARD_ORG_CARDS)[number];
+/** DASHBOARD_ENTITY_ID_MAX is the longest cluster id or organization id. */
+export declare const DASHBOARD_ENTITY_ID_MAX = 64;
+/**
+ * DASHBOARD_NOTE_MAX is the longest text of a note tile.
+ *
+ * Twenty full notes of ASCII text fit in `DASHBOARD_DEFINITION_BYTES_MAX`.
+ * Text with characters of more than one UTF-8 byte can pass that limit first,
+ * so the frontend measures the whole definition with
+ * `dashboardDefinitionBytes` before it saves.
+ */
+export declare const DASHBOARD_NOTE_MAX = 1000;
+/** DASHBOARD_LINK_URL_MAX is the longest address of a link tile. */
+export declare const DASHBOARD_LINK_URL_MAX = 1000;
+/**
+ * How a chart tile draws its result. `stat` is one number with a sparkline.
+ * Each render is a chart of `@camunda/design-system`, which has no area chart.
+ */
+export declare const DASHBOARD_CHART_RENDERS: readonly ["line", "bar", "stacked-bar", "stat"];
+export type DashboardChartRender = (typeof DASHBOARD_CHART_RENDERS)[number];
+/**
+ * A chart query and how to draw it. The tile stores the structured spec and
+ * not the text, so a later change of the grammar cannot break a stored tile.
+ */
+export interface DashboardChartQuery extends ChartSpec {
+    render: DashboardChartRender;
+}
+/** One card of one cluster. */
+export interface DashboardClusterDetailQuery {
+    clusterId: string;
+    card: DashboardClusterCard;
+}
+/** One card of one organization. */
+export interface DashboardOrgDetailQuery {
+    orgId: string;
+    card: DashboardOrgCard;
+}
+interface DashboardTileBaseV1 {
+    /** Unique in its dashboard. The client makes it. */
+    id: string;
+    title: string;
+    layout: DashboardTileLayout;
+}
+export interface DashboardFleetQueryTileV1 extends DashboardTileBaseV1 {
+    kind: 'fleet-query';
+    query: DashboardFleetQuery;
+}
+export interface DashboardAnnotationsTileV1 extends DashboardTileBaseV1 {
+    kind: 'annotations';
+    query: DashboardAnnotationsQuery;
+}
+export type DashboardTileV1 = DashboardFleetQueryTileV1 | DashboardAnnotationsTileV1;
+export interface DashboardDefinitionV1 {
+    schemaVersion: 1;
+    tiles: DashboardTileV1[];
+}
+export interface DashboardClusterDetailTileV2 extends DashboardTileBaseV1 {
+    kind: 'cluster-detail';
+    query: DashboardClusterDetailQuery;
+}
+export interface DashboardOrgDetailTileV2 extends DashboardTileBaseV1 {
+    kind: 'org-detail';
+    query: DashboardOrgDetailQuery;
+}
+/** A section title. The `title` of the tile is the text. */
+export interface DashboardHeadingTileV2 extends DashboardTileBaseV1 {
+    kind: 'heading';
+}
+/** Plain text. Line breaks stay, and nothing in it is markup. */
+export interface DashboardNoteTileV2 extends DashboardTileBaseV1 {
+    kind: 'note';
+    body: string;
+}
+/**
+ * A link to a page of Control (a path that starts with `/`) or to an
+ * `https://` address. `isSafeDashboardLink` holds the rule.
+ */
+export interface DashboardLinkTileV2 extends DashboardTileBaseV1 {
+    kind: 'link';
+    url: string;
+}
+/**
+ * Version 2 adds kinds of tiles and changes no tile of version 1. A version 1
+ * row is a version 2 row with a lower number, so an upgrade only sets the
+ * number.
+ *
+ * The number moved because the kinds are new. A pod with version 1 code
+ * answers `unsupportedVersion` for a row with a new kind, and not a 500 from
+ * its serializer. A row with no new kind stays version 1, so that pod still
+ * reads it (`toStoredDashboardDefinition`).
+ */
+export type DashboardTileV2 = DashboardTileV1 | DashboardClusterDetailTileV2 | DashboardOrgDetailTileV2 | DashboardHeadingTileV2 | DashboardNoteTileV2 | DashboardLinkTileV2;
+export interface DashboardDefinitionV2 {
+    schemaVersion: 2;
+    tiles: DashboardTileV2[];
+}
+/** A chart of a metric of HDP. accounts-backend runs the query. */
+export interface DashboardChartTileV3 extends DashboardTileBaseV1 {
+    kind: 'chart';
+    query: DashboardChartQuery;
+}
+/**
+ * Version 3 adds the `chart` kind and changes no tile of version 2, for the
+ * same reason that version 2 moved the number. A row with no chart tile stays
+ * at version 1 or 2 (`toStoredDashboardDefinition`).
+ */
+export type DashboardTileV3 = DashboardTileV2 | DashboardChartTileV3;
+export interface DashboardDefinitionV3 {
+    schemaVersion: 3;
+    tiles: DashboardTileV3[];
+}
+/**
+ * Every shape that a row can hold. A row keeps its old shape until somebody
+ * saves the dashboard again.
+ */
+export type StoredDashboardDefinition = DashboardDefinitionV1 | DashboardDefinitionV2 | DashboardDefinitionV3;
+/** The current shape. Every DTO carries this one. */
+export type DashboardDefinition = DashboardDefinitionV3;
+export type DashboardTile = DashboardTileV3;
+export type DashboardFleetQueryTile = DashboardFleetQueryTileV1;
+export type DashboardAnnotationsTile = DashboardAnnotationsTileV1;
+export type DashboardClusterDetailTile = DashboardClusterDetailTileV2;
+export type DashboardOrgDetailTile = DashboardOrgDetailTileV2;
+export type DashboardHeadingTile = DashboardHeadingTileV2;
+export type DashboardNoteTile = DashboardNoteTileV2;
+export type DashboardLinkTile = DashboardLinkTileV2;
+export type DashboardChartTile = DashboardChartTileV3;
+/**
+ * `Omit` on a union merges its members into one shape. This one omits from
+ * each member, so the kinds stay apart.
+ */
+type OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** A tile as a client adds it to a dashboard. The backend places it. */
+export type DashboardNewTile = OmitEach<DashboardTile, 'layout'>;
+/** Who created or archived a dashboard. The same shape as `ApprovalActor`. */
+export interface DashboardActor {
+    userId: string;
+    email: string;
+}
+/**
+ * One dashboard in a list, without its tiles.
+ *
+ * The sidebar reads a list of these, so it never parses a definition.
+ */
+export interface DashboardSummaryDto {
+    id: string;
+    title: string;
+    tileCount: number;
+    createdBy: DashboardActor;
+    createdAt: string;
+    updatedAt: string;
+    /** Set when the dashboard is archived. An archived dashboard is read-only. */
+    archivedAt?: string;
+    archivedBy?: DashboardActor;
+    /** True when the CALLER pinned it. A pin is personal. */
+    pinned: boolean;
+}
+export interface DashboardDto extends DashboardSummaryDto {
+    definition: DashboardDefinition;
+    /**
+     * The version that the optimistic lock of a save compares. Send back the
+     * value of the read that the edit started from.
+     */
+    version: number;
+}
+export interface DashboardListDto {
+    dashboards: DashboardSummaryDto[];
+    page: {
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+/** One Lucene field that a search or a chart filter can use. */
+export interface DashboardCatalogueSearchField {
+    field: string;
+    label: string;
+    description: string;
+    type: SearchFieldType;
+    capabilities: SearchFieldCapability[];
+    enumValues?: string[];
+    example: string;
+}
+/** One metric of the chart tiles, without its SQL. */
+export interface DashboardCatalogueChartMetric {
+    id: string;
+    label: string;
+    description: string;
+    unit: ChartUnit;
+    dimensions: {
+        id: string;
+        label: string;
+        description: string;
+    }[];
+    filters: DashboardCatalogueSearchField[];
+    grains: ChartGrain[];
+    maxWindowDays: number;
+}
+/**
+ * What a client must know to write a dashboard definition: the kinds of tiles,
+ * the cards, the chart metrics and the limits. The answer of
+ * `GET /api/dashboards/catalogue`.
+ */
+export interface DashboardCatalogue {
+    definitionVersion: number;
+    limits: {
+        tiles: number;
+        gridColumns: number;
+        tileRowsMax: number;
+        titleMax: number;
+        noteMax: number;
+        linkUrlMax: number;
+        definitionBytesMax: number;
+    };
+    tileKinds: {
+        kind: DashboardTileKind;
+        description: string;
+    }[];
+    clusterCards: DashboardClusterCard[];
+    orgCards: DashboardOrgCard[];
+    fleetSearchFields: {
+        cluster: DashboardCatalogueSearchField[];
+        org: DashboardCatalogueSearchField[];
+    };
+    charts: {
+        /** False where the flag `control.dashboardCharts` is off. */
+        enabled: boolean;
+        grammar: string;
+        queryMaxLength: number;
+        renders: DashboardChartRender[];
+        grains: ChartGrain[];
+        windowUnits: ChartWindowUnit[];
+        defaults: {
+            grain: ChartGrain;
+            window: {
+                amount: number;
+                unit: ChartWindowUnit;
+            };
+            top: number;
+        };
+        topMax: number;
+        metrics: DashboardCatalogueChartMetric[];
+    };
+}
+export {};

package/dist/dtos/Dashboard.dto.js

@@ -0,0 +1,70 @@
+const DASHBOARD_TILES_MAX = 20;
+const DASHBOARD_GRID_COLUMNS = 12;
+const DASHBOARD_TILE_ROWS_MAX = 24;
+const DASHBOARD_GRID_ROWS_MAX = DASHBOARD_TILES_MAX * DASHBOARD_TILE_ROWS_MAX;
+const DASHBOARD_TITLE_MAX = 120;
+const DASHBOARD_DEFINITION_BYTES_MAX = 32768;
+const DASHBOARD_PAGE_SIZE_MAX = 200;
+const DASHBOARD_PAGE_SIZE_DEFAULT = 200;
+const DASHBOARD_DEFINITION_VERSION = 3;
+const DASHBOARD_TILE_KINDS = [
+  "fleet-query",
+  "annotations",
+  "cluster-detail",
+  "org-detail",
+  "heading",
+  "note",
+  "link",
+  "chart"
+];
+const DASHBOARD_CLUSTER_CARDS = [
+  "identity",
+  "component-status",
+  "datacenter",
+  "generation",
+  "plan",
+  "backup-encryption",
+  "settings-flags",
+  "external-idp",
+  "data-filters",
+  "auto-pause",
+  "change-history",
+  "disk-usage"
+];
+const DASHBOARD_ORG_CARDS = [
+  "summary",
+  "details",
+  "sales-plan",
+  "queued-operations",
+  "clusters",
+  "managed-llm",
+  "recent-activity"
+];
+const DASHBOARD_ENTITY_ID_MAX = 64;
+const DASHBOARD_NOTE_MAX = 1e3;
+const DASHBOARD_LINK_URL_MAX = 1e3;
+const DASHBOARD_CHART_RENDERS = [
+  "line",
+  "bar",
+  "stacked-bar",
+  "stat"
+];
+export {
+  DASHBOARD_CHART_RENDERS,
+  DASHBOARD_CLUSTER_CARDS,
+  DASHBOARD_DEFINITION_BYTES_MAX,
+  DASHBOARD_DEFINITION_VERSION,
+  DASHBOARD_ENTITY_ID_MAX,
+  DASHBOARD_GRID_COLUMNS,
+  DASHBOARD_GRID_ROWS_MAX,
+  DASHBOARD_LINK_URL_MAX,
+  DASHBOARD_NOTE_MAX,
+  DASHBOARD_ORG_CARDS,
+  DASHBOARD_PAGE_SIZE_DEFAULT,
+  DASHBOARD_PAGE_SIZE_MAX,
+  DASHBOARD_TILES_MAX,
+  DASHBOARD_TILE_KINDS,
+  DASHBOARD_TILE_ROWS_MAX,
+  DASHBOARD_TITLE_MAX
+};
+//# sourceMappingURL=Dashboard.dto.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/dtos/Dashboard.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 {\n  ChartGrain,\n  ChartSpec,\n  ChartUnit,\n  ChartWindowUnit,\n} from '../charts/chart-spec.js'\nimport type {\n  SearchFieldCapability,\n  SearchFieldType,\n} from '../search/fields.js'\nimport type { AnnotationEntityKind, AnnotationKind } from './Annotation.dto.js'\n\n/**\n * The wire types of the dashboards of Camunda Control.\n *\n * A dashboard stores QUESTIONS and never answers. A tile holds the filters of\n * the page that it came from, and the dashboard runs them again each time a\n * reader opens it. So a stored dashboard stays small, and it never holds a\n * copy of fleet data that can go stale or leak.\n *\n * control-backend and control-frontend both read this file, so it holds no\n * logic with I/O and no dependency.\n */\n\n/** DASHBOARD_TILES_MAX is the most tiles that one dashboard can hold. */\nexport const DASHBOARD_TILES_MAX = 20\n\n/** DASHBOARD_GRID_COLUMNS is the width of the tile grid, in columns. */\nexport const DASHBOARD_GRID_COLUMNS = 12\n\n/** DASHBOARD_TILE_ROWS_MAX is the tallest tile, in grid rows. */\nexport const DASHBOARD_TILE_ROWS_MAX = 24\n\n/**\n * DASHBOARD_GRID_ROWS_MAX is the lowest row that a tile can start on. It is\n * the height of 20 tiles of the tallest size, one under the other, so a\n * compact grid never reaches it.\n */\nexport const DASHBOARD_GRID_ROWS_MAX =\n  DASHBOARD_TILES_MAX * DASHBOARD_TILE_ROWS_MAX\n\n/** DASHBOARD_TITLE_MAX is the longest title of a dashboard or of a tile. */\nexport const DASHBOARD_TITLE_MAX = 120\n\n/**\n * DASHBOARD_DEFINITION_BYTES_MAX is the largest definition that the backend\n * stores, as JSON text. Twenty tiles of filters need a few kilobytes, so a\n * larger body is a client that tries to store data and not filters.\n */\nexport const DASHBOARD_DEFINITION_BYTES_MAX = 32_768\n\n/** DASHBOARD_PAGE_SIZE_MAX is the most dashboards that one list page holds. */\nexport const DASHBOARD_PAGE_SIZE_MAX = 200\n\n/** DASHBOARD_PAGE_SIZE_DEFAULT is the list page size when a caller sends none. */\nexport const DASHBOARD_PAGE_SIZE_DEFAULT = 200\n\n/**\n * DASHBOARD_DEFINITION_VERSION is the `schemaVersion` that this code writes.\n *\n * Raise it when the shape of the definition changes, add the old shape to\n * `StoredDashboardDefinition`, and teach `upgradeDashboardDefinition` to read\n * it. A row is never rewritten in place: it moves to the new version on its\n * next save.\n */\nexport const DASHBOARD_DEFINITION_VERSION = 3\n\n/**\n * Every kind of tile.\n *\n * `fleet-query` and `annotations` run saved filters. `cluster-detail` and\n * `org-detail` show one card of the page of one cluster or one organization.\n * `heading`, `note` and `link` hold text that a person wrote, and fetch\n * nothing. `chart` runs a chart query on HDP.\n */\nexport const DASHBOARD_TILE_KINDS = [\n  'fleet-query',\n  'annotations',\n  'cluster-detail',\n  'org-detail',\n  'heading',\n  'note',\n  'link',\n  'chart',\n] as const\n\nexport type DashboardTileKind = (typeof DASHBOARD_TILE_KINDS)[number]\n\n/** Where a tile sits on the grid, in columns and rows from the top left. */\nexport interface DashboardTileLayout {\n  x: number\n  y: number\n  w: number\n  h: number\n}\n\n/**\n * The search params of a Fleet query page, as that page writes them.\n *\n * The backend stores them as they are and checks only their shape: flat\n * values, no objects. The keys belong to the Fleet query page, so the\n * frontend validates them on read with the same function that validates the\n * URL. A tile with a key that this function drops does not run, because the\n * query would be wider than the one that was saved.\n */\nexport type DashboardFleetQuery = Record<\n  string,\n  string | number | boolean | string[]\n>\n\n/** The filters of the Notes & tags page. */\nexport interface DashboardAnnotationsQuery {\n  kind?: AnnotationKind\n  entityKind?: AnnotationEntityKind\n  tag?: string\n  q?: string\n}\n\n/**\n * The cards of the Overview tab of a cluster that a dashboard can show.\n *\n * The id names the card and never its content. The tile reads the cluster\n * again each time it is in view, so it shows the current state.\n */\nexport const DASHBOARD_CLUSTER_CARDS = [\n  'identity',\n  'component-status',\n  'datacenter',\n  'generation',\n  'plan',\n  'backup-encryption',\n  'settings-flags',\n  'external-idp',\n  'data-filters',\n  'auto-pause',\n  'change-history',\n  'disk-usage',\n] as const\n\nexport type DashboardClusterCard = (typeof DASHBOARD_CLUSTER_CARDS)[number]\n\n/** The cards of the Overview tab of an organization. */\nexport const DASHBOARD_ORG_CARDS = [\n  'summary',\n  'details',\n  'sales-plan',\n  'queued-operations',\n  'clusters',\n  'managed-llm',\n  'recent-activity',\n] as const\n\nexport type DashboardOrgCard = (typeof DASHBOARD_ORG_CARDS)[number]\n\n/** DASHBOARD_ENTITY_ID_MAX is the longest cluster id or organization id. */\nexport const DASHBOARD_ENTITY_ID_MAX = 64\n\n/**\n * DASHBOARD_NOTE_MAX is the longest text of a note tile.\n *\n * Twenty full notes of ASCII text fit in `DASHBOARD_DEFINITION_BYTES_MAX`.\n * Text with characters of more than one UTF-8 byte can pass that limit first,\n * so the frontend measures the whole definition with\n * `dashboardDefinitionBytes` before it saves.\n */\nexport const DASHBOARD_NOTE_MAX = 1000\n\n/** DASHBOARD_LINK_URL_MAX is the longest address of a link tile. */\nexport const DASHBOARD_LINK_URL_MAX = 1000\n\n/**\n * How a chart tile draws its result. `stat` is one number with a sparkline.\n * Each render is a chart of `@camunda/design-system`, which has no area chart.\n */\nexport const DASHBOARD_CHART_RENDERS = [\n  'line',\n  'bar',\n  'stacked-bar',\n  'stat',\n] as const\n\nexport type DashboardChartRender = (typeof DASHBOARD_CHART_RENDERS)[number]\n\n/**\n * A chart query and how to draw it. The tile stores the structured spec and\n * not the text, so a later change of the grammar cannot break a stored tile.\n */\nexport interface DashboardChartQuery extends ChartSpec {\n  render: DashboardChartRender\n}\n\n/** One card of one cluster. */\nexport interface DashboardClusterDetailQuery {\n  clusterId: string\n  card: DashboardClusterCard\n}\n\n/** One card of one organization. */\nexport interface DashboardOrgDetailQuery {\n  orgId: string\n  card: DashboardOrgCard\n}\n\ninterface DashboardTileBaseV1 {\n  /** Unique in its dashboard. The client makes it. */\n  id: string\n  title: string\n  layout: DashboardTileLayout\n}\n\nexport interface DashboardFleetQueryTileV1 extends DashboardTileBaseV1 {\n  kind: 'fleet-query'\n  query: DashboardFleetQuery\n}\n\nexport interface DashboardAnnotationsTileV1 extends DashboardTileBaseV1 {\n  kind: 'annotations'\n  query: DashboardAnnotationsQuery\n}\n\nexport type DashboardTileV1 =\n  | DashboardFleetQueryTileV1\n  | DashboardAnnotationsTileV1\n\nexport interface DashboardDefinitionV1 {\n  schemaVersion: 1\n  tiles: DashboardTileV1[]\n}\n\nexport interface DashboardClusterDetailTileV2 extends DashboardTileBaseV1 {\n  kind: 'cluster-detail'\n  query: DashboardClusterDetailQuery\n}\n\nexport interface DashboardOrgDetailTileV2 extends DashboardTileBaseV1 {\n  kind: 'org-detail'\n  query: DashboardOrgDetailQuery\n}\n\n/** A section title. The `title` of the tile is the text. */\nexport interface DashboardHeadingTileV2 extends DashboardTileBaseV1 {\n  kind: 'heading'\n}\n\n/** Plain text. Line breaks stay, and nothing in it is markup. */\nexport interface DashboardNoteTileV2 extends DashboardTileBaseV1 {\n  kind: 'note'\n  body: string\n}\n\n/**\n * A link to a page of Control (a path that starts with `/`) or to an\n * `https://` address. `isSafeDashboardLink` holds the rule.\n */\nexport interface DashboardLinkTileV2 extends DashboardTileBaseV1 {\n  kind: 'link'\n  url: string\n}\n\n/**\n * Version 2 adds kinds of tiles and changes no tile of version 1. A version 1\n * row is a version 2 row with a lower number, so an upgrade only sets the\n * number.\n *\n * The number moved because the kinds are new. A pod with version 1 code\n * answers `unsupportedVersion` for a row with a new kind, and not a 500 from\n * its serializer. A row with no new kind stays version 1, so that pod still\n * reads it (`toStoredDashboardDefinition`).\n */\nexport type DashboardTileV2 =\n  | DashboardTileV1\n  | DashboardClusterDetailTileV2\n  | DashboardOrgDetailTileV2\n  | DashboardHeadingTileV2\n  | DashboardNoteTileV2\n  | DashboardLinkTileV2\n\nexport interface DashboardDefinitionV2 {\n  schemaVersion: 2\n  tiles: DashboardTileV2[]\n}\n\n/** A chart of a metric of HDP. accounts-backend runs the query. */\nexport interface DashboardChartTileV3 extends DashboardTileBaseV1 {\n  kind: 'chart'\n  query: DashboardChartQuery\n}\n\n/**\n * Version 3 adds the `chart` kind and changes no tile of version 2, for the\n * same reason that version 2 moved the number. A row with no chart tile stays\n * at version 1 or 2 (`toStoredDashboardDefinition`).\n */\nexport type DashboardTileV3 = DashboardTileV2 | DashboardChartTileV3\n\nexport interface DashboardDefinitionV3 {\n  schemaVersion: 3\n  tiles: DashboardTileV3[]\n}\n\n/**\n * Every shape that a row can hold. A row keeps its old shape until somebody\n * saves the dashboard again.\n */\nexport type StoredDashboardDefinition =\n  | DashboardDefinitionV1\n  | DashboardDefinitionV2\n  | DashboardDefinitionV3\n\n/** The current shape. Every DTO carries this one. */\nexport type DashboardDefinition = DashboardDefinitionV3\nexport type DashboardTile = DashboardTileV3\nexport type DashboardFleetQueryTile = DashboardFleetQueryTileV1\nexport type DashboardAnnotationsTile = DashboardAnnotationsTileV1\nexport type DashboardClusterDetailTile = DashboardClusterDetailTileV2\nexport type DashboardOrgDetailTile = DashboardOrgDetailTileV2\nexport type DashboardHeadingTile = DashboardHeadingTileV2\nexport type DashboardNoteTile = DashboardNoteTileV2\nexport type DashboardLinkTile = DashboardLinkTileV2\nexport type DashboardChartTile = DashboardChartTileV3\n\n/**\n * `Omit` on a union merges its members into one shape. This one omits from\n * each member, so the kinds stay apart.\n */\ntype OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never\n\n/** A tile as a client adds it to a dashboard. The backend places it. */\nexport type DashboardNewTile = OmitEach<DashboardTile, 'layout'>\n\n/** Who created or archived a dashboard. The same shape as `ApprovalActor`. */\nexport interface DashboardActor {\n  userId: string\n  email: string\n}\n\n/**\n * One dashboard in a list, without its tiles.\n *\n * The sidebar reads a list of these, so it never parses a definition.\n */\nexport interface DashboardSummaryDto {\n  id: string\n  title: string\n  tileCount: number\n  createdBy: DashboardActor\n  createdAt: string\n  updatedAt: string\n  /** Set when the dashboard is archived. An archived dashboard is read-only. */\n  archivedAt?: string\n  archivedBy?: DashboardActor\n  /** True when the CALLER pinned it. A pin is personal. */\n  pinned: boolean\n}\n\nexport interface DashboardDto extends DashboardSummaryDto {\n  definition: DashboardDefinition\n  /**\n   * The version that the optimistic lock of a save compares. Send back the\n   * value of the read that the edit started from.\n   */\n  version: number\n}\n\nexport interface DashboardListDto {\n  dashboards: DashboardSummaryDto[]\n  page: { limit: number; offset: number; hasMore: boolean }\n}\n\n/** One Lucene field that a search or a chart filter can use. */\nexport interface DashboardCatalogueSearchField {\n  field: string\n  label: string\n  description: string\n  type: SearchFieldType\n  capabilities: SearchFieldCapability[]\n  enumValues?: string[]\n  example: string\n}\n\n/** One metric of the chart tiles, without its SQL. */\nexport interface DashboardCatalogueChartMetric {\n  id: string\n  label: string\n  description: string\n  unit: ChartUnit\n  dimensions: { id: string; label: string; description: string }[]\n  filters: DashboardCatalogueSearchField[]\n  grains: ChartGrain[]\n  maxWindowDays: number\n}\n\n/**\n * What a client must know to write a dashboard definition: the kinds of tiles,\n * the cards, the chart metrics and the limits. The answer of\n * `GET /api/dashboards/catalogue`.\n */\nexport interface DashboardCatalogue {\n  definitionVersion: number\n  limits: {\n    tiles: number\n    gridColumns: number\n    tileRowsMax: number\n    titleMax: number\n    noteMax: number\n    linkUrlMax: number\n    definitionBytesMax: number\n  }\n  tileKinds: { kind: DashboardTileKind; description: string }[]\n  clusterCards: DashboardClusterCard[]\n  orgCards: DashboardOrgCard[]\n  fleetSearchFields: {\n    cluster: DashboardCatalogueSearchField[]\n    org: DashboardCatalogueSearchField[]\n  }\n  charts: {\n    /** False where the flag `control.dashboardCharts` is off. */\n    enabled: boolean\n    grammar: string\n    queryMaxLength: number\n    renders: DashboardChartRender[]\n    grains: ChartGrain[]\n    windowUnits: ChartWindowUnit[]\n    defaults: {\n      grain: ChartGrain\n      window: { amount: number; unit: ChartWindowUnit }\n      top: number\n    }\n    topMax: number\n    metrics: DashboardCatalogueChartMetric[]\n  }\n}\n"],
+  "mappings": "AA+BO,MAAM,sBAAsB;AAG5B,MAAM,yBAAyB;AAG/B,MAAM,0BAA0B;AAOhC,MAAM,0BACX,sBAAsB;AAGjB,MAAM,sBAAsB;AAO5B,MAAM,iCAAiC;AAGvC,MAAM,0BAA0B;AAGhC,MAAM,8BAA8B;AAUpC,MAAM,+BAA+B;AAUrC,MAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAwCO,MAAM,0BAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAKO,MAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAKO,MAAM,0BAA0B;AAUhC,MAAM,qBAAqB;AAG3B,MAAM,yBAAyB;AAM/B,MAAM,0BAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;",
+  "names": []
+}

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

@@ -1,59 +1,93 @@
 /**
- * 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 flags of one caller, as `GET /api/feature-flags/evaluate` of
+ * control-backend and `GET external/feature-flags` of accounts-backend send
+ * them. Nested by the segments of the key: `console.byoidp` is
+ * `{ console: { byoidp: true } }`.
  *
- * 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 keys are not typed. The flag table of each stage holds them, and a key
+ * that the table does not hold is not in the answer. A reader takes one flag
+ * by its key and reads a missing one as off: `isFeatureOn` of
+ * `@camunda-cloud/featureflags`, or `useC4FeatureFlag('console.byoidp')` in
+ * c4.
+ */
+export interface FeatureFlagAnswer {
+    [segment: string]: boolean | FeatureFlagAnswer;
+}
+/**
+ * One feature flag, as a row of the table of control-backend.
  *
- * A c4 host reads one flag with `useC4FeatureFlag('console.appIntegrations')`
- * — a dot path into this object.
+ * Each stage holds its own database, thus a row is the value of THAT stage. A
+ * flag is on for a caller when `enabled` is true, when the org of the caller
+ * is in `orgIds`, or when the domain of the email of the caller is in
+ * `emailDomains`. `evaluateFlags` of `@camunda-cloud/featureflags` holds that
+ * rule.
  */
-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;
-        hubUpgradeBanner: boolean;
-    };
-    control: {
-        frontendTelemetry: boolean;
-        approvals: boolean;
-        annotations: boolean;
-        clusterHostingCostBreakdown: boolean;
-        /** Per-cluster disk usage chart (Elasticsearch and Zeebe) on the cluster page. */
-        elasticsearchUsageChart: boolean;
-        fleetHostingCost: boolean;
-    };
-    accounts: {
-        moveClusterOrg: boolean;
-        orgLimitAuditLog: boolean;
-        orgReservationAuditLog: boolean;
-        deleteLiteLLMKeyOnTrialExpiry: boolean;
-    };
-    shared: {
-        cyberpunkBrutalism: boolean;
-        tenantsValueMetric: boolean;
-        hdpValueMetricsFor2025: boolean;
-        permissionsRework: boolean;
-    };
+export interface FeatureFlagDto {
+    id: string;
+    /** The dot path, for example `console.byoidp`. It cannot change. */
+    key: string;
+    /** Why the flag exists. */
+    description: string;
+    /** The value for everybody. */
+    enabled: boolean;
+    /** Organizations that get the flag when `enabled` is false. */
+    orgIds: string[];
+    /** Lower-case email domains, with no `@`. */
+    emailDomains: string[];
+    /**
+     * The team that owns the flag, for example `team-console`. Absent on an
+     * older row that nobody gave an owner.
+     */
+    owner?: string;
+    /**
+     * The day after which the flag is late, as `YYYY-MM-DD`. The page warns
+     * from that day on. Absent for a flag that has no end, such as a permission.
+     */
+    expiresAt?: string;
+    createdAt: string;
+    /**
+     * The email of the person who made the row, or the name of the seed
+     * migration. `UNKNOWN_ACTOR_EMAIL` for a token with no email.
+     */
+    createdBy: string;
+    updatedAt: string;
+    /** The email of the person who changed the row last, as `createdBy`. */
+    updatedBy: string;
 }
+/**
+ * The answer of `GET /api/feature-flags`: every row of the stage, and the two
+ * versions that show whether the other services read the rows yet.
+ */
+export interface FeatureFlagListDto {
+    flags: FeatureFlagDto[];
+    /** The version of the table. Every write raises it. */
+    tableVersion: number;
+    /**
+     * The version that the Redis key holds, which console-backend and
+     * accounts-backend read. Absent on a stage with no Redis, and when
+     * control-backend cannot read the key. While it is lower than
+     * `tableVersion`, those services still answer from the rows before.
+     */
+    publishedVersion?: number;
+}
+/** What a create sends. The key cannot change after this. */
+export interface CreateFeatureFlagDto {
+    key: string;
+    description: string;
+    enabled: boolean;
+    orgIds: string[];
+    emailDomains: string[];
+    /** Required for a new flag: a flag with no owner is a flag nobody removes. */
+    owner: string;
+    /** `YYYY-MM-DD`. Give it for a flag that gates a rollout. */
+    expiresAt?: string;
+}
+type EditableFeatureFlagFields = Omit<CreateFeatureFlagDto, 'key'>;
+/**
+ * What an edit sends: at least one field. A field that is absent stays as it
+ * is. The route answers 400 to an empty body.
+ */
+export type UpdateFeatureFlagDto = {
+    [Field in keyof EditableFeatureFlagFields]: Pick<EditableFeatureFlagFields, Field> & Partial<EditableFeatureFlagFields>;
+}[keyof EditableFeatureFlagFields];
+export {};