@camunda/ccma-shared-types 0.4.0 → 0.5.1

package/dist/types/HdpTenantUsage.type.d.ts

@@ -0,0 +1,4 @@
+export interface HdpTenantUsagePoint {
+    ts: number;
+    value: number;
+}

package/dist/types/HdpTenantUsage.type.js

@@ -0,0 +1 @@
+//# sourceMappingURL=HdpTenantUsage.type.js.map

package/dist/types/HdpTenantUsage.type.js.map

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

package/dist/utils/enterpriseTerm.utils.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The enterprise contract period a usage figure belongs to.
+ *
+ * An enterprise contract starts at `enterpriseStartDate` and renews every
+ * `enterpriseDurationInMonth` months. Usage is measured against the *current*
+ * period's included quota, so anything summed or peaked over a wider window
+ * bills a previous term's usage against this term's inclusions.
+ *
+ * Extracted from c4's billing tab so that surface, control-frontend and
+ * accounts-frontend cannot disagree about which days a figure covers — three
+ * copies of this arithmetic is how the same metric ends up with three different
+ * values depending on where a Camundi reads it.
+ */
+export interface EnterpriseTermWindow {
+    /** First day of the current period. Keeps the wall-clock time of the start date. */
+    periodStart: Date;
+    /** Last day of the current period (inclusive). */
+    periodEnd: Date;
+    /** How many full periods have elapsed since the contract started. */
+    completedPeriods: number;
+    /** First day of the next period. */
+    nextRenewal: Date;
+    /** Months elapsed at `periodStart`, i.e. the first month index of this period. */
+    startMonth: number;
+    /** Last month index of this period. */
+    endMonth: number;
+}
+/** Default contract length when the org carries no explicit duration. */
+export declare const DEFAULT_ENTERPRISE_DURATION_IN_MONTHS = 12;
+/**
+ * Add months, clamping to the end of the target month rather than rolling into
+ * the next one — `addMonthsClamped(Jan 31, 1)` is Feb 28/29, not Mar 2/3.
+ *
+ * Deliberately local-time (`getMonth`/`setMonth`), matching how contract dates
+ * are compared elsewhere; only the day-bucket comparison against HDP rows
+ * switches to UTC, via `toUtcDayStartMs`.
+ */
+export declare function addMonthsClamped(date: Date, months: number): Date;
+/** Whole months between two dates, ignoring the day of month. */
+export declare function diffInWholeMonths(start: Date, end: Date): number;
+/**
+ * The UTC day `date` falls on, as epoch millis.
+ *
+ * HDP buckets usage per UTC day (a BigQuery DATE column, so every row's ts is
+ * UTC midnight), whereas a contract bound keeps the wall-clock time it was
+ * created at. Comparing the two directly drops the term's first day whenever the
+ * plan was created after midnight, so both sides collapse to a UTC day first.
+ */
+export declare function toUtcDayStartMs(date: Date): number;
+/**
+ * Resolve the contract period that `now` falls in.
+ *
+ * `durationInMonths` falls back to 12 for anything non-positive or absent,
+ * matching what the billing surfaces already assumed. `null` is accepted as well
+ * as `undefined` because the accounts MobX model stores the field as
+ * `types.maybeNull(types.number)` while the DTO has it optional — callers
+ * shouldn't have to normalise that difference at every call site.
+ *
+ * A contract dated in the future resolves to its first period — nothing has been
+ * used before it starts, so there is no earlier window to report on.
+ */
+export declare function getCurrentEnterpriseTerm(options: {
+    startDate: Date;
+    durationInMonths?: number | null;
+    now?: Date;
+}): EnterpriseTermWindow;
+/**
+ * Peak value among the points inside `term`, or 0 when none fall in it.
+ *
+ * For a gauge like tenants the org's figure for a period is its highest daily
+ * reading, never a sum — and the reading has to come from *this* period. Both
+ * ends are inclusive and compared as UTC days, so the term's first and last day
+ * count regardless of the time of day the contract was created at.
+ */
+export declare function peakWithinTerm(points: readonly {
+    ts: number;
+    value: number;
+}[], term: Pick<EnterpriseTermWindow, 'periodStart' | 'periodEnd'>): number;

package/dist/utils/enterpriseTerm.utils.js

@@ -0,0 +1,69 @@
+const DAY_MS = 24 * 60 * 60 * 1e3;
+const DEFAULT_ENTERPRISE_DURATION_IN_MONTHS = 12;
+function addMonthsClamped(date, months) {
+  const next = new Date(date.getTime());
+  const originalDay = next.getDate();
+  next.setMonth(next.getMonth() + months);
+  if (next.getDate() !== originalDay) {
+    next.setDate(0);
+  }
+  return next;
+}
+function diffInWholeMonths(start, end) {
+  return (end.getFullYear() - start.getFullYear()) * 12 + (end.getMonth() - start.getMonth());
+}
+function toUtcDayStartMs(date) {
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+function getCurrentEnterpriseTerm(options) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const durationInMonths = typeof options.durationInMonths === "number" && options.durationInMonths > 0 ? options.durationInMonths : DEFAULT_ENTERPRISE_DURATION_IN_MONTHS;
+  let completedPeriods = Math.max(
+    0,
+    Math.floor(
+      Math.abs(diffInWholeMonths(options.startDate, now)) / durationInMonths
+    )
+  );
+  const nowDay = toUtcDayStartMs(now);
+  const periodStartDay = (periods) => toUtcDayStartMs(
+    addMonthsClamped(options.startDate, periods * durationInMonths)
+  );
+  while (completedPeriods > 0 && periodStartDay(completedPeriods) > nowDay) {
+    completedPeriods -= 1;
+  }
+  while (periodStartDay(completedPeriods + 1) <= nowDay) {
+    completedPeriods += 1;
+  }
+  const periodStart = addMonthsClamped(
+    options.startDate,
+    completedPeriods * durationInMonths
+  );
+  const nextRenewal = addMonthsClamped(periodStart, durationInMonths);
+  const periodEnd = new Date(nextRenewal.getTime() - DAY_MS);
+  const startMonth = completedPeriods * durationInMonths;
+  return {
+    periodStart,
+    periodEnd,
+    completedPeriods,
+    nextRenewal,
+    startMonth,
+    endMonth: startMonth + (durationInMonths - 1)
+  };
+}
+function peakWithinTerm(points, term) {
+  const from = toUtcDayStartMs(term.periodStart);
+  const to = toUtcDayStartMs(term.periodEnd);
+  return points.reduce(
+    (peak, point) => point.ts >= from && point.ts <= to ? Math.max(peak, point.value) : peak,
+    0
+  );
+}
+export {
+  DEFAULT_ENTERPRISE_DURATION_IN_MONTHS,
+  addMonthsClamped,
+  diffInWholeMonths,
+  getCurrentEnterpriseTerm,
+  peakWithinTerm,
+  toUtcDayStartMs
+};
+//# sourceMappingURL=enterpriseTerm.utils.js.map

package/dist/utils/enterpriseTerm.utils.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/enterpriseTerm.utils.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 enterprise contract period a usage figure belongs to.\n *\n * An enterprise contract starts at `enterpriseStartDate` and renews every\n * `enterpriseDurationInMonth` months. Usage is measured against the *current*\n * period's included quota, so anything summed or peaked over a wider window\n * bills a previous term's usage against this term's inclusions.\n *\n * Extracted from c4's billing tab so that surface, control-frontend and\n * accounts-frontend cannot disagree about which days a figure covers \u2014 three\n * copies of this arithmetic is how the same metric ends up with three different\n * values depending on where a Camundi reads it.\n */\nexport interface EnterpriseTermWindow {\n  /** First day of the current period. Keeps the wall-clock time of the start date. */\n  periodStart: Date\n  /** Last day of the current period (inclusive). */\n  periodEnd: Date\n  /** How many full periods have elapsed since the contract started. */\n  completedPeriods: number\n  /** First day of the next period. */\n  nextRenewal: Date\n  /** Months elapsed at `periodStart`, i.e. the first month index of this period. */\n  startMonth: number\n  /** Last month index of this period. */\n  endMonth: number\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000\n\n/** Default contract length when the org carries no explicit duration. */\nexport const DEFAULT_ENTERPRISE_DURATION_IN_MONTHS = 12\n\n/**\n * Add months, clamping to the end of the target month rather than rolling into\n * the next one \u2014 `addMonthsClamped(Jan 31, 1)` is Feb 28/29, not Mar 2/3.\n *\n * Deliberately local-time (`getMonth`/`setMonth`), matching how contract dates\n * are compared elsewhere; only the day-bucket comparison against HDP rows\n * switches to UTC, via `toUtcDayStartMs`.\n */\nexport function addMonthsClamped(date: Date, months: number): Date {\n  const next = new Date(date.getTime())\n  const originalDay = next.getDate()\n  next.setMonth(next.getMonth() + months)\n\n  if (next.getDate() !== originalDay) {\n    next.setDate(0)\n  }\n\n  return next\n}\n\n/** Whole months between two dates, ignoring the day of month. */\nexport function diffInWholeMonths(start: Date, end: Date): number {\n  return (\n    (end.getFullYear() - start.getFullYear()) * 12 +\n    (end.getMonth() - start.getMonth())\n  )\n}\n\n/**\n * The UTC day `date` falls on, as epoch millis.\n *\n * HDP buckets usage per UTC day (a BigQuery DATE column, so every row's ts is\n * UTC midnight), whereas a contract bound keeps the wall-clock time it was\n * created at. Comparing the two directly drops the term's first day whenever the\n * plan was created after midnight, so both sides collapse to a UTC day first.\n */\nexport function toUtcDayStartMs(date: Date): number {\n  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())\n}\n\n/**\n * Resolve the contract period that `now` falls in.\n *\n * `durationInMonths` falls back to 12 for anything non-positive or absent,\n * matching what the billing surfaces already assumed. `null` is accepted as well\n * as `undefined` because the accounts MobX model stores the field as\n * `types.maybeNull(types.number)` while the DTO has it optional \u2014 callers\n * shouldn't have to normalise that difference at every call site.\n *\n * A contract dated in the future resolves to its first period \u2014 nothing has been\n * used before it starts, so there is no earlier window to report on.\n */\nexport function getCurrentEnterpriseTerm(options: {\n  startDate: Date\n  durationInMonths?: number | null\n  now?: Date\n}): EnterpriseTermWindow {\n  const now = options.now ?? new Date()\n  const durationInMonths =\n    typeof options.durationInMonths === 'number' && options.durationInMonths > 0\n      ? options.durationInMonths\n      : DEFAULT_ENTERPRISE_DURATION_IN_MONTHS\n\n  // `diffInWholeMonths` ignores the day of month, so this is only an estimate:\n  // for a contract starting the 15th, `now` on the 1st of an anniversary month\n  // counts a full extra month and the estimate overshoots into a period that\n  // hasn't started yet. `abs` keeps a future-dated contract off a negative index.\n  let completedPeriods = Math.max(\n    0,\n    Math.floor(\n      Math.abs(diffInWholeMonths(options.startDate, now)) / durationInMonths,\n    ),\n  )\n\n  // Correct the estimate against the real dates until `now` actually sits in the\n  // period. Compared as UTC days so the renewal day belongs to the new period\n  // rather than to neither \u2014 the same day granularity `peakWithinTerm` uses.\n  // Both loops are bounded: the day-of-month error is under one month, so the\n  // estimate is at most one period out either way.\n  const nowDay = toUtcDayStartMs(now)\n  const periodStartDay = (periods: number): number =>\n    toUtcDayStartMs(\n      addMonthsClamped(options.startDate, periods * durationInMonths),\n    )\n\n  while (completedPeriods > 0 && periodStartDay(completedPeriods) > nowDay) {\n    completedPeriods -= 1\n  }\n  while (periodStartDay(completedPeriods + 1) <= nowDay) {\n    completedPeriods += 1\n  }\n\n  const periodStart = addMonthsClamped(\n    options.startDate,\n    completedPeriods * durationInMonths,\n  )\n  const nextRenewal = addMonthsClamped(periodStart, durationInMonths)\n  const periodEnd = new Date(nextRenewal.getTime() - DAY_MS)\n  const startMonth = completedPeriods * durationInMonths\n\n  return {\n    periodStart,\n    periodEnd,\n    completedPeriods,\n    nextRenewal,\n    startMonth,\n    endMonth: startMonth + (durationInMonths - 1),\n  }\n}\n\n/**\n * Peak value among the points inside `term`, or 0 when none fall in it.\n *\n * For a gauge like tenants the org's figure for a period is its highest daily\n * reading, never a sum \u2014 and the reading has to come from *this* period. Both\n * ends are inclusive and compared as UTC days, so the term's first and last day\n * count regardless of the time of day the contract was created at.\n */\nexport function peakWithinTerm(\n  points: readonly { ts: number; value: number }[],\n  term: Pick<EnterpriseTermWindow, 'periodStart' | 'periodEnd'>,\n): number {\n  const from = toUtcDayStartMs(term.periodStart)\n  const to = toUtcDayStartMs(term.periodEnd)\n\n  return points.reduce(\n    (peak, point) =>\n      point.ts >= from && point.ts <= to ? Math.max(peak, point.value) : peak,\n    0,\n  )\n}\n"],
+  "mappings": "AAkCA,MAAM,SAAS,KAAK,KAAK,KAAK;AAGvB,MAAM,wCAAwC;AAU9C,SAAS,iBAAiB,MAAY,QAAsB;AACjE,QAAM,OAAO,IAAI,KAAK,KAAK,QAAQ,CAAC;AACpC,QAAM,cAAc,KAAK,QAAQ;AACjC,OAAK,SAAS,KAAK,SAAS,IAAI,MAAM;AAEtC,MAAI,KAAK,QAAQ,MAAM,aAAa;AAClC,SAAK,QAAQ,CAAC;AAAA,EAChB;AAEA,SAAO;AACT;AAGO,SAAS,kBAAkB,OAAa,KAAmB;AAChE,UACG,IAAI,YAAY,IAAI,MAAM,YAAY,KAAK,MAC3C,IAAI,SAAS,IAAI,MAAM,SAAS;AAErC;AAUO,SAAS,gBAAgB,MAAoB;AAClD,SAAO,KAAK,IAAI,KAAK,eAAe,GAAG,KAAK,YAAY,GAAG,KAAK,WAAW,CAAC;AAC9E;AAcO,SAAS,yBAAyB,SAIhB;AACvB,QAAM,MAAM,QAAQ,OAAO,oBAAI,KAAK;AACpC,QAAM,mBACJ,OAAO,QAAQ,qBAAqB,YAAY,QAAQ,mBAAmB,IACvE,QAAQ,mBACR;AAMN,MAAI,mBAAmB,KAAK;AAAA,IAC1B;AAAA,IACA,KAAK;AAAA,MACH,KAAK,IAAI,kBAAkB,QAAQ,WAAW,GAAG,CAAC,IAAI;AAAA,IACxD;AAAA,EACF;AAOA,QAAM,SAAS,gBAAgB,GAAG;AAClC,QAAM,iBAAiB,CAAC,YACtB;AAAA,IACE,iBAAiB,QAAQ,WAAW,UAAU,gBAAgB;AAAA,EAChE;AAEF,SAAO,mBAAmB,KAAK,eAAe,gBAAgB,IAAI,QAAQ;AACxE,wBAAoB;AAAA,EACtB;AACA,SAAO,eAAe,mBAAmB,CAAC,KAAK,QAAQ;AACrD,wBAAoB;AAAA,EACtB;AAEA,QAAM,cAAc;AAAA,IAClB,QAAQ;AAAA,IACR,mBAAmB;AAAA,EACrB;AACA,QAAM,cAAc,iBAAiB,aAAa,gBAAgB;AAClE,QAAM,YAAY,IAAI,KAAK,YAAY,QAAQ,IAAI,MAAM;AACzD,QAAM,aAAa,mBAAmB;AAEtC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,UAAU,cAAc,mBAAmB;AAAA,EAC7C;AACF;AAUO,SAAS,eACd,QACA,MACQ;AACR,QAAM,OAAO,gBAAgB,KAAK,WAAW;AAC7C,QAAM,KAAK,gBAAgB,KAAK,SAAS;AAEzC,SAAO,OAAO;AAAA,IACZ,CAAC,MAAM,UACL,MAAM,MAAM,QAAQ,MAAM,MAAM,KAAK,KAAK,IAAI,MAAM,MAAM,KAAK,IAAI;AAAA,IACrE;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/utils/enterpriseTerm.utils.spec.d.ts

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

package/dist/utils/failoverKeyPolicy.utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The three IAM principals that need access to a BYOK cluster's KMS keys after
+ * a failover. All three live in the failover region's account — the same
+ * account as the failover cluster's own role.
+ */
+export interface FailoverKeyPolicyPrincipals {
+    /** Reads the source cluster's secondary bucket during the BucketClone. */
+    cloneRole: string;
+    /** The failover cluster's own access to its new primary bucket. */
+    clusterRole: string;
+    /** Replicates the new primary bucket back out to its secondary. */
+    replicationRole: string;
+}
+/**
+ * Derive the three principals a customer must add to both KMS key policies
+ * after a failover, from the failover cluster's own role ARN and the stableId
+ * carried over from its source.
+ *
+ * The clone role is pre-staged as `clone-backup-<stableId>`, and the
+ * replication role is the cluster role with a `-replication` suffix — so the
+ * account parsed out of the cluster role ARN is all that is needed.
+ *
+ * Returns `undefined` when either input is missing or the role ARN is not in
+ * the expected shape, so callers render nothing rather than a wrong ARN.
+ */
+export declare function deriveFailoverKeyPolicyPrincipals(clusterRoleArn: string | undefined, stableId: string | undefined): FailoverKeyPolicyPrincipals | undefined;

package/dist/utils/failoverKeyPolicy.utils.js

@@ -0,0 +1,15 @@
+const CLUSTER_ROLE_ARN = /^arn:aws:iam::(?<account>\d{12}):role\/c8-cluster\/c8-apps-(?<uuid>[0-9a-f-]{36})$/u;
+function deriveFailoverKeyPolicyPrincipals(clusterRoleArn, stableId) {
+  if (!clusterRoleArn || !stableId) return void 0;
+  const account = CLUSTER_ROLE_ARN.exec(clusterRoleArn)?.groups?.account;
+  if (!account) return void 0;
+  return {
+    cloneRole: `arn:aws:iam::${account}:role/c8-cluster/clone-backup-${stableId}`,
+    clusterRole: clusterRoleArn,
+    replicationRole: `${clusterRoleArn}-replication`
+  };
+}
+export {
+  deriveFailoverKeyPolicyPrincipals
+};
+//# sourceMappingURL=failoverKeyPolicy.utils.js.map

package/dist/utils/failoverKeyPolicy.utils.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/failoverKeyPolicy.utils.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 cluster's own IAM role ARN, surfaced by the operator on the ZeebeCluster\n * `status.accountId` field (the name is historical \u2014 the value is a role ARN,\n * not a bare account id):\n *\n *   arn:aws:iam::<account>:role/c8-cluster/c8-apps-<clusterUuid>\n */\nconst CLUSTER_ROLE_ARN =\n  /^arn:aws:iam::(?<account>\\d{12}):role\\/c8-cluster\\/c8-apps-(?<uuid>[0-9a-f-]{36})$/u\n\n/**\n * The three IAM principals that need access to a BYOK cluster's KMS keys after\n * a failover. All three live in the failover region's account \u2014 the same\n * account as the failover cluster's own role.\n */\nexport interface FailoverKeyPolicyPrincipals {\n  /** Reads the source cluster's secondary bucket during the BucketClone. */\n  cloneRole: string\n  /** The failover cluster's own access to its new primary bucket. */\n  clusterRole: string\n  /** Replicates the new primary bucket back out to its secondary. */\n  replicationRole: string\n}\n\n/**\n * Derive the three principals a customer must add to both KMS key policies\n * after a failover, from the failover cluster's own role ARN and the stableId\n * carried over from its source.\n *\n * The clone role is pre-staged as `clone-backup-<stableId>`, and the\n * replication role is the cluster role with a `-replication` suffix \u2014 so the\n * account parsed out of the cluster role ARN is all that is needed.\n *\n * Returns `undefined` when either input is missing or the role ARN is not in\n * the expected shape, so callers render nothing rather than a wrong ARN.\n */\nexport function deriveFailoverKeyPolicyPrincipals(\n  clusterRoleArn: string | undefined,\n  stableId: string | undefined,\n): FailoverKeyPolicyPrincipals | undefined {\n  if (!clusterRoleArn || !stableId) return undefined\n\n  const account = CLUSTER_ROLE_ARN.exec(clusterRoleArn)?.groups?.account\n  if (!account) return undefined\n\n  return {\n    cloneRole: `arn:aws:iam::${account}:role/c8-cluster/clone-backup-${stableId}`,\n    clusterRole: clusterRoleArn,\n    replicationRole: `${clusterRoleArn}-replication`,\n  }\n}\n"],
+  "mappings": "AAaA,MAAM,mBACJ;AA4BK,SAAS,kCACd,gBACA,UACyC;AACzC,MAAI,CAAC,kBAAkB,CAAC,SAAU,QAAO;AAEzC,QAAM,UAAU,iBAAiB,KAAK,cAAc,GAAG,QAAQ;AAC/D,MAAI,CAAC,QAAS,QAAO;AAErB,SAAO;AAAA,IACL,WAAW,gBAAgB,OAAO,iCAAiC,QAAQ;AAAA,IAC3E,aAAa;AAAA,IACb,iBAAiB,GAAG,cAAc;AAAA,EACpC;AACF;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camunda/ccma-shared-types",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Shared TypeScript types for Camunda Cloud Management Apps",
   "bugs": {
     "url": "https://github.com/camunda/camunda-cloud-management-apps/issues"
@@ -23,7 +23,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "semver": "7.8.4"
+    "semver": "7.8.5"
   },
   "scripts": {
     "build": "node esbuild.mjs && tsc --emitDeclarationOnly --outDir dist",