@segmentstream-cloud/app 0.4.0 → 0.5.0

package/README.md

@@ -325,10 +325,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 +386,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 +409,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/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.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
@@ -211,7 +224,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/changeStatus`.
  */
-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

@@ -19,7 +19,7 @@ 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`.
  */
-export function createOntologyClient(transport) {
+export function createOntologyClient(transport, aggregateTransport) {
     const entities = new Map();
     return new Proxy(Object.create(null), {
         get(_target, property) {
@@ -28,7 +28,14 @@ export function createOntologyClient(transport) {
             }
             let client = entities.get(property);
             if (client === undefined) {
-                client = entityClient(property, transport);
+                client = {
+                    ...entityClient(property, transport),
+                    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;

package/package.json

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