@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/messages/commands/02-adding-commands.md

@@ -0,0 +1,131 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog commands
+sidebar_label: Creating a command
+title: Creating commands
+description: Creating and managing commands within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Commands live in a `/commands` folder. This folder can be placed:
+
+- At the root of your catalog, or
+  - `/commands/{Command Name}/index.mdx` 
+- Inside a specific service folder.
+  - `/services/{Service Name}/commands/{Command Name}/index.mdx` 
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a command markdown file may look like._
+
+```md title="/commands/UpdateInventory/index.mdx (example)"
+---
+# id of your command, used for slugs and references in EventCatalog.
+id: UpdateInventory
+
+# Display name of the command, rendered in EventCatalog
+name: Update Inventory
+
+# Version of the command
+version: 0.0.3
+
+# Short summary of your command
+summary: |
+  Command with the intent to update the inventory
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+The `Update Inventory` command represents intent to update the inventory of a given item over HTTP.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the command will automatically appear across EventCatalog.
+
+## Writing command content
+
+You can write any Markdown inside a command. 
+
+Each command gets its own page, so use this space to fully explain how it works.
+
+You can also use [interactive components](/docs/development/components/using-components) to enrich your documentation.
+
+## Assign services to your commands
+
+To add services that invoke or accept your command you can read the [guide on adding messages to services](/docs/development/guides/messages/common/map-to-producers-and-consumers).
+
+You can also assign your command to one or more [channels](/docs/development/guides/channels/adding-messages-to-services) (e.g HTTP, GraphQL, etc).
+
+<AddedIn version="3.18.0" />
+
+## Document an HTTP operation
+
+If your command maps to an HTTP endpoint, use the `operation` field to document the method, path, and expected status codes.
+
+```md title="/commands/UpdateInventory/index.mdx (example)"
+---
+id: UpdateInventory
+# ...
+operation:
+  method: PUT
+  path: /inventory/{id}
+  statusCodes:
+    - "200"
+    - "400"
+    - "404"
+---
+```
+
+When defined, the visualiser shows an HTTP method badge, the API path, and colored status code pills on the command node. See the [command API reference](/docs/api/command-api#operation) for all available options.
+
+## Adding schemas to your command
+
+You can add any schema format to your command, you can read the [guide on adding schemas to messages](/docs/development/guides/messages/common/adding-schemas).
+
+## What should I document?
+
+There’s no strict structure, but consider including:
+
+- Purpose – What does this command do and why does it exist?
+- How to trigger it – APIs, SDKs, or UI actions
+- Schema – Payload structure and validation rules
+- Ownership – Who maintains this command?
+- Contributing – How others can propose changes
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` in your frontmatter to display a custom icon on the command. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/commands/UpdateInventory/index.mdx (example)"
+---
+id: UpdateInventory
+name: Update Inventory
+version: 0.0.3
+styles:
+  icon: /icons/messaging/sns.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/messaging/sns.svg`) or an absolute URL (e.g. `https://cdn.simpleicons.org/amazonsqs`).
+
+## How do commands appear in EventCatalog?
+
+![Example](../../img/commands/example.png)
+
+

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

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

package/dist/docs/development/guides/messages/common/01-map-to-producers-and-consumers.md

@@ -0,0 +1,37 @@
+---
+keywords:
+- EventCatalog commands
+sidebar_label: Map to producers and consumers
+title: Assigning events to services
+description: Understanding how to link events to services
+sidebar_position: 1
+---
+
+[Services](/docs/development/guides/services/introduction) can either **send** or **receive** events, commands and queries. 
+
+To add messages to services you need to reference them within your service itself by adding the `id`. The `version` is optional and if not provided the latest version will be used.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+receives:
+    # id of the message this service receives
+    - id: OrderPlaced
+    # (optional) The version of the message you want to add
+      version: 0.0.1
+sends:  
+    # id of the message this service sends
+    - id: PaymentProcessed
+---
+
+<!-- Markdown contents... -->
+```
+
+### Versioning
+
+When you reference a message in your service you can specify the version of the message.
+
+This allows you to document which versions of messages your service interacts with.
+
+If you don't specify a version the latest version will be used.

package/dist/docs/development/guides/messages/common/02-adding-schemas.md

@@ -0,0 +1,58 @@
+---
+keywords:
+- EventCatalog commands
+sidebar_label: Adding schemas to messages
+title: Adding schemas to messages
+description: Understand how to add schemas to your messages.
+sidebar_position: 2
+---
+
+EventCatalog allows you to attach schemas to any message. 
+
+**EventCatalog supports any schema format. (e.g Avro, Protobuf, JSON etc)**
+
+![Example](../../img/commands/schemas.png)
+
+Schemas are very useful for users that want to understand the properties of your message and the context behind them.
+
+### Adding schemas to your messages
+
+To add a schema to your message you need to add the `schemaPath` value in your message frontmatter and drop the schema file into your message folder.
+
+```md title="/{events|commands|queries}/InventoryAdjusted/index.mdx (example)"
+---
+id: InventoryAdjusted
+version: 0.0.4
+# relative path to the schema file
+schemaPath: schema.avro
+---
+```
+
+Folder structure:
+```md
+/commands (or /events or /queries)
+  /InventoryAdjusted
+    index.mdx
+    schema.avro
+```
+
+#### Schema Components
+
+EventCatalog supports two components to render schemas into your message page.
+
+1. `<Schema/>` - Renders the schema into your message page as a JSON code block
+2. `<SchemaViewer/>` - Renders the schema into your message page using a nice Schema component (JSON and Avro supported)
+
+```md title="/{events|commands|queries}/InventoryAdjusted/index.mdx (example)"
+<!-- Renders the given schema into the page, as a JSON code block -->
+<Schema file="schema.avro" />
+
+<!-- Renders the given schema into the page using a nice Schema component -->
+<SchemaViewer file="schema.avro" />
+```
+
+#### Adding example usage for your message
+
+Once you document your schema, you can also add `Usage Examples` for your schemas to help your teams understand how they schemas are used in a list of different ways.
+
+You can read more about in the [usage example documentation](/docs/development/guides/messages/common/examples).

package/dist/docs/development/guides/messages/common/02-deprecating.md

@@ -0,0 +1,71 @@
+---
+keywords:
+- EventCatalog
+- messages  
+- deprecating
+sidebar_label: Deprecating messages
+title: Deprecating messages
+description: Deprecating messages with EventCatalog.
+sidebar_position: 4
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.10" />
+
+Any resource in EventCatalog can be deprecated or marked as deprecated.
+
+This will show a banner on the page indicating that the resource is deprecated.
+
+## Deprecating messages using frontmatter
+
+To deprecate a message you need to add the `deprecated` field to the message frontmatter API.
+
+This accepts a `boolean` or an `object` with the following properties:
+
+- `date`: Date the message will be or was deprecated (YYYY-MM-DD)
+- `message`: Reason the message is deprecated, supports markdown (optional)
+
+```md title="/{events|commands|queries}/UpdateInventory/index.mdx (example)"
+---
+id: UpdateInventory
+... # other message frontmatter
+
+# deprecated as an object (Recommended)
+deprecated:
+  # Date the event will be or was deprecated (YYYY-MM-DD)
+  date: 2025-01-01
+  # Reason the event is deprecated, supports markdown (optional)
+  message: | 
+    This message has been deprecated and replaced by the new message **UpdateInventoryV2**.
+    Please contact the [team for more information](mailto:inventory-team@example.com) or visit our [website](https://eventcatalog.dev).
+
+# deprecated as a boolean 
+deprecated: true
+---
+
+```
+
+Configuration:
+
+- `deprecated`: `boolean` or `object`
+
+Deprecated as an object is recommended, as it gives your users more information to why the resource is deprecated and a date in the past or future.
+
+- `deprecated.date`: Date the message will be or was deprecated (YYYY-MM-DD)
+- `deprecated.message`: Reason the message is deprecated, supports markdown (optional)
+
+
+#### Rendered output
+
+Example of resource that will be deprecated:
+
+  ![Deprecating messages](../../img/deprecated/will-be-deprecated.png) 
+
+Example of resource that is deprecated:
+
+![Deprecating messages](../../img/deprecated/is-deprecated.png) 
+
+#### Demo
+
+You can see a demo of deprecating resources in the [EventCatalog demo site](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).

package/dist/docs/development/guides/messages/common/02-draft-messages.md

@@ -0,0 +1,63 @@
+---
+keywords:
+- EventCatalog events
+sidebar_label: Creating a draft message
+title: Creating draft messages
+description: Creating and managing draft messages within EventCatalog.
+sidebar_position: 4
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.48.4" />
+
+Sometimes, you may want to create a message without immediately publishing it to production. Draft messages allow you to collaborate, gather feedback, or prepare for future changes—without exposing the message as "live" in your catalog
+
+**Common Use Cases**
+- **Collaboration & Feedback**
+  - Share a draft message with teammates to gather comments and suggestions before it goes live.
+- **Versioning with Breaking Changes**
+  - Introduce a new version of a message that includes breaking changes. Keep it in draft mode until it’s fully reviewed and ready for deployment.
+- **Designing Event Lifecycles**
+  - Use drafts to plan and iterate on message definitions before promoting them to production.
+
+### How to add a draft message
+
+To mark an event as a draft, simply add the draft attribute to the frontmatter of the event file.
+
+- **Option 1:** Add a `draft` attribute to your message frontmatter.
+- **Option 2:** Add a `draft` object to your message frontmatter. (recommended)
+
+```md title="/{events|commands|queries}/InventoryOutOfStock/index.mdx (example)"
+---
+# Uses the default title and summary to mark things as draft in the UI
+draft: true
+
+# Or you can specify a title and summary for your draft
+draft: 
+  title: "Inventory Adjusted 1.0.1 is in draft"
+  # Supports markdown
+  message: |
+    ### New version of Inventory Adjusted is in draft
+
+    This is a new version of the Inventory Adjusted event. It is not yet ready for production. We are still working on it and collecting feedback from the team.
+    You can use this version in lower environments, **but please be aware that it is still in draft and may change.**
+    You can still use a previous version of the event, [Inventory Adjusted 1.0.0](/docs/events/InventoryAdjusted/1.0.0), until that version is deprecated.
+    _If you would like to provide feedback, please contact us at [feedback@eventcatalog.io](mailto:feedback@eventcatalog.io) or our slack channel [Order Management](https://join.slack.com/t/eventcatalog/shared_invite/zt-1q900000000000000000000000000000)_
+
+---
+
+```
+
+When you mark a message as draft, it will show in the UI as a draft message.
+
+
+![Example](../../img/draft-message.png)
+
+### Filtering for Draft Messages
+
+If you want to quickly find draft messages, in your architecture, you can use the [**discover** feature](https://demo.eventcatalog.dev/discover/{events|commands|queries}) and filter for draft messages.
+
+![Example](../../img/draft-filter.png)
+
+This will remove all resources, and only show the draft messages.

package/dist/docs/development/guides/messages/common/02-examples.md

@@ -0,0 +1,99 @@
+---
+keywords:
+    - examples
+    - events
+    - commands
+    - queries
+sidebar_label: Adding usage examples
+title: Message examples
+description: Add usage examples to your messages for quick reference.
+sidebar_position: 3
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.22.1" />
+
+EventCatalog lets you attach example payloads to any message (event, command, or query). This can help your team understand exactly how your schemas can be used
+in your architecture and provide them with real examples.
+
+Examples appear in the Schema Explorer under a **Usage Examples** tab alongside the schema, properties, and changelog tabs.
+
+![Example](./imgs/examples.png)
+
+### Add examples
+
+Create an `examples/` folder inside your message directory and drop in any example files. EventCatalog supports any text-based format: JSON, YAML, XML, Protobuf, and more.
+
+```
+events/
+  OrderCreated/
+    index.mdx
+    schema.json
+    examples/
+      basic-order.json
+      international-order.json
+```
+
+The **Usage Examples** tab appears automatically when at least one example file is present. No frontmatter changes are required.
+
+### Organise with subfolders
+
+You can use nested folders to group related examples. EventCatalog displays all files in a flat list regardless of folder depth.
+
+```
+examples/
+  domestic/
+    basic-order.json
+  international/
+    eu-order.json
+    apac-order.json
+```
+
+### Add metadata
+
+Place an `examples.config.yaml` (or `.yml` or `.json`) file inside the `examples/` folder to add a display name, summary, and usage snippet to each example.
+
+```yaml title="events/OrderCreated/examples/examples.config.yaml"
+basic-order.json:
+  name: Basic Order
+  summary: A simple domestic order with a single item.
+  usage: |
+    curl -X POST http://localhost:3000/events/publish \
+      -H "Content-Type: application/json" \
+      -d @basic-order.json
+
+international-order.json:
+  name: International Order
+  summary: An order with international shipping and customs information.
+```
+
+All fields are optional. When `name` is omitted, EventCatalog uses the filename without its extension as the title.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | Display name shown in the examples list |
+| `summary` | `string` | Short description shown below the name |
+| `usage` | `string` | How-to-run snippet shown below the code block |
+
+### Use the SDK
+
+You can manage examples programmatically using the EventCatalog SDK.
+
+```ts
+import { addExampleToEvent, getExamplesFromEvent, removeExampleFromEvent } from '@eventcatalog/sdk';
+
+// Add an example
+await addExampleToEvent('OrderCreated', '1.0.0', {
+  fileName: 'basic-order.json',
+  content: JSON.stringify({ orderId: '123', total: 49.99 }, null, 2),
+});
+
+// Read all examples
+const examples = await getExamplesFromEvent('OrderCreated', '1.0.0');
+
+// Remove an example
+await removeExampleFromEvent('OrderCreated', '1.0.0', 'basic-order.json');
+```
+
+Equivalent functions exist for commands (`addExampleToCommand`, `getExamplesFromCommand`, `removeExampleFromCommand`) and queries (`addExampleToQuery`, `getExamplesFromQuery`, `removeExampleFromQuery`).

package/dist/docs/development/guides/messages/common/03-owners.md

@@ -0,0 +1,40 @@
+---
+keywords:
+- EventCatalog
+- events 
+- owners
+sidebar_label: Assigning Owners
+title: Adding event owners
+description: Adding owners to events with EventCatalog.
+---
+
+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 event.
+
+## Adding owners using frontmatter
+
+To add owners within an event you need to add them to the `owners` array within your event frontmatter API.
+
+You need to add the `id` of the owner.
+
+```md title="/events/InventoryOutOfStock/index.mdx (example)"
+---
+id: AdjustInventory
+... # other event frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your events can provide others with context of who owns this event 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/messages/common/04-versioning.md

@@ -0,0 +1,27 @@
+---
+keywords:
+- versioning
+- events
+sidebar_label: Versioning messages
+title: Versioning
+description: Learn how to version events
+---
+
+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 message
+
+1. Create a `/versioned` directory inside the `/events|commands|queries` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/events|commands|queries/InventoryOutOfStock/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/events|commands|queries/InventoryOutOfStock/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 domain.
+    - Example `/events|commands|queries/InventoryOutOfStock/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/events|commands|queries/InventoryOutOfStock/1.0.2 would load the 1.0.2 version of this service).
+
+![Example](../../img/domains/versioned.png)

package/dist/docs/development/guides/messages/common/05-changelog.md

@@ -0,0 +1,73 @@
+---
+keywords:
+    - changelog 
+    - events
+sidebar_label: Message changelogs
+title: Event changelogs 
+description: Adding changelogs to your events
+---
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/services) and [messages](/docs/messages).
+
+When you [version a message](/docs/development/guides/messages/common/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that message or versioned message.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your message (or versioned message)
+    - example `/events|commands|queries/{Message}/changelog.mdx`
+    - versioned example `/events|commands|queries/{Message}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/docs/event/InventoryAdjusted/changelog.md"
+---
+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"]
+}
+
+``
+``` 
+
+Navigate to your change log page for your message (example [/docs/events/InventoryAdjusted/1.0.0/changelog](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.0/changelog)) or **click on the Changelog button** on your  message page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your message and also be used for auditing purposes.
+
+Changelogs are visualized by EventCatalog.
+
+
+

package/dist/docs/development/guides/messages/common/07-components.md

@@ -0,0 +1,12 @@
+---
+keywords:
+    - components 
+    - domains
+sidebar_label: Components
+title: Components
+description: Component list for domains 
+---
+
+You can add custom EventCatalog components to your commands.
+
+[See the list of components and how to use them](/docs/development/components/using-components).