@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/plugins/github/02-plugin-configuration.md

@@ -0,0 +1,253 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GitHub plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog GitHub plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog GitHub plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+
+## Required Configuration Options
+
+| Option | Type | Required | Example | Description |
+|--------|------|----------|---------|-------------|
+| `source` | `string` | Yes | `https://github.com/event-catalog/eventcatalog.git` | The HTTP or SSH URL of the GitHub repository. |
+| `path` | `string` | Yes | `examples/default` | The path to the directory in the repository that contains the schemas. |
+
+
+## Optional Configuration Options
+
+<AddedIn version="1.0.0" pkg="@eventcatalog/generator-github" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+### Authentication
+
+| Option | Type | Required | Example | Description |
+|--------|------|----------|---------|-------------|
+| `token` | `string` | No | `process.env.MY_GITHUB_TOKEN` | GitHub personal access token or GitHub App installation token for private repository access. Can also be set via `EVENTCATALOG_GITHUB_TOKEN` environment variable. |
+
+<details>
+<summary>See an example configuration - Private repository authentication</summary>
+
+Access private repositories by providing a GitHub token.
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/your-org/private-repo',
+      path: 'schemas',
+      token: process.env.GITHUB_TOKEN,
+      messages: [
+        {
+          id: 'order-placed',
+          schemaPath: 'order-placed.avro',
+          type: 'event',
+        },
+      ]
+    }
+  ]
+]
+```
+</details>
+
+### Messages
+
+You can assign schemas to messages (events, commands, or commands) in EventCatalog.
+
+:::tip Documentation
+Remember the GitHub plugin will keep your schemas in sync with your messages. Any documentation (markdown) added to your messages will be persisted between imports and versions.
+:::
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `messages` | object | - | - | List of messages to assign the schemas to. |
+| `messages.id` | string | Yes | - | EventCatalog ID for the message. |
+| `messages.name` | string | No | - | Friendly name of the message, if not provided the message id will be used. |
+| `messages.version` | string | No | - | Version of the message, recommended you set this to the version of the message in the repository, Defaults to `1`. |
+| `messages.schemaPath` | string | Yes | - | The path to your schema file in the repository, relative to the path configured in the `path` option. For example if `path` is `examples/default` and your `schemaPath` is `/schemas/order-placed.avro`, the path used will be `examples/default/schemas/order-placed.avro`. |
+| `messages.type` | string | Yes | - | Type of the message (`event`, `command`, or `query`). |
+
+<details>
+<summary>See an example configuration - Assign schemas to messages</summary>
+
+In this example we assign schemas to messages.
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/event-catalog/eventcatalog.git',
+      path: 'examples/default',
+      messages: [
+        {
+          id: 'order-placed',
+          name: 'Order Placed',
+          version: '1',
+          schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
+          type: 'event',
+        }, 
+        {
+          id: 'update-order',
+          name: 'Update Order',
+          version: '1',
+          schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
+          type: 'command',
+        }, 
+      ]
+    }
+  ]
+]
+```
+</details>
+
+### Services
+
+You can assign your schemas to your producers and consumers (services).
+
+:::tip Documentation
+Remember the GitHub plugin will keep your schemas in sync with your services. Any documentation (markdown) added to your services will be persisted between imports and versions.
+:::
+
+
+| Option | Type | Default | Required | Description |
+|--------|------|---------|----------|-------------|
+| `services` | object | - | Yes | List of producers/consumers (services) to assign the schemas to. |
+| `services.id` | string | - | Yes | EventCatalog ID for the service. |
+| `services.sends` | Message[] | - | No | Configuration to assign schemas to a producer. The schemas and topic defined here will be assigned to the producer. |
+| `services.receives` | Message[] | - | No | Configuration to assign schemas to a consumer. The schemas and topic defined here will be assigned to the consumer. |
+
+<details>
+<summary>See an example configuration - Assign schemas to producers and consumers</summary>
+
+In this example we assign schemas to producers and consumers (services).
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/event-catalog/eventcatalog.git',
+      path: 'examples/default',
+      services: [
+        {
+          id: 'Orders Service',
+          // The order service sends these messages...
+          sends: [
+            {
+              id: 'order-placed', 
+              name: 'Order Placed',
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
+              type: 'event',
+            }
+          ],
+          // The order service receives these messages...
+          receives: [{
+            {
+              id: 'place-order', 
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
+              type: 'command',
+            }
+          }]
+        }
+      ]
+    }
+  ]
+]
+```
+
+</details>
+
+### Domains
+
+You can define and assign domains to your services.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain.id` | string | - | EventCatalog ID for the domain (e.g `orders-domain`). |
+| `domain.name` | string | - | Name of the domain (e.g `Orders Domain`). |
+| `domain.version` | string | - | Version of the domain (e.g `1.0.0`). |
+
+<details>
+<summary>See an example configuration - Assign a domain to a service</summary>
+
+In this example we assign a domain to a service.
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    { 
+      source: 'https://github.com/event-catalog/eventcatalog.git',
+      path: 'examples/default',
+      services: [
+        {
+          id: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-placed',
+              name: 'Order Placed',
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
+              type: 'event',
+            }
+          ],
+          receives: [
+            {
+              id: 'place-order',
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
+              type: 'command',
+            }
+          ]
+        }
+      ],
+      // The list of services are assigned to this domain
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      }
+    }
+  ]
+]
+```
+
+</details>
+
+
+## Need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord)
+or refer to the [Github Plugin examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-github).
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/docs/plugins/github/03-features.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of the Github Plugin with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Adding semantic meaning to schemas
+
+Using the Github plugin with EventCatalog, you can import and keep your schemas in Sync with your documentation.
+
+When you import a schema into EventCatalog the schema will be mapped to your event, query or command. The schema (any format, e.g JSON, Avro, Protobuf) will be stored against the message in EventCatalog. 
+
+Each message (command, event, query) has their own `index.mdx` file. This is the place you can write your documentation for the message. Everytime you reimport your schemas, your documentation will be preserved.
+
+This pattern gives you the flexibility to add business meaning to your messages and make them easier to understand for teams whilst keeping your schemas up to date and in sync with the real world.
+
+### Visualize producers, consumers and your schemas.
+
+When you import your schemas into EventCatalog you can assign them to producers and consumers.
+
+After the import process, you can use the EventCatalog Visualizer ([see demo](https://demo.eventcatalog.dev/visualiser/domains/E-Commerce/1.0.0)) to see exactly how your messages, producers and consumers are mapped.
+
+![Example Image](./images/visualizer.png)
+
+### Downloading schemas
+
+EventCatalog supports any schema format (e.g avro, json, protobuf, etc). When you import your schemas into EventCatalog users can view and download the schema directly from EventCatalog.
+
+You can use the [Schema](/docs/development/components/components/schema) or [SchemaViewer](/docs/development/components/components/schema-viewer) components in your markdown to display them in your documentation.
+
+### Missing a feature?
+
+If you are missing a feature, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
+
+### Example
+
+See the [eventcatalog-github-example](https://github.com/event-catalog/generators/tree/main/examples/generator-github) for a working example.

package/dist/docs/plugins/github/04-examples.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Github plugin
+---
+
+You can find many examples of using the Github plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Basic example](https://github.com/event-catalog/generators/tree/main/examples/generator-github/basic)
+  - An example of using the Github plugin to pull schemas from GitHub and assign them to events, queries and commands.
+- [Import all schemas and assign them to producers and consumers](https://github.com/event-catalog/generators/tree/main/examples/generator-github/assign-schemas-to-producers-and-consumers) 
+  - An example of using the Github plugin to pull schemas from GitHub and assign them to producers and consumers (Services).

package/dist/docs/plugins/github/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "GitHub Plugin",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "github",
+    "title": "GitHub",
+    "description": "GitHub integration for EventCatalog"
+  }
+}

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

@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with GraphQL plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/J352QYLWQkw?si=hwwKr-k2IENfICmR" 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>
+
+---
+
+[GraphQL](https://graphql.org/) is a query language and runtime for APIs that provides a complete and understandable description of the data in your API. It gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
+
+Using the EventCatalog GraphQL generator you can generate and maintain your EventCatalog from your GraphQL schema files. 
+
+### Core Features
+
+The EventCatalog GraphQL plugin can provide you with many features:
+
+- ⭐️ Generate domains, services and messages into your catalog from your GraphQL schema files
+- ⭐️ [Map queries, mutations and subscriptions from your GraphQL schema](/docs/plugins/graphql/features#mapping-operations-as-queries-mutations-or-subscriptions)
+- ⭐️ [Assign owners (your teams) to your services and messages all generated by your GraphQL schemas](/docs/plugins/graphql/features#assign-owners-to-your-domains-services-and-messages)
+- ⭐️ [Add semantic meaning to your GraphQL schemas, persist this meaning between versions](/docs/plugins/graphql/features#persist-markdown)
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your GraphQL schema versions](#automatic-versioning)
+- ⭐️ [Display your GraphQL schemas and operations in the catalog](#displaying-schemas)
+- ⭐️ Ability to download your schemas and GraphQL files (also versioned)
+- ⭐️ Ability to draft services and operations in EventCatalog from your GraphQL schemas
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/graphql/graphql.png)
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog GraphQL plugin let's you generate your catalog from one or more GraphQL schema files.
+
+Your GraphQL schemas are parsed and transformed into services, domains and messages in your catalog.
+
+This let's you visualize your architecture, assign owners to your services and much more.
+
+## 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.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The license key is required to use the GraphQL 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/graphql/01-installation.md

@@ -0,0 +1,144 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GraphQL
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog GraphQL plugin
+---
+
+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 GraphQL plugin is used to generate EventCatalog resources (e.g domains, services and messages) from your GraphQL schema files.
+
+## Installation
+
+Run the command below to install the EventCatalog GraphQL plugin.
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-graphql
+```
+  </TabItem>
+</Tabs>
+
+:::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.
+:::
+
+#### Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  // Add single GraphQL schema to a domain
+  [
+    '@eventcatalog/generator-graphql',
+    {
+      services: [
+        // Point to a local GraphQL schema file, we assign it to the service "User Service", the service has a version of 1.0.0
+        { path: path.join(__dirname, 'graphql-schemas', 'user-service.graphql'), id: "User Service", version: "1.0.0"}
+      ],
+      // The services are assigned to the domain "Users"
+      domain: { id: 'users', name: 'Users', version: '0.0.1' },
+    },
+  ],
+  // Add many GraphQL schemas to a domain
+  [
+    '@eventcatalog/generator-graphql',
+    {
+      services: [
+        // Orders service
+        { path: path.join(__dirname, 'graphql-schemas', 'order-service.graphql'), id: "Order Service", version: "1.0.0"}
+        // Payment service
+        { path: path.join(__dirname, 'graphql-schemas', 'payment-service.graphql'), id: "Payment Service", version: "1.0.0"}
+      ],
+      // We add the orders and payment services to the domain "Shopping"
+      domain: { id: 'shopping', name: 'Shopping', version: '0.0.1' },
+    },
+  ],
+],
+};
+
+```
+
+### Configure license key
+
+The EventCatalog GraphQL 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)
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_GRAPHQL=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_GRAPHQL=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 GraphQL plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_GRAPHQL
+      },
+    ],
+  ],
+};
+```
+
+#### 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 plugin
+
+_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
+```
+
+## 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/graphql/02-plugin-configuration.md

@@ -0,0 +1,127 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GraphQL plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog GraphQL plugin
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog GraphQL plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `services` | `Service[]` | Yes | List of GraphQL schema files to add to your catalog, and the service name and version |
+| `licenseKey` | string | Yes* | License key for the plugin. Get a 14-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via `EVENTCATALOG_LICENSE_KEY_GRAPHQL` environment variable. |
+
+### Service Configuration
+
+Each service in the `services` array requires the following properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | EventCatalog ID for the service. This is required and must be unique. |
+| `path` | string | Yes | Path to your GraphQL schema file |
+| `version` | string | Yes | Version of the service. _EventCatalog resources are versioned, you must specify a version for the service._|
+| `owners` | string[] | No | Owners of the service. You can assign EventCatalog users or teams to services. Setting owners on the service will also set the owners of the messages in the GraphQL schema. If owners are already set on any resource, those owners are persisted. |
+| `name` | string | No | Display name for the service. If not provided, the `id` will be used. |
+| `summary` | string | No | Short summary of the service. |
+| `generateMarkdown` | function | - | Function to override the default markdown generation for the service. See [Markdown templates](#markdown-templates) for more information. |
+| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service writes to. (Added in v0.4.4) |
+| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service reads from. (Added in v0.4.0) |
+
+## Optional Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain` | object | - | Domain to associate all configured services with |
+| `domain.id` | string | - | Domain identifier |
+| `domain.name` | string | - | Domain display name |
+| `domain.version` | string | - | Domain version |
+| `domain.owners` | string[] | - | Owners of the domain. If owners are already set on the domain, those owners are persisted. |
+| `domain.markdown` | string | - | Custom markdown content for the domain. |
+| `messages.generateMarkdown` | function | - | Function to override the default markdown generation for the message. See [Markdown templates](#markdown-templates) for more information. |
+| `writeFilesToRoot` | boolean | `false` | Write GraphQL messages to root instead of service folder. By default all domains, services and messages will be grouped in the folder directory structure. |
+
+## 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: "GraphQL API Catalog",
+  tagline: "Your GraphQL API Documentation",
+  organizationName: "Your Organization",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/your-org/your-catalog/edit/master",
+  trailingSlash: false,
+  base: "/",
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "Your Organization",
+  },
+  docs: {
+    sidebar: {
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            id: 'User Service',
+            version: '1.0.0',
+            name: 'User Service',
+            path: path.join(__dirname, 'graphql-schemas', 'user-service.graphql'),
+            owners: ['team-users']
+          },
+          {
+            id: 'Order Service',
+            version: '1.2.0',
+            name: 'Order Service',
+            path: path.join(__dirname, 'graphql-schemas', 'order-service.graphql'),
+            owners: ['team-orders']
+          },
+        ],
+        domain: { id: 'ecommerce', name: 'E-commerce', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            id: 'Analytics Service',
+            version: '3.0.0',
+            name: 'Analytics Service',
+            path: path.join(__dirname, 'graphql-schemas', 'analytics-service.graphql'),
+            draft: true
+          },
+        ],
+        domain: { id: 'analytics', name: 'Analytics', version: '0.0.1' },
+        debug: true
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the [EventCatalog GraphQL plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-graphql/basic/eventcatalog.config.js).
+