@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/plugins/asyncapi/03a-workflows.md

@@ -0,0 +1,153 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Workflows  
+title: Workflows
+description: Workflows of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+There are a few ways to configure the AsyncAPI plugin depending on your preferred development workflows.
+Many companies have different needs, so we have provided a few different workflows to choose from.
+
+- [Simple mapping between AsyncAPI files and EventCatalog services](#simple-mapping-between-asyncapi-files-and-eventcatalog-services)
+  - Map a single AsyncAPI file to a single EventCatalog service
+- [Independent message versions from your AsyncAPI file](#independent-message-versions-from-your-asyncapi-file)
+  - Version your messages independently of the service version
+- [Mapping multiple AsyncAPI files to a single EventCatalog service](#mapping-multiple-asyncapi-files-to-a-single-eventcatalog-service)
+  - Map multiple AsyncAPI files to a single EventCatalog service
+- [Mapping AsyncAPI and OpenAPI files to the same EventCatalog service](#mapping-asyncapi-and-openapi-files-to-the-same-eventcatalog-service)
+  - Map an AsyncAPI and OpenAPI file to the same EventCatalog service
+
+_If we are missing a workflow that you think is useful, please raise an [issue on GitHub](https://github.com/event-catalog/generators/issues)._  
+
+## Simple mapping between AsyncAPI files and EventCatalog services
+
+This is the simplest workflow and is useful if you have a single AsyncAPI file per service.
+
+EventCatalog will parse your AsyncAPI file and map it's specification to the service you define. 
+
+This will document your service, and the messages it produces and consumes.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Tell EventCatalog where the AsyncAPI file is located and map it to the service you define
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service' },
+      ],
+    },
+  ],
+],
+```
+
+### Independent message versions from your AsyncAPI file
+
+This is useful if you want to version your messages separately from the AsyncAPI file.
+
+AsyncAPI currently does not support versioning messages separately from the AsyncAPI file, that's why you have to use the `x-eventcatalog-message-version` extension.
+
+You can use the `x-eventcatalog-message-version` extension to specify a different version for a particular message.
+
+```yaml
+asyncapi: 3.0.0
+info:
+  title: Orders Service
+  version: 1.0.0
+components:
+  messages:
+    OrderCreated:
+      description: 'Event triggered when an order is created'
+      # Specify the version of the message to 2.0.0
+      x-eventcatalog-message-version: 2.0.0
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: The ID of the order
+```
+
+In the example above, the message `OrderCreated` will be versioned as `2.0.0` and all other messages will be versioned as `1.0.0`.
+
+You can read more about message versioning in the [Features](/docs/plugins/asyncapi/features#defining-message-versions) section.
+
+## Mapping multiple AsyncAPI files to a single EventCatalog service
+
+This is useful if you have a single service that produces and consumes multiple AsyncAPI versions.
+
+Some people call this a "polyglot" service, as it produces and consumes multiple APIs.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Version 1 of the AsyncAPI file
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service-v1.yml'), id: 'orders-service' },
+        // Version 2 of the AsyncAPI File
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service-v2.yml'), id: 'orders-service' },
+      ],
+    },
+  ],
+],
+```
+
+:::info Versioning
+When you map multiple versions of an AsyncAPI file to a single service, the `version` property in your AsyncAPI files needs to be the same.
+
+If they are different, EventCatalog will version the previous versions of your service.
+
+In the example above, the `version` property in the AsyncAPI files is `1.0.0` and `2.0.0`.
+
+EventCatalog will version the service as `1.0.0` and `2.0.0`.
+
+The messages in the service will be versioned as `1.0.0` and `2.0.0`.
+
+This allows you to track the history of your service and the messages in it.
+
+:::
+
+## Mapping AsyncAPI and OpenAPI files to the same EventCatalog service
+
+<AddedIn version="5.1.1" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+<AddedIn version="7.6.1" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+This is useful if you have a single service that produces and consumes both AsyncAPI and OpenAPI files.
+
+In this example we map an OpenAPI file and an AsyncAPI file to the same service (inventory-service). 
+
+The AsyncAPI and OpenAPI may have their own versions independent of each other, but EventCatalog will document both of them in the same service.
+
+:::tip Message Versioning
+You can still use the `x-eventcatalog-message-version` extension to version your messages independently of the service version.
+:::
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+    [
+      "@eventcatalog/generator-openapi",
+      {
+        services: [
+          { path: path.join(__dirname, "specifications", "openapi.yml"), id: "inventory-service", version: "15.2.0" },
+        ],
+      },
+    ],
+    [
+      "@eventcatalog/generator-asyncapi",
+      {
+        services: [{ path: path.join(__dirname, "specifications", "asyncapi.yml"), id: "inventory-service", version: "15.2.0" }],
+      },
+    ],
+  ],
+```

package/dist/docs/plugins/asyncapi/04-examples.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the AsyncAPI plugin
+---
+
+You can find many examples of using the AsyncAPI plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [AsyncAPI Example](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/basic)
+  -  A basic example of using the AsyncAPI plugin to generate a catalog from an AsyncAPI file.
+- [Fetch AsyncAPI files from remote URLs](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/fetch-from-remote-urls) 
+  - An example of using the AsyncAPI plugin to fetch an AsyncAPI file from a remote URL.
+- [Version AsyncAPI messages in EventCatalog](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/independent-message-versioning) 
+  - An example of using the AsyncAPI plugin to version AsyncAPI messages in EventCatalog.
+- [Map AsyncAPI routes to commands, events and queries](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/mapping-commands-events-queries) 
+  - An example of using the AsyncAPI plugin to map AsyncAPI routes to commands, events and queries.
+- [Assign ownership to teams](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/message-ownership)
+  - An example of using the AsyncAPI plugin to assign ownership to teams.

package/dist/docs/plugins/asyncapi/04-using-reference-objects.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 4
+keywords:
+- components
+sidebar_label: Using reference objects
+title: Using reference objects
+description: Understanding reference objects with AsyncAPI
+---
+
+AsyncAPI supports reusable parts in your AsyncAPI files using [References Objects](https://www.asyncapi.com/docs/concepts/asyncapi-document/reusable-parts).
+
+EventCatalog also supports reference with EventCatalog. For example you can keep your message schemas outside of your AsyncAPI file, as seen in this example.
+
+```yaml title="/asyncapi.yml"
+channels:
+  signUp:
+    address: user/signedup
+    messages:
+      UserSignup:
+        $ref: './message-schema.yaml#/UserSignup'
+operations:
+  user/signedup.publish:
+    action: receive
+    channel:
+      $ref: '#/channels/signUp'
+    messages:
+      - $ref: '#/channels/signUp/messages/UserSignup'
+```
+
+```yaml title="/message-schema.yaml"
+UserSignup:
+  name: UserSignup
+  title: User signup
+  summary: Action to sign a user up.
+  description: A longer description
+  contentType: application/json
+  payload: null
+```
+
+You can see the example [EventCatalog AsyncAPI GitHub project for a demo](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi).
+
+---
+
+Note: When the AsyncAPI file is written against your EventCatalog service, all refs are removed. This allows EventCatalog to render the AsyncAPI UI without the need to store and track references. 
+

package/dist/docs/plugins/asyncapi/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "AsyncAPI Plugin",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "asyncapi",
+    "title": "AsyncAPI",
+    "description": "AsyncAPI integration documentation for EventCatalog"
+  }
+}

package/dist/docs/plugins/aws-glue-registry/00-intro.md

@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with AWS Glue Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="515" src="https://www.youtube.com/embed/cUQDdisz1wg?si=4Sj262A8N6iD8MTV" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+---
+
+[AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html) is a feature of [AWS Glue](https://aws.amazon.com/glue) that enables you to discover, register, and evolve schemas for your data streams. The Schema Registry helps you centrally store and manage schemas for your event-driven applications and streaming data platforms.
+
+AWS Glue Schema Registry provides schema evolution with full compatibility control, supporting Apache Avro, JSON Schema, and Protocol Buffers formats. It integrates seamlessly with AWS services like Amazon Kinesis, Amazon MSK, and the Apache Kafka ecosystem.
+
+Using [schema versioning and compatibility features](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-concepts.html), as schemas evolve in your applications, they are versioned and stored in the registry. These schemas can be used to help you and your teams understand and discover events in your event-driven architecture, ensuring data quality and contract compliance.
+
+Although Glue Schema Registry offers powerful schema management solutions, [there is still an issue of discoverability and documentation for your events, services and domains](https://www.youtube.com/watch?v=VLUvfIm9wnQ&t=4s). It remains difficult to organize your event-driven architecture for governance and team collaboration.
+
+### Why use EventCatalog with AWS Glue Schema Registry?
+
+Using the EventCatalog AWS Glue Schema Registry integration you can sync your schemas with EventCatalog.
+
+You can map and sync schemas to your services and domains, and then use the EventCatalog to document your architecture.
+Giving your teams a single source of truth for your event-driven architecture.
+
+### Core Features
+
+The EventCatalog AWS Glue plugin can provide you with many features:
+
+- Import schemas directly from AWS Glue Schema Registry and keep them in sync with your documentation
+- Assign schemas to producers and consumers
+- Use filters to assign your schemas to your producer and consumers (e.g tag matching, prefix, suffix, etc)
+- Generate domains, services, channels and messages into your catalog
+- Add more meaning to your schemas with custom markdown. Persisted between changes to your schemas.
+- Visualize your schemas and let your teams download and explore them in your catalog.
+- Use EventCatalog MCP and AI features to talk to your schemas, and find insights in seconds.
+- and more....
+
+### How it works
+
+![How it works](/img/integrations/aws-glue/glue.png)
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog AWS Glue Schema Registry plugin lets you document, sync and map your schemas into EventCatalog.
+
+You can use [custom filters (schemaName, prefix, suffix, includes, tags, dataFormat)](/docs/plugins/aws-glue-registry/features) to map which schemas you want your service to produce and consume. This is useful if you have a lot of schemas and you want to map only a subset of them to your services.
+
+You can also use the EventCatalog plugin to map ALL schemas from your registry into your system and not map them into services if you wish to have a direct import.
+
+### Supported Schema Formats
+
+EventCatalog is technology agnostic, and supports all schema formats.
+
+The plugin supports all AWS Glue Schema Registry formats:
+
+- **Apache Avro** - For efficient serialization in streaming applications
+- **JSON Schema** - For JSON data validation and documentation  
+- **Protocol Buffers** - For language-neutral, platform-neutral serialization
+
+
+### See an example
+
+If you would like to get started with our example project, [you can find it on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-glue-registry/basic).
+
+
+
+## Commercial and License
+
+This plugin requires a license key to be used. 
+
+You can get a 14 day trial license key to try the plugin out by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial you can purchase a license to continue using this plugin, we have different plans to suit your organization. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The license key is required to use the AWS Glue Schema Registry plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get a license key?
+You can obtain a license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 14-day free trial.
+
+### Terms
+- **Trial Period**: 14 days free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can purchase a full license through [EventCatalog Cloud](https://eventcatalog.cloud) to continue using the plugin.
+
+## Issues
+
+If you have any problems or feature requests please feel free to raise them on GitHub. https://github.com/event-catalog/generators

package/dist/docs/plugins/aws-glue-registry/00a-installation.md

@@ -0,0 +1,305 @@
+---
+sidebar_position: 2
+keywords:
+- installation
+sidebar_label: Installation
+title: Installation
+description: How to install the AWS Glue Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+## Installation
+
+Install the plugin into your EventCatalog application:
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+
+```bash
+npm install @eventcatalog/generator-aws-glue
+```
+
+## Configuration
+
+Add the generator to your `eventcatalog.config.js` file:
+
+<Tabs>
+  <TabItem value="apple" label="Import all schemas" default>
+
+  ---
+
+  In this example we import all schemas from an AWS Glue Schema Registry.
+
+  We don't map them to any services or domains.
+
+  ```js title="eventcatalog.config.js"
+  // ...
+generators: [
+    // Import all schemas into your catalog
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        // The region of your AWS Glue Schema Registry
+        region: 'us-east-1',
+        // The name of your AWS Glue Schema Registry
+        registryName: 'my-glue-registry'
+      },
+    ],
+],
+// ...
+```
+  </TabItem>
+  <TabItem value="orange" label="Map schemas to producers and consumers">
+
+  ---
+
+  In this example we map schemas to producers and consumers (services).
+
+  Every time you run the plugin, it will check if the service already exists in your catalog.
+
+  If the service already exists, it will not create a new one and just maintain the schema mappings.
+
+  We create two services, the `orders` service and the `inventory` service.
+  
+  
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      // The region of your EventBridge registry
+      region: 'us-east-1',
+      // The name of your AWS Glue Schema Registry
+      registryName: 'my-glue-registry',
+      // Creating producers and consumers, and mapping them to your catalog
+      services: [
+        
+        // We map schemas to the orders service
+        // Using the prefix and suffix we can map specific schemas to the service
+        { id: 'Orders Service', version: '1.0.0', sends: [{ prefix: 'Order' }, { suffix: 'Placed' }], receives:[{ prefix: 'Inventory' }, { suffix: 'Adjusted' }] },
+
+        // Map schemas to the Inventory Service
+        // Filter by prefix (all schemas that match the prefix get assigned). This example shows any schema matching the prefix
+        // "myapp.orders" will be assigned to the inventory service. The inventory service will publish these schemas.
+        { id: 'Inventory Service', version: '1.0.0', sends: [{ prefix: "myapp.orders"}], receives:[{ prefix: "UserCheckedOut"}] },
+
+
+        // This service sends schemas that match the SchemaName prefixing myapp, and will receive schemas that end with Payment
+        // this also does not map any schemas to your schemas
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+      ],
+
+      // all services are mapped to this domain
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+],
+// ...
+```
+  </TabItem>
+  <TabItem value="orange2" label="Multiple domains, services and events">
+
+  ---
+
+  In this example we have two domains, `orders` and `inventory`.
+
+  We map schemas to the orders and inventory services, and we assign these services to new domains.
+
+  If the domain or service already exists in your catalog, the plugin will not create a new one and just maintain the schema mappings.
+
+  :::info Why do we define the plugin twice?
+  The plugin can be defined multiple times in your `eventcatalog.config.js` file.
+
+  In this example we define the plugin twice, the first time we import the schemas and create the `orders` domain.
+
+  The second time we map the inventory service to the `inventory` domain.
+  :::
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      // The region of your AWS Glue Schema Registry
+      region: 'us-east-1',
+      // The name of your AWS Glue Schema Registry
+      registryName: 'my-glue-registry',
+      // Creating producers and consumers, and mapping them to your catalog
+      services: [
+        // We map schemas to the orders service
+        // Using the prefix and suffix we can map specific schemas to the service
+        { id: 'Orders Service', version: '1.0.0', sends: [{ prefix: 'Order' }, { suffix: 'Placed' }], receives:[{ prefix: 'Inventory' }, { suffix: 'Adjusted' }] },
+      ],
+
+      // all services are mapped to this domain
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-glue-registry',
+      services: [
+        // Create the inventory service and map schemas to it (producer/consumer relationship)
+        { id: 'Inventory Service', version: '1.0.0', sends: [{ prefix: "myapp.orders"}], receives:[{ prefix: "UserCheckedOut"}] },
+      ],
+
+      // create the inventory domain and assign the inventory service to it
+      domain: { id: 'inventory', name: 'Inventory', version: '0.0.1' },
+    },
+  ],
+],
+// ...
+```
+  </TabItem>
+</Tabs>
+
+### Configure license key
+
+The EventCatalog AWS Glue Schema Registry plugin requires a license key to work with EventCatalog.
+
+You can get a trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended)
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_AWS_GLUE_SCHEMA_REGISTRY=your-license-key
+```
+
+#### 2. Setting license key in eventcatalog.config.js
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog AWS Glue Schema Registry plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_AWS_GLUE_SCHEMA_REGISTRY
+      },
+    ],
+  ],
+};
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+## Required AWS Permissions
+
+The plugin requires the following AWS IAM permissions to access your Glue Schema Registry:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "glue:ListSchemas",
+        "glue:GetSchema",
+        "glue:GetSchemaVersion",
+        "glue:GetTags"
+      ],
+      "Resource": [
+        "arn:aws:glue:*:*:registry/*",
+        "arn:aws:glue:*:*:schema/*/*"
+      ]
+    }
+  ]
+}
+```
+
+## AWS Credential Configuration
+
+The plugin uses the AWS SDK for JavaScript and supports all standard AWS credential methods:
+
+### Environment Variables
+```bash
+export AWS_ACCESS_KEY_ID=your-access-key
+export AWS_SECRET_ACCESS_KEY=your-secret-key
+export AWS_REGION=us-east-1
+```
+
+### AWS CLI Profile
+```bash
+aws configure --profile eventcatalog
+export AWS_PROFILE=eventcatalog
+```
+
+### Custom Credentials
+You can also provide credentials directly in the configuration:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'my-event-registry',
+        credentials: {
+          accessKeyId: 'your-access-key',
+          secretAccessKey: 'your-secret-key',
+        },
+      },
+    ],
+  ],
+}
+```
+
+:::warning
+Never commit credentials to your repository. Use environment variables or AWS credential files instead.
+:::
+
+## Cross-Account Access
+
+To access registries in different AWS accounts, use the `registryArn` parameter:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryArn: 'arn:aws:glue:us-east-1:123456789012:registry/cross-account-registry',
+      },
+    ],
+  ],
+}
+```
+
+## Running the Generator
+
+Once configured, generate your catalog:
+
+```bash
+npm run generate
+```
+
+This will connect to your AWS Glue Schema Registry and generate EventCatalog documentation for all your schemas.