@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/plugins/confluent-schema-registry/02-plugin-configuration.md

@@ -0,0 +1,473 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Confluent Schema Registry plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog Confluent Schema Registry plugin
+---
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog Confluent Schema Registry plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+:::info API Keys
+If you are using Confluent Cloud, you need to export your API keys as environment variables in the `.env` file.
+
+<details>
+<summary>Example .env file</summary>
+
+```bash
+export CONFLUENT_SCHEMA_REGISTRY_KEY=your-confluent-schema-registry-key
+export CONFLUENT_SCHEMA_REGISTRY_SECRET=your-confluent-schema-registry-key-secret
+```
+
+</details>
+
+:::
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `schemaRegistryUrl` | `string` | Yes | The URL of your Confluent Schema Registry. You can find this in the Confluent Cloud dashboard. If you are running locally you can use the `http://localhost:8081` endpoint. |
+| `includeAllVersions` | `boolean` | No | If true, all versions of the schemas will be imported into EventCatalog (default is `false`). |
+
+
+
+## Optional Configuration Options
+
+### Services
+
+You can assign the schemas to a producer or consumer (service).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `services` | object | - | List of producers/consumers (services) to assign the schemas to. |
+| `services.id` | string | - | EventCatalog ID for the service. |
+| `services.sends` | Filter | - | Configuration to assign schemas to a producer. The schemas and topic defined here will be assigned to the producer. |
+| `services.receives` | Filter | - | Configuration to assign schemas to a consumer. The schemas and topic defined here will be assigned to the consumer. |
+| `services.writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service writes to. (Added in v0.2.1) |
+| `services.readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service reads from. (Added in v0.2.1) |
+
+### Topics
+
+You can document the topics for your schemas. These are channels in EventCatalog.
+Schemas are mapped to their topics.
+
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topics` | object | - | Optional list of topics to assign the schemas to. (optional). [These are documented as channels](/docs/development/guides/channels/introduction) in EventCatalog. |
+| `topics.id` | string | - | EventCatalog ID for the topic (e.g `orders-topic`). |
+| `topics.name` | string | - | Name of the topic (e.g `Orders Topic`). |
+| `topics.address` | string | - | Address of the topic (e.g `kafka-cluster-1.us-east-1.confluent.cloud:9092`). |
+
+### Domains
+
+You can define and assign domains to your services.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain.id` | string | - | EventCatalog ID for the domain (e.g `orders-domain`). |
+| `domain.name` | string | - | Name of the domain (e.g `Orders Domain`). |
+| `domain.version` | string | - | Version of the domain (e.g `1.0.0`). |
+
+### Filtering schemas to producers and consumers
+
+When you assign schemas to a producer or consumer (service), you can use a range of filtering options including:(suffixes, prefixes, includes or exact matches).
+
+Here are some examples of how to filter schemas to producers and consumers.
+
+<details>
+<summary>`exact` matching example - Match schemas that exactly match the specified name</summary>
+
+**What is exact matching?**
+
+Exact matching is when the schema name exactly matches the specified name.
+
+In this example, the `Orders Service` will send `events` with the schema name `order-placed`, `order-cancelled` and receive `commands` with the schema name `place-order`.
+
+Example schemas (subjects) in Confluent Schema Registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `place-order-value`
+- `cancel-order-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the schema name `order-placed` or `order-cancelled`
+            sends: [{ events: ['order-placed', 'order-cancelled']},
+            // The Order services receives commands that match the schema name `place-order` or `cancel-order`
+            receives: [{ commands: ['place-order', 'cancel-order']},
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+
+<details>
+<summary>`suffix` matching example - Match schemas that end with a specific string</summary>
+
+**What is suffix matching?**
+
+Suffix matching is when the schema name ends with the specified suffix.
+
+In this example, the `Orders Service` will send `events` with a suffix of `placed` and receive `commands` with a suffix of `command`.
+
+Example schemas in registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `place-order-command-value`
+- `cancel-order-command-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events (schemas) with a suffix of `placed`
+            sends: [{ events: { suffix: '-placed' }},
+            // The Order services receives commands (schemas) with a suffix of `command`
+            receives: [{ commands: { suffix: '-command' }},
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+<details>
+<summary>`prefix` matching example - Match schemas that start with a specific string</summary>
+
+In this example, the `Orders Service` will send `events` with a prefix of `order` and receive `commands` with a prefix of `analytics`
+
+Example schemas in registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `analytics-place-order-value`
+- `analytics-cancel-order-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events with a prefix of `order`
+            sends: [{ events: { prefix: 'order' }}],
+            // The Order services receives commands with a prefix of `analytics`
+            receives: [{ commands: { prefix: 'analytics' }}],
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+<details>
+<summary>`includes` matching example - Match schemas that include a specific string</summary>
+
+In this example, the `Orders Service` will send `events` that include the string `order` and receives `commands` that include the string `analytics`
+
+Example schemas in registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `analytics-place-order-value`
+- `analytics-cancel-order-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events with a prefix of `order`
+            sends: [{ events: { includes: 'order' }}],
+            // The Order services receives commands with a prefix of `analytics`
+            receives: [{ commands: { includes: 'analytics' }}],
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+
+## Example Configurations
+
+The Confluent Schema Registry plugin is flexible to work with your use case.
+Here are a few examples of how you can configure the plugin.
+
+
+<details>
+<summary>Example configuration - Import all schemas (and versions) into EventCatalog</summary>
+
+In this example we import all schemas from the Confluent Schema Registry into EventCatalog.
+No topics, services or domains are configured or created. This is a simple way to import schemas into the catalog and keep them in sync with your documentation.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+
+        // Include all versions of the schemas
+        includeAllVersions: true,
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog).
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the schema name `order-placed` or `order-cancelled`
+            sends: [{ events: ['order-placed', 'order-cancelled']}],
+            // The Order services receives commands that match the schema name `place-order` or `cancel-order`
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers (with filters)</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog) but we use filters to match the schemas.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that start with `order`
+            sends: [{ events: { prefix: 'order' }}],
+            // The Order services receives commands that end with `command`
+            receives: [{ commands: { suffix: 'command' }}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers with topics</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog) but we also assign them to *topics*.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // List of kafka topics to assign the schemas to (optional)
+        // These will be documented as channels in EventCatalog
+        topics: [
+          {
+            id: 'orders-topic',
+            name: 'Orders Topic',
+            address: 'kafka-cluster-1.us-east-1.confluent.cloud:9092',
+          }
+        ],
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that start with `order` using the `orders-topic` (channel)
+            sends: [{ events: { prefix: 'order' }, topic: 'orders-topic'}],
+            // The Order services receives commands that end with `command` using the `orders-topic` (channel)
+            receives: [{ commands: { suffix: 'command' }, topic: 'orders-topic'}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers within a domain</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog) but we also assign them to a *domain*.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the schema name `order-placed` or `order-cancelled`
+            sends: [{ events: ['order-placed', 'order-cancelled']}],
+            // The Order services receives commands that match the schema name `place-order` or `cancel-order`
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ],
+        // The domain to assign the service (orders-service) to
+        // if it does not exist, it will be created
+        domain: {
+          id: 'orders-domain',
+          name: 'Orders Domain',
+          version: '1.0.0',
+        }
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+## Need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord)
+or refer to the [Confluent Schema Registry examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry).
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/docs/plugins/confluent-schema-registry/03-features.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Adding semantic meaning to schemas
+
+Using the Confluent Schema Registry plugin, you can import and map your schemas to topics, services, domains and owners.
+
+When you import a schema into EventCatalog your (event or command) will be created. The schema (JSON, Avro or Protobuf) will be stored against the message in EventCatalog. 
+
+Each message (command or event) has their own `index.mdx` file. This is the place to store semantic meaning for the message. You can add a title, summary, description, and more (custom components, markdown, etc).
+
+This gives you the opportunity to add meaning to your messages and make them easier to understand for teams.
+
+When you reimport your schemas, your schemas will download the latest version of the schema from the Confluent Schema Registry and your semantic meaning will persist between imports. This means you can keep your message schemas up to date and your semantic meaning will be preserved.
+
+### Visualize schemas, topics, services and domains
+
+When you import your schemas into EventCatalog you can assign them to producers, consumers and topics (channels).
+
+After the import process, you can use the EventCatalog Visualizer to see exactly how your schemas, topics, services and domains are mapped.
+
+![Example Image](./images/visualizer.png)
+
+
+### Downloading schemas
+
+EventCatalog supports any schema format (e.g avro, json, protobuf, etc). When you import your schemas into EventCatalog you can view and download the schema directly from EventCatalog.
+
+### Missing a feature?
+
+If you are missing a feature, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
+
+### Example
+
+See the [eventcatalog-asyncapi-example](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi) for a working example.

package/dist/docs/plugins/confluent-schema-registry/04-examples.md

@@ -0,0 +1,19 @@
+---
+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 Confluent Schema Registry plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Confluent Schema Registry Example](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry/basic)
+  - An example of using the Confluent Schema Registry plugin to generate a catalog from a Confluent Schema Registry, including services, and topics.
+- [Import all schemas in a Confluent Schema Registry](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry/document-all-schemas) 
+  - An example that will document all schemas in a Confluent Schema Registry including all the versions.
+- [Confluent Schema Registry with EventCatalog Chat](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry/eventcatalog-chat-with-schemas-and-topics) 
+  - Import schemas into EventCatalog and use EventCatalog Chat to ask questions about the schemas and topics.

package/dist/docs/plugins/confluent-schema-registry/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Confluent Schema Registry Plugin",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "confluent-schema-registry",
+    "title": "Confluent Schema Registry",
+    "description": "Confluent Schema Registry integration for EventCatalog"
+  }
+}

package/dist/docs/plugins/eventbridge/00-intro.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with Amazon EventBridge plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<AddedIn version="2.6.0"/>
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/MeBuwAflwM4?si=rhio4gjfDPau4eqB" 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>
+
+---
+
+[Amazon EventBridge](https://aws.amazon.com/eventbridge/) is an AWS service that helps developers build event-driven applications at scale. Amazon EventBridge offers mutiple solutions including [Event Bus](https://aws.amazon.com/eventbridge/), [Amazon EventBridge Pipes](https://aws.amazon.com/eventbridge/) and [Amazon EventBridge Scheduler](https://aws.amazon.com/eventbridge/).
+
+Amazon EventBridge also offers [a schema registry](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-schema.html). This registry help you store your events in JSON and OpenAPI formats, give you the ability to download code bindings and also manage schema versions with automatic schema discovery.
+
+Using the [schema discovery feature](https://aws.amazon.com/blogs/compute/introducing-amazon-eventbridge-schema-registry-and-discovery-in-preview/), as events are put onto the event bus 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.
+
+Although EventBridge offers managed schema solutions, [there is a still an issue of discoverabilty and documentation for your events, services and domains](https://www.youtube.com/watch?v=VLUvfIm9wnQ&t=4s). It still remains difficult to organize your event-driven architecture for governance. 
+
+### Why use EventCatalog with EventBridge?
+
+Using the EventCatalog EventBridge generator you can automate and generate your EventCatalog. Enable your teams to quickly find events from EventBridge, what services they belong too and how to start consuming them.
+
+
+### Core Features
+
+The EventCatalog Amazon EventBridge plugin can provide you with many features:
+
+- ⭐️ Generate domains, services, channels and messages into your catalog
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your registry versions](#automatic-versioning)
+- ⭐️ [Allow you to write and persist custom markdown between changes](#persist-markdown)
+- ⭐️ [Display your JSONDraft and OpenAPI schemas for each event in EventCatalog](#downloading-schemas)
+- ⭐️ [Filter events to match to your services](#using-filters-to-map-events-to-your-services)
+- ⭐️ Visualize your architecture
+- ⭐️ Download schemas and code bindings
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/eventbridge/eventbridge.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 EventBridge plugin let's you map your events into domains and services. You can use [custom filters (prefix, suffix, detailType and source)](#using-filters-to-map-events-to-your-services) to map which events you want your service to produce and consume.
+
+You can also use the EventCatalog plugin to map ALL events from your registry into your system and not map them into services if you wish to have a direct import.
+