@camunda/ccma-shared-types 4.0.0 → 5.0.0

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

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

package/dist/dtos/FeatureFlagOverride.dto.js

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

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

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