feat: add DataPathwayMetricsFetchCommand and throughput metrics support

Add GET /api/v1/pathways/:id/metrics command for fetching per-pathway
delivery throughput data. Also extend heartbeat input to carry optional
throughput snapshot (events/sec, success rate, per-endpoint/flowType).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jbiskur

src/commands/data-pathways/assignment.heartbeat.ts

@@ -10,6 +10,25 @@ export interface DataPathwayAssignmentHeartbeatInput {
     deliveryErrorsTotal?: number
     bufferDepth?: number
     lagSeconds?: number
+    throughput?: {
+      global: { eventsPerSecond: number; totalRecorded: number; windowSeconds: number }
+      endpoints: Record<
+        string,
+        {
+          eventsPerSecond: number
+          successRate: number
+          flowTypes: Record<
+            string,
+            {
+              eventsPerSecond: number
+              successRate: number
+              avgDurationMs: number
+              recentResults: Array<{ status: number; durationMs: number; success: boolean; ageMs: number }>
+            }
+          >
+        }
+      >
+    }
   }
 }
 

src/commands/data-pathways/index.ts

@@ -4,6 +4,7 @@ export * from "./pathway.fetch.ts"
 export * from "./pathway.list.ts"
 export * from "./pathway.disable.ts"
 export * from "./pathway.delete.ts"
+export * from "./pathway.metrics.fetch.ts"
 
 // Slots
 export * from "./slot.register.ts"

src/commands/data-pathways/pathway.metrics.fetch.ts

@@ -0,0 +1,36 @@
+import { Command } from "../../common/command.ts"
+import { type DataPathwayMetrics, DataPathwayMetricsSchema } from "../../contracts/data-pathways.ts"
+import type { ClientError } from "../../exceptions/client-error.ts"
+import { NotFoundException } from "../../exceptions/not-found.ts"
+import { parseResponseHelper } from "../../utils/parse-response-helper.ts"
+
+export interface DataPathwayMetricsFetchInput {
+  id: string
+}
+
+export class DataPathwayMetricsFetchCommand extends Command<DataPathwayMetricsFetchInput, DataPathwayMetrics> {
+  protected override allowedModes: ("apiKey" | "bearer")[] = ["bearer"]
+
+  protected override getMethod(): string {
+    return "GET"
+  }
+
+  protected override getBaseUrl(): string {
+    return "https://data-pathways.api.flowcore.io"
+  }
+
+  protected override getPath(): string {
+    return `/api/v1/pathways/${this.input.id}/metrics`
+  }
+
+  protected override parseResponse(rawResponse: unknown): DataPathwayMetrics {
+    return parseResponseHelper(DataPathwayMetricsSchema, rawResponse)
+  }
+
+  protected override handleClientError(error: ClientError): void {
+    if (error.status === 404) {
+      throw new NotFoundException("DataPathway", { id: this.input.id })
+    }
+    throw error
+  }
+}

src/contracts/data-pathways.ts

@@ -492,6 +492,86 @@ export const DataPathwayDeliveryErrorListSchema: TObject<{
 })
 export type DataPathwayDeliveryErrorList = Static<typeof DataPathwayDeliveryErrorListSchema>
 
+// ── Pathway Metrics ──
+
+type TThroughputRecentResult = TObject<{
+  status: TNumber
+  durationMs: TNumber
+  success: TBoolean
+  ageMs: TNumber
+}>
+const ThroughputRecentResultSchema: TThroughputRecentResult = Type.Object({
+  status: Type.Number(),
+  durationMs: Type.Number(),
+  success: Type.Boolean(),
+  ageMs: Type.Number(),
+})
+
+type TThroughputFlowType = TObject<{
+  eventsPerSecond: TNumber
+  successRate: TNumber
+  avgDurationMs: TNumber
+  recentResults: TArray<TThroughputRecentResult>
+}>
+const ThroughputFlowTypeSchema: TThroughputFlowType = Type.Object({
+  eventsPerSecond: Type.Number(),
+  successRate: Type.Number(),
+  avgDurationMs: Type.Number(),
+  recentResults: Type.Array(ThroughputRecentResultSchema),
+})
+
+type TThroughputEndpoint = TObject<{
+  eventsPerSecond: TNumber
+  successRate: TNumber
+  flowTypes: TRecord<TString, TThroughputFlowType>
+}>
+const ThroughputEndpointSchema: TThroughputEndpoint = Type.Object({
+  eventsPerSecond: Type.Number(),
+  successRate: Type.Number(),
+  flowTypes: Type.Record(Type.String(), ThroughputFlowTypeSchema),
+})
+
+type TThroughputGlobal = TObject<{
+  eventsPerSecond: TNumber
+  totalRecorded: TNumber
+  windowSeconds: TNumber
+}>
+
+type TThroughputSnapshot = TObject<{
+  global: TThroughputGlobal
+  endpoints: TRecord<TString, TThroughputEndpoint>
+}>
+const ThroughputSnapshotSchema: TThroughputSnapshot = Type.Object({
+  global: Type.Object({
+    eventsPerSecond: Type.Number(),
+    totalRecorded: Type.Number(),
+    windowSeconds: Type.Number(),
+  }),
+  endpoints: Type.Record(Type.String(), ThroughputEndpointSchema),
+})
+
+type TMetricsAssignmentEntry = TObject<{
+  assignmentId: TString
+  status: TString
+  throughput: TUnion<[TThroughputSnapshot, TNull]>
+  updatedAt: TString
+}>
+const MetricsAssignmentEntrySchema: TMetricsAssignmentEntry = Type.Object({
+  assignmentId: Type.String(),
+  status: Type.String(),
+  throughput: Type.Union([ThroughputSnapshotSchema, Type.Null()]),
+  updatedAt: Type.String(),
+})
+
+export const DataPathwayMetricsSchema: TObject<{
+  pathwayId: TString
+  assignments: TArray<TMetricsAssignmentEntry>
+}> = Type.Object({
+  pathwayId: Type.String(),
+  assignments: Type.Array(MetricsAssignmentEntrySchema),
+})
+export type DataPathwayMetrics = Static<typeof DataPathwayMetricsSchema>
+
 // ── Health ──
 
 export const DataPathwayHealthSchema: TObject<{