@segmentstream/app 0.0.0-stage → 0.38.1

package/dist/oauth.d.ts

@@ -0,0 +1,59 @@
+import type { OntologyTransport } from "./ontology.js";
+import { CONSENT_PAGE } from "./pages.js";
+export { CONSENT_PAGE };
+/** Everything the member may do, or only the reads of it. */
+export type AgentScope = "ontology" | "ontology:read";
+/** An agent asking to act for the signed-in member, as the consent page shows it. */
+export interface AgentAuthorizationRequest {
+    readonly id: string;
+    readonly client: {
+        /** The name the agent registered with. Agents choose it themselves, so show the host too. */
+        readonly name: string;
+        readonly uri: string | null;
+        /** Where the member's browser goes after the decision: the agent's own address. */
+        readonly redirectUri: string;
+        readonly redirectHost: string;
+    };
+    readonly scope: AgentScope;
+    /** What the member may do, and so the most the agent may do for them. */
+    readonly permissions: ReadonlyArray<string>;
+    readonly expiresAt: string;
+}
+/**
+ * Why a device code cannot be decided: it `expired`, was already `decided`, or is `unknown` (never
+ * issued, mistyped, cleaned up, or reported by an ontology service too old to say).
+ */
+export type DeviceCodeUnavailable = "expired" | "decided" | "unknown";
+/** A device code looked up for the signed-in member: its request, or why there is none. */
+export type DeviceLookup = {
+    readonly status: "pending";
+    readonly request: AgentAuthorizationRequest;
+} | {
+    readonly status: DeviceCodeUnavailable;
+};
+export interface AgentAuthorizations {
+    /**
+     * The request the consent page at `/oauth/consent?request=<id>` shows, for the signed-in member;
+     * `null` when it expired or was already decided. Server-only.
+     */
+    readonly request: (id: string) => Promise<AgentAuthorizationRequest | null>;
+    /**
+     * The request for a device code the member entered at `/oauth/consent?device=1`, or why there is
+     * none, so the consent page can tell an expired code from an already decided or unknown one.
+     * Server-only. Each lookup counts toward the member's verification attempts.
+     */
+    readonly deviceLookup: (userCode: string) => Promise<DeviceLookup>;
+    /** {@link AgentAuthorizations.deviceLookup}'s request, or `null` when there is none. */
+    readonly deviceRequest: (userCode: string) => Promise<AgentAuthorizationRequest | null>;
+    /**
+     * The Route Handler the consent page's form posts to, at `app/src/app/api/oauth/consent/route.ts`.
+     * It takes `request`, `decision` (`approve` or `deny`) and, to allow reading only, `scope`
+     * (`ontology:read`), and sends the browser back to the agent. `decision=lookup` with `user_code`
+     * redirects to the consent page for that device code.
+     */
+    readonly consentHandler: () => {
+        readonly POST: (request: Request) => Promise<Response>;
+    };
+}
+/** The consent flow, over the ontology service as the signed-in member. */
+export declare function createAgentAuthorizations(transport: OntologyTransport): AgentAuthorizations;

package/dist/oauth.js

@@ -0,0 +1,129 @@
+import { NextResponse } from "next/server";
+import { isSameOrigin } from "./decision-pages.js";
+import { apiErrorFrom, readJson } from "./errors.js";
+import { loopbackRedirect, oauthCompletion } from "./oauth-completion.js";
+import { CONSENT_PAGE } from "./pages.js";
+export { CONSENT_PAGE };
+function parseRequest(payload) {
+    if (typeof payload !== "object" || payload === null) {
+        return null;
+    }
+    const body = payload;
+    const client = (body.client ?? {});
+    if (typeof body.id !== "string" ||
+        typeof client.name !== "string" ||
+        typeof client.redirect_uri !== "string" ||
+        typeof client.redirect_host !== "string" ||
+        (body.scope !== "ontology" && body.scope !== "ontology:read") ||
+        !Array.isArray(body.permissions) ||
+        typeof body.expires_at !== "string") {
+        return null;
+    }
+    return {
+        id: body.id,
+        client: {
+            name: client.name,
+            uri: typeof client.uri === "string" ? client.uri : null,
+            redirectUri: client.redirect_uri,
+            redirectHost: client.redirect_host,
+        },
+        scope: body.scope,
+        permissions: body.permissions.filter((permission) => typeof permission === "string"),
+        expiresAt: body.expires_at,
+    };
+}
+function unavailableReason(payload) {
+    const reason = payload?.reason;
+    return reason === "expired" || reason === "decided" ? reason : "unknown";
+}
+function requestPath(id, decision) {
+    const path = `/oauth/requests/${encodeURIComponent(id)}`;
+    return decision === undefined ? path : `${path}/${decision}`;
+}
+/** The consent flow, over the ontology service as the signed-in member. */
+export function createAgentAuthorizations(transport) {
+    async function deviceLookup(userCode) {
+        const response = await transport.fetch("/oauth/device/lookup", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ user_code: userCode }),
+        });
+        const payload = await readJson(response);
+        if (response.status === 404) {
+            return { status: unavailableReason(payload) };
+        }
+        if (!response.ok) {
+            throw apiErrorFrom(response.status, payload, "The verification attempt was refused.");
+        }
+        const request = parseRequest(payload);
+        return request === null ? { status: "unknown" } : { status: "pending", request };
+    }
+    return {
+        async request(id) {
+            if (id === "") {
+                return null;
+            }
+            const response = await transport.fetch(requestPath(id), {
+                method: "GET",
+                headers: { accept: "application/json" },
+            });
+            const payload = await readJson(response);
+            if (response.status === 404) {
+                return null;
+            }
+            if (!response.ok) {
+                throw apiErrorFrom(response.status, payload, "The ontology service refused the request.");
+            }
+            return parseRequest(payload);
+        },
+        deviceLookup,
+        async deviceRequest(userCode) {
+            const lookup = await deviceLookup(userCode);
+            return lookup.status === "pending" ? lookup.request : null;
+        },
+        consentHandler: () => ({
+            async POST(request) {
+                if (!isSameOrigin(request)) {
+                    return NextResponse.json({ error: "forbidden", detail: "Decide on an agent from the app's own page." }, { status: 403 });
+                }
+                const form = await request.formData();
+                const id = String(form.get("request") ?? "");
+                if (form.get("decision") === "lookup") {
+                    const url = new URL(CONSENT_PAGE, request.url);
+                    url.searchParams.set("device", "1");
+                    url.searchParams.set("user_code", String(form.get("user_code") ?? "").slice(0, 32));
+                    return NextResponse.redirect(url, 303);
+                }
+                const device = id.startsWith("device:");
+                const decision = form.get("decision") === "approve" ? "approve" : "deny";
+                const response = await transport.fetch(device ? `/oauth/device/${decision}` : requestPath(id, decision), {
+                    method: "POST",
+                    headers: { "content-type": "application/json", accept: "application/json" },
+                    body: JSON.stringify({
+                        ...(device ? { user_code: id.slice(7) } : {}),
+                        ...(form.get("scope") === "ontology:read" ? { scope: "ontology:read" } : {}),
+                    }),
+                });
+                const payload = await readJson(response);
+                if (response.status === 404) {
+                    return NextResponse.redirect(new URL(`${CONSENT_PAGE}?expired=1`, request.url), 303);
+                }
+                if (!response.ok) {
+                    throw apiErrorFrom(response.status, payload, "The ontology service refused the decision.");
+                }
+                if (device) {
+                    return oauthCompletion({ approved: decision === "approve" });
+                }
+                const redirect = payload?.redirect;
+                if (typeof redirect !== "string" || !URL.canParse(redirect)) {
+                    throw apiErrorFrom(502, payload, "The ontology service answered without a redirect.");
+                }
+                if (decision === "approve" && loopbackRedirect(redirect)) {
+                    return oauthCompletion({ redirect });
+                }
+                // 303: the agent's redirect URI receives a GET, whatever method brought the browser here.
+                return NextResponse.redirect(redirect, 303);
+            },
+        }),
+    };
+}

package/dist/ontology-names.d.ts

@@ -0,0 +1,10 @@
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export declare function toSnakeCase(name: string): string;
+export declare function toCamelCase(name: string): string;
+/**
+ * camelCase that keeps an `_` before a digit, so `toSnakeCase` restores the name: `sales_2025`
+ * stays `sales_2025` and `wb2_sales` becomes `wb2Sales`. Model-level metric query names, whose
+ * first segment is a declared snake_case entity name, use it; records and per-entity metric
+ * queries keep `toCamelCase`.
+ */
+export declare function toReversibleCamelCase(name: string): string;

package/dist/ontology-names.js

@@ -0,0 +1,38 @@
+/** Ontology identifiers in TypeScript and their canonical transport spelling. */
+function isUppercase(letter) {
+    return letter !== undefined && letter >= "A" && letter <= "Z";
+}
+function isLowercase(letter) {
+    return letter !== undefined && letter >= "a" && letter <= "z";
+}
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export function toSnakeCase(name) {
+    if (name.toLowerCase() === name) {
+        return name;
+    }
+    const characters = [];
+    for (let index = 0; index < name.length; index++) {
+        const current = name[index];
+        const previous = name[index - 1];
+        const next = name[index + 1];
+        const followsWord = isLowercase(previous) || (previous !== undefined && previous >= "0" && previous <= "9");
+        const endsAcronym = isUppercase(previous) && isLowercase(next);
+        if (isUppercase(current) && (followsWord || endsAcronym)) {
+            characters.push("_");
+        }
+        characters.push(current);
+    }
+    return characters.join("").toLowerCase();
+}
+export function toCamelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+ * camelCase that keeps an `_` before a digit, so `toSnakeCase` restores the name: `sales_2025`
+ * stays `sales_2025` and `wb2_sales` becomes `wb2Sales`. Model-level metric query names, whose
+ * first segment is a declared snake_case entity name, use it; records and per-entity metric
+ * queries keep `toCamelCase`.
+ */
+export function toReversibleCamelCase(name) {
+    return name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/dist/ontology-transport.d.ts

@@ -0,0 +1,34 @@
+import { type OntologyTransport } from "./ontology.js";
+import type { Fetch } from "./sessions.js";
+/** Every ontology route lives under this path, beside the app on the same origin. */
+export declare const ONTOLOGY_BASE_PATH = "/api/ontology";
+/**
+ * How long an action call waits. The service answers an action within its own bounds: up to 5 s
+ * for a write slot, 60 s for `prepare` and 60 s for the transaction, then its workflow starts.
+ * Waiting longer means a slow action returns its result instead of an error while it still runs.
+ */
+export declare const ACTION_TIMEOUT_MS = 150000;
+/** How long a metric query waits; the service waits up to 60 s for SegmentStream's answer. */
+export declare const METRIC_QUERY_TIMEOUT_MS = 75000;
+/** How long every other request waits. */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** The caller's bearer token for the ontology service. */
+export interface OntologyCredentials {
+    /** The token for this request, or `null` when nobody is signed in. */
+    readonly token: () => Promise<string | null>;
+    /** Forgets a token the service rejected, so `token` returns a fresh one. */
+    readonly rejected?: (token: string) => void;
+}
+export interface OntologyTransportOptions {
+    readonly fetch: Fetch;
+    /** `SEGMENTSTREAM_ONTOLOGY_URL`: where the service runs when it is not beside the app. */
+    readonly ontologyUrl: string | undefined;
+    readonly credentials: OntologyCredentials;
+}
+/**
+ * Server-side requests to the ontology service with the signed-in user's token. Deployed, the
+ * service shares the app's origin; `SEGMENTSTREAM_ONTOLOGY_URL` points elsewhere, for example at
+ * `http://localhost:3100` or the deployed app during local development.
+ */
+export declare function createOntologyTransport(options: OntologyTransportOptions): OntologyTransport;
+export declare function ontologyOrigin(configured: string | undefined): Promise<string>;

package/dist/ontology-transport.js

@@ -0,0 +1,130 @@
+import { headers } from "next/headers";
+import { isLoopbackHostname } from "./cookies.js";
+import { SegmentStreamApiError } from "./errors.js";
+import { EARLIER_QUERY_METRICS } from "./legacy.js";
+import { QUERY_METRICS_ROUTE } from "./ontology.js";
+/** Every ontology route lives under this path, beside the app on the same origin. */
+export const ONTOLOGY_BASE_PATH = "/api/ontology";
+/**
+ * How long an action call waits. The service answers an action within its own bounds: up to 5 s
+ * for a write slot, 60 s for `prepare` and 60 s for the transaction, then its workflow starts.
+ * Waiting longer means a slow action returns its result instead of an error while it still runs.
+ */
+export const ACTION_TIMEOUT_MS = 150_000;
+/** How long a metric query waits; the service waits up to 60 s for SegmentStream's answer. */
+export const METRIC_QUERY_TIMEOUT_MS = 75_000;
+/** How long every other request waits. */
+export const REQUEST_TIMEOUT_MS = 30_000;
+const ACTION_PATH = /^\/[^/]+\/actions\/[^/]+$/;
+const METRIC_QUERY_PATH = new RegExp(`^(?:/[^/]+)?/(?:${QUERY_METRICS_ROUTE}|${EARLIER_QUERY_METRICS})$`);
+/** A caller's `signal` can shorten these, never extend them. */
+function timeoutOf(path, init) {
+    if (init.method?.toUpperCase() !== "POST") {
+        return REQUEST_TIMEOUT_MS;
+    }
+    return ACTION_PATH.test(path)
+        ? ACTION_TIMEOUT_MS
+        : METRIC_QUERY_PATH.test(path)
+            ? METRIC_QUERY_TIMEOUT_MS
+            : REQUEST_TIMEOUT_MS;
+}
+/**
+ * Server-side requests to the ontology service with the signed-in user's token. Deployed, the
+ * service shares the app's origin; `SEGMENTSTREAM_ONTOLOGY_URL` points elsewhere, for example at
+ * `http://localhost:3100` or the deployed app during local development.
+ */
+export function createOntologyTransport(options) {
+    async function send(url, token, init, timeoutMs) {
+        const requestHeaders = new Headers(init.headers);
+        const timeout = AbortSignal.timeout(timeoutMs);
+        requestHeaders.set("authorization", `Bearer ${token}`);
+        if (token.startsWith("sso_")) {
+            // Keep the browser's public app-session resource when a local proxy uses another origin.
+            const incoming = await headers();
+            const host = incoming.get("x-forwarded-host") ?? incoming.get("host");
+            if (host) {
+                requestHeaders.set("x-forwarded-host", host);
+                requestHeaders.set("x-forwarded-proto", incoming.get("x-forwarded-proto") ?? "https");
+            }
+        }
+        try {
+            return await options.fetch(url, {
+                ...init,
+                headers: requestHeaders,
+                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: "ontology_unreachable",
+                status: 503,
+                detail: `The ontology service at ${new URL(url).origin} could not be reached.`,
+                retryable: true,
+                cause: error,
+            });
+        }
+    }
+    return {
+        async fetch(path, init) {
+            const token = await options.credentials.token();
+            if (token === null) {
+                throw new SegmentStreamApiError({
+                    code: "app_session_missing",
+                    status: 401,
+                    detail: "No signed-in user for this request; call the ontology from Server Components, Route Handlers, or Server Functions behind the SegmentStream proxy.",
+                });
+            }
+            const url = `${await ontologyOrigin(options.ontologyUrl)}${ONTOLOGY_BASE_PATH}${path}`;
+            const timeoutMs = timeoutOf(path, init);
+            const response = await send(url, token, init, timeoutMs);
+            if (response.status !== 401 || options.credentials.rejected === undefined) {
+                return response;
+            }
+            // A cached token the service no longer accepts: retry once with a fresh one.
+            options.credentials.rejected(token);
+            const fresh = await options.credentials.token();
+            if (fresh === null || fresh === token) {
+                return response;
+            }
+            await response.body?.cancel();
+            return send(url, fresh, init, timeoutMs);
+        },
+    };
+}
+export async function ontologyOrigin(configured) {
+    if (configured !== undefined) {
+        return new URL(configured).origin;
+    }
+    // Vercel sets Host to the domain the request arrived on, which routes /api/ontology to the service.
+    const headerStore = await headers();
+    const host = (headerStore.get("x-forwarded-host") ?? headerStore.get("host"))
+        ?.split(",")[0]
+        ?.trim();
+    if (host === undefined || host === "") {
+        throw new SegmentStreamApiError({
+            code: "ontology_url_unknown",
+            status: 500,
+            detail: "The request has no Host header to reach the ontology service; set SEGMENTSTREAM_ONTOLOGY_URL.",
+        });
+    }
+    const forwarded = headerStore.get("x-forwarded-proto")?.split(",")[0]?.trim();
+    const protocol = forwarded === "http" || forwarded === "https"
+        ? forwarded
+        : isLoopbackHostname(hostnameOf(host))
+            ? "http"
+            : "https";
+    return new URL(`${protocol}://${host}`).origin;
+}
+function hostnameOf(host) {
+    try {
+        return new URL(`http://${host}`).hostname;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/ontology-wire.d.ts

@@ -0,0 +1,66 @@
+import type { Edit, JsonRecord, OntologyQuery, Where } from "./ontology.js";
+interface CatalogProperty {
+    readonly name: string;
+    readonly type: string;
+    readonly options?: ReadonlyArray<{
+        readonly value: string;
+    }>;
+}
+interface CatalogRelationship {
+    readonly name: string;
+    readonly to: string;
+    readonly inverse: string;
+    readonly cardinality: string;
+    /** Present when either end is warehouse-backed: the relationship is matched by value. */
+    readonly on?: unknown;
+}
+interface CatalogEntity {
+    readonly name: string;
+    readonly properties: ReadonlyArray<CatalogProperty>;
+    readonly relationships: ReadonlyArray<CatalogRelationship>;
+    readonly actions?: ReadonlyArray<{
+        readonly name: string;
+        readonly input: JsonSchema;
+    }>;
+}
+interface JsonSchema {
+    readonly $ref?: string;
+    readonly $defs?: Readonly<Record<string, JsonSchema>>;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly items?: JsonSchema;
+    readonly anyOf?: ReadonlyArray<JsonSchema>;
+    readonly oneOf?: ReadonlyArray<JsonSchema>;
+    readonly enum?: ReadonlyArray<unknown>;
+    readonly const?: unknown;
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly required?: ReadonlyArray<string>;
+}
+export interface WireCatalog {
+    readonly hash?: string;
+    readonly entities: ReadonlyArray<CatalogEntity>;
+}
+/** Whether a generated action of `user` answers with the updated user record. */
+export declare function returnsUserRecord(entity: string, action: string): boolean;
+/** 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<JsonRecord, readonly string[] | undefined>): unknown;
+/**
+ * `include` with snake_case names, as an object: a list of names, `["assignedOwner"]`, becomes
+ * `{ assigned_owner: true }`, which every version of the ontology service accepts.
+ */
+export declare function includeToWire(include: NonNullable<OntologyQuery["include"]>): Readonly<Record<string, unknown>>;
+/** Decode record fields and included relationships without descending into JSON properties. */
+export declare function recordFromWire<A = unknown>(value: unknown, entity: string, catalog: WireCatalog): A;
+export declare function actionInputToWire(given: unknown, entity: string, action: string, catalog: WireCatalog): unknown;
+export declare function responseFromWire(input: {
+    readonly method: "GET" | "POST";
+    readonly path: string;
+    readonly payload: unknown;
+}): unknown;
+/** Decode current edits using the current catalog; stored historical changes retain their names. */
+export declare function editsFromWire(edits: ReadonlyArray<Edit>, catalog: WireCatalog): ReadonlyArray<Edit>;
+export {};