@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/agent-api-catalog.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+type Schema = Record<string, unknown>;
+/** The well-known location RFC 9727 reserves for an API catalog. */
+export declare const API_CATALOG_PATH = "/.well-known/api-catalog";
+/**
+ * The linkset media type RFC 9727 REQUIRES the catalog to support.
+ *
+ * Not `application/json`. RFC 9727 §3 says a catalog "MUST support the Linkset
+ * [RFC9264] format of application/linkset+json", and a client that content-
+ * negotiates for it is entitled to get it. The `+json` structured suffix means
+ * anything that parses JSON still parses this.
+ */
+export declare const API_CATALOG_MEDIA_TYPE = "application/linkset+json";
+/** One API in the catalog. */
+export interface CatalogApi {
+    /**
+     * The API's root URI. This is the linkset `anchor` — the context every one
+     * of its links hangs from — so it identifies the API rather than locating a
+     * document about it.
+     */
+    url: string;
+    /** Human label, carried as the `title` target attribute on the listing. */
+    title: string;
+    /** Machine-readable description: OpenAPI, published as `service-desc`. */
+    specUrl?: string;
+    /** Human documentation, published as `service-doc`. */
+    docsUrl?: string;
+    /**
+     * Media type of {@link docsUrl}. Defaults to HTML because that is what a
+     * documentation site serves — but a tenant's own documentation is
+     * `/llms.txt`, which is Markdown, and declaring it HTML in a document whose
+     * entire purpose is machine-readability would be a lie a client acts on.
+     */
+    docsType?: string;
+    /** Health endpoint, published as `status`. */
+    statusUrl?: string;
+}
+export interface AgentApiCatalogOptions {
+    /** The site's public origin, no trailing slash. */
+    origin: string;
+    /** The APIs to advertise, in the order a reader should meet them. */
+    apis: readonly CatalogApi[];
+}
+/**
+ * The site's API catalog (RFC 9727), as an RFC 9264 linkset.
+ *
+ * ## What this is for
+ *
+ * A tenant's `/openapi.json` describes the SITE: its pages as Markdown, its
+ * sitemap, its feeds, and the handful of JSON reads that serve them. That is an
+ * honest description of a website, and it is not the typed REST API. The typed
+ * API is the platform's, it lives on another origin, and until this document
+ * existed nothing on a customer's site pointed at it — an agent standing on
+ * `acme.com` had no way to learn that a full CRUD API describes the same data.
+ *
+ * A catalog is the published answer to exactly that question, which is why this
+ * follows RFC 9727 rather than inventing a `/apis.json`: an agent that knows
+ * the standard finds this without being told, and one that does not can still
+ * read it, because a linkset is plain JSON.
+ *
+ * ## The shape, and why entries are separate objects
+ *
+ * A linkset is a list of link CONTEXTS, each keyed by its `anchor`. The first
+ * context is anchored at the catalog itself and carries the `item` links — the
+ * membership list, "these are my APIs". Every context after it is anchored at
+ * one API's own root and carries that API's `service-desc`, `service-doc` and
+ * `status`. Folding the metadata into the `item` entries would say something
+ * different and weaker: that the CATALOG has a description, rather than that
+ * each API does.
+ *
+ * ## Absent members are omitted, never emitted empty
+ *
+ * An operator running this platform themselves configures their own console
+ * and docs origins, and may have neither. A `service-doc` pointing at an empty
+ * string is a link an agent will follow and a 404 it will attribute to us, so
+ * an API with nothing but an anchor contributes no context object at all.
+ */
+export declare function buildAgentApiCatalog(options: AgentApiCatalogOptions): Schema;
+export {};

package/src/lib/app-utils/agent-api-catalog.js

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /** The well-known location RFC 9727 reserves for an API catalog. */ export const API_CATALOG_PATH = '/.well-known/api-catalog';
+/**
+ * The linkset media type RFC 9727 REQUIRES the catalog to support.
+ *
+ * Not `application/json`. RFC 9727 §3 says a catalog "MUST support the Linkset
+ * [RFC9264] format of application/linkset+json", and a client that content-
+ * negotiates for it is entitled to get it. The `+json` structured suffix means
+ * anything that parses JSON still parses this.
+ */ export const API_CATALOG_MEDIA_TYPE = 'application/linkset+json';
+/**
+ * The site's API catalog (RFC 9727), as an RFC 9264 linkset.
+ *
+ * ## What this is for
+ *
+ * A tenant's `/openapi.json` describes the SITE: its pages as Markdown, its
+ * sitemap, its feeds, and the handful of JSON reads that serve them. That is an
+ * honest description of a website, and it is not the typed REST API. The typed
+ * API is the platform's, it lives on another origin, and until this document
+ * existed nothing on a customer's site pointed at it — an agent standing on
+ * `acme.com` had no way to learn that a full CRUD API describes the same data.
+ *
+ * A catalog is the published answer to exactly that question, which is why this
+ * follows RFC 9727 rather than inventing a `/apis.json`: an agent that knows
+ * the standard finds this without being told, and one that does not can still
+ * read it, because a linkset is plain JSON.
+ *
+ * ## The shape, and why entries are separate objects
+ *
+ * A linkset is a list of link CONTEXTS, each keyed by its `anchor`. The first
+ * context is anchored at the catalog itself and carries the `item` links — the
+ * membership list, "these are my APIs". Every context after it is anchored at
+ * one API's own root and carries that API's `service-desc`, `service-doc` and
+ * `status`. Folding the metadata into the `item` entries would say something
+ * different and weaker: that the CATALOG has a description, rather than that
+ * each API does.
+ *
+ * ## Absent members are omitted, never emitted empty
+ *
+ * An operator running this platform themselves configures their own console
+ * and docs origins, and may have neither. A `service-doc` pointing at an empty
+ * string is a link an agent will follow and a 404 it will attribute to us, so
+ * an API with nothing but an anchor contributes no context object at all.
+ */ export function buildAgentApiCatalog(options) {
+    const origin = options.origin.replace(/\/+$/, '');
+    const linkset = [
+        {
+            anchor: `${origin}${API_CATALOG_PATH}`,
+            item: options.apis.map((api)=>({
+                    href: api.url,
+                    title: api.title
+                }))
+        }
+    ];
+    for (const api of options.apis){
+        const context = {
+            anchor: api.url
+        };
+        if (api.specUrl) {
+            context['service-desc'] = [
+                {
+                    href: api.specUrl,
+                    type: 'application/json'
+                }
+            ];
+        }
+        if (api.docsUrl) {
+            var _api_docsType;
+            context['service-doc'] = [
+                {
+                    href: api.docsUrl,
+                    type: (_api_docsType = api.docsType) != null ? _api_docsType : 'text/html'
+                }
+            ];
+        }
+        if (api.statusUrl) {
+            context['status'] = [
+                {
+                    href: api.statusUrl,
+                    type: 'application/json'
+                }
+            ];
+        }
+        // An anchor and nothing else describes nothing. See the note above.
+        if (Object.keys(context).length > 1) linkset.push(context);
+    }
+    return {
+        linkset
+    };
+}
+
+//# sourceMappingURL=agent-api-catalog.js.map

package/src/lib/app-utils/agent-api-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/agent-api-catalog.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\ntype Schema = Record<string, unknown>\n\n/** The well-known location RFC 9727 reserves for an API catalog. */\nexport const API_CATALOG_PATH = '/.well-known/api-catalog'\n\n/**\n * The linkset media type RFC 9727 REQUIRES the catalog to support.\n *\n * Not `application/json`. RFC 9727 §3 says a catalog \"MUST support the Linkset\n * [RFC9264] format of application/linkset+json\", and a client that content-\n * negotiates for it is entitled to get it. The `+json` structured suffix means\n * anything that parses JSON still parses this.\n */\nexport const API_CATALOG_MEDIA_TYPE = 'application/linkset+json'\n\n/** One API in the catalog. */\nexport interface CatalogApi {\n  /**\n   * The API's root URI. This is the linkset `anchor` — the context every one\n   * of its links hangs from — so it identifies the API rather than locating a\n   * document about it.\n   */\n  url: string\n  /** Human label, carried as the `title` target attribute on the listing. */\n  title: string\n  /** Machine-readable description: OpenAPI, published as `service-desc`. */\n  specUrl?: string\n  /** Human documentation, published as `service-doc`. */\n  docsUrl?: string\n  /**\n   * Media type of {@link docsUrl}. Defaults to HTML because that is what a\n   * documentation site serves — but a tenant's own documentation is\n   * `/llms.txt`, which is Markdown, and declaring it HTML in a document whose\n   * entire purpose is machine-readability would be a lie a client acts on.\n   */\n  docsType?: string\n  /** Health endpoint, published as `status`. */\n  statusUrl?: string\n}\n\nexport interface AgentApiCatalogOptions {\n  /** The site's public origin, no trailing slash. */\n  origin: string\n  /** The APIs to advertise, in the order a reader should meet them. */\n  apis: readonly CatalogApi[]\n}\n\n/**\n * The site's API catalog (RFC 9727), as an RFC 9264 linkset.\n *\n * ## What this is for\n *\n * A tenant's `/openapi.json` describes the SITE: its pages as Markdown, its\n * sitemap, its feeds, and the handful of JSON reads that serve them. That is an\n * honest description of a website, and it is not the typed REST API. The typed\n * API is the platform's, it lives on another origin, and until this document\n * existed nothing on a customer's site pointed at it — an agent standing on\n * `acme.com` had no way to learn that a full CRUD API describes the same data.\n *\n * A catalog is the published answer to exactly that question, which is why this\n * follows RFC 9727 rather than inventing a `/apis.json`: an agent that knows\n * the standard finds this without being told, and one that does not can still\n * read it, because a linkset is plain JSON.\n *\n * ## The shape, and why entries are separate objects\n *\n * A linkset is a list of link CONTEXTS, each keyed by its `anchor`. The first\n * context is anchored at the catalog itself and carries the `item` links — the\n * membership list, \"these are my APIs\". Every context after it is anchored at\n * one API's own root and carries that API's `service-desc`, `service-doc` and\n * `status`. Folding the metadata into the `item` entries would say something\n * different and weaker: that the CATALOG has a description, rather than that\n * each API does.\n *\n * ## Absent members are omitted, never emitted empty\n *\n * An operator running this platform themselves configures their own console\n * and docs origins, and may have neither. A `service-doc` pointing at an empty\n * string is a link an agent will follow and a 404 it will attribute to us, so\n * an API with nothing but an anchor contributes no context object at all.\n */\nexport function buildAgentApiCatalog(options: AgentApiCatalogOptions): Schema {\n  const origin = options.origin.replace(/\\/+$/, '')\n  const linkset: Schema[] = [\n    {\n      anchor: `${origin}${API_CATALOG_PATH}`,\n      item: options.apis.map((api) => ({ href: api.url, title: api.title })),\n    },\n  ]\n\n  for (const api of options.apis) {\n    const context: Schema = { anchor: api.url }\n    if (api.specUrl) {\n      context['service-desc'] = [\n        { href: api.specUrl, type: 'application/json' },\n      ]\n    }\n    if (api.docsUrl) {\n      context['service-doc'] = [\n        { href: api.docsUrl, type: api.docsType ?? 'text/html' },\n      ]\n    }\n    if (api.statusUrl) {\n      context['status'] = [{ href: api.statusUrl, type: 'application/json' }]\n    }\n    // An anchor and nothing else describes nothing. See the note above.\n    if (Object.keys(context).length > 1) linkset.push(context)\n  }\n\n  return { linkset }\n}\n"],"names":["API_CATALOG_PATH","API_CATALOG_MEDIA_TYPE","buildAgentApiCatalog","options","origin","replace","linkset","anchor","item","apis","map","api","href","url","title","context","specUrl","type","docsUrl","docsType","statusUrl","Object","keys","length","push"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID,kEAAkE,GAClE,OAAO,MAAMA,mBAAmB,2BAA0B;AAE1D;;;;;;;CAOC,GACD,OAAO,MAAMC,yBAAyB,2BAA0B;AAkChE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCC,GACD,OAAO,SAASC,qBAAqBC,OAA+B;IAClE,MAAMC,SAASD,QAAQC,MAAM,CAACC,OAAO,CAAC,QAAQ;IAC9C,MAAMC,UAAoB;QACxB;YACEC,QAAQ,GAAGH,SAASJ,kBAAkB;YACtCQ,MAAML,QAAQM,IAAI,CAACC,GAAG,CAAC,CAACC,MAAS,CAAA;oBAAEC,MAAMD,IAAIE,GAAG;oBAAEC,OAAOH,IAAIG,KAAK;gBAAC,CAAA;QACrE;KACD;IAED,KAAK,MAAMH,OAAOR,QAAQM,IAAI,CAAE;QAC9B,MAAMM,UAAkB;YAAER,QAAQI,IAAIE,GAAG;QAAC;QAC1C,IAAIF,IAAIK,OAAO,EAAE;YACfD,OAAO,CAAC,eAAe,GAAG;gBACxB;oBAAEH,MAAMD,IAAIK,OAAO;oBAAEC,MAAM;gBAAmB;aAC/C;QACH;QACA,IAAIN,IAAIO,OAAO,EAAE;gBAEcP;YAD7BI,OAAO,CAAC,cAAc,GAAG;gBACvB;oBAAEH,MAAMD,IAAIO,OAAO;oBAAED,IAAI,GAAEN,gBAAAA,IAAIQ,QAAQ,YAAZR,gBAAgB;gBAAY;aACxD;QACH;QACA,IAAIA,IAAIS,SAAS,EAAE;YACjBL,OAAO,CAAC,SAAS,GAAG;gBAAC;oBAAEH,MAAMD,IAAIS,SAAS;oBAAEH,MAAM;gBAAmB;aAAE;QACzE;QACA,oEAAoE;QACpE,IAAII,OAAOC,IAAI,CAACP,SAASQ,MAAM,GAAG,GAAGjB,QAAQkB,IAAI,CAACT;IACpD;IAEA,OAAO;QAAET;IAAQ;AACnB"}

package/src/lib/app-utils/agent-openapi.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * `/openapi.json` for a tenant site (AGL-2716) — the machine-readable
+ * description of what a site serves, per host.
+ *
+ * ## Why this is generated and not a checked-in file
+ *
+ * The document is a function of the SITE: its name, its origin, the content
+ * collections it publishes. A static file would describe one site, and every
+ * other host on the platform would publish a spec naming somebody else's
+ * domain in `servers[]` — which is worse than no spec, because a client that
+ * trusts it makes requests to the wrong origin.
+ *
+ * ## Read-only, deliberately
+ *
+ * Only GET operations are described. The tenant does serve writes — form
+ * submissions, membership, consent — and each is reachable, rate-limited and
+ * public, so listing them would be truthful. It would also be an invitation:
+ * a spec is a list of things to call, an agent that reads one calls them, and
+ * "submit this form" is not an operation a site owner asked to publish to
+ * every crawler on the internet. Writes stay discoverable the way they always
+ * were, from the page that carries the form.
+ *
+ * That decision belongs in the document, not just in this comment, so the
+ * `description` says so — a reader who needs a write endpoint is told where to
+ * look rather than left assuming none exists.
+ *
+ * ## Shaped for function calling
+ *
+ * Every operation carries a unique `operationId`, a `summary`, a `description`
+ * and typed parameters, and every response names a schema. That is exactly the
+ * subset an LLM tool-calling bridge reads when it turns a spec into callable
+ * functions — a missing `operationId` becomes a generated name nobody can
+ * predict, and a missing parameter type becomes a string the model guesses at.
+ *
+ * OpenAPI **3.1.0** rather than 3.0: 3.1 aligns its schema dialect with JSON
+ * Schema 2020-12, which is the dialect the function-calling formats already
+ * speak, so a bridge converts without a lossy pass.
+ */
+/** A content collection the site publishes, as the feed operation names it. */
+export interface AgentOpenApiCollection {
+    slug: string;
+    name?: string;
+}
+export interface AgentOpenApiOptions {
+    /** The site's name, for `info.title`. */
+    siteName: string;
+    /** Absolute origin, no trailing slash — the single `servers[]` entry. */
+    origin: string;
+    /** The site's own description, for `info.description`. */
+    description?: string;
+    /** Published content collections, for the feed operation's enum. */
+    collections?: readonly AgentOpenApiCollection[];
+    /** Whether the site serves `/search`. */
+    hasSearch?: boolean;
+    /** Platform version, so a consumer can tell two documents apart. */
+    version?: string;
+    /** Contact email published in `info.contact`, when the site has one. */
+    contactEmail?: string;
+    /** Absolute URL of the site's terms, when it publishes any. */
+    termsOfServiceUrl?: string;
+}
+/** A JSON-Schema-shaped object; loose on purpose — this is a document, not a type. */
+type Schema = Record<string, unknown>;
+/**
+ * The header that carries the API version, in both directions (AGL-2722).
+ *
+ * A header and not a URL segment, because most of this surface sits at a
+ * location some other specification fixed — `/openapi.json`, `/robots.txt`,
+ * `/llms.txt`, `/sitemap.xml`, `/manifest.webmanifest`. `/v1/robots.txt` is
+ * not a robots.txt: the crawler that needs it looks at the root and nowhere
+ * else. Versioning only the `/api/*` half would leave one surface running two
+ * rules, which is worse than either rule alone.
+ */
+export declare const API_VERSION_HEADER = "Aglyn-API-Version";
+/**
+ * The version this description and these responses are.
+ *
+ * ⚠️ Independent of the platform's release version, and deliberately so. The
+ * platform ships several times a day; this shape is a promise to strangers and
+ * moves only when the promise does. Bump it when a field is removed or
+ * renamed, or when an operation narrows what it accepts — never for an
+ * addition, which is why a consumer is told to parse leniently.
+ */
+export declare const API_VERSION = "1.0.0";
+/** Build the OpenAPI 3.1 document for one site. */
+export declare function buildAgentOpenApi(options: AgentOpenApiOptions): Schema;
+export {};