@letpeoplework/lighthouse-client 1.7.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 {};
@@ -796,7 +806,10 @@ var FEATURE_REQUIRES_SERVER_NEWER_THAN = {
   mcpOAuthPassThrough: "v26.6.16.14",
   blockedCountHistory: "v26.7.3.1",
   percentilesOverTime: "v26.7.11.4",
-  processBehaviorOverTime: "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, "");
@@ -1444,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) {
@@ -1520,5 +1545,6 @@ var createLighthouseClient = (configuration, dependencies = {}) => {
   pollCliAuthSession,
   queryServerAuthMode,
   startCliAuthSession,
+  summariseDeliveryMetricsHistory,
   validateLighthouseConnectivity
 });

package/dist/index.d.cts

@@ -233,6 +233,68 @@ 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.
@@ -408,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>>;
@@ -434,6 +497,7 @@ declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
     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
@@ -443,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 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, 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,68 @@ 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.
@@ -408,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>>;
@@ -434,6 +497,7 @@ declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
     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
@@ -443,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 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, 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 {};
@@ -760,7 +769,10 @@ var FEATURE_REQUIRES_SERVER_NEWER_THAN = {
   mcpOAuthPassThrough: "v26.6.16.14",
   blockedCountHistory: "v26.7.3.1",
   percentilesOverTime: "v26.7.11.4",
-  processBehaviorOverTime: "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, "");
@@ -1408,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) {
@@ -1483,5 +1507,6 @@ export {
   pollCliAuthSession,
   queryServerAuthMode,
   startCliAuthSession,
+  summariseDeliveryMetricsHistory,
   validateLighthouseConnectivity
 };

package/package.json

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