@segmentstream-cloud/app 0.9.0 → 0.10.0

package/README.md

@@ -334,9 +334,79 @@ export default async function Page() {
 - Values arrive as JSON: safe integers as numbers, larger integers and decimals as strings,
   timestamps as ISO strings, records and arrays as JSON strings.
 
-`segmentstream.ontology.<entity>.aggregate(request)` uses the server-held workspace app
-credential and supports Neon Auth apps. Stored record operations use the ontology user token.
-`segmentstream.fetch(path)` still requires the legacy platform session.
+One authorization model covers the ontology: every `segmentstream.ontology` call, aggregates
+included, runs as the signed-in user through the ontology service, which checks their
+permissions. `segmentstream.ontology.<entity>.aggregate(request)` posts to
+`/api/ontology/<entity>/aggregate` and needs read permission on the entities it reaches.
+`segmentstream.warehouse` is the only call that uses the workspace app credential, and it
+reaches the whole workspace warehouse. `segmentstream.fetch(path)` still requires the legacy
+platform session. Aggregates through the service need the workspace's ontology deployed with
+`@segmentstream-cloud/ontology` 0.13.0 or later.
+
+Since 0.10.0, dimensions, filters and `orderBy` accept relationship paths, typed from the
+ontology's relationships:
+
+```ts
+const { rows, execution } = await segmentstream.ontology.order.aggregate({
+  dimensions: ["customer.segment"],
+  measures: ["orders"],
+  dateRange: { from: "2026-09-01", to: "2026-09-30" },
+});
+```
+
+- A path is `<relationship>.<property>`, through one or two to-one relationships. Paths into
+  a stored target include `id`; json and blob properties are left out. A thunk target types
+  its paths as `` `customer.${string}` ``. Each segment converts to snake_case on the wire,
+  and rows come back keyed by the camelCase path. These names are relative to the entity and
+  convert as record fields do: `line_2` reads as `line2`.
+- `execution.warnings` reports keys that matched more than one related row; totals are
+  unaffected. `execution.sources` gives, for each stored entity read through replication,
+  the time its data is current to, once known. Both are absent when the query produced none.
+- 0.10.0 requires the platform release that joins stored targets through replication.
+- See [ontology aggregates](../../docs/ontology-aggregates.md#relationship-paths).
+
+Since 0.10.0, `segmentstream.ontology.aggregate(request)` asks for numbers about the whole
+model: measures of several entities, warehouse-backed or stored, grouped by properties they all
+reach. Look at or change records through `find` and actions; count, sum or compare through
+`aggregate`.
+
+```ts
+const { fields, rows, execution } = await segmentstream.ontology.aggregate({
+  measures: ["trendtoysSales.revenue", "trendtoysStock.onHand"],
+  dimensions: ["trendtoysProduct.assortmentStatus"],
+  filters: [
+    {
+      dimension: "trendtoysSales.orderDate",
+      operator: "between",
+      values: ["2026-09-01", "2026-09-30"],
+    },
+    { dimension: "trendtoysSales.currency", operator: "equals", value: "RUB" },
+  ],
+  orderBy: [{ measure: "trendtoysSales.revenue", direction: "desc" }],
+});
+```
+
+- Names are `entity.measure` and `entity.property`, each segment in camelCase, typed from the
+  ontology. An `_` before a digit stays, so an entity's declared name converts back:
+  `sales_2025.revenue`. This differs from the per-entity call and records, which drop it. Fields
+  and rows are keyed by these names.
+- When an entity reaches a property's entity in more than one way, write a route from it:
+  `trendtoysSales.returnedProduct.brand`. Its column is still keyed by the property's own name,
+  `trendtoysProduct.brand`.
+- It posts to the ontology service's `/api/ontology/aggregate` as the signed-in user, who needs
+  read permission on every entity the request reaches. Previews and local development answer
+  `aggregate_unavailable`.
+- Date bounds are `between` filters, inclusive. Each partitioned entity needs one on its own
+  partition property. Currency measures need their entity filtered to one currency, the same
+  for every entity.
+- A measure field's `filters` lists the filters applied to it, and `execution.warnings` names
+  each filter that did not reach a measure's entity. `additive: false` marks a measure whose
+  rows don't add up to a total.
+- Failures throw `SegmentStreamApiError` with the service's `code`: `invalid_request`,
+  `invalid_aggregate_query`, `forbidden`, `rate_limited` (30 aggregates a minute per user),
+  `aggregate_unavailable`, `aggregate_upstream_unavailable`, `ontology_version_mismatch` or
+  `aggregate_scope_mismatch`. See
+  [ontology aggregates](../../docs/ontology-aggregates.md#errors).
 
 ## How requests are handled
 
@@ -395,7 +465,7 @@ Without `NEON_AUTH_BASE_URL`, 0.3 behaves exactly as 0.2, so existing apps keep
 working: members of the workspace's organization sign in with their SegmentStream
 account through `/api/segmentstream/[...path]/route.ts`
 (`export const { GET, POST } = segmentstream.handlers();`), the proxy redirects to
-SegmentStream, and `fetch` acts as the member; warehouse queries and aggregates prefer the workspace app credential. In that mode
+SegmentStream, and `fetch` acts as the member; warehouse queries prefer the workspace app credential. In that mode
 `roles` and `permissions` are empty, `can()` is `false`, `authHandlers()` answers
 `404 neon_auth_not_configured`, and `segmentstream.ontology` sends the member's app
 token, which the ontology service accepts while workspaces move to Neon Auth. Keep the
@@ -422,3 +492,18 @@ Apache-2.0
 ## Upgrading to 0.5
 
 Replace segmentstream.semantic with typed warehouse-backed entity aggregates. See [ontology aggregates](../../docs/ontology-aggregates.md). Warehouse-backed clients expose no record CRUD or actions.
+
+## Upgrading to 0.10
+
+- Shorthand aggregates accept relationship paths. Their responses may carry
+  `execution.warnings` and `execution.sources`.
+- `segmentstream.ontology.aggregate()` is new, and `aggregate` is a reserved entity name.
+- `segmentstream.ontology.<entity>.aggregate()` now runs as the signed-in user through the
+  ontology service, like record reads, and no longer uses `SEGMENTSTREAM_APP_CREDENTIAL`. The
+  user needs read permission on the entities it reaches.
+- Server code without a signed-in user, such as a scheduled Route Handler, can no longer
+  aggregate with the workspace credential. Use `segmentstream.warehouse` there, or call the
+  ontology service with an API key.
+- Deploy the workspace's ontology with `@segmentstream-cloud/ontology` 0.13.0 or later. It
+  serves `/api/ontology/<entity>/aggregate` and `/api/ontology/aggregate`; earlier versions
+  don't.

package/dist/app.js

@@ -55,7 +55,7 @@ export function createApp(config, dependencies = {}) {
             getAccessToken: legacy.getAccessToken,
             fetch: data.fetch,
             warehouse: data.warehouse,
-            ontology: createOntologyClient(ontologyTransport, data.aggregateTransport),
+            ontology: createOntologyClient(ontologyTransport),
             oauth: createAgentAuthorizations(ontologyTransport),
         };
     }
@@ -84,7 +84,7 @@ export function createApp(config, dependencies = {}) {
         getAccessToken: async () => null,
         fetch: data.fetch,
         warehouse: data.warehouse,
-        ontology: createOntologyClient(neon.ontologyTransport, data.aggregateTransport),
+        ontology: createOntologyClient(neon.ontologyTransport),
         oauth: createAgentAuthorizations(neon.ontologyTransport),
     };
 }
@@ -93,7 +93,7 @@ async function noSegmentStreamSession() {
     throw new SegmentStreamApiError({
         code: "app_credential_missing",
         status: 401,
-        detail: "Apps that sign in with Neon Auth have no SegmentStream session. Warehouse queries and ontology aggregates use the workspace app credential, SEGMENTSTREAM_APP_CREDENTIAL, which is not set; SegmentStream sets it on deploy. Other SegmentStream API calls are not available to these apps yet.",
+        detail: "Apps that sign in with Neon Auth have no SegmentStream session. Warehouse queries use the workspace app credential, SEGMENTSTREAM_APP_CREDENTIAL, which is not set; SegmentStream sets it on deploy. Other SegmentStream API calls are not available to these apps yet.",
     });
 }
 function notConfiguredHandlers() {

package/dist/data.d.ts

@@ -43,34 +43,71 @@ export interface WarehouseDryRun {
     readonly bytesProcessed: string | null;
     readonly maximumBytesBilled: string;
 }
-export interface AggregateRequest<Property extends string = string, Measure extends string = string, Temporal extends Property = Property> {
-    readonly dimensions: readonly Property[];
+/**
+ * An aggregate query. Dimensions, filters and ordering name the entity's own properties, or a
+ * related entity's property through to-one relationships: `Path`, such as `product.brand`.
+ */
+export interface AggregateRequest<Property extends string = string, Measure extends string = string, Temporal extends Property = Property, Path extends string = never> {
+    readonly dimensions: readonly (Property | Path)[];
     readonly measures: readonly Measure[];
     readonly dateRange?: {
         readonly from: string;
         readonly to: string;
     };
-    readonly granularityOf?: Temporal;
+    /** The selected date or timestamp dimension to bucket, which may be a related one. */
+    readonly granularityOf?: Temporal | Path;
     readonly granularity?: "day" | "week" | "month";
     readonly filters?: ReadonlyArray<{
-        readonly dimension: Property;
+        readonly dimension: Property | Path;
         readonly operator: "equals" | "in" | "isNull" | "isNotNull";
         readonly value?: string | number | boolean;
         readonly values?: ReadonlyArray<string | number | boolean>;
     }>;
     readonly orderBy?: ReadonlyArray<{
         readonly measure?: Measure;
-        readonly dimension?: Property;
+        readonly dimension?: Property | Path;
         readonly direction: "asc" | "desc";
     }>;
     readonly limit?: number;
 }
+/** A filter of a model-level aggregate. `between` takes two inclusive `values`, the lower first. */
+export interface ModelAggregateFilter<Dimension extends string = string> {
+    readonly dimension: Dimension;
+    readonly operator: "equals" | "in" | "isNull" | "isNotNull" | "between";
+    readonly value?: string | number | boolean;
+    readonly values?: ReadonlyArray<string | number | boolean>;
+}
+/**
+ * A model-level aggregate: measures of one or more entities, as `entity.measure`, grouped by
+ * `entity.property` dimensions. A dimension may instead be a route from a measure's entity,
+ * `entity.relationship.property`, which picks the way that entity reaches the property. Date bounds
+ * are `between` filters.
+ */
+export interface ModelAggregateRequest<Measure extends string = string, Dimension extends string = string> {
+    readonly measures: readonly Measure[];
+    readonly dimensions?: readonly Dimension[];
+    readonly filters?: ReadonlyArray<ModelAggregateFilter<Dimension>>;
+    readonly granularity?: "day" | "week" | "month";
+    /** The requested date or timestamp dimension to bucket by `granularity`. */
+    readonly granularityOf?: Dimension;
+    readonly orderBy?: ReadonlyArray<{
+        readonly measure?: Measure;
+        readonly dimension?: Dimension;
+        readonly direction: "asc" | "desc";
+    }>;
+    /** Rows to return, 1–1000; 100 by default. */
+    readonly limit?: number;
+}
 export interface AggregateField {
     readonly name: string;
     readonly label: string;
     readonly type: string;
     readonly unit?: string;
     readonly format?: string;
+    /** On a measure: the filters applied to it. A filter its entity cannot reach is not listed. */
+    readonly filters?: readonly string[];
+    /** `false` on a measure whose rows don't add up to a total, such as a distinct count or a ratio. */
+    readonly additive?: boolean;
 }
 export interface AggregateResult<Row = Record<string, string | boolean | null>> {
     readonly deploymentId: string | null;
@@ -82,6 +119,16 @@ export interface AggregateResult<Row = Record<string, string | boolean | null>>
         readonly elapsedMs: number;
         readonly bytesProcessed?: string;
         readonly bytesBilled?: string;
+        /**
+         * Data problems the query met, for example a join key that matched more than one record, and
+         * filters that did not apply to some measure's entity.
+         */
+        readonly warnings?: readonly string[];
+        /** The stored entities a query read, each with the time up to which its copy is complete. */
+        readonly sources?: ReadonlyArray<{
+            readonly entity: string;
+            readonly asOf: string;
+        }>;
     };
 }
 export interface WarehouseClient {
@@ -111,7 +158,4 @@ export interface DataClientDependencies {
 export declare function createDataClient(dependencies: DataClientDependencies): {
     fetch: (path: string, init?: RequestInit) => Promise<Response>;
     warehouse: WarehouseClient;
-    aggregateTransport: {
-        fetch: (path: string, init: RequestInit) => Promise<Response>;
-    };
 };

package/dist/data.js

@@ -154,14 +154,7 @@ export function createDataClient(dependencies) {
             };
         },
     };
-    const aggregateTransport = {
-        fetch: (path, init) => {
-            if (!/^\/[a-z][a-z0-9_]*\/aggregate$/.test(path))
-                throw new TypeError("Invalid aggregate path.");
-            return authorizedFetch(`${workspace}/entities${path}`, init, warehouseToken);
-        },
-    };
-    return { fetch: apiFetch, warehouse, aggregateTransport };
+    return { fetch: apiFetch, warehouse };
 }
 function bytesLimit(value) {
     if (value === undefined) {

package/dist/index.d.ts

@@ -24,9 +24,9 @@ export type { AgentAuthorizationRequest, AgentAuthorizations, AgentScope } from
 export type { ApiIssue } from "./errors.js";
 export type { CurrentUser } from "./me.js";
 export type { AuthRouteHandler, AuthRouteHandlers, SignOutOptions } from "./neon.js";
-export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
+export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, ModelAggregateClient, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
 export type { PermissionHolder } from "./permissions.js";
-export type { AggregateField, AggregateRequest, AggregateResult, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
+export type { AggregateField, AggregateRequest, AggregateResult, ModelAggregateFilter, ModelAggregateRequest, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
 export type { ParameterType, QueryParameterValue, QueryParameters, TypedParameter, } from "./parameters.js";
 export type { SegmentStreamAppConfig } from "./config.js";
 export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";

package/dist/ontology-names.d.ts

@@ -1,3 +1,10 @@
 /** Convert each character once, including acronym boundaries such as HTTPClient. */
 export declare function toSnakeCase(name: string): string;
 export declare function toCamelCase(name: string): string;
+/**
+ * camelCase that keeps an `_` before a digit, so `toSnakeCase` restores the name: `sales_2025`
+ * stays `sales_2025` and `wb2_sales` becomes `wb2Sales`. Model-level aggregate names, whose first
+ * segment is a declared snake_case entity name, use it; records and per-entity aggregates keep
+ * `toCamelCase`.
+ */
+export declare function toReversibleCamelCase(name: string): string;

package/dist/ontology-names.js

@@ -24,3 +24,12 @@ export function toSnakeCase(name) {
 export function toCamelCase(name) {
     return name.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
 }
+/**
+ * camelCase that keeps an `_` before a digit, so `toSnakeCase` restores the name: `sales_2025`
+ * stays `sales_2025` and `wb2_sales` becomes `wb2Sales`. Model-level aggregate names, whose first
+ * segment is a declared snake_case entity name, use it; records and per-entity aggregates keep
+ * `toCamelCase`.
+ */
+export function toReversibleCamelCase(name) {
+    return name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/dist/ontology-wire.d.ts

@@ -11,6 +11,8 @@ interface CatalogRelationship {
     readonly to: string;
     readonly inverse: string;
     readonly cardinality: string;
+    /** Present when either end is warehouse-backed: the relationship is matched by value. */
+    readonly on?: unknown;
 }
 interface CatalogEntity {
     readonly name: string;

package/dist/ontology-wire.js

@@ -16,6 +16,13 @@ const SYSTEM_FIELDS = ["id", "created_at", "updated_at", "created_by", "updated_
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+/**
+ * A relationship with a warehouse-backed end is matched by value through `on`: it has no
+ * `<name>_id` field, and the ontology service cannot traverse or filter through it.
+ */
+function isValueMatched(relationship) {
+    return relationship.on !== undefined && relationship.on !== null;
+}
 /** Catalog metadata distinguishes relationship filters from opaque JSON property values. */
 export async function encodeWhere(input) {
     const { where, entity, getCatalog } = input;
@@ -51,12 +58,14 @@ function whereFromCatalog(input) {
 }
 function relationshipTarget(input) {
     const { field, entity, definition, catalog } = input;
-    const forward = definition?.relationships.find((candidate) => candidate.name === field);
+    const forward = definition?.relationships.find((candidate) => candidate.name === field && !isValueMatched(candidate));
     if (forward !== undefined) {
         return { entity: forward.to, many: forward.cardinality === "many" };
     }
     for (const candidate of catalog.entities) {
-        const inverse = candidate.relationships.find((relationship) => relationship.to === entity && relationship.inverse === field);
+        const inverse = candidate.relationships.find((relationship) => relationship.to === entity &&
+            relationship.inverse === field &&
+            !isValueMatched(relationship));
         if (inverse !== undefined) {
             return { entity: candidate.name, many: true };
         }
@@ -79,7 +88,9 @@ function isGeneratedField(field, definition) {
     if (SYSTEM_FIELDS.includes(field)) {
         return true;
     }
-    return (definition?.relationships.some((relationship) => relationship.cardinality === "one" && `${relationship.name}_id` === field) ?? false);
+    return (definition?.relationships.some((relationship) => relationship.cardinality === "one" &&
+        !isValueMatched(relationship) &&
+        `${relationship.name}_id` === field) ?? false);
 }
 function fieldFilterToWire(input) {
     const { field, condition, definition } = input;

package/dist/ontology.d.ts

@@ -1,4 +1,4 @@
-import type { AggregateRequest, AggregateResult } from "./data.js";
+import type { AggregateRequest, AggregateResult, ModelAggregateRequest } from "./data.js";
 /**
  * The typed client for the app's ontology service, `/api/ontology`. The app imports its ontology as
  * types only (`import type ontology from "../../ontology"`) and passes `typeof ontology` to
@@ -191,31 +191,99 @@ type ActionClients<A> = {
 type PropertiesOf<E> = E extends {
     readonly properties: infer P;
 } ? P : never;
+/** Declared names only: a definition typed as any `Measures` names none the client can check. */
+type DeclaredNames<M> = string extends keyof M ? never : keyof M & string;
+/** A warehouse-backed entity's `measures`, or the measures of a stored entity's definition. */
 type MeasuresOf<E> = E extends {
     readonly measures: infer M;
-} ? keyof M & string : never;
-export interface AggregateEntityClient<Property extends string = string, Measure extends string = string, Temporal extends Property = Property> {
-    readonly aggregate: (request: AggregateRequest<Property, Measure, Temporal>, options?: RequestOptions) => Promise<AggregateResult>;
-}
-type ClientOf<E> = E extends {
+} ? keyof M & string : E extends {
+    readonly definition: {
+        readonly measures?: infer M;
+    };
+} ? DeclaredNames<NonNullable<M>> : never;
+type RelationshipsOf<E> = E extends {
+    readonly relationships: infer R;
+} ? R : never;
+type IsWarehouseBacked<E> = E extends {
     readonly definition: {
         readonly source: object;
     };
-} ? AggregateEntityClient<keyof PropertiesOf<E> & string, MeasuresOf<E>> : EntityClient<RecordOf<E>, ActionClients<ActionsOf<E>>>;
+} ? true : false;
+/**
+ * A `rel.one`, which aggregates may follow. Every relationship of a warehouse-backed entity is
+ * matched by value; a stored entity's may also be keyed (`<relationship>_id` joined to `id`).
+ */
+interface ToOne {
+    readonly cardinality: "one";
+}
+/** The target's name, or `string` when a thunk erased it or the ontology SDK predates the name. */
+type TargetNameOf<R> = R extends {
+    readonly "~ontology.target": infer Name extends string;
+} ? Name : string;
+/** The entity of `O` named `Name`. `User` is not replicated, so aggregates never reach it. */
+type EntityNamed<O, Name extends string> = Name extends "user" ? never : Extract<EntitiesOf<O>, {
+    readonly name: Name;
+}>;
+/** Properties whose values are scalars. json and blob values are objects, which aggregates skip. */
+type ScalarPropertiesOf<T> = {
+    [K in keyof PropertiesOf<T>]-?: PropertiesOf<T>[K] extends {
+        readonly Type: infer V;
+    } ? [Extract<V, object>] extends [never] ? K : never : K;
+}[keyof PropertiesOf<T>] & string;
+/** What a path may end on: the target's scalar properties, and `id` when the target is stored. */
+type FieldsOf<T> = ScalarPropertiesOf<T> | (IsWarehouseBacked<T> extends true ? never : "id");
+/** The rest of a path after reaching `T`: a field, or one more relationship when `Again`. */
+type PathEnds<T, O, Again extends boolean> = [T] extends [never] ? never : FieldsOf<T> | (Again extends true ? PathsFrom<T, O, false> : never);
+type PathsFrom<E, O, Again extends boolean> = {
+    [K in keyof RelationshipsOf<E> & string]: RelationshipsOf<E>[K] extends ToOne ? string extends TargetNameOf<RelationshipsOf<E>[K]> ? `${K}.${string}` : `${K}.${PathEnds<EntityNamed<O, TargetNameOf<RelationshipsOf<E>[K]>>, O, Again>}` : never;
+}[keyof RelationshipsOf<E> & string];
+/**
+ * Related properties of `E` as aggregate paths through at most two `rel.one` relationships:
+ * `product.brand`, `product.brand.name`. A thunk target erases its entity, so any path may follow
+ * its relationship: `` `${relationship}.${string}` ``.
+ */
+type PathsOf<E, O> = PathsFrom<E, O, true>;
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/**
+ * A snake_case entity name in camelCase, keeping an `_` before a digit so the name converts back:
+ * `sales_2025` stays, `wb2_sales` is `wb2Sales`. The client decodes model-level names the same way.
+ */
+type CamelCase<S extends string> = S extends `${infer Head}_${infer Tail}` ? Tail extends `${Digit}${string}` ? `${Head}_${CamelCase<Tail>}` : `${Head}${Capitalize<CamelCase<Tail>>}` : S;
+/** `entity.measure` for every measure of every entity, warehouse-backed or stored. */
+type ModelMeasuresOf<E> = E extends unknown ? `${CamelCase<NameOf<E>>}.${MeasuresOf<E>}` : never;
+/** A route picks how an entity with measures reaches a property, so only such entities start one. */
+type RoutesOf<E, O> = [MeasuresOf<E>] extends [never] ? never : PathsOf<E, O>;
+/**
+ * `entity.property` for every entity's scalar properties, and `id` for stored entities, plus the
+ * routes `entity.relationship.property` from each entity with measures.
+ */
+type ModelDimensionsOf<E, O> = E extends unknown ? `${CamelCase<NameOf<E>>}.${FieldsOf<E> | RoutesOf<E, O>}` : never;
+/**
+ * `segmentstream.ontology.aggregate`: `POST /api/ontology/aggregate`, as the signed-in user, who
+ * needs read permission on every entity the request reaches.
+ */
+export interface ModelAggregateClient<Measure extends string = string, Dimension extends string = string> {
+    readonly aggregate: (request: ModelAggregateRequest<Measure, Dimension>, options?: RequestOptions) => Promise<AggregateResult>;
+}
+export interface AggregateEntityClient<Property extends string = string, Measure extends string = string, Temporal extends Property = Property, Path extends string = never> {
+    readonly aggregate: (request: AggregateRequest<Property, Measure, Temporal, Path>, options?: RequestOptions) => Promise<AggregateResult>;
+}
+type ClientOf<E, O> = IsWarehouseBacked<E> extends true ? AggregateEntityClient<keyof PropertiesOf<E> & string, MeasuresOf<E>, keyof PropertiesOf<E> & string, PathsOf<E, O>> : EntityClient<RecordOf<E>, ActionClients<ActionsOf<E>>>;
 type TypedOntologyClient<O> = {
     readonly [N in NameOf<EntitiesOf<O>>]: ClientOf<Extract<EntitiesOf<O>, {
         readonly name: N;
-    }>>;
-};
+    }>, O>;
+} & ModelAggregateClient<ModelMeasuresOf<EntitiesOf<O>>, ModelDimensionsOf<EntitiesOf<O>, O>>;
 /** A client for any entity, when the app passes no ontology type. */
-export type UntypedOntologyClient = {
+export type UntypedOntologyClient = ModelAggregateClient & {
     readonly [entity: string]: EntityClient<JsonRecord, {
         readonly [action: string]: ActionCall<JsonRecord, JsonValue>;
     }> & AggregateEntityClient;
 };
 /**
  * `segmentstream.ontology`: one client per entity of `O`, the type of the app's ontology
- * (`typeof ontology`). Without it, any entity name is accepted and records are untyped.
+ * (`typeof ontology`), and `aggregate` across them. `aggregate` is a reserved entity name. Without
+ * `O`, any entity name is accepted and records are untyped.
  */
 export type OntologyClient<O = unknown> = unknown extends O ? UntypedOntologyClient : TypedOntologyClient<O>;
 /** Sends one ontology request with the caller's credentials. Paths are below `/api/ontology`. */
@@ -226,7 +294,7 @@ export interface OntologyTransport {
  * Entities and actions exist only in the app's types, so the client resolves them by name when
  * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
  */
-export declare function createOntologyClient<O>(transport: OntologyTransport, aggregateTransport?: OntologyTransport): OntologyClient<O>;
+export declare function createOntologyClient<O>(transport: OntologyTransport): OntologyClient<O>;
 /** `find` sends the query as URL parameters: `where` as JSON, `orderBy` as `field:direction`. */
 export declare function findParameters(query: OntologyQuery<JsonRecord>): URLSearchParams;
 export {};

package/dist/ontology.js

@@ -1,8 +1,10 @@
 import { SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
 import { actionInputToWire, encodeWhere, editsFromWire, queryToWire, recordFromWire, responseFromWire, } from "./ontology-wire.js";
-import { toCamelCase, toSnakeCase } from "./ontology-names.js";
+import { toCamelCase, toReversibleCamelCase, toSnakeCase } from "./ontology-names.js";
 const ENTITY_NAME = /^[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*$/;
 const ACTION_NAME = ENTITY_NAME;
+/** The ontology service's model-level aggregate, `/api/ontology/aggregate`; never an entity. */
+const MODEL_AGGREGATE = "aggregate";
 /** Names a caller may probe on any object; never an entity or an action. */
 const RESERVED = new Set([
     "then",
@@ -21,11 +23,16 @@ const RESERVED = new Set([
  * Entities and actions exist only in the app's types, so the client resolves them by name when
  * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
  */
-export function createOntologyClient(transport, aggregateTransport) {
+export function createOntologyClient(transport) {
     const entities = new Map();
     const catalogReader = createCatalogReader(transport);
+    // Every call, aggregates included, carries the user's session: the service checks permissions.
+    const aggregate = (request, options = {}) => send(catalogReader.transport, "POST", `/${MODEL_AGGREGATE}`, aggregateToWire(request), options.signal).then(modelAggregateResultFromWire);
     return new Proxy(Object.create(null), {
         get(_target, property) {
+            if (property === MODEL_AGGREGATE) {
+                return aggregate;
+            }
             if (typeof property !== "string" || RESERVED.has(property) || !ENTITY_NAME.test(property)) {
                 return undefined;
             }
@@ -33,16 +40,8 @@ export function createOntologyClient(transport, aggregateTransport) {
             if (client === undefined) {
                 client = {
                     ...entityClient(toSnakeCase(property), catalogReader.transport, catalogReader.getCatalog),
-                    aggregate: (request, options = {}) => {
-                        if (!aggregateTransport) {
-                            throw new TypeError("An aggregate transport is required.");
-                        }
-                        return send(aggregateTransport, "POST", `/${toSnakeCase(property)}/aggregate`, aggregateToWire(request), options.signal).then((result) => ({
-                            ...result,
-                            fields: result.fields.map((field) => ({ ...field, name: toCamelCase(field.name) })),
-                            rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [toCamelCase(name), value]))),
-                        }));
-                    },
+                    // Names are relative to the entity and convert as record fields do.
+                    aggregate: (request, options = {}) => send(catalogReader.transport, "POST", `/${toSnakeCase(property)}/aggregate`, aggregateToWire(request), options.signal).then((result) => aggregateResultFromWire(result, toCamelCase)),
                 };
                 entities.set(property, client);
             }
@@ -212,11 +211,16 @@ export function findParameters(query) {
     }
     return search;
 }
-/** The platform aggregate API keeps its existing protocol keys; ontology identifiers are canonical. */
+/**
+ * Aggregate requests keep their camelCase protocol keys and filter values; the names in them convert
+ * to snake_case one segment at a time.
+ */
 function aggregateToWire(request) {
     return {
         ...request,
-        dimensions: request.dimensions.map(toSnakeCase),
+        ...(request.dimensions === undefined
+            ? {}
+            : { dimensions: request.dimensions.map(toSnakeCase) }),
         measures: request.measures.map(toSnakeCase),
         ...(request.granularityOf === undefined
             ? {}
@@ -240,6 +244,39 @@ function aggregateToWire(request) {
             }),
     };
 }
+/**
+ * Field names, the filters each measure applied and row keys come back camelCase per segment;
+ * `execution` is passed on as sent.
+ */
+function aggregateResultFromWire(result, decodeName) {
+    return {
+        ...result,
+        fields: result.fields.map((field) => ({
+            ...field,
+            name: decodeName(field.name),
+            ...(field.filters === undefined ? {} : { filters: field.filters.map(decodeName) }),
+        })),
+        rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [decodeName(name), value]))),
+    };
+}
+/** Model-level names keep an `_` before a digit, and the entities in `sources` convert too. */
+function modelAggregateResultFromWire(wire) {
+    const result = aggregateResultFromWire(wire, toReversibleCamelCase);
+    const sources = result.execution.sources;
+    if (sources === undefined) {
+        return result;
+    }
+    return {
+        ...result,
+        execution: {
+            ...result.execution,
+            sources: sources.map((source) => ({
+                ...source,
+                entity: toReversibleCamelCase(source.entity),
+            })),
+        },
+    };
+}
 async function send(transport, method, path, body, signal) {
     const headers = new Headers({ accept: "application/json" });
     if (body !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",