@segmentstream-cloud/app 0.17.0 → 0.17.2

package/README.md

@@ -347,16 +347,19 @@ 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`   |
+| 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; `303` on success; throws on conflict |
 
 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
+`/agent/connect?expired=1` when the code was used or is older than ten minutes. An account already
+connected to another member throws `SegmentStreamApiError` with status `409` and
+`code === "identity_in_use"` through the app's existing error mechanism. The app owns conflict copy.
+Same-member pairing is idempotent, and replacing your own previous account on a provider is supported. 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
@@ -698,6 +701,34 @@ Replace segmentstream.semantic with typed warehouse-backed entity aggregates. Se
   deployed with `@segmentstream-cloud/ontology` 0.17.0 or later. Requests that use none of
   them work as before.
 
+## Request timing
+
+Wrap app Route Handlers to add `Server-Timing: app;dur=…`, `x-request-id` and safe
+structured `app.request` runtime logs:
+
+```ts
+import { withRequestTiming } from "@segmentstream-cloud/app";
+
+export const GET = withRequestTiming(async (request: Request) => {
+  return Response.json({ ok: true });
+});
+```
+
+The wrapper passes handler arguments through and preserves response headers and
+streaming bodies. It logs duration, method, HTTP status and a generated request ID,
+excluding URLs, cookies, bodies and error details. Errors propagate unchanged.
+Next.js redirects and `notFound()` log their HTTP status and propagate unchanged;
+other Next.js control-flow exceptions log `status: null` because Next owns their eventual response.
+Those exceptions cannot receive timing headers here;
+return an explicit response when the wrapper needs to decorate its headers.
+Read these logs with `segmentstream logs --service app` (deployment permission required).
+Duration ends when the handler returns response headers; it excludes later stream
+work and browser rendering. It is opt-in for Route Handlers, not a page renderer
+or a web vitals collector. A Next.js proxy cannot time the downstream page render.
+
+Ontology SDK 0.31.2 adds request timing for ontology calls automatically. Timings
+are available in hosted logs; retained diagnostics are tracked in issue #520.
+
 ## Upgrading to 0.14
 
 - `segmentstream.ontology.aggregate()` accepts the measures of the model by their bare names, typed

package/dist/agent.d.ts

@@ -34,7 +34,8 @@ export interface AgentIdentities {
     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`).
+     * 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>;

package/dist/agent.js

@@ -9,6 +9,7 @@ const GONE_CODES = new Set(["not_found", "expired"]);
 const STATUS_CODES = {
     403: "forbidden",
     404: "not_found",
+    409: "identity_in_use",
     410: "expired",
 };
 function pairingPath(code, approve) {

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export declare function createSegmentStreamApp<O = unknown>(config: SegmentStrea
 export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
+export { withRequestTiming } from "./request-timing.js";
 export type { AuthenticationMethod, SegmentStreamApp } from "./app.js";
 export { CONSENT_PAGE } from "./oauth.js";
 export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./agent.js";

package/dist/index.js

@@ -19,6 +19,7 @@ export function createSegmentStreamApp(config) {
 export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
+export { withRequestTiming } from "./request-timing.js";
 export { CONSENT_PAGE } from "./oauth.js";
 export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./agent.js";
 export { createBlobStorageClient, } from "./storage.js";

package/dist/request-timing.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Time an app Route Handler until it returns response headers. Streaming/rendering after that
+ * point is excluded. Logs contain no URL, cookies, body or error text. Server Components need
+ * framework instrumentation for complete page timing; a Next.js proxy only times authentication.
+ */
+export declare function withRequestTiming<R extends Request, A extends unknown[]>(handler: (request: R, ...args: A) => Promise<Response>): (request: R, ...args: A) => Promise<Response>;

package/dist/request-timing.js

@@ -0,0 +1,53 @@
+import { unstable_rethrow } from "next/navigation";
+import { getRedirectStatusCodeFromError } from "next/dist/client/components/redirect.js";
+import { isRedirectError } from "next/dist/client/components/redirect-error.js";
+import { getAccessFallbackHTTPStatus, isHTTPAccessFallbackError, } from "next/dist/client/components/http-access-fallback/http-access-fallback.js";
+/**
+ * Time an app Route Handler until it returns response headers. Streaming/rendering after that
+ * point is excluded. Logs contain no URL, cookies, body or error text. Server Components need
+ * framework instrumentation for complete page timing; a Next.js proxy only times authentication.
+ */
+export function withRequestTiming(handler) {
+    return async (request, ...args) => {
+        const started = performance.now();
+        const requestId = crypto.randomUUID();
+        let status = 500;
+        let durationMs;
+        try {
+            const response = await handler(request, ...args);
+            const headers = new Headers(response.headers);
+            durationMs = Math.round((performance.now() - started) * 100) / 100;
+            status = response.status;
+            headers.append("server-timing", `app;dur=${durationMs}`);
+            headers.set("x-request-id", requestId);
+            return new Response(response.body, {
+                status,
+                statusText: response.statusText,
+                headers,
+            });
+        }
+        catch (error) {
+            try {
+                unstable_rethrow(error);
+            }
+            catch {
+                // Next owns the eventual response for control-flow exceptions, outside this wrapper.
+                status = isRedirectError(error)
+                    ? getRedirectStatusCodeFromError(error)
+                    : isHTTPAccessFallbackError(error)
+                        ? getAccessFallbackHTTPStatus(error)
+                        : null;
+            }
+            throw error;
+        }
+        finally {
+            console.info(JSON.stringify({
+                event: "app.request",
+                requestId,
+                method: request.method,
+                status,
+                durationMs: durationMs ?? Math.round((performance.now() - started) * 100) / 100,
+            }));
+        }
+    };
+}

package/package.json

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