@segmentstream/app 0.0.0-stage → 0.38.0

package/dist/agent.d.ts

@@ -0,0 +1,56 @@
+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`), a member it does not admit (`forbidden`), or an
+     * account linked to another member (`identity_in_use`, HTTP 409).
+     * 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,203 @@
+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",
+    409: "identity_in_use",
+    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

@@ -0,0 +1,82 @@
+import { type DeploymentObservation } from "./deployment.js";
+import type { Environment, SegmentStreamAppConfig } from "./config.js";
+import type { AgentIdentities } from "./agent.js";
+import type { WarehouseClient } from "./data.js";
+import type { JobsClient } from "./jobs.js";
+import type { SegmentStreamRouteHandlers } from "./handlers.js";
+import type { AgentAuthorizations } from "./oauth.js";
+import type { AuthRouteHandlers, CreateNeonAuth, SignOutOptions, UserOptions } from "./neon.js";
+import type { OntologyClient } from "./ontology.js";
+import type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
+import type { Fetch } from "./sessions.js";
+import type { AppUser, KeySet } from "./tokens.js";
+/** Primary server integration; declared browser methods take precedence over legacy environment discovery. */
+export type AuthenticationMethod = "neon-auth" | "segmentstream";
+/**
+ * The app's SegmentStream integration. `O` is the type of the app's ontology,
+ * `typeof import("../../ontology").default`, which types {@link SegmentStreamApp.ontology}.
+ */
+export interface SegmentStreamApp<O = unknown> {
+    readonly deployment: DeploymentObservation;
+    /** `neon-auth` when email is enabled and configured; otherwise `segmentstream`. */
+    readonly authentication: AuthenticationMethod;
+    /** The Next.js Proxy that keeps every non-public request signed in. */
+    readonly proxy: (options?: ProxyOptions) => SegmentStreamProxy;
+    /** Route Handlers for `app/src/app/api/auth/[...path]/route.ts`: the Neon Auth API. */
+    readonly authHandlers: () => AuthRouteHandlers;
+    /** Route Handlers for `app/api/segmentstream/[...path]/route.ts`: the legacy sign-in. */
+    readonly handlers: () => SegmentStreamRouteHandlers;
+    /**
+     * The signed-in user for this request, or `null`. Roles and permissions are cached per session
+     * for a minute; `{ fresh: true }` asks the ontology again.
+     */
+    readonly getUser: (options?: UserOptions) => Promise<AppUser | null>;
+    /** The signed-in user; redirects to sign-in when there is none. Takes `{ fresh }` as `getUser`. */
+    readonly requireUser: (options?: UserOptions) => Promise<AppUser>;
+    /**
+     * Whether the signed-in user's permissions cover `permission`, wildcards included. Takes
+     * `{ fresh }` as `getUser`.
+     */
+    readonly can: (permission: string, options?: UserOptions) => Promise<boolean>;
+    /**
+     * Ends the session and redirects to the sign-in page, or to `redirectTo`. Call it from a Server
+     * Function or Route Handler, which may change cookies.
+     */
+    readonly signOut: (options?: SignOutOptions) => Promise<never>;
+    /** The verified legacy app session token for this request, or `null`; always `null` under Neon Auth. */
+    readonly getAccessToken: () => Promise<string | null>;
+    /**
+     * Calls any SegmentStream API path as the signed-in member, with their organization role
+     * and permissions. Server-only; the session token never reaches the browser. Legacy sign-in only.
+     */
+    readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * Read-only SQL over the workspace warehouse. Server-only. Uses the workspace app credential
+     * (`SEGMENTSTREAM_APP_CREDENTIAL`) when it is set, else the signed-in member's session.
+     */
+    readonly warehouse: WarehouseClient;
+    /** Start and read pipeline runs with the workspace credential. Server-only; gate app users. */
+    readonly jobs: JobsClient;
+    /** The app's ontology service, `/api/ontology`, as the signed-in user. Server-only. */
+    readonly ontology: OntologyClient<O>;
+    /**
+     * Agents connecting to the app's MCP server: the request the consent page shows the signed-in
+     * 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 {
+    readonly fetch: Fetch;
+    readonly keySet: KeySet;
+    readonly environment: Environment;
+    readonly createNeonAuth: CreateNeonAuth;
+    readonly now: () => number;
+}
+export declare function createApp<O = unknown>(config: SegmentStreamAppConfig, dependencies?: Partial<AppDependencies>): SegmentStreamApp<O>;