@segmentstream-cloud/app 0.10.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

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,
@@ -57,6 +59,7 @@ export function createApp(config, dependencies = {}) {
             warehouse: data.warehouse,
             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,
@@ -86,6 +89,7 @@ export function createApp(config, dependencies = {}) {
         warehouse: data.warehouse,
         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. */

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,6 +20,8 @@ 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";
@@ -33,3 +35,5 @@ 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/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.10.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",