@camunda/ccma-shared-types 5.0.0 → 6.0.0

package/dist/_tests/approvals/dns-subdomain.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/_tests/approvals/expected-value.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/_tests/charts/chart-query.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/_tests/dashboards/definition.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/_tests/utils/elasticsearchPlanPath.utils.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/approvals/dns-subdomain.d.ts

@@ -0,0 +1,12 @@
+/** The longest DNS subdomain that Kubernetes accepts as a resource name. */
+export declare const DNS_SUBDOMAIN_MAX_LENGTH = 253;
+/**
+ * True when a name is a DNS-1123 subdomain, as Kubernetes accepts one for
+ * the name of a resource.
+ *
+ * Each dot-separated label is 1 to 63 characters of lower case letters,
+ * digits and `-`, and starts and ends with a letter or a digit. A single
+ * regular expression over the whole name accepts `a..b` and a label of 64
+ * characters, and Kubernetes refuses both.
+ */
+export declare function isDnsSubdomain(name: string): boolean;

package/dist/approvals/dns-subdomain.js

@@ -0,0 +1,16 @@
+const DNS_SUBDOMAIN_MAX_LENGTH = 253;
+const DNS_LABEL = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/;
+const DNS_LABEL_MAX_LENGTH = 63;
+function isDnsSubdomain(name) {
+  if (name.length === 0 || name.length > DNS_SUBDOMAIN_MAX_LENGTH) {
+    return false;
+  }
+  return name.split(".").every(
+    (label) => label.length <= DNS_LABEL_MAX_LENGTH && DNS_LABEL.test(label)
+  );
+}
+export {
+  DNS_SUBDOMAIN_MAX_LENGTH,
+  isDnsSubdomain
+};
+//# sourceMappingURL=dns-subdomain.js.map

package/dist/approvals/dns-subdomain.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/approvals/dns-subdomain.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/** The longest DNS subdomain that Kubernetes accepts as a resource name. */\nexport const DNS_SUBDOMAIN_MAX_LENGTH = 253\n\nconst DNS_LABEL = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/\nconst DNS_LABEL_MAX_LENGTH = 63\n\n/**\n * True when a name is a DNS-1123 subdomain, as Kubernetes accepts one for\n * the name of a resource.\n *\n * Each dot-separated label is 1 to 63 characters of lower case letters,\n * digits and `-`, and starts and ends with a letter or a digit. A single\n * regular expression over the whole name accepts `a..b` and a label of 64\n * characters, and Kubernetes refuses both.\n */\nexport function isDnsSubdomain(name: string): boolean {\n  if (name.length === 0 || name.length > DNS_SUBDOMAIN_MAX_LENGTH) {\n    return false\n  }\n  return name\n    .split('.')\n    .every(\n      (label) => label.length <= DNS_LABEL_MAX_LENGTH && DNS_LABEL.test(label),\n    )\n}\n"],
+  "mappings": "AAOO,MAAM,2BAA2B;AAExC,MAAM,YAAY;AAClB,MAAM,uBAAuB;AAWtB,SAAS,eAAe,MAAuB;AACpD,MAAI,KAAK,WAAW,KAAK,KAAK,SAAS,0BAA0B;AAC/D,WAAO;AAAA,EACT;AACA,SAAO,KACJ,MAAM,GAAG,EACT;AAAA,IACC,CAAC,UAAU,MAAM,UAAU,wBAAwB,UAAU,KAAK,KAAK;AAAA,EACzE;AACJ;",
+  "names": []
+}

package/dist/approvals/expected-value.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The guard against a stale approval.
+ *
+ * Days can pass between the request and the run. A request that says "set X
+ * from 3 to 5" was approved as a CHANGE from 3. When somebody else set X to 4
+ * in the meantime, the run must not write 5 over the 4: the approvers never
+ * read that change, and they never agreed to undo it.
+ *
+ * So a use case that writes a value carries the value that the person who
+ * asked READ, as `expected`. The service that owns the value compares it with
+ * what it holds when the call ARRIVES, and it refuses the whole change when one
+ * value moved. It never applies a part of it: the approvers read the change as
+ * one thing.
+ *
+ * The comparison lives here so that the form of control-frontend, the use case
+ * of control-backend and the route of accounts-backend read "the same value"
+ * in one way.
+ */
+/** One value that a request writes, with the value that the asker read. */
+export interface ApprovalExpectedChange<T = unknown> {
+    key: string;
+    /** The value that the person who asked read. `undefined` for "not set". */
+    expected?: T;
+}
+/** True when the value that the asker read is the value that the service holds. */
+export declare function isSameApprovalValue(expected: unknown, current: unknown): boolean;
+/**
+ * The keys of a change whose value moved since the person who asked read it.
+ *
+ * An empty answer means the change can run. Any other answer means none of it
+ * can.
+ */
+export declare function staleApprovalKeys(changes: readonly ApprovalExpectedChange[], currentOf: (key: string) => unknown): string[];

package/dist/approvals/expected-value.js

@@ -0,0 +1,26 @@
+function canonical(value) {
+  if (value === void 0 || value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonical).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value).filter(([, inner]) => inner !== void 0).sort(([one], [other]) => one < other ? -1 : one > other ? 1 : 0).map(([key, inner]) => `${JSON.stringify(key)}:${canonical(inner)}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function isSameApprovalValue(expected, current) {
+  return canonical(expected) === canonical(current);
+}
+function staleApprovalKeys(changes, currentOf) {
+  return changes.filter(
+    (change) => !isSameApprovalValue(change.expected, currentOf(change.key))
+  ).map((change) => change.key);
+}
+export {
+  isSameApprovalValue,
+  staleApprovalKeys
+};
+//# sourceMappingURL=expected-value.js.map

package/dist/approvals/expected-value.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/approvals/expected-value.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 * The guard against a stale approval.\n *\n * Days can pass between the request and the run. A request that says \"set X\n * from 3 to 5\" was approved as a CHANGE from 3. When somebody else set X to 4\n * in the meantime, the run must not write 5 over the 4: the approvers never\n * read that change, and they never agreed to undo it.\n *\n * So a use case that writes a value carries the value that the person who\n * asked READ, as `expected`. The service that owns the value compares it with\n * what it holds when the call ARRIVES, and it refuses the whole change when one\n * value moved. It never applies a part of it: the approvers read the change as\n * one thing.\n *\n * The comparison lives here so that the form of control-frontend, the use case\n * of control-backend and the route of accounts-backend read \"the same value\"\n * in one way.\n */\n\n/** One value that a request writes, with the value that the asker read. */\nexport interface ApprovalExpectedChange<T = unknown> {\n  key: string\n  /** The value that the person who asked read. `undefined` for \"not set\". */\n  expected?: T\n}\n\n/**\n * Turns a value into the one text that two equal values share.\n *\n * `undefined` and `null` both mean \"not set\", because a JSON body cannot carry\n * `undefined` and a database column reads as `null`. The keys of an object\n * are sorted, because two objects with the same fields in another order are\n * the same value.\n */\nfunction canonical(value: unknown): string {\n  if (value === undefined || value === null) {\n    return 'null'\n  }\n  if (Array.isArray(value)) {\n    return `[${value.map(canonical).join(',')}]`\n  }\n  if (typeof value === 'object') {\n    const entries = Object.entries(value as Record<string, unknown>)\n      .filter(([, inner]) => inner !== undefined)\n      .sort(([one], [other]) => (one < other ? -1 : one > other ? 1 : 0))\n      .map(([key, inner]) => `${JSON.stringify(key)}:${canonical(inner)}`)\n    return `{${entries.join(',')}}`\n  }\n  return JSON.stringify(value)\n}\n\n/** True when the value that the asker read is the value that the service holds. */\nexport function isSameApprovalValue(\n  expected: unknown,\n  current: unknown,\n): boolean {\n  return canonical(expected) === canonical(current)\n}\n\n/**\n * The keys of a change whose value moved since the person who asked read it.\n *\n * An empty answer means the change can run. Any other answer means none of it\n * can.\n */\nexport function staleApprovalKeys(\n  changes: readonly ApprovalExpectedChange[],\n  currentOf: (key: string) => unknown,\n): string[] {\n  return changes\n    .filter(\n      (change) => !isSameApprovalValue(change.expected, currentOf(change.key)),\n    )\n    .map((change) => change.key)\n}\n"],
+  "mappings": "AAwCA,SAAS,UAAU,OAAwB;AACzC,MAAI,UAAU,UAAa,UAAU,MAAM;AACzC,WAAO;AAAA,EACT;AACA,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,IAAI,MAAM,IAAI,SAAS,EAAE,KAAK,GAAG,CAAC;AAAA,EAC3C;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,UAAU,OAAO,QAAQ,KAAgC,EAC5D,OAAO,CAAC,CAAC,EAAE,KAAK,MAAM,UAAU,MAAS,EACzC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,MAAO,MAAM,QAAQ,KAAK,MAAM,QAAQ,IAAI,CAAE,EACjE,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,GAAG,KAAK,UAAU,GAAG,CAAC,IAAI,UAAU,KAAK,CAAC,EAAE;AACrE,WAAO,IAAI,QAAQ,KAAK,GAAG,CAAC;AAAA,EAC9B;AACA,SAAO,KAAK,UAAU,KAAK;AAC7B;AAGO,SAAS,oBACd,UACA,SACS;AACT,SAAO,UAAU,QAAQ,MAAM,UAAU,OAAO;AAClD;AAQO,SAAS,kBACd,SACA,WACU;AACV,SAAO,QACJ;AAAA,IACC,CAAC,WAAW,CAAC,oBAAoB,OAAO,UAAU,UAAU,OAAO,GAAG,CAAC;AAAA,EACzE,EACC,IAAI,CAAC,WAAW,OAAO,GAAG;AAC/B;",
+  "names": []
+}

package/dist/approvals/use-cases.const.d.ts

@@ -23,7 +23,27 @@ export declare const APPROVAL_USE_CASE_TYPES: {
     readonly clusterBulkSleepWakeup: "cluster-bulk-sleep-wakeup";
     readonly clusterBulkDeletion: "cluster-bulk-deletion";
     readonly clusterBulkSpecUpdate: "cluster-bulk-spec-update";
+    readonly changePlatformRoles: "change-platform-roles";
+    readonly deleteInternalBackup: "delete-internal-backup";
+    readonly changeOrgLimits: "change-org-limits";
+    readonly deleteSsoConnection: "delete-sso-connection";
+    readonly changeSalesPlan: "change-sales-plan";
+    readonly deleteOrganization: "delete-organization";
+    readonly deleteUser: "delete-user";
+    readonly changeUserEmail: "change-user-email";
+    readonly purgeUsers: "purge-users";
+    readonly updateUserMetadata: "update-user-metadata";
+    readonly changeFeatureFlag: "change-feature-flag";
 };
+/**
+ * The approvals that a change of the feature flag table needs on prod.
+ *
+ * A flag there turns a feature on or off for every customer, and a person who
+ * holds `aafw` could do it alone. Two other Camundis stand in every change,
+ * the same floor as a cluster bulk operation on prod
+ * (`CLUSTER_BULK_OPERATION_MIN_ACKS`). Int needs one.
+ */
+export declare const FEATURE_FLAG_MIN_ACKS_PROD = 2;
 export type ApprovalUseCaseType = (typeof APPROVAL_USE_CASE_TYPES)[keyof typeof APPROVAL_USE_CASE_TYPES];
 /**
  * The shortest extension that accounts-backend accepts.
@@ -46,3 +66,63 @@ export declare const EXTEND_TRIAL_MIN_DAYS = 15;
  * margin as the floor above.
  */
 export declare const EXTEND_TRIAL_MAX_DAYS = 61;
+/**
+ * The most roles that one change-platform-roles request adds, or removes.
+ *
+ * The form of control-frontend offers every platform role, and a person who
+ * gives a Camundi a new position rarely changes more than a few. A request with
+ * more roles than this is a request that nobody reads before they approve it.
+ */
+export declare const PLATFORM_ROLE_CHANGE_MAX_ROLES = 10;
+/**
+ * The longest text value that one change-org-limits request writes.
+ *
+ * A text limit holds a short value, such as a list of regions. The bound keeps
+ * a request readable for the person who approves it.
+ */
+export declare const ORG_LIMIT_TEXT_MAX_LENGTH = 2000;
+/**
+ * The most users that one purge-users request deletes.
+ *
+ * The God Mode purge deletes one user after the other, and Auth0 limits how
+ * fast that goes. A list longer than this is also a list that no approver
+ * reads before they agree.
+ */
+export declare const PURGE_USERS_MAX_USERS = 1000;
+/**
+ * What a person must hold to open or to approve a purge-users request.
+ *
+ * The purge of God Mode is behind `GOD_PURGE_USERS`, and each deletion calls a
+ * route behind `DELETE_USER`. The use case of control-backend returns this
+ * list from `permissionsFor`, and the form passes it to `canCreate`, so the
+ * button and the server never disagree.
+ */
+export declare const PURGE_USERS_REQUIRED_PERMISSIONS: readonly string[];
+/**
+ * The largest metadata object that one update-user-metadata request writes,
+ * in characters of its JSON text.
+ *
+ * This is a bound of the product, and not the limit of Auth0, which is far
+ * larger. The approvers read the whole object before they agree, and an
+ * object that is longer than this is an object that nobody reads.
+ */
+export declare const USER_METADATA_MAX_LENGTH = 16000;
+/**
+ * The largest metadata object that a request carries as the object that the
+ * person who asked READ.
+ *
+ * It is larger than `USER_METADATA_MAX_LENGTH`, so a user whose metadata grew
+ * past that bound can still get an edit that makes it smaller. It still has a
+ * bound, because the request keeps the copy in its row.
+ */
+export declare const USER_METADATA_EXPECTED_MAX_LENGTH = 500000;
+/** The longest email address that a change-user-email request carries. */
+export declare const APPROVAL_EMAIL_MAX_LENGTH = 320;
+/**
+ * The email addresses that a change-user-email request accepts.
+ *
+ * It is the email pattern of zod 4.6. The pattern is here, so the schema of
+ * control-backend and the form of control-frontend accept the same addresses,
+ * and a form never sends an address that the service refuses.
+ */
+export declare const APPROVAL_EMAIL_PATTERN: RegExp;

package/dist/approvals/use-cases.const.js

@@ -1,3 +1,4 @@
+import { AccountsPermissions } from "../permissions/accounts.permissions.js";
 const APPROVAL_USE_CASE_TYPES = {
   sendToExpiredTrial: "send-to-expired-trial",
   extendTrial: "extend-trial",
@@ -10,13 +11,52 @@ const APPROVAL_USE_CASE_TYPES = {
   clusterBulkPlanTypeUpdate: "cluster-bulk-plan-type-update",
   clusterBulkSleepWakeup: "cluster-bulk-sleep-wakeup",
   clusterBulkDeletion: "cluster-bulk-deletion",
-  clusterBulkSpecUpdate: "cluster-bulk-spec-update"
+  clusterBulkSpecUpdate: "cluster-bulk-spec-update",
+  // The second group, behind `control.approvalAdminActions`.
+  changePlatformRoles: "change-platform-roles",
+  deleteInternalBackup: "delete-internal-backup",
+  changeOrgLimits: "change-org-limits",
+  deleteSsoConnection: "delete-sso-connection",
+  changeSalesPlan: "change-sales-plan",
+  // The third group, behind `control.approvalAccountActions`.
+  deleteOrganization: "delete-organization",
+  deleteUser: "delete-user",
+  changeUserEmail: "change-user-email",
+  purgeUsers: "purge-users",
+  updateUserMetadata: "update-user-metadata",
+  // A change of the feature flag table, on a stage where
+  // `isFeatureFlagApprovalRequired` is true.
+  changeFeatureFlag: "change-feature-flag"
 };
+const FEATURE_FLAG_MIN_ACKS_PROD = 2;
 const EXTEND_TRIAL_MIN_DAYS = 15;
 const EXTEND_TRIAL_MAX_DAYS = 61;
+const PLATFORM_ROLE_CHANGE_MAX_ROLES = 10;
+const ORG_LIMIT_TEXT_MAX_LENGTH = 2e3;
+const PURGE_USERS_MAX_USERS = 1e3;
+const PURGE_USERS_REQUIRED_PERMISSIONS = [
+  AccountsPermissions.GOD_PURGE_USERS,
+  AccountsPermissions.DELETE_USER
+];
+const USER_METADATA_MAX_LENGTH = 16e3;
+const USER_METADATA_EXPECTED_MAX_LENGTH = 5e5;
+const APPROVAL_EMAIL_MAX_LENGTH = 320;
+const APPROVAL_EMAIL_PATTERN = (
+  // biome-ignore lint/complexity/noUselessEscapeInRegex: the same source as zod, character for character
+  /^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/
+);
 export {
+  APPROVAL_EMAIL_MAX_LENGTH,
+  APPROVAL_EMAIL_PATTERN,
   APPROVAL_USE_CASE_TYPES,
   EXTEND_TRIAL_MAX_DAYS,
-  EXTEND_TRIAL_MIN_DAYS
+  EXTEND_TRIAL_MIN_DAYS,
+  FEATURE_FLAG_MIN_ACKS_PROD,
+  ORG_LIMIT_TEXT_MAX_LENGTH,
+  PLATFORM_ROLE_CHANGE_MAX_ROLES,
+  PURGE_USERS_MAX_USERS,
+  PURGE_USERS_REQUIRED_PERMISSIONS,
+  USER_METADATA_EXPECTED_MAX_LENGTH,
+  USER_METADATA_MAX_LENGTH
 };
 //# sourceMappingURL=use-cases.const.js.map

package/dist/approvals/use-cases.const.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/approvals/use-cases.const.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 * The names and the value ranges of the registered use cases.\n *\n * control-backend owns the registry, and a frontend reads it at run time\n * (`GET /api/approvals/use-cases`). Two things cannot wait for that answer:\n *\n * - **The identifier**, because a caller must NAME a use case to find it in the\n *   registry, and to open a request of it.\n * - **The range of a payload field**, because a form holds the value before any\n *   call goes out.\n *\n * Both live here, so the schema of the service and the form of the browser can\n * never hold different numbers.\n */\n\n/** The identifier of each use case, on the wire and in the table. */\nexport const APPROVAL_USE_CASE_TYPES = {\n  sendToExpiredTrial: 'send-to-expired-trial',\n  extendTrial: 'extend-trial',\n  moveClusterOrg: 'move-cluster-org',\n  // One use case for each type of a cluster bulk operation. The types need\n  // different permissions and different approval counts, and a use case holds\n  // one of each. See `cluster-bulk-operation.ts` beside this file.\n  clusterBulkGenerationUpdate: 'cluster-bulk-generation-update',\n  clusterBulkPlanUpdate: 'cluster-bulk-plan-update',\n  clusterBulkPlanTypeUpdate: 'cluster-bulk-plan-type-update',\n  clusterBulkSleepWakeup: 'cluster-bulk-sleep-wakeup',\n  clusterBulkDeletion: 'cluster-bulk-deletion',\n  clusterBulkSpecUpdate: 'cluster-bulk-spec-update',\n} as const\n\nexport type ApprovalUseCaseType =\n  (typeof APPROVAL_USE_CASE_TYPES)[keyof typeof APPROVAL_USE_CASE_TYPES]\n\n/**\n * The shortest extension that accounts-backend accepts.\n *\n * `POST /:orgId/extendtrial` refuses a date that is less than 14 days away\n * when the body carries `onBehalfOf`, and it measures those 14 days when the\n * CALL arrives. The floor here is 15 and not 14, for two reasons:\n *\n * - The two clocks are not the same instant. Accounts builds its own \"14 days\n *   from now\" a few milliseconds after control-backend builds the date, so a\n *   date of exactly 14 days is already in the past for the comparison.\n * - Accounts counts with `setDate`, which is calendar arithmetic. A change of\n *   the daylight saving time moves its limit by an hour.\n */\nexport const EXTEND_TRIAL_MIN_DAYS = 15\n\n/**\n * The longest extension that accounts-backend accepts.\n *\n * The same route refuses a date more than 62 days away. 61 keeps the same\n * margin as the floor above.\n */\nexport const EXTEND_TRIAL_MAX_DAYS = 61\n"],
-  "mappings": "AAsBO,MAAM,0BAA0B;AAAA,EACrC,oBAAoB;AAAA,EACpB,aAAa;AAAA,EACb,gBAAgB;AAAA;AAAA;AAAA;AAAA,EAIhB,6BAA6B;AAAA,EAC7B,uBAAuB;AAAA,EACvB,2BAA2B;AAAA,EAC3B,wBAAwB;AAAA,EACxB,qBAAqB;AAAA,EACrB,uBAAuB;AACzB;AAkBO,MAAM,wBAAwB;AAQ9B,MAAM,wBAAwB;",
+  "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 { AccountsPermissions } from '../permissions/accounts.permissions.js'\n\n/**\n * The names and the value ranges of the registered use cases.\n *\n * control-backend owns the registry, and a frontend reads it at run time\n * (`GET /api/approvals/use-cases`). Two things cannot wait for that answer:\n *\n * - **The identifier**, because a caller must NAME a use case to find it in the\n *   registry, and to open a request of it.\n * - **The range of a payload field**, because a form holds the value before any\n *   call goes out.\n *\n * Both live here, so the schema of the service and the form of the browser can\n * never hold different numbers.\n */\n\n/** The identifier of each use case, on the wire and in the table. */\nexport const APPROVAL_USE_CASE_TYPES = {\n  sendToExpiredTrial: 'send-to-expired-trial',\n  extendTrial: 'extend-trial',\n  moveClusterOrg: 'move-cluster-org',\n  // One use case for each type of a cluster bulk operation. The types need\n  // different permissions and different approval counts, and a use case holds\n  // one of each. See `cluster-bulk-operation.ts` beside this file.\n  clusterBulkGenerationUpdate: 'cluster-bulk-generation-update',\n  clusterBulkPlanUpdate: 'cluster-bulk-plan-update',\n  clusterBulkPlanTypeUpdate: 'cluster-bulk-plan-type-update',\n  clusterBulkSleepWakeup: 'cluster-bulk-sleep-wakeup',\n  clusterBulkDeletion: 'cluster-bulk-deletion',\n  clusterBulkSpecUpdate: 'cluster-bulk-spec-update',\n  // The second group, behind `control.approvalAdminActions`.\n  changePlatformRoles: 'change-platform-roles',\n  deleteInternalBackup: 'delete-internal-backup',\n  changeOrgLimits: 'change-org-limits',\n  deleteSsoConnection: 'delete-sso-connection',\n  changeSalesPlan: 'change-sales-plan',\n  // The third group, behind `control.approvalAccountActions`.\n  deleteOrganization: 'delete-organization',\n  deleteUser: 'delete-user',\n  changeUserEmail: 'change-user-email',\n  purgeUsers: 'purge-users',\n  updateUserMetadata: 'update-user-metadata',\n  // A change of the feature flag table, on a stage where\n  // `isFeatureFlagApprovalRequired` is true.\n  changeFeatureFlag: 'change-feature-flag',\n} as const\n\n/**\n * The approvals that a change of the feature flag table needs on prod.\n *\n * A flag there turns a feature on or off for every customer, and a person who\n * holds `aafw` could do it alone. Two other Camundis stand in every change,\n * the same floor as a cluster bulk operation on prod\n * (`CLUSTER_BULK_OPERATION_MIN_ACKS`). Int needs one.\n */\nexport const FEATURE_FLAG_MIN_ACKS_PROD = 2\n\nexport type ApprovalUseCaseType =\n  (typeof APPROVAL_USE_CASE_TYPES)[keyof typeof APPROVAL_USE_CASE_TYPES]\n\n/**\n * The shortest extension that accounts-backend accepts.\n *\n * `POST /:orgId/extendtrial` refuses a date that is less than 14 days away\n * when the body carries `onBehalfOf`, and it measures those 14 days when the\n * CALL arrives. The floor here is 15 and not 14, for two reasons:\n *\n * - The two clocks are not the same instant. Accounts builds its own \"14 days\n *   from now\" a few milliseconds after control-backend builds the date, so a\n *   date of exactly 14 days is already in the past for the comparison.\n * - Accounts counts with `setDate`, which is calendar arithmetic. A change of\n *   the daylight saving time moves its limit by an hour.\n */\nexport const EXTEND_TRIAL_MIN_DAYS = 15\n\n/**\n * The longest extension that accounts-backend accepts.\n *\n * The same route refuses a date more than 62 days away. 61 keeps the same\n * margin as the floor above.\n */\nexport const EXTEND_TRIAL_MAX_DAYS = 61\n\n/**\n * The most roles that one change-platform-roles request adds, or removes.\n *\n * The form of control-frontend offers every platform role, and a person who\n * gives a Camundi a new position rarely changes more than a few. A request with\n * more roles than this is a request that nobody reads before they approve it.\n */\nexport const PLATFORM_ROLE_CHANGE_MAX_ROLES = 10\n\n/**\n * The longest text value that one change-org-limits request writes.\n *\n * A text limit holds a short value, such as a list of regions. The bound keeps\n * a request readable for the person who approves it.\n */\nexport const ORG_LIMIT_TEXT_MAX_LENGTH = 2000\n\n/**\n * The most users that one purge-users request deletes.\n *\n * The God Mode purge deletes one user after the other, and Auth0 limits how\n * fast that goes. A list longer than this is also a list that no approver\n * reads before they agree.\n */\nexport const PURGE_USERS_MAX_USERS = 1000\n\n/**\n * What a person must hold to open or to approve a purge-users request.\n *\n * The purge of God Mode is behind `GOD_PURGE_USERS`, and each deletion calls a\n * route behind `DELETE_USER`. The use case of control-backend returns this\n * list from `permissionsFor`, and the form passes it to `canCreate`, so the\n * button and the server never disagree.\n */\nexport const PURGE_USERS_REQUIRED_PERMISSIONS: readonly string[] = [\n  AccountsPermissions.GOD_PURGE_USERS,\n  AccountsPermissions.DELETE_USER,\n]\n\n/**\n * The largest metadata object that one update-user-metadata request writes,\n * in characters of its JSON text.\n *\n * This is a bound of the product, and not the limit of Auth0, which is far\n * larger. The approvers read the whole object before they agree, and an\n * object that is longer than this is an object that nobody reads.\n */\nexport const USER_METADATA_MAX_LENGTH = 16_000\n\n/**\n * The largest metadata object that a request carries as the object that the\n * person who asked READ.\n *\n * It is larger than `USER_METADATA_MAX_LENGTH`, so a user whose metadata grew\n * past that bound can still get an edit that makes it smaller. It still has a\n * bound, because the request keeps the copy in its row.\n */\nexport const USER_METADATA_EXPECTED_MAX_LENGTH = 500_000\n\n/** The longest email address that a change-user-email request carries. */\nexport const APPROVAL_EMAIL_MAX_LENGTH = 320\n\n/**\n * The email addresses that a change-user-email request accepts.\n *\n * It is the email pattern of zod 4.6. The pattern is here, so the schema of\n * control-backend and the form of control-frontend accept the same addresses,\n * and a form never sends an address that the service refuses.\n */\nexport const APPROVAL_EMAIL_PATTERN =\n  // biome-ignore lint/complexity/noUselessEscapeInRegex: the same source as zod, character for character\n  /^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$/\n"],
+  "mappings": "AAMA,SAAS,2BAA2B;AAkB7B,MAAM,0BAA0B;AAAA,EACrC,oBAAoB;AAAA,EACpB,aAAa;AAAA,EACb,gBAAgB;AAAA;AAAA;AAAA;AAAA,EAIhB,6BAA6B;AAAA,EAC7B,uBAAuB;AAAA,EACvB,2BAA2B;AAAA,EAC3B,wBAAwB;AAAA,EACxB,qBAAqB;AAAA,EACrB,uBAAuB;AAAA;AAAA,EAEvB,qBAAqB;AAAA,EACrB,sBAAsB;AAAA,EACtB,iBAAiB;AAAA,EACjB,qBAAqB;AAAA,EACrB,iBAAiB;AAAA;AAAA,EAEjB,oBAAoB;AAAA,EACpB,YAAY;AAAA,EACZ,iBAAiB;AAAA,EACjB,YAAY;AAAA,EACZ,oBAAoB;AAAA;AAAA;AAAA,EAGpB,mBAAmB;AACrB;AAUO,MAAM,6BAA6B;AAkBnC,MAAM,wBAAwB;AAQ9B,MAAM,wBAAwB;AAS9B,MAAM,iCAAiC;AAQvC,MAAM,4BAA4B;AASlC,MAAM,wBAAwB;AAU9B,MAAM,mCAAsD;AAAA,EACjE,oBAAoB;AAAA,EACpB,oBAAoB;AACtB;AAUO,MAAM,2BAA2B;AAUjC,MAAM,oCAAoC;AAG1C,MAAM,4BAA4B;AASlC,MAAM;AAAA;AAAA,EAEX;AAAA;",
   "names": []
 }

package/dist/charts/chart-metrics.d.ts

@@ -0,0 +1,35 @@
+import type { SearchFieldSpec } from '../search/fields.js';
+import type { ChartGrain, ChartUnit } from './chart-spec.js';
+export interface ChartDimensionSpec {
+    /** As typed after `by`. */
+    id: string;
+    label: string;
+    description: string;
+}
+export interface ChartMetricSpec {
+    /** As typed at the start of a query. */
+    id: string;
+    label: string;
+    description: string;
+    unit: ChartUnit;
+    dimensions: readonly ChartDimensionSpec[];
+    /** The fields that `where` can use. */
+    filters: readonly SearchFieldSpec[];
+    grains: readonly ChartGrain[];
+    /** The longest window, in days. */
+    maxWindowDays: number;
+    /**
+     * How one number comes from a chart, for the `stat` render: first over the
+     * series of a bucket, then over the buckets of the window. A counter sums
+     * both. A gauge must not: a sum of daily load percentages means nothing.
+     */
+    stat: {
+        series: 'sum' | 'mean';
+        window: 'sum' | 'max' | 'mean';
+    };
+}
+export declare const CHART_METRICS: readonly ChartMetricSpec[];
+/** Case-insensitive. */
+export declare const findChartMetric: (id: string, metrics?: readonly ChartMetricSpec[]) => ChartMetricSpec | undefined;
+/** Case-insensitive. */
+export declare const findChartDimension: (metric: ChartMetricSpec, id: string) => ChartDimensionSpec | undefined;

package/dist/charts/chart-metrics.js

@@ -0,0 +1,188 @@
+const CLUSTER_DIMENSION = {
+  id: "cluster",
+  label: "Cluster",
+  description: "The cluster id."
+};
+const ORG_DIMENSION = {
+  id: "org",
+  label: "Organization",
+  description: "The organization id."
+};
+const ORG_NAME_DIMENSION = {
+  id: "orgName",
+  label: "Organization name",
+  description: "The name of the organization of the cluster. Prod clusters only: on other stages it is (unknown)."
+};
+const ORG_ID_FILTER = {
+  field: "orgId",
+  label: "Organization id",
+  description: "Exact organization id.",
+  type: "string",
+  capabilities: ["match"],
+  example: "orgId:3f2c\u2026"
+};
+const CLUSTER_ID_FILTER = {
+  field: "clusterId",
+  label: "Cluster id",
+  description: "Exact cluster id.",
+  type: "string",
+  capabilities: ["match"],
+  example: "clusterId:9a1b\u2026"
+};
+const VALUE_METRIC_DIMENSIONS = [
+  CLUSTER_DIMENSION,
+  ORG_DIMENSION,
+  ORG_NAME_DIMENSION,
+  {
+    id: "salesPlan",
+    label: "Sales plan",
+    description: "The sales plan of the organization on that day."
+  },
+  {
+    id: "env",
+    label: "Environment",
+    description: "Production or development cluster."
+  }
+];
+const VALUE_METRIC_FILTERS = [
+  ORG_ID_FILTER,
+  CLUSTER_ID_FILTER,
+  {
+    field: "salesPlan",
+    label: "Sales plan",
+    description: "Sales plan name, case-insensitive. Use * as a wildcard.",
+    type: "string",
+    capabilities: ["match"],
+    example: "salesPlan:enterprise*"
+  },
+  {
+    field: "env",
+    label: "Environment",
+    description: "Production or development cluster.",
+    type: "enum",
+    capabilities: ["match"],
+    enumValues: ["production", "development"],
+    example: "env:production"
+  }
+];
+const ALL_GRAINS = ["day", "week", "month"];
+const VALUE_METRIC_GRAINS = ALL_GRAINS;
+const LARGE_TABLE_MAX_WINDOW_DAYS = 400;
+const gaugeMetric = (id, label, unit, stat, description) => ({
+  id,
+  label,
+  description,
+  unit,
+  dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],
+  filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],
+  grains: ALL_GRAINS,
+  maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,
+  stat
+});
+const VALUE_METRIC_MAX_WINDOW_DAYS = 762;
+const valueMetric = (id, label, description) => ({
+  id,
+  label,
+  description,
+  unit: "count",
+  dimensions: VALUE_METRIC_DIMENSIONS,
+  filters: VALUE_METRIC_FILTERS,
+  grains: VALUE_METRIC_GRAINS,
+  maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,
+  stat: { series: "sum", window: "sum" }
+});
+const CHART_METRICS = [
+  valueMetric(
+    "processInstances",
+    "Process instances",
+    "Process instances that started, from the HDP value metrics. The sum over each bucket."
+  ),
+  valueMetric(
+    "decisionInstances",
+    "Decision instances",
+    "Decision instances that ran, from the HDP value metrics. The sum over each bucket."
+  ),
+  valueMetric(
+    "taskUsers",
+    "Task users",
+    "Task users, from the HDP value metrics. The sum of the daily values over each bucket, as on the Value metrics tab."
+  ),
+  gaugeMetric(
+    "activeTenants",
+    "Active tenants",
+    "count",
+    { series: "sum", window: "max" },
+    "Active tenants: the peak of each cluster on a day, summed over the clusters. A week or a month shows its highest day. The table holds every stage."
+  ),
+  gaugeMetric(
+    "clusterLoad",
+    "Cluster load",
+    "percent",
+    { series: "mean", window: "mean" },
+    "The load of a cluster, in percent: the mean of a day, then the mean over the clusters and the days of a bucket. The table holds every stage."
+  ),
+  gaugeMetric(
+    "diskUsedBytes",
+    "Elasticsearch disk used",
+    "bytes",
+    { series: "sum", window: "max" },
+    "The used Elasticsearch disk: the peak of each cluster on a day, summed over the clusters. A week or a month shows its highest day. The table holds every stage."
+  ),
+  {
+    id: "hostingCost",
+    label: "Hosting cost",
+    description: "The loaded hosting cost of the clusters, in US dollars, from the cloud bill. The sum over each bucket. The bill holds every stage.",
+    unit: "usd",
+    dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],
+    filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],
+    grains: ALL_GRAINS,
+    maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,
+    stat: { series: "sum", window: "sum" }
+  },
+  {
+    id: "changeEvents",
+    label: "Change events",
+    description: "The change events that the backends of this stage sent to HDP: one for each insert, update or delete of an entity. The count over each bucket.",
+    unit: "count",
+    dimensions: [
+      { id: "entity", label: "Entity", description: "For example cluster." },
+      {
+        id: "operation",
+        label: "Operation",
+        description: "insert, update or delete."
+      }
+    ],
+    filters: [
+      {
+        field: "entity",
+        label: "Entity",
+        description: "The entity, case-insensitive. Use * as a wildcard.",
+        type: "string",
+        capabilities: ["match"],
+        example: "entity:cluster"
+      },
+      {
+        field: "operation",
+        label: "Operation",
+        description: "The operation.",
+        type: "enum",
+        capabilities: ["match"],
+        enumValues: ["insert", "update", "delete"],
+        example: "operation:delete"
+      }
+    ],
+    grains: ALL_GRAINS,
+    maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,
+    stat: { series: "sum", window: "sum" }
+  }
+];
+const findChartMetric = (id, metrics = CHART_METRICS) => metrics.find((metric) => metric.id.toLowerCase() === id.toLowerCase());
+const findChartDimension = (metric, id) => metric.dimensions.find(
+  (dimension) => dimension.id.toLowerCase() === id.toLowerCase()
+);
+export {
+  CHART_METRICS,
+  findChartDimension,
+  findChartMetric
+};
+//# sourceMappingURL=chart-metrics.js.map

package/dist/charts/chart-metrics.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/charts/chart-metrics.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 { SearchFieldSpec } from '../search/fields.js'\nimport type { ChartGrain, ChartUnit } from './chart-spec.js'\n\n// ============================================================================\n// The metric catalogue of the chart tiles, without SQL.\n//\n// The frontend reads it for autocomplete, help and validation as you type.\n// accounts-backend pairs each entry with its SQL (`hdp-data.charts.controller`),\n// and a test there makes sure that the two have the same ids.\n// ============================================================================\n\nexport interface ChartDimensionSpec {\n  /** As typed after `by`. */\n  id: string\n  label: string\n  description: string\n}\n\nexport interface ChartMetricSpec {\n  /** As typed at the start of a query. */\n  id: string\n  label: string\n  description: string\n  unit: ChartUnit\n  dimensions: readonly ChartDimensionSpec[]\n  /** The fields that `where` can use. */\n  filters: readonly SearchFieldSpec[]\n  grains: readonly ChartGrain[]\n  /** The longest window, in days. */\n  maxWindowDays: number\n  /**\n   * How one number comes from a chart, for the `stat` render: first over the\n   * series of a bucket, then over the buckets of the window. A counter sums\n   * both. A gauge must not: a sum of daily load percentages means nothing.\n   */\n  stat: { series: 'sum' | 'mean'; window: 'sum' | 'max' | 'mean' }\n}\n\nconst CLUSTER_DIMENSION: ChartDimensionSpec = {\n  id: 'cluster',\n  label: 'Cluster',\n  description: 'The cluster id.',\n}\n\nconst ORG_DIMENSION: ChartDimensionSpec = {\n  id: 'org',\n  label: 'Organization',\n  description: 'The organization id.',\n}\n\n/**\n * The name of the organization of the cluster. It comes from the clusters\n * table of HDP, which holds the prod clusters only, so on another stage every\n * series is `(unknown)`.\n */\nconst ORG_NAME_DIMENSION: ChartDimensionSpec = {\n  id: 'orgName',\n  label: 'Organization name',\n  description:\n    'The name of the organization of the cluster. Prod clusters only: on other stages it is (unknown).',\n}\n\nconst ORG_ID_FILTER: SearchFieldSpec = {\n  field: 'orgId',\n  label: 'Organization id',\n  description: 'Exact organization id.',\n  type: 'string',\n  capabilities: ['match'],\n  example: 'orgId:3f2c\u2026',\n}\n\nconst CLUSTER_ID_FILTER: SearchFieldSpec = {\n  field: 'clusterId',\n  label: 'Cluster id',\n  description: 'Exact cluster id.',\n  type: 'string',\n  capabilities: ['match'],\n  example: 'clusterId:9a1b\u2026',\n}\n\nconst VALUE_METRIC_DIMENSIONS: readonly ChartDimensionSpec[] = [\n  CLUSTER_DIMENSION,\n  ORG_DIMENSION,\n  ORG_NAME_DIMENSION,\n  {\n    id: 'salesPlan',\n    label: 'Sales plan',\n    description: 'The sales plan of the organization on that day.',\n  },\n  {\n    id: 'env',\n    label: 'Environment',\n    description: 'Production or development cluster.',\n  },\n]\n\nconst VALUE_METRIC_FILTERS: readonly SearchFieldSpec[] = [\n  ORG_ID_FILTER,\n  CLUSTER_ID_FILTER,\n  {\n    field: 'salesPlan',\n    label: 'Sales plan',\n    description: 'Sales plan name, case-insensitive. Use * as a wildcard.',\n    type: 'string',\n    capabilities: ['match'],\n    example: 'salesPlan:enterprise*',\n  },\n  {\n    field: 'env',\n    label: 'Environment',\n    description: 'Production or development cluster.',\n    type: 'enum',\n    capabilities: ['match'],\n    enumValues: ['production', 'development'],\n    example: 'env:production',\n  },\n]\n\nconst ALL_GRAINS: readonly ChartGrain[] = ['day', 'week', 'month']\nconst VALUE_METRIC_GRAINS = ALL_GRAINS\n\n/**\n * About one year, for a metric on a large table: the cluster gauges, which\n * are scraped about once a minute, and the change events of every backend\n * and stage. `over 12m every month` starts on the 1st of a month and reads up\n * to 396 days, so the limit holds that query.\n */\nconst LARGE_TABLE_MAX_WINDOW_DAYS = 400\n\n/** A gauge of the clusters, from the Prometheus metrics in HDP. */\nconst gaugeMetric = (\n  id: string,\n  label: string,\n  unit: ChartMetricSpec['unit'],\n  stat: ChartMetricSpec['stat'],\n  description: string,\n): ChartMetricSpec => ({\n  id,\n  label,\n  description,\n  unit,\n  dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],\n  filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],\n  grains: ALL_GRAINS,\n  maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,\n  stat,\n})\n\n/**\n * About two years. The table holds one row for each cluster, day and metric.\n * `over 24m every month` starts on the 1st of a month and reads up to 761\n * days, so the limit holds that query.\n */\nconst VALUE_METRIC_MAX_WINDOW_DAYS = 762\n\nconst valueMetric = (\n  id: string,\n  label: string,\n  description: string,\n): ChartMetricSpec => ({\n  id,\n  label,\n  description,\n  unit: 'count',\n  dimensions: VALUE_METRIC_DIMENSIONS,\n  filters: VALUE_METRIC_FILTERS,\n  grains: VALUE_METRIC_GRAINS,\n  maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,\n  stat: { series: 'sum', window: 'sum' },\n})\n\nexport const CHART_METRICS: readonly ChartMetricSpec[] = [\n  valueMetric(\n    'processInstances',\n    'Process instances',\n    'Process instances that started, from the HDP value metrics. The sum over each bucket.',\n  ),\n  valueMetric(\n    'decisionInstances',\n    'Decision instances',\n    'Decision instances that ran, from the HDP value metrics. The sum over each bucket.',\n  ),\n  valueMetric(\n    'taskUsers',\n    'Task users',\n    'Task users, from the HDP value metrics. The sum of the daily values over each bucket, as on the Value metrics tab.',\n  ),\n  gaugeMetric(\n    'activeTenants',\n    'Active tenants',\n    'count',\n    { series: 'sum', window: 'max' },\n    'Active tenants: the peak of each cluster on a day, summed over the clusters. A week or a month shows its highest day. The table holds every stage.',\n  ),\n  gaugeMetric(\n    'clusterLoad',\n    'Cluster load',\n    'percent',\n    { series: 'mean', window: 'mean' },\n    'The load of a cluster, in percent: the mean of a day, then the mean over the clusters and the days of a bucket. The table holds every stage.',\n  ),\n  gaugeMetric(\n    'diskUsedBytes',\n    'Elasticsearch disk used',\n    'bytes',\n    { series: 'sum', window: 'max' },\n    'The used Elasticsearch disk: the peak of each cluster on a day, summed over the clusters. A week or a month shows its highest day. The table holds every stage.',\n  ),\n  {\n    id: 'hostingCost',\n    label: 'Hosting cost',\n    description:\n      'The loaded hosting cost of the clusters, in US dollars, from the cloud bill. The sum over each bucket. The bill holds every stage.',\n    unit: 'usd',\n    dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],\n    filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],\n    grains: ALL_GRAINS,\n    maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,\n    stat: { series: 'sum', window: 'sum' },\n  },\n  {\n    id: 'changeEvents',\n    label: 'Change events',\n    description:\n      'The change events that the backends of this stage sent to HDP: one for each insert, update or delete of an entity. The count over each bucket.',\n    unit: 'count',\n    dimensions: [\n      { id: 'entity', label: 'Entity', description: 'For example cluster.' },\n      {\n        id: 'operation',\n        label: 'Operation',\n        description: 'insert, update or delete.',\n      },\n    ],\n    filters: [\n      {\n        field: 'entity',\n        label: 'Entity',\n        description: 'The entity, case-insensitive. Use * as a wildcard.',\n        type: 'string',\n        capabilities: ['match'],\n        example: 'entity:cluster',\n      },\n      {\n        field: 'operation',\n        label: 'Operation',\n        description: 'The operation.',\n        type: 'enum',\n        capabilities: ['match'],\n        enumValues: ['insert', 'update', 'delete'],\n        example: 'operation:delete',\n      },\n    ],\n    grains: ALL_GRAINS,\n    maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,\n    stat: { series: 'sum', window: 'sum' },\n  },\n]\n\n/** Case-insensitive. */\nexport const findChartMetric = (\n  id: string,\n  metrics: readonly ChartMetricSpec[] = CHART_METRICS,\n): ChartMetricSpec | undefined =>\n  metrics.find((metric) => metric.id.toLowerCase() === id.toLowerCase())\n\n/** Case-insensitive. */\nexport const findChartDimension = (\n  metric: ChartMetricSpec,\n  id: string,\n): ChartDimensionSpec | undefined =>\n  metric.dimensions.find(\n    (dimension) => dimension.id.toLowerCase() === id.toLowerCase(),\n  )\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/charts/chart-query.d.ts

@@ -0,0 +1,55 @@
+import { type ChartMetricSpec } from './chart-metrics.js';
+import { type ChartSpec } from './chart-spec.js';
+export type ChartQueryErrorKind = 'syntax' | 'unknown-metric' | 'unknown-dimension' | 'unknown-field' | 'bad-value';
+export declare class ChartQueryError extends Error {
+    readonly kind: ChartQueryErrorKind;
+    /** A name to use instead, for "did you mean". */
+    readonly suggestion?: string;
+    constructor(message: string, kind: ChartQueryErrorKind, suggestion?: string);
+}
+/** Type guard that works across package boundaries. */
+export declare const isChartQueryError: (error: unknown) => error is ChartQueryError;
+/**
+ * The answer of `POST /api/dashboards/chart-queries/check`: the canonical spec
+ * of a valid query, or what is wrong with a query and how to fix it. A wrong
+ * query is an answer and not a failure, so a client reads `valid`.
+ */
+export type ChartQueryCheck = {
+    valid: true;
+    spec: ChartSpec;
+    query: string;
+} | {
+    valid: false;
+    error: {
+        kind: ChartQueryErrorKind;
+        message: string;
+        suggestion?: string;
+    };
+};
+export interface ChartQueryOptions {
+    metrics?: readonly ChartMetricSpec[];
+    /** `YYYY-MM-DD`. The default is today in UTC. */
+    today?: string;
+}
+/**
+ * Parse and validate a chart query. Gives the canonical {@link ChartSpec}:
+ * the ids in the spelling of the catalogue, and the defaults filled in.
+ * Throws {@link ChartQueryError}.
+ */
+export declare const parseChartQuery: (text: string, options?: ChartQueryOptions) => ChartSpec;
+/**
+ * Check a spec against the catalogue and give it in canonical form. The chart
+ * route runs this on every request body, so a spec that a tile stored long ago
+ * gets the rules of today. Throws {@link ChartQueryError}.
+ */
+export declare const validateChartSpec: (spec: ChartSpec, options?: ChartQueryOptions) => ChartSpec;
+/**
+ * The text of a spec, in one canonical form. Parsing it again gives the same
+ * spec, so the text field and the builder can never disagree.
+ */
+export declare const formatChartSpec: (spec: ChartSpec) => string;
+/**
+ * Read a spec from JSON, for example a request body or a stored tile. Checks
+ * the shape only. Run {@link validateChartSpec} after it.
+ */
+export declare const readChartSpec: (value: unknown) => ChartSpec;