@camunda/ccma-shared-types 3.0.0 → 4.0.0

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

@@ -0,0 +1,240 @@
+/**
+ * The wire types of the annotations of the fleet: the notes and the tags that a
+ * Camundi attaches to an entity.
+ *
+ * An annotation adds CONTEXT that the fleet itself does not hold. A cluster row
+ * says how much memory it has; it does not say "this is the playground of the
+ * demo team". A Camundi writes that here, and the next Camundi reads it.
+ *
+ * This file holds no logic and no dependency, because control-backend and
+ * control-frontend both read it. The rules that read these types are in
+ * `../annotations/policy.js`, and they are pure for the same reason.
+ *
+ * The feature is INTERNAL. No annotation reaches a customer, and no route of
+ * another service reads one.
+ */
+/**
+ * Every kind of fleet entity that can carry an annotation.
+ *
+ * A `const` tuple, not an enum, so it is both the union type and the list that
+ * validates a request at run time.
+ *
+ * The kind is a STRING on the row and not a foreign key, because the entity is
+ * in a different database: a cluster belongs to console-backend and an
+ * organization to accounts-backend. That is also what keeps an annotation after
+ * the entity goes away. See `AnnotationDto.entityLabel`.
+ *
+ * Add a kind here and in `ANNOTATION_ENTITY_KIND_LABELS` below. The two lists
+ * are one `Record`, so a kind with no label does not compile.
+ *
+ * Every kind here is a THING of the fleet, and none of them is a person. That
+ * is a rule and not an accident. A `user` kind was in this list and came out
+ * again: an annotation outlives its entity on purpose, which is right for a
+ * cluster that somebody deleted and wrong for a colleague who left, and this
+ * feature has no retention rule, no reaper, and no way for the person written
+ * about to read or correct it. Add a kind that names a PERSON only with those
+ * three answered.
+ */
+export declare const ANNOTATION_ENTITY_KINDS: readonly ["cluster", "organization", "cluster-plan", "cluster-plan-type", "generation", "channel", "sales-plan", "k8s-context"];
+export type AnnotationEntityKind = (typeof ANNOTATION_ENTITY_KINDS)[number];
+/**
+ * What a reader sees for each kind, in the singular.
+ *
+ * The label is here and not in the frontend, because the search page shows
+ * results of every kind together and the backend writes the same word into a
+ * log line. Two spellings of one kind would read as two kinds.
+ */
+export declare const ANNOTATION_ENTITY_KIND_LABELS: Record<AnnotationEntityKind, string>;
+/**
+ * What an annotation IS: a written note, or a tag out of the dictionary.
+ *
+ * One row type carries both, because both answer the same question — what does
+ * a Camundi need to know about this entity? — and both are read, listed and
+ * removed the same way. The difference is what the row points at: a note holds
+ * `body`, and a tag holds `tag`.
+ */
+export declare const ANNOTATION_KINDS: readonly ["note", "tag"];
+export type AnnotationKind = (typeof ANNOTATION_KINDS)[number];
+/** Who wrote an annotation. The same shape as `ApprovalActor`. */
+export interface AnnotationActor {
+    userId: string;
+    email: string;
+}
+/**
+ * One tag of the dictionary.
+ *
+ * A tag is its own row, and not a string on the annotation, for one reason:
+ * a Camundi must be able to ask "what else carries `partner`?". A string on
+ * each row answers that only with a scan, and it drifts: `Partner`, `partner `
+ * and `partner` would be three tags that read as one.
+ */
+export interface AnnotationTagDto {
+    id: string;
+    /** What a reader sees. The first spelling that anybody wrote wins. */
+    name: string;
+    /** `name` through `normalizeTagName`. It is the identity of the tag. */
+    normalizedName: string;
+    createdBy: AnnotationActor;
+    createdAt: string;
+    /**
+     * How many LIVE entities carry this tag.
+     *
+     * It is counted at read time and never stored, so a removed assignment
+     * lowers it with no second write. A list of the dictionary needs it to sort
+     * by use, which is how a Camundi finds the tag that the team already uses
+     * instead of inventing a second spelling of it.
+     */
+    usageCount: number;
+}
+/**
+ * One note, or one tag, on one entity.
+ *
+ * `entityKind` and `entityId` together name the entity. Neither is checked
+ * against the fleet: the entity lives in another service, and an annotation
+ * must survive its entity. See `entityLabel`.
+ */
+export interface AnnotationDto {
+    id: string;
+    kind: AnnotationKind;
+    entityKind: AnnotationEntityKind;
+    entityId: string;
+    /**
+     * What the entity was CALLED when somebody wrote the annotation.
+     *
+     * This is the only reason a search result stays readable after the entity is
+     * deleted: the id of a cluster that no longer exists says nothing, and the
+     * fleet can no longer answer what its name was. The label is a copy on
+     * purpose, so it can be stale — it says what the entity was called then, not
+     * what it is called now.
+     */
+    entityLabel?: string;
+    /** The text of a note. Absent on a tag. */
+    body?: string;
+    /** The tag of a tag annotation. Absent on a note. */
+    tag?: AnnotationTagDto;
+    createdBy: AnnotationActor;
+    createdAt: string;
+    updatedAt: string;
+    /** True when `body` was changed after it was written. */
+    edited: boolean;
+    /**
+     * How many times this row was written. A new one carries 1.
+     *
+     * An edit sends the version that it read, and the route refuses the write
+     * when the row moved on since. Without it the tab that somebody left open at
+     * breakfast silently replaces the edit they made at lunch, and neither write
+     * tells them that one of the two is gone.
+     */
+    version: number;
+}
+/** The annotations of one entity, in one answer. */
+export interface EntityAnnotationsDto {
+    entityKind: AnnotationEntityKind;
+    entityId: string;
+    notes: AnnotationDto[];
+    tags: AnnotationDto[];
+    /**
+     * True when the entity carries more than `ANNOTATION_ENTITY_MAX` rows, so
+     * the two lists above are the newest of them and not all of them.
+     *
+     * A panel that showed no sign of this would be a page that quietly stops
+     * being the whole story, which is worse for documentation than a page that
+     * says where the rest is.
+     */
+    hasMore: boolean;
+}
+/**
+ * What one entity carries, in the answer of a lookup over many entities.
+ *
+ * A table of 3000 clusters cannot read 3000 panels. The lookup answers the
+ * two questions that a row of such a table needs: which tags, and whether a
+ * colleague wrote something that a person must read before they act.
+ */
+export interface AnnotationLookupEntryDto {
+    entityId: string;
+    /**
+     * The live tag annotations of the entity, oldest first, and at most
+     * `ANNOTATION_LOOKUP_TAGS_MAX` of them.
+     */
+    tags: AnnotationDto[];
+    /** How many live tags the entity carries. More than `tags` holds is cut. */
+    tagCount: number;
+    /** How many live notes the entity carries. */
+    noteCount: number;
+    /** The newest live note, so a row can show it with no second read. */
+    latestNote?: AnnotationDto;
+}
+/**
+ * The answer of a lookup. It holds ONLY the entities that carry something,
+ * so an entity with no entry carries nothing.
+ */
+export interface AnnotationLookupDto {
+    entityKind: AnnotationEntityKind;
+    entries: AnnotationLookupEntryDto[];
+}
+/**
+ * The most entities that one lookup names.
+ *
+ * The same number as the largest cluster bulk operation, which is the table
+ * that asks the largest question.
+ */
+export declare const ANNOTATION_LOOKUP_MAX_ENTITIES = 3000;
+/**
+ * The most tags that a lookup answers for ONE entity.
+ *
+ * An entity can carry any number of tags. Without this cap, one lookup of
+ * 3000 entities has no bound on its rows. A row of a table shows a few chips,
+ * and `tagCount` tells it how many it did not get.
+ */
+export declare const ANNOTATION_LOOKUP_TAGS_MAX = 20;
+/**
+ * The most annotations that the read of ONE entity answers with.
+ *
+ * The read has no page of its own: a panel is a thread that a person scrolls,
+ * not a table they walk. But it cannot be unbounded either — an entity that
+ * collects notes for a year would make every load of that page serialize
+ * thousands of rows of up to `ANNOTATION_BODY_MAX` characters each. So the
+ * answer is the NEWEST rows up to this number, with `hasMore` to say that
+ * older ones exist. The search page reads the rest.
+ */
+export declare const ANNOTATION_ENTITY_MAX = 200;
+/**
+ * The longest note that a route accepts.
+ *
+ * A note is context for a colleague and not a document. The ceiling keeps one
+ * paste of a log file out of every read of the entity page, and a person who
+ * needs more has a handbook page to link to.
+ */
+export declare const ANNOTATION_BODY_MAX = 4000;
+/** The longest tag name. A tag is a label, so it is short by design. */
+export declare const ANNOTATION_TAG_NAME_MAX = 60;
+/**
+ * The longest free text that the search accepts.
+ *
+ * The VIEW needs it as much as the route: a field with no ceiling lets a
+ * person paste more than the route takes, and the answer is then a 400 that
+ * reads like a broken search. The field holds them here instead, and a deep
+ * link that carries more is cut to this length rather than breaking the page.
+ */
+export declare const ANNOTATION_SEARCH_MAX_LENGTH = 200;
+/** Annotations for each page when the caller asks for no number. */
+export declare const ANNOTATION_PAGE_SIZE_DEFAULT = 100;
+/**
+ * The most annotations that one page can hold.
+ *
+ * The view needs this number too: a page that asked for more rows than the
+ * service allows would get a 400 instead of rows.
+ */
+export declare const ANNOTATION_PAGE_SIZE_MAX = 500;
+/**
+ * The identity of a tag, from what a person typed.
+ *
+ * The case and the outer spaces go, and every run of inner whitespace becomes
+ * one hyphen. `Partner`, ` partner ` and `Partner ` are then one tag, and
+ * `key account` is `key-account`.
+ *
+ * Both sides run this: the backend writes the result into `normalizedName` and
+ * holds it unique, and the frontend runs it to tell a person, before they
+ * press the button, that the tag they are typing already exists.
+ */
+export declare function normalizeTagName(name: string): string;

package/dist/dtos/Annotation.dto.js

@@ -0,0 +1,47 @@
+const ANNOTATION_ENTITY_KINDS = [
+  "cluster",
+  "organization",
+  "cluster-plan",
+  "cluster-plan-type",
+  "generation",
+  "channel",
+  "sales-plan",
+  "k8s-context"
+];
+const ANNOTATION_ENTITY_KIND_LABELS = {
+  cluster: "Cluster",
+  organization: "Organization",
+  "cluster-plan": "Cluster plan",
+  "cluster-plan-type": "Cluster plan type",
+  generation: "Generation",
+  channel: "Channel",
+  "sales-plan": "Sales plan",
+  "k8s-context": "Kubernetes context"
+};
+const ANNOTATION_KINDS = ["note", "tag"];
+const ANNOTATION_LOOKUP_MAX_ENTITIES = 3e3;
+const ANNOTATION_LOOKUP_TAGS_MAX = 20;
+const ANNOTATION_ENTITY_MAX = 200;
+const ANNOTATION_BODY_MAX = 4e3;
+const ANNOTATION_TAG_NAME_MAX = 60;
+const ANNOTATION_SEARCH_MAX_LENGTH = 200;
+const ANNOTATION_PAGE_SIZE_DEFAULT = 100;
+const ANNOTATION_PAGE_SIZE_MAX = 500;
+function normalizeTagName(name) {
+  return name.trim().toLowerCase().replace(/\s+/g, "-");
+}
+export {
+  ANNOTATION_BODY_MAX,
+  ANNOTATION_ENTITY_KINDS,
+  ANNOTATION_ENTITY_KIND_LABELS,
+  ANNOTATION_ENTITY_MAX,
+  ANNOTATION_KINDS,
+  ANNOTATION_LOOKUP_MAX_ENTITIES,
+  ANNOTATION_LOOKUP_TAGS_MAX,
+  ANNOTATION_PAGE_SIZE_DEFAULT,
+  ANNOTATION_PAGE_SIZE_MAX,
+  ANNOTATION_SEARCH_MAX_LENGTH,
+  ANNOTATION_TAG_NAME_MAX,
+  normalizeTagName
+};
+//# sourceMappingURL=Annotation.dto.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/dtos/Annotation.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 * The wire types of the annotations of the fleet: the notes and the tags that a\n * Camundi attaches to an entity.\n *\n * An annotation adds CONTEXT that the fleet itself does not hold. A cluster row\n * says how much memory it has; it does not say \"this is the playground of the\n * demo team\". A Camundi writes that here, and the next Camundi reads it.\n *\n * This file holds no logic and no dependency, because control-backend and\n * control-frontend both read it. The rules that read these types are in\n * `../annotations/policy.js`, and they are pure for the same reason.\n *\n * The feature is INTERNAL. No annotation reaches a customer, and no route of\n * another service reads one.\n */\n\n/**\n * Every kind of fleet entity that can carry an annotation.\n *\n * A `const` tuple, not an enum, so it is both the union type and the list that\n * validates a request at run time.\n *\n * The kind is a STRING on the row and not a foreign key, because the entity is\n * in a different database: a cluster belongs to console-backend and an\n * organization to accounts-backend. That is also what keeps an annotation after\n * the entity goes away. See `AnnotationDto.entityLabel`.\n *\n * Add a kind here and in `ANNOTATION_ENTITY_KIND_LABELS` below. The two lists\n * are one `Record`, so a kind with no label does not compile.\n *\n * Every kind here is a THING of the fleet, and none of them is a person. That\n * is a rule and not an accident. A `user` kind was in this list and came out\n * again: an annotation outlives its entity on purpose, which is right for a\n * cluster that somebody deleted and wrong for a colleague who left, and this\n * feature has no retention rule, no reaper, and no way for the person written\n * about to read or correct it. Add a kind that names a PERSON only with those\n * three answered.\n */\nexport const ANNOTATION_ENTITY_KINDS = [\n  'cluster',\n  'organization',\n  'cluster-plan',\n  'cluster-plan-type',\n  'generation',\n  'channel',\n  'sales-plan',\n  'k8s-context',\n] as const\n\nexport type AnnotationEntityKind = (typeof ANNOTATION_ENTITY_KINDS)[number]\n\n/**\n * What a reader sees for each kind, in the singular.\n *\n * The label is here and not in the frontend, because the search page shows\n * results of every kind together and the backend writes the same word into a\n * log line. Two spellings of one kind would read as two kinds.\n */\nexport const ANNOTATION_ENTITY_KIND_LABELS: Record<\n  AnnotationEntityKind,\n  string\n> = {\n  cluster: 'Cluster',\n  organization: 'Organization',\n  'cluster-plan': 'Cluster plan',\n  'cluster-plan-type': 'Cluster plan type',\n  generation: 'Generation',\n  channel: 'Channel',\n  'sales-plan': 'Sales plan',\n  'k8s-context': 'Kubernetes context',\n}\n\n/**\n * What an annotation IS: a written note, or a tag out of the dictionary.\n *\n * One row type carries both, because both answer the same question \u2014 what does\n * a Camundi need to know about this entity? \u2014 and both are read, listed and\n * removed the same way. The difference is what the row points at: a note holds\n * `body`, and a tag holds `tag`.\n */\nexport const ANNOTATION_KINDS = ['note', 'tag'] as const\n\nexport type AnnotationKind = (typeof ANNOTATION_KINDS)[number]\n\n/** Who wrote an annotation. The same shape as `ApprovalActor`. */\nexport interface AnnotationActor {\n  userId: string\n  email: string\n}\n\n/**\n * One tag of the dictionary.\n *\n * A tag is its own row, and not a string on the annotation, for one reason:\n * a Camundi must be able to ask \"what else carries `partner`?\". A string on\n * each row answers that only with a scan, and it drifts: `Partner`, `partner `\n * and `partner` would be three tags that read as one.\n */\nexport interface AnnotationTagDto {\n  id: string\n  /** What a reader sees. The first spelling that anybody wrote wins. */\n  name: string\n  /** `name` through `normalizeTagName`. It is the identity of the tag. */\n  normalizedName: string\n  createdBy: AnnotationActor\n  createdAt: string\n  /**\n   * How many LIVE entities carry this tag.\n   *\n   * It is counted at read time and never stored, so a removed assignment\n   * lowers it with no second write. A list of the dictionary needs it to sort\n   * by use, which is how a Camundi finds the tag that the team already uses\n   * instead of inventing a second spelling of it.\n   */\n  usageCount: number\n}\n\n/**\n * One note, or one tag, on one entity.\n *\n * `entityKind` and `entityId` together name the entity. Neither is checked\n * against the fleet: the entity lives in another service, and an annotation\n * must survive its entity. See `entityLabel`.\n */\nexport interface AnnotationDto {\n  id: string\n  kind: AnnotationKind\n  entityKind: AnnotationEntityKind\n  entityId: string\n  /**\n   * What the entity was CALLED when somebody wrote the annotation.\n   *\n   * This is the only reason a search result stays readable after the entity is\n   * deleted: the id of a cluster that no longer exists says nothing, and the\n   * fleet can no longer answer what its name was. The label is a copy on\n   * purpose, so it can be stale \u2014 it says what the entity was called then, not\n   * what it is called now.\n   */\n  entityLabel?: string\n  /** The text of a note. Absent on a tag. */\n  body?: string\n  /** The tag of a tag annotation. Absent on a note. */\n  tag?: AnnotationTagDto\n  createdBy: AnnotationActor\n  createdAt: string\n  updatedAt: string\n  /** True when `body` was changed after it was written. */\n  edited: boolean\n  /**\n   * How many times this row was written. A new one carries 1.\n   *\n   * An edit sends the version that it read, and the route refuses the write\n   * when the row moved on since. Without it the tab that somebody left open at\n   * breakfast silently replaces the edit they made at lunch, and neither write\n   * tells them that one of the two is gone.\n   */\n  version: number\n}\n\n/** The annotations of one entity, in one answer. */\nexport interface EntityAnnotationsDto {\n  entityKind: AnnotationEntityKind\n  entityId: string\n  notes: AnnotationDto[]\n  tags: AnnotationDto[]\n  /**\n   * True when the entity carries more than `ANNOTATION_ENTITY_MAX` rows, so\n   * the two lists above are the newest of them and not all of them.\n   *\n   * A panel that showed no sign of this would be a page that quietly stops\n   * being the whole story, which is worse for documentation than a page that\n   * says where the rest is.\n   */\n  hasMore: boolean\n}\n\n/**\n * What one entity carries, in the answer of a lookup over many entities.\n *\n * A table of 3000 clusters cannot read 3000 panels. The lookup answers the\n * two questions that a row of such a table needs: which tags, and whether a\n * colleague wrote something that a person must read before they act.\n */\nexport interface AnnotationLookupEntryDto {\n  entityId: string\n  /**\n   * The live tag annotations of the entity, oldest first, and at most\n   * `ANNOTATION_LOOKUP_TAGS_MAX` of them.\n   */\n  tags: AnnotationDto[]\n  /** How many live tags the entity carries. More than `tags` holds is cut. */\n  tagCount: number\n  /** How many live notes the entity carries. */\n  noteCount: number\n  /** The newest live note, so a row can show it with no second read. */\n  latestNote?: AnnotationDto\n}\n\n/**\n * The answer of a lookup. It holds ONLY the entities that carry something,\n * so an entity with no entry carries nothing.\n */\nexport interface AnnotationLookupDto {\n  entityKind: AnnotationEntityKind\n  entries: AnnotationLookupEntryDto[]\n}\n\n/**\n * The most entities that one lookup names.\n *\n * The same number as the largest cluster bulk operation, which is the table\n * that asks the largest question.\n */\nexport const ANNOTATION_LOOKUP_MAX_ENTITIES = 3000\n\n/**\n * The most tags that a lookup answers for ONE entity.\n *\n * An entity can carry any number of tags. Without this cap, one lookup of\n * 3000 entities has no bound on its rows. A row of a table shows a few chips,\n * and `tagCount` tells it how many it did not get.\n */\nexport const ANNOTATION_LOOKUP_TAGS_MAX = 20\n\n/**\n * The most annotations that the read of ONE entity answers with.\n *\n * The read has no page of its own: a panel is a thread that a person scrolls,\n * not a table they walk. But it cannot be unbounded either \u2014 an entity that\n * collects notes for a year would make every load of that page serialize\n * thousands of rows of up to `ANNOTATION_BODY_MAX` characters each. So the\n * answer is the NEWEST rows up to this number, with `hasMore` to say that\n * older ones exist. The search page reads the rest.\n */\nexport const ANNOTATION_ENTITY_MAX = 200\n\n/**\n * The longest note that a route accepts.\n *\n * A note is context for a colleague and not a document. The ceiling keeps one\n * paste of a log file out of every read of the entity page, and a person who\n * needs more has a handbook page to link to.\n */\nexport const ANNOTATION_BODY_MAX = 4000\n\n/** The longest tag name. A tag is a label, so it is short by design. */\nexport const ANNOTATION_TAG_NAME_MAX = 60\n\n/**\n * The longest free text that the search accepts.\n *\n * The VIEW needs it as much as the route: a field with no ceiling lets a\n * person paste more than the route takes, and the answer is then a 400 that\n * reads like a broken search. The field holds them here instead, and a deep\n * link that carries more is cut to this length rather than breaking the page.\n */\nexport const ANNOTATION_SEARCH_MAX_LENGTH = 200\n\n/** Annotations for each page when the caller asks for no number. */\nexport const ANNOTATION_PAGE_SIZE_DEFAULT = 100\n\n/**\n * The most annotations that one page can hold.\n *\n * The view needs this number too: a page that asked for more rows than the\n * service allows would get a 400 instead of rows.\n */\nexport const ANNOTATION_PAGE_SIZE_MAX = 500\n\n/**\n * The identity of a tag, from what a person typed.\n *\n * The case and the outer spaces go, and every run of inner whitespace becomes\n * one hyphen. `Partner`, ` partner ` and `Partner ` are then one tag, and\n * `key account` is `key-account`.\n *\n * Both sides run this: the backend writes the result into `normalizedName` and\n * holds it unique, and the frontend runs it to tell a person, before they\n * press the button, that the tag they are typing already exists.\n */\nexport function normalizeTagName(name: string): string {\n  return name.trim().toLowerCase().replace(/\\s+/g, '-')\n}\n"],
+  "mappings": "AA4CO,MAAM,0BAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAWO,MAAM,gCAGT;AAAA,EACF,SAAS;AAAA,EACT,cAAc;AAAA,EACd,gBAAgB;AAAA,EAChB,qBAAqB;AAAA,EACrB,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,cAAc;AAAA,EACd,eAAe;AACjB;AAUO,MAAM,mBAAmB,CAAC,QAAQ,KAAK;AAqIvC,MAAM,iCAAiC;AASvC,MAAM,6BAA6B;AAYnC,MAAM,wBAAwB;AAS9B,MAAM,sBAAsB;AAG5B,MAAM,0BAA0B;AAUhC,MAAM,+BAA+B;AAGrC,MAAM,+BAA+B;AAQrC,MAAM,2BAA2B;AAajC,SAAS,iBAAiB,MAAsB;AACrD,SAAO,KAAK,KAAK,EAAE,YAAY,EAAE,QAAQ,QAAQ,GAAG;AACtD;",
+  "names": []
+}

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

@@ -57,6 +57,80 @@ export declare const APPROVAL_PAGE_SIZE_DEFAULT = 500;
  * page that asked for more would get a 400 instead of rows.
  */
 export declare const APPROVAL_PAGE_SIZE_MAX = 2000;
+/**
+ * The columns that the queue can be ordered by.
+ *
+ * A NAME and not an SQL expression: the repository maps each one, so a caller
+ * can never name a column that this list does not hold. `status` orders by the
+ * EFFECTIVE status, because a `pending` row whose time ran out reads as
+ * `expired` everywhere else.
+ */
+export declare const APPROVAL_SORT_FIELDS: readonly ["createdAt", "expiresAt", "status", "type", "createdBy"];
+export type ApprovalSortField = (typeof APPROVAL_SORT_FIELDS)[number];
+export type ApprovalSortOrder = 'asc' | 'desc';
+/** The default order of the queue: the newest request first. */
+export declare const APPROVAL_SORT_DEFAULT: {
+    sort: ApprovalSortField;
+    order: ApprovalSortOrder;
+};
+/**
+ * The longest reason that a request, a rejection or a withdrawal accepts.
+ *
+ * ONE number, because three routes of control-backend hold it and three fields
+ * of control-frontend must stop there. A field that let a person write more
+ * than the schema accepts turns their sentence into a 400 after they wrote it.
+ */
+export declare const APPROVAL_REASON_MAX_LENGTH = 2000;
+/**
+ * The largest number of approvals that a caller can ask for.
+ *
+ * A request that asks for 400 approvals can never reach them, so it is a
+ * request that only fills the table and expires. The ceiling turns that into a
+ * 400 at the moment a person types it. It is HERE because the form of the
+ * bulk operation must stop at the same number as the route.
+ */
+export declare const APPROVAL_ACKS_MAX = 10;
+/**
+ * The longest search text that the list accepts.
+ *
+ * A search runs `ILIKE` over the payload of every visible row, so the cost of
+ * one call follows the length of the text. Nothing a person types to find a
+ * request is near this.
+ */
+export declare const APPROVAL_SEARCH_MAX_LENGTH = 200;
+/**
+ * The payload field that names the organization a request acts on.
+ *
+ * It is a CONVENTION, and this constant is what makes the convention readable
+ * from both sides. A use case whose action hits one organization puts the id of
+ * that organization in this field, and `GET /api/approvals?orgId=…` then finds
+ * the request with no knowledge of the use case. The filter reads this one
+ * field of the payload, so it matches the whole id and nothing else. The free
+ * text search reads the payload as TEXT, which also matches an id that only
+ * appears inside another field, and it cannot answer "the requests of this
+ * organization".
+ *
+ * The organization page of control-frontend does NOT read this field. It asks
+ * the entity-link filter (`entityType=org`), which reads a row that
+ * `relatedEntities` of a use case writes — see `ApprovalEntityRef`. The summary
+ * is separate again: the `org` field of a `summarize` result is what a READER
+ * follows.
+ */
+export declare const APPROVAL_PAYLOAD_ORG_FIELD = "orgId";
+/**
+ * How many requests each status holds, for the filters of the queue.
+ *
+ * Every number answers the SAME question as the list beside it: the counts are
+ * built with the visibility rule, the action filter and the search text of the
+ * caller, and with the lazy expiry. A count that ignored one of those would
+ * send a person to a filter that then shows nothing.
+ */
+export interface ApprovalStatusCountsDto {
+    /** Every request that matches, whatever its status. */
+    all: number;
+    /** One number for each status. A status with no request is 0, never absent. */
+    byStatus: Record<ApprovalJobStatus, number>;
+}
 /**
  * What happens when a request reaches its threshold.
  *
@@ -95,6 +169,40 @@ export interface ApprovalAck extends ApprovalActor {
     /** An ISO timestamp. It is in a json column, so it is a string, not a Date. */
     date: string;
 }
+/**
+ * Who asked for an action, and who agreed to it.
+ *
+ * Every route of `api/admin/approvals` takes this envelope, and control-backend
+ * builds it from the request that it runs. The envelope exists because the
+ * token cannot carry it: the call is machine to machine, so `sub` holds the id
+ * of the Auth0 application and not a person. A service that reads the token
+ * alone therefore writes "control-backend" into its audit record, which hides
+ * the two Camundis that the whole mechanism exists to record.
+ *
+ * `approvedBy` is a list, because a use case can need more than one approval,
+ * and the record must name all of them. It can also be EMPTY: how many
+ * approvals an action needs is a number of the use case, and `move-cluster-org`
+ * holds zero on purpose. The person in `requestedBy` is never in the list: the
+ * four-eyes rule is that the person who asks is not the person who agrees, and
+ * control-backend holds that rule.
+ *
+ * Each person carries both keys of `ApprovalActor`. The email is what a route
+ * uses to ask Auth0 about the person, and the user id is what an audit record
+ * holds, because every other record of the fleet holds an Auth0 `sub`.
+ *
+ * CAUTION: The envelope is a CLAIM of the caller, and not proof. A route that
+ * acts on it must ask Auth0 again whether `requestedBy` holds the permission
+ * of the action. `api/admin/approvals` in accounts-backend does that. See the
+ * note on `M2M_CONTROL_APPROVALS`.
+ */
+export interface ApprovalM2mActor {
+    /** The id of the approval request, to join the records of both services. */
+    requestId: string;
+    /** The Camundi who opened the request. */
+    requestedBy: ApprovalActor;
+    /** The Camundis who approved it. Empty when the use case needs none. */
+    approvedBy: ApprovalActor[];
+}
 /**
  * What one value of a summary field is.
  *
@@ -133,6 +241,44 @@ export interface ApprovalSummaryField {
     label: string;
     kind: ApprovalSummaryFieldKind;
     values: ApprovalSummaryValue[];
+    /**
+     * How many values the field holds, when `values` holds only the first of
+     * them. The list route cuts every field to `APPROVAL_LIST_SUMMARY_VALUES_MAX`
+     * values. The detail route sends every value and no `total`.
+     */
+    total?: number;
+}
+/**
+ * How many values of one summary field a row of the list carries.
+ *
+ * A bulk operation names up to 3000 clusters in one field. A page of 100 such
+ * rows would carry 300,000 values that no row shows. The view shows at most
+ * 12 values of a field, so the list stops there, and `total` holds the count.
+ */
+export declare const APPROVAL_LIST_SUMMARY_VALUES_MAX = 12;
+/**
+ * The kinds of entity that an approval request can concern.
+ *
+ * These are the entities that a request is findable by: the org and cluster
+ * detail pages ask "which requests touch me", and the answer reads a row for
+ * each entity. It is a subset of `APPROVAL_SUMMARY_FIELD_KINDS` — the kinds that
+ * name an entity — because only those carry an id that a page can match.
+ */
+export declare const APPROVAL_ENTITY_TYPES: readonly ["cluster", "org", "user"];
+export type ApprovalEntityType = (typeof APPROVAL_ENTITY_TYPES)[number];
+/**
+ * One entity that an approval request concerns.
+ *
+ * A use case reports these from its payload, and the service writes one row for
+ * each into `approval_job_entity`. That row is what makes a request findable by
+ * an entity it touches, without a text search over the payload: a cluster-move
+ * request names its cluster, its target organization AND its source
+ * organization, so it shows on all three detail pages. The `summary` still
+ * carries the words a reader sees; this carries only the ids a page matches.
+ */
+export interface ApprovalEntityRef {
+    type: ApprovalEntityType;
+    id: string;
 }
 /**
  * How long a run may go quiet before a reader calls it stalled.
@@ -330,8 +476,12 @@ export interface ApprovalUseCaseDto {
      * approvals on it. A use case that carries the creator into its call sets
      * this, and `canCreate` then refuses such a caller at the start.
      *
-     * `extend-trial` is one: accounts makes the creator the actor of the
-     * extension, through `onBehalfOf`.
+     * `extend-trial` and `send-to-expired-trial` are two: both send the creator
+     * to accounts in an `ApprovalM2mActor`, and accounts reads the permissions
+     * of that person again before it acts.
+     *
+     * `move-cluster-org` does NOT set this. Its envelope reaches console, which
+     * reads the user id alone and needs no address.
      */
     creatorEmailRequired?: boolean;
 }

package/dist/dtos/ApprovalJob.dto.js

@@ -15,6 +15,18 @@ const APPROVAL_LIVE_STATUSES = [
 ];
 const APPROVAL_PAGE_SIZE_DEFAULT = 500;
 const APPROVAL_PAGE_SIZE_MAX = 2e3;
+const APPROVAL_SORT_FIELDS = [
+  "createdAt",
+  "expiresAt",
+  "status",
+  "type",
+  "createdBy"
+];
+const APPROVAL_SORT_DEFAULT = { sort: "createdAt", order: "desc" };
+const APPROVAL_REASON_MAX_LENGTH = 2e3;
+const APPROVAL_ACKS_MAX = 10;
+const APPROVAL_SEARCH_MAX_LENGTH = 200;
+const APPROVAL_PAYLOAD_ORG_FIELD = "orgId";
 const APPROVAL_SUMMARY_FIELD_KINDS = [
   "text",
   "number",
@@ -25,6 +37,8 @@ const APPROVAL_SUMMARY_FIELD_KINDS = [
   "user",
   "code"
 ];
+const APPROVAL_LIST_SUMMARY_VALUES_MAX = 12;
+const APPROVAL_ENTITY_TYPES = ["cluster", "org", "user"];
 const APPROVAL_RUN_STALE_MS = 12e4;
 function progressFraction(progress) {
   if (!progress || progress.total <= 0) {
@@ -43,11 +57,19 @@ function isRunStalled(job, now) {
   return now.getTime() - new Date(lastSign).getTime() > APPROVAL_RUN_STALE_MS;
 }
 export {
+  APPROVAL_ACKS_MAX,
+  APPROVAL_ENTITY_TYPES,
   APPROVAL_JOB_STATUSES,
+  APPROVAL_LIST_SUMMARY_VALUES_MAX,
   APPROVAL_LIVE_STATUSES,
   APPROVAL_PAGE_SIZE_DEFAULT,
   APPROVAL_PAGE_SIZE_MAX,
+  APPROVAL_PAYLOAD_ORG_FIELD,
+  APPROVAL_REASON_MAX_LENGTH,
   APPROVAL_RUN_STALE_MS,
+  APPROVAL_SEARCH_MAX_LENGTH,
+  APPROVAL_SORT_DEFAULT,
+  APPROVAL_SORT_FIELDS,
   APPROVAL_SUMMARY_FIELD_KINDS,
   isRunStalled,
   progressFraction

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/dtos/ApprovalJob.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 * The wire types of the generic approval mechanism.\n *\n * This file holds no logic and no dependency, because three consumers read it:\n * control-backend, control-frontend and cloudbot. The rules that read these\n * types are in `../approvals/policy.js`, and they are pure for the same reason.\n */\n\n/**\n * Every state that an approval request can hold.\n *\n * A `const` tuple, not an enum, so it is both the union type and the list that\n * validates a status filter at run time.\n *\n * The path of a request: `pending` until it reaches the threshold. Then\n * `executing` (automatic mode) or `approved` (explicit mode, which waits for a\n * person to press the button). `executed` or `failed` after the action ran. A\n * request that never reaches the threshold ends `rejected`, `withdrawn` or\n * `expired`.\n */\nexport const APPROVAL_JOB_STATUSES = [\n  'pending',\n  'approved',\n  'executing',\n  'executed',\n  'failed',\n  'rejected',\n  'withdrawn',\n  'expired',\n] as const\n\nexport type ApprovalJobStatus = (typeof APPROVAL_JOB_STATUSES)[number]\n\n/**\n * The states in which the action of a request is still COMING.\n *\n * `pending` waits for approvals, `approved` waits for a person to press the\n * button, and `executing` is running now. Each of them can still change the\n * world, so two requests for one target must not be in these states together.\n * `dedupeKey` reads this set for that reason.\n *\n * `failed` is NOT here, although a person can run a failed request again. A\n * failed request runs only when a person presses the button, and that person\n * sees the row. Blocking a new request on a failed one would also trap the\n * key: `canWithdraw` accepts `pending` alone, so nobody could close it.\n *\n * `executed`, `rejected`, `withdrawn` and `expired` are the end of a request.\n */\nexport const APPROVAL_LIVE_STATUSES = [\n  'pending',\n  'approved',\n  'executing',\n] as const satisfies readonly ApprovalJobStatus[]\n\n/**\n * How many requests one page of the list holds when the caller asks for no\n * number.\n *\n * The list is a work queue that a Camundi reads, so the page is large: a\n * person wants the whole queue and not ten rows at a time. What the number is\n * for is the ceiling below.\n */\nexport const APPROVAL_PAGE_SIZE_DEFAULT = 500\n\n/**\n * The largest page that the service builds, and the largest that a caller may\n * ask for. The API answers 400 above it.\n *\n * The list had no limit at all. One authenticated caller could then make the\n * service read the whole table into memory, serialize it, and do it again, so\n * the cost of a request grew with the age of the service and with nothing that\n * the caller had to pay for. A ceiling turns that into a fixed cost.\n *\n * It is HERE and not only in the service, because the view must know it: a\n * page that asked for more would get a 400 instead of rows.\n */\nexport const APPROVAL_PAGE_SIZE_MAX = 2000\n\n/**\n * What happens when a request reaches its threshold.\n *\n * `auto` runs the action immediately. `explicit` holds the request at\n * `approved` and waits for a person to run it.\n */\nexport type ApprovalExecutionMode = 'auto' | 'explicit'\n\n/**\n * WHERE the action runs. It is a separate question from who starts it.\n *\n * - `inline` runs the action inside the call that started it, and the answer\n *   already carries the outcome. Right for one call to another service.\n * - `background` answers as soon as the request is claimed, and the action\n *   runs on. It reports into `ApprovalJobDto.progress`, and the row is the\n *   only place that holds the progress, so a reload and a second person read\n *   the same numbers. A pod that stops loses the run, and the reconciler of\n *   control-backend recovers the row.\n *\n * An action over thousands of targets MUST be `background`. `inline` would\n * hold one HTTP request for the whole run, and the ingress, the load balancer\n * and the browser each have their own deadline before it finishes.\n */\nexport type ApprovalActionMode = 'inline' | 'background'\n\n/**\n * A person, as an approval request records them.\n *\n * Both keys are kept. The machine then never has to choose one identity key,\n * which is what split the earlier acknowledgement flows: some held an email and\n * some held a user id, and the two could not be compared.\n */\nexport interface ApprovalActor {\n  userId: string\n  email: string\n}\n\nexport interface ApprovalAck extends ApprovalActor {\n  /** An ISO timestamp. It is in a json column, so it is a string, not a Date. */\n  date: string\n}\n\n/**\n * What one value of a summary field is.\n *\n * `text` is what a person reads. `id` is what a link points at, and it is\n * absent when the kind names no entity. The two are separate because the text\n * is a COPY that the request keeps: an organization that gets a new name after\n * the request was opened must still read as the organization that the person\n * chose.\n */\nexport interface ApprovalSummaryValue {\n  text: string\n  id?: string\n}\n\n/**\n * How a reader must render one field of a summary.\n *\n * `org`, `cluster` and `user` name an entity, so a reader can link to it and\n * can resolve a fresh name. The others are plain: `date` is an ISO timestamp,\n * and `code` is a value that must keep its characters, such as a json fragment.\n */\nexport const APPROVAL_SUMMARY_FIELD_KINDS = [\n  'text',\n  'number',\n  'boolean',\n  'date',\n  'org',\n  'cluster',\n  'user',\n  'code',\n] as const\n\nexport type ApprovalSummaryFieldKind =\n  (typeof APPROVAL_SUMMARY_FIELD_KINDS)[number]\n\n/**\n * One labelled field of the payload of a request.\n *\n * This is what makes ONE view able to show EVERY use case. The payload of a\n * request is an object of anything, so a generic view can only print it as\n * json. The use case turns it into labelled fields here, and the view renders\n * a field by its kind: it links an `org`, it formats a `date`, and it lists\n * 300 clusters as 300 links.\n *\n * `values` is always an array. A field that holds one value holds an array of\n * one, so a reader needs no branch for \"one or many\".\n */\nexport interface ApprovalSummaryField {\n  label: string\n  kind: ApprovalSummaryFieldKind\n  values: ApprovalSummaryValue[]\n}\n\n/**\n * How long a run may go quiet before a reader calls it stalled.\n *\n * The pod that runs an action writes its progress and renews its lease on one\n * timer, so a healthy run touches the row well inside this window. A row that\n * is `executing` and older than this held a pod that stopped, and the\n * reconciler of control-backend is on its way to it.\n *\n * It lives here, and not in the config of the service, because a READER needs\n * it: the browser must decide what to show without a second call, and a number\n * that only the backend knew would make the two disagree. `ACTION_LEASE_MS` in\n * `config/index.ts` is held below this on purpose.\n */\nexport const APPROVAL_RUN_STALE_MS = 120_000\n\n/**\n * What an action reports while it runs.\n *\n * This is what makes a long action watchable. Every field is in the DATABASE\n * and not in the answer to the call that started the run, so three readers see\n * the same thing: the person who pressed the button, the same person after a\n * reload, and a second person who opens the request.\n *\n * `total` can be 0 while an action counts its targets, and it stays 0 for an\n * action that cannot count them. A reader must then show that it runs, and no\n * percentage.\n */\nexport interface ApprovalProgress {\n  /** Targets in total. 0 means the action did not say. */\n  total: number\n  /** Targets finished, whatever the outcome of each one. */\n  done: number\n  /** Targets that finished with an error. Part of `done`. */\n  failed: number\n  /** One short line for a person, such as the step that runs now. */\n  note?: string\n  /** An ISO timestamp: when the run started. */\n  startedAt: string\n  /** An ISO timestamp: when the run last wrote anything. */\n  updatedAt: string\n}\n\n/** The share of the work that is finished, or `undefined` with no total. */\nexport function progressFraction(\n  progress: ApprovalProgress | undefined,\n): number | undefined {\n  if (!progress || progress.total <= 0) {\n    return undefined\n  }\n  return Math.min(1, progress.done / progress.total)\n}\n\n/**\n * Reports whether a running request went quiet.\n *\n * True means that the pod which held the run stopped, or lost the row. It does\n * NOT mean that the action failed: the reconciler either runs it again, or it\n * writes `failed` so that a person can. See `APPROVAL_RUN_STALE_MS`.\n */\nexport function isRunStalled(job: ApprovalJobDto, now: Date): boolean {\n  if (job.status !== 'executing') {\n    return false\n  }\n  const lastSign = job.progress?.updatedAt ?? job.executingSince\n  if (!lastSign) {\n    return false\n  }\n  return now.getTime() - new Date(lastSign).getTime() > APPROVAL_RUN_STALE_MS\n}\n\n/** One approval request, as the API returns it. */\nexport interface ApprovalJobDto {\n  id: string\n  type: string\n  dedupeKey?: string\n  payload: Record<string, unknown>\n  /**\n   * The payload as labelled fields. See `ApprovalSummaryField`.\n   *\n   * The use case builds it when the request is opened AND every time the\n   * request is read, so a field that a later version of the use case adds\n   * appears on a request that is already open.\n   */\n  summary: ApprovalSummaryField[]\n  /** Why the person opened the request. Some use cases demand one. */\n  reason?: string\n  createdBy: ApprovalActor\n  acks: ApprovalAck[]\n  /**\n   * How many approvals THIS request needs.\n   *\n   * It is on the request and not only on the use case, because the person who\n   * opens one can ask for more than the floor of the use case. A bulk\n   * operation over 3000 clusters is the same action as one over 3, and it can\n   * still deserve a third pair of eyes. `ApprovalUseCaseDto.minAcks` is the\n   * floor that a caller cannot go below.\n   */\n  requiredAcks: number\n  /**\n   * What a person must hold to approve, reject or run THIS request.\n   *\n   * It is on the request and not only on the use case, because a payload can\n   * raise the guard: a generation update with `yoloForceUpdate` needs the yolo\n   * permission on top of the base one, and the same use case without the flag\n   * does not. The set is computed ONE time, when the request is opened, so it\n   * is also the record of what the request was guarded by.\n   *\n   * A person needs EVERY permission in the set, not one of them.\n   */\n  requiredPermissions: string[]\n  executionMode: ApprovalExecutionMode\n  actionMode: ApprovalActionMode\n  status: ApprovalJobStatus\n  closedBy?: ApprovalActor\n  closedReason?: string\n  /** An ISO timestamp. */\n  expiresAt: string\n  /**\n   * An ISO timestamp: when the current run took the request.\n   *\n   * It is set every time a run starts, so a run that the reconciler starts\n   * again moves it. `attempts` says how many runs there were.\n   */\n  executingSince?: string\n  /** How many times a run started. A recovery raises it. */\n  attempts: number\n  /**\n   * What the action reports while it runs. See `ApprovalProgress`.\n   *\n   * It stays on the row after the run, so the record of a finished run says\n   * how many targets it touched and how many refused.\n   */\n  progress?: ApprovalProgress\n  executedAt?: string\n  executionError?: string\n  /**\n   * What the action reported when it ran.\n   *\n   * The shape belongs to the use case. An action over many targets puts the\n   * result of each target here, which is the difference between \"it failed\"\n   * and \"it did 2998 of 3000, and these two refused\".\n   */\n  executionResult?: Record<string, unknown>\n  createdAt: string\n  updatedAt: string\n}\n\n/**\n * What a use case is, as the API reports it.\n *\n * The frontend needs `requiredPermission` to run the same rule as the backend.\n * PR #9301 kept this registry a second time, by hand, in the frontend. A\n * registry that the server owns means a new use case needs no frontend deploy.\n */\nexport interface ApprovalUseCaseDto {\n  type: string\n  /** A short name for a person to read. */\n  label: string\n  /** One sentence: what the action does, and what it cannot undo. */\n  description: string\n  /** The approvals a new request asks for when the caller names no number. */\n  defaultAcks: number\n  /**\n   * The floor. A caller can ask for more approvals, never for fewer.\n   *\n   * It is a separate number from `defaultAcks` because the two answer\n   * different questions: the default is what the form offers, and the floor is\n   * what the service refuses to go below.\n   */\n  minAcks: number\n  ttlDays: number\n  executionMode: ApprovalExecutionMode\n  /** See `ApprovalActionMode`. An action over many targets is `background`. */\n  actionMode: ApprovalActionMode\n  /**\n   * True when a run that was interrupted can start again by itself.\n   *\n   * It is a promise about the ACTION, and the reconciler reads it. Set it only\n   * when the action can run a second time over the same payload and do no harm\n   * twice: it must read what the first run already finished, out of\n   * `ApprovalJobDto.executionResult`, and skip it.\n   *\n   * False, the default, is the safe answer. An interrupted run then lands in\n   * `failed`, which a person can run again from the detail page, and a person\n   * decides whether running it twice is safe.\n   */\n  resumable: boolean\n  /**\n   * The permission that every request of this use case needs to approve,\n   * reject or run. A payload can add more. See\n   * `ApprovalJobDto.requiredPermissions`, which is the effective set.\n   *\n   * It is also the permission to SEE a request of this use case, because a\n   * person who cannot act on one has no reason to read it. The person who\n   * opened a request always sees that request.\n   */\n  requiredPermission: string\n  /**\n   * The permission to open a request. Absent means any signed-in Camundi.\n   *\n   * Set it when the pool that can ASK must be as small as the pool that can\n   * approve. Leave it absent when the approvals alone are the guard, and the\n   * proposal is not.\n   */\n  createPermission?: string\n  /** True when a request cannot be opened without a reason. */\n  reasonRequired: boolean\n  /**\n   * True when the ACTION needs the email address of the person who asked.\n   *\n   * A token can carry no address, and the row then stores\n   * `UNKNOWN_ACTOR_EMAIL`. An action that sends that placeholder to another\n   * service asks it to find a user that does not exist, so the request can\n   * only fail \u2014 and it fails at the END, after other people spent their\n   * approvals on it. A use case that carries the creator into its call sets\n   * this, and `canCreate` then refuses such a caller at the start.\n   *\n   * `extend-trial` is one: accounts makes the creator the actor of the\n   * extension, through `onBehalfOf`.\n   */\n  creatorEmailRequired?: boolean\n}\n"],
-  "mappings": "AA0BO,MAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAmBO,MAAM,yBAAyB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AACF;AAUO,MAAM,6BAA6B;AAcnC,MAAM,yBAAyB;AAiE/B,MAAM,+BAA+B;AAAA,EAC1C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAoCO,MAAM,wBAAwB;AA8B9B,SAAS,iBACd,UACoB;AACpB,MAAI,CAAC,YAAY,SAAS,SAAS,GAAG;AACpC,WAAO;AAAA,EACT;AACA,SAAO,KAAK,IAAI,GAAG,SAAS,OAAO,SAAS,KAAK;AACnD;AASO,SAAS,aAAa,KAAqB,KAAoB;AACpE,MAAI,IAAI,WAAW,aAAa;AAC9B,WAAO;AAAA,EACT;AACA,QAAM,WAAW,IAAI,UAAU,aAAa,IAAI;AAChD,MAAI,CAAC,UAAU;AACb,WAAO;AAAA,EACT;AACA,SAAO,IAAI,QAAQ,IAAI,IAAI,KAAK,QAAQ,EAAE,QAAQ,IAAI;AACxD;",
+  "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 wire types of the generic approval mechanism.\n *\n * This file holds no logic and no dependency, because three consumers read it:\n * control-backend, control-frontend and cloudbot. The rules that read these\n * types are in `../approvals/policy.js`, and they are pure for the same reason.\n */\n\n/**\n * Every state that an approval request can hold.\n *\n * A `const` tuple, not an enum, so it is both the union type and the list that\n * validates a status filter at run time.\n *\n * The path of a request: `pending` until it reaches the threshold. Then\n * `executing` (automatic mode) or `approved` (explicit mode, which waits for a\n * person to press the button). `executed` or `failed` after the action ran. A\n * request that never reaches the threshold ends `rejected`, `withdrawn` or\n * `expired`.\n */\nexport const APPROVAL_JOB_STATUSES = [\n  'pending',\n  'approved',\n  'executing',\n  'executed',\n  'failed',\n  'rejected',\n  'withdrawn',\n  'expired',\n] as const\n\nexport type ApprovalJobStatus = (typeof APPROVAL_JOB_STATUSES)[number]\n\n/**\n * The states in which the action of a request is still COMING.\n *\n * `pending` waits for approvals, `approved` waits for a person to press the\n * button, and `executing` is running now. Each of them can still change the\n * world, so two requests for one target must not be in these states together.\n * `dedupeKey` reads this set for that reason.\n *\n * `failed` is NOT here, although a person can run a failed request again. A\n * failed request runs only when a person presses the button, and that person\n * sees the row. Blocking a new request on a failed one would also trap the\n * key: `canWithdraw` accepts `pending` alone, so nobody could close it.\n *\n * `executed`, `rejected`, `withdrawn` and `expired` are the end of a request.\n */\nexport const APPROVAL_LIVE_STATUSES = [\n  'pending',\n  'approved',\n  'executing',\n] as const satisfies readonly ApprovalJobStatus[]\n\n/**\n * How many requests one page of the list holds when the caller asks for no\n * number.\n *\n * The list is a work queue that a Camundi reads, so the page is large: a\n * person wants the whole queue and not ten rows at a time. What the number is\n * for is the ceiling below.\n */\nexport const APPROVAL_PAGE_SIZE_DEFAULT = 500\n\n/**\n * The largest page that the service builds, and the largest that a caller may\n * ask for. The API answers 400 above it.\n *\n * The list had no limit at all. One authenticated caller could then make the\n * service read the whole table into memory, serialize it, and do it again, so\n * the cost of a request grew with the age of the service and with nothing that\n * the caller had to pay for. A ceiling turns that into a fixed cost.\n *\n * It is HERE and not only in the service, because the view must know it: a\n * page that asked for more would get a 400 instead of rows.\n */\nexport const APPROVAL_PAGE_SIZE_MAX = 2000\n\n/**\n * The columns that the queue can be ordered by.\n *\n * A NAME and not an SQL expression: the repository maps each one, so a caller\n * can never name a column that this list does not hold. `status` orders by the\n * EFFECTIVE status, because a `pending` row whose time ran out reads as\n * `expired` everywhere else.\n */\nexport const APPROVAL_SORT_FIELDS = [\n  'createdAt',\n  'expiresAt',\n  'status',\n  'type',\n  'createdBy',\n] as const\n\nexport type ApprovalSortField = (typeof APPROVAL_SORT_FIELDS)[number]\n\nexport type ApprovalSortOrder = 'asc' | 'desc'\n\n/** The default order of the queue: the newest request first. */\nexport const APPROVAL_SORT_DEFAULT: {\n  sort: ApprovalSortField\n  order: ApprovalSortOrder\n} = { sort: 'createdAt', order: 'desc' }\n\n/**\n * The longest reason that a request, a rejection or a withdrawal accepts.\n *\n * ONE number, because three routes of control-backend hold it and three fields\n * of control-frontend must stop there. A field that let a person write more\n * than the schema accepts turns their sentence into a 400 after they wrote it.\n */\nexport const APPROVAL_REASON_MAX_LENGTH = 2000\n\n/**\n * The largest number of approvals that a caller can ask for.\n *\n * A request that asks for 400 approvals can never reach them, so it is a\n * request that only fills the table and expires. The ceiling turns that into a\n * 400 at the moment a person types it. It is HERE because the form of the\n * bulk operation must stop at the same number as the route.\n */\nexport const APPROVAL_ACKS_MAX = 10\n\n/**\n * The longest search text that the list accepts.\n *\n * A search runs `ILIKE` over the payload of every visible row, so the cost of\n * one call follows the length of the text. Nothing a person types to find a\n * request is near this.\n */\nexport const APPROVAL_SEARCH_MAX_LENGTH = 200\n\n/**\n * The payload field that names the organization a request acts on.\n *\n * It is a CONVENTION, and this constant is what makes the convention readable\n * from both sides. A use case whose action hits one organization puts the id of\n * that organization in this field, and `GET /api/approvals?orgId=\u2026` then finds\n * the request with no knowledge of the use case. The filter reads this one\n * field of the payload, so it matches the whole id and nothing else. The free\n * text search reads the payload as TEXT, which also matches an id that only\n * appears inside another field, and it cannot answer \"the requests of this\n * organization\".\n *\n * The organization page of control-frontend does NOT read this field. It asks\n * the entity-link filter (`entityType=org`), which reads a row that\n * `relatedEntities` of a use case writes \u2014 see `ApprovalEntityRef`. The summary\n * is separate again: the `org` field of a `summarize` result is what a READER\n * follows.\n */\nexport const APPROVAL_PAYLOAD_ORG_FIELD = 'orgId'\n\n/**\n * How many requests each status holds, for the filters of the queue.\n *\n * Every number answers the SAME question as the list beside it: the counts are\n * built with the visibility rule, the action filter and the search text of the\n * caller, and with the lazy expiry. A count that ignored one of those would\n * send a person to a filter that then shows nothing.\n */\nexport interface ApprovalStatusCountsDto {\n  /** Every request that matches, whatever its status. */\n  all: number\n  /** One number for each status. A status with no request is 0, never absent. */\n  byStatus: Record<ApprovalJobStatus, number>\n}\n\n/**\n * What happens when a request reaches its threshold.\n *\n * `auto` runs the action immediately. `explicit` holds the request at\n * `approved` and waits for a person to run it.\n */\nexport type ApprovalExecutionMode = 'auto' | 'explicit'\n\n/**\n * WHERE the action runs. It is a separate question from who starts it.\n *\n * - `inline` runs the action inside the call that started it, and the answer\n *   already carries the outcome. Right for one call to another service.\n * - `background` answers as soon as the request is claimed, and the action\n *   runs on. It reports into `ApprovalJobDto.progress`, and the row is the\n *   only place that holds the progress, so a reload and a second person read\n *   the same numbers. A pod that stops loses the run, and the reconciler of\n *   control-backend recovers the row.\n *\n * An action over thousands of targets MUST be `background`. `inline` would\n * hold one HTTP request for the whole run, and the ingress, the load balancer\n * and the browser each have their own deadline before it finishes.\n */\nexport type ApprovalActionMode = 'inline' | 'background'\n\n/**\n * A person, as an approval request records them.\n *\n * Both keys are kept. The machine then never has to choose one identity key,\n * which is what split the earlier acknowledgement flows: some held an email and\n * some held a user id, and the two could not be compared.\n */\nexport interface ApprovalActor {\n  userId: string\n  email: string\n}\n\nexport interface ApprovalAck extends ApprovalActor {\n  /** An ISO timestamp. It is in a json column, so it is a string, not a Date. */\n  date: string\n}\n\n/**\n * Who asked for an action, and who agreed to it.\n *\n * Every route of `api/admin/approvals` takes this envelope, and control-backend\n * builds it from the request that it runs. The envelope exists because the\n * token cannot carry it: the call is machine to machine, so `sub` holds the id\n * of the Auth0 application and not a person. A service that reads the token\n * alone therefore writes \"control-backend\" into its audit record, which hides\n * the two Camundis that the whole mechanism exists to record.\n *\n * `approvedBy` is a list, because a use case can need more than one approval,\n * and the record must name all of them. It can also be EMPTY: how many\n * approvals an action needs is a number of the use case, and `move-cluster-org`\n * holds zero on purpose. The person in `requestedBy` is never in the list: the\n * four-eyes rule is that the person who asks is not the person who agrees, and\n * control-backend holds that rule.\n *\n * Each person carries both keys of `ApprovalActor`. The email is what a route\n * uses to ask Auth0 about the person, and the user id is what an audit record\n * holds, because every other record of the fleet holds an Auth0 `sub`.\n *\n * CAUTION: The envelope is a CLAIM of the caller, and not proof. A route that\n * acts on it must ask Auth0 again whether `requestedBy` holds the permission\n * of the action. `api/admin/approvals` in accounts-backend does that. See the\n * note on `M2M_CONTROL_APPROVALS`.\n */\nexport interface ApprovalM2mActor {\n  /** The id of the approval request, to join the records of both services. */\n  requestId: string\n  /** The Camundi who opened the request. */\n  requestedBy: ApprovalActor\n  /** The Camundis who approved it. Empty when the use case needs none. */\n  approvedBy: ApprovalActor[]\n}\n\n/**\n * What one value of a summary field is.\n *\n * `text` is what a person reads. `id` is what a link points at, and it is\n * absent when the kind names no entity. The two are separate because the text\n * is a COPY that the request keeps: an organization that gets a new name after\n * the request was opened must still read as the organization that the person\n * chose.\n */\nexport interface ApprovalSummaryValue {\n  text: string\n  id?: string\n}\n\n/**\n * How a reader must render one field of a summary.\n *\n * `org`, `cluster` and `user` name an entity, so a reader can link to it and\n * can resolve a fresh name. The others are plain: `date` is an ISO timestamp,\n * and `code` is a value that must keep its characters, such as a json fragment.\n */\nexport const APPROVAL_SUMMARY_FIELD_KINDS = [\n  'text',\n  'number',\n  'boolean',\n  'date',\n  'org',\n  'cluster',\n  'user',\n  'code',\n] as const\n\nexport type ApprovalSummaryFieldKind =\n  (typeof APPROVAL_SUMMARY_FIELD_KINDS)[number]\n\n/**\n * One labelled field of the payload of a request.\n *\n * This is what makes ONE view able to show EVERY use case. The payload of a\n * request is an object of anything, so a generic view can only print it as\n * json. The use case turns it into labelled fields here, and the view renders\n * a field by its kind: it links an `org`, it formats a `date`, and it lists\n * 300 clusters as 300 links.\n *\n * `values` is always an array. A field that holds one value holds an array of\n * one, so a reader needs no branch for \"one or many\".\n */\nexport interface ApprovalSummaryField {\n  label: string\n  kind: ApprovalSummaryFieldKind\n  values: ApprovalSummaryValue[]\n  /**\n   * How many values the field holds, when `values` holds only the first of\n   * them. The list route cuts every field to `APPROVAL_LIST_SUMMARY_VALUES_MAX`\n   * values. The detail route sends every value and no `total`.\n   */\n  total?: number\n}\n\n/**\n * How many values of one summary field a row of the list carries.\n *\n * A bulk operation names up to 3000 clusters in one field. A page of 100 such\n * rows would carry 300,000 values that no row shows. The view shows at most\n * 12 values of a field, so the list stops there, and `total` holds the count.\n */\nexport const APPROVAL_LIST_SUMMARY_VALUES_MAX = 12\n\n/**\n * The kinds of entity that an approval request can concern.\n *\n * These are the entities that a request is findable by: the org and cluster\n * detail pages ask \"which requests touch me\", and the answer reads a row for\n * each entity. It is a subset of `APPROVAL_SUMMARY_FIELD_KINDS` \u2014 the kinds that\n * name an entity \u2014 because only those carry an id that a page can match.\n */\nexport const APPROVAL_ENTITY_TYPES = ['cluster', 'org', 'user'] as const\n\nexport type ApprovalEntityType = (typeof APPROVAL_ENTITY_TYPES)[number]\n\n/**\n * One entity that an approval request concerns.\n *\n * A use case reports these from its payload, and the service writes one row for\n * each into `approval_job_entity`. That row is what makes a request findable by\n * an entity it touches, without a text search over the payload: a cluster-move\n * request names its cluster, its target organization AND its source\n * organization, so it shows on all three detail pages. The `summary` still\n * carries the words a reader sees; this carries only the ids a page matches.\n */\nexport interface ApprovalEntityRef {\n  type: ApprovalEntityType\n  id: string\n}\n\n/**\n * How long a run may go quiet before a reader calls it stalled.\n *\n * The pod that runs an action writes its progress and renews its lease on one\n * timer, so a healthy run touches the row well inside this window. A row that\n * is `executing` and older than this held a pod that stopped, and the\n * reconciler of control-backend is on its way to it.\n *\n * It lives here, and not in the config of the service, because a READER needs\n * it: the browser must decide what to show without a second call, and a number\n * that only the backend knew would make the two disagree. `ACTION_LEASE_MS` in\n * `config/index.ts` is held below this on purpose.\n */\nexport const APPROVAL_RUN_STALE_MS = 120_000\n\n/**\n * What an action reports while it runs.\n *\n * This is what makes a long action watchable. Every field is in the DATABASE\n * and not in the answer to the call that started the run, so three readers see\n * the same thing: the person who pressed the button, the same person after a\n * reload, and a second person who opens the request.\n *\n * `total` can be 0 while an action counts its targets, and it stays 0 for an\n * action that cannot count them. A reader must then show that it runs, and no\n * percentage.\n */\nexport interface ApprovalProgress {\n  /** Targets in total. 0 means the action did not say. */\n  total: number\n  /** Targets finished, whatever the outcome of each one. */\n  done: number\n  /** Targets that finished with an error. Part of `done`. */\n  failed: number\n  /** One short line for a person, such as the step that runs now. */\n  note?: string\n  /** An ISO timestamp: when the run started. */\n  startedAt: string\n  /** An ISO timestamp: when the run last wrote anything. */\n  updatedAt: string\n}\n\n/** The share of the work that is finished, or `undefined` with no total. */\nexport function progressFraction(\n  progress: ApprovalProgress | undefined,\n): number | undefined {\n  if (!progress || progress.total <= 0) {\n    return undefined\n  }\n  return Math.min(1, progress.done / progress.total)\n}\n\n/**\n * Reports whether a running request went quiet.\n *\n * True means that the pod which held the run stopped, or lost the row. It does\n * NOT mean that the action failed: the reconciler either runs it again, or it\n * writes `failed` so that a person can. See `APPROVAL_RUN_STALE_MS`.\n */\nexport function isRunStalled(job: ApprovalJobDto, now: Date): boolean {\n  if (job.status !== 'executing') {\n    return false\n  }\n  const lastSign = job.progress?.updatedAt ?? job.executingSince\n  if (!lastSign) {\n    return false\n  }\n  return now.getTime() - new Date(lastSign).getTime() > APPROVAL_RUN_STALE_MS\n}\n\n/** One approval request, as the API returns it. */\nexport interface ApprovalJobDto {\n  id: string\n  type: string\n  dedupeKey?: string\n  payload: Record<string, unknown>\n  /**\n   * The payload as labelled fields. See `ApprovalSummaryField`.\n   *\n   * The use case builds it when the request is opened AND every time the\n   * request is read, so a field that a later version of the use case adds\n   * appears on a request that is already open.\n   */\n  summary: ApprovalSummaryField[]\n  /** Why the person opened the request. Some use cases demand one. */\n  reason?: string\n  createdBy: ApprovalActor\n  acks: ApprovalAck[]\n  /**\n   * How many approvals THIS request needs.\n   *\n   * It is on the request and not only on the use case, because the person who\n   * opens one can ask for more than the floor of the use case. A bulk\n   * operation over 3000 clusters is the same action as one over 3, and it can\n   * still deserve a third pair of eyes. `ApprovalUseCaseDto.minAcks` is the\n   * floor that a caller cannot go below.\n   */\n  requiredAcks: number\n  /**\n   * What a person must hold to approve, reject or run THIS request.\n   *\n   * It is on the request and not only on the use case, because a payload can\n   * raise the guard: a generation update with `yoloForceUpdate` needs the yolo\n   * permission on top of the base one, and the same use case without the flag\n   * does not. The set is computed ONE time, when the request is opened, so it\n   * is also the record of what the request was guarded by.\n   *\n   * A person needs EVERY permission in the set, not one of them.\n   */\n  requiredPermissions: string[]\n  executionMode: ApprovalExecutionMode\n  actionMode: ApprovalActionMode\n  status: ApprovalJobStatus\n  closedBy?: ApprovalActor\n  closedReason?: string\n  /** An ISO timestamp. */\n  expiresAt: string\n  /**\n   * An ISO timestamp: when the current run took the request.\n   *\n   * It is set every time a run starts, so a run that the reconciler starts\n   * again moves it. `attempts` says how many runs there were.\n   */\n  executingSince?: string\n  /** How many times a run started. A recovery raises it. */\n  attempts: number\n  /**\n   * What the action reports while it runs. See `ApprovalProgress`.\n   *\n   * It stays on the row after the run, so the record of a finished run says\n   * how many targets it touched and how many refused.\n   */\n  progress?: ApprovalProgress\n  executedAt?: string\n  executionError?: string\n  /**\n   * What the action reported when it ran.\n   *\n   * The shape belongs to the use case. An action over many targets puts the\n   * result of each target here, which is the difference between \"it failed\"\n   * and \"it did 2998 of 3000, and these two refused\".\n   */\n  executionResult?: Record<string, unknown>\n  createdAt: string\n  updatedAt: string\n}\n\n/**\n * What a use case is, as the API reports it.\n *\n * The frontend needs `requiredPermission` to run the same rule as the backend.\n * PR #9301 kept this registry a second time, by hand, in the frontend. A\n * registry that the server owns means a new use case needs no frontend deploy.\n */\nexport interface ApprovalUseCaseDto {\n  type: string\n  /** A short name for a person to read. */\n  label: string\n  /** One sentence: what the action does, and what it cannot undo. */\n  description: string\n  /** The approvals a new request asks for when the caller names no number. */\n  defaultAcks: number\n  /**\n   * The floor. A caller can ask for more approvals, never for fewer.\n   *\n   * It is a separate number from `defaultAcks` because the two answer\n   * different questions: the default is what the form offers, and the floor is\n   * what the service refuses to go below.\n   */\n  minAcks: number\n  ttlDays: number\n  executionMode: ApprovalExecutionMode\n  /** See `ApprovalActionMode`. An action over many targets is `background`. */\n  actionMode: ApprovalActionMode\n  /**\n   * True when a run that was interrupted can start again by itself.\n   *\n   * It is a promise about the ACTION, and the reconciler reads it. Set it only\n   * when the action can run a second time over the same payload and do no harm\n   * twice: it must read what the first run already finished, out of\n   * `ApprovalJobDto.executionResult`, and skip it.\n   *\n   * False, the default, is the safe answer. An interrupted run then lands in\n   * `failed`, which a person can run again from the detail page, and a person\n   * decides whether running it twice is safe.\n   */\n  resumable: boolean\n  /**\n   * The permission that every request of this use case needs to approve,\n   * reject or run. A payload can add more. See\n   * `ApprovalJobDto.requiredPermissions`, which is the effective set.\n   *\n   * It is also the permission to SEE a request of this use case, because a\n   * person who cannot act on one has no reason to read it. The person who\n   * opened a request always sees that request.\n   */\n  requiredPermission: string\n  /**\n   * The permission to open a request. Absent means any signed-in Camundi.\n   *\n   * Set it when the pool that can ASK must be as small as the pool that can\n   * approve. Leave it absent when the approvals alone are the guard, and the\n   * proposal is not.\n   */\n  createPermission?: string\n  /** True when a request cannot be opened without a reason. */\n  reasonRequired: boolean\n  /**\n   * True when the ACTION needs the email address of the person who asked.\n   *\n   * A token can carry no address, and the row then stores\n   * `UNKNOWN_ACTOR_EMAIL`. An action that sends that placeholder to another\n   * service asks it to find a user that does not exist, so the request can\n   * only fail \u2014 and it fails at the END, after other people spent their\n   * approvals on it. A use case that carries the creator into its call sets\n   * this, and `canCreate` then refuses such a caller at the start.\n   *\n   * `extend-trial` and `send-to-expired-trial` are two: both send the creator\n   * to accounts in an `ApprovalM2mActor`, and accounts reads the permissions\n   * of that person again before it acts.\n   *\n   * `move-cluster-org` does NOT set this. Its envelope reaches console, which\n   * reads the user id alone and needs no address.\n   */\n  creatorEmailRequired?: boolean\n}\n"],
+  "mappings": "AA0BO,MAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAmBO,MAAM,yBAAyB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AACF;AAUO,MAAM,6BAA6B;AAcnC,MAAM,yBAAyB;AAU/B,MAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAOO,MAAM,wBAGT,EAAE,MAAM,aAAa,OAAO,OAAO;AAShC,MAAM,6BAA6B;AAUnC,MAAM,oBAAoB;AAS1B,MAAM,6BAA6B;AAoBnC,MAAM,6BAA6B;AAmHnC,MAAM,+BAA+B;AAAA,EAC1C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAoCO,MAAM,mCAAmC;AAUzC,MAAM,wBAAwB,CAAC,WAAW,OAAO,MAAM;AAgCvD,MAAM,wBAAwB;AA8B9B,SAAS,iBACd,UACoB;AACpB,MAAI,CAAC,YAAY,SAAS,SAAS,GAAG;AACpC,WAAO;AAAA,EACT;AACA,SAAO,KAAK,IAAI,GAAG,SAAS,OAAO,SAAS,KAAK;AACnD;AASO,SAAS,aAAa,KAAqB,KAAoB;AACpE,MAAI,IAAI,WAAW,aAAa;AAC9B,WAAO;AAAA,EACT;AACA,QAAM,WAAW,IAAI,UAAU,aAAa,IAAI;AAChD,MAAI,CAAC,UAAU;AACb,WAAO;AAAA,EACT;AACA,SAAO,IAAI,QAAQ,IAAI,IAAI,KAAK,QAAQ,EAAE,QAAQ,IAAI;AACxD;",
   "names": []
 }