@segmentstream-cloud/app 0.9.0 → 0.11.0

package/README.md

@@ -140,6 +140,7 @@ user in Server Functions and Route Handlers too; do not rely on the proxy alone.
 | `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                |
 | `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise       |
 | `<UserMenu />`                         | Name, email, roles and sign-out                                                 |
+| `<AgentConnect />`                     | The agent connect page: the pairing, an Approve button and the result           |
 | `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
 | `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                            |
 | `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                 |
@@ -289,6 +290,77 @@ const { result, validation, edits } = await segmentstream.ontology.lead.actions.
   structurally, so the app needs neither the ontology SDK nor Effect at runtime.
   Without a type argument, any entity name is accepted and records are untyped.
 
+## Agent connect page
+
+The workspace agent answers a chat account it does not know, such as a Telegram user,
+with a link to `/agent/connect?code=<code>`. A signed-in member approves there, and the
+ontology links the account to them: the agent then acts as that member, with their
+current roles, for that account's messages. The proxy signs the page in like any other
+and forbids other sites to frame it.
+
+```tsx
+// src/app/agent/connect/page.tsx, without Tailwind
+import { SegmentStreamApiError, type AgentPairing } from "@segmentstream-cloud/app";
+import { AgentConnect } from "@segmentstream-cloud/app/ui";
+import { segmentstream } from "@/segmentstream";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export default async function ConnectPage({ searchParams }: { searchParams: SearchParams }) {
+  const user = await segmentstream.requireUser();
+  const { code, connected } = await searchParams;
+  let pairing: AgentPairing | null = null;
+
+  if (typeof code === "string" && typeof connected !== "string") {
+    try {
+      pairing = await segmentstream.agent.pairing(code);
+    } catch (error) {
+      // A used or expired code shows "This link has expired"; anything else is an error.
+      if (
+        !(error instanceof SegmentStreamApiError) ||
+        !["not_found", "expired"].includes(error.code)
+      ) {
+        throw error;
+      }
+    }
+  }
+
+  return (
+    <AgentConnect
+      code={typeof code === "string" ? code : undefined}
+      pairing={pairing}
+      connected={typeof connected === "string" ? connected : undefined}
+      member={user.email ?? undefined}
+    />
+  );
+}
+```
+
+```ts
+// src/app/api/agent/connect/route.ts
+import { segmentstream } from "@/segmentstream";
+
+export const { POST } = segmentstream.agent.connectHandler();
+```
+
+`segmentstream.agent` holds:
+
+| Call                   | Does                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `pairing(code)`        | `{ provider, display, expiresAt }`; throws `not_found` or `expired`             |
+| `approvePairing(code)` | Links the account to the signed-in member; returns the `AgentIdentity`          |
+| `identities()`         | The member's own: `{ id, provider, externalId, display, createdAt, revokedAt }` |
+| `revokeIdentity(id)`   | Revokes one of them at once                                                     |
+| `connectHandler()`     | `{ POST }` for the page's form: same-origin only, takes `code`, answers `303`   |
+
+The handler sends the browser back to `/agent/connect?connected=<provider>`, or to
+`/agent/connect?expired=1` when the code was used or is older than ten minutes. Other
+refusals, such as `forbidden` for a member the ontology does not admit, throw
+`SegmentStreamApiError`. All calls are server-only and run as the signed-in member;
+the ontology decides every one. The workspace starter renders the page with Tailwind CSS
+and shadcn/ui; apps made from an earlier starter add `src/app/agent/connect/page.tsx`
+and `src/app/api/agent/connect/route.ts` from it.
+
 ## Query the warehouse
 
 ```tsx
@@ -334,9 +406,79 @@ export default async function Page() {
 - Values arrive as JSON: safe integers as numbers, larger integers and decimals as strings,
   timestamps as ISO strings, records and arrays as JSON strings.
 
-`segmentstream.ontology.<entity>.aggregate(request)` uses the server-held workspace app
-credential and supports Neon Auth apps. Stored record operations use the ontology user token.
-`segmentstream.fetch(path)` still requires the legacy platform session.
+One authorization model covers the ontology: every `segmentstream.ontology` call, aggregates
+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
+platform session. Aggregates through the service need the workspace's ontology deployed with
+`@segmentstream-cloud/ontology` 0.13.0 or later.
+
+Since 0.10.0, dimensions, filters and `orderBy` accept relationship paths, typed from the
+ontology's relationships:
+
+```ts
+const { rows, execution } = await segmentstream.ontology.order.aggregate({
+  dimensions: ["customer.segment"],
+  measures: ["orders"],
+  dateRange: { from: "2026-09-01", to: "2026-09-30" },
+});
+```
+
+- A path is `<relationship>.<property>`, through one or two to-one relationships. Paths into
+  a stored target include `id`; json and blob properties are left out. A thunk target types
+  its paths as `` `customer.${string}` ``. Each segment converts to snake_case on the wire,
+  and rows come back keyed by the camelCase path. These names are relative to the entity and
+  convert as record fields do: `line_2` reads as `line2`.
+- `execution.warnings` reports keys that matched more than one related row; totals are
+  unaffected. `execution.sources` gives, for each stored entity read through replication,
+  the time its data is current to, once known. Both are absent when the query produced none.
+- 0.10.0 requires the platform release that joins stored targets through replication.
+- See [ontology aggregates](../../docs/ontology-aggregates.md#relationship-paths).
+
+Since 0.10.0, `segmentstream.ontology.aggregate(request)` asks for numbers about the whole
+model: measures of several entities, warehouse-backed or stored, grouped by properties they all
+reach. Look at or change records through `find` and actions; count, sum or compare through
+`aggregate`.
+
+```ts
+const { fields, rows, execution } = await segmentstream.ontology.aggregate({
+  measures: ["trendtoysSales.revenue", "trendtoysStock.onHand"],
+  dimensions: ["trendtoysProduct.assortmentStatus"],
+  filters: [
+    {
+      dimension: "trendtoysSales.orderDate",
+      operator: "between",
+      values: ["2026-09-01", "2026-09-30"],
+    },
+    { dimension: "trendtoysSales.currency", operator: "equals", value: "RUB" },
+  ],
+  orderBy: [{ measure: "trendtoysSales.revenue", direction: "desc" }],
+});
+```
+
+- Names are `entity.measure` and `entity.property`, each segment in camelCase, typed from the
+  ontology. An `_` before a digit stays, so an entity's declared name converts back:
+  `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`.
+- 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`.
+- Date bounds are `between` filters, inclusive. Each partitioned entity needs one on its own
+  partition property. Currency measures need their entity filtered to one currency, the same
+  for every entity.
+- A measure field's `filters` lists the filters applied to it, and `execution.warnings` names
+  each filter that did not reach a measure's entity. `additive: false` marks a measure whose
+  rows don't add up to a total.
+- Failures throw `SegmentStreamApiError` with the service's `code`: `invalid_request`,
+  `invalid_aggregate_query`, `forbidden`, `rate_limited` (30 aggregates a minute per user),
+  `aggregate_unavailable`, `aggregate_upstream_unavailable`, `ontology_version_mismatch` or
+  `aggregate_scope_mismatch`. See
+  [ontology aggregates](../../docs/ontology-aggregates.md#errors).
 
 ## How requests are handled
 
@@ -395,7 +537,7 @@ Without `NEON_AUTH_BASE_URL`, 0.3 behaves exactly as 0.2, so existing apps keep
 working: members of the workspace's organization sign in with their SegmentStream
 account through `/api/segmentstream/[...path]/route.ts`
 (`export const { GET, POST } = segmentstream.handlers();`), the proxy redirects to
-SegmentStream, and `fetch` acts as the member; warehouse queries and aggregates prefer the workspace app credential. In that mode
+SegmentStream, and `fetch` acts as the member; warehouse queries prefer the workspace app credential. In that mode
 `roles` and `permissions` are empty, `can()` is `false`, `authHandlers()` answers
 `404 neon_auth_not_configured`, and `segmentstream.ontology` sends the member's app
 token, which the ontology service accepts while workspaces move to Neon Auth. Keep the
@@ -422,3 +564,18 @@ Apache-2.0
 ## Upgrading to 0.5
 
 Replace segmentstream.semantic with typed warehouse-backed entity aggregates. See [ontology aggregates](../../docs/ontology-aggregates.md). Warehouse-backed clients expose no record CRUD or actions.
+
+## Upgrading to 0.10
+
+- Shorthand aggregates accept relationship paths. Their responses may carry
+  `execution.warnings` and `execution.sources`.
+- `segmentstream.ontology.aggregate()` is new, and `aggregate` is a reserved entity name.
+- `segmentstream.ontology.<entity>.aggregate()` now runs as the signed-in user through the
+  ontology service, like record reads, and no longer uses `SEGMENTSTREAM_APP_CREDENTIAL`. The
+  user needs read permission on the entities it reaches.
+- Server code without a signed-in user, such as a scheduled Route Handler, can no longer
+  aggregate with the workspace credential. Use `segmentstream.warehouse` there, or call the
+  ontology service with an API key.
+- Deploy the workspace's ontology with `@segmentstream-cloud/ontology` 0.13.0 or later. It
+  serves `/api/ontology/<entity>/aggregate` and `/api/ontology/aggregate`; earlier versions
+  don't.

package/dist/agent.d.ts

@@ -0,0 +1,55 @@
+import type { OntologyTransport } from "./ontology.js";
+import { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./pages.js";
+export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE };
+/**
+ * A chat account asking to be linked to the signed-in member, as the connect page shows it. The
+ * workspace agent answers a sender it does not know with the link `/agent/connect?code=<code>`.
+ */
+export interface AgentPairing {
+    /** The channel the sender wrote on, such as `telegram`. */
+    readonly provider: string;
+    /** How the channel names the sender, such as `@ada`; `null` when it gave no name. */
+    readonly display: string | null;
+    /** When the code stops working: ten minutes after the agent issued it. */
+    readonly expiresAt: string;
+}
+/** A chat account linked to a member: the agent acts as that member for its messages. */
+export interface AgentIdentity {
+    readonly id: string;
+    readonly provider: string;
+    /** The account's id on the channel, such as a Telegram user id. */
+    readonly externalId: string;
+    /** How the channel named the account when it was linked; `null` when unknown. */
+    readonly display: string | null;
+    readonly createdAt: string;
+    /** When the member or an administrator revoked it; `null` while it is live. */
+    readonly revokedAt: string | null;
+}
+export interface AgentIdentities {
+    /**
+     * The pairing the connect page at `/agent/connect?code=<code>` shows, for the signed-in member.
+     * Throws `SegmentStreamApiError` with `not_found` or `expired` when the code is unknown, used or
+     * too old. Server-only.
+     */
+    readonly pairing: (code: string) => Promise<AgentPairing>;
+    /**
+     * Links the pairing's chat account to the signed-in member. The ontology decides: it refuses a
+     * used or expired code (`not_found`, `expired`) and a member it does not admit (`forbidden`).
+     * Server-only.
+     */
+    readonly approvePairing: (code: string) => Promise<AgentIdentity>;
+    /** The signed-in member's own linked chat accounts. Server-only. */
+    readonly identities: () => Promise<ReadonlyArray<AgentIdentity>>;
+    /** Revokes one of the signed-in member's linked chat accounts at once. Server-only. */
+    readonly revokeIdentity: (id: string) => Promise<void>;
+    /**
+     * The Route Handler the connect page's form posts to, at `app/src/app/api/agent/connect/route.ts`.
+     * It takes `code`, approves the pairing and sends the browser back to the connect page with
+     * `connected=<provider>`, or with `expired=1` when the code no longer works.
+     */
+    readonly connectHandler: () => {
+        readonly POST: (request: Request) => Promise<Response>;
+    };
+}
+/** Pairing and linked chat accounts, over the ontology service as the signed-in member. */
+export declare function createAgentIdentities(transport: OntologyTransport): AgentIdentities;

package/dist/agent.js

@@ -0,0 +1,202 @@
+import { NextResponse } from "next/server";
+import { isSameOrigin } from "./decision-pages.js";
+import { SegmentStreamApiError, apiErrorFrom } from "./errors.js";
+import { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./pages.js";
+export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE };
+/** The error codes of a code that no longer works: the connect page asks for a new link. */
+const GONE_CODES = new Set(["not_found", "expired"]);
+/** The SDK's error code for a refusal whose body names none. */
+const STATUS_CODES = {
+    403: "forbidden",
+    404: "not_found",
+    410: "expired",
+};
+function pairingPath(code, approve) {
+    const path = `/agent/pairings/${encodeURIComponent(code)}`;
+    return approve ? `${path}/approve` : path;
+}
+function identityPath(id) {
+    return id === undefined ? "/agent/identities" : `/agent/identities/${encodeURIComponent(id)}`;
+}
+/** The service's error, with the SDK's codes when its body names none. */
+function agentErrorFrom(status, payload, detail) {
+    const error = apiErrorFrom(status, payload, detail);
+    if (!error.code.startsWith("http_")) {
+        return error;
+    }
+    const code = STATUS_CODES[status];
+    if (code === undefined) {
+        return error;
+    }
+    return new SegmentStreamApiError({
+        code,
+        status,
+        detail: error.detail,
+        requestId: error.requestId,
+        retryable: error.retryable,
+    });
+}
+function invalidResponse(detail) {
+    return new SegmentStreamApiError({
+        code: "ontology_invalid_response",
+        status: 502,
+        detail,
+        retryable: true,
+    });
+}
+function unknownCode() {
+    return new SegmentStreamApiError({
+        code: "not_found",
+        status: 404,
+        detail: "The link has no pairing code. Ask the agent for a new link.",
+    });
+}
+function fields(payload) {
+    return typeof payload === "object" && payload !== null && !Array.isArray(payload)
+        ? payload
+        : null;
+}
+function optionalString(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}
+/** Reads `{ provider, display, expires_at }` tolerantly: unknown fields are ignored. */
+function parsePairing(payload) {
+    const body = fields(payload);
+    if (body === null || typeof body.provider !== "string" || typeof body.expires_at !== "string") {
+        return null;
+    }
+    return {
+        provider: body.provider,
+        display: optionalString(body.display),
+        expiresAt: body.expires_at,
+    };
+}
+/** Reads `{ id, provider, external_id, display?, created_at, revoked_at? }` tolerantly. */
+function parseIdentity(payload) {
+    const body = fields(payload);
+    if (body === null ||
+        typeof body.id !== "string" ||
+        typeof body.provider !== "string" ||
+        typeof body.external_id !== "string" ||
+        typeof body.created_at !== "string") {
+        return null;
+    }
+    return {
+        id: body.id,
+        provider: body.provider,
+        externalId: body.external_id,
+        display: optionalString(body.display),
+        createdAt: body.created_at,
+        revokedAt: optionalString(body.revoked_at),
+    };
+}
+/** The identities in `{ identities: [...] }`, `{ items: [...] }` or a bare array. */
+function identityList(payload) {
+    if (Array.isArray(payload)) {
+        return payload;
+    }
+    const body = fields(payload);
+    const list = body?.identities ?? body?.items;
+    return Array.isArray(list) ? list : null;
+}
+/** Pairing and linked chat accounts, over the ontology service as the signed-in member. */
+export function createAgentIdentities(transport) {
+    async function send(path, method) {
+        const response = await transport.fetch(path, {
+            method,
+            headers: { accept: "application/json" },
+        });
+        const text = await response.text();
+        let payload = null;
+        try {
+            // An empty body, such as a 204 on revocation, carries no payload.
+            payload = text === "" ? null : JSON.parse(text);
+        }
+        catch (error) {
+            // The parse failure is the cause, so a malformed answer is told apart from a refusal.
+            const refused = agentErrorFrom(response.status, null, "The ontology service refused the request.");
+            throw new SegmentStreamApiError({
+                code: response.ok ? "ontology_invalid_response" : refused.code,
+                status: response.ok ? 502 : refused.status,
+                detail: response.ok
+                    ? "The ontology service answered with a body that is not JSON."
+                    : refused.detail,
+                retryable: response.ok ? true : refused.retryable,
+                cause: error,
+            });
+        }
+        if (!response.ok) {
+            throw agentErrorFrom(response.status, payload, "The ontology service refused the request.");
+        }
+        return payload;
+    }
+    async function approvePairing(code) {
+        if (code === "") {
+            throw unknownCode();
+        }
+        const payload = await send(pairingPath(code, true), "POST");
+        const identity = parseIdentity(fields(payload)?.identity);
+        if (identity === null) {
+            throw invalidResponse("The ontology service approved the pairing without an { identity }.");
+        }
+        return identity;
+    }
+    return {
+        async pairing(code) {
+            if (code === "") {
+                throw unknownCode();
+            }
+            const payload = await send(pairingPath(code, false), "GET");
+            const pairing = parsePairing(payload);
+            if (pairing === null) {
+                throw invalidResponse("The ontology service answered without { provider, expires_at }.");
+            }
+            return pairing;
+        },
+        approvePairing,
+        async identities() {
+            const payload = await send(identityPath(), "GET");
+            const list = identityList(payload);
+            if (list === null) {
+                throw invalidResponse("The ontology service answered without a list of identities.");
+            }
+            return list.flatMap((candidate) => {
+                const identity = parseIdentity(candidate);
+                return identity === null ? [] : [identity];
+            });
+        },
+        async revokeIdentity(id) {
+            if (id === "") {
+                throw new SegmentStreamApiError({
+                    code: "not_found",
+                    status: 404,
+                    detail: "No identity to revoke.",
+                });
+            }
+            await send(identityPath(id), "DELETE");
+        },
+        connectHandler: () => ({
+            async POST(request) {
+                if (!isSameOrigin(request)) {
+                    return NextResponse.json({ error: "forbidden", detail: "Connect a chat account from the app's own page." }, { status: 403 });
+                }
+                const form = await request.formData();
+                const code = String(form.get("code") ?? "");
+                let identity;
+                try {
+                    identity = await approvePairing(code);
+                }
+                catch (error) {
+                    if (error instanceof SegmentStreamApiError && GONE_CODES.has(error.code)) {
+                        return NextResponse.redirect(new URL(`${AGENT_CONNECT_PAGE}?expired=1`, request.url), 303);
+                    }
+                    throw error;
+                }
+                const connected = new URL(AGENT_CONNECT_PAGE, request.url);
+                connected.searchParams.set("connected", identity.provider);
+                // 303: the browser loads the connect page with a GET, showing the result.
+                return NextResponse.redirect(connected, 303);
+            },
+        }),
+    };
+}

package/dist/app.d.ts

@@ -1,4 +1,5 @@
 import type { Environment, SegmentStreamAppConfig } from "./config.js";
+import type { AgentIdentities } from "./agent.js";
 import type { WarehouseClient } from "./data.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
 import type { AgentAuthorizations } from "./oauth.js";
@@ -52,6 +53,12 @@ export interface SegmentStreamApp<O = unknown> {
      * member, and the Route Handler that carries out their decision. Server-only.
      */
     readonly oauth: AgentAuthorizations;
+    /**
+     * The workspace agent's chat accounts: the pairing the agent connect page shows the signed-in
+     * member, its approval, the member's linked accounts and their revocation, and the Route Handler
+     * the page's form posts to. Server-only.
+     */
+    readonly agent: AgentIdentities;
 }
 /** Replaceable capabilities, for tests. */
 export interface AppDependencies {

package/dist/app.js

@@ -1,11 +1,13 @@
 import { createNeonAuth } from "@neondatabase/auth/next/server";
 import { NextResponse } from "next/server";
 import { environmentValue, processEnvironment, resolveConfig, resolveNeonAuth } from "./config.js";
+import { createAgentIdentities } from "./agent.js";
 import { createDataClient } from "./data.js";
+import { withUnframeablePages } from "./decision-pages.js";
 import { SegmentStreamApiError } from "./errors.js";
 import { createHandlers } from "./handlers.js";
 import { createNeonSession } from "./neon.js";
-import { createAgentAuthorizations, withUnframeableConsent } from "./oauth.js";
+import { createAgentAuthorizations } from "./oauth.js";
 import { createOntologyClient } from "./ontology.js";
 import { createOntologyTransport } from "./ontology-transport.js";
 import { createProxy } from "./proxy.js";
@@ -44,7 +46,7 @@ export function createApp(config, dependencies = {}) {
         });
         return {
             authentication: "segmentstream",
-            proxy: (options) => withUnframeableConsent(createProxy(context, options)),
+            proxy: (options) => withUnframeablePages(createProxy(context, options)),
             authHandlers: notConfiguredHandlers,
             handlers: () => createHandlers(context),
             getUser: legacy.getUser,
@@ -55,8 +57,9 @@ export function createApp(config, dependencies = {}) {
             getAccessToken: legacy.getAccessToken,
             fetch: data.fetch,
             warehouse: data.warehouse,
-            ontology: createOntologyClient(ontologyTransport, data.aggregateTransport),
+            ontology: createOntologyClient(ontologyTransport),
             oauth: createAgentAuthorizations(ontologyTransport),
+            agent: createAgentIdentities(ontologyTransport),
         };
     }
     const neon = createNeonSession({
@@ -74,7 +77,7 @@ export function createApp(config, dependencies = {}) {
     });
     return {
         authentication: "neon-auth",
-        proxy: (options) => withUnframeableConsent(neon.proxy(options)),
+        proxy: (options) => withUnframeablePages(neon.proxy(options)),
         authHandlers: neon.authHandlers,
         handlers: () => createHandlers(context),
         getUser: neon.getUser,
@@ -84,8 +87,9 @@ export function createApp(config, dependencies = {}) {
         getAccessToken: async () => null,
         fetch: data.fetch,
         warehouse: data.warehouse,
-        ontology: createOntologyClient(neon.ontologyTransport, data.aggregateTransport),
+        ontology: createOntologyClient(neon.ontologyTransport),
         oauth: createAgentAuthorizations(neon.ontologyTransport),
+        agent: createAgentIdentities(neon.ontologyTransport),
     };
 }
 /** Under Neon Auth the app has no SegmentStream session to call the API with. */
@@ -93,7 +97,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 and ontology aggregates use the workspace app credential, SEGMENTSTREAM_APP_CREDENTIAL, which is not set; SegmentStream sets it on deploy. Other SegmentStream API calls are not available to these apps yet.",
+        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.",
     });
 }
 function notConfiguredHandlers() {

package/dist/data.d.ts

@@ -43,34 +43,71 @@ export interface WarehouseDryRun {
     readonly bytesProcessed: string | null;
     readonly maximumBytesBilled: string;
 }
-export interface AggregateRequest<Property extends string = string, Measure extends string = string, Temporal extends Property = Property> {
-    readonly dimensions: readonly Property[];
+/**
+ * An aggregate query. 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 AggregateRequest<Property extends string = string, Measure extends string = string, Temporal extends Property = Property, Path extends string = never> {
+    readonly dimensions: readonly (Property | Path)[];
     readonly measures: readonly Measure[];
     readonly dateRange?: {
         readonly from: string;
         readonly to: string;
     };
-    readonly granularityOf?: Temporal;
+    /** The selected date or timestamp dimension to bucket, which may be a related one. */
+    readonly granularityOf?: Temporal | Path;
     readonly granularity?: "day" | "week" | "month";
     readonly filters?: ReadonlyArray<{
-        readonly dimension: Property;
+        readonly dimension: Property | Path;
         readonly operator: "equals" | "in" | "isNull" | "isNotNull";
         readonly value?: string | number | boolean;
         readonly values?: ReadonlyArray<string | number | boolean>;
     }>;
     readonly orderBy?: ReadonlyArray<{
         readonly measure?: Measure;
-        readonly dimension?: Property;
+        readonly dimension?: Property | Path;
         readonly direction: "asc" | "desc";
     }>;
     readonly limit?: number;
 }
+/** A filter of a model-level aggregate. `between` takes two inclusive `values`, the lower first. */
+export interface ModelAggregateFilter<Dimension extends string = string> {
+    readonly dimension: Dimension;
+    readonly operator: "equals" | "in" | "isNull" | "isNotNull" | "between";
+    readonly value?: string | number | boolean;
+    readonly values?: ReadonlyArray<string | number | boolean>;
+}
+/**
+ * A model-level aggregate: measures of one or more entities, as `entity.measure`, 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` filters.
+ */
+export interface ModelAggregateRequest<Measure extends string = string, Dimension extends string = string> {
+    readonly measures: readonly Measure[];
+    readonly dimensions?: readonly Dimension[];
+    readonly filters?: ReadonlyArray<ModelAggregateFilter<Dimension>>;
+    readonly granularity?: "day" | "week" | "month";
+    /** The requested date or timestamp dimension to bucket by `granularity`. */
+    readonly granularityOf?: Dimension;
+    readonly orderBy?: ReadonlyArray<{
+        readonly measure?: Measure;
+        readonly dimension?: Dimension;
+        readonly direction: "asc" | "desc";
+    }>;
+    /** Rows to return, 1–1000; 100 by default. */
+    readonly limit?: number;
+}
 export interface AggregateField {
     readonly name: string;
     readonly label: string;
     readonly type: string;
     readonly unit?: string;
     readonly format?: string;
+    /** On a measure: the filters applied to it. A filter its entity cannot reach is not listed. */
+    readonly filters?: readonly string[];
+    /** `false` on a measure whose rows don't add up to a total, such as a distinct count or a ratio. */
+    readonly additive?: boolean;
 }
 export interface AggregateResult<Row = Record<string, string | boolean | null>> {
     readonly deploymentId: string | null;
@@ -82,6 +119,16 @@ export interface AggregateResult<Row = Record<string, string | boolean | null>>
         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 measure's entity.
+         */
+        readonly warnings?: readonly string[];
+        /** The stored entities a query read, each with the time up to which its copy is complete. */
+        readonly sources?: ReadonlyArray<{
+            readonly entity: string;
+            readonly asOf: string;
+        }>;
     };
 }
 export interface WarehouseClient {
@@ -111,7 +158,4 @@ export interface DataClientDependencies {
 export declare function createDataClient(dependencies: DataClientDependencies): {
     fetch: (path: string, init?: RequestInit) => Promise<Response>;
     warehouse: WarehouseClient;
-    aggregateTransport: {
-        fetch: (path: string, init: RequestInit) => Promise<Response>;
-    };
 };

package/dist/data.js

@@ -154,14 +154,7 @@ export function createDataClient(dependencies) {
             };
         },
     };
-    const aggregateTransport = {
-        fetch: (path, init) => {
-            if (!/^\/[a-z][a-z0-9_]*\/aggregate$/.test(path))
-                throw new TypeError("Invalid aggregate path.");
-            return authorizedFetch(`${workspace}/entities${path}`, init, warehouseToken);
-        },
-    };
-    return { fetch: apiFetch, warehouse, aggregateTransport };
+    return { fetch: apiFetch, warehouse };
 }
 function bytesLimit(value) {
     if (value === undefined) {

package/dist/decision-pages.d.ts

@@ -0,0 +1,12 @@
+import { type SegmentStreamProxy } from "./proxy.js";
+/**
+ * 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): 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.
+ */
+export declare function isSameOrigin(request: Request): boolean;

package/dist/decision-pages.js

@@ -0,0 +1,31 @@
+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];
+/**
+ * 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) {
+    return async (request) => {
+        const response = await proxy(request);
+        const pathname = request.nextUrl.pathname;
+        if (DECISION_PAGES.some((page) => matchesPathPrefix(pathname, page))) {
+            response.headers.set("x-frame-options", "DENY");
+            response.headers.set("content-security-policy", "frame-ancestors 'none'");
+        }
+        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.
+ */
+export function isSameOrigin(request) {
+    const origin = request.headers.get("origin");
+    if (origin !== null) {
+        return origin === new URL(request.url).origin;
+    }
+    return request.headers.get("sec-fetch-site") === "same-origin";
+}

package/dist/index.d.ts

@@ -20,16 +20,20 @@ export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
 export type { AuthenticationMethod, SegmentStreamApp } from "./app.js";
 export { CONSENT_PAGE } from "./oauth.js";
+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 { CurrentUser } from "./me.js";
 export type { AuthRouteHandler, AuthRouteHandlers, SignOutOptions } from "./neon.js";
-export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
+export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, ModelAggregateClient, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
 export type { PermissionHolder } from "./permissions.js";
-export type { AggregateField, AggregateRequest, AggregateResult, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
+export type { AggregateField, AggregateRequest, AggregateResult, ModelAggregateFilter, ModelAggregateRequest, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
 export type { ParameterType, QueryParameterValue, QueryParameters, TypedParameter, } from "./parameters.js";
 export type { SegmentStreamAppConfig } from "./config.js";
 export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";
 export type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
 export type { AppUser } from "./tokens.js";
 export { createBlobStorageClient, type BlobUploadTicket, type FileRevision, type FileTransfer, type FileUploadTarget, type UploadSession, type FileUploadOptions, } from "./storage.js";
+/** Whether a form post came from the app itself: the check the agent connect and consent handlers use. */
+export { isSameOrigin } from "./decision-pages.js";

package/dist/index.js

@@ -20,4 +20,7 @@ export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./erro
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
 export { CONSENT_PAGE } from "./oauth.js";
+export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./agent.js";
 export { createBlobStorageClient, } from "./storage.js";
+/** Whether a form post came from the app itself: the check the agent connect and consent handlers use. */
+export { isSameOrigin } from "./decision-pages.js";

package/dist/oauth.d.ts

@@ -1,12 +1,6 @@
 import type { OntologyTransport } from "./ontology.js";
-import { type SegmentStreamProxy } from "./proxy.js";
-/** The app's page where a signed-in member decides whether an agent may act for them. */
-export declare const CONSENT_PAGE = "/oauth/consent";
-/**
- * The proxy, with the consent page unframeable: no other site may show it in a frame and trick a
- * member into clicking Allow. Every app gets this from the SDK, whatever its Next.js config says.
- */
-export declare function withUnframeableConsent(proxy: SegmentStreamProxy): SegmentStreamProxy;
+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. */

package/dist/oauth.js

@@ -1,22 +1,8 @@
 import { NextResponse } from "next/server";
+import { isSameOrigin } from "./decision-pages.js";
 import { apiErrorFrom, readJson } from "./errors.js";
-import { matchesPathPrefix } from "./proxy.js";
-/** The app's page where a signed-in member decides whether an agent may act for them. */
-export const CONSENT_PAGE = "/oauth/consent";
-/**
- * The proxy, with the consent page unframeable: no other site may show it in a frame and trick a
- * member into clicking Allow. Every app gets this from the SDK, whatever its Next.js config says.
- */
-export function withUnframeableConsent(proxy) {
-    return async (request) => {
-        const response = await proxy(request);
-        if (matchesPathPrefix(request.nextUrl.pathname, CONSENT_PAGE)) {
-            response.headers.set("x-frame-options", "DENY");
-            response.headers.set("content-security-policy", "frame-ancestors 'none'");
-        }
-        return response;
-    };
-}
+import { CONSENT_PAGE } from "./pages.js";
+export { CONSENT_PAGE };
 function parseRequest(payload) {
     if (typeof payload !== "object" || payload === null) {
         return null;
@@ -45,17 +31,6 @@ function parseRequest(payload) {
         expiresAt: body.expires_at,
     };
 }
-/**
- * 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.
- */
-function sameOrigin(request) {
-    const origin = request.headers.get("origin");
-    if (origin !== null) {
-        return origin === new URL(request.url).origin;
-    }
-    return request.headers.get("sec-fetch-site") === "same-origin";
-}
 function requestPath(id, decision) {
     const path = `/oauth/requests/${encodeURIComponent(id)}`;
     return decision === undefined ? path : `${path}/${decision}`;
@@ -82,7 +57,7 @@ export function createAgentAuthorizations(transport) {
         },
         consentHandler: () => ({
             async POST(request) {
-                if (!sameOrigin(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();

package/dist/ontology-names.d.ts

@@ -1,3 +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 aggregate names, whose first
+ * segment is a declared snake_case entity name, use it; records and per-entity aggregates keep
+ * `toCamelCase`.
+ */
+export declare function toReversibleCamelCase(name: string): string;

package/dist/ontology-names.js

@@ -24,3 +24,12 @@ export function toSnakeCase(name) {
 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 aggregate names, whose first
+ * segment is a declared snake_case entity name, use it; records and per-entity aggregates keep
+ * `toCamelCase`.
+ */
+export function toReversibleCamelCase(name) {
+    return name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/dist/ontology-wire.d.ts

@@ -11,6 +11,8 @@ interface CatalogRelationship {
     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;

package/dist/ontology-wire.js

@@ -16,6 +16,13 @@ const SYSTEM_FIELDS = ["id", "created_at", "updated_at", "created_by", "updated_
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+/**
+ * A relationship with a warehouse-backed end is matched by value through `on`: it has no
+ * `<name>_id` field, and the ontology service cannot traverse or filter through it.
+ */
+function isValueMatched(relationship) {
+    return relationship.on !== undefined && relationship.on !== null;
+}
 /** Catalog metadata distinguishes relationship filters from opaque JSON property values. */
 export async function encodeWhere(input) {
     const { where, entity, getCatalog } = input;
@@ -51,12 +58,14 @@ function whereFromCatalog(input) {
 }
 function relationshipTarget(input) {
     const { field, entity, definition, catalog } = input;
-    const forward = definition?.relationships.find((candidate) => candidate.name === field);
+    const forward = definition?.relationships.find((candidate) => candidate.name === field && !isValueMatched(candidate));
     if (forward !== undefined) {
         return { entity: forward.to, many: forward.cardinality === "many" };
     }
     for (const candidate of catalog.entities) {
-        const inverse = candidate.relationships.find((relationship) => relationship.to === entity && relationship.inverse === field);
+        const inverse = candidate.relationships.find((relationship) => relationship.to === entity &&
+            relationship.inverse === field &&
+            !isValueMatched(relationship));
         if (inverse !== undefined) {
             return { entity: candidate.name, many: true };
         }
@@ -79,7 +88,9 @@ function isGeneratedField(field, definition) {
     if (SYSTEM_FIELDS.includes(field)) {
         return true;
     }
-    return (definition?.relationships.some((relationship) => relationship.cardinality === "one" && `${relationship.name}_id` === field) ?? false);
+    return (definition?.relationships.some((relationship) => relationship.cardinality === "one" &&
+        !isValueMatched(relationship) &&
+        `${relationship.name}_id` === field) ?? false);
 }
 function fieldFilterToWire(input) {
     const { field, condition, definition } = input;

package/dist/ontology.d.ts

@@ -1,4 +1,4 @@
-import type { AggregateRequest, AggregateResult } from "./data.js";
+import type { AggregateRequest, AggregateResult, ModelAggregateRequest } from "./data.js";
 /**
  * The typed client for the app's ontology service, `/api/ontology`. The app imports its ontology as
  * types only (`import type ontology from "../../ontology"`) and passes `typeof ontology` to
@@ -191,31 +191,99 @@ type ActionClients<A> = {
 type PropertiesOf<E> = E extends {
     readonly properties: infer P;
 } ? P : never;
+/** Declared names only: a definition typed as any `Measures` names none the client can check. */
+type DeclaredNames<M> = string extends keyof M ? never : keyof M & string;
+/** A warehouse-backed entity's `measures`, or the measures of a stored entity's definition. */
 type MeasuresOf<E> = E extends {
     readonly measures: infer M;
-} ? keyof M & string : never;
-export interface AggregateEntityClient<Property extends string = string, Measure extends string = string, Temporal extends Property = Property> {
-    readonly aggregate: (request: AggregateRequest<Property, Measure, Temporal>, options?: RequestOptions) => Promise<AggregateResult>;
-}
-type ClientOf<E> = E extends {
+} ? keyof M & string : E extends {
+    readonly definition: {
+        readonly measures?: infer M;
+    };
+} ? DeclaredNames<NonNullable<M>> : never;
+type RelationshipsOf<E> = E extends {
+    readonly relationships: infer R;
+} ? R : never;
+type IsWarehouseBacked<E> = E extends {
     readonly definition: {
         readonly source: object;
     };
-} ? AggregateEntityClient<keyof PropertiesOf<E> & string, MeasuresOf<E>> : EntityClient<RecordOf<E>, ActionClients<ActionsOf<E>>>;
+} ? true : false;
+/**
+ * A `rel.one`, which aggregates may follow. Every relationship of a warehouse-backed entity is
+ * matched by value; a stored entity's may also be keyed (`<relationship>_id` joined to `id`).
+ */
+interface ToOne {
+    readonly cardinality: "one";
+}
+/** The target's name, or `string` when a thunk erased it or the ontology SDK predates the name. */
+type TargetNameOf<R> = R extends {
+    readonly "~ontology.target": infer Name extends string;
+} ? Name : string;
+/** The entity of `O` named `Name`. `User` is not replicated, so aggregates never reach it. */
+type EntityNamed<O, Name extends string> = Name extends "user" ? never : Extract<EntitiesOf<O>, {
+    readonly name: Name;
+}>;
+/** Properties whose values are scalars. json and blob values are objects, which aggregates skip. */
+type ScalarPropertiesOf<T> = {
+    [K in keyof PropertiesOf<T>]-?: PropertiesOf<T>[K] extends {
+        readonly Type: infer V;
+    } ? [Extract<V, object>] extends [never] ? K : never : K;
+}[keyof PropertiesOf<T>] & string;
+/** What a path may end on: the target's scalar properties, and `id` when the target is stored. */
+type FieldsOf<T> = ScalarPropertiesOf<T> | (IsWarehouseBacked<T> extends true ? never : "id");
+/** The rest of a path after reaching `T`: a field, or one more relationship when `Again`. */
+type PathEnds<T, O, Again extends boolean> = [T] extends [never] ? never : FieldsOf<T> | (Again extends true ? PathsFrom<T, O, false> : never);
+type PathsFrom<E, O, Again extends boolean> = {
+    [K in keyof RelationshipsOf<E> & string]: RelationshipsOf<E>[K] extends ToOne ? string extends TargetNameOf<RelationshipsOf<E>[K]> ? `${K}.${string}` : `${K}.${PathEnds<EntityNamed<O, TargetNameOf<RelationshipsOf<E>[K]>>, O, Again>}` : never;
+}[keyof RelationshipsOf<E> & string];
+/**
+ * Related properties of `E` as aggregate paths through at most two `rel.one` relationships:
+ * `product.brand`, `product.brand.name`. A thunk target erases its entity, so any path may follow
+ * its relationship: `` `${relationship}.${string}` ``.
+ */
+type PathsOf<E, O> = PathsFrom<E, O, true>;
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/**
+ * A snake_case entity name in camelCase, keeping an `_` before a digit so the name converts back:
+ * `sales_2025` stays, `wb2_sales` is `wb2Sales`. The client decodes model-level names the same way.
+ */
+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;
+/** 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>;
+/**
+ * `entity.property` for every entity's scalar properties, and `id` for stored entities, plus the
+ * routes `entity.relationship.property` from each entity with measures.
+ */
+type ModelDimensionsOf<E, O> = E extends unknown ? `${CamelCase<NameOf<E>>}.${FieldsOf<E> | RoutesOf<E, O>}` : never;
+/**
+ * `segmentstream.ontology.aggregate`: `POST /api/ontology/aggregate`, as the signed-in user, who
+ * needs read permission on every entity the request reaches.
+ */
+export interface ModelAggregateClient<Measure extends string = string, Dimension extends string = string> {
+    readonly aggregate: (request: ModelAggregateRequest<Measure, Dimension>, options?: RequestOptions) => Promise<AggregateResult>;
+}
+export interface AggregateEntityClient<Property extends string = string, Measure extends string = string, Temporal extends Property = Property, Path extends string = never> {
+    readonly aggregate: (request: AggregateRequest<Property, Measure, Temporal, Path>, options?: RequestOptions) => Promise<AggregateResult>;
+}
+type ClientOf<E, O> = IsWarehouseBacked<E> extends true ? AggregateEntityClient<keyof PropertiesOf<E> & string, MeasuresOf<E>, keyof PropertiesOf<E> & string, PathsOf<E, O>> : EntityClient<RecordOf<E>, ActionClients<ActionsOf<E>>>;
 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>>;
 /** A client for any entity, when the app passes no ontology type. */
-export type UntypedOntologyClient = {
+export type UntypedOntologyClient = ModelAggregateClient & {
     readonly [entity: string]: EntityClient<JsonRecord, {
         readonly [action: string]: ActionCall<JsonRecord, JsonValue>;
     }> & AggregateEntityClient;
 };
 /**
  * `segmentstream.ontology`: one client per entity of `O`, the type of the app's ontology
- * (`typeof ontology`). Without it, any entity name is accepted and records are untyped.
+ * (`typeof ontology`), and `aggregate` across them. `aggregate` is a reserved entity name. Without
+ * `O`, any entity name is accepted and records are untyped.
  */
 export type OntologyClient<O = unknown> = unknown extends O ? UntypedOntologyClient : TypedOntologyClient<O>;
 /** Sends one ontology request with the caller's credentials. Paths are below `/api/ontology`. */
@@ -226,7 +294,7 @@ export interface OntologyTransport {
  * Entities and actions exist only in the app's types, so the client resolves them by name when
  * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
  */
-export declare function createOntologyClient<O>(transport: OntologyTransport, aggregateTransport?: OntologyTransport): OntologyClient<O>;
+export declare function createOntologyClient<O>(transport: OntologyTransport): OntologyClient<O>;
 /** `find` sends the query as URL parameters: `where` as JSON, `orderBy` as `field:direction`. */
 export declare function findParameters(query: OntologyQuery<JsonRecord>): URLSearchParams;
 export {};

package/dist/ontology.js

@@ -1,8 +1,10 @@
 import { SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
 import { actionInputToWire, encodeWhere, editsFromWire, queryToWire, recordFromWire, responseFromWire, } from "./ontology-wire.js";
-import { toCamelCase, toSnakeCase } from "./ontology-names.js";
+import { toCamelCase, toReversibleCamelCase, toSnakeCase } from "./ontology-names.js";
 const ENTITY_NAME = /^[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*$/;
 const ACTION_NAME = ENTITY_NAME;
+/** The ontology service's model-level aggregate, `/api/ontology/aggregate`; never an entity. */
+const MODEL_AGGREGATE = "aggregate";
 /** Names a caller may probe on any object; never an entity or an action. */
 const RESERVED = new Set([
     "then",
@@ -21,11 +23,16 @@ const RESERVED = new Set([
  * Entities and actions exist only in the app's types, so the client resolves them by name when
  * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
  */
-export function createOntologyClient(transport, aggregateTransport) {
+export function createOntologyClient(transport) {
     const entities = new Map();
     const catalogReader = createCatalogReader(transport);
+    // Every call, aggregates included, carries the user's session: the service checks permissions.
+    const aggregate = (request, options = {}) => send(catalogReader.transport, "POST", `/${MODEL_AGGREGATE}`, aggregateToWire(request), options.signal).then(modelAggregateResultFromWire);
     return new Proxy(Object.create(null), {
         get(_target, property) {
+            if (property === MODEL_AGGREGATE) {
+                return aggregate;
+            }
             if (typeof property !== "string" || RESERVED.has(property) || !ENTITY_NAME.test(property)) {
                 return undefined;
             }
@@ -33,16 +40,8 @@ export function createOntologyClient(transport, aggregateTransport) {
             if (client === undefined) {
                 client = {
                     ...entityClient(toSnakeCase(property), catalogReader.transport, catalogReader.getCatalog),
-                    aggregate: (request, options = {}) => {
-                        if (!aggregateTransport) {
-                            throw new TypeError("An aggregate transport is required.");
-                        }
-                        return send(aggregateTransport, "POST", `/${toSnakeCase(property)}/aggregate`, aggregateToWire(request), options.signal).then((result) => ({
-                            ...result,
-                            fields: result.fields.map((field) => ({ ...field, name: toCamelCase(field.name) })),
-                            rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [toCamelCase(name), value]))),
-                        }));
-                    },
+                    // Names are relative to the entity and convert as record fields do.
+                    aggregate: (request, options = {}) => send(catalogReader.transport, "POST", `/${toSnakeCase(property)}/aggregate`, aggregateToWire(request), options.signal).then((result) => aggregateResultFromWire(result, toCamelCase)),
                 };
                 entities.set(property, client);
             }
@@ -212,11 +211,16 @@ export function findParameters(query) {
     }
     return search;
 }
-/** The platform aggregate API keeps its existing protocol keys; ontology identifiers are canonical. */
+/**
+ * Aggregate requests keep their camelCase protocol keys and filter values; the names in them convert
+ * to snake_case one segment at a time.
+ */
 function aggregateToWire(request) {
     return {
         ...request,
-        dimensions: request.dimensions.map(toSnakeCase),
+        ...(request.dimensions === undefined
+            ? {}
+            : { dimensions: request.dimensions.map(toSnakeCase) }),
         measures: request.measures.map(toSnakeCase),
         ...(request.granularityOf === undefined
             ? {}
@@ -240,6 +244,39 @@ function aggregateToWire(request) {
             }),
     };
 }
+/**
+ * Field names, the filters each measure applied and row keys come back camelCase per segment;
+ * `execution` is passed on as sent.
+ */
+function aggregateResultFromWire(result, decodeName) {
+    return {
+        ...result,
+        fields: result.fields.map((field) => ({
+            ...field,
+            name: decodeName(field.name),
+            ...(field.filters === undefined ? {} : { filters: field.filters.map(decodeName) }),
+        })),
+        rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [decodeName(name), value]))),
+    };
+}
+/** Model-level names keep an `_` before a digit, and the entities in `sources` convert too. */
+function modelAggregateResultFromWire(wire) {
+    const result = aggregateResultFromWire(wire, toReversibleCamelCase);
+    const sources = result.execution.sources;
+    if (sources === undefined) {
+        return result;
+    }
+    return {
+        ...result,
+        execution: {
+            ...result.execution,
+            sources: sources.map((source) => ({
+                ...source,
+                entity: toReversibleCamelCase(source.entity),
+            })),
+        },
+    };
+}
 async function send(transport, method, path, body, signal) {
     const headers = new Headers({ accept: "application/json" });
     if (body !== undefined) {

package/dist/pages.d.ts

@@ -0,0 +1,6 @@
+/** The app's page where a signed-in member decides whether an agent may act for them. */
+export declare const CONSENT_PAGE = "/oauth/consent";
+/** The app's page where a signed-in member links their chat account to the workspace agent. */
+export declare const AGENT_CONNECT_PAGE = "/agent/connect";
+/** The Route Handler the agent connect page's form posts to. */
+export declare const AGENT_CONNECT_HANDLER = "/api/agent/connect";

package/dist/pages.js

@@ -0,0 +1,6 @@
+/** The app's page where a signed-in member decides whether an agent may act for them. */
+export const CONSENT_PAGE = "/oauth/consent";
+/** The app's page where a signed-in member links their chat account to the workspace agent. */
+export const AGENT_CONNECT_PAGE = "/agent/connect";
+/** The Route Handler the agent connect page's form posts to. */
+export const AGENT_CONNECT_HANDLER = "/api/agent/connect";

package/dist/ui/agent-connect.d.ts

@@ -0,0 +1,18 @@
+import type { AgentPairing } from "../agent.js";
+export interface AgentConnectProps {
+    /** The page's `code` query parameter, from the agent's link. */
+    readonly code: string | undefined;
+    /** `segmentstream.agent.pairing(code)`, or `null` when the code no longer works. */
+    readonly pairing: AgentPairing | null;
+    /** The page's `connected` query parameter: the channel just linked, after approval. */
+    readonly connected?: string | undefined;
+    /** Who is signed in, such as their email, so they see whom the chat account will act as. */
+    readonly member?: string | undefined;
+    /** Where the form posts. Defaults to `/api/agent/connect`, `segmentstream.agent.connectHandler()`. */
+    readonly action?: string;
+}
+/**
+ * The agent connect page in the SDK's neutral styles: what asks to be linked, an Approve button and
+ * the result. Render it from the Server Component at `/agent/connect` with the pairing it read.
+ */
+export declare function AgentConnect({ code, pairing, connected, member, action, }: AgentConnectProps): import("react").JSX.Element;

package/dist/ui/agent-connect.js

@@ -0,0 +1,23 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId } from "react";
+import { AGENT_CONNECT_HANDLER } from "../pages.js";
+/**
+ * The agent connect page in the SDK's neutral styles: what asks to be linked, an Approve button and
+ * the result. Render it from the Server Component at `/agent/connect` with the pairing it read.
+ */
+export function AgentConnect({ code, pairing, connected, member = "you", action = AGENT_CONNECT_HANDLER, }) {
+    const titleId = `${useId()}-title`;
+    if (connected !== undefined) {
+        return (_jsxs("section", { className: "ss-card", "aria-labelledby": titleId, children: [_jsxs("h1", { id: titleId, className: "ss-title", children: [providerName(connected), " is connected"] }), _jsxs("p", { className: "ss-text", children: ["The agent now acts as ", _jsx("strong", { children: member }), " when you write to it there. Go back to the chat and send your message again."] })] }));
+    }
+    if (code === undefined || code === "" || pairing === null) {
+        return (_jsxs("section", { className: "ss-card", "aria-labelledby": titleId, children: [_jsx("h1", { id: titleId, className: "ss-title", children: "This link has expired" }), _jsx("p", { className: "ss-text", children: "The link was already used or is more than ten minutes old. Write to the agent again for a new one." })] }));
+    }
+    const provider = providerName(pairing.provider);
+    return (_jsxs("section", { className: "ss-card", "aria-labelledby": titleId, children: [_jsxs("h1", { id: titleId, className: "ss-title", children: ["Connect ", provider, " to this app?"] }), _jsxs("p", { className: "ss-text", children: [pairing.display === null ? (`A ${provider} account`) : (_jsxs(_Fragment, { children: [_jsx("strong", { children: pairing.display }), " on ", provider] })), " ", "asks to talk to the workspace agent as ", _jsx("strong", { children: member }), ". The agent answers it with your permissions, and history records its changes under your name. Approve only if this is your own account."] }), _jsxs("form", { className: "ss-form", method: "post", action: action, children: [_jsx("input", { type: "hidden", name: "code", value: code }), _jsx("button", { type: "submit", className: "ss-button", children: "Approve" })] })] }));
+}
+/** `telegram` reads as `Telegram`. */
+function providerName(provider) {
+    return provider.charAt(0).toUpperCase() + provider.slice(1);
+}

package/dist/ui/index.d.ts

@@ -1,5 +1,7 @@
 export { Can, SignedIn, SignedOut, UserMenu, signOut } from "./components.js";
 export type { CanProps, ChildrenProps, UserMenuProps } from "./components.js";
+export { AgentConnect } from "./agent-connect.js";
+export type { AgentConnectProps } from "./agent-connect.js";
 export { usePermissions, useSession, useUser } from "./hooks.js";
 export type { Permissions } from "./hooks.js";
 export { SignIn } from "./sign-in.js";
@@ -9,4 +11,5 @@ export type { SignInController, SignInErrorCode, SignInNoticeCode, SignInOptions
 export type { SessionState, SessionUser, UserState } from "./store.js";
 export { isAllowed } from "../permissions.js";
 export type { CurrentUser } from "../me.js";
+export type { AgentPairing } from "../agent.js";
 export { SegmentStreamApiError, NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";

package/dist/ui/index.js

@@ -3,6 +3,7 @@
 // layout, when rendering the components: `import "@segmentstream-cloud/app/ui/styles.css";`. The
 // hooks, `useSignIn()` among them, need no stylesheet.
 export { Can, SignedIn, SignedOut, UserMenu, signOut } from "./components.js";
+export { AgentConnect } from "./agent-connect.js";
 export { usePermissions, useSession, useUser } from "./hooks.js";
 export { SignIn } from "./sign-in.js";
 export { SIGN_IN_ERROR_MESSAGES, signInErrorCode, signInErrorMessage, useSignIn, } from "./use-sign-in.js";

package/package.json

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