@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/plugins/eventcatalog-federation/05-setup-team-catalog.md

@@ -0,0 +1,97 @@
+---
+keywords:
+- EventCatalog components
+sidebar_label: Configuring team catalogs
+title: Configuring team catalogs
+description: Configuring federation in your EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+
+<!-- <Beta /> -->
+<AddedIn version="2.18.0" />
+<PluginLicense url="/docs/development/guides/custom-components%20copy/introduction#commercial-use" />
+
+Multiple teams can own their own EventCatalog, this is useful if you have multiple teams that want to own their own EventCatalog / Documentation.
+
+**Why would your teams want their own EventCatalog?**
+
+- They want to own their own documentation
+- They want to keep their documentation close to their code
+- They want to control their own teams documentation but share it with the rest of the organization
+
+### Getting started
+
+To get started you will need to create a new EventCatalog instance for your team.
+
+You can run the following command in any directory you want to create your team catalog in.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest team-catalog
+```
+
+This will create a new EventCatalog instance in the current directory called `team-catalog`.
+
+Your team can document their own services, messages and domains in this catalog, and these can be merged into the main catalog using the federation generator.
+
+To help you get started:
+
+- [Creating domains in EventCatalog](/docs/development/guides/domains/introduction)
+- [Creating services in EventCatalog](/docs/development/guides/services/introduction)
+- [Creating events in EventCatalog](/docs/development/guides/messages/events/introduction)
+- [Creating commands in EventCatalog](/docs/development/guides/messages/commands/introduction)
+- [Creating queries in EventCatalog](/docs/development/guides/messages/queries/introduction)
+
+Once your teams have created their own documentation you can [merge them into the main catalog using the federation generator](https://github.com/event-catalog/generators).
+
+### Mocking out dependencies in your Catalog
+
+<AddedIn version="2.18.0" />
+
+If you have many team catalogs you can mock out `dependencies` in your catalog. 
+
+**Why would you want to mock out dependencies?**
+
+- Team A wants to consume an event from Team B, but Team B owns the event documentation
+- Team A mocks out the event using the `dependencies` section of their `eventcatalog.config.js` file
+- EventCatalog renders a mocked page for Team B event.
+- When merging the catalogs, the federation generator will resolve events.
+
+**How to use dependencies?**
+
+You can define dependencies in your `eventcatalog.config.js` file in the `dependencies` section.
+
+```js title="eventcatalog.config.js"
+// rest of your config
+dependencies: {
+  events: [{
+    id: 'OrderPlaced',
+    version: '1.0.0', // optional
+  }, {
+    id: 'OrderShipped',
+    version: '1.0.0', // optional
+  }]
+}
+// rest of your config
+```
+
+This will mock out the `OrderPlaced` and `OrderShipped` events in the catalog and EventCatalog will render a mocked page for these events.
+
+You can also mock out domains, services, events, commands and queries by changing the key to `domains`, `services`, `events`, `commands` and `queries` respectively.
+
+Example:
+
+```js title="eventcatalog.config.js"
+// rest of your config
+dependencies: {
+  domains: [{
+    id: 'Order',
+    version: '1.0.0', // optional
+  }]
+}
+// rest of your config
+```
+
+

package/dist/docs/plugins/eventcatalog-federation/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "EventCatalog Federation",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/eventcatalog-federation",
+    "description": "Merge multiple EventCatalog instances into a single catalog."
+  }
+}

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

@@ -0,0 +1,93 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with GitHub plugin
+---
+
+
+<!-- import PluginLicense from '@site/src/components/MDX/PluginLicense'; -->
+
+<!-- <PluginLicense url="#commercial-use" /> -->
+
+<!-- <iframe width="100%" height="515" src="https://www.youtube.com/embed/NMZKnPKx-L0?si=og1Nvnr3FfPfAqn4" 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> -->
+
+<iframe width="100%" height="515" src="https://www.youtube.com/embed/o2ryPdBa-68?si=2d1cynW_wgzNhbaV" 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>
+
+---
+
+Many folks are using GitHub as a source of truth for their schemas. This gives the flexibility to use any schema format, version control, and have review and approval processes.
+
+EventCatalog supports documenting any schema format, and you can use the [EventCatalog GitHub plugin](https://github.com/event-catalog/generators/tree/main/packages/generator-github) to pull your schemas into EventCatalog and keep them in sync along side your documentation.
+
+You can choose either to import all your schemas, or specific folders or files, and assign them to producers, consumers, domains and owners.
+
+:::info Why are people using GitHub as a source of truth for their schemas?
+GitHub is a popular tool for version control and collaboration. It gives the flexibility to use any schema format, version control, and have review and approval processes.
+:::
+
+### Core Features of the GitHub plugin
+
+The EventCatalog GitHub plugin can provide you with many features:
+
+- 📃 Pull and sync your schemas from your GitHub repository to EventCatalog
+- 📃 Keep your schemas in sync with your producers and consumers documentation
+- 📃 Supports any schema format (e.g Avro, Protobuf, JSON)
+- 📃 Import all schemas, or specific folders/files
+- ⭐ **Go beyond a schema.** Add semantic meaning to your schemas, business logic and much more. Help your developers and teams understand the meaning behind the schemas with clear documentation and visualisations.
+- 📊 Visualise producers and consumers in your architecture ([demo](https://demo.eventcatalog.dev/visualiser))
+- ⭐ Download synced schemas from EventCatalog (e.g Avro, Protobuf, JSON) ([demo](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/0.0.4))
+- 📃 Assign schemas to **events**, **commands** and **queries**
+- ⭐ Discoverability feature (search, filter and more) ([demo](https://demo.eventcatalog.dev/discover/events))
+- ⭐ And much more...
+
+### How it works
+
+1. Install the GitHub plugin on your EventCatalog instance
+1. Configure the plugin (e.g. repository, branch, path to schemas)
+1. Run the plugin to import your schemas into EventCatalog
+1. View and deploy your catalog
+
+![Example](/img/integrations/github/github-generator.png)
+
+:::info How are my schemas kept in sync?
+
+EventCatalog is a static site generator, and as such the schemas are pulled into EventCatalog when the site is built.
+
+When your schemas change in GitHub, you can re-run your build to pull in the latest changes. You can build EventCatalog as many times as you want, and it will only pull in the changes from GitHub if there are any changes.
+
+Any documentation you add to your schemas in EventCatalog will persist between builds. Only the schemas are updated.
+
+:::
+
+## Commercial and License
+
+This plugin requires a license key to be used. 
+
+You can get a 14 day trial license key to try the plugin out by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial you can purchase a license to continue using this plugin, we have different plans to suit your organization based on where you are in your governance and documentation journey.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## Need a demo?
+
+If you would like a demo of the plugin, please feel free to reach out to us and book a time to chat at hello@eventcatalog.dev.
+
+## License FAQ
+
+### What is the license key for?
+The license key is required to use the GitHub plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get a license key?
+You can obtain a license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 14-day free trial.
+
+### Terms
+- **Trial Period**: 14 days free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can purchase a full license through [EventCatalog Cloud](https://eventcatalog.cloud) to continue using the plugin.

package/dist/docs/plugins/github/01-installation.md

@@ -0,0 +1,293 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GitHub
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog GitHub plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The GitHub plugin is used to pull and sync your schemas from your GitHub repository to EventCatalog, these can be public or private repositories.
+
+You can map your schemas from your GitHub repository to commands, events and queries in your catalog, and assign these to services (producers and consumers) and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog GitHub plugin.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-github
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with GitHub plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template github
+```
+  </TabItem>
+</Tabs>
+
+## Configuration
+
+To use the plugin you need to configure it in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+<Tabs>
+  <TabItem value="apple" label="Assign schemas to commands, events and queries" default>
+
+  In this example we assign schemas to commands, events and queries in our catalog.
+
+  We don't create any producers or consumers in this example.
+
+  :::info "Why would I import schemas without assigning them to producers or consumers?"
+  You may just want to import the schemas into EventCatalog (events, queries, commands) without assigning them to producers or consumers.
+  You can assign them later to producers and consumers yourself in EventCatalog.
+  :::
+
+  
+    ```js title="eventcatalog.config.js"
+    // ...
+    generators: [
+      // 1. Import all schemas from a Confluent Schema Registry
+      [
+        '@eventcatalog/generator-github',
+        {
+          // The HTTP or SSH URL of your GitHub repository
+          source: 'https://github.com/event-catalog/eventcatalog',
+          // The branch to pull schemas from (default: main)
+          branch: 'main',
+          // The root path to your schemas
+          path: 'some-folder/schemas',
+          messages: [
+            {
+              // the id of the message, needed for eventcatalog
+              id: 'place-order',
+              // Optional name for your message (if not provided, the id will be used)
+              name: 'Place Order',
+              // Optional version for your message (if not provided, default version of 1 will be used)
+              version: '2.1',
+              // The path to the schema file (relative to the root path, some-folder/schemas/place-order.avro)
+              schemaPath: 'place-order.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'command',
+            },
+            // just required fields, defaulting version and name
+            {
+              id: 'order-shipped',
+              // The path to the schema file (relative to the root path, some-folder/schemas/order-shipped.avro)
+              schemaPath: 'order-shipped.avro',
+              type: 'event',
+            },
+          ]
+        },
+      ],
+    ];
+    ```
+  </TabItem>
+  <TabItem value="orange" label="Import schemas and assign them to producers and consumers (services)">
+
+In this example we import schemas from a GitHub repository, and assign them to producers and consumers (services).
+We also create a domain and assign our services to it. 
+
+:::info Adding documentation to your schemas
+This plugin will import and keep your schemas in sync with your producers and consumers.
+
+You can still use EventCatalog to document your schemas, services and domains using markdown. The markdown is persisted between imports.
+This let's you add semantic meaning to your schemas, and document them for your teams, whilst keeping your schemas in sync with your producers and consumers.
+:::
+
+In this example we:
+
+- Create two services (producers and consumers)
+  - `Orders Service`
+    - Sends `place-order` command
+    - Receives `order-shipped` event
+  - `Inventory Service`
+    - Sends `inventory-updated` event
+    - Receives `order-placed` event
+- Create a domain `Retail Domain`
+  - Assign the services to the domain
+
+
+```js title="eventcatalog.config.js"
+// ...
+ [
+  '@eventcatalog/generator-github',
+      {
+        // The URL of your GitHub repository
+        source: 'https://github.com/event-catalog/eventcatalog',
+        // The branch to pull schemas from (default: main)
+        branch: 'main',
+        // The root path to your schemas
+        path: 'some-folder/schemas',
+        
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // the messages this service sends
+            sends: [{
+              id: 'place-order',
+              version: '2.1',
+              // The path to the schema file (relative to the root path, some-folder/schemas/place-order.avro)
+              schemaPath: 'place-order.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'command',
+            }],
+            // the messages this service receives
+            receives: [{
+              id: 'order-shipped',
+              version: '1.0',
+              // The path to the schema file (relative to the root path, some-folder/schemas/order-shipped.avro)
+              schemaPath: 'order-shipped.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'event',
+            }],
+          },
+          {
+            id: 'Inventory Service',
+            version: '1.0.0',
+            // the messages this service sends
+            sends: [{
+              id: 'inventory-updated',
+              version: '1.0',
+              // The path to the schema file (relative to the root path, some-folder/schemas/inventory-updated.avro)
+              schemaPath: 'inventory-updated.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'event',
+            }],
+            // the messages this service receives
+            receives: [{
+              id: 'order-placed',
+              version: '1.0',
+              // The path to the schema file (relative to the root path, some-folder/schemas/order-placed.avro)
+              schemaPath: 'order-placed.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'event',
+            }],
+          },
+        ],
+        // We assign the services to a domain "Retail Domain" (optional)
+        domain: {
+          id: 'retail-domain',
+          name: 'Retail Domain',
+          version: '1.0.0',
+        }
+      },
+    ]
+```  
+  </TabItem>
+</Tabs>
+
+### Configure API keys
+
+The EventCatalog GitHub plugin requires API keys in your environment variables.
+
+1. A license key for the GitHub plugin (14 days trial, at [EventCatalog Cloud](https://eventcatalog.cloud))
+
+Create a `.env` file in the root, and add your keys to the project.
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_LICENSE_KEY_GITHUB=your-license-key
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+### Private repository authentication
+
+<AddedIn version="1.0.0" pkg="@eventcatalog/generator-github" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+The GitHub plugin supports authentication for private repositories using GitHub personal access tokens (PAT) or GitHub App installation tokens.
+
+You can authenticate in two ways:
+
+**Option 1: Environment variable (recommended)**
+
+Set the `EVENTCATALOG_GITHUB_TOKEN` environment variable in your `.env` file.
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_LICENSE_KEY_GITHUB=your-license-key
+
+# GitHub token for private repository access
+EVENTCATALOG_GITHUB_TOKEN=ghp_your_token_here
+```
+
+**Option 2: Configuration option**
+
+Pass the token directly in your configuration file.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/your-org/private-repo',
+      path: 'schemas',
+      token: process.env.MY_GITHUB_TOKEN,
+      // ... rest of configuration
+    },
+  ],
+];
+```
+
+:::tip Create a GitHub token
+To create a personal access token, visit [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens). For private repositories, you need the `repo` scope.
+:::
+
+:::info Public repositories
+For public repositories, authentication is not required. The plugin will work without any token configuration.
+:::
+
+### Running the plugin
+
+Run the plugin to import your schemas into EventCatalog.
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+#### Build your catalog for production
+
+```
+npm run build
+```
+
+
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-github).
+
+
+