@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/plugins/eventcatalog-federation/01-installation.md

@@ -0,0 +1,182 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Federation
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog Federation 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';
+
+<PluginLicense url="#commercial-use" />
+
+The EventCatalog Federation plugin is designed for your [main catalog](/docs/plugins/eventcatalog-federation/configuration).
+
+This plugin will allow you to merge multiple EventCatalog instances into a single catalog.
+
+## Prerequisites
+
+- [Installed EventCatalog](/docs/development/getting-started/installation)
+
+## Installation
+
+Run the command below to install the EventCatalog Federation plugin.
+
+```sh
+npm i @eventcatalog/generator-federation
+```
+
+## Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators`.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository, (generator supports any Git source e.g GitLab, Bitbucket, etc)
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // optional (specify which files you want to copy from the repository)
+        copy: [
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    // Payment Team
+    // When no `copy` values are provided, the plugin will copy eventcatalog files for you.
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the directory of the eventcatalog in your project (default it the root directory)
+        // This example clones the generators repository, and looks for the eventcatalog in the my-project-eventcatalog directory
+        sourceRootDir: 'my-project-eventcatalog'
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+  ],
+```
+
+### Configure license key
+
+The EventCatalog Federation plugin requires a license key to work with EventCatalog.
+
+You can get a trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended)
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_FEDERATION=your-license-key
+```
+
+:::tip Using an older version of EventCatalog?
+
+If you are using an older version of EventCatalog that does not support the `.env` file, you can just export the license key as an environment variable.
+
+```bash title="Setting license key in environment variables"
+export EVENTCATALOG_LICENSE_KEY_FEDERATION=your-license-key
+```
+
+:::
+
+#### 2. Setting license key in eventcatalog.config.js
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog Federation plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_FEDERATION
+      },
+    ],
+  ],
+};
+```
+
+#### 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.
+
+## Run the generator
+
+Once you have configured the plugin and license key you can run the generator.
+
+```sh
+npm run generate
+```
+
+## View your catalog
+
+Run your catalog locally to see the changes.
+
+```sh
+npm run dev
+```
+
+## 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).
+
+
+

package/dist/docs/plugins/eventcatalog-federation/02-plugin-configuration.md

@@ -0,0 +1,208 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Federation
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog Federation plugin
+---
+
+API Configuration for the EventCatalog Federation plugin
+
+
+
+## Overview
+
+The EventCatalog Federation plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `source` | string | Yes | - | Git repository URL (supports any git provider e.g GitHub, GitLab, Bitbucket) |
+| `sourceRootDir` | string | No | - | The root directory for your files. For example if your repository is organized with subdirectories, you can specify the root directory to use for the import (e.g `'my-awesome-catalog'`, would be the root directory for the import). |
+| `branch` | string | No | `'main'` | Branch to use for the import. Default is `'main'`. |
+| `copy` | object | No | - | Copy options for the import. You can pick which files to copy from the remote repository. |
+| `copy.content` | string | No | - | Content to copy to the destination. |
+| `copy.destination` | string | No | - | Destination path to copy the content to. |
+| `debug` | boolean | No | `false` | Enable debug mode. |
+| `override` | boolean | No | `false` | Override existing files in the destination. |
+| `destination` | string | No | - | Destination path to copy the content to, if you don't specify the `copy` option, the content will be copied to the root of the destination path. |
+| `enforceUniqueResources` | boolean | No | `false` | Setting to true. The plugin will enforce unique resources in the destination and error if any resources are not unique. |
+
+## Example Configuration
+
+```js title="eventcatalog.config.js"
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: "10b46030-5736-4600-8254-421c3ed56e47",
+  title: "MetaRetail Inc",
+  tagline: "Fake Retail Company for EventCatalog Demo",
+  organizationName: "MetaRetail Inc",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/boyney123/eventcatalog-demo/edit/master",
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: "/",
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "MetaRetail Inc",
+  },
+  docs: {
+    sidebar: {
+      // Should the sub heading be rendered in the docs sidebar?
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository
+        copy: [
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    // Payment Team
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository
+        copy: [
+          {
+            // importing content from the payment-team catalog
+            content: 'examples/generator-federation/basic/payment-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the payment-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the payment-team catalog
+            content: 'examples/generator-federation/basic/payment-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the payment-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the payment-team catalog
+            content: 'examples/generator-federation/basic/payment-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the payment-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository
+        copy: [
+          {
+            // importing content from the order-management-team catalog
+            content: 'examples/generator-federation/basic/order-management-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the order-management-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the order-management-team catalog
+            content: 'examples/generator-federation/basic/order-management-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the order-management-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the order-management-team catalog
+            content: 'examples/generator-federation/basic/order-management-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the order-management-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the [EventCatalog Federation plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-federation/basic/central-catalog/eventcatalog.config.js).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/docs/plugins/eventcatalog-federation/03-examples.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Federation plugin
+---
+
+You can find many examples of using the Federation plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Federation Example](https://github.com/event-catalog/generators/tree/main/examples/generator-federation/basic)
+  -  An example of merging multiple catalogs into a single catalog from different teams.

package/dist/docs/plugins/eventcatalog-federation/04-configuration.md

@@ -0,0 +1,193 @@
+---
+keywords:
+- EventCatalog components
+sidebar_label: Configuring main catalog
+title: Setup main catalog
+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" />
+
+EventCatalog Federation is powered by the [EventCatalog Federation Generator](https://github.com/event-catalog/generators), this let's you define the repositories you want to merge into your main catalog.
+
+### Getting started
+
+If you haven't already, you will need to create a new EventCatalog instance that will be your main catalog, this will be the one you will use to generate your documentation and host your documentation for your users.
+
+You can create a new empty EventCatalog instance using the `eventcatalog` CLI.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest main-catalog --empty
+```
+
+Next you will need to install the `federation` generator (in your main catalog).
+
+```bash
+npm install @eventcatalog/generator-federation
+```
+
+#### Configuring the federation generator
+
+You need to configure the federation generator in your main catalog, this is done by adding the generator to the `generators` section of your `eventcatalog.config.js` file.
+
+Using the federation generator you need to specify:
+
+- The source repository to pull from (your teams catalogs)
+- The branch to pull from (default is `main`)
+- The files to copy from the source repository to your main catalog 
+- If you want to override any conflicts (`last-write-wins`)
+- If you want the plugin to error if there are duplicate resources in your main catalog
+
+Here is an example of how you can configure the federation generator.
+ This demo shows:
+
+- Pulling information from a GitHub repository
+- Pulling information from a GitLab repository
+- Copying files from the source repository to your main catalog
+- Overriding any conflicts (`last-write-wins`)
+- Enforcing unique resources in your main catalog
+
+```js
+import path from 'path';
+import url from 'url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: 'fe4efb73-11db-4bea-ad2b-d7e1d424a0c1',
+  title: 'OurLogix',
+  tagline: 'A comprehensive logistics and shipping management company',
+  organizationName: 'OurLogix',
+  homepageLink: 'https://eventcatalog.dev/',
+  landingPage: '',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  trailingSlash: false,
+  base: '/',
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'OurLogix',
+  },
+  docs: {
+    sidebar: {
+      showPageHeadings: true,
+    },
+  },
+  // Add the federation generator to your main catalog
+  generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository (this would be your teams catalogs)
+        source: 'git@github.com:event-catalog/eventcatalog.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository 
+        copy: [
+          { 
+            // specify the path in the external catalog
+            content: 'examples/default/components',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'components')
+          },
+          { 
+            // specify the path in the external catalog
+            content: 'examples/default/domains/Orders/services',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // specify the path in the external catalog
+            content: 'examples/default/teams',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // specify the path in the external catalog
+            content: 'examples/default/domains/Payment/services',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'services')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    [
+      // This example does not specify the files to copy, the plugin will find all the files in the repository and copy them to your main catalog
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitLab repository, it will check for events, queries, domains, services, teams, etc
+        // Any matching files will be copied to your main catalog
+        source: 'git@gitlab.com:boyneyy123/eventcatalog-gitlab-example.git',
+        branch: 'main',
+        destination: path.resolve(__dirname),
+        override: true,
+        enforceUniqueResources: true
+      },
+    ],
+  ],
+};
+
+```
+
+Generator options:
+
+- `source` - The source repository to pull from (required)
+- `branch` - The branch to pull from (default is `main`)
+- `copy` - The files to copy from the source repository to your main catalog (optional, if not specified the plugin will find all the files in the repository and copy them to your main catalog)
+- `override` - If you want to override any conflicts (`last-write-wins`) (default is `false`)
+- `enforceUniqueResources` - If you want the plugin to error if there are duplicate resources in your main catalog (default is `false`). 
+
+If you want to learn more about the federation generator you can read the [EventCatalog Federation Generator documentation](https://github.com/event-catalog/generators).
+
+### Running the generator
+
+You will need a license key to run the generator, you can get a free 14 day trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+Once you have configured the federation generator you can run the generator.
+
+Inside your main catalog run the following command:
+
+```bash
+npm run generate
+```
+
+This will generate the resources from the source repositories and copy them to your main catalog and handle any conflicts if you have configured the generator to do so.
+
+:::tip Combining multiple generators
+EventCatalog offers other plugins including [AsyncAPI](/docs/plugins/asyncapi/intro) and [OpenAPI](/docs/plugins/openapi/intro) plugins. You can combine generators to pull information from multiple sources and generate your documentation.
+:::
+
+### Authentication
+
+The federation generator uses `git` under the hood, so you will need to ensure you have the correct authentication setup for your git provider on the machine you are running the generator on.
+
+### View demo
+
+You can view and run a demo of the federation generator on GitHub.
+
+- [View demo](https://github.com/event-catalog/generators/tree/main/examples/generator-federation/basic)
+
+### Need help or got a question?
+
+If you need help or got a question, please [create an issue](https://github.com/event-catalog/eventcatalog/issues/new) or [join the community on Discord](https://eventcatalog.dev/discord).