@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/governance/architecture-change-detection/06-pipeline-gates.md

@@ -0,0 +1,162 @@
+---
+sidebar_position: 6
+sidebar_label: Pipeline gates
+title: Pipeline gates
+description: Block merges automatically when governance rules trigger
+---
+
+Use the `fail` action to exit the CLI with code `1`, turning governance checks into hard gates that prevent merges when architectural rules are violated. Without `fail`, triggered rules only notify -- the CLI always exits `0`.
+
+:::info Scale plan required
+Architecture Change Detection requires an [EventCatalog Scale plan](https://eventcatalog.dev/pricing).
+:::
+
+## Add the fail action
+
+Add `type: fail` to any rule that should block the pipeline. The `message` field is optional but recommended -- it explains to the developer exactly what needs to happen before the PR can merge.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+      - message:PaymentProcessed
+    actions:
+      - type: console
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+When this rule fires, the CLI prints the failure reason and exits with code `1`:
+
+```
+Governance check: comparing feat/api-change against main
+
+Governance:
+
+  Rule "payment-schema-guard" triggered (schema_changed):
+    ! Schema changed for PaymentProcessed (event) — consumers: PaymentService
+
+1 rule triggered.
+
+FAILED: payment-schema-guard
+  Schema change impacts payment services. Requires sign-off from @payments-team.
+```
+
+## Combine with webhooks
+
+Pairing `type: fail` with `type: webhook` lets you block the pipeline and notify the right team at the same time. Both actions run before the process exits.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+      - consumes:BillingService
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_ALERTS_WEBHOOK
+        headers:
+          Authorization: Bearer $SLACK_TOKEN
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+## Use environment variables in messages
+
+The `message` field supports `$ENV_VAR` interpolation, the same as webhook URLs and headers. This lets you include dynamic content such as a team handle or ticket URL stored in CI secrets.
+
+```yaml
+actions:
+  - type: fail
+    message: "Breaking change detected. Contact $PAYMENTS_TEAM_HANDLE for approval."
+```
+
+## Mix blocking and non-blocking rules
+
+Rules without a `fail` action always exit `0`. You can freely mix notification-only rules with blocking rules in the same file. Only rules that include `type: fail` and actually trigger will cause a non-zero exit.
+
+```yaml title="governance.yaml"
+rules:
+  # Blocks CI
+  - name: consumer-removal-guard
+    when:
+      - consumer_removed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: fail
+        message: "Removing a consumer is a breaking change. Open a migration ticket first."
+
+  # Notifies only, never blocks
+  - name: notify-new-consumers
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_NOTIFICATIONS_WEBHOOK
+```
+
+## Set up GitHub Actions
+
+No special flags are needed. The step fails automatically when the CLI exits with code `1`.
+
+```yaml title=".github/workflows/governance.yaml"
+name: EventCatalog Governance
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+      - run: git fetch origin main
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: |
+          npx @eventcatalog/cli governance check \
+            --base main \
+            --target ${{ github.head_ref }}
+        env:
+          EVENTCATALOG_SCALE_LICENSE_KEY: ${{ secrets.EVENTCATALOG_SCALE_LICENSE_KEY }}
+          SLACK_ALERTS_WEBHOOK: ${{ secrets.SLACK_ALERTS_WEBHOOK }}
+          SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}
+```
+
+If a triggered rule has `type: fail`, the `Run governance check` step is marked as failed and the PR cannot be merged until the check passes.
+
+## Set up GitLab CI
+
+```yaml title=".gitlab-ci.yml"
+governance:
+  stage: validate
+  script:
+    - npx @eventcatalog/cli governance check --base origin/main
+  variables:
+    EVENTCATALOG_SCALE_LICENSE_KEY: $EVENTCATALOG_SCALE_LICENSE_KEY
+    SLACK_ALERTS_WEBHOOK: $SLACK_ALERTS_WEBHOOK
+```
+
+## Common gating patterns
+
+| Scenario | Trigger | Resource filter |
+|---|---|---|
+| Block schema changes to payment messages | `schema_changed` | `consumes:PaymentService` or `message:PaymentProcessed` |
+| Block silent consumer removal | `consumer_removed` | `"*"` |
+| Block unreviewed deprecations | `message_deprecated` | `"*"` |
+| Block producer removal for critical messages | `producer_removed` | `message:OrderCreated` |

package/dist/docs/development/governance/architecture-change-detection/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Architecture Change Detection",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": true
+}

package/dist/docs/development/guides/12-customize-your-sidebar.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 200
+keywords:
+- EventCatalog custom documentation
+sidebar_label: Customize sidebar
+title: Customize your docs sidebar
+description: Customize your docs sidebar to show your own content.
+---
+
+EventCatalog provides the ability to customize the documentation sidebar to show your own content.
+
+You can read and follow the guide on [how to customize the documentation sidebar](/docs/development/customization/customize-sidebars/documentation-sidebar).

package/dist/docs/development/guides/99-adding-analytics.md

@@ -0,0 +1,138 @@
+---
+sidebar_position: 99
+sidebar_label: Adding Analytics
+title: Adding Analytics
+description: Track page views and user behavior across your catalog
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<PlanBanner plan="Scale" />
+<AddedIn version="3.21.0" />
+
+EventCatalog supports analytics integrations that let you track how your team navigates and uses your catalog. Connect your existing analytics tools to understand which services, events, and flows your team visits most.
+
+Three providers are supported: **Google Analytics 4**, **Google Tag Manager**, and **PostHog**. Multiple providers can be enabled at the same time.
+
+*Don't see your analytics provider? [Get in contact with us](https://discord.gg/3rjaZMmrAm) and let us know.*
+
+## How it works
+
+Analytics are configured in `eventcatalog.config.js` under the `integrations` key. When EventCatalog loads, the provider scripts are injected into the page `<head>` and a tracker listens for every navigation event.
+
+Every page view sends a set of properties automatically extracted from the URL:
+
+| Property | Description |
+|---|---|
+| `url` | The page pathname |
+| `section` | Catalog area: `visualiser`, `discover`, `directory`, `schemas`, `custom-docs`, `docs`, `home`, or `other` |
+| `resource_type` | One of: `service`, `event`, `command`, `query`, `domain`, `flow`, `channel`, `entity` |
+| `resource_id` | The resource identifier |
+| `resource_version` | The semver version |
+
+Analytics scripts load asynchronously and never block page rendering. If a provider fails, errors are caught silently so analytics never affect the catalog.
+
+## Configure a provider
+
+Add an `integrations` block to your `eventcatalog.config.js`. All providers are optional and can be combined.
+
+### Google Analytics 4
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+    },
+  },
+};
+```
+
+### Google Tag Manager
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    gtm: {
+      tagId: 'GTM-XXXXXXX',
+    },
+  },
+};
+```
+
+### PostHog
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    posthog: {
+      apiKey: 'phc_XXXXXXXXXXXX',
+      // Optional: defaults to US cloud
+      apiHost: 'https://us.i.posthog.com',
+    },
+  },
+};
+```
+
+### Use multiple providers
+
+Providers can be combined in a single `integrations` block.
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+    },
+    gtm: {
+      tagId: 'GTM-XXXXXXX',
+    },
+    posthog: {
+      apiKey: 'phc_XXXXXXXXXXXX',
+    },
+  },
+};
+```
+
+## Enable debug mode
+
+Set `debug: true` to log all analytics events to the browser console. This is useful for verifying that events are being sent correctly before deploying.
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    debug: true,
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+    },
+  },
+};
+```
+
+All events will appear in the browser console prefixed with `[EventCatalog Analytics]`, including adapter registration, page views, and any custom events.
+
+## Track custom events
+
+The analytics manager is exposed on `window.__ec_analytics`. Use it to send custom events from your own scripts or MDX pages.
+
+```js
+if (window.__ec_analytics) {
+  window.__ec_analytics.track('custom_event', { key: 'value' });
+}
+```
+
+Custom events are forwarded to all configured providers simultaneously.
+
+## Missing an integration?
+
+If you need support for an analytics provider not listed here, [open a GitHub issue](https://github.com/boyney123/eventcatalog/issues) or [join the Discord community](https://discord.gg/3rjaZMmrAm) and let us know. We are always looking to expand our integrations based on what teams are using.
+
+:::info Scale plan required
+Analytics integrations require an [EventCatalog Scale plan](https://eventcatalog.dev/pricing). If you configure integrations without a valid license, a warning is shown during build.
+:::

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

@@ -0,0 +1,11 @@
+{
+  "label": "Documenting your architecture",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "guides",
+    "description": "A collection of guides for EventCatalog."
+  }
+}

package/dist/docs/development/guides/changelogs/01-introduction.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Changelogs
+sidebar_label: What are changelogs?
+title: Understanding changelogs
+description: What are changelogs
+---
+
+In your architecture, various resources like domains, services, schemas, and boundaries are constantly evolving. **Unfortunately, the context or reason behind these changes often gets lost.**
+
+EventCatalog changelogs allow you to capture these changes and help your team understand the history of your architecture.
+
+### Features
+
+- Powered by markdown, add a `changelog.mdx` to your domains, services and messages
+- Automated diffs for `.json`, `.avro`, `.yml` and `.yaml` files.
+- Custom components and MDX component support
+- Timestamps and linear history on page
+
+
+
+
+#### Example
+
+<!-- ![Example](/assets/images/changelog-b60ba4ecaafb228a61fd5a517d3c1428.png) -->
+
+![Example](/img/blogs/changelog.png)
+
+[You can see a changelog example here](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1/changelog).
+
+<!-- http://localhost:3000/assets/images/changelog-b60ba4ecaafb228a61fd5a517d3c1428.png -->

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

@@ -0,0 +1,94 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog changelogs
+sidebar_label: Creating a changelog
+title: Creating changelogs
+description: Creating and managing changelogs within EventCatalog.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Changelogs are currently supported in [domains](/docs/development/guides/domains/versioning-and-changelogs/changelog), [services](/docs/development/guides/services/versioning-and-lifecycle/changelog) and [messages](/docs/development/guides/messages/common/changelog).
+
+To add a changelog to your resources you need to create a `changelog.mdx` file.
+
+- /\{resource\}/\{resource name\}/changelog.mdx
+  - example: /services/My Service/changelog.mdx
+  - example for verion: /services/My Service/versioned/0.0.1/changelog.mdx
+
+**Example of changelogs for resources**
+
+<Tabs>
+  <TabItem value="events" label="Events" default>
+   ```md title="/events/OrderPlaced/changelog.mdx"
+---
+createdAt: 2024-08-01
+badges:
+    - content: ⭐️ JSON Schema
+      backgroundColor: purple
+      textColor: purple
+---
+
+### Added support for JSON Schema
+
+InventoryAdjusted uses Avro but now also supports JSON Draft 7.
+
+```json title="Employee JSON Draft"
+// labeled-line-markers.jsx
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Employee",
+  "properties": {
+    "Name": {
+      "type": "string"
+    },
+    "Age": {
+      "type": "integer"
+    },
+    "Town": {
+      "type": "string"
+    }
+  },
+  "required": ["Name", "Age", "Town"]
+}
+
+``
+```
+
+  </TabItem>
+  <TabItem value="services" label="Services">
+    ```md title="/services/Inventory/changelog.mdx"
+    ---
+createdAt: 2024-08-01
+---
+
+### Service receives additional events
+
+Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.
+    ```
+  </TabItem>
+  <TabItem value="domains" label="Domains">
+    ```md title="/domains/Order/changelog.mdx"
+    ---
+createdAt: 2024-08-01
+---
+
+### New service added to the Payment domain
+
+Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.
+    ```
+  </TabItem>
+</Tabs>
+
+### Viewing your changelog
+
+Domains, services and messages have a **Changelog** button. Clicking this button will take you to the changelog for that resource.
+
+![Example output](./img/changelog-button.png)
+
+Domains, services and messages all have a changelog url.
+
+See example changelog: https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1/changelog

package/dist/docs/development/guides/changelogs/03-automated-changelogs.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog diffs
+sidebar_label: Automated diffs
+title: Automated diffs
+description: Understanding how EventCatalog automates diffs for your files
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.7.3"/>
+
+EventCatalog allows you to store schemas, API specifications and custom files along side your domains, services and messages. For [example you can add specifications to a service](/docs/development/guides/services/adding-to-services/openapi).
+
+When you version your resources, you can also version the files. When you do this, EventCatalog will match the current version to it's previous version and calculate if any diffs should be displayed in your changelog page.
+
+**Features**
+
+- Automated diffs for your OpenAPI and AsyncAPI files
+- Automated diffs for your schemas (any format)
+
+:::info
+Automated diffs only work with `.json`, `.avro`, `.yml` and `.yaml` files at the moment. If you would like to support more files please raise an issue on GitHub.
+:::
+
+### How it works
+
+Let's say we have a service called Orders, this service has an OpenAPI file.
+- `/services/Orders/index.mdx`
+- `/services/Orders/openapi.yml`
+- `/services/Orders/changelog.mdx`
+
+Let's now version this service, by added the `versioned` folder.
+
+- `/services/Orders/versioned/0.0.1/index.mdx`
+- `/services/Orders/versioned/0.0.1/openapi.yml`
+- `/services/Orders/versioned/0.0.1/changelog.mdx`
+
+If any changes have been made to the `openapi.yml` file in this example, this changes will be shown in the service changelog page.
+
+![Automated logs](./img/automated-logs.png)
+
+[You can see the example in our demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/changelog).

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

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

package/dist/docs/development/guides/channels/01-introduction.md

@@ -0,0 +1,111 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Services
+sidebar_label: What are channels?
+title: Understanding channels
+description: What are channels? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0" />
+
+In EventCatalog a channel represents the organization and transmission of messages. 
+
+Channels in EventCatalog describe how a messages transport between producers and consumers. You can use the channels resource to help your team understand how your messages are transported.
+
+```mermaid 
+sequenceDiagram
+    participant P as Producer
+    participant MC as Channel
+    participant C as Consumer
+    
+    P->>MC: Send Message
+    MC->>C: Deliver Message
+    C-->>MC: Acknowledge
+```
+<br/>
+
+Channels are resources in EventCatalog that you can define in a `/channels` directory. 
+The channel directory can be defined anywhere in your EventCatalog or you can have many channel directories in your EventCatalog.
+
+<!-- Any message ([event](/docs/development/guides/messages/events/introduction), [command](/docs/development/guides/messages/commands/introduction) or [query](/docs/development/guides/messages/queries/introduction)) can be associated to one or many channels. -->
+
+### Example of a channels are visualized in EventCatalog
+
+Here is an example of the `Orders Service` publishing an event `Order amended` over a `Kafka` channel.
+
+![Example](../img/channels/channels-example.png)
+<!-- <a class="block" href="https://demo.eventcatalog.dev/visualiser/services/InventoryService/0.0.2">View demo</a> -->
+
+### Routing messages through multiple channels
+
+<AddedIn version="2.55.0" />
+
+In some cases you may want to model how messages are routed through multiple channels, you can do this using channel `routes`.
+
+In the example below:
+
+    - The Payment Service publishes a `PaymentProcessed` event over the `PaymentEvents` channel.
+    - The Billing Service subscribes to the `PaymentProcessed` event through the `PaymentEvents` channel.
+    - The Fraud Detection Service subscribes to the `PaymentProcessed` event through the `Fraud Dection Queue` which is pulling from the `PaymentEvents` channel (chained channels)
+
+:::info What is the `PaymentEvents` channel?
+This is just an example, but a channel can be any protocol you like. For example if you are using Kafka then this channel could be a Kafka topic.
+Or if you are using an Event Bus this channel could be your bus, queue or topic.
+
+You can model as many channels as you like, and you can route messages through multiple channels.
+:::
+
+![Example](../img/channels/channel-chains.png)
+
+
+### Supported Channel Protocols
+
+**EventCatalog is technology agnostic**, so can work with any protocol.
+
+Using channels you can define the `protocol` used, this can be one or many protocols.
+
+Here is a list of protocols that are supported by EventCatalog (with icons)
+
+- [amqp](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol#:~:text=The%20Advanced%20Message%20Queuing%20Protocol,protocol%20for%20message%2Doriented%20middleware.)
+- [azure-event-hubs](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-about)
+    - _Added in EventCatalog 2.37.4_
+- [azure-service-bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview)
+    - _Added in EventCatalog 2.37.4_
+- [azure-eventgrid](https://learn.microsoft.com/en-us/azure/event-grid/overview)
+    - _Added in EventCatalog 2.37.4_
+- [eventbridge](https://aws.amazon.com/eventbridge/)
+- [googlepubsub](https://cloud.google.com/pubsub)
+- [grpc](https://grpc.io/)
+- [http](https://en.wikipedia.org/wiki/HTTP)
+- [jms](https://www.oracle.com/java/technologies/java-message-service.html)
+- [kafka](https://kafka.apache.org/protocol.html)
+- [kinesis](https://aws.amazon.com/kinesis/)
+- [mercure](https://mercure.rocks/)
+- [mqtt](https://en.wikipedia.org/wiki/MQTT)
+- [nats](https://docs.nats.io/reference/reference-protocols/nats-protocol)
+- [pulsar](https://pulsar.apache.org/docs/next/developing-binary-protocol/)
+- [redis](https://redis-doc-test.readthedocs.io/en/latest/topics/protocol/)
+- [sns](https://aws.amazon.com/sns/)
+- [solace](https://solace.com/products/apis-protocols/)
+- [sqs](https://aws.amazon.com/sqs/)
+- [tibco-ftl](https://www.tibco.com/products/tibco-ftl)
+    - _Added in EventCatalog 2.37.4_
+- [tibco-rv](https://docs.tibco.com/products/tibco-rendezvous)
+    - _Added in EventCatalog 2.37.4_
+- [ws](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
+- [webrtc](https://webrtc.org/)
+    - _Added in EventCatalog 2.55.1_
+- [zmq](https://zeromq.org/)
+
+If you are using a protocol that is not on this list, please raise on issue on [GitHub](https://github.com/event-catalog/eventcatalog) so we can get the icon supported.
+
+
+<!-- 
+### Further reading
+- [Event-driven architecture and domain-driven design](https://eda-visuals.boyney.io/visuals/eda-and-ddd)
+- [Domain, Subdomain, Bounded Context: Problem/Solution Space in DDD: Clearly Defined](https://medium.com/nick-tune-tech-strategy-blog/domains-subdomain-problem-solution-space-in-ddd-clearly-defined-e0b49c7b586c)
+- [Building Blocks of DDD](https://redis.io/glossary/domain-driven-design-ddd/) -->