@eventcatalog/core 3.35.0 → 3.36.1

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

@@ -0,0 +1,197 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of GraphQL with EventCatalog
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<!-- Table -->
+| Feature | Use cases |
+|---------|-----------|
+| [Mapping operations as queries, mutations, or subscriptions](#mapping-operations-as-queries-mutations-or-subscriptions) | GraphQL distinguishes between queries (read operations), mutations (write operations), and subscriptions (real-time operations). EventCatalog automatically maps these operations from your GraphQL schema to the appropriate message types in your catalog. |
+| [Assign owners to your domains, services and messages](#assign-owners-to-your-domains-services-and-messages) | You can assign owners (teams or individuals) to your GraphQL services and all the messages that are generated from your schema. This helps with accountability and contact information for your APIs. |
+| [Automatic versioning](#automatic-versioning) | When you change versions in your GraphQL schema and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between schema versions. |
+| [Creating draft domains, services and messages](#creating-draft-domains-services-and-messages) | You can create draft domains, services and messages in EventCatalog from your GraphQL schemas. This will be used to mark the resources as draft in EventCatalog. |
+| [Persist markdown](#persist-markdown) | When you generate your GraphQL schemas your markdown on your domains, services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your schemas. |
+| [Displaying schemas](#displaying-schemas) | EventCatalog will document your GraphQL schemas and allow users to download them. Your schema files are versioned alongside your services and messages. |
+
+### Mapping operations as queries, mutations, or subscriptions
+
+GraphQL has three main operation types:
+
+- **Queries**: Read operations that fetch data
+- **Mutations**: Write operations that modify data
+- **Subscriptions**: Real-time operations that listen for data changes
+
+The EventCatalog GraphQL generator automatically maps these operations from your GraphQL schema:
+
+```graphql title="Example GraphQL Schema"
+type Query {
+  getUser(id: ID!): User
+  getAllUsers: [User]
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): User
+  updateUser(id: ID!, input: UpdateUserInput!): User
+  deleteUser(id: ID!): Boolean
+}
+
+type Subscription {
+  userUpdated(id: ID!): User
+  userDeleted: ID
+}
+
+type User {
+  id: ID!
+  name: String!
+  email: String!
+}
+```
+
+When this schema is processed by the GraphQL generator:
+
+- **Queries** like `getUser` and `getAllUsers` will be documented as [queries](/docs/development/guides/messages/queries/introduction)
+- **Mutations** like `createUser`, `updateUser`, and `deleteUser` will be documented as [commands](/docs/development/guides/messages/commands/introduction)
+- **Subscriptions** like `userUpdated` and `userDeleted` will be documented as [events](/docs/development/guides/messages/events/introduction)
+
+Each operation becomes a message in EventCatalog with:
+- The operation name as the message ID
+- The operation description (if provided in schema)
+- Input parameters and return types
+- The operation type (query/mutation/subscription) as a badge
+
+### Assign owners to your domains, services and messages
+
+You can assign owners to your GraphQL services and all generated messages to help with accountability and contact information.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            id: 'User Service',
+            version: '1.0.0',
+            name: 'User Service',
+            summary: 'This is the user service',
+            path: path.join(__dirname, 'graphql-schemas', 'user-service.graphql'),
+            owners: ['team-users', 'john.doe@company.com']
+          },
+        ],
+        domain: {
+          id: 'users',
+          name: 'Users',
+          version: '0.0.1',
+          owners: ['team-platform']
+        },
+      },
+    ],
+  ],
+};
+```
+
+When you assign owners:
+- **Service owners**: Set on the service configuration and apply to the service and all its messages
+- **Domain owners**: Set on the domain configuration and apply to the domain
+
+
+### Automatic versioning
+
+EventCatalog automatically versions your services and messages when you change the version in your configuration:
+
+```js title="eventcatalog.config.js - Version 1.0.0"
+{
+  path: path.join(__dirname, 'schemas', 'user-service.graphql'),
+  id: 'User Service',
+  version: '1.0.0'  // Initial version
+}
+```
+
+```js title="eventcatalog.config.js - Version 1.1.0"
+{
+  path: path.join(__dirname, 'schemas', 'user-service.graphql'),
+  id: 'User Service',
+  version: '1.1.0'  // Updated version
+}
+```
+
+When you update the version and run `npm run generate`:
+
+1. **Service versioning**: The service gets a new version (1.1.0) while keeping the old version (1.0.0)
+2. **Message versioning**: All messages (queries, mutations, subscriptions) get versioned
+3. **Schema versioning**: The GraphQL schema file is versioned and downloadable
+4. **Change tracking**: You can see what changed between versions
+
+This allows you to:
+- Track API evolution over time
+- Maintain backward compatibility documentation
+- Show deprecation timelines
+- Compare schema changes between versions
+
+### Creating draft domains, services and messages
+
+You can mark your GraphQL services as drafts during development:
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'schemas', 'new-feature-service.graphql'),
+            id: 'New Feature Service',
+            version: '0.1.0',
+            draft: true  // Mark as draft
+          },
+        ],
+        domain: { id: 'experimental', name: 'Experimental', version: '0.0.1' },
+      },
+    ],
+  ],
+};
+```
+
+Draft resources:
+- Are marked with a "DRAFT" badge in the UI
+- Can be filtered out from production views
+- Help distinguish between stable and experimental APIs
+- Useful for API development and review processes
+
+### Persist markdown
+
+EventCatalog preserves your custom markdown content when you regenerate from GraphQL schemas:
+
+1. **Initial generation**: GraphQL generator creates default markdown for your services and messages
+2. **Custom additions**: You add custom content, components, or documentation
+3. **Regeneration**: When you run the generator again, your custom content is preserved
+4. **Version updates**: Custom content persists across version changes
+
+This allows you to:
+- Add business context to technical schema definitions
+- Include examples and usage guidelines
+- Add custom MDX components for rich documentation
+- Provide architectural decision records (ADRs)
+- Include troubleshooting guides
+
+### Displaying schemas
+
+EventCatalog displays your GraphQL schemas and makes them downloadable:
+
+1. **Schema visualization**: Your complete GraphQL schema is rendered in the service page
+2. **Operation details**: Each query, mutation, and subscription shows:
+   - Input parameters and types
+   - Return types
+   - Field descriptions
+   - Deprecation notices
+3. **Downloadable schemas**: Users can download the complete GraphQL schema file
+4. **Versioned schemas**: Each version of your service includes its schema version

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

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the GraphQL plugin
+---
+
+You can find many examples of using the GraphQL plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [GraphQL Basic Example](https://github.com/event-catalog/generators/tree/main/examples/generator-graphql/basic)
+  -  A basic example of using the GraphQL plugin to generate a catalog from GraphQL schema files.

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

@@ -0,0 +1,12 @@
+{
+  "label": "GraphQL Plugin",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "graphql",
+    "title": "GraphQL",
+    "description": "GraphQL integration documentation for EventCatalog"
+  }
+}

package/dist/docs/plugins/hookdeck/01-intro.md

@@ -0,0 +1,152 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with Hookdeck plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+[Hookdeck](https://hookdeck.com?ref=eventcatalog-docs) is an event gateway that provides serverless infrastructure, features, tooling to enable the full software development lifecycle of event-driven applications.
+
+Using the EventCatalog Hookdeck plugin you can extract information from Hookdeck to gain further understanding of event sources, destinations, and flows within the Hookdeck platform.
+
+### Core Features
+
+The Hookdeck plugin can provide you with the following features:
+
+- ⭐️ [Generate EventCatalog Services](#generate-services) from Hookdeck Sources and Destinations
+- ⭐️ [Auto-generate EventCatalog Messages](#generate-messages) from Hookdeck Requests and Events
+- ⭐️ [Auto-generate EventCatalog Message Schemas](#generate-schemas) from Hookdeck Requests and Events
+- ⭐️ [Provide insight into Hookdeck Filters](#filtered-messages) by indicating Requests that are received by an EventCatalog Service but are not connected to destination Service.
+
+### How it works
+
+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 Hookdeck plugin queries the [Hookdeck API](https://hookdeck.com/docs/api?ref=eventcatalog-docs) to generate an EventCatalog visualization including Services and Messages. It also generates inferred Message schemas.
+
+The plugin can either be used as a plugin within an EventCatalog instance or as a CLI configured to point to an EventCatalog instance.
+
+
+### Getting started
+
+#### 1. Install the plugin
+
+```sh
+npm i @hookdeck/eventcatalog-generator
+```
+
+#### 2. Configure your generator in your `eventcatalog.config.js` file
+
+```js title="eventcatalog.config.js"
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  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,
+    },
+  },
+  generators: [
+    [
+      "@hookdeck/eventcatalog-generator",
+      {
+        hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+        domain: "Payments",
+        connectionSourcedMatch: "payments-.*",
+        processMaxEvents: 200,
+        logLevel: "debug",
+      },
+    ],
+  ],
+};
+
+```
+
+#### 3. Run the generate command
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```sh
+npm run generate
+```
+
+#### 4. View your catalog
+
+Run your catalog locally to see the changes:
+
+```sh
+npm run dev
+```
+
+![Example](/img/integrations/hookdeck/example.png)
+
+## Hookdeck Concepts
+
+### Sources
+
+A Hookdeck [Source](https://hookdeck.com/docs/sources?ref=eventcatalog-docs) represents any service that makes an HTTP request to Hookdeck. The HTTP requests can be inbound events such as webhooks or asynchronous API calls.
+
+### Destinations
+
+A Hookdeck [Destination](https://hookdeck.com/docs/destinations?ref=eventcatalog-docs) represents the destination for an event to be routed to. A destination can be connected to one or many Sources.
+
+### Connections
+
+[Connections](https://hookdeck.com/docs/connection?ref=eventcatalog-docs) in Hookdeck route an event from a Source to a Destination. Connections can reuse sources and destinations, allowing one event to be routed to multiple destinations.
+
+### Event lifecycle
+
+The following represent different stages of the lifecycle of an event within Hookdeck:
+
+- [Requests](https://hookdeck.com/docs/requests?ref=eventcatalog-docs): An HTTP request received by a Source URL defined within Hookdeck, such as a webhook.
+- [Events](https://hookdeck.com/docs/events?ref=eventcatalog-docs): An outbound event payload that Hookdeck has queued for delivery.
+- [Attempts](https://hookdeck.com/docs/attempts?ref=eventcatalog-docs): An HTTP delivery attempt to the URL defined by a Destination.
+
+## Features
+
+### Generate EventCatalog Services {#generate-services}
+
+The Hookdeck plugin generates EventCatalog Services from Sources and Destinations that are used within defined Hookdeck Connections. The Sources and Destinations that have Services created can be filtered using the `connectionSourcedMatch` configuration option which performs a regular expression match on the connection source name.
+
+### Auto-generate EventCatalog Messages {#generate-message}
+
+EventCatalog Messages are generated for Requests received by a Source and Events received by a Destination. The number of Hookdeck Request and Events to have EventCatalog Messages generated can be set using the `processMaxEvents` configuration option.
+
+By default, the plugin search for a `type` or `eventType` property on the event payload to uniquely identify a Request or Event type. If the property cannot be found, each Request or Event is treated as a unique Message within EventCatalog.
+
+### Auto-generate EventCatalog Message Schemas {#generate-schemas}
+
+Hookdeck does not presently support schemas. Therefore, a Message schema can only be inferred from an event payload. The Hookdeck EventCatalog plugin generates inferred schemas for the first instance of an Event type and Request type it processes.
+
+### Provide insight into Hookdeck Filters {#filtered-messages}
+
+Hookdeck supports the ability to [filter events](https://hookdeck.com/docs/filters?ref=eventcatalog-docs) based on header or body contents. This can result in Sources receiving Requests but not Events being generated. EventCatalog's visual representation help you identify where events are being entirely filtered out and not delivered to any destination service.
+
+## Commercial Use
+
+This plugin is free to use for commercial use.
+
+## Source
+
+https://github.com/hookdeck/eventcatalog-generator
+
+## Issues
+
+If you have any problems or feature requests please raise them on GitHub: https://github.com/hookdeck/eventcatalog-generator/issues
+

package/dist/docs/plugins/hookdeck/02-api.md

@@ -0,0 +1,133 @@
+---
+sidebar_position: 2
+keywords:
+  - components
+sidebar_label: Generator configuration
+title: Hookdeck Generator API
+description: Getting started with Hookdeck plugin
+---
+
+## Overview {#overview}
+
+API for the EventCatalog Hookdeck generator.
+
+**Example eventcatalog.config.js file**
+
+```js title="eventcatalog.config.js"
+export default {
+  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,
+    },
+  },
+  generators: [
+    [
+      "@hookdeck/eventcatalog-generator",
+      {
+        hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+        domain: "Payments",
+        connectionSourcedMatch: "payments-.*",
+        processMaxEvents: 200,
+        logLevel: "debug",
+      },
+    ],
+  ],
+};
+
+```
+
+## Required fields {#required-fields}
+
+### `hookdeckApiKey` {#hookdeckApiKey}
+
+- Type: `String`
+
+Hookdeck Project API Key to generate an EventCatalog visualization from.
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+  },
+],
+```
+
+## Optional fields {#optional-fields}
+
+### `domain` {#domain}
+
+The domain you want the services be associated with in your catalog.
+
+- Type: `String`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    domain: "Payments",
+  },
+],
+```
+
+### `connectionSourcedMatch` {#connectionSourcedMatch}
+
+Regular expression match for Source names on Connections.
+
+- Type: `String`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    connectionSourcedMatch: "payments-.*",
+  },
+],
+```
+
+### `processMaxEvents` {#processMaxEvents}
+
+The maximum number of Requests/Events to process per Source/Destination
+
+- Type: `Integer`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    processMaxEvents: 200,
+  },
+],
+```
+
+### `logLevel` {#logLevel}
+
+The level to log at.
+
+- Type: `fatal` | `error` | `warn` | `info` | `debug` | `trace`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    logLevel: "debug",
+  },
+],
+```

package/dist/docs/plugins/hookdeck/03-cli.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 3
+keywords:
+  - components
+sidebar_label: Generator CLI
+title: Hookdeck Generator CLI
+description: Getting started with Hookdeck plugin as a CLI
+---
+
+## Overview {#overview}
+
+The Hookdeck EventCatalog plugin can be run as a CLI.
+
+## Run the generator as a CLI
+
+```sh
+npx @hookdeck/eventcatalog-generator {flags}
+```
+
+Supported flags are:
+
+- `dir`: **Required**. Path the the EventCatalog install directory
+- `api-key`: **Required**. Hookdeck Project API Key
+- `log-level`: The level to log at - "fatal" | "error" | "warn" | "info" | "debug" | "trace"
+- `match`: Regular expression match for Source names on Connections
+- `max-events`: The maximum number of Requests/Events to process per Source/Destination
+
+Example:
+
+```sh
+npx @hookdeck/eventcatalog-generator \
+    --dir ./path/to/eventcatalog/install \
+    --api-key {HOOKDECK_API_KEY} \
+    --log-level debug \
+    --match "stripe-production" \
+    --domain Payments \
+    --max-events 200
+```
+
+The CLI will also use the following environment variables:
+
+- `PROJECT_DIR`: Path the the EventCatalog install directory
+- `HOOKDECK_PROJECT_API_KEY`: Hookdeck Project API Key
+
+The environment variables can be within a `.env` file that will automatically be detected.

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

@@ -0,0 +1,11 @@
+{
+  "label": "Hookdeck Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "hookdeck",
+    "title": "Hookdeck",
+    "description": "Hookdeck integration with EventCatalog"
+  }
+}

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

@@ -0,0 +1,78 @@
+---
+sidebar_position: 1
+keywords:
+  - components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with OpenAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<AddedIn version="2.6.0"/>
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/E6cXxQXH49k?si=1IfHfIvrOLxIy3DF" 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>
+
+---
+
+The [OpenAPI specification](https://swagger.io/specification/) is a widely-adopted standard for defining and describing RESTful APIs in a structured, machine-readable format. It provides a way to document APIs, including the endpoints, parameters, request and response formats, authentication methods, and more, making it easier for both humans and machines to understand and interact with the API.
+
+Using the EventCatalog OpenAPI generator you can automate and generate your EventCatalog.
+
+:::tip Try it now
+Want to see what your OpenAPI file looks like in EventCatalog? [Try the playground](https://try.eventcatalog.dev) — drop your file and see the result in seconds.
+:::
+
+### Core Features
+
+The EventCatalog OpenAPI plugin can provide you with many features:
+
+- ⭐️ Generate domains, services and messages into your catalog from your OpenAPI specification files
+- ⭐️ [Assign owners (your teams) to your services and messages all generated by your OpenAPI files](/docs/plugins/openapi/features#assign-owners-to-your-domains-services-and-messages)
+- ⭐️ [Automate your EventCatalog and fetch OpenAPI files by URL](/docs/plugins/openapi/features#fetch-openapi-files-by-url)
+- ⭐️ [Map commands, queries and events from your OpenAPI file using custom extensions](/docs/plugins/openapi/features#mapping-messages-as-commands-queries-or-events)
+- ⭐️ [Add semantic meaning to your OpenAPI files, persist this meaning between versions](/docs/plugins/openapi/features#persist-markdown)
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your OpenAPI versions](#automatic-versioning)
+- ⭐️ [Render and display your OpenAPI specification in EventCatalog](/docs/plugins/openapi/intro)
+- ⭐️ Display your endpoints and parameters in the catalog
+- ⭐️ Ability to download your schemas and OpenAPI files (also versioned)
+- ⭐️ Ability to draft services and endpoints in EventCatalog from your OpenAPI files
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/openapi/openapi.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 OpenAPI plugin let's you define 1 or many OpenAPI files. When running the generate command the scripts populate your EventCatalog. You can choose how your OpenAPI services are added to EventCatalog and which domain they belong to.
+
+
+
+## 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 OpenAPI 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.