@segmentstream-cloud/app 0.14.0 → 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.
 
@@ -529,9 +529,7 @@ const { fields, rows } = await segmentstream.ontology.aggregate({
   dimensions: ["acmeSales.orderDate"],
   granularity: "month",
   granularityOf: "acmeSales.orderDate",
-  filters: [
-    { dimension: "acmeSales.orderDate", operator: "inPeriod", value: "this year to date" },
-  ],
+  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,
@@ -553,6 +551,42 @@ const { fields, rows } = await segmentstream.ontology.aggregate({
   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
@@ -568,7 +602,7 @@ const { fields, rows } = 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`.            |
 

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

@@ -214,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>;
@@ -224,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/package.json

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