@segmentstream-cloud/app 0.4.0 → 0.6.0

package/README.md

@@ -1,5 +1,11 @@
 # @segmentstream-cloud/app
 
+The ontology client uses snake_case entity fields and action names. Its TypeScript
+options remain camelCase; it maps `orderBy`, `isNull`, `startsWith`, and
+`validateOnly` to the generated REST contract and returns pagination/history
+metadata as camelCase. Queries using multiword filter operators lazily read and
+cache the ontology catalog so JSON property contents remain unchanged.
+
 Sign-in, users, permissions, the ontology client and warehouse data access for
 SegmentStream workspace apps built with Next.js (App Router, version 16 or later) and
 React 19. The app's users sign in with an email code, or a sign-in link the first time,
@@ -111,7 +117,7 @@ authUserId?, organizationId, workspaceId }`. `id` is the person's ontology `user
   or use another email.
 - `getUser()` returns the same, or `null` when signed out; it throws
   `SegmentStreamApiError` with `code: "not_invited"` for people without an invitation.
-- `can("lead:changeStatus")` is `true` when the user's permissions cover the
+- `can("lead:change_status")` is `true` when the user's permissions cover the
   permission. Roles may hold wildcards: `lead:*`, `*:read`, `*:*`. `isAllowed` and
   `grants` apply the same rule to any list of permissions.
 - `signOut()` ends the session, clears its cookies and redirects to `/sign-in` (or
@@ -126,22 +132,22 @@ user in Server Functions and Route Handlers too; do not rely on the proxy alone.
 (no Tailwind). Every class starts with `ss-`; the `--ss-*` custom properties on
 `:root` set colours, radius and font.
 
-| Export                                 | Does                                                                            |
-| -------------------------------------- | ------------------------------------------------------------------------------- |
-| `<SignIn />`                           | Email, then a six-digit code or a sign-in link; resend after 30 seconds, errors |
-| `useSignIn()`                          | The same sign-in without markup, for the app's own form                         |
-| `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                |
-| `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise       |
-| `<UserMenu />`                         | Name, email, roles and sign-out                                                 |
-| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
-| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                            |
-| `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                 |
+| Export                                  | Does                                                                            |
+| --------------------------------------- | ------------------------------------------------------------------------------- |
+| `<SignIn />`                            | Email, then a six-digit code or a sign-in link; resend after 30 seconds, errors |
+| `useSignIn()`                           | The same sign-in without markup, for the app's own form                         |
+| `<SignedIn>`, `<SignedOut>`             | Render children by session state                                                |
+| `<Can permission="lead:change_status">` | Renders children when the user holds the permission; `fallback` otherwise       |
+| `<UserMenu />`                          | Name, email, roles and sign-out                                                 |
+| `useUser()`                             | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
+| `usePermissions()`                      | `{ isLoading, roles, permissions, can(permission) }`                            |
+| `useSession()`, `signOut()`             | The Neon Auth session in the browser; sign-out from the browser                 |
 
 `<Can>` only hides controls: the ontology service checks every read and action. A
 Server Component may wrap server-rendered children in `<Can>`:
 
 ```tsx
-<Can permission="lead:changeStatus" fallback={lead.status}>
+<Can permission="lead:change_status" fallback={lead.status}>
   <ChangeStatusForm lead={lead.id} />
 </Can>
 ```
@@ -254,7 +260,7 @@ Records, action inputs and action results are typed from the ontology:
 ```ts
 const { items, nextCursor } = await segmentstream.ontology.lead.find({
   where: { status: { in: ["new", "contacted"] } },
-  orderBy: [{ field: "createdAt", direction: "desc" }],
+  orderBy: [{ field: "created_at", direction: "desc" }],
   include: { owner: true },
   limit: 20,
 });
@@ -263,8 +269,11 @@ const history = await segmentstream.ontology.lead.history(id, { limit: 50 });
 const page = await segmentstream.ontology.lead.query({ where: { email: { startsWith: "ada" } } });
 
 const input = { lead: id, status: "contacted" } as const;
-const check = await segmentstream.ontology.lead.actions.changeStatus(input, { validateOnly: true });
-const { result, validation, edits } = await segmentstream.ontology.lead.actions.changeStatus(input);
+const check = await segmentstream.ontology.lead.actions.change_status(input, {
+  validateOnly: true,
+});
+const { result, validation, edits } =
+  await segmentstream.ontology.lead.actions.change_status(input);
 ```
 
 - `find` sends the query as URL parameters, `query` as a JSON body; both return
@@ -272,7 +281,7 @@ const { result, validation, edits } = await segmentstream.ontology.lead.actions.
 - `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
-  name, such as `upsertByEmail`.
+  name, such as `upsert_by_email`.
 - Failures throw `SegmentStreamApiError` with the service's `code` (`forbidden`,
   `not_found`, `invalid_input`, `action_rejected`, `conflict`, `not_invited`), `status`,
   `detail`, `requestId` and, for invalid input, `issues`.
@@ -325,10 +334,9 @@ 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.semantic` (governed metrics from semantic models) and
-`segmentstream.fetch(path)` (any SegmentStream API path) act as the signed-in
-SegmentStream member, so they need the legacy sign-in; under Neon Auth they throw
-`app_credential_missing`.
+`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.
 
 ## How requests are handled
 
@@ -387,7 +395,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`, `warehouse` and `semantic` act as the member. In that mode
+SegmentStream, and `fetch` acts as the member; warehouse queries and aggregates 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
@@ -410,3 +418,7 @@ app word messages in its own language without matching the English sentences.
 ## License
 
 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.

package/dist/app.d.ts

@@ -1,5 +1,5 @@
 import type { Environment, SegmentStreamAppConfig } from "./config.js";
-import type { SemanticClient, WarehouseClient } from "./data.js";
+import type { WarehouseClient } from "./data.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
 import type { AuthRouteHandlers, CreateNeonAuth, SignOutOptions } from "./neon.js";
 import type { OntologyClient } from "./ontology.js";
@@ -44,8 +44,6 @@ export interface SegmentStreamApp<O = unknown> {
      * (`SEGMENTSTREAM_APP_CREDENTIAL`) when it is set, else the signed-in member's session.
      */
     readonly warehouse: WarehouseClient;
-    /** Governed metrics from the workspace's deployed semantic models. Server-only. Legacy sign-in only. */
-    readonly semantic: SemanticClient;
     /** The app's ontology service, `/api/ontology`, as the signed-in user. Server-only. */
     readonly ontology: OntologyClient<O>;
 }

package/dist/app.js

@@ -48,13 +48,12 @@ export function createApp(config, dependencies = {}) {
             getAccessToken: legacy.getAccessToken,
             fetch: data.fetch,
             warehouse: data.warehouse,
-            semantic: data.semantic,
             // The ontology service accepts SegmentStream app tokens while workspaces move to Neon Auth.
             ontology: createOntologyClient(createOntologyTransport({
                 fetch: fetchImplementation,
                 ontologyUrl: ontologyUrl === undefined ? undefined : new URL(ontologyUrl).origin,
                 credentials: { token: legacy.getAccessToken },
-            })),
+            }), data.aggregateTransport),
         };
     }
     const neon = createNeonSession({
@@ -82,8 +81,7 @@ export function createApp(config, dependencies = {}) {
         getAccessToken: async () => null,
         fetch: data.fetch,
         warehouse: data.warehouse,
-        semantic: data.semantic,
-        ontology: createOntologyClient(neon.ontologyTransport),
+        ontology: createOntologyClient(neon.ontologyTransport, data.aggregateTransport),
     };
 }
 /** Under Neon Auth the app has no SegmentStream session to call the API with. */
@@ -91,7 +89,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 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 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.",
     });
 }
 function notConfiguredHandlers() {

package/dist/data.d.ts

@@ -43,38 +43,39 @@ export interface WarehouseDryRun {
     readonly bytesProcessed: string | null;
     readonly maximumBytesBilled: string;
 }
-export interface SemanticQueryRequest {
-    readonly dimensions: readonly string[];
-    readonly measures: readonly string[];
-    readonly dateRange: {
+export interface AggregateRequest<Property extends string = string, Measure extends string = string, Temporal extends Property = Property> {
+    readonly dimensions: readonly Property[];
+    readonly measures: readonly Measure[];
+    readonly dateRange?: {
         readonly from: string;
         readonly to: string;
     };
+    readonly granularityOf?: Temporal;
     readonly granularity?: "day" | "week" | "month";
     readonly filters?: ReadonlyArray<{
-        readonly dimension: string;
+        readonly dimension: Property;
         readonly operator: "equals" | "in" | "isNull" | "isNotNull";
         readonly value?: string | number | boolean;
         readonly values?: ReadonlyArray<string | number | boolean>;
     }>;
     readonly orderBy?: ReadonlyArray<{
-        readonly measure?: string;
-        readonly dimension?: string;
+        readonly measure?: Measure;
+        readonly dimension?: Property;
         readonly direction: "asc" | "desc";
     }>;
     readonly limit?: number;
 }
-export interface SemanticField {
+export interface AggregateField {
     readonly name: string;
     readonly label: string;
     readonly type: string;
     readonly unit?: string;
     readonly format?: string;
 }
-export interface SemanticQueryResult<Row = Record<string, string | boolean | null>> {
+export interface AggregateResult<Row = Record<string, string | boolean | null>> {
     readonly deploymentId: string | null;
     readonly definitionDigest: string;
-    readonly fields: readonly SemanticField[];
+    readonly fields: readonly AggregateField[];
     readonly rows: Row[];
     readonly truncated: boolean;
     readonly execution: {
@@ -94,18 +95,6 @@ export interface WarehouseClient {
     /** Validates SQL and estimates bytes processed without running it. */
     readonly dryRun: (sql: string, options?: Pick<WarehouseQueryOptions, "params" | "maximumBytesBilled" | "signal">) => Promise<WarehouseDryRun>;
 }
-export interface SemanticClient {
-    readonly list: () => Promise<{
-        readonly deploymentId: string | null;
-        readonly models: readonly unknown[];
-    }>;
-    readonly get: (model: string) => Promise<{
-        readonly deploymentId: string | null;
-        readonly definitionDigest: string;
-        readonly model: unknown;
-    }>;
-    readonly query: <Row = Record<string, string | boolean | null>>(model: string, request: SemanticQueryRequest) => Promise<SemanticQueryResult<Row>>;
-}
 export interface DataClientDependencies {
     readonly config: ResolvedConfig;
     readonly fetch: Fetch;
@@ -122,5 +111,7 @@ export interface DataClientDependencies {
 export declare function createDataClient(dependencies: DataClientDependencies): {
     fetch: (path: string, init?: RequestInit) => Promise<Response>;
     warehouse: WarehouseClient;
-    semantic: SemanticClient;
+    aggregateTransport: {
+        fetch: (path: string, init: RequestInit) => Promise<Response>;
+    };
 };

package/dist/data.js

@@ -154,12 +154,14 @@ export function createDataClient(dependencies) {
             };
         },
     };
-    const semantic = {
-        list: () => call("GET", `${workspace}/semantic-models`),
-        get: (model) => call("GET", `${workspace}/semantic-models/${encodeURIComponent(model)}`),
-        query: (model, request) => call("POST", `${workspace}/semantic-models/${encodeURIComponent(model)}/query`, request),
+    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, semantic };
+    return { fetch: apiFetch, warehouse, aggregateTransport };
 }
 function bytesLimit(value) {
     if (value === undefined) {

package/dist/errors.js

@@ -35,7 +35,11 @@ export function apiErrorFrom(status, payload, fallbackDetail) {
         code: typeof body.error === "string" ? body.error : `http_${status}`,
         status,
         detail: typeof body.detail === "string" ? body.detail : fallbackDetail,
-        requestId: typeof body.requestId === "string" ? body.requestId : undefined,
+        requestId: typeof body.request_id === "string"
+            ? body.request_id
+            : typeof body.requestId === "string"
+                ? body.requestId
+                : undefined,
         retryable: typeof body.retryable === "boolean" ? body.retryable : status >= 500 || status === 429,
         issues: issuesFrom(body.issues),
     });

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export type { AuthenticationMethod, SegmentStreamApp } from "./app.js";
 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, 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, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
 export type { PermissionHolder } from "./permissions.js";
-export type { SemanticClient, SemanticField, SemanticQueryRequest, SemanticQueryResult, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
+export type { AggregateField, AggregateRequest, AggregateResult, 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-wire.d.ts

@@ -0,0 +1,33 @@
+import type { OntologyQuery, Where } from "./ontology.js";
+interface CatalogProperty {
+    readonly name: string;
+    readonly type: string;
+}
+interface CatalogRelationship {
+    readonly name: string;
+    readonly to: string;
+    readonly inverse: string;
+    readonly cardinality: string;
+}
+interface CatalogEntity {
+    readonly name: string;
+    readonly properties: ReadonlyArray<CatalogProperty>;
+    readonly relationships: ReadonlyArray<CatalogRelationship>;
+}
+export interface WireCatalog {
+    readonly hash?: string;
+    readonly entities: ReadonlyArray<CatalogEntity>;
+}
+/** Catalog metadata distinguishes relationship filters from opaque JSON property values. */
+export declare function encodeWhere(input: {
+    readonly where: Where | undefined;
+    readonly entity: string;
+    readonly getCatalog: () => Promise<WireCatalog>;
+}): Promise<Where | undefined>;
+export declare function queryToWire(query: OntologyQuery): unknown;
+export declare function responseFromWire(input: {
+    readonly method: "GET" | "POST";
+    readonly path: string;
+    readonly payload: unknown;
+}): unknown;
+export {};

package/dist/ontology-wire.js

@@ -0,0 +1,161 @@
+const FILTER_OPERATORS = [
+    "eq",
+    "ne",
+    "in",
+    "isNull",
+    "contains",
+    "startsWith",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "between",
+];
+const SYSTEM_FIELDS = ["id", "created_at", "updated_at", "created_by", "updated_by"];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function needsOperatorEncoding(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "isNull" || key === "startsWith") {
+            return true;
+        }
+        if (needsOperatorEncoding(child)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Catalog metadata distinguishes relationship filters from opaque JSON property values. */
+export async function encodeWhere(input) {
+    const { where, entity, getCatalog } = input;
+    if (where === undefined || !needsOperatorEncoding(where)) {
+        return where;
+    }
+    const catalog = await getCatalog();
+    return whereFromCatalog({ where, entity, catalog });
+}
+function whereFromCatalog(input) {
+    const { where, entity, catalog } = input;
+    const definition = catalog.entities.find((candidate) => candidate.name === entity);
+    const encodedWhere = Object.create(null);
+    for (const [field, condition] of Object.entries(where)) {
+        if (field === "and" || field === "or") {
+            const conditions = condition;
+            encodedWhere[field] = conditions.map((child) => whereFromCatalog({ where: child, entity, catalog }));
+            continue;
+        }
+        if (field === "not") {
+            encodedWhere[field] = whereFromCatalog({ where: condition, entity, catalog });
+            continue;
+        }
+        const relationship = relationshipTarget({ field, entity, definition, catalog });
+        if (relationship !== undefined && isRecord(condition)) {
+            encodedWhere[field] = relationshipFilterToWire({ condition, relationship, catalog });
+            continue;
+        }
+        encodedWhere[field] = fieldFilterToWire({ field, condition, definition });
+    }
+    return encodedWhere;
+}
+function relationshipTarget(input) {
+    const { field, entity, definition, catalog } = input;
+    const forward = definition?.relationships.find((candidate) => candidate.name === field);
+    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);
+        if (inverse !== undefined) {
+            return { entity: candidate.name, many: true };
+        }
+    }
+    return undefined;
+}
+function relationshipFilterToWire(input) {
+    const { condition, relationship, catalog } = input;
+    const entity = relationship.entity;
+    if (!relationship.many) {
+        return whereFromCatalog({ where: condition, entity, catalog });
+    }
+    const encodedQuantifiers = Object.create(null);
+    for (const [quantifier, child] of Object.entries(condition)) {
+        encodedQuantifiers[quantifier] = whereFromCatalog({ where: child, entity, catalog });
+    }
+    return encodedQuantifiers;
+}
+function isGeneratedField(field, definition) {
+    if (SYSTEM_FIELDS.includes(field)) {
+        return true;
+    }
+    return (definition?.relationships.some((relationship) => relationship.cardinality === "one" && `${relationship.name}_id` === field) ?? false);
+}
+function fieldFilterToWire(input) {
+    const { field, condition, definition } = input;
+    if (!isRecord(condition)) {
+        return condition;
+    }
+    const property = definition?.properties.find((candidate) => candidate.name === field);
+    if (property === undefined && !isGeneratedField(field, definition)) {
+        return condition;
+    }
+    const operatorFilter = Object.keys(condition).every((operator) => FILTER_OPERATORS.includes(operator));
+    if (property?.type === "json" && !operatorFilter) {
+        return condition;
+    }
+    const encodedFilter = Object.create(null);
+    for (const [operator, operand] of Object.entries(condition)) {
+        encodedFilter[operatorToWire(operator)] = operand;
+    }
+    return encodedFilter;
+}
+function operatorToWire(operator) {
+    if (operator === "isNull") {
+        return "is_null";
+    }
+    if (operator === "startsWith") {
+        return "starts_with";
+    }
+    return operator;
+}
+export function queryToWire(query) {
+    const { orderBy, where, ...rest } = query;
+    return {
+        ...rest,
+        ...(orderBy === undefined ? {} : { order_by: orderBy }),
+        ...(where === undefined ? {} : { where }),
+    };
+}
+function isPagedRoute(method, route) {
+    if (route.endsWith("/history")) {
+        return true;
+    }
+    if (method === "POST") {
+        return route.endsWith("/query");
+    }
+    const segments = route.split("/").filter(Boolean);
+    return segments.length === 1;
+}
+function historyEntryFromWire(item) {
+    const { record_id: recordId, action_id: actionId, principal_id: principalId, ...entry } = item;
+    return { ...entry, recordId, actionId, principalId };
+}
+export function responseFromWire(input) {
+    const { method, path, payload } = input;
+    if (!isRecord(payload)) {
+        return payload;
+    }
+    const route = path.split("?")[0] ?? "";
+    if (!isPagedRoute(method, route) || !Object.hasOwn(payload, "next_cursor")) {
+        return payload;
+    }
+    const { next_cursor: nextCursor, ...page } = payload;
+    if (!route.endsWith("/history") || !Array.isArray(page.items)) {
+        return { ...page, nextCursor };
+    }
+    const items = page.items.map(historyEntryFromWire);
+    return { ...page, nextCursor, items };
+}

package/dist/ontology.d.ts

@@ -1,3 +1,4 @@
+import type { AggregateRequest, AggregateResult } 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
@@ -185,18 +186,30 @@ type ResultOf<A> = A extends {
 type ActionClients<A> = {
     readonly [K in keyof A & string]: ActionCall<InputOf<A[K]>, ResultOf<A[K]>>;
 };
+type PropertiesOf<E> = E extends {
+    readonly properties: infer P;
+} ? P : never;
+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 {
+    readonly definition: {
+        readonly source: object;
+    };
+} ? AggregateEntityClient<keyof PropertiesOf<E> & string, MeasuresOf<E>> : EntityClient<RecordOf<E>, ActionClients<ActionsOf<E>>>;
 type TypedOntologyClient<O> = {
-    readonly [N in NameOf<EntitiesOf<O>>]: EntityClient<RecordOf<Extract<EntitiesOf<O>, {
-        readonly name: N;
-    }>>, ActionClients<ActionsOf<Extract<EntitiesOf<O>, {
+    readonly [N in NameOf<EntitiesOf<O>>]: ClientOf<Extract<EntitiesOf<O>, {
         readonly name: N;
-    }>>>>;
+    }>>;
 };
 /** A client for any entity, when the app passes no ontology type. */
 export type UntypedOntologyClient = {
     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
@@ -209,9 +222,9 @@ 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/changeStatus`.
+ * they are used: `ontology.lead.actions.change_status(…)` posts to `lead/actions/change_status`.
  */
-export declare function createOntologyClient<O>(transport: OntologyTransport): OntologyClient<O>;
+export declare function createOntologyClient<O>(transport: OntologyTransport, aggregateTransport?: 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,6 +1,7 @@
 import { SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
+import { encodeWhere, queryToWire, responseFromWire } from "./ontology-wire.js";
 const ENTITY_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
-const ACTION_NAME = /^[a-z][a-zA-Z0-9]*$/;
+const ACTION_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
 /** Names a caller may probe on any object; never an entity or an action. */
 const RESERVED = new Set([
     "then",
@@ -17,10 +18,11 @@ 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/changeStatus`.
+ * they are used: `ontology.lead.actions.change_status(…)` posts to `lead/actions/change_status`.
  */
-export function createOntologyClient(transport) {
+export function createOntologyClient(transport, aggregateTransport) {
     const entities = new Map();
+    const catalogReader = createCatalogReader(transport);
     return new Proxy(Object.create(null), {
         get(_target, property) {
             if (typeof property !== "string" || RESERVED.has(property) || !ENTITY_NAME.test(property)) {
@@ -28,21 +30,60 @@ export function createOntologyClient(transport) {
             }
             let client = entities.get(property);
             if (client === undefined) {
-                client = entityClient(property, transport);
+                client = {
+                    ...entityClient(property, catalogReader.transport, catalogReader.getCatalog),
+                    aggregate: (request, options = {}) => {
+                        if (!aggregateTransport) {
+                            throw new TypeError("An aggregate transport is required.");
+                        }
+                        return send(aggregateTransport, "POST", `/${property}/aggregate`, request, options.signal);
+                    },
+                };
                 entities.set(property, client);
             }
             return client;
         },
     });
 }
-function entityClient(entity, transport) {
+function createCatalogReader(transport) {
+    let catalogPromise;
+    let catalogHash;
+    const observedTransport = {
+        async fetch(path, init) {
+            const response = await transport.fetch(path, init);
+            const hash = response.headers.get("x-ontology-hash");
+            if (catalogHash !== undefined && hash !== null && hash !== catalogHash) {
+                catalogPromise = undefined;
+                catalogHash = undefined;
+            }
+            return response;
+        },
+    };
+    async function readCatalog() {
+        try {
+            const catalog = await send(observedTransport, "GET", "", undefined, undefined);
+            catalogHash = catalog.hash;
+            return catalog;
+        }
+        catch (error) {
+            catalogPromise = undefined;
+            throw error;
+        }
+    }
+    function getCatalog() {
+        catalogPromise ??= readCatalog();
+        return catalogPromise;
+    }
+    return { transport: observedTransport, getCatalog };
+}
+function entityClient(entity, transport, getCatalog) {
     const base = `/${entity}`;
     const actionCalls = new Map();
     const runAction = (name, input, options = {}) => send(transport, "POST", `${base}/actions/${encodeURIComponent(name)}`, {
         input,
         ...(options.validateOnly === undefined
             ? {}
-            : { options: { validateOnly: options.validateOnly } }),
+            : { options: { validate_only: options.validateOnly } }),
     }, options.signal);
     const actions = new Proxy(Object.create(null), {
         get(_target, property) {
@@ -58,11 +99,15 @@ function entityClient(entity, transport) {
         },
     });
     return {
-        find: (query = {}, options = {}) => {
-            const search = findParameters(query).toString();
+        find: async (query = {}, options = {}) => {
+            const where = await encodeWhere({ where: query.where, entity, getCatalog });
+            const search = findParameters({ ...query, where }).toString();
             return send(transport, "GET", search === "" ? base : `${base}?${search}`, undefined, options.signal);
         },
-        query: (query = {}, options = {}) => send(transport, "POST", `${base}/query`, query, options.signal),
+        query: async (query = {}, options = {}) => {
+            const where = await encodeWhere({ where: query.where, entity, getCatalog });
+            return send(transport, "POST", `${base}/query`, queryToWire({ ...query, where }), options.signal);
+        },
         get: (id, options = {}) => send(transport, "GET", `${base}/${recordId(id)}`, undefined, options.signal),
         history: (id, options = {}) => {
             const search = new URLSearchParams();
@@ -98,7 +143,7 @@ export function findParameters(query) {
         search.set("where", JSON.stringify(query.where));
     }
     if (query.orderBy !== undefined && query.orderBy.length > 0) {
-        search.set("orderBy", query.orderBy.map(({ field, direction }) => `${field}:${direction ?? "asc"}`).join(","));
+        search.set("order_by", query.orderBy.map(({ field, direction }) => `${field}:${direction ?? "asc"}`).join(","));
     }
     if (query.include !== undefined) {
         const relationships = Object.keys(query.include).filter((name) => query.include?.[name] === true);
@@ -137,5 +182,5 @@ async function send(transport, method, path, body, signal) {
             retryable: true,
         });
     }
-    return payload;
+    return responseFromWire({ method, path, payload });
 }

package/dist/permissions.js

@@ -8,8 +8,8 @@
  * ontology runtime. Keep the two in step.
  */
 const WILDCARD = "*";
-/** `<entity>:<verb>` with lowercase snake_case entities and lower camelCase verbs, or `*` for either. */
-const PERMISSION = /^(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*)$/;
+/** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
+const PERMISSION = /^(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
 function parsePermission(value) {
     if (typeof value !== "string") {
         return undefined;

package/package.json

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