@frontera-sdk/blueprint 1.52.26 → 1.52.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/blueprint",
-  "version": "1.52.26",
+  "version": "1.52.27",
   "description": "React hooks for reading Blueprint data and invoking governed Actions from inside a Frontera app.",
   "keywords": [
     "frontera",
@@ -56,7 +56,7 @@
     "smoke": "bun run scripts/smoke.ts"
   },
   "dependencies": {
-    "@frontera-sdk/core": "1.52.26"
+    "@frontera-sdk/core": "1.52.27"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.90.21",

package/src/blueprint-client.ts

@@ -7,6 +7,7 @@ import type {
   BlueprintObjectName,
   BlueprintRow,
   MetricQueryRequest,
+  MetricQueryResponse,
   ObjectInstance,
   QueryRequest,
   QueryResponse,
@@ -118,8 +119,8 @@ export class BlueprintClient {
       }))
   }
 
-  metricQuery(apiName: string, request: MetricQueryRequest = {}): Promise<AggregateResponse> {
-    return this.client.request<AggregateResponse>(
+  metricQuery(apiName: string, request: MetricQueryRequest = {}): Promise<MetricQueryResponse> {
+    return this.client.request<MetricQueryResponse>(
       `/v1/blueprint/metrics/${encodeURIComponent(apiName)}/query`,
       { method: 'POST', body: request },
     )

package/src/hooks.ts

@@ -12,6 +12,7 @@ import type {
   BlueprintRow,
   BlueprintSortableProperty,
   MetricQueryRequest,
+  MetricQueryResponse,
   NearestRequest,
   ObjectInstance,
   QueryRequest,
@@ -207,8 +208,8 @@ export function useObjectInstance<
 export function useMetric(
   apiName: string,
   request: MetricQueryRequest = {},
-  options: ReadOptions<AggregateResponse> = {},
-): UseQueryResult<AggregateResponse, Error> {
+  options: ReadOptions<MetricQueryResponse> = {},
+): UseQueryResult<MetricQueryResponse, Error> {
   const client = useBlueprintClient()
   return useQuery({
     queryKey: blueprintKeys.metric(apiName, request),

package/src/types.ts

@@ -308,11 +308,59 @@ export interface AggregateResponse {
   rows: Array<Record<string, unknown>>
 }
 
+export interface MetricTimeRange {
+  /** ISO 8601 duration ending now, such as `P30D`. */
+  isoDuration?: string
+  start?: string
+  end?: string
+}
+
+/**
+ * `true` compares with the window just before `timeRange`; `{ start, end }`
+ * compares with that explicit window. `true` needs `timeRange.start` and
+ * `timeRange.end`: the service refuses it with `isoDuration`. Each measure
+ * then also returns `<measure>_prev`, `<measure>_delta` and `<measure>_pct`
+ * columns.
+ */
+export type MetricCompare = boolean | { start: string; end: string }
+
 export interface MetricQueryRequest {
   measures?: string[]
   dimensions?: string[]
+  timeRange?: MetricTimeRange
+  compare?: MetricCompare
   grain?: TimeGrain
-  limit?: number
+  /** Ask for `drill`, the objects behind each number. */
+  drill?: boolean
+}
+
+/** Which reviewed revisions produced an answer. */
+export interface QueryLineage {
+  objectTypes: string[]
+  linkTypes: string[]
+  datasetRevisionIds: string[]
+  sourceRevisionIds: string[]
+  editGenerations?: Array<{ objectType: string; generation: number }>
+  datasetNames?: Array<{ revisionId: string; name: string }>
+  sourceNames?: Array<{ revisionId: string; name: string }>
+}
+
+/**
+ * What the metric route answers. `lineage` and `drill` are absent for a metric
+ * the service cannot trace to Dataset revisions; `drill` also needs
+ * `drill: true` in the request. `drill[i]` describes `data[i]`, keyed by
+ * measure name. `drill` is also absent for a comparison, and a `share` or
+ * `ratio` measure has no entry, so a missing entry means the cell cannot name
+ * its rows, not that it has none.
+ */
+export interface MetricQueryResponse {
+  data: Array<Record<string, unknown>>
+  /** `true` when the rows stop at the row cap; narrow the window to see the rest. */
+  truncated?: boolean
+  /** The comparison window used, when the request set `compare`. */
+  compareWindow?: { start: string; end: string }
+  lineage?: QueryLineage
+  drill?: Array<Record<string, ObjectSetExpr>>
 }
 
 /**