@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/channels/02-adding-channels.md

@@ -0,0 +1,198 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Creating a channel
+title: Creating channels
+description: Creating and managing channels within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0" />
+
+Adding a channel to your Catalog is a great way for you to document how messages are transported between producers and consumers.
+
+### What do channels look like in EventCatalog?
+
+![Example](../img/channels/channel-page-example.png)
+<a href="https://demo.eventcatalog.dev/docs/channels/inventory.%7Benv%7D.events/1.0.0" class="block">View demo</a>
+
+## Adding a new channel
+
+To add a new channel create a new folder called `channels` and then add your channel files to it.
+
+- `**/channels/{Channel Name}/index.mdx` 
+  - (example `**/channels/EventsChannel/index.mdx`)
+  - (example `**/channels/inventory.{env}.events/index.mdx`)
+  - (example `**/channels/EventBus/index.mdx`)
+
+Channels can be defined in any folder you like. This let's you group channels by domains, service, teams anything you want.
+
+### Creating the channel file
+
+Within your channel folder you will need to create an `index.mdx` file.
+
+The `index.mdx` contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a channel markdown file may look like. [You can read the API docs for the channel front matter API](/docs/api/channel-api)_
+
+```md title="/channels/inventory.{env}.events/index.mdx (example)"
+---
+# id of your channel, used for slugs and references in EventCatalog.
+# this channel is using dynamic naming using parameters
+id: inventory.{env}.events
+
+# Display name of the Channel, rendered in EventCatalog
+name: Inventory channel
+
+# Version of the Channel
+version: 0.0.1
+
+# Short summary of your Channel
+summary: |
+  Central event stream for all inventory-related events including stock updates, allocations, and adjustments
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Address of the channel, this example shows a kafka address with parameters, but it can be anything
+address: inventory.{env}.events
+
+# optionally document the params for your channel name
+# here we know that the channel address "env" value can be "dev,stg,or prod"
+parameters:
+  env:
+    enum:
+      - dev
+      - stg
+      - prod
+    description: 'Environment to use'
+---
+
+### Overview
+
+The Inventory Events channel is the central stream for all inventory-related events across the system. This includes stock level changes, inventory allocations, adjustments, and stocktake events. Events for a specific SKU are guaranteed to be processed in sequence when using productId as the partition key.
+
+<!-- Shows channel information on the page including a table of all your params and their values -->
+<ChannelInformation />
+
+<!-- Rest of markdown -->
+
+```
+
+**That's it!**
+
+Once you add your new channel to EventCatalog, it will now show in the catalog.
+
+With **channels** you can write any Markdown you want and it will render on your page. Every channel gets its own page.
+
+Within your markdown content you can use [components](/docs/development/components/using-components) to add interactive components to your page.
+
+If you want to see some examples you can [look at the EventCatalog demo on GitHub](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/channels).
+
+---
+
+## Using parameters in channel names
+
+You may have some channel names/addresses that are dynamic. For example `address: inventory.{env}.events`.
+
+The channel `address: inventory.{env}.events` shows us the channel name is dynamic with the given parameter `env`.
+
+In your channel you can document your parameters, give them values, default values and descriptions.
+
+```md
+---
+# channel markdown file.
+
+# The dynamic address
+address: inventory.{env}.events
+
+# optionally document the params for your channel name
+# here we know that the channel address "env" value can be "dev,stg,or prod"
+parameters:
+  env:
+    # What values for the parameter? (optional)
+    enum:
+      - dev
+      - stg
+      - prod
+    # what is the default value (optional)
+    default: dev
+    # Any examples if you want to list them
+    examples: 
+      - dev
+      - stg
+      - prod
+    # Describe the channel information (optional)
+    description: 'Environment to use'
+---
+```
+
+Once this information is defined, it can then be rendered on your page using the `<ChannelInformation />` component.
+
+#### Example output using the `<ChannelInformation />` component
+
+![Example](../img/channels/channelinformation-example.png)
+
+## Using protocols in channels
+
+Your channel can have one or many protocols. To define a protocol you add the property to your channel.
+
+```md
+---
+id: inventory.{env}.events
+
+# rest of channel markdown...
+
+# You can define one or many protocols
+# list of protocols: https://eventcatalog.dev/docs/development/guides/channels/introduction#protocols
+protocols:
+  - http
+  - kafka
+  - mqtt
+---
+```
+
+These protocols will be displayed on your channel page and the visualizer.
+
+You can get [the list of protocols here](/docs/development/guides/channels/introduction#protocols).
+
+<AddedIn version="3.18.0" />
+
+## Setting a delivery guarantee
+
+You can document the delivery guarantee for your channel using the `deliveryGuarantee` field. This tells consumers what to expect regarding message delivery behavior.
+
+```md
+---
+id: inventory.{env}.events
+
+# How reliably messages are delivered through this channel
+# Accepted values: at-most-once | at-least-once | exactly-once
+deliveryGuarantee: at-least-once
+---
+```
+
+When set, the visualiser shows a colored badge on the channel node. You can read more about the accepted values in the [channel API reference](/docs/api/channel-api#deliveryGuarantee).
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` in your frontmatter to display a custom icon on the channel. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/channels/inventory.{env}.events/index.mdx (example)"
+---
+id: inventory.{env}.events
+name: Inventory channel
+version: 0.0.1
+styles:
+  icon: /icons/streaming/kafka.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/streaming/kafka.svg`) or an absolute URL (e.g. `https://cdn.simpleicons.org/apachekafka`).
+
+

package/dist/docs/development/guides/channels/04-adding-messages-to-services.md

@@ -0,0 +1,292 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog domains
+sidebar_label: Routing messages through channels
+title: Routing messages through channels
+description: Understanding how to route messages through channels
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.65.0" />
+
+Services in EventCatalog can **send** and **receive** messages.
+
+When you define this you can also specify **how** the message is transported using channels.
+
+You do this using the `to` and `from` fields in your service frontmatter.
+
+### Publishing messages to channels
+
+To publish a message through a channel you need to specify the channel in the `to` field in your service frontmatter.
+
+In this example the `OrderService` sends an `OrderPlaced` message to the `orders.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+# The messages this service sends
+sends:
+  # The id of the message this service sends
+  - id: OrderPlaced
+    to:
+      - id: orders.events
+      # You can also publish to many channels
+      - id: orders.events.filtered
+---
+```
+
+_This assumes you have already defined the `orders.events` channel documentation._
+
+### Consuming messages from channels
+
+To consume a message from a channel you need to specify the channel in the `from` field in your service frontmatter.
+
+In this example the `PaymentService` consumes the `OrderPlaced` message from the `orders.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: PaymentService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      - id: orders.events
+      # You can also consume from many channels
+      - id: orders.events.filtered
+---
+```
+
+### Channels visualized in EventCatalog
+
+When messages get added to your channels EventCatalog will visualize this for you through the visualizer.
+
+![Example](../img/channels/channels-example.png)
+
+:::tip Turn off channels in the visualizer
+You can turn off the channels in the visualizer by using the visualizer settings in the UI.
+:::
+
+## Chaining channels
+
+In some cases you may want to chain channels together. For example you may want to send a message from one channel to another channel before it is consumed by something downstream.
+
+For example you may want to publish an event to a broker, then route/filter events to another channel (e.g Queue, Topic, etc) before it is consumed by something downstream.
+
+This let's you model publish/subscribe patterns or point to point messaging patterns.
+
+### Example of publish/subscribe pattern
+
+Let's say we have :
+
+- A `OrdersService` publishing an `OrderPlaced` event to the `orders.events` channel.
+- A `PaymentService` consuming the `OrderPlaced` event from the `orders.events` channel.
+- A `FraudDetectionService` consuming the `OrderPlaced` event from the `orders.events` channel.
+
+
+To model this, we define the `OrdersService` to send the `OrderPlaced` event to the `orders.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+# The messages this service sends
+sends:
+  - id: OrderPlaced
+    to:
+      - id: orders.events
+---
+```
+
+Then we define the `PaymentService` to consume the `OrderPlaced` event from the `orders.events` channel.
+
+```md title="/services/Payment/index.mdx (example)"
+---
+id: PaymentService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      - id: orders.events
+---
+```
+
+Then we define the `FraudDetectionService` to consume the `OrderPlaced` event from the `orders.events` channel.
+
+```md title="/services/FraudDetection/index.mdx (example)"
+---
+id: FraudDetectionService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      - id: orders.events
+---
+```
+
+This will model that the `OrderServices` is publishing onto the broker, with many consumers consuming the event from the same channel.
+
+### Point to point messaging pattern
+
+Let's say we have :
+
+- A `OrdersService` publishing an `OrderPlaced` event to the `orders.events` event broker.
+- Filtering is setup on the `orders.events` event broker to route the event to a new topic `orders.events.filtered`
+- A `PaymentService` consumes the event through a custom queue `payment.queue`
+
+First we define the `OrdersService` to publish an event to the `orders.events` event broker.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+# The messages this service sends
+sends:
+  - id: OrderPlaced
+    to:
+      # Route to the event broker we defined
+      - id: orders.events
+---
+```
+
+Next we define the `PaymentService` to consume the event from the `payment.queue` queue.
+
+```md title="/services/Payment/index.mdx (example)"
+---
+id: PaymentService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      # Consume from it's own queue
+      - id: payment.queue
+---
+```
+
+Next we setup the routing logic between the channels.
+
+Here, we tell the broker (channel) that is can route to the `orders.events.filtered` topic.
+
+```md title="/channels/orders.events/index.mdx (example)"
+---
+id: orders.events
+# The routes for this channel
+routes:
+  - id: orders.events.filtered
+---
+```
+
+Next, we tell the `orders.events.filtered` channel it can route to the `payment.queue` queue.
+
+```md title="/channels/orders.events.filtered/index.mdx (example)"
+---
+id: orders.events.filtered
+# The routes for this channel
+routes:
+  - id: payment.queue
+    to:
+      - id: payment.queue
+---
+```
+
+EventCatalog will understand the channel routes and relationships and create a visual representation of the channels and their relationships.
+
+![Example](../img/channels/channel-chains.png)
+
+
+---
+
+### Looking for previous channel documentation?
+
+Find previous channel documentation below. If you are using EventCatalog 2.65.0 or greater you can skip this section.
+
+<details>
+<summary>Channel documentation for versions less than 2.65.0 </summary>
+
+
+EventCatalog supports different types of messages (commands, events and queries).
+
+Any message can be added to **one or many channels**.
+
+![Example](../img/channels/channels-example.png)
+
+To add messages to a channel you first have to define your messages.
+
+Once you define your message you can specify that channel/s it uses.
+
+:::tip Turn off channels in the visualizer
+
+In the visualizer you can show and hide the channels.
+
+To hide the channels in the visualizer you can use the visualizer settings in the UI
+:::
+
+:::tip Why am I seeing multiple nodes for my channels in the visualizer?
+
+By default EventCatalog will render multiple nodes for your channels in the visualizer. This is to give you a better understanding of the relationship between your messages and channels.
+
+If you prefer to only see a single node for your channels you can change the [rendering mode in the visualizer settings](/docs/api/config#visualiser).
+
+:::
+
+## Adding messages to your channels
+
+To add a message to a channel, you need to add the `channels` information to your message.
+
+Here is an example of adding channel information to an `InventoryOutOfStockEvent`.
+
+```md title="/events/InventoryOutOfStockEvent/index.mdx (example)"
+---
+id: InventoryOutOfStockEvent
+... # other event frontmatter
+channels:
+  # The id of the channel to map to.
+  - id: inventory.{env}.events
+    # The version of the channel, this is optional and not required
+    # EventCatalog will map to the latest channel version if not used.
+    version: 0.0.1
+    # optional list of params for this channel
+    # this example means that this message is used on the inventory.dev.events channel
+    parameters:
+      env: dev
+---
+
+<!-- Markdown contents... -->
+
+```
+
+The **receives** and **sends** fields in your service tell EventCatalog which messages this service either consumes or publishes.  
+
+:::info Versioning your channels
+  Versioning for channels is optional. But if your message/channel relationship evolves over time, and you find value capturing this version/history then you can version your channels.
+:::
+
+### Using semver versioning
+
+You can use [semver](https://semver.org/) syntax when referencing your channels in your messages.
+
+```md title="/events/InventoryOutOfStockEvent/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+channels:
+    # Latest minor version of InventoryEvents (channel) will be added
+    - id: InventoryEvents
+      version: 0.x.1
+    # Minor and patches of this version will be linked
+    - id: NotificationsChannel
+      version: ^1.0.1
+    # Latest version of this service will be shown by default.
+    - id: PaymentsChannel
+---
+
+<!-- Markdown contents... -->
+
+```
+
+### Visualizing messages with channels
+
+When messages get added to your channels EventCatalog will visualize this for you through the visualizer.
+
+![Example](../img/channels/visualizer.png)
+
+</details>

package/dist/docs/development/guides/channels/09-configuration

@@ -0,0 +1,39 @@
+---
+sidebar_position: 9
+keywords:
+    - configuration
+    - channels
+sidebar_label: Visualizer Configuration
+title: Visualizer Configuration
+description: Configuration for the visualizer
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.42.0" />
+
+By default EventCatalog will render multiple nodes for your channels in the visualizer. This is to give you a better understanding of the relationship between your messages and channels.
+
+If you prefer to only see a single node for your channels you can change the [rendering mode in the visualizer settings](/docs/api/config#visualiser).
+
+
+## Visualizer configuration
+
+The visualizer configuration is set in the `eventcatalog.config.js` file.
+
+```js
+module.exports = {
+  visualiser: {
+    channels: {
+      // The render mode for channels in the visualiser
+      // supports `flat` or `single`
+      renderMode: 'single'
+    }
+  }
+}
+```
+
+### `flat` and `single` view examples
+
+![Flat Example](./img/flat-single-view.png)
+

package/dist/docs/development/guides/channels/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Channels",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/channels",
+    "description": "A collection of guides to help you understand channels and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/channels/ownership-and-components/01-owners.md

@@ -0,0 +1,44 @@
+---
+keywords:
+- EventCatalog
+- channels 
+- owners
+sidebar_label: Owners
+title: Adding channel owners
+description: Adding owners to channels with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0" />
+
+Owners in EventCatalog are either **users** or **teams** and are **optional**.
+
+To add an owner or a team, you need to add the user or team to the owners field of the channel.
+
+## Adding owners using frontmatter
+
+To add owners within a channel you need to add them to the `owners` array within your channel frontmatter API.
+
+You need to add the `id` of the owner.
+
+```md title="/channels/OrderChannel/index.mdx (example)"
+---
+id: OrderChannel
+... # other channel frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your channels can provide others with context of who owns this channel and how to contact them.
+
+:::tip Creating users and teams
+    EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
+:::
+
+

package/dist/docs/development/guides/channels/ownership-and-components/02-components.md

@@ -0,0 +1,16 @@
+---
+keywords:
+    - components 
+    - domains
+sidebar_label: Components
+title: Components
+description: Component list for domains 
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0" />
+
+You can add custom EventCatalog components to your services.
+
+[See the list of components and how to use them](/docs/development/components/using-components).

package/dist/docs/development/guides/channels/ownership-and-components/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Ownership & components",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/channels/ownership-and-components",
+    "description": "A collection of guides to help you understand entities and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/channels/versioning-and-lifecycle/01-versioning.md

@@ -0,0 +1,31 @@
+---
+keywords:
+- versioning
+- channels
+sidebar_label: Versioning
+title: Versioning
+description: Learn how to version channels
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0" />
+
+All content in EventCatalog can be versioned. This allows you to keep historic versions of content which can give context to users why things are changing.
+
+## How to version a channel
+
+1. Create a `/versioned` directory inside the `/channels` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/channels/OrdersChannel/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/channels/OrdersChannel/versioned/0.0.1/index.mdx`
+    - Note: the version inside this index.mdx file would be `0.0.1`
+1. Bump the version of the `index.mdx` file in the route of the channel.
+    - Example `/channels/OrdersChannel/index.mdx`, change the `version` to `0.0.2`
+
+## How to navigate to versions
+
+EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/channels/OrdersChannel/1.0.2 would load the 1.0.2 version of this channel).
+
+![Example](../../img/channels/versions.png)