@frontera-sdk/blueprint 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sebati
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,48 @@
+# @frontera-sdk/blueprint
+
+React hooks for reading Blueprint — the organization-wide model of object
+types, properties, links and metrics — from inside a Frontera app.
+
+```bash
+bun add @frontera-sdk/blueprint @frontera-sdk/core react @tanstack/react-query
+```
+
+```tsx
+import { blueprintProvider } from '@frontera-sdk/blueprint/provider'
+import { useObjects } from '@frontera-sdk/blueprint/hooks'
+import { createFronteraApp } from '@frontera-sdk/core/create-frontera-app'
+
+createFronteraApp(<App />, { providers: [blueprintProvider] })
+
+function App() {
+  const { data, isLoading } = useObjects('Shipment', {
+    where: { property: 'deliveryStatus', op: 'eq', value: 'late' },
+    pageSize: 20,
+  })
+  return <p>{isLoading ? 'Loading…' : `${data?.rows.length} late`}</p>
+}
+```
+
+## Filter on the server
+
+`where` compiles into the object set, so the server filters and pages.
+Filtering the returned array instead narrows one page and misreports every
+total — a filter matching 8,961 records renders 5 of them under "Page 1 of 1".
+For the same reason a total is its own query (`useAggregate` with a count over
+the same object set), never `rows.length`.
+
+## Entry points
+
+| Import | What it is |
+|---|---|
+| `@frontera-sdk/blueprint/hooks` | `useObjects`, `useAggregate`, `useObjectInstance` |
+| `@frontera-sdk/blueprint/provider` | the provider `createFronteraApp` takes |
+| `@frontera-sdk/blueprint/blueprint-client` | the client underneath the hooks |
+| `@frontera-sdk/blueprint/types` | request and response types, `WhereNode` |
+
+Every read is scoped by the credential the host handed over at handshake, so an
+object type the workspace was not granted is absent rather than forbidden.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@frontera-sdk/blueprint",
+  "version": "0.1.0",
+  "description": "React hooks for reading Blueprint data from inside a Frontera app.",
+  "keywords": [
+    "frontera",
+    "blueprint",
+    "react",
+    "hooks"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "src",
+    "!src/__tests__",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./types": {
+      "types": "./src/types.ts",
+      "import": "./src/types.ts"
+    },
+    "./blueprint-client": {
+      "types": "./src/blueprint-client.ts",
+      "import": "./src/blueprint-client.ts"
+    },
+    "./hooks": {
+      "types": "./src/hooks.ts",
+      "import": "./src/hooks.ts"
+    },
+    "./provider": {
+      "types": "./src/provider.tsx",
+      "import": "./src/provider.tsx"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "smoke": "bun run scripts/smoke.ts"
+  },
+  "dependencies": {
+    "@frontera-sdk/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "react": "19.2.5",
+    "typescript": "^5.9.3"
+  }
+}

package/src/blueprint-client.ts

@@ -0,0 +1,81 @@
+import type { FronteraClient } from '@frontera-sdk/core/client'
+import type {
+  AggregateGroupBy,
+  AggregateRequest,
+  AggregateResponse,
+  MetricQueryRequest,
+  ObjectInstance,
+  QueryRequest,
+  QueryResponse,
+} from './types'
+
+/**
+ * Typed client for the Blueprint read API.
+ *
+ * Every method is workspace-scoped by the credential on the underlying
+ * `FronteraClient`. An object type the workspace has not been granted is absent
+ * from the server's catalog snapshot, so the query compiler raises
+ * `UNKNOWN_OBJECT_TYPE` — grant violations arrive as a 404, not a 403, and that
+ * is intentional: the caller cannot distinguish "does not exist" from "not
+ * granted", which is the point.
+ */
+export class BlueprintClient {
+  constructor(private readonly client: FronteraClient) {}
+
+  query<TRow = Record<string, unknown>>(request: QueryRequest): Promise<QueryResponse<TRow>> {
+    return this.client.request<QueryResponse<TRow>>('/v1/blueprint/query', {
+      method: 'POST',
+      body: request,
+    })
+  }
+
+  queryObjectSet<TRow = Record<string, unknown>>(
+    objectSetId: string,
+    request: Omit<QueryRequest, 'objectSet'> = {},
+  ): Promise<QueryResponse<TRow>> {
+    return this.client.request<QueryResponse<TRow>>(
+      `/v1/blueprint/object-sets/${encodeURIComponent(objectSetId)}/query`,
+      { method: 'POST', body: request },
+    )
+  }
+
+  /**
+   * Run an aggregation.
+   *
+   * `groupBy` is required by the service; it is defaulted here so a grand
+   * total reads as `aggregate({ objectSet, aggregations })` rather than
+   * forcing every caller to remember an empty array.
+   */
+  aggregate(
+    request: Omit<AggregateRequest, 'groupBy'> & { groupBy?: AggregateGroupBy[] },
+  ): Promise<AggregateResponse> {
+    return this.client.request<AggregateResponse>('/v1/blueprint/aggregate', {
+      method: 'POST',
+      // Default AFTER the spread: an explicit `undefined` in the request must
+      // not win over the fallback.
+      body: { ...request, groupBy: request.groupBy ?? [] },
+    })
+  }
+
+  instance<TProps = Record<string, unknown>>(
+    objectType: string,
+    pk: string,
+  ): Promise<ObjectInstance<TProps>> {
+    return this.client.request<ObjectInstance<TProps>>(
+      `/v1/blueprint/object-types/${encodeURIComponent(objectType)}/instances/${encodeURIComponent(pk)}`,
+    )
+  }
+
+  propertyValues(objectType: string, property: string): Promise<string[]> {
+    return this.client.request<string[]>(
+      `/v1/blueprint/object-types/${encodeURIComponent(objectType)}/properties/${encodeURIComponent(property)}/values`,
+    )
+  }
+
+  metricQuery(apiName: string, request: MetricQueryRequest = {}): Promise<AggregateResponse> {
+    return this.client.request<AggregateResponse>(
+      `/v1/blueprint/metrics/${encodeURIComponent(apiName)}/query`,
+      { method: 'POST', body: request },
+    )
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,102 @@
+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 type {
+  AggregateRequest,
+  AggregateResponse,
+  ObjectInstance,
+  QueryRequest,
+  QueryResponse,
+  WhereNode,
+} from './types'
+
+/**
+ * Query-key factory.
+ *
+ * Requests are serialised into the key so two structurally equal requests share
+ * a cache entry. Key order therefore matters: callers must build request
+ * objects consistently, which they do because these hooks construct them.
+ */
+export const blueprintKeys = {
+  all: ['blueprint'] as const,
+  query: (request: QueryRequest) => ['blueprint', 'query', JSON.stringify(request)] as const,
+  aggregate: (request: AggregateRequest) =>
+    ['blueprint', 'aggregate', JSON.stringify(request)] as const,
+  instance: (objectType: string, pk: string) =>
+    ['blueprint', 'instance', objectType, pk] as const,
+}
+
+export const FronteraBlueprintContext = createContext<BlueprintClient | null>(null)
+
+export function useBlueprintClient(): BlueprintClient {
+  const client = useContext(FronteraBlueprintContext)
+  if (!client) {
+    throw new Error(
+      'No BlueprintClient in context. Wrap the tree in FronteraBlueprintContext.Provider — createFronteraApp does this for you in a Frontera app.',
+    )
+  }
+  return client
+}
+
+type ReadOptions<TData> = Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn'>
+
+/** Run an arbitrary object-set query. */
+export function useObjectQuery<TRow = Record<string, unknown>>(
+  request: QueryRequest,
+  options: ReadOptions<QueryResponse<TRow>> = {},
+): UseQueryResult<QueryResponse<TRow>, Error> {
+  const client = useBlueprintClient()
+  return useQuery({
+    queryKey: blueprintKeys.query(request),
+    queryFn: () => client.query<TRow>(request),
+    ...options,
+  })
+}
+
+/**
+ * One object type, optionally filtered.
+ *
+ * `where` compiles into the object-set expression, so the SERVER filters and
+ * pages. Filtering the returned rows in the component instead is the classic
+ * mistake: it narrows only the page you happened to fetch, so a facet showing
+ * 8,961 matches renders 5 rows and claims "Page 1 of 1".
+ */
+export function useObjects<TRow = Record<string, unknown>>(
+  objectType: string,
+  options: ReadOptions<QueryResponse<TRow>> &
+    Omit<QueryRequest, 'objectSet'> & { where?: WhereNode } = {},
+): UseQueryResult<QueryResponse<TRow>, Error> {
+  const { select, orderBy, page, pageSize, where, ...queryOptions } = options
+  return useObjectQuery<TRow>(
+    { objectSet: objectsOf(objectType, where), select, orderBy, page, pageSize },
+    queryOptions,
+  )
+}
+
+export function useAggregate(
+  request: AggregateRequest,
+  options: ReadOptions<AggregateResponse> = {},
+): UseQueryResult<AggregateResponse, Error> {
+  const client = useBlueprintClient()
+  return useQuery({
+    queryKey: blueprintKeys.aggregate(request),
+    queryFn: () => client.aggregate(request),
+    ...options,
+  })
+}
+
+export function useObjectInstance<TProps = Record<string, unknown>>(
+  objectType: string,
+  pk: string | null | undefined,
+  options: ReadOptions<ObjectInstance<TProps>> = {},
+): UseQueryResult<ObjectInstance<TProps>, Error> {
+  const client = useBlueprintClient()
+  return useQuery({
+    queryKey: blueprintKeys.instance(objectType, pk ?? ''),
+    queryFn: () => client.instance<TProps>(objectType, pk as string),
+    enabled: Boolean(pk) && options.enabled !== false,
+    ...options,
+  })
+}

package/src/provider.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react'
+import type { FronteraClient } from '@frontera-sdk/core/client'
+
+import { BlueprintClient } from './blueprint-client'
+import { FronteraBlueprintContext } from './hooks'
+
+/**
+ * Plug Blueprint reads into `createFronteraApp`.
+ *
+ * The dependency runs one way — `@frontera-sdk/blueprint` knows about
+ * `@frontera-sdk/core`, never the reverse — so the app entry point composes the
+ * two rather than sdk-core importing a domain package it should not know exists.
+ * That is why this is a callback the entry passes in:
+ *
+ * ```tsx
+ * createFronteraApp(<App />, { providers: [blueprintProvider] })
+ * ```
+ *
+ * The client is rebuilt whenever the host rotates the credential, because the
+ * `FronteraClient` it wraps is replaced rather than mutated.
+ */
+export function blueprintProvider(
+  value: { client: FronteraClient },
+  children: ReactNode,
+): ReactNode {
+  return (
+    <FronteraBlueprintContext.Provider value={new BlueprintClient(value.client)}>
+      {children}
+    </FronteraBlueprintContext.Provider>
+  )
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Request and response types for the Blueprint read API.
+ *
+ * `ObjectSetExpr` is deliberately loose. The service validates the expression
+ * tree in `query/validate.ts` with error messages far better than a structural
+ * type could produce, and mirroring that grammar here would mean shipping an
+ * SDK release every time the service gained a node kind. The common shapes are
+ * named so callers get completion for what they actually write.
+ */
+/**
+ * Condition operators, mirroring the service's `ConditionOp`.
+ *
+ * Filtering belongs in the object-set expression, NOT in the app: a client-side
+ * `.filter()` over a fetched page silently reduces "8,961 cancelled shipments"
+ * to "the cancelled ones that happened to be in the last 200 rows", and the
+ * counts stop matching the table.
+ */
+export type ConditionOp =
+  | 'eq' | 'ne' | 'in' | 'notIn' | 'contains' | 'startsWith'
+  | 'isNull' | 'isNotNull'
+  | 'gt' | 'gte' | 'lt' | 'lte' | 'between'
+  | 'dateRange'
+
+export type DatePreset =
+  | 'TODAY' | 'YESTERDAY' | 'LAST_7_DAYS' | 'LAST_30_DAYS' | 'LAST_90_DAYS'
+  | 'THIS_MONTH' | 'LAST_MONTH' | 'THIS_QUARTER' | 'THIS_YEAR'
+
+export interface PropertyCondition {
+  property: string
+  op: ConditionOp
+  value?: unknown
+  values?: unknown[]
+  /** `dateRange` only — resolved to [start, end) server-side. */
+  preset?: DatePreset
+  timezone?: string
+}
+
+export type WhereNode =
+  | PropertyCondition
+  | { and: WhereNode[] }
+  | { or: WhereNode[] }
+  | { not: WhereNode }
+
+export type ObjectSetExpr =
+  | { type: 'base'; objectType: string }
+  | { type: 'filter'; objectSet: ObjectSetExpr; where: WhereNode }
+  | { type: 'searchAround'; objectSet: ObjectSetExpr; link: string }
+  | { type: 'union' | 'intersect' | 'subtract'; objectSets: ObjectSetExpr[] }
+  | { type: 'reference'; objectSetId: string }
+  | { type: 'static'; objectType: string; pks: Array<string | number> }
+  | { type: string; [key: string]: unknown }
+
+export interface OrderBy {
+  property: string
+  dir: 'asc' | 'desc'
+}
+
+export interface QueryRequest {
+  objectSet: ObjectSetExpr
+  select?: string[]
+  orderBy?: OrderBy[]
+  page?: number
+  pageSize?: number
+}
+
+/**
+ * `properties` is the FULL projection for the object type regardless of what
+ * `select` asked for — filter display columns client-side rather than assuming
+ * this list matches `select`.
+ */
+export interface QueryResponse<TRow = Record<string, unknown>> {
+  rows: TRow[]
+  properties: Array<{ apiName: string; displayName?: string; dataType?: string }>
+  totalCount?: number
+}
+
+export const AGGREGATE_FUNCTIONS = [
+  'count',
+  'sum',
+  'avg',
+  'min',
+  'max',
+  'countDistinct',
+] as const
+
+export type AggregateFunction = (typeof AGGREGATE_FUNCTIONS)[number]
+
+export type TimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
+
+export interface AggregateSpec {
+  /**
+   * Result column name.
+   *
+   * `alias`, not `name` — this mirrors the service's `aggregateBody` schema
+   * exactly (blueprint-query-router.ts). Getting it wrong produces a 400 that
+   * says only "Expected required property", which is a miserable thing to
+   * debug from inside an app.
+   */
+  alias: string
+  fn: AggregateFunction
+  property?: string
+  /** Per-aggregation filter expression, validated server-side. */
+  filters?: unknown
+}
+
+export interface AggregateGroupBy {
+  property: string
+  /** Set for a temporal property to bucket by grain; the service aliases the
+   *  result column as `${property}_${grain}`. */
+  bucket?: TimeGrain
+}
+
+export interface AggregateRequest {
+  objectSet: ObjectSetExpr
+  aggregations: AggregateSpec[]
+  /** REQUIRED by the service — pass `[]` for a grand total. */
+  groupBy: AggregateGroupBy[]
+  having?: unknown
+  sort?: Array<{ alias: string; dir: 'asc' | 'desc' }>
+  limit?: number
+}
+
+export interface AggregateResponse {
+  rows: Array<Record<string, unknown>>
+}
+
+export interface MetricQueryRequest {
+  measures?: string[]
+  dimensions?: string[]
+  grain?: TimeGrain
+  limit?: number
+}
+
+/**
+ * One object, as the service returns it: the property bag itself.
+ *
+ * NOT wrapped in `{ objectType, primaryKey, properties }` — the instance route
+ * responds with the properties flat under the envelope's `data`, so a wrapper
+ * type here would make `.properties` permanently undefined and render an empty
+ * detail panel with no error to explain it.
+ */
+export type ObjectInstance<TProps = Record<string, unknown>> = TProps
+
+/** Wrap an object set in a filter. `where` undefined returns the set unchanged. */
+export function filtered(objectSet: ObjectSetExpr, where?: WhereNode): ObjectSetExpr {
+  return where ? { type: 'filter', objectSet, where } : objectSet
+}
+
+/** The common case: one object type, optionally filtered. */
+export function objectsOf(objectType: string, where?: WhereNode): ObjectSetExpr {
+  return filtered({ type: 'base', objectType }, where)
+}