@frontera-sdk/blueprint 1.50.82 → 1.50.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/blueprint",
-  "version": "1.50.82",
+  "version": "1.50.83",
   "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.50.82"
+    "@frontera-sdk/core": "1.50.83"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.90.21",

package/src/action-types.ts

@@ -158,6 +158,16 @@ export interface ActionRequestRequester {
   userId: string | null
 }
 
+/** How to read one submitted parameter value: its label, declared kind and whether it is withheld. */
+export interface ActionRequestInputField {
+  /** The parameter's own name, for a label. */
+  displayName: string
+  /** The declared kind (`string`, `number`, `geopoint`, …), or `null` when the parameter is no longer published. */
+  kind: string | null
+  /** The value is withheld from this reader; `input` holds `"[redacted]"` in its place. */
+  hidden: boolean
+}
+
 /**
  * What a request is asking for, ready to render.
  *
@@ -172,15 +182,23 @@ export interface ActionRequestRequester {
  * it agree on what to call it.
  *
  * A parameter the Action declares as confidential or restricted arrives as the
- * literal string `'[redacted]'`. Show it as withheld rather than as an empty
- * value: the parameter WAS supplied, and the approver is simply not the
- * audience for it.
+ * placeholder string `'[redacted]'` with `inputFields[key].hidden` true. Decide
+ * by `hidden`, never by matching the text: a submitted string can read
+ * `'[redacted]'` too. Show it as withheld rather than as an empty value: the
+ * parameter WAS supplied, and the approver is simply not the audience for it.
  */
 export interface ActionRequestIntent {
   actionApiName: string
   actionDisplayName: string
   /** Submitted values, keyed by parameter API name. */
   input: Record<string, unknown>
+  /**
+   * How to read each `input` entry, under the same key. Format a value by its
+   * declared `kind`, never by its shape (a `json` value can look like a
+   * location); `hidden` means the value is withheld from this reader. Absent
+   * on replies from a platform release that predates it.
+   */
+  inputFields?: Record<string, ActionRequestInputField>
   reason: string | null
   correlationId: string | null
   requester: ActionRequestRequester

package/src/hooks.ts

@@ -2,15 +2,17 @@ import { createContext, useContext } from 'react'
 import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query'
 
 import type { BlueprintClient } from './blueprint-client'
-import { objectsOf } from './types'
+import { DISTANCE_ROW_KEY, objectsOf } from './types'
 import type {
   AggregateRequest,
   AggregateResponse,
   BlueprintFilterableProperty,
+  BlueprintLocationProperty,
   BlueprintObjectName,
   BlueprintRow,
   BlueprintSortableProperty,
   MetricQueryRequest,
+  NearestRequest,
   ObjectInstance,
   QueryRequest,
   QueryResponse,
@@ -97,6 +99,12 @@ type EffectiveSortable<TLegacy, TObject extends BlueprintObjectName> =
     ? BlueprintSortableProperty<TObject>
     : Extract<keyof TLegacy, string>
 
+/** A location property of the row, or any name for an untyped object type. */
+type EffectiveLocation<TLegacy, TObject extends BlueprintObjectName> =
+  string extends EffectiveFilterable<TLegacy, TObject>
+    ? string
+    : BlueprintLocationProperty<EffectiveRow<TLegacy, TObject>>
+
 type SelectedRow<TRow, TSelect> =
   undefined extends TSelect
     ? TRow
@@ -104,15 +112,28 @@ type SelectedRow<TRow, TSelect> =
       ? Pick<TRow, TSelect[number]>
       : TRow
 
+/** `nearest` adds the distance to every row, whatever `select` narrowed. */
+type WithDistance<TRow, TNearest> =
+  TNearest extends NearestRequest ? TRow & { [DISTANCE_ROW_KEY]: number } : TRow
+
+type ObjectsRow<
+  TLegacy,
+  TObject extends BlueprintObjectName,
+  TSelect,
+  TNearest,
+> = WithDistance<SelectedRow<EffectiveRow<TLegacy, TObject>, TSelect>, TNearest>
+
 type ObjectsOptions<
   TLegacy,
   TObject extends BlueprintObjectName,
   TSelect extends readonly Extract<keyof EffectiveRow<TLegacy, TObject>, string>[] | undefined,
-> = ReadOptions<QueryResponse<SelectedRow<EffectiveRow<TLegacy, TObject>, TSelect>>> &
-  Omit<QueryRequest, 'objectSet' | 'select' | 'orderBy'> & {
+  TNearest extends NearestRequest<EffectiveLocation<TLegacy, TObject>> | undefined,
+> = ReadOptions<QueryResponse<ObjectsRow<TLegacy, TObject, TSelect, TNearest>>> &
+  Omit<QueryRequest, 'objectSet' | 'select' | 'orderBy' | 'nearest'> & {
     select?: TSelect
     orderBy?: Array<{ property: EffectiveSortable<TLegacy, TObject>; dir: 'asc' | 'desc' }>
     where?: TypedWhereNode<EffectiveRow<TLegacy, TObject>, EffectiveFilterable<TLegacy, TObject>>
+    nearest?: TNearest
   }
 
 export function useObjects<
@@ -120,18 +141,20 @@ export function useObjects<
   const TObject extends BlueprintObjectName = BlueprintObjectName,
   const TSelect extends readonly Extract<keyof EffectiveRow<TLegacy, TObject>, string>[] | undefined =
     readonly Extract<keyof EffectiveRow<TLegacy, TObject>, string>[] | undefined,
+  const TNearest extends NearestRequest<EffectiveLocation<TLegacy, TObject>> | undefined = undefined,
 >(
   objectType: TObject,
-  options: ObjectsOptions<NoInfer<TLegacy>, TObject, TSelect> = {},
-): UseQueryResult<QueryResponse<SelectedRow<EffectiveRow<TLegacy, TObject>, TSelect>>, Error> {
-  const { select, orderBy, pageSize, pageToken, where, ...queryOptions } = options
-  return useObjectQuery<SelectedRow<EffectiveRow<TLegacy, TObject>, TSelect>>(
+  options: ObjectsOptions<NoInfer<TLegacy>, TObject, TSelect, TNearest> = {},
+): UseQueryResult<QueryResponse<ObjectsRow<TLegacy, TObject, TSelect, TNearest>>, Error> {
+  const { select, orderBy, pageSize, pageToken, where, nearest, ...queryOptions } = options
+  return useObjectQuery<ObjectsRow<TLegacy, TObject, TSelect, TNearest>>(
     {
       objectSet: objectsOf(objectType, where as WhereNode | undefined),
       select: select ? [...select] : undefined,
       orderBy,
       pageSize,
       pageToken,
+      ...(nearest ? { nearest } : {}),
     },
     queryOptions,
   )

package/src/types.ts

@@ -20,6 +20,60 @@ export type ConditionOp =
   | 'isNull' | 'isNotNull'
   | 'gt' | 'gte' | 'lt' | 'lte' | 'between'
   | 'dateRange'
+  /** Some element of an array property satisfies every `elementWhere` condition. */
+  | 'arrayAny'
+  /** A location within `radiusMeters` of the point in `value`. */
+  | 'nearby'
+  /** A location inside the box in `value`. */
+  | 'withinBbox'
+
+/** The operators a location property takes, and the only ones it takes. */
+export type LocationConditionOp = 'nearby' | 'withinBbox' | 'isNull' | 'isNotNull'
+
+/** Every operator except the location-only ones. */
+export type ScalarConditionOp = Exclude<ConditionOp, 'nearby' | 'withinBbox'>
+
+/**
+ * A WGS 84 location in decimal degrees: `lat` in -90..90, `lon` in -180..180.
+ * Always named, never a `[lat, lon]` pair. This is the value a location
+ * property reads as, and the centre of a `nearby` condition.
+ */
+export interface BlueprintGeoPoint {
+  lat: number
+  lon: number
+}
+
+/**
+ * A latitude/longitude box with inclusive edges. `west > east` means the box
+ * crosses the 180° meridian (for example `west: 170, east: -170`). A box that
+ * should contain a pole must span every longitude (`west: -180, east: 180`).
+ */
+export interface BlueprintGeoBbox {
+  west: number
+  south: number
+  east: number
+  north: number
+}
+
+/** One condition on an element of an array property (`arrayAny`). */
+export interface ArrayElementCondition {
+  /** Field of a struct element; omit when the elements are scalars. */
+  field?: string
+  op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte'
+  value: unknown
+}
+
+/**
+ * The row key `nearest` adds: the distance in metres from `nearest.from`.
+ * Property names start with a lowercase letter, so it never collides with one.
+ */
+export const DISTANCE_ROW_KEY = '_distanceMeters'
+
+/** Order rows by distance from `from`, closest first. */
+export interface NearestRequest<TProperty extends string = string> {
+  property: TProperty
+  from: BlueprintGeoPoint
+}
 
 export type DatePreset =
   | 'TODAY' | 'YESTERDAY' | 'LAST_7_DAYS' | 'LAST_30_DAYS' | 'LAST_90_DAYS'
@@ -71,20 +125,45 @@ export type BlueprintSortableProperty<TObject extends BlueprintObjectName> =
 type PropertyValue<TRow, TProperty extends string> =
   TProperty extends keyof TRow ? TRow[TProperty] : unknown
 
+/**
+ * The properties of a row that read as a location. Derived from the row type
+ * (a generated row types a location as `BlueprintGeoPoint | null`), so it needs
+ * nothing from the registry.
+ */
+export type BlueprintLocationProperty<TRow> = {
+  [K in Extract<keyof TRow, string>]-?: [NonNullable<TRow[K]>] extends [never]
+    ? never
+    : NonNullable<TRow[K]> extends BlueprintGeoPoint ? K : never
+}[Extract<keyof TRow, string>]
+
 export type TypedPropertyCondition<TRow, TProperty extends string> =
   TProperty extends unknown
     ? {
         property: TProperty
-        op: ConditionOp
+        // An untyped (string-keyed) object type takes every operator; a
+        // registered one keeps the location operators for its locations.
+        op: string extends TProperty ? ConditionOp : ScalarConditionOp
         value?: PropertyValue<TRow, TProperty>
         values?: Array<PropertyValue<TRow, TProperty>>
         preset?: DatePreset
         timezone?: string
+        elementWhere?: ArrayElementCondition[]
+        radiusMeters?: number
       }
     : never
 
+/** A condition on a location property: geo operators and presence only. */
+export type TypedLocationCondition<TProperty extends string> =
+  TProperty extends unknown
+    ?
+        | { property: TProperty; op: 'nearby'; value: BlueprintGeoPoint; radiusMeters: number }
+        | { property: TProperty; op: 'withinBbox'; value: BlueprintGeoBbox }
+        | { property: TProperty; op: 'isNull' | 'isNotNull' }
+    : never
+
 export type TypedWhereNode<TRow, TProperty extends string> =
   | TypedPropertyCondition<TRow, TProperty>
+  | TypedLocationCondition<BlueprintLocationProperty<TRow>>
   | { and: Array<TypedWhereNode<TRow, TProperty>> }
   | { or: Array<TypedWhereNode<TRow, TProperty>> }
   | { not: TypedWhereNode<TRow, TProperty> }
@@ -102,6 +181,13 @@ export interface PropertyCondition {
   /** `dateRange` only — resolved to [start, end) server-side. */
   preset?: DatePreset
   timezone?: string
+  /** `arrayAny` only — conditions one element must satisfy together. */
+  elementWhere?: ArrayElementCondition[]
+  /**
+   * `nearby` only — the radius in metres around the point in `value`, measured
+   * over the Earth's surface; objects exactly on the circle match.
+   */
+  radiusMeters?: number
 }
 
 export type WhereNode =
@@ -139,6 +225,13 @@ export interface QueryRequest {
    * the types sent a parameter guaranteed to fail.
    */
   pageToken?: string
+  /**
+   * Order by distance from `nearest.from` to the location `nearest.property`,
+   * closest first, and add `_distanceMeters` to every row. The object set must
+   * also filter that location with `nearby` or `withinBbox` (outside any `or`
+   * or `not`), and `orderBy` must be omitted.
+   */
+  nearest?: NearestRequest
 }
 
 /**