@segmentstream-cloud/app 0.13.2 → 0.15.0

package/README.md

@@ -412,8 +412,8 @@ One authorization model covers the ontology: every `segmentstream.ontology` call
 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
+`segmentstream.warehouse` uses the workspace app credential and reaches the whole workspace
+warehouse. The job helpers below use it for explicitly opted-in jobs. `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.
 
@@ -446,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" }],
 });
 ```
 
@@ -465,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`.
@@ -486,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",
 });
@@ -519,6 +519,74 @@ 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`.
+
+## Start a pipeline job
+
+With app SDK 0.15.0 and pipeline SDK 0.1.0a65 or later, opt in a job and deploy it:
+
+```python
+s.job("land_watch", assets=[land_checks], allow_app_runs=True)
+```
+
+In server code, check the user's role or permissions before calling on their behalf:
+
+```ts
+const user = await segmentstream.requireUser();
+if (!user.roles.includes("operator")) {
+  throw new Error("An operator role is required.");
+}
+
+const run = await segmentstream.jobs.run("land_watch");
+// From a later authorized request, for example a Route Handler the page polls:
+const current = await segmentstream.jobs.getRun(run.id);
+const recent = await segmentstream.jobs.listRuns("land_watch");
+```
+
+The helpers use the workspace app credential, read on every call, or fall back to the
+legacy member session. Credential access defaults to denied unless the current deployed
+job sets `allow_app_runs=True`. It stays within the workspace and permits submission and
+status/history reads; run logs, activity and cancellation require platform membership.
+Removing the flag revokes app access to that job's runs.
+
+`run()` returns immediately with a run ID and status. It generates a UUID idempotency key
+unless passed `{ idempotencyKey }`; reuse an explicit key when retrying one button action.
+Separate calls with new keys can run concurrently. Partitioned jobs accept
+`{ partitionRange: { startDate, endDate } }`. All helpers accept an optional `signal`.
+Poll `getRun()` until status is `succeeded`, `failed` or `cancelled`, and tolerate future
+status values. Protect both submission and status routes with your app's authorization.
+See [app data access](../../docs/app-data.md#start-a-pipeline-job-from-the-app) for a Route Handler.
+
 ## How requests are handled
 
 - Page navigations without a session are redirected to `/sign-in?returnTo=<path>` and
@@ -534,7 +602,7 @@ const { rows, execution } = await segmentstream.ontology.aggregate({
 | -------------------------------------- | ------------------------------------------------------------------------------- |
 | `NEON_AUTH_BASE_URL`                   | The workspace's Neon Auth URL. Set: sign in with Neon Auth. Unset: 0.2 sign-in. |
 | `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET` | 32 or more characters; signs the session cache cookie. Required with Neon Auth. |
-| `SEGMENTSTREAM_APP_CREDENTIAL`         | The workspace app credential for warehouse queries.                             |
+| `SEGMENTSTREAM_APP_CREDENTIAL`         | The workspace app credential for warehouse queries and opted-in pipeline jobs.  |
 | `SEGMENTSTREAM_ONTOLOGY_URL`           | Optional: the ontology service when it does not run beside the app.             |
 | `SEGMENTSTREAM_URL`                    | SegmentStream origin. Defaults to `https://cloud.segmentstream.com`.            |
 
@@ -629,3 +697,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/app.d.ts

@@ -1,6 +1,7 @@
 import type { Environment, SegmentStreamAppConfig } from "./config.js";
 import type { AgentIdentities } from "./agent.js";
 import type { WarehouseClient } from "./data.js";
+import type { JobsClient } from "./jobs.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
 import type { AgentAuthorizations } from "./oauth.js";
 import type { AuthRouteHandlers, CreateNeonAuth, SignOutOptions } from "./neon.js";
@@ -46,6 +47,8 @@ export interface SegmentStreamApp<O = unknown> {
      * (`SEGMENTSTREAM_APP_CREDENTIAL`) when it is set, else the signed-in member's session.
      */
     readonly warehouse: WarehouseClient;
+    /** Start and read pipeline runs with the workspace credential. Server-only; gate app users. */
+    readonly jobs: JobsClient;
     /** The app's ontology service, `/api/ontology`, as the signed-in user. Server-only. */
     readonly ontology: OntologyClient<O>;
     /**

package/dist/app.js

@@ -57,6 +57,7 @@ export function createApp(config, dependencies = {}) {
             getAccessToken: legacy.getAccessToken,
             fetch: data.fetch,
             warehouse: data.warehouse,
+            jobs: data.jobs,
             ontology: createOntologyClient(ontologyTransport),
             oauth: createAgentAuthorizations(ontologyTransport),
             agent: createAgentIdentities(ontologyTransport),
@@ -87,6 +88,7 @@ export function createApp(config, dependencies = {}) {
         getAccessToken: async () => null,
         fetch: data.fetch,
         warehouse: data.warehouse,
+        jobs: data.jobs,
         ontology: createOntologyClient(neon.ontologyTransport),
         oauth: createAgentAuthorizations(neon.ontologyTransport),
         agent: createAgentIdentities(neon.ontologyTransport),
@@ -97,7 +99,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 opted-in job runs need SEGMENTSTREAM_APP_CREDENTIAL, which SegmentStream sets on deploy. Generic fetch requires a legacy SegmentStream session.",
     });
 }
 function notConfiguredHandlers() {

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;
@@ -207,7 +214,7 @@ export interface DataClientDependencies {
     readonly getAccessToken: () => Promise<string | null>;
     /**
      * The workspace app credential, `SEGMENTSTREAM_APP_CREDENTIAL`, read on every call. The API
-     * accepts it for warehouse queries and their results; without it they use the session token.
+     * accepts it for warehouse queries and opted-in job runs; otherwise they use the session token.
      */
     readonly getAppCredential?: () => string | undefined;
     readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
@@ -217,4 +224,5 @@ export interface DataClientDependencies {
 export declare function createDataClient(dependencies: DataClientDependencies): {
     fetch: (path: string, init?: RequestInit) => Promise<Response>;
     warehouse: WarehouseClient;
+    jobs: import("./jobs.js").JobsClient;
 };

package/dist/data.js

@@ -1,5 +1,6 @@
 import { SegmentStreamApiError, readJson } from "./errors.js";
 import { encodeParameters } from "./parameters.js";
+import { createJobsClient } from "./jobs.js";
 export { SegmentStreamApiError } from "./errors.js";
 const REQUEST_TIMEOUT_MS = 45_000;
 const DEFAULT_MAX_ROWS = 10_000;
@@ -17,8 +18,8 @@ export function createDataClient(dependencies) {
     function apiFetch(path, init = {}) {
         return authorizedFetch(path, init, dependencies.getAccessToken);
     }
-    /** Warehouse queries prefer the app's own credential, which needs no SegmentStream session. */
-    async function warehouseToken() {
+    /** Workspace operations prefer the app credential, which needs no SegmentStream session. */
+    async function workspaceToken() {
         return dependencies.getAppCredential?.() ?? dependencies.getAccessToken();
     }
     async function authorizedFetch(path, init, getToken) {
@@ -122,7 +123,7 @@ export function createDataClient(dependencies) {
             parameters: encodeParameters(options.params),
             ...bytesLimit(options.maximumBytesBilled),
             pageSize: bounds.pageSize,
-        }, options.signal, warehouseToken);
+        }, options.signal, workspaceToken);
         return collect(page, bounds, options.signal);
     }
     async function result(queryId, options = {}) {
@@ -135,7 +136,7 @@ export function createDataClient(dependencies) {
         if (pageToken !== undefined) {
             search.set("pageToken", pageToken);
         }
-        return call("GET", `${workspace}/warehouse/queries/${encodeURIComponent(queryId)}?${search.toString()}`, undefined, signal, warehouseToken);
+        return call("GET", `${workspace}/warehouse/queries/${encodeURIComponent(queryId)}?${search.toString()}`, undefined, signal, workspaceToken);
     }
     const warehouse = {
         query,
@@ -146,7 +147,7 @@ export function createDataClient(dependencies) {
                 parameters: encodeParameters(options.params),
                 ...bytesLimit(options.maximumBytesBilled),
                 dryRun: true,
-            }, options.signal, warehouseToken);
+            }, options.signal, workspaceToken);
             return {
                 columns: page.columns,
                 bytesProcessed: page.bytesProcessed ?? null,
@@ -154,7 +155,11 @@ export function createDataClient(dependencies) {
             };
         },
     };
-    return { fetch: apiFetch, warehouse };
+    const jobs = createJobsClient({
+        workspace,
+        fetch: (path, init) => authorizedFetch(path, init, workspaceToken),
+    });
+    return { fetch: apiFetch, warehouse, jobs };
 }
 function bytesLimit(value) {
     if (value === undefined) {

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./agent.js";
 export type { AgentIdentities, AgentIdentity, AgentPairing } from "./agent.js";
 export type { AgentAuthorizationRequest, AgentAuthorizations, AgentScope } from "./oauth.js";
 export type { ApiIssue } from "./errors.js";
+export type { JobReadOptions, JobRun, JobRunOptions, JobsClient } from "./jobs.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, ModelAggregateClient, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";

package/dist/jobs.d.ts

@@ -0,0 +1,49 @@
+/** A pipeline run, returned immediately by `run()` and refreshed with `getRun()`. */
+export interface JobRun {
+    readonly id: string;
+    readonly deploymentId: string;
+    readonly jobName: string;
+    /** `queued`, `starting`, `running`, `succeeded`, `failed` or `cancelled`; future values are accepted. */
+    readonly status: string;
+    readonly trigger: string;
+    readonly partitionRange?: {
+        readonly startDate: string;
+        readonly endDate: string;
+    };
+    readonly failure?: {
+        readonly code: string;
+        readonly detail: string;
+        readonly retryable: boolean;
+        readonly reference: string;
+    };
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly startedAt?: string;
+    readonly completedAt?: string;
+}
+export interface JobRunOptions {
+    /** Reuse the same key when retrying one submission. Defaults to a new UUID for each call. */
+    readonly idempotencyKey?: string;
+    readonly partitionRange?: {
+        readonly startDate: string;
+        readonly endDate: string;
+    };
+    readonly signal?: AbortSignal;
+}
+export interface JobReadOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * Server-only pipeline execution. The workspace credential can start and read only jobs deployed
+ * with `allow_app_runs=True`. Check the app user's permissions before calling on their behalf.
+ */
+export interface JobsClient {
+    /** Submit a run without waiting for completion. */
+    readonly run: (jobName: string, options?: JobRunOptions) => Promise<JobRun>;
+    readonly getRun: (runId: string, options?: JobReadOptions) => Promise<JobRun>;
+    readonly listRuns: (jobName: string, options?: JobReadOptions) => Promise<readonly JobRun[]>;
+}
+export declare function createJobsClient(dependencies: {
+    readonly workspace: string;
+    readonly fetch: (path: string, init: RequestInit) => Promise<Response>;
+}): JobsClient;

package/dist/jobs.js

@@ -0,0 +1,40 @@
+import { apiErrorFrom, readJson } from "./errors.js";
+export function createJobsClient(dependencies) {
+    async function request(path, init) {
+        const response = await dependencies.fetch(path, init);
+        const payload = await readJson(response);
+        if (!response.ok) {
+            throw apiErrorFrom(response.status, payload, "SegmentStream rejected the job request.");
+        }
+        return payload;
+    }
+    return {
+        async run(jobName, options = {}) {
+            const key = options.idempotencyKey?.trim() ?? crypto.randomUUID();
+            if (!/^[A-Za-z0-9._:-]{8,128}$/.test(key)) {
+                throw new TypeError("idempotencyKey must be 8–128 letters, numbers, dots, underscores, colons or hyphens.");
+            }
+            const { run } = await request(`${dependencies.workspace}/jobs/${segment(jobName, "jobName")}/runs`, {
+                method: "POST",
+                headers: { "content-type": "application/json", "idempotency-key": key },
+                body: JSON.stringify(options.partitionRange ? { partitionRange: options.partitionRange } : {}),
+                signal: options.signal,
+            });
+            return run;
+        },
+        async getRun(runId, options = {}) {
+            const { run } = await request(`${dependencies.workspace}/runs/${segment(runId, "runId")}?includeTrigger=true`, { method: "GET", signal: options.signal });
+            return run;
+        },
+        async listRuns(jobName, options = {}) {
+            const { runs } = await request(`${dependencies.workspace}/jobs/${segment(jobName, "jobName")}/runs?includeTrigger=true`, { method: "GET", signal: options.signal });
+            return runs;
+        },
+    };
+}
+function segment(value, name) {
+    if (!value || value === "." || value === "..") {
+        throw new TypeError(`${name} must be a non-empty identifier.`);
+    }
+    return encodeURIComponent(value);
+}

package/dist/ontology.d.ts

@@ -252,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>;
 /**
@@ -275,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

@@ -247,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 {
@@ -258,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.2",
+  "version": "0.15.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",