@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/resources/messages/03-create-messages/01-create-event.md

@@ -0,0 +1,137 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog events
+sidebar_label: Create an event
+title: Create an event
+description: Creating and managing events within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Events are a type of message in EventCatalog that represent an immutable fact.
+
+![Example](../../../img/events/example.png)
+
+## Adding a new event
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog event">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/create-messages/create-event.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/events.md then help me create a new EventCatalog event in my catalog.
+
+Ask me for the event name, what happened, summary, whether it belongs at the root of the catalog or inside a service, domain, or system, and any known producers, consumers, channels, or schema files. Then create the correct events/{'{Event Name}'}/index.mdx, services/{'{Service Name}'}/events/{'{Event Name}'}/index.mdx, domains/{'{Domain Name}'}/events/{'{Event Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/events/{'{Event Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+You can also ask the user if they have a schema of the event, if they provide one, you can add this schema to the event, and set the schemaPath to that schema on the event frontmatter properties.
+
+If the catalog does not have any services, domains, or systems, put it into the root events folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the event should live, create the right folder structure, and add the first version of the event documentation.
+
+### Manual Creation
+
+Events live in a `/events` folder. This folder can be placed:
+
+- At the root of your catalog
+- Inside a specific service or domain folder
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'InventoryAdjusted',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a event markdown file may look like._
+
+```md title="/events/InventoryAdjusted/index.mdx (example)"
+---
+# id of your event, used for slugs and references in EventCatalog.
+id: InventoryAdjusted
+
+# Display name of the event, rendered in EventCatalog
+name: Inventory Adjusted
+
+# Version of the event
+version: 0.0.4
+
+# Short summary of your event
+summary: |
+  Event with the intent to adjust 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 `Inventory Adjusted` event represents intent to adjust the inventory of a given item.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the event will automatically appear across EventCatalog.
+
+### Assign producers and consumers to your event
+
+To add producers or consumers to your event you can read the [guide on adding messages to services](/docs/development/guides/resources/messages/connect-messages/map-producers-and-consumers).
+
+You can also assign your event to one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g Kafka, RabbitMQ, AWS SQS, AWS SNS, etc).
+
+### Adding schemas to your event
+
+You can add any schema format to your event, you can read the [guide on adding schemas to messages](/docs/development/guides/resources/schemas/add-schemas-to-messages).
+

package/dist/docs/development/guides/resources/messages/03-create-messages/02-create-command.md

@@ -0,0 +1,156 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog commands
+sidebar_label: Create a command
+title: Create a command
+description: Creating and managing commands within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A command documents intent. Use commands when one part of your architecture asks another part to do something that may be accepted, rejected, validated, or handled asynchronously (e.g a POST request)
+
+![Example](../../../img/commands/example.png)
+
+## Adding a new command
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog command">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/create-messages/create-command.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/commands.md then help me create a new EventCatalog command in my catalog.
+
+Ask me for the command name, what action it requests, summary, whether it belongs at the root of the catalog or inside a service, domain, or system, and any known invokers, handlers, channels, HTTP operation details, or schema files. Then create the correct commands/{'{Command Name}'}/index.mdx, services/{'{Service Name}'}/commands/{'{Command Name}'}/index.mdx, domains/{'{Domain Name}'}/commands/{'{Command Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/commands/{'{Command Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any services, domains, or systems, put it into the root commands folder.
+
+You can also ask the user if they have a schema of the command, if they provide one, you can add this schema to the command, and set the schemaPath to that schema on the command frontmatter properties.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the command should live, create the right folder structure, and add the first version of the command documentation.
+
+### Manual Creation
+
+Commands live in a `/commands` folder. This folder can be placed:
+
+- At the root of your catalog
+- Inside a specific service folder
+
+<ProjectTree
+  items={[
+    {
+      name: 'commands',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'UpdateInventory',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'commands',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'AddOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+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.
+
+### Assign producers and consumer to your command
+
+To add services that invoke or accept your command you can read the [guide on adding messages to services](/docs/development/guides/resources/messages/connect-messages/map-producers-and-consumers).
+
+You can also assign your command to one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g HTTP, GraphQL, etc).
+
+### 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 [messages reference](/docs/development/guides/resources/messages/reference#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/resources/schemas/add-schemas-to-messages).

package/dist/docs/development/guides/resources/messages/03-create-messages/03-create-query.md

@@ -0,0 +1,158 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog queries
+sidebar_label: Create a query
+title: Create a query
+description: Creating and managing queries within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A query documents a request for information. Use queries when one part of your architecture asks another part to return data without changing state (e.g GET request)
+
+![Example](../../../img/queries/example.png)
+
+## Adding a new query
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog query">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/create-messages/create-query.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/queries.md then help me create a new EventCatalog query in my catalog.
+
+Ask me for the query name, what information it returns, summary, whether it belongs at the root of the catalog or inside a service, domain, or system, and any known callers, handlers, channels, HTTP operation details, or schema files. Then create the correct queries/{'{Query Name}'}/index.mdx, services/{'{Service Name}'}/queries/{'{Query Name}'}/index.mdx, domains/{'{Domain Name}'}/queries/{'{Query Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/queries/{'{Query Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any services, domains, or systems, put it into the root queries folder.
+
+You can also ask the user if they have a schema of the query, if they provide one, you can add this schema to the query, and set the schemaPath to that schema on the query frontmatter properties.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the query should live, create the right folder structure, and add the first version of the query documentation.
+
+### Manual Creation
+
+Queries live in a `/queries` folder. This folder can be placed:
+
+- At the root of your catalog
+- Inside a specific service folder
+
+<ProjectTree
+  items={[
+    {
+      name: 'queries',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'GetOrder',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'queries',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'GetOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a query markdown file may look like._
+
+```md title="/queries/GetOrder/index.mdx (example)"
+---
+# id of your query, used for slugs and references in EventCatalog.
+id: GetOrder
+
+# Display name of the query, rendered in EventCatalog
+name: Get Order
+
+# Version of the query
+version: 0.0.4
+
+# Short summary of your query
+summary: |
+    Query with the intent to get an order from the system
+
+# 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 `GetOrder` query represents intent to get an order from the system.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the query will automatically appear across EventCatalog.
+
+## Assign services to your queries
+
+To add services that invoke or accept your query you can read the [guide on adding messages to services](/docs/development/guides/resources/messages/connect-messages/map-producers-and-consumers).
+
+You can also assign your query to one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g HTTP, GraphQL, etc).
+
+<AddedIn version="3.18.0" />
+
+## Document an HTTP operation
+
+If your query maps to an HTTP endpoint, use the `operation` field to document the method, path, and expected status codes.
+
+```md title="/queries/GetOrder/index.mdx (example)"
+---
+id: GetOrder
+# ...
+operation:
+  method: GET
+  path: /orders/{id}
+  statusCodes:
+    - "200"
+    - "404"
+---
+```
+
+When defined, the visualiser shows an HTTP method badge, the API path, and colored status code pills on the query node. See the [messages reference](/docs/development/guides/resources/messages/reference#operation) for all available options.
+
+## Adding schemas to your query
+
+You can add any schema format to your query, you can read the [guide on adding schemas to messages](/docs/development/guides/resources/schemas/add-schemas-to-messages).
+

package/dist/docs/development/guides/{messages/common/02-draft-messages.md → resources/messages/03-create-messages/04-create-draft-message.md}

@@ -1,16 +1,14 @@
 ---
 keywords:
 - EventCatalog events
-sidebar_label: Creating a draft message
-title: Creating draft messages
+sidebar_label: Create a draft message
+title: Create a draft message
 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**
@@ -52,12 +50,12 @@ draft:
 When you mark a message as draft, it will show in the UI as a draft message.
 
 
-![Example](../../img/draft-message.png)
+![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)
+![Example](../../../img/draft-filter.png)
 
-This will remove all resources, and only show the draft messages.
+This will remove all resources, and only show the draft messages.

package/dist/docs/development/guides/resources/messages/03-create-messages/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Create messages",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/create-messages",
+    "description": "Create events, commands, queries, and draft messages."
+  }
+}

package/dist/docs/development/guides/resources/messages/04-connect-messages/01-map-producers-and-consumers.md

@@ -0,0 +1,32 @@
+---
+keywords:
+- EventCatalog commands
+sidebar_label: Map producers and consumers
+title: Map producers and consumers
+description: Understand how to link messages to services.
+sidebar_position: 1
+---
+
+[Services](/docs/development/guides/resources/services/introduction) or Domains can either **send** or **receive** events, commands and queries. 
+
+To add messages to resource you need to reference them within your resource 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
+    # If no version is given latest version is used.
+      version: 0.0.1
+sends:  
+    # id of the message this service sends
+    - id: PaymentProcessed
+---
+
+<!-- Markdown contents... -->
+```
+
+If you don't specify a version the latest version will be used.