@mercury-fw/channel-http 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @mercury-fw/channel-http
 
+## 0.13.1
+
+### Patch Changes
+
+- f631dd5: README: a link to the package's page on Mercury's documentation site (https://lucabro81.github.io/mercury-fw/), published from this release on. The HTTP channel's README points to the HTTP API reference there, and the core's memory section to the page that explains it.
+
+## 0.13.0
+
+### Minor Changes
+
+- 7c9a038: - `GET /version` answers the framework's version (`{ ok: true, version: "0.59.0" }`) with no token, for a UI to show which Mercury it's talking to.
+  - The channel now needs the framework at 0.59 or later (peer range `>=0.59.0 <1.0.0`), the first whose core gives channels its version.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,9 @@
 
 Gives a [Mercury](https://github.com/lucabro81/mercury-fw) agent an HTTP surface to build a custom UI on: one conversational turn per request, streamed back as Server-Sent Events, plus confirmation and read-only routes over what the agent holds (conversations, the wiki, memory, its plugins).
 
-This version is written for version 6 of the channel contract, the one that brings the channels' texts in the person's language, and needs the framework at 0.54 or later: a core with an older contract skips it, and the log says why. `X-Time-Zone` and `PATCH /me` need the framework at 0.56 or later: an older core ignores the header and offers no `PATCH /me`.
+On Mercury's documentation site: [its page](https://lucabro81.github.io/mercury-fw/plugins/channel-http/).
+
+This version is written for version 6 of the channel contract, the one that brings the channels' texts in the person's language, and needs the framework at 0.59 or later, the first whose core gives channels its version (`GET /version`). A core with an older contract skips it, and the log says why.
 
 ```bash
 bun add @mercury-fw/channel-http
@@ -29,13 +31,13 @@ It needs an auth provider next to it, or several (`auth: [a, b]`, tried in order
 
 It's active whenever it's declared in `mercury.config.ts`'s `channels` with an auth provider; remove it there to turn the surface off. It listens on `HTTP_SURFACE_PORT` (default `4100`). Base URL `http://<host>:<port>`.
 
-**Authentication.** Every route except `GET /openapi.yaml`, `GET /login/callback` and the `OPTIONS` preflights needs `Authorization: Bearer <token>`, and the auth providers decide who the token belongs to: the first that recognizes it. A missing or refused token gets `401` with `WWW-Authenticate: Bearer` before anything runs. Then the core decides whether it talks to that person at all: someone the app's directory doesn't know gets `403` (unless the app lets unknown people in), and `503` when the directory can't be reached, both with `{ ok: false, error, reason }`, where `error` is what to tell them.
+**Authentication.** Every route except `GET /openapi.yaml`, `GET /version`, `GET /login/callback` and the `OPTIONS` preflights needs `Authorization: Bearer <token>`, and the auth providers decide who the token belongs to: the first that recognizes it. A missing or refused token gets `401` with `WWW-Authenticate: Bearer` before anything runs. Then the core decides whether it talks to that person at all: someone the app's directory doesn't know gets `403` (unless the app lets unknown people in), and `503` when the directory can't be reached, both with `{ ok: false, error, reason }`, where `error` is what to tell them.
 
 **Conversations belong to whoever opened them.** The session key is `<caller id>:<conversationId>`, so the same `conversationId` sent by someone else is a conversation of their own, and a confirmation token staged in your conversation can't be confirmed from theirs. Each authenticated caller also gets their own episodic memory and wiki area, as on Google Chat.
 
 **CORS** is enabled on every response and every route answers an `OPTIONS` preflight, so a browser UI on another origin can call it. The allowed origin is `HTTP_SURFACE_CORS_ORIGIN` (default `*`: the token travels in a header, never in a cookie the browser would send on its own).
 
-The full contract is described by an **OpenAPI document**, served raw at `GET /openapi.yaml` and published as a rendered docs page on GitHub Pages (see `packages/channels/channel-http/openapi.yaml`, the single source of truth).
+The full contract is described by an **OpenAPI document**, served raw at `GET /openapi.yaml` and published as [the HTTP API reference](https://lucabro81.github.io/mercury-fw/reference/http-api/) on the documentation site (see `packages/channels/channel-http/openapi.yaml`, the single source of truth).
 
 All responses are JSON except `POST /turn`, which streams `text/event-stream`. Every JSON response is either `{ "ok": true, ... }` or, on error, `{ "ok": false, "error": "<message>" }` with HTTP `400`/`401`/`500`.
 
@@ -119,3 +121,7 @@ All `GET`, all JSON, all reporting state already held in-process. They need an a
 | `GET /openapi.yaml` | the OpenAPI document for this surface (`text/yaml`) |
 
 Conversation history and the conversation list are backed by the durable verbatim archive; they degrade to empty when the vector store is unreachable.
+
+## `GET /version`
+
+Which Mercury this is, for a UI to show: `{ ok: true, version }`, the framework's version as `major.minor.patch` (`"0.59.0"`), the one of `@mercury-fw/core`, not this channel's own. It needs no token.

package/dist/http-provider.d.ts

@@ -42,6 +42,8 @@ export type HttpProviderDeps = {
     assistantName?: string;
     /** The texts in each caller's language (`ctx.i18n`). */
     i18n?: ChannelI18n;
+    /** The framework's version, served on `/version` (`ctx.frameworkVersion`). */
+    version?: string;
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -15,7 +15,7 @@
  * `/login/callback` is where a person's browser comes back after logging in to
  * a service a plugin acts on as them; the single-use state is its credential.
  *
- * Every route but the OpenAPI document, the login callback and the CORS
+ * Every route but the OpenAPI document, `/version`, the login callback and the CORS
  * preflights asks the injected `authenticate` (the auth provider the app declares) who is calling
  * before anything runs, and answers 401 when nobody is. A conversation belongs
  * to whoever opened it: the session key is `<principal.id>:<conversationId>`.
@@ -47,9 +47,9 @@ export type TurnRequestDeps = {
 };
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
- * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
- * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
+ * of truth in this package's `openapi.yaml`, also rendered as the docs site's
+ * HTTP API reference. Served raw as `text/yaml` (no YAML parser needed at
+ * runtime); most tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */
 export declare function openApiResponse(corsOrigin?: string): Response;
 /**
@@ -157,6 +157,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     settings?: ChannelSettings;
     /** What the pages people read call the assistant. */
     assistantName?: string;
+    /** The framework's version; `/version` is mounted only with it. */
+    version?: string;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * The HTTP channel plugin: an opt-in conversational HTTP surface (SSE `/turn`,
- * `/confirm`, read-only introspection routes, the OpenAPI doc) that a custom UI
+ * `/confirm`, read-only introspection routes, the OpenAPI doc, `/version`) that a custom UI
  * calls. Exported as a `ChannelPlugin` the core's channel loader consumes; it
  * does not import the app. Enabled by listing it in `mercury.config.ts` — there
  * is no runtime inert condition (unlike Google Chat's subscription): if it's

package/http-provider.ts

@@ -39,6 +39,8 @@ export type HttpProviderDeps = {
   assistantName?: string;
   /** The texts in each caller's language (`ctx.i18n`). */
   i18n?: ChannelI18n;
+  /** The framework's version, served on `/version` (`ctx.frameworkVersion`). */
+  version?: string;
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -60,6 +62,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         ...(deps.resumeMaxChars === undefined ? {} : { resumeMaxChars: deps.resumeMaxChars }),
         ...(deps.assistantName === undefined ? {} : { assistantName: deps.assistantName }),
         ...(deps.i18n === undefined ? {} : { i18n: deps.i18n }),
+        ...(deps.version === undefined ? {} : { version: deps.version }),
       });
       deps.logins?.accept(deps.logins.callbackUrl);
     },

package/http-server.ts

@@ -15,7 +15,7 @@
  * `/login/callback` is where a person's browser comes back after logging in to
  * a service a plugin acts on as them; the single-use state is its credential.
  *
- * Every route but the OpenAPI document, the login callback and the CORS
+ * Every route but the OpenAPI document, `/version`, the login callback and the CORS
  * preflights asks the injected `authenticate` (the auth provider the app declares) who is calling
  * before anything runs, and answers 401 when nobody is. A conversation belongs
  * to whoever opened it: the session key is `<principal.id>:<conversationId>`.
@@ -153,9 +153,9 @@ function preflight(origin: string): Response {
 
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
- * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
- * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
+ * of truth in this package's `openapi.yaml`, also rendered as the docs site's
+ * HTTP API reference. Served raw as `text/yaml` (no YAML parser needed at
+ * runtime); most tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */
 export function openApiResponse(corsOrigin = "*"): Response {
   const file = Bun.file(new URL("./openapi.yaml", import.meta.url));
@@ -579,6 +579,19 @@ export function readRoutes(
   };
 }
 
+/**
+ * `GET /version`: which Mercury this is (the framework's version), for any
+ * front end to show. Nobody is asked who they are, like `/openapi.yaml`.
+ */
+function versionRoutes(version: string, corsOrigin = "*"): Record<string, ReadRoute> {
+  return {
+    "/version": {
+      GET: () => Response.json({ ok: true, version }, { headers: corsHeaders(corsOrigin) }),
+      OPTIONS: () => preflight(corsOrigin),
+    },
+  };
+}
+
 export type HttpServerDeps = TurnRequestDeps & {
   port: number;
   reads?: ChannelHostReads;
@@ -592,6 +605,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   settings?: ChannelSettings;
   /** What the pages people read call the assistant. */
   assistantName?: string;
+  /** The framework's version; `/version` is mounted only with it. */
+  version?: string;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -623,6 +638,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
         OPTIONS: () => preflight(origin),
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
+      ...(deps.version === undefined ? {} : versionRoutes(deps.version, origin)),
       ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit, deps.settings) : {}),
       ...(deps.completeLogin ? loginRoutes(deps.completeLogin, deps.assistantName, deps.i18n) : {}),
       ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),

package/index.ts

@@ -1,6 +1,6 @@
 /**
  * The HTTP channel plugin: an opt-in conversational HTTP surface (SSE `/turn`,
- * `/confirm`, read-only introspection routes, the OpenAPI doc) that a custom UI
+ * `/confirm`, read-only introspection routes, the OpenAPI doc, `/version`) that a custom UI
  * calls. Exported as a `ChannelPlugin` the core's channel loader consumes; it
  * does not import the app. Enabled by listing it in `mercury.config.ts` — there
  * is no runtime inert condition (unlike Google Chat's subscription): if it's
@@ -51,6 +51,7 @@ export const httpChannel: ChannelPlugin = {
       ...(ctx.settings === undefined ? {} : { settings: ctx.settings }),
       ...(resumeMaxChars === undefined ? {} : { resumeMaxChars }),
       ...(ctx.assistantName === undefined ? {} : { assistantName: ctx.assistantName }),
+      ...(ctx.frameworkVersion === undefined ? {} : { version: ctx.frameworkVersion }),
       ...(logins ? { logins: { callbackUrl: `${publicUrl}/login/callback`, accept: logins.accept, complete: logins.complete } } : {}),
     });
   },

package/openapi.yaml

@@ -14,7 +14,7 @@ info:
 
     ## Authentication
 
-    Every route except this document and the `OPTIONS` preflights needs
+    Every route except this document, `/version` and the `OPTIONS` preflights needs
     `Authorization: Bearer <token>`. The app's auth provider decides what a
     valid token is (an OpenID Connect access token, a static test token); a
     missing or refused one gets `401` with `WWW-Authenticate: Bearer`, before
@@ -589,6 +589,27 @@ paths:
           content:
             text/plain:
               schema: { type: string }
+  /version:
+    get:
+      summary: Which Mercury this is
+      description: >
+        The framework's version, `major.minor.patch`, for a UI to show. Needs
+        no bearer token.
+      security: []
+      responses:
+        "200":
+          description: The framework's version.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, version]
+                properties:
+                  ok: { type: boolean, const: true }
+                  version:
+                    type: string
+                    pattern: '^\d+\.\d+\.\d+$'
+                    examples: ["0.59.0"]
   /openapi.yaml:
     get:
       summary: This OpenAPI document

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.54.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.59.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.56.0",
-    "@mercury-fw/plugin-types": "0.56.0",
+    "@mercury-fw/channel-types": "0.59.2",
+    "@mercury-fw/plugin-types": "0.59.2",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"