@letpeoplework/lighthouse-client 1.6.0 → 1.8.0

package/dist/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   pollCliAuthSession: () => pollCliAuthSession,
   queryServerAuthMode: () => queryServerAuthMode,
   startCliAuthSession: () => startCliAuthSession,
+  summariseDeliveryMetricsHistory: () => summariseDeliveryMetricsHistory,
   validateLighthouseConnectivity: () => validateLighthouseConnectivity
 });
 module.exports = __toCommonJS(index_exports);
@@ -531,6 +532,15 @@ var getDefaultMetricsDateRange = () => {
     endDate: toIsoDate(end)
   };
 };
+var summariseDeliveryMetricsHistory = (history) => history.points.map((point) => ({
+  date: point.date,
+  totalWork: point.totalWork,
+  doneWork: point.doneWork,
+  remainingWork: point.remainingWork,
+  epicCount: point.featureBreakdown.length,
+  estimatedItemCount: point.estimatedItemCount,
+  likelihoodPercentage: point.likelihoodPercentage
+}));
 var getAuthHeaders = (auth) => {
   if (auth === void 0 || auth.kind === "none") {
     return {};
@@ -734,6 +744,12 @@ var getMetricsAsOfDateQuery = (asOfDate) => `asOfDate=${encodeURIComponent(asOfD
 var getItemIdsQuerySuffix = (itemIds) => itemIds && itemIds.length > 0 ? itemIds.map((id) => `&itemIds=${encodeURIComponent(id)}`).join("") : "";
 var getViewQuerySuffix = (view) => view === "filtered" ? "&view=filtered" : "";
 var getDefinitionIdQuerySuffix = (definitionId) => definitionId !== void 0 ? `&definitionId=${encodeURIComponent(definitionId)}` : "";
+var getPercentilesOverTimeQuerySuffix = (metricType, horizon) => {
+  const metricTypePart = metricType === void 0 ? "" : `&metricType=${encodeURIComponent(metricType)}`;
+  const horizonPart = horizon === void 0 ? "" : `&horizon=${encodeURIComponent(horizon)}`;
+  return `${metricTypePart}${horizonPart}`;
+};
+var getProcessBehaviorTypeQuerySuffix = (metricType) => metricType === void 0 ? "" : `&type=${encodeURIComponent(metricType)}`;
 var addUtcDays = (dateStr, days) => {
   const d = /* @__PURE__ */ new Date(`${dateStr}T00:00:00Z`);
   d.setUTCDate(d.getUTCDate() + days);
@@ -788,7 +804,12 @@ var FEATURE_REQUIRES_SERVER_NEWER_THAN = {
   recurringBlackoutRules: "v26.5.29.5",
   workItemAgePercentiles: "v26.6.7.1",
   mcpOAuthPassThrough: "v26.6.16.14",
-  blockedCountHistory: "v26.7.3.1"
+  blockedCountHistory: "v26.7.3.1",
+  percentilesOverTime: "v26.7.11.4",
+  processBehaviorOverTime: "v26.7.11.4",
+  // The endpoint landed in v26.6.7.1. The per-epic size fields came much later and are optional on
+  // the wire, so a server between the two answers fine — it just reports no sizes.
+  deliveryMetricsHistory: "v26.5.29.5"
 };
 var parseServerVersion = (raw) => {
   const trimmed = raw.trim().replace(/^v/iu, "");
@@ -1258,6 +1279,58 @@ var createLighthouseClient = (configuration, dependencies = {}) => {
         { method: "GET" }
       );
     },
+    getTeamPercentilesOverTime: async (teamId, range, metricType, horizon) => {
+      const unsupported = await ensureServerSupports("percentilesOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/teams/${teamId}/metrics/percentiles-over-time?${getMetricsDateRangeQuery(r)}${getPercentilesOverTimeQuerySuffix(metricType, horizon)}`,
+        { method: "GET" }
+      );
+    },
+    getPortfolioPercentilesOverTime: async (portfolioId, range, metricType, horizon) => {
+      const unsupported = await ensureServerSupports("percentilesOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/portfolios/${portfolioId}/metrics/percentiles-over-time?${getMetricsDateRangeQuery(r)}${getPercentilesOverTimeQuerySuffix(metricType, horizon)}`,
+        { method: "GET" }
+      );
+    },
+    getTeamProcessBehaviorOverTime: async (teamId, range, metricType) => {
+      const unsupported = await ensureServerSupports("processBehaviorOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/teams/${teamId}/metrics/process-behavior-over-time?${getMetricsDateRangeQuery(r)}${getProcessBehaviorTypeQuerySuffix(metricType)}`,
+        { method: "GET" }
+      );
+    },
+    getPortfolioProcessBehaviorOverTime: async (portfolioId, range, metricType) => {
+      const unsupported = await ensureServerSupports("processBehaviorOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/portfolios/${portfolioId}/metrics/process-behavior-over-time?${getMetricsDateRangeQuery(r)}${getProcessBehaviorTypeQuerySuffix(metricType)}`,
+        { method: "GET" }
+      );
+    },
     getTeamCumulativeStateTime: async (teamId, range, itemIds) => {
       const unsupported = await ensureServerSupports("cumulativeStateTime");
       if (unsupported) {
@@ -1384,6 +1457,18 @@ var createLighthouseClient = (configuration, dependencies = {}) => {
       `/v1/deliveries/${deliveryId}`,
       { method: "DELETE" }
     ),
+    getDeliveryMetricsHistory: async (deliveryId) => {
+      const unsupported = await ensureServerSupports("deliveryMetricsHistory");
+      if (unsupported) {
+        return unsupported;
+      }
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/deliveries/${deliveryId}/metrics-history`,
+        { method: "GET" }
+      );
+    },
     getRecurringBlackoutRules: async () => {
       const unsupported = await ensureServerSupports("recurringBlackoutRules");
       if (unsupported) {
@@ -1460,5 +1545,6 @@ var createLighthouseClient = (configuration, dependencies = {}) => {
   pollCliAuthSession,
   queryServerAuthMode,
   startCliAuthSession,
+  summariseDeliveryMetricsHistory,
   validateLighthouseConnectivity
 });

package/dist/index.d.cts

@@ -233,6 +233,125 @@ type BlockedCountSnapshot = {
     readonly recordedAt: string;
     readonly blockedCount: number;
 };
+/**
+ * One epic as it stood on the day a delivery snapshot was taken.
+ *
+ * `likelihood` is null when the epic cannot be forecast (ADR-112). `totalItems` and
+ * `isUsingDefaultSize` are absent from every snapshot recorded before Lighthouse began writing
+ * sizes, so both are optional and a missing value means "not recorded", never zero.
+ */
+type DeliveryFeatureMetric = {
+    readonly referenceId: string;
+    readonly name: string;
+    readonly completion: number;
+    readonly likelihood: number | null;
+    readonly totalItems?: number | null;
+    readonly isUsingDefaultSize?: boolean | null;
+};
+/** One point on a delivery's forecast distribution: the chance of finishing by a date. */
+type DeliveryWhenDistributionPoint = {
+    readonly probability: number;
+    readonly expectedDate: string;
+};
+/** A delivery as it stood on one recorded day. Dates are ISO strings. */
+type DeliveryMetricsHistoryPoint = {
+    readonly date: string;
+    readonly targetDateAtSnapshot: string | null;
+    readonly totalWork: number;
+    readonly doneWork: number;
+    readonly remainingWork: number;
+    readonly estimatedItemCount: number | null;
+    readonly forecastHowMany: number | null;
+    readonly likelihoodPercentage: number | null;
+    readonly whenDistribution: readonly DeliveryWhenDistributionPoint[] | null;
+    readonly featureBreakdown: readonly DeliveryFeatureMetric[];
+};
+/** The whole recorded trend for one delivery. Forward-only: it starts at the first snapshot. */
+type DeliveryMetricsHistory = {
+    readonly deliveryDate: string;
+    readonly firstSnapshotDate: string | null;
+    readonly points: readonly DeliveryMetricsHistoryPoint[];
+};
+/**
+ * One day of a delivery, without the per-epic breakdown or the forecast distribution.
+ *
+ * A ninety-day window over fifteen epics is well over a thousand breakdown objects plus a
+ * distribution per day — more than an assistant should be handed by default (ADR-121), and more
+ * than a terminal can show. {@link summariseDeliveryMetricsHistory} projects to this.
+ */
+type DeliveryMetricsHistorySummaryRow = {
+    readonly date: string;
+    readonly totalWork: number;
+    readonly doneWork: number;
+    readonly remainingWork: number;
+    readonly epicCount: number;
+    readonly estimatedItemCount: number | null;
+    readonly likelihoodPercentage: number | null;
+};
+/**
+ * Projects a delivery history to one row per recorded day. Pure.
+ *
+ * The client itself returns the payload whole: dropping data is the caller's choice, so the CLI and
+ * the MCP tool apply this by default and step around it when asked for per-epic detail.
+ */
+declare const summariseDeliveryMetricsHistory: (history: DeliveryMetricsHistory) => readonly DeliveryMetricsHistorySummaryRow[];
+/**
+ * Percentile family recorded by the percentiles-over-time pipeline. Sent as the
+ * `metricType` query parameter, and echoed back on every returned row.
+ */
+type PercentilesOverTimeMetricType = "CycleTime" | "WorkItemAge";
+/**
+ * One captured day on the percentiles-over-time trend: the percentile quartet
+ * recorded for {@link recordedAt} (an ISO date string, one row per calendar day,
+ * ascending).
+ *
+ * Recording is FORWARD-ONLY — Lighthouse starts capturing the day the feature is
+ * first deployed and never backfills history it did not observe, so a freshly
+ * upgraded server legitimately returns an empty array until the first refresh.
+ *
+ * `CycleTime` is recorded per horizon (30/60/90 days); `WorkItemAge` is always
+ * "as of today" and therefore has no horizon dimension, so a horizon sent
+ * alongside it is ignored in favour of the horizon-less series.
+ *
+ * SHARP EDGE: a `CycleTime` request that omits `horizon` is not filtered to one
+ * horizon — it returns every recorded horizon interleaved, and because this row
+ * shape carries no horizon field they cannot be told apart. Pass an explicit
+ * horizon whenever you ask for `CycleTime`.
+ */
+type PercentilesOverTimeSnapshot = {
+    readonly recordedAt: string;
+    readonly metricType: PercentilesOverTimeMetricType;
+    readonly p50: number;
+    readonly p70: number;
+    readonly p85: number;
+    readonly p95: number;
+};
+/**
+ * Process-behaviour family recorded by the natural-process-limits over-time
+ * pipeline. Sent as the `type` query parameter.
+ *
+ * `FeatureSize` is PORTFOLIO-ONLY: it has no team-level equivalent, so a team
+ * never records it. The server answers a team asking for it with an empty
+ * series rather than an error.
+ */
+type ProcessBehaviorMetricType = "Throughput" | "WorkItemAge" | "Wip" | "CycleTime" | "Arrivals" | "FeatureSize";
+/**
+ * One captured day on the process-behaviour-over-time trend: the natural process
+ * limit triple recorded for {@link recordedAt} (an ISO date string, one row per
+ * calendar day, ascending). The family is carried by the request's `type`
+ * parameter, not repeated per row.
+ *
+ * Recording is FORWARD-ONLY, and a day is only recorded when the underlying
+ * chart had a usable baseline — days where it did not are absent from the
+ * series rather than present as a zeroed triple, so an empty array means
+ * "nothing recorded yet", never "a process pinned at zero".
+ */
+type ProcessBehaviorSnapshot = {
+    readonly recordedAt: string;
+    readonly unpl: number;
+    readonly average: number;
+    readonly lnpl: number;
+};
 type CumulativeStateTimeStateRow = {
     readonly state: string;
     readonly workflowOrder: number;
@@ -334,6 +453,10 @@ type LighthouseClient = {
     readonly getPortfolioTotalWorkItemAgeOverTime: (portfolioId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<TotalWorkItemAgeOverTimeResult>>;
     readonly getTeamBlockedCountHistory: (teamId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<readonly BlockedCountSnapshot[]>>;
     readonly getPortfolioBlockedCountHistory: (portfolioId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<readonly BlockedCountSnapshot[]>>;
+    readonly getTeamPercentilesOverTime: (teamId: number, range?: MetricsDateRange, metricType?: PercentilesOverTimeMetricType, horizon?: number) => Promise<LighthouseApiResult<readonly PercentilesOverTimeSnapshot[]>>;
+    readonly getPortfolioPercentilesOverTime: (portfolioId: number, range?: MetricsDateRange, metricType?: PercentilesOverTimeMetricType, horizon?: number) => Promise<LighthouseApiResult<readonly PercentilesOverTimeSnapshot[]>>;
+    readonly getTeamProcessBehaviorOverTime: (teamId: number, range?: MetricsDateRange, metricType?: ProcessBehaviorMetricType) => Promise<LighthouseApiResult<readonly ProcessBehaviorSnapshot[]>>;
+    readonly getPortfolioProcessBehaviorOverTime: (portfolioId: number, range?: MetricsDateRange, metricType?: ProcessBehaviorMetricType) => Promise<LighthouseApiResult<readonly ProcessBehaviorSnapshot[]>>;
     readonly getTeamCumulativeStateTime: (teamId: number, range?: MetricsDateRange, itemIds?: readonly number[]) => Promise<LighthouseApiResult<CumulativeStateTimeResult>>;
     readonly getTeamCumulativeStateTimeItems: (teamId: number, state: string, range?: MetricsDateRange, itemIds?: readonly number[]) => Promise<LighthouseApiResult<CumulativeStateTimeItemsResult>>;
     readonly getTeamCumulativeStateTimeCandidates: (teamId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<CumulativeStateTimeCandidatesResult>>;
@@ -347,6 +470,7 @@ type LighthouseClient = {
     readonly createDelivery: (portfolioId: number, payload: LighthouseWritePayload) => Promise<LighthouseApiResult<unknown>>;
     readonly updateDelivery: (deliveryId: number, payload: LighthouseWritePayload) => Promise<LighthouseApiResult<unknown>>;
     readonly deleteDelivery: (deliveryId: number) => Promise<LighthouseApiResult<undefined>>;
+    readonly getDeliveryMetricsHistory: (deliveryId: number) => Promise<LighthouseApiResult<DeliveryMetricsHistory>>;
     readonly getRecurringBlackoutRules: () => Promise<LighthouseApiResult<readonly RecurringBlackoutRule[]>>;
     readonly createRecurringBlackoutRule: (payload: LighthouseWritePayload) => Promise<LighthouseApiResult<RecurringBlackoutRule>>;
     readonly updateRecurringBlackoutRule: (id: number, payload: LighthouseWritePayload) => Promise<LighthouseApiResult<RecurringBlackoutRule>>;
@@ -371,6 +495,9 @@ declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
     readonly workItemAgePercentiles: "v26.6.7.1";
     readonly mcpOAuthPassThrough: "v26.6.16.14";
     readonly blockedCountHistory: "v26.7.3.1";
+    readonly percentilesOverTime: "v26.7.11.4";
+    readonly processBehaviorOverTime: "v26.7.11.4";
+    readonly deliveryMetricsHistory: "v26.5.29.5";
 };
 /**
  * Returns true when `candidate` is strictly newer than `baseline`, false when
@@ -380,4 +507,4 @@ declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
 declare const isServerVersionNewerThan: (candidate: string, baseline: string) => boolean | null;
 declare const createLighthouseClient: (configuration: LighthouseClientConfiguration, dependencies?: LighthouseClientDependencies) => LighthouseClient;
 
-export { type BacktestInput, type BlockedCountSnapshot, type CliAuthSessionPollResult, type CliAuthSessionStartError, type CliAuthSessionStartOutcome, type CliAuthSessionStartResult, type CliConnection, type CliServerAuthMode, type CliServerConnection, type CliStandaloneConnection, type ClientCapability, type ClientPackageContract, type ConnectivityCategory, type ConnectivityDependencies, type ConnectivityFetchResponse, type ConnectivityValidationResult, type CumulativeStateTimeCandidateRow, type CumulativeStateTimeCandidatesResult, type CumulativeStateTimeItemRow, type CumulativeStateTimeItemsResult, type CumulativeStateTimeResult, type CumulativeStateTimeStateRow, type DailyTotalWorkItemAge, type DailyWorkItemAge, type DayOfWeek, FEATURE_REQUIRES_SERVER_NEWER_THAN, type LighthouseApiError, type LighthouseApiResult, type LighthouseAuthContext, type LighthouseAuthOverrides, type LighthouseAuthStatus, type LighthouseAuthStore, type LighthouseClient, type LighthouseClientAuth, type LighthouseClientConfiguration, type LighthouseClientDependencies, type LighthouseConnectionConfiguration, type LighthouseWritePayload, type ManualForecastInput, type MetricsDateRange, type RecurringBlackoutRule, type RecurringBlackoutRuleInput, type ResolvedLighthouseEndpoint, type ServerAuthModeResult, type StandaloneDiscoveryContract, type StandaloneDiscoveryContractParseResult, type StoredLighthouseAuth, type ThroughputFilterView, type TotalWorkItemAgeOverTimeResult, type WorkItemAgeEntry, type WorkItemAgeOverTimeResult, createLighthouseAuthContext, createLighthouseClient, getClientPackageContract, getDefaultMetricsDateRange, getStandaloneDiscoveryLockfilePath, isServerVersionNewerThan, loadStandaloneDiscoveryContract, parseStandaloneDiscoveryContract, pollCliAuthSession, queryServerAuthMode, startCliAuthSession, validateLighthouseConnectivity };
+export { type BacktestInput, type BlockedCountSnapshot, type CliAuthSessionPollResult, type CliAuthSessionStartError, type CliAuthSessionStartOutcome, type CliAuthSessionStartResult, type CliConnection, type CliServerAuthMode, type CliServerConnection, type CliStandaloneConnection, type ClientCapability, type ClientPackageContract, type ConnectivityCategory, type ConnectivityDependencies, type ConnectivityFetchResponse, type ConnectivityValidationResult, type CumulativeStateTimeCandidateRow, type CumulativeStateTimeCandidatesResult, type CumulativeStateTimeItemRow, type CumulativeStateTimeItemsResult, type CumulativeStateTimeResult, type CumulativeStateTimeStateRow, type DailyTotalWorkItemAge, type DailyWorkItemAge, type DayOfWeek, type DeliveryFeatureMetric, type DeliveryMetricsHistory, type DeliveryMetricsHistoryPoint, type DeliveryMetricsHistorySummaryRow, type DeliveryWhenDistributionPoint, FEATURE_REQUIRES_SERVER_NEWER_THAN, type LighthouseApiError, type LighthouseApiResult, type LighthouseAuthContext, type LighthouseAuthOverrides, type LighthouseAuthStatus, type LighthouseAuthStore, type LighthouseClient, type LighthouseClientAuth, type LighthouseClientConfiguration, type LighthouseClientDependencies, type LighthouseConnectionConfiguration, type LighthouseWritePayload, type ManualForecastInput, type MetricsDateRange, type PercentilesOverTimeMetricType, type PercentilesOverTimeSnapshot, type ProcessBehaviorMetricType, type ProcessBehaviorSnapshot, type RecurringBlackoutRule, type RecurringBlackoutRuleInput, type ResolvedLighthouseEndpoint, type ServerAuthModeResult, type StandaloneDiscoveryContract, type StandaloneDiscoveryContractParseResult, type StoredLighthouseAuth, type ThroughputFilterView, type TotalWorkItemAgeOverTimeResult, type WorkItemAgeEntry, type WorkItemAgeOverTimeResult, createLighthouseAuthContext, createLighthouseClient, getClientPackageContract, getDefaultMetricsDateRange, getStandaloneDiscoveryLockfilePath, isServerVersionNewerThan, loadStandaloneDiscoveryContract, parseStandaloneDiscoveryContract, pollCliAuthSession, queryServerAuthMode, startCliAuthSession, summariseDeliveryMetricsHistory, validateLighthouseConnectivity };

package/dist/index.d.ts

@@ -233,6 +233,125 @@ type BlockedCountSnapshot = {
     readonly recordedAt: string;
     readonly blockedCount: number;
 };
+/**
+ * One epic as it stood on the day a delivery snapshot was taken.
+ *
+ * `likelihood` is null when the epic cannot be forecast (ADR-112). `totalItems` and
+ * `isUsingDefaultSize` are absent from every snapshot recorded before Lighthouse began writing
+ * sizes, so both are optional and a missing value means "not recorded", never zero.
+ */
+type DeliveryFeatureMetric = {
+    readonly referenceId: string;
+    readonly name: string;
+    readonly completion: number;
+    readonly likelihood: number | null;
+    readonly totalItems?: number | null;
+    readonly isUsingDefaultSize?: boolean | null;
+};
+/** One point on a delivery's forecast distribution: the chance of finishing by a date. */
+type DeliveryWhenDistributionPoint = {
+    readonly probability: number;
+    readonly expectedDate: string;
+};
+/** A delivery as it stood on one recorded day. Dates are ISO strings. */
+type DeliveryMetricsHistoryPoint = {
+    readonly date: string;
+    readonly targetDateAtSnapshot: string | null;
+    readonly totalWork: number;
+    readonly doneWork: number;
+    readonly remainingWork: number;
+    readonly estimatedItemCount: number | null;
+    readonly forecastHowMany: number | null;
+    readonly likelihoodPercentage: number | null;
+    readonly whenDistribution: readonly DeliveryWhenDistributionPoint[] | null;
+    readonly featureBreakdown: readonly DeliveryFeatureMetric[];
+};
+/** The whole recorded trend for one delivery. Forward-only: it starts at the first snapshot. */
+type DeliveryMetricsHistory = {
+    readonly deliveryDate: string;
+    readonly firstSnapshotDate: string | null;
+    readonly points: readonly DeliveryMetricsHistoryPoint[];
+};
+/**
+ * One day of a delivery, without the per-epic breakdown or the forecast distribution.
+ *
+ * A ninety-day window over fifteen epics is well over a thousand breakdown objects plus a
+ * distribution per day — more than an assistant should be handed by default (ADR-121), and more
+ * than a terminal can show. {@link summariseDeliveryMetricsHistory} projects to this.
+ */
+type DeliveryMetricsHistorySummaryRow = {
+    readonly date: string;
+    readonly totalWork: number;
+    readonly doneWork: number;
+    readonly remainingWork: number;
+    readonly epicCount: number;
+    readonly estimatedItemCount: number | null;
+    readonly likelihoodPercentage: number | null;
+};
+/**
+ * Projects a delivery history to one row per recorded day. Pure.
+ *
+ * The client itself returns the payload whole: dropping data is the caller's choice, so the CLI and
+ * the MCP tool apply this by default and step around it when asked for per-epic detail.
+ */
+declare const summariseDeliveryMetricsHistory: (history: DeliveryMetricsHistory) => readonly DeliveryMetricsHistorySummaryRow[];
+/**
+ * Percentile family recorded by the percentiles-over-time pipeline. Sent as the
+ * `metricType` query parameter, and echoed back on every returned row.
+ */
+type PercentilesOverTimeMetricType = "CycleTime" | "WorkItemAge";
+/**
+ * One captured day on the percentiles-over-time trend: the percentile quartet
+ * recorded for {@link recordedAt} (an ISO date string, one row per calendar day,
+ * ascending).
+ *
+ * Recording is FORWARD-ONLY — Lighthouse starts capturing the day the feature is
+ * first deployed and never backfills history it did not observe, so a freshly
+ * upgraded server legitimately returns an empty array until the first refresh.
+ *
+ * `CycleTime` is recorded per horizon (30/60/90 days); `WorkItemAge` is always
+ * "as of today" and therefore has no horizon dimension, so a horizon sent
+ * alongside it is ignored in favour of the horizon-less series.
+ *
+ * SHARP EDGE: a `CycleTime` request that omits `horizon` is not filtered to one
+ * horizon — it returns every recorded horizon interleaved, and because this row
+ * shape carries no horizon field they cannot be told apart. Pass an explicit
+ * horizon whenever you ask for `CycleTime`.
+ */
+type PercentilesOverTimeSnapshot = {
+    readonly recordedAt: string;
+    readonly metricType: PercentilesOverTimeMetricType;
+    readonly p50: number;
+    readonly p70: number;
+    readonly p85: number;
+    readonly p95: number;
+};
+/**
+ * Process-behaviour family recorded by the natural-process-limits over-time
+ * pipeline. Sent as the `type` query parameter.
+ *
+ * `FeatureSize` is PORTFOLIO-ONLY: it has no team-level equivalent, so a team
+ * never records it. The server answers a team asking for it with an empty
+ * series rather than an error.
+ */
+type ProcessBehaviorMetricType = "Throughput" | "WorkItemAge" | "Wip" | "CycleTime" | "Arrivals" | "FeatureSize";
+/**
+ * One captured day on the process-behaviour-over-time trend: the natural process
+ * limit triple recorded for {@link recordedAt} (an ISO date string, one row per
+ * calendar day, ascending). The family is carried by the request's `type`
+ * parameter, not repeated per row.
+ *
+ * Recording is FORWARD-ONLY, and a day is only recorded when the underlying
+ * chart had a usable baseline — days where it did not are absent from the
+ * series rather than present as a zeroed triple, so an empty array means
+ * "nothing recorded yet", never "a process pinned at zero".
+ */
+type ProcessBehaviorSnapshot = {
+    readonly recordedAt: string;
+    readonly unpl: number;
+    readonly average: number;
+    readonly lnpl: number;
+};
 type CumulativeStateTimeStateRow = {
     readonly state: string;
     readonly workflowOrder: number;
@@ -334,6 +453,10 @@ type LighthouseClient = {
     readonly getPortfolioTotalWorkItemAgeOverTime: (portfolioId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<TotalWorkItemAgeOverTimeResult>>;
     readonly getTeamBlockedCountHistory: (teamId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<readonly BlockedCountSnapshot[]>>;
     readonly getPortfolioBlockedCountHistory: (portfolioId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<readonly BlockedCountSnapshot[]>>;
+    readonly getTeamPercentilesOverTime: (teamId: number, range?: MetricsDateRange, metricType?: PercentilesOverTimeMetricType, horizon?: number) => Promise<LighthouseApiResult<readonly PercentilesOverTimeSnapshot[]>>;
+    readonly getPortfolioPercentilesOverTime: (portfolioId: number, range?: MetricsDateRange, metricType?: PercentilesOverTimeMetricType, horizon?: number) => Promise<LighthouseApiResult<readonly PercentilesOverTimeSnapshot[]>>;
+    readonly getTeamProcessBehaviorOverTime: (teamId: number, range?: MetricsDateRange, metricType?: ProcessBehaviorMetricType) => Promise<LighthouseApiResult<readonly ProcessBehaviorSnapshot[]>>;
+    readonly getPortfolioProcessBehaviorOverTime: (portfolioId: number, range?: MetricsDateRange, metricType?: ProcessBehaviorMetricType) => Promise<LighthouseApiResult<readonly ProcessBehaviorSnapshot[]>>;
     readonly getTeamCumulativeStateTime: (teamId: number, range?: MetricsDateRange, itemIds?: readonly number[]) => Promise<LighthouseApiResult<CumulativeStateTimeResult>>;
     readonly getTeamCumulativeStateTimeItems: (teamId: number, state: string, range?: MetricsDateRange, itemIds?: readonly number[]) => Promise<LighthouseApiResult<CumulativeStateTimeItemsResult>>;
     readonly getTeamCumulativeStateTimeCandidates: (teamId: number, range?: MetricsDateRange) => Promise<LighthouseApiResult<CumulativeStateTimeCandidatesResult>>;
@@ -347,6 +470,7 @@ type LighthouseClient = {
     readonly createDelivery: (portfolioId: number, payload: LighthouseWritePayload) => Promise<LighthouseApiResult<unknown>>;
     readonly updateDelivery: (deliveryId: number, payload: LighthouseWritePayload) => Promise<LighthouseApiResult<unknown>>;
     readonly deleteDelivery: (deliveryId: number) => Promise<LighthouseApiResult<undefined>>;
+    readonly getDeliveryMetricsHistory: (deliveryId: number) => Promise<LighthouseApiResult<DeliveryMetricsHistory>>;
     readonly getRecurringBlackoutRules: () => Promise<LighthouseApiResult<readonly RecurringBlackoutRule[]>>;
     readonly createRecurringBlackoutRule: (payload: LighthouseWritePayload) => Promise<LighthouseApiResult<RecurringBlackoutRule>>;
     readonly updateRecurringBlackoutRule: (id: number, payload: LighthouseWritePayload) => Promise<LighthouseApiResult<RecurringBlackoutRule>>;
@@ -371,6 +495,9 @@ declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
     readonly workItemAgePercentiles: "v26.6.7.1";
     readonly mcpOAuthPassThrough: "v26.6.16.14";
     readonly blockedCountHistory: "v26.7.3.1";
+    readonly percentilesOverTime: "v26.7.11.4";
+    readonly processBehaviorOverTime: "v26.7.11.4";
+    readonly deliveryMetricsHistory: "v26.5.29.5";
 };
 /**
  * Returns true when `candidate` is strictly newer than `baseline`, false when
@@ -380,4 +507,4 @@ declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
 declare const isServerVersionNewerThan: (candidate: string, baseline: string) => boolean | null;
 declare const createLighthouseClient: (configuration: LighthouseClientConfiguration, dependencies?: LighthouseClientDependencies) => LighthouseClient;
 
-export { type BacktestInput, type BlockedCountSnapshot, type CliAuthSessionPollResult, type CliAuthSessionStartError, type CliAuthSessionStartOutcome, type CliAuthSessionStartResult, type CliConnection, type CliServerAuthMode, type CliServerConnection, type CliStandaloneConnection, type ClientCapability, type ClientPackageContract, type ConnectivityCategory, type ConnectivityDependencies, type ConnectivityFetchResponse, type ConnectivityValidationResult, type CumulativeStateTimeCandidateRow, type CumulativeStateTimeCandidatesResult, type CumulativeStateTimeItemRow, type CumulativeStateTimeItemsResult, type CumulativeStateTimeResult, type CumulativeStateTimeStateRow, type DailyTotalWorkItemAge, type DailyWorkItemAge, type DayOfWeek, FEATURE_REQUIRES_SERVER_NEWER_THAN, type LighthouseApiError, type LighthouseApiResult, type LighthouseAuthContext, type LighthouseAuthOverrides, type LighthouseAuthStatus, type LighthouseAuthStore, type LighthouseClient, type LighthouseClientAuth, type LighthouseClientConfiguration, type LighthouseClientDependencies, type LighthouseConnectionConfiguration, type LighthouseWritePayload, type ManualForecastInput, type MetricsDateRange, type RecurringBlackoutRule, type RecurringBlackoutRuleInput, type ResolvedLighthouseEndpoint, type ServerAuthModeResult, type StandaloneDiscoveryContract, type StandaloneDiscoveryContractParseResult, type StoredLighthouseAuth, type ThroughputFilterView, type TotalWorkItemAgeOverTimeResult, type WorkItemAgeEntry, type WorkItemAgeOverTimeResult, createLighthouseAuthContext, createLighthouseClient, getClientPackageContract, getDefaultMetricsDateRange, getStandaloneDiscoveryLockfilePath, isServerVersionNewerThan, loadStandaloneDiscoveryContract, parseStandaloneDiscoveryContract, pollCliAuthSession, queryServerAuthMode, startCliAuthSession, validateLighthouseConnectivity };
+export { type BacktestInput, type BlockedCountSnapshot, type CliAuthSessionPollResult, type CliAuthSessionStartError, type CliAuthSessionStartOutcome, type CliAuthSessionStartResult, type CliConnection, type CliServerAuthMode, type CliServerConnection, type CliStandaloneConnection, type ClientCapability, type ClientPackageContract, type ConnectivityCategory, type ConnectivityDependencies, type ConnectivityFetchResponse, type ConnectivityValidationResult, type CumulativeStateTimeCandidateRow, type CumulativeStateTimeCandidatesResult, type CumulativeStateTimeItemRow, type CumulativeStateTimeItemsResult, type CumulativeStateTimeResult, type CumulativeStateTimeStateRow, type DailyTotalWorkItemAge, type DailyWorkItemAge, type DayOfWeek, type DeliveryFeatureMetric, type DeliveryMetricsHistory, type DeliveryMetricsHistoryPoint, type DeliveryMetricsHistorySummaryRow, type DeliveryWhenDistributionPoint, FEATURE_REQUIRES_SERVER_NEWER_THAN, type LighthouseApiError, type LighthouseApiResult, type LighthouseAuthContext, type LighthouseAuthOverrides, type LighthouseAuthStatus, type LighthouseAuthStore, type LighthouseClient, type LighthouseClientAuth, type LighthouseClientConfiguration, type LighthouseClientDependencies, type LighthouseConnectionConfiguration, type LighthouseWritePayload, type ManualForecastInput, type MetricsDateRange, type PercentilesOverTimeMetricType, type PercentilesOverTimeSnapshot, type ProcessBehaviorMetricType, type ProcessBehaviorSnapshot, type RecurringBlackoutRule, type RecurringBlackoutRuleInput, type ResolvedLighthouseEndpoint, type ServerAuthModeResult, type StandaloneDiscoveryContract, type StandaloneDiscoveryContractParseResult, type StoredLighthouseAuth, type ThroughputFilterView, type TotalWorkItemAgeOverTimeResult, type WorkItemAgeEntry, type WorkItemAgeOverTimeResult, createLighthouseAuthContext, createLighthouseClient, getClientPackageContract, getDefaultMetricsDateRange, getStandaloneDiscoveryLockfilePath, isServerVersionNewerThan, loadStandaloneDiscoveryContract, parseStandaloneDiscoveryContract, pollCliAuthSession, queryServerAuthMode, startCliAuthSession, summariseDeliveryMetricsHistory, validateLighthouseConnectivity };

package/dist/index.js

@@ -495,6 +495,15 @@ var getDefaultMetricsDateRange = () => {
     endDate: toIsoDate(end)
   };
 };
+var summariseDeliveryMetricsHistory = (history) => history.points.map((point) => ({
+  date: point.date,
+  totalWork: point.totalWork,
+  doneWork: point.doneWork,
+  remainingWork: point.remainingWork,
+  epicCount: point.featureBreakdown.length,
+  estimatedItemCount: point.estimatedItemCount,
+  likelihoodPercentage: point.likelihoodPercentage
+}));
 var getAuthHeaders = (auth) => {
   if (auth === void 0 || auth.kind === "none") {
     return {};
@@ -698,6 +707,12 @@ var getMetricsAsOfDateQuery = (asOfDate) => `asOfDate=${encodeURIComponent(asOfD
 var getItemIdsQuerySuffix = (itemIds) => itemIds && itemIds.length > 0 ? itemIds.map((id) => `&itemIds=${encodeURIComponent(id)}`).join("") : "";
 var getViewQuerySuffix = (view) => view === "filtered" ? "&view=filtered" : "";
 var getDefinitionIdQuerySuffix = (definitionId) => definitionId !== void 0 ? `&definitionId=${encodeURIComponent(definitionId)}` : "";
+var getPercentilesOverTimeQuerySuffix = (metricType, horizon) => {
+  const metricTypePart = metricType === void 0 ? "" : `&metricType=${encodeURIComponent(metricType)}`;
+  const horizonPart = horizon === void 0 ? "" : `&horizon=${encodeURIComponent(horizon)}`;
+  return `${metricTypePart}${horizonPart}`;
+};
+var getProcessBehaviorTypeQuerySuffix = (metricType) => metricType === void 0 ? "" : `&type=${encodeURIComponent(metricType)}`;
 var addUtcDays = (dateStr, days) => {
   const d = /* @__PURE__ */ new Date(`${dateStr}T00:00:00Z`);
   d.setUTCDate(d.getUTCDate() + days);
@@ -752,7 +767,12 @@ var FEATURE_REQUIRES_SERVER_NEWER_THAN = {
   recurringBlackoutRules: "v26.5.29.5",
   workItemAgePercentiles: "v26.6.7.1",
   mcpOAuthPassThrough: "v26.6.16.14",
-  blockedCountHistory: "v26.7.3.1"
+  blockedCountHistory: "v26.7.3.1",
+  percentilesOverTime: "v26.7.11.4",
+  processBehaviorOverTime: "v26.7.11.4",
+  // The endpoint landed in v26.6.7.1. The per-epic size fields came much later and are optional on
+  // the wire, so a server between the two answers fine — it just reports no sizes.
+  deliveryMetricsHistory: "v26.5.29.5"
 };
 var parseServerVersion = (raw) => {
   const trimmed = raw.trim().replace(/^v/iu, "");
@@ -1222,6 +1242,58 @@ var createLighthouseClient = (configuration, dependencies = {}) => {
         { method: "GET" }
       );
     },
+    getTeamPercentilesOverTime: async (teamId, range, metricType, horizon) => {
+      const unsupported = await ensureServerSupports("percentilesOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/teams/${teamId}/metrics/percentiles-over-time?${getMetricsDateRangeQuery(r)}${getPercentilesOverTimeQuerySuffix(metricType, horizon)}`,
+        { method: "GET" }
+      );
+    },
+    getPortfolioPercentilesOverTime: async (portfolioId, range, metricType, horizon) => {
+      const unsupported = await ensureServerSupports("percentilesOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/portfolios/${portfolioId}/metrics/percentiles-over-time?${getMetricsDateRangeQuery(r)}${getPercentilesOverTimeQuerySuffix(metricType, horizon)}`,
+        { method: "GET" }
+      );
+    },
+    getTeamProcessBehaviorOverTime: async (teamId, range, metricType) => {
+      const unsupported = await ensureServerSupports("processBehaviorOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/teams/${teamId}/metrics/process-behavior-over-time?${getMetricsDateRangeQuery(r)}${getProcessBehaviorTypeQuerySuffix(metricType)}`,
+        { method: "GET" }
+      );
+    },
+    getPortfolioProcessBehaviorOverTime: async (portfolioId, range, metricType) => {
+      const unsupported = await ensureServerSupports("processBehaviorOverTime");
+      if (unsupported) {
+        return unsupported;
+      }
+      const r = getResolvedMetricsDateRange(range);
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/portfolios/${portfolioId}/metrics/process-behavior-over-time?${getMetricsDateRangeQuery(r)}${getProcessBehaviorTypeQuerySuffix(metricType)}`,
+        { method: "GET" }
+      );
+    },
     getTeamCumulativeStateTime: async (teamId, range, itemIds) => {
       const unsupported = await ensureServerSupports("cumulativeStateTime");
       if (unsupported) {
@@ -1348,6 +1420,18 @@ var createLighthouseClient = (configuration, dependencies = {}) => {
       `/v1/deliveries/${deliveryId}`,
       { method: "DELETE" }
     ),
+    getDeliveryMetricsHistory: async (deliveryId) => {
+      const unsupported = await ensureServerSupports("deliveryMetricsHistory");
+      if (unsupported) {
+        return unsupported;
+      }
+      return requestJson(
+        configuration,
+        dependencies,
+        `/v1/deliveries/${deliveryId}/metrics-history`,
+        { method: "GET" }
+      );
+    },
     getRecurringBlackoutRules: async () => {
       const unsupported = await ensureServerSupports("recurringBlackoutRules");
       if (unsupported) {
@@ -1423,5 +1507,6 @@ export {
   pollCliAuthSession,
   queryServerAuthMode,
   startCliAuthSession,
+  summariseDeliveryMetricsHistory,
   validateLighthouseConnectivity
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letpeoplework/lighthouse-client",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Shared Lighthouse API client contracts",
   "repository": "https://github.com/LetPeopleWork/lighthouse-clients",
   "type": "module",