@segmentstream-cloud/app 0.13.1 → 0.14.0

package/README.md

@@ -263,7 +263,7 @@ Records, action inputs and action results are typed from the ontology:
 const { items, nextCursor } = await segmentstream.ontology.lead.find({
   where: { status: { in: ["new", "contacted"] } },
   orderBy: [{ field: "createdAt", direction: "desc" }],
-  include: { owner: true },
+  include: ["owner"],
   limit: 20,
 });
 const lead = await segmentstream.ontology.lead.get(id);
@@ -279,6 +279,8 @@ const { result, validation, edits } = await segmentstream.ontology.lead.actions.
 
 - `find` sends the query as URL parameters, `query` as a JSON body; both return
   `{ items, nextCursor }`. Pass `nextCursor` as `after` for the next page.
+- `include` adds related records under their relationship names: list the names,
+  `["owner", "tags"]`, or pass `{ owner: true, tags: true }`.
 - `actions.<name>(input, { validateOnly })` posts `{ input, options }` and returns
   `{ result, validation, edits }`. Generated actions are there too
   (`actions.create`, `update`, `delete`), and `action(name, input)` runs any action by
@@ -444,17 +446,17 @@ reach. Look at or change records through `find` and actions; count, sum or compa
 
 ```ts
 const { fields, rows, execution } = await segmentstream.ontology.aggregate({
-  measures: ["trendtoysSales.revenue", "trendtoysStock.onHand"],
-  dimensions: ["trendtoysProduct.assortmentStatus"],
+  measures: ["acmeSales.revenue", "acmeStock.onHand"],
+  dimensions: ["acmeProduct.assortmentStatus"],
   filters: [
     {
-      dimension: "trendtoysSales.orderDate",
+      dimension: "acmeSales.orderDate",
       operator: "between",
       values: ["2026-09-01", "2026-09-30"],
     },
-    { dimension: "trendtoysSales.currency", operator: "equals", value: "RUB" },
+    { dimension: "acmeSales.currency", operator: "equals", value: "RUB" },
   ],
-  orderBy: [{ measure: "trendtoysSales.revenue", direction: "desc" }],
+  orderBy: [{ measure: "acmeSales.revenue", direction: "desc" }],
 });
 ```
 
@@ -463,8 +465,8 @@ const { fields, rows, execution } = await segmentstream.ontology.aggregate({
   `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`.
+  `acmeSales.returnedProduct.brand`. Its column is still keyed by the property's own name,
+  `acmeProduct.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`.
@@ -484,13 +486,13 @@ Since 0.13.0, both aggregates take more conditions, buckets and a timezone:
 
 ```ts
 const { rows, execution } = await segmentstream.ontology.aggregate({
-  measures: ["trendtoysSales.wonOrders"],
-  dimensions: ["trendtoysSales.orderDate"],
+  measures: ["acmeSales.wonOrders"],
+  dimensions: ["acmeSales.orderDate"],
   granularity: "week",
-  granularityOf: "trendtoysSales.orderDate",
+  granularityOf: "acmeSales.orderDate",
   filters: [
-    { dimension: "trendtoysSales.orderDate", operator: "inPeriod", value: "last 4 weeks" },
-    { dimension: "trendtoysProduct.brand", operator: "notIn", values: ["Unknown", "Test"] },
+    { dimension: "acmeSales.orderDate", operator: "inPeriod", value: "last 4 weeks" },
+    { dimension: "acmeProduct.brand", operator: "notIn", values: ["Unknown", "Test"] },
   ],
   timezone: "Europe/Moscow",
 });
@@ -517,6 +519,40 @@ const { rows, execution } = await segmentstream.ontology.aggregate({
   `@segmentstream-cloud/ontology` 0.17.0 or later, whose service accepts them; earlier
   versions refuse them. See [Upgrading to 0.13](#upgrading-to-013).
 
+Since 0.14.0, the model-level call also takes the measures of the model, which the ontology
+declares in `defineOntology({ measures })` over measures of several entities, by their bare
+names beside `entity.measure` names:
+
+```ts
+const { fields, rows } = await segmentstream.ontology.aggregate({
+  measures: ["planAttainment", "acmeSales.ordered"],
+  dimensions: ["acmeSales.orderDate"],
+  granularity: "month",
+  granularityOf: "acmeSales.orderDate",
+  filters: [
+    { dimension: "acmeSales.orderDate", operator: "inPeriod", value: "this year to date" },
+  ],
+  orderBy: [{ measure: "planAttainment", direction: "desc" }],
+});
+// fields[1]: { name: "planAttainment", label: "Plan attainment", unit: "ratio", additive: false,
+//   filters: [...], inputs: ["acmeSales.ordered", "acmePlans.plannedUnits"] }
+```
+
+- A measure of the model is requested by the camelCase name the ontology declares, typed from
+  `typeof ontology`. The platform names it in snake_case, `plan_attainment`; its field and row
+  key are the camelCase form, `planAttainment`, as for entity measures.
+- Its field carries `inputs`, the entity measures it reads, as `entity.measure` in camelCase per
+  segment, like other names. They are computed whether or not you request them; request one to
+  get its column too.
+- Its `filters` lists the filters that applied to every input. A filter on a property the
+  measure aligns applies to each entity through its own property; a filter that reaches some of
+  its entities and not others is refused with `invalid_aggregate_query`.
+- A group one of its entities has no rows for, or a zero denominator, gives `null`.
+- The caller needs read permission on every entity it reads.
+- These requests need the workspace's ontology deployed with `@segmentstream-cloud/ontology`
+  0.23.0 or later, which declares and serves measures of the model; earlier versions refuse
+  them. Requests that name none work as before, and their fields carry no `inputs`.
+
 ## How requests are handled
 
 - Page navigations without a session are redirected to `/sign-in?returnTo=<path>` and
@@ -627,3 +663,10 @@ Replace segmentstream.semantic with typed warehouse-backed entity aggregates. Se
 - The new operators, `inPeriod`, granularities and `timezone` need the workspace's ontology
   deployed with `@segmentstream-cloud/ontology` 0.17.0 or later. Requests that use none of
   them work as before.
+
+## Upgrading to 0.14
+
+- `segmentstream.ontology.aggregate()` accepts the measures of the model by their bare names, typed
+  from an ontology that declares them with `defineOntology({ measures })`. Ontologies without them
+  type the same names as before.
+- `AggregateField` gains `inputs`, which only fields of measures of the model carry.

package/dist/data.d.ts

@@ -115,7 +115,8 @@ export type ModelAggregateFilter<Dimension extends string = string> = {
     readonly values?: undefined;
 };
 /**
- * A model-level aggregate: measures of one or more entities, as `entity.measure`, grouped by
+ * A model-level aggregate: measures of one or more entities, as `entity.measure`, and measures of
+ * the model, declared in `defineOntology({ measures })`, by their bare names, 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` or `inPeriod` filters.
@@ -156,6 +157,12 @@ export interface AggregateField {
      * rows snapshot. The request groups by it or filters it to one day.
      */
     readonly balanceOver?: string;
+    /**
+     * On a measure of the model: the entity measures it reads, as `entity.measure`, in declaration
+     * order. They are computed whether or not the request names them, and come back as columns only
+     * when it does. Its `filters` are the filters that applied to every one of them.
+     */
+    readonly inputs?: readonly string[];
 }
 export interface AggregateResult<Row = Record<string, string | boolean | null>> {
     readonly deploymentId: string | null;

package/dist/ontology-wire.d.ts

@@ -46,6 +46,11 @@ export declare function encodeWhere(input: {
     readonly getCatalog: () => Promise<WireCatalog>;
 }): Promise<Where | undefined>;
 export declare function queryToWire(query: OntologyQuery): unknown;
+/**
+ * `include` with snake_case names, as an object: a list of names, `["assignedOwner"]`, becomes
+ * `{ assigned_owner: true }`, which every version of the ontology service accepts.
+ */
+export declare function includeToWire(include: NonNullable<OntologyQuery["include"]>): Readonly<Record<string, unknown>>;
 /** Decode record fields and included relationships without descending into JSON properties. */
 export declare function recordFromWire<A = unknown>(value: unknown, entity: string, catalog: WireCatalog): A;
 export declare function actionInputToWire(input: unknown, entity: string, action: string, catalog: WireCatalog): unknown;

package/dist/ontology-wire.js

@@ -127,14 +127,23 @@ export function queryToWire(query) {
         ...(orderBy === undefined
             ? {}
             : { order_by: orderBy.map((order) => ({ ...order, field: toSnakeCase(order.field) })) }),
-        ...(query.include === undefined
-            ? {}
-            : {
-                include: Object.fromEntries(Object.entries(query.include).map(([name, value]) => [toSnakeCase(name), value])),
-            }),
+        ...(query.include === undefined ? {} : { include: includeToWire(query.include) }),
         ...(where === undefined ? {} : { where }),
     };
 }
+/**
+ * `include` with snake_case names, as an object: a list of names, `["assignedOwner"]`, becomes
+ * `{ assigned_owner: true }`, which every version of the ontology service accepts.
+ */
+export function includeToWire(include) {
+    const entries = isIncludeList(include)
+        ? include.map((name) => [name, true])
+        : Object.entries(include);
+    return Object.fromEntries(entries.map(([name, value]) => [toSnakeCase(name), value]));
+}
+function isIncludeList(include) {
+    return Array.isArray(include);
+}
 function selectToWire(value, property) {
     if (property?.type !== "select") {
         return value;

package/dist/ontology.d.ts

@@ -53,8 +53,10 @@ export interface OrderBy<Field extends string = string> {
 export interface OntologyQuery<Row = JsonRecord> {
     readonly where?: Where;
     readonly orderBy?: ReadonlyArray<OrderBy<keyof Row & string>>;
-    /** Related records to add to each record, by relationship name. */
-    readonly include?: {
+    /**
+     * Related records to add to each record, by relationship name: `["owner"]` or `{ owner: true }`.
+     */
+    readonly include?: ReadonlyArray<string> | {
         readonly [relationship: string]: true;
     };
     /** The `nextCursor` of the previous page. */
@@ -250,7 +252,16 @@ type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
  */
 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;
+type EntityMeasuresOf<E> = E extends unknown ? `${CamelCase<NameOf<E>>}.${MeasuresOf<E>}` : never;
+/**
+ * The measures of the model, `defineOntology({ measures })`, by their bare declared names. An
+ * ontology SDK without them, or a definition typed as any record of measures, names none.
+ */
+type ModelMeasuresOf<O> = O extends {
+    readonly config: {
+        readonly measures?: infer M;
+    };
+} ? DeclaredNames<NonNullable<M>> : 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>;
 /**
@@ -273,7 +284,7 @@ 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>>;
+} & ModelAggregateClient<EntityMeasuresOf<EntitiesOf<O>> | ModelMeasuresOf<O>, ModelDimensionsOf<EntitiesOf<O>, O>>;
 /** A client for any entity, when the app passes no ontology type. */
 export type UntypedOntologyClient = ModelAggregateClient & {
     readonly [entity: string]: EntityClient<JsonRecord, {

package/dist/ontology.js

@@ -1,5 +1,5 @@
 import { SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
-import { actionInputToWire, encodeWhere, editsFromWire, queryToWire, recordFromWire, responseFromWire, } from "./ontology-wire.js";
+import { actionInputToWire, encodeWhere, editsFromWire, includeToWire, queryToWire, recordFromWire, responseFromWire, } from "./ontology-wire.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;
@@ -198,9 +198,11 @@ export function findParameters(query) {
             .join(","));
     }
     if (query.include !== undefined) {
-        const relationships = Object.keys(query.include).filter((name) => query.include?.[name] === true);
+        const relationships = Object.entries(includeToWire(query.include))
+            .filter(([, included]) => included === true)
+            .map(([name]) => name);
         if (relationships.length > 0) {
-            search.set("include", relationships.map(toSnakeCase).join(","));
+            search.set("include", relationships.join(","));
         }
     }
     if (query.after !== undefined) {
@@ -245,8 +247,8 @@ function aggregateToWire(request) {
     };
 }
 /**
- * Field names, the filters each measure applied, a balance's dimension and row keys come back
- * camelCase per segment; `execution` is passed on as sent.
+ * Field names, the filters each measure applied, a balance's dimension, a model measure's inputs
+ * and row keys come back camelCase per segment; `execution` is passed on as sent.
  */
 function aggregateResultFromWire(result, decodeName) {
     return {
@@ -256,6 +258,7 @@ function aggregateResultFromWire(result, decodeName) {
             name: decodeName(field.name),
             ...(field.filters === undefined ? {} : { filters: field.filters.map(decodeName) }),
             ...(field.balanceOver === undefined ? {} : { balanceOver: decodeName(field.balanceOver) }),
+            ...(field.inputs === undefined ? {} : { inputs: field.inputs.map(decodeName) }),
         })),
         rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [decodeName(name), value]))),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.13.1",
+  "version": "0.14.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",