@eventcatalog/core 3.41.4 → 3.42.0

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "3.41.4";
+var version = "3.42.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-VQLDZRHC.js";
-import "../chunk-OH2U6UEJ.js";
+} from "../chunk-6FAGUEM4.js";
+import "../chunk-VPZ77Y6E.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -110,7 +110,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "3.41.4";
+var version = "3.42.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-LYRAK5LI.js";
-import "../chunk-VQLDZRHC.js";
+} from "../chunk-L66TCSM7.js";
+import "../chunk-6FAGUEM4.js";
 import "../chunk-3DVHEVHQ.js";
-import "../chunk-OH2U6UEJ.js";
+import "../chunk-VPZ77Y6E.js";
 import "../chunk-5T63CXKU.js";
 export {
   log_build_default as default

package/dist/{chunk-VQLDZRHC.js → chunk-6FAGUEM4.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-OH2U6UEJ.js";
+} from "./chunk-VPZ77Y6E.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-YWG7CCN7.js → chunk-KE6YTTLB.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-COPXPOV2.js";
+} from "./chunk-UQIDXF2V.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-LYRAK5LI.js → chunk-L66TCSM7.js}

@@ -1,6 +1,6 @@
 import {
   raiseEvent
-} from "./chunk-VQLDZRHC.js";
+} from "./chunk-6FAGUEM4.js";
 import {
   countResources,
   serializeCounts

package/dist/{chunk-COPXPOV2.js → chunk-UQIDXF2V.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-OH2U6UEJ.js";
+} from "./chunk-VPZ77Y6E.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-OH2U6UEJ.js → chunk-VPZ77Y6E.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "3.41.4";
+var version = "3.42.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "3.41.4";
+var version = "3.42.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-OH2U6UEJ.js";
+} from "./chunk-VPZ77Y6E.js";
 export {
   VERSION
 };

package/dist/docs/development/developer-tools/api-catalog.md

@@ -0,0 +1,114 @@
+---
+sidebar_position: 5
+keywords:
+- api-catalog
+- RFC 9727
+- well-known
+- API discovery
+- OpenAPI
+- AsyncAPI
+- GraphQL
+sidebar_label: api-catalog (RFC 9727)
+title: api-catalog
+description: Machine-readable catalog discovery endpoint for tools and agents
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.42.0" />
+
+Let API tools, agents, and crawlers discover every service and domain specification in your catalog from a single endpoint, without parsing HTML.
+
+### What is RFC 9727?
+
+[RFC 9727](https://datatracker.ietf.org/doc/rfc9727/) defines the `/.well-known/api-catalog` well-known URI. It returns a [Linkset](https://www.rfc-editor.org/rfc/rfc9264) document that lists every API an organization publishes along with links to their specifications and documentation.
+
+Tools that understand RFC 9727 can point at your catalog URL and immediately enumerate all services and domains, their OpenAPI, AsyncAPI, and GraphQL specs, and their documentation pages. No scraping required.
+
+### How it works
+
+EventCatalog automatically publishes a Linkset at `/.well-known/api-catalog`. Every service and domain that has `specifications` defined in its frontmatter appears as an entry.
+
+Each entry contains:
+
+- **`anchor`** - the canonical URL of the service. EventCatalog reads the `servers[].url` field from OpenAPI or AsyncAPI specs and uses that. When no server URL is found it falls back to the EventCatalog documentation page.
+- **`service-desc`** - one link per specification file, pointing at `/api-catalog/specifications/{collection}/{id}/{version}/{specification}` with the correct media type (`application/yaml`, `application/json`, or `application/graphql`).
+- **`service-doc`** - two links per resource: the markdown source and the rendered HTML page.
+
+Resources marked `hidden: true` are excluded from the linkset.
+
+### Access the endpoint
+
+```
+GET  /.well-known/api-catalog
+HEAD /.well-known/api-catalog
+```
+
+The `GET` response body is `application/linkset+json` profiled against RFC 9727:
+
+```json
+{
+  "linkset": [
+    {
+      "anchor": "https://api.example.com/orders",
+      "service-desc": [
+        {
+          "href": "https://catalog.example.com/api-catalog/specifications/services/OrderService/1.0.0/openapi-b3BlbmFwaS55bWw",
+          "type": "application/yaml",
+          "title": "Order Service OpenAPI"
+        }
+      ],
+      "service-doc": [
+        {
+          "href": "https://catalog.example.com/docs/services/OrderService/1.0.0.md",
+          "type": "text/markdown",
+          "title": "Order Service documentation"
+        },
+        {
+          "href": "https://catalog.example.com/docs/services/OrderService/1.0.0",
+          "type": "text/html",
+          "title": "Order Service documentation"
+        }
+      ]
+    }
+  ]
+}
+```
+
+The `HEAD` response includes a `Link` header so clients can confirm the endpoint exists before fetching the full body:
+
+```
+Link: <https://catalog.example.com/.well-known/api-catalog>; rel="api-catalog"
+```
+
+### Fetch a specification file
+
+The raw specification files referenced in `service-desc` are served from:
+
+```
+GET /api-catalog/specifications/{collection}/{id}/{version}/{specification}
+```
+
+| Segment | Values |
+|---------|--------|
+| `collection` | `services`, `domains` |
+| `id` | The resource `id` field |
+| `version` | The resource `version` field |
+| `specification` | Stable specification identifier, formatted as `{type}-{base64url(path)}` |
+
+Example:
+
+```
+GET /api-catalog/specifications/services/OrderService/1.0.0/openapi-b3BlbmFwaS55bWw
+Content-Type: application/yaml
+```
+
+### MCP server entry
+
+When the EventCatalog MCP server is enabled, an additional entry pointing at `/docs/mcp` is appended to the linkset. This lets MCP-aware agents discover the catalog's machine interface alongside its API specifications.
+
+### What is included
+
+Only services and domains are included in v1 of this endpoint. Events, commands, queries, data products, schemas, diagrams, teams, and users are out of scope for this release.
+
+For a broader machine-readable index of your catalog content, see [llms.txt](/docs/development/developer-tools/llms.txt) and [schemas.txt](/docs/development/developer-tools/schemas.txt).

package/dist/eventcatalog.cjs

@@ -114,7 +114,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.41.4";
+var version = "3.42.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.js

@@ -13,8 +13,8 @@ import {
 } from "./chunk-3H2RT3CM.js";
 import {
   log_build_default
-} from "./chunk-LYRAK5LI.js";
-import "./chunk-VQLDZRHC.js";
+} from "./chunk-L66TCSM7.js";
+import "./chunk-6FAGUEM4.js";
 import "./chunk-3DVHEVHQ.js";
 import {
   catalogToAstro
@@ -28,13 +28,13 @@ import {
 } from "./chunk-ULZYHF3V.js";
 import {
   generate
-} from "./chunk-YWG7CCN7.js";
+} from "./chunk-KE6YTTLB.js";
 import {
   logger
-} from "./chunk-COPXPOV2.js";
+} from "./chunk-UQIDXF2V.js";
 import {
   VERSION
-} from "./chunk-OH2U6UEJ.js";
+} from "./chunk-VPZ77Y6E.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/generate.cjs

@@ -78,7 +78,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.41.4";
+var version = "3.42.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-YWG7CCN7.js";
-import "./chunk-COPXPOV2.js";
-import "./chunk-OH2U6UEJ.js";
+} from "./chunk-KE6YTTLB.js";
+import "./chunk-UQIDXF2V.js";
+import "./chunk-VPZ77Y6E.js";
 import "./chunk-5T63CXKU.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.41.4";
+var version = "3.42.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-COPXPOV2.js";
-import "../chunk-OH2U6UEJ.js";
+} from "../chunk-UQIDXF2V.js";
+import "../chunk-VPZ77Y6E.js";
 export {
   logger
 };

package/eventcatalog/src/pages/.well-known/api-catalog.ts

@@ -0,0 +1,191 @@
+import type { APIRoute } from 'astro';
+import yaml from 'js-yaml';
+import { getServices, getSpecificationsForService } from '@utils/collections/services';
+import { getDomains, getSpecificationsForDomain } from '@utils/collections/domains';
+import type { ProcessedSpecification } from '@utils/collections/util';
+import { buildUrl } from '@utils/url-builder';
+import { readResourceFile } from '@utils/resource-files';
+import { isEventCatalogMCPEnabled } from '@utils/feature';
+
+const RFC_9727_PROFILE = 'https://www.rfc-editor.org/info/rfc9727';
+const LINKSET_CONTENT_TYPE = `application/linkset+json; profile="${RFC_9727_PROFILE}"`;
+
+type LinkTarget = {
+  href: string;
+  type?: string;
+  title?: string;
+};
+
+type ApiCatalogEntry = {
+  anchor: string;
+  'service-desc': LinkTarget[];
+  'service-doc'?: LinkTarget[];
+};
+
+type ApiCatalogResource = Awaited<ReturnType<typeof getServices>>[number] | Awaited<ReturnType<typeof getDomains>>[number];
+
+const absoluteUrl = (request: Request, pathOrUrl: string) => new URL(pathOrUrl, request.url).toString();
+
+const getSpecificationMediaType = (specification: ProcessedSpecification) => {
+  const extension = specification.filename.split('.').pop()?.toLowerCase();
+
+  if (specification.type === 'graphql') return 'application/graphql';
+  if (extension === 'json') return 'application/json';
+  if (extension === 'yaml' || extension === 'yml') return 'application/yaml';
+
+  return 'text/plain';
+};
+
+const getSpecificationIdentifier = (specification: ProcessedSpecification) => {
+  return `${specification.type}-${Buffer.from(specification.path).toString('base64url')}`;
+};
+
+const parseSpecification = (rawSpecification: string, path: string): unknown => {
+  if (path.endsWith('.json')) {
+    return JSON.parse(rawSpecification);
+  }
+
+  return yaml.load(rawSpecification);
+};
+
+const toHttpUrl = (value: unknown): string | undefined => {
+  if (typeof value !== 'string' || value.trim() === '') return undefined;
+  if (!/^https?:\/\//i.test(value)) return undefined;
+
+  try {
+    const url = new URL(value);
+    if (url.protocol === 'http:' || url.protocol === 'https:') {
+      return url.toString();
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+};
+
+const getSpecificationsForResource = (resource: ApiCatalogResource) => {
+  if (resource.collection === 'domains') {
+    return getSpecificationsForDomain(resource);
+  }
+
+  return getSpecificationsForService(resource);
+};
+
+const getEndpointFromSpecification = (request: Request, resource: ApiCatalogResource) => {
+  const specifications = getSpecificationsForResource(resource);
+
+  for (const specification of specifications) {
+    if (specification.type !== 'openapi' && specification.type !== 'asyncapi') continue;
+
+    const rawSpecification = readResourceFile(resource, specification.path);
+    if (!rawSpecification) continue;
+
+    try {
+      const parsedSpecification = parseSpecification(rawSpecification, specification.path) as any;
+
+      if (specification.type === 'openapi') {
+        const serverUrl = parsedSpecification?.servers?.find((server: any) => typeof server?.url === 'string')?.url;
+        const endpoint = toHttpUrl(serverUrl);
+        if (endpoint) return endpoint;
+      }
+
+      if (specification.type === 'asyncapi') {
+        const servers = Object.values(parsedSpecification?.servers ?? {}) as any[];
+        const serverUrl = servers.find((server) => typeof server?.url === 'string')?.url;
+        const endpoint = toHttpUrl(serverUrl);
+        if (endpoint) return endpoint;
+      }
+    } catch {
+      // Invalid or unsupported specifications should not prevent catalog discovery.
+    }
+  }
+};
+
+const getResourceDocumentationUrl = (request: Request, resource: ApiCatalogResource) => {
+  return absoluteUrl(request, buildUrl(`/docs/${resource.collection}/${resource.data.id}/${resource.data.version}`, true));
+};
+
+const getResourceMarkdownUrl = (request: Request, resource: ApiCatalogResource) => {
+  return absoluteUrl(request, buildUrl(`/docs/${resource.collection}/${resource.data.id}/${resource.data.version}.md`, true));
+};
+
+const toApiCatalogEntry = (request: Request, resource: ApiCatalogResource): ApiCatalogEntry | null => {
+  const specifications = getSpecificationsForResource(resource);
+  if (specifications.length === 0) return null;
+
+  const resourceDocumentationUrl = getResourceDocumentationUrl(request, resource);
+  const resourceMarkdownUrl = getResourceMarkdownUrl(request, resource);
+
+  return {
+    anchor: getEndpointFromSpecification(request, resource) ?? resourceDocumentationUrl,
+    'service-desc': specifications.map((specification) => ({
+      href: absoluteUrl(
+        request,
+        buildUrl(
+          `/api-catalog/specifications/${resource.collection}/${resource.data.id}/${resource.data.version}/${getSpecificationIdentifier(specification)}`,
+          true
+        )
+      ),
+      type: getSpecificationMediaType(specification),
+      title: `${resource.data.name || resource.data.id} ${specification.name}`,
+    })),
+    'service-doc': [
+      {
+        href: resourceMarkdownUrl,
+        type: 'text/markdown',
+        title: `${resource.data.name || resource.data.id} documentation`,
+      },
+      {
+        href: resourceDocumentationUrl,
+        type: 'text/html',
+        title: `${resource.data.name || resource.data.id} documentation`,
+      },
+    ],
+  };
+};
+
+const getMcpCatalogEntry = (request: Request): ApiCatalogEntry | null => {
+  if (!isEventCatalogMCPEnabled()) return null;
+
+  const mcpUrl = absoluteUrl(request, buildUrl('/docs/mcp', true));
+
+  return {
+    anchor: mcpUrl,
+    'service-desc': [
+      {
+        href: mcpUrl,
+        type: 'application/json',
+        title: 'EventCatalog MCP Server',
+      },
+    ],
+  };
+};
+
+export const GET: APIRoute = async ({ request }) => {
+  const [services, domains] = await Promise.all([getServices({ getAllVersions: true }), getDomains({ getAllVersions: true })]);
+  const resources = [...services, ...domains];
+  const linkset = resources
+    .map((resource) => toApiCatalogEntry(request, resource))
+    .filter((entry): entry is ApiCatalogEntry => entry !== null);
+
+  const mcpEntry = getMcpCatalogEntry(request);
+  if (mcpEntry) {
+    linkset.push(mcpEntry);
+  }
+
+  return new Response(JSON.stringify({ linkset }, null, 2), {
+    headers: {
+      'Content-Type': LINKSET_CONTENT_TYPE,
+    },
+  });
+};
+
+export const HEAD: APIRoute = async ({ request }) => {
+  return new Response(null, {
+    headers: {
+      'Content-Type': LINKSET_CONTENT_TYPE,
+      Link: `<${absoluteUrl(request, buildUrl('/.well-known/api-catalog', true))}>; rel="api-catalog"`,
+    },
+  });
+};

package/eventcatalog/src/pages/api-catalog/specifications/[collection]/[id]/[version]/[specification].ts

@@ -0,0 +1,109 @@
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { getSpecificationsForDomain } from '@utils/collections/domains';
+import { getSpecificationsForService } from '@utils/collections/services';
+import type { ProcessedSpecification } from '@utils/collections/util';
+import { readResourceFile } from '@utils/resource-files';
+
+type SupportedCollection = 'domains' | 'services';
+
+const isSupportedCollection = (collection: string | undefined): collection is SupportedCollection => {
+  return collection === 'domains' || collection === 'services';
+};
+
+const getSpecificationMediaType = (specification: ProcessedSpecification) => {
+  const extension = specification.filename.split('.').pop()?.toLowerCase();
+
+  if (specification.type === 'graphql') return 'application/graphql';
+  if (extension === 'json') return 'application/json';
+  if (extension === 'yaml' || extension === 'yml') return 'application/yaml';
+
+  return 'text/plain';
+};
+
+const getSpecificationIdentifier = (specification: ProcessedSpecification) => {
+  return `${specification.type}-${Buffer.from(specification.path).toString('base64url')}`;
+};
+
+const getSpecificationsForResource = (
+  resource:
+    | Awaited<ReturnType<typeof getCollection<'services'>>>[number]
+    | Awaited<ReturnType<typeof getCollection<'domains'>>>[number]
+) => {
+  if (resource.collection === 'domains') {
+    return getSpecificationsForDomain(resource);
+  }
+
+  return getSpecificationsForService(resource);
+};
+
+export async function getStaticPaths() {
+  const [services, domains] = await Promise.all([getCollection('services'), getCollection('domains')]);
+  const resources = [...services, ...domains].filter((resource) => resource.data.hidden !== true);
+
+  return resources.flatMap((resource) =>
+    getSpecificationsForResource(resource).map((specification) => ({
+      params: {
+        collection: resource.collection,
+        id: resource.data.id,
+        version: resource.data.version,
+        specification: getSpecificationIdentifier(specification),
+      },
+      props: {
+        rawSpecification: readResourceFile(resource, specification.path),
+        contentType: getSpecificationMediaType(specification),
+      },
+    }))
+  );
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  if (props.rawSpecification) {
+    return new Response(props.rawSpecification, {
+      headers: { 'Content-Type': props.contentType ?? 'text/plain' },
+    });
+  }
+
+  const { collection, id, version, specification } = params;
+
+  if (!isSupportedCollection(collection) || !id || !version || !specification) {
+    return new Response(JSON.stringify({ error: 'Missing or invalid collection, id, version, or specification parameter' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const resources = await getCollection(collection);
+  const resource = resources.find((item) => item.data.id === id && item.data.version === version && item.data.hidden !== true);
+
+  if (!resource) {
+    return new Response(JSON.stringify({ error: 'Resource not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const spec = getSpecificationsForResource(resource).find(
+    (item) => getSpecificationIdentifier(item) === specification || item.type === specification
+  );
+
+  if (!spec) {
+    return new Response(JSON.stringify({ error: 'Specification not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const rawSpecification = readResourceFile(resource, spec.path);
+
+  if (!rawSpecification) {
+    return new Response(JSON.stringify({ error: 'Specification file could not be read' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  return new Response(rawSpecification, {
+    headers: { 'Content-Type': getSpecificationMediaType(spec) },
+  });
+};

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "3.41.4",
+  "version": "3.42.0",
   "publishConfig": {
     "access": "public"
   },
@@ -113,8 +113,8 @@
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
     "@eventcatalog/sdk": "2.23.0",
-    "@eventcatalog/visualiser": "^3.22.1",
-    "@eventcatalog/linter": "1.0.26"
+    "@eventcatalog/linter": "1.0.26",
+    "@eventcatalog/visualiser": "^3.22.1"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",