@segmentstream/app 0.0.0-stage → 0.38.1

package/dist/data.d.ts

@@ -0,0 +1,233 @@
+import type { ResolvedConfig } from "./config.js";
+import type { QueryParameters } from "./parameters.js";
+import type { Fetch } from "./sessions.js";
+export { SegmentStreamApiError } from "./errors.js";
+export type WarehouseValue = string | number | boolean | null;
+export type WarehouseRow = Record<string, WarehouseValue>;
+export interface WarehouseColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly mode: string;
+    readonly description: string;
+}
+/** How much of a query result to wait for and collect. */
+export interface WarehouseReadOptions {
+    /** Rows to collect across pages before stopping. Defaults to 10,000. */
+    readonly maxRows?: number;
+    /** Rows per API page, 1–1,000. Defaults to the smaller of `maxRows` and 1,000. */
+    readonly pageSize?: number;
+    /** How long to wait for a running query. Defaults to 60 seconds. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface WarehouseQueryOptions extends WarehouseReadOptions {
+    /** Values for named `@parameters` in the SQL. Never interpolate values into the SQL text. */
+    readonly params?: QueryParameters;
+    /** Lowers the workspace's per-query byte ceiling for this query. */
+    readonly maximumBytesBilled?: number | bigint | string;
+}
+export interface WarehouseQueryResult<Row = WarehouseRow> {
+    readonly queryId: string | null;
+    readonly columns: readonly WarehouseColumn[];
+    readonly rows: Row[];
+    /** Rows in the full result, which may exceed `rows` when `truncated`. */
+    readonly totalRows: number | null;
+    /** True when more rows exist than `maxRows` allowed. */
+    readonly truncated: boolean;
+    readonly bytesProcessed: string | null;
+    readonly bytesBilled: string | null;
+    readonly cacheHit: boolean | null;
+}
+export interface WarehouseDryRun {
+    readonly columns: readonly WarehouseColumn[];
+    readonly bytesProcessed: string | null;
+    readonly maximumBytesBilled: string;
+}
+/**
+ * The filter operators of both metric queries. `equals` and `notEquals` take one `value`; `in` and
+ * `notIn` take 1–100 `values`; `isNull` and `isNotNull` take none. `notEquals` and `notIn` also
+ * match nulls and rows whose relationship found no target, so they are the exact complements of
+ * `equals` and `in`. `gt`, `gte`, `lt` and `lte` compare a date, timestamp or number dimension
+ * with one `value`; a date bound on a timestamp covers whole days. `contains`, `startsWith` and
+ * `endsWith` match one non-empty string in a text dimension, case-sensitively, without wildcards.
+ */
+export type MetricQueryFilterOperator = "equals" | "in" | "notEquals" | "notIn" | "isNull" | "isNotNull" | "gt" | "gte" | "lt" | "lte" | "contains" | "startsWith" | "endsWith";
+/** How a date or timestamp dimension is bucketed. `hour` needs a timestamp and yields one. */
+export type MetricQueryGranularity = "hour" | "day" | "week" | "month" | "quarter" | "year";
+type CalendarUnit = "week" | "month" | "quarter" | "year";
+/**
+ * A period relative to today, which the platform resolves to two inclusive dates: `today`,
+ * `yesterday`; the whole current or previous week, month, quarter or year (`this month`,
+ * `last quarter`); the current one through today (`this year to date`); the N days ending
+ * yesterday (`last 7 days`); or the N whole weeks, months, quarters or years before the current
+ * one (`last 4 weeks`). N is at least 1, weeks start on Monday, and a period covers at most 3660
+ * days.
+ */
+export type RelativePeriod = "today" | "yesterday" | `this ${CalendarUnit}` | `this ${CalendarUnit} to date` | `last ${CalendarUnit}` | `last ${number} ${"days" | "weeks" | "months" | "quarters" | "years"}`;
+/**
+ * A metric query of one entity: its metrics, grouped by dimensions. Dimensions, filters and
+ * ordering name the entity's own properties, or a related entity's property through to-one
+ * relationships: `Path`, such as `product.brand`.
+ */
+export interface EntityMetricQuery<Property extends string = string, Metric extends string = string, Temporal extends Property = Property, Path extends string = never> {
+    readonly dimensions: readonly (Property | Path)[];
+    readonly metrics: readonly Metric[];
+    /** The only partition bound this request takes: it has neither `between` nor `inPeriod`. */
+    readonly dateRange?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    /** The selected date or timestamp dimension to bucket, which may be a related one. */
+    readonly granularityOf?: Temporal | Path;
+    readonly granularity?: MetricQueryGranularity;
+    /**
+     * An IANA timezone, such as `Europe/Moscow`, or `UTC`. It replaces the entities' timezones for
+     * timestamp buckets and date bounds on timestamps; metric conditions keep their own.
+     */
+    readonly timezone?: string;
+    readonly filters?: ReadonlyArray<{
+        readonly dimension: Property | Path;
+        readonly operator: MetricQueryFilterOperator;
+        readonly value?: string | number | boolean;
+        readonly values?: ReadonlyArray<string | number | boolean>;
+    }>;
+    readonly orderBy?: ReadonlyArray<{
+        readonly metric?: Metric;
+        readonly dimension?: Property | Path;
+        readonly direction: "asc" | "desc";
+    }>;
+    readonly limit?: number;
+}
+/**
+ * A filter of a model-level metric query. Besides the shared operators, `between` takes two
+ * inclusive `values`, the lower first, and `inPeriod` a period relative to today as its `value`;
+ * the answer's `execution.periods` gives the dates it resolved to. Only these two bound a
+ * partitioned entity.
+ */
+export type MetricQueryFilter<Dimension extends string = string> = {
+    readonly dimension: Dimension;
+    readonly operator: MetricQueryFilterOperator | "between";
+    readonly value?: string | number | boolean;
+    readonly values?: ReadonlyArray<string | number | boolean>;
+} | {
+    readonly dimension: Dimension;
+    readonly operator: "inPeriod";
+    readonly value: RelativePeriod;
+    /** Never set; declared so code reading `values` from any filter still compiles. */
+    readonly values?: undefined;
+};
+/**
+ * A model-level metric query: metrics of one or more entities, as `entity.metric`, and model
+ * metrics, declared in `defineOntology({ metrics })`, by their bare names, grouped by
+ * `entity.property` dimensions. A dimension may instead be a route from a metric's entity,
+ * `entity.relationship.property`, which picks the way that entity reaches the property. Date bounds
+ * are `between` or `inPeriod` filters.
+ */
+export interface MetricQuery<Metric extends string = string, Dimension extends string = string> {
+    readonly metrics: readonly Metric[];
+    readonly dimensions?: readonly Dimension[];
+    readonly filters?: ReadonlyArray<MetricQueryFilter<Dimension>>;
+    readonly granularity?: MetricQueryGranularity;
+    /** The requested date or timestamp dimension to bucket by `granularity`. */
+    readonly granularityOf?: Dimension;
+    /**
+     * An IANA timezone, such as `Europe/Moscow`, or `UTC`. It replaces the entities' timezones for
+     * timestamp buckets, date bounds on timestamps and the today of `inPeriod`; metric conditions
+     * keep their own.
+     */
+    readonly timezone?: string;
+    readonly orderBy?: ReadonlyArray<{
+        readonly metric?: Metric;
+        readonly dimension?: Dimension;
+        readonly direction: "asc" | "desc";
+    }>;
+    /** Rows to return, 1–1000; 100 by default. */
+    readonly limit?: number;
+}
+/** A column of a metric query's answer: a dimension or a metric. */
+export interface MetricQueryField {
+    readonly name: string;
+    readonly label: string;
+    readonly type: string;
+    readonly unit?: string;
+    readonly format?: string;
+    /** On a metric: the filters applied to it. A filter its entity cannot reach is not listed. */
+    readonly filters?: readonly string[];
+    /** `false` on a metric whose rows don't add up to a total, such as a distinct count or ratio. */
+    readonly additive?: boolean;
+    /**
+     * On a balance metric: the date or timestamp dimension, as `entity.property`, whose days its
+     * rows snapshot. The request groups by it or filters it to one day.
+     */
+    readonly balanceOver?: string;
+    /**
+     * On a model metric: the entity metrics it reads, as `entity.metric`, 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[];
+}
+/** The answer to a metric query, per entity or model-level. */
+export interface MetricQueryResult<Row = Record<string, string | boolean | null>> {
+    readonly deploymentId: string | null;
+    readonly definitionDigest: string;
+    readonly fields: readonly MetricQueryField[];
+    readonly rows: Row[];
+    readonly truncated: boolean;
+    readonly execution: {
+        readonly elapsedMs: number;
+        readonly bytesProcessed?: string;
+        readonly bytesBilled?: string;
+        /**
+         * Data problems the query met, for example a join key that matched more than one record, and
+         * filters that did not apply to some metric's entity.
+         */
+        readonly warnings?: readonly string[];
+        /** The stored entities a query read, each with the time up to which its copy is complete. */
+        /** Historical server observations; current servers omit destination freshness metadata. */
+        readonly sources?: ReadonlyArray<{
+            readonly entity: string;
+            readonly asOf: string;
+        }>;
+        /**
+         * Each `inPeriod` filter in request order: its dimension as requested, its period, the
+         * inclusive dates it resolved to and the timezone whose today decided them.
+         */
+        readonly periods?: ReadonlyArray<{
+            readonly dimension: string;
+            readonly value: string;
+            readonly from: string;
+            readonly to: string;
+            readonly timezone: string;
+        }>;
+    };
+}
+export interface WarehouseClient {
+    /** Runs read-only SQL in the workspace warehouse as the signed-in user's app session. */
+    readonly query: <Row = WarehouseRow>(sql: string, options?: WarehouseQueryOptions) => Promise<WarehouseQueryResult<Row>>;
+    /**
+     * Resumes a query by ID from a later request. Queries keep running in the warehouse for
+     * up to an hour after `query()` stops waiting, and each request uses a fresh app token.
+     */
+    readonly result: <Row = WarehouseRow>(queryId: string, options?: WarehouseReadOptions) => Promise<WarehouseQueryResult<Row>>;
+    /** Validates SQL and estimates bytes processed without running it. */
+    readonly dryRun: (sql: string, options?: Pick<WarehouseQueryOptions, "params" | "maximumBytesBilled" | "signal">) => Promise<WarehouseDryRun>;
+}
+export interface DataClientDependencies {
+    readonly config: ResolvedConfig;
+    readonly fetch: Fetch;
+    readonly getAccessToken: () => Promise<string | null>;
+    /**
+     * The workspace app credential, `SEGMENTSTREAM_APP_CREDENTIAL`, read on every call. The API
+     * 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>;
+    readonly now?: () => number;
+}
+/** Server-side SegmentStream API access as the signed-in member. */
+export declare function createDataClient(dependencies: DataClientDependencies): {
+    fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    warehouse: WarehouseClient;
+    jobs: import("./jobs.js").JobsClient;
+};

package/dist/data.js

@@ -0,0 +1,206 @@
+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;
+const MAXIMUM_PAGE_SIZE = 1000;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const FIRST_POLL_MS = 500;
+const LONGEST_POLL_MS = 2000;
+/** Server-side SegmentStream API access as the signed-in member. */
+export function createDataClient(dependencies) {
+    const { config } = dependencies;
+    const workspace = `/api/v1/workspaces/${encodeURIComponent(config.workspaceId)}`;
+    const sleep = dependencies.sleep ?? defaultSleep;
+    const now = dependencies.now ?? Date.now;
+    /** Calls any SegmentStream API path as the signed-in member; the token never leaves the server. */
+    function apiFetch(path, init = {}) {
+        return authorizedFetch(path, init, dependencies.getAccessToken);
+    }
+    /** 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) {
+        if (!path.startsWith("/api/")) {
+            throw new TypeError('SegmentStream API paths start with "/api/", for example "/api/v1/me".');
+        }
+        const token = await getToken();
+        if (token === null) {
+            throw new SegmentStreamApiError({
+                code: "app_session_missing",
+                status: 401,
+                detail: "No signed-in SegmentStream session for this request; call SegmentStream from Server Components, Route Handlers, or Server Functions behind the SegmentStream proxy.",
+            });
+        }
+        const headers = new Headers(init.headers);
+        const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        headers.set("authorization", `Bearer ${token}`);
+        if (!headers.has("accept")) {
+            headers.set("accept", "application/json");
+        }
+        try {
+            return await dependencies.fetch(`${config.baseUrl}${path}`, {
+                ...init,
+                headers,
+                cache: "no-store",
+                redirect: "error",
+                signal: init.signal ? AbortSignal.any([init.signal, timeout]) : timeout,
+            });
+        }
+        catch (error) {
+            if (init.signal?.aborted) {
+                throw error;
+            }
+            throw new SegmentStreamApiError({
+                code: "segmentstream_unreachable",
+                status: 503,
+                detail: "SegmentStream could not be reached.",
+                retryable: true,
+            });
+        }
+    }
+    async function call(method, path, body, signal, getToken = dependencies.getAccessToken) {
+        const response = await authorizedFetch(path, {
+            method,
+            ...(body === undefined
+                ? {}
+                : { body: JSON.stringify(body), headers: { "content-type": "application/json" } }),
+            ...(signal ? { signal } : {}),
+        }, getToken);
+        const payload = await readJson(response);
+        if (!response.ok) {
+            throw errorFrom(response.status, payload);
+        }
+        return payload;
+    }
+    function limits(options) {
+        const maxRows = positiveInteger(options.maxRows ?? DEFAULT_MAX_ROWS, "maxRows");
+        const pageSize = positiveInteger(options.pageSize ?? Math.min(maxRows, MAXIMUM_PAGE_SIZE), "pageSize");
+        return { maxRows, pageSize, deadline: now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS) };
+    }
+    /** Waits for a running query, then follows pages up to `maxRows`. */
+    async function collect(first, { maxRows, pageSize, deadline }, signal) {
+        let page = first;
+        const queryId = page.id ?? null;
+        let wait = FIRST_POLL_MS;
+        while (page.state === "running") {
+            if (queryId === null || now() + wait > deadline) {
+                throw new SegmentStreamApiError({
+                    code: "query_timeout",
+                    status: 504,
+                    detail: "The query is still running; resume it from a later request with warehouse.result(queryId).",
+                    retryable: true,
+                    queryId: queryId ?? undefined,
+                });
+            }
+            await sleep(wait, signal);
+            wait = Math.min(wait * 2, LONGEST_POLL_MS);
+            page = (await read(queryId, pageSize, undefined, signal)).query;
+        }
+        const head = page;
+        const rows = [...page.rows];
+        while (page.nextPageToken !== undefined && rows.length < maxRows && queryId !== null) {
+            page = (await read(queryId, pageSize, page.nextPageToken, signal)).query;
+            rows.push(...page.rows);
+        }
+        return {
+            queryId,
+            columns: head.columns,
+            rows: rows.slice(0, maxRows),
+            totalRows: head.totalRows === undefined ? null : Number(head.totalRows),
+            truncated: rows.length > maxRows || page.nextPageToken !== undefined,
+            bytesProcessed: head.bytesProcessed ?? null,
+            bytesBilled: head.bytesBilled ?? null,
+            cacheHit: head.cacheHit ?? null,
+        };
+    }
+    async function query(sql, options = {}) {
+        const bounds = limits(options);
+        const { query: page } = await call("POST", `${workspace}/warehouse/queries`, {
+            sql,
+            parameters: encodeParameters(options.params),
+            ...bytesLimit(options.maximumBytesBilled),
+            pageSize: bounds.pageSize,
+        }, options.signal, workspaceToken);
+        return collect(page, bounds, options.signal);
+    }
+    async function result(queryId, options = {}) {
+        const bounds = limits(options);
+        const { query: page } = await read(queryId, bounds.pageSize, undefined, options.signal);
+        return collect(page, bounds, options.signal);
+    }
+    function read(queryId, pageSize, pageToken, signal) {
+        const search = new URLSearchParams({ pageSize: String(pageSize) });
+        if (pageToken !== undefined) {
+            search.set("pageToken", pageToken);
+        }
+        return call("GET", `${workspace}/warehouse/queries/${encodeURIComponent(queryId)}?${search.toString()}`, undefined, signal, workspaceToken);
+    }
+    const warehouse = {
+        query,
+        result,
+        dryRun: async (sql, options = {}) => {
+            const { query: page } = await call("POST", `${workspace}/warehouse/queries`, {
+                sql,
+                parameters: encodeParameters(options.params),
+                ...bytesLimit(options.maximumBytesBilled),
+                dryRun: true,
+            }, options.signal, workspaceToken);
+            return {
+                columns: page.columns,
+                bytesProcessed: page.bytesProcessed ?? null,
+                maximumBytesBilled: page.maximumBytesBilled,
+            };
+        },
+    };
+    const jobs = createJobsClient({
+        workspace,
+        fetch: (path, init) => authorizedFetch(path, init, workspaceToken),
+    });
+    return { fetch: apiFetch, warehouse, jobs };
+}
+function bytesLimit(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const text = String(value);
+    if (!/^[1-9][0-9]*$/.test(text)) {
+        throw new TypeError("maximumBytesBilled must be a positive whole number of bytes.");
+    }
+    return { maximumBytesBilled: text };
+}
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new TypeError(`${name} must be a positive integer.`);
+    }
+    return value;
+}
+function errorFrom(status, payload) {
+    const body = typeof payload === "object" && payload !== null ? payload : {};
+    return new SegmentStreamApiError({
+        code: typeof body.error === "string" ? body.error : `http_${status}`,
+        status,
+        detail: typeof body.detail === "string" ? body.detail : "SegmentStream rejected the request.",
+        requestId: typeof body.requestId === "string" ? body.requestId : undefined,
+        retryable: typeof body.retryable === "boolean" ? body.retryable : status >= 500,
+    });
+}
+function defaultSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}

package/dist/decision-pages.d.ts

@@ -0,0 +1,14 @@
+import { type SegmentStreamProxy } from "./proxy.js";
+export declare function isDecisionPage(pathname: string): boolean;
+/**
+ * The proxy, with the decision pages unframeable: no other site may show them in a frame and trick
+ * a member into clicking Allow or Approve. Every app gets this from the SDK, whatever its Next.js
+ * config says.
+ */
+export declare function withUnframeablePages(proxy: SegmentStreamProxy, frameAncestors?: string): SegmentStreamProxy;
+/**
+ * Whether a form post came from the app's own pages. A decision must never be made from another
+ * site, which could otherwise approve an agent in the member's name. Fetch Metadata describes
+ * the browser's public request even when a trusted proxy rewrites the server's request URL.
+ */
+export declare function isSameOrigin(request: Request): boolean;

package/dist/decision-pages.js

@@ -0,0 +1,87 @@
+import { isLoopbackHostname } from "./cookies.js";
+import { AGENT_CONNECT_PAGE, CONSENT_PAGE } from "./pages.js";
+import { matchesPathPrefix } from "./proxy.js";
+/** Pages where a signed-in member lets an agent act for them. */
+const DECISION_PAGES = [CONSENT_PAGE, AGENT_CONNECT_PAGE, "/sign-in", "/api/oauth/consent"];
+export function isDecisionPage(pathname) {
+    return DECISION_PAGES.some((page) => matchesPathPrefix(pathname, page));
+}
+/**
+ * The proxy, with the decision pages unframeable: no other site may show them in a frame and trick
+ * a member into clicking Allow or Approve. Every app gets this from the SDK, whatever its Next.js
+ * config says.
+ */
+export function withUnframeablePages(proxy, frameAncestors) {
+    return async (request) => {
+        const response = await proxy(request);
+        const pathname = request.nextUrl.pathname;
+        if (isDecisionPage(pathname)) {
+            response.headers.set("cache-control", "no-store");
+            response.headers.set("referrer-policy", "no-referrer");
+            response.headers.set("x-frame-options", "DENY");
+            const policy = response.headers.get("content-security-policy");
+            response.headers.set("content-security-policy", policy === null
+                ? "frame-ancestors 'none'"
+                : policy.replace(/frame-ancestors[^;]*/g, "frame-ancestors 'none'") +
+                    (policy.includes("frame-ancestors") ? "" : "; frame-ancestors 'none'"));
+        }
+        else if (frameAncestors &&
+            !["/api", "/mcp", "/.well-known", "/_next"].some((path) => matchesPathPrefix(pathname, path))) {
+            const policy = response.headers.get("content-security-policy");
+            const ancestors = `frame-ancestors ${frameAncestors}`;
+            response.headers.delete("x-frame-options");
+            response.headers.set("content-security-policy", policy === null
+                ? ancestors
+                : policy.replace(/frame-ancestors[^;]*/g, ancestors) +
+                    (policy.includes("frame-ancestors") ? "" : `; ${ancestors}`));
+        }
+        return response;
+    };
+}
+/**
+ * Whether a form post came from the app's own pages. A decision must never be made from another
+ * site, which could otherwise approve an agent in the member's name. Fetch Metadata describes
+ * the browser's public request even when a trusted proxy rewrites the server's request URL.
+ */
+export function isSameOrigin(request) {
+    const site = request.headers.get("sec-fetch-site");
+    if (site !== null) {
+        return site === "same-origin";
+    }
+    const supplied = request.headers.get("origin");
+    const origin = supplied === null ? undefined : httpOrigin(supplied);
+    if (origin === undefined) {
+        return false;
+    }
+    if (origin === new URL(request.url).origin) {
+        return true;
+    }
+    const host = (request.headers.get("x-forwarded-host") ?? request.headers.get("host"))
+        ?.split(",")[0]
+        ?.trim();
+    if (!host) {
+        return false;
+    }
+    const forwardedProto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+    const protocol = forwardedProto === "http" || forwardedProto === "https"
+        ? forwardedProto
+        : isLoopbackHostname(host.replace(/:\d+$/, ""))
+            ? "http"
+            : "https";
+    return origin === httpOrigin(`${protocol}://${host}`);
+}
+/** An Origin names only an HTTP(S) authority, never credentials, a path or query. */
+function httpOrigin(value) {
+    if (!URL.canParse(value)) {
+        return undefined;
+    }
+    const url = new URL(value);
+    return (url.protocol === "http:" || url.protocol === "https:") &&
+        url.username === "" &&
+        url.password === "" &&
+        url.pathname === "/" &&
+        url.search === "" &&
+        url.hash === ""
+        ? url.origin
+        : undefined;
+}

package/dist/deployment.d.ts

@@ -0,0 +1,30 @@
+/** Runtime observations; authorization of the machine credential remains platform-owned. */
+export interface DeploymentCapabilities {
+    readonly warehouseRead: boolean;
+    readonly pipelineRuns: boolean;
+    readonly connections: boolean;
+    readonly agents: boolean;
+    readonly workflows: boolean;
+}
+export type DeploymentObservation = {
+    readonly target: "production";
+    readonly deploymentId?: string;
+    readonly capabilities: DeploymentCapabilities;
+} | {
+    readonly target: "preview";
+    readonly deploymentId: string;
+    readonly expiresAt: string;
+    readonly capabilities: DeploymentCapabilities;
+};
+export type DeploymentAdmissionCode = "preview_configuration_invalid" | "preview_expired" | "preview_capability_unavailable" | "preview_authentication_unavailable" | "preview_storage_binding_invalid";
+/** Stable codes only: workspace code owns explanations and presentation. */
+export declare class DeploymentAdmissionError extends Error {
+    readonly code: DeploymentAdmissionCode;
+    readonly capability?: keyof DeploymentCapabilities | undefined;
+    readonly _tag = "DeploymentAdmissionError";
+    constructor(code: DeploymentAdmissionCode, capability?: keyof DeploymentCapabilities | undefined);
+    get status(): number;
+}
+export declare function deploymentFromEnv(environment?: Readonly<Record<string, string | undefined>>): DeploymentObservation;
+/** Recheck the deadline on every admission, including a warm process and cached sessions. */
+export declare function requireDeploymentCapability(deployment: DeploymentObservation, capability?: keyof DeploymentCapabilities, now?: number): void;

package/dist/deployment.js

@@ -0,0 +1,72 @@
+/** Stable codes only: workspace code owns explanations and presentation. */
+export class DeploymentAdmissionError extends Error {
+    code;
+    capability;
+    _tag = "DeploymentAdmissionError";
+    constructor(code, capability) {
+        super(code);
+        this.code = code;
+        this.capability = capability;
+        this.name = "DeploymentAdmissionError";
+    }
+    get status() {
+        return this.code === "preview_expired"
+            ? 410
+            : this.code === "preview_configuration_invalid" ||
+                this.code === "preview_storage_binding_invalid"
+                ? 503
+                : 403;
+    }
+}
+export function deploymentFromEnv(environment = process.env) {
+    const target = environment.SEGMENTSTREAM_DEPLOYMENT_TARGET?.trim() || "production";
+    const deploymentId = environment.SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID?.trim();
+    if (target === "production") {
+        return Object.freeze({
+            target,
+            ...(deploymentId ? { deploymentId } : {}),
+            capabilities: Object.freeze({
+                warehouseRead: true,
+                pipelineRuns: true,
+                connections: true,
+                agents: true,
+                workflows: true,
+            }),
+        });
+    }
+    const expiresAt = environment.SEGMENTSTREAM_PREVIEW_EXPIRES_AT?.trim();
+    if (target !== "preview" ||
+        !deploymentId ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deploymentId) ||
+        !expiresAt ||
+        !/^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(expiresAt) ||
+        !Number.isFinite(Date.parse(expiresAt))) {
+        throw new DeploymentAdmissionError("preview_configuration_invalid");
+    }
+    return Object.freeze({
+        target,
+        deploymentId,
+        expiresAt,
+        capabilities: Object.freeze({
+            warehouseRead: true,
+            pipelineRuns: false,
+            connections: false,
+            agents: false,
+            workflows: true,
+        }),
+    });
+}
+/** Recheck the deadline on every admission, including a warm process and cached sessions. */
+export function requireDeploymentCapability(deployment, capability, now = Date.now()) {
+    if (deployment.target !== "preview")
+        return;
+    if (!Number.isFinite(now) ||
+        !Number.isFinite(Date.parse(deployment.expiresAt)) ||
+        now >= Date.parse(deployment.expiresAt)) {
+        throw new DeploymentAdmissionError("preview_expired");
+    }
+    // The preview profile is fixed; supplied flags cannot enable managed integrations.
+    if (capability !== undefined && capability !== "warehouseRead" && capability !== "workflows") {
+        throw new DeploymentAdmissionError("preview_capability_unavailable", capability);
+    }
+}