@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/plugins/aws-glue-registry/03-api.md

@@ -0,0 +1,282 @@
+---
+sidebar_position: 5
+keywords:
+- api
+sidebar_label: API Reference
+title: API Reference
+description: Complete API reference for AWS Glue Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Configuration Options
+
+### Required Configuration
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `region` | `string` | AWS region where your schema registry is located |
+| `registryName` | `string` | Name of the AWS Glue Schema Registry |
+
+### Optional Configuration
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `registryArn` | `string` | `undefined` | ARN of the registry (for cross-account access) |
+| `services` | `Service[]` | `[]` | Array of service definitions to map schemas to |
+| `domain` | `Domain` | `undefined` | Domain configuration for organizing services |
+| `credentials` | `AwsCredentials` | `undefined` | Custom AWS credentials |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `format` | `'md' \| 'mdx'` | `'mdx'` | Output file format |
+| `writeFilesToRoot` | `boolean` | `false` | Write files to root instead of service directories |
+
+## Type Definitions
+
+### Service
+
+Defines a service and which schemas it produces/consumes.
+
+```typescript
+type Service = {
+  id: string;           // Unique service identifier
+  version: string;      // Service version
+  sends?: Filter[];     // Schemas this service produces
+  receives?: Filter[];  // Schemas this service consumes
+}
+```
+
+### Filter
+
+Defines criteria for matching schemas to services.
+
+```typescript
+type Filter = {
+  schemaName?: string | string[];    // Exact schema name matching
+  prefix?: string | string[];        // Schema name starts with
+  suffix?: string | string[];        // Schema name ends with  
+  includes?: string | string[];      // Schema name contains
+  dataFormat?: string | string[];    // Schema format (AVRO, JSON, PROTOBUF)
+  tags?: Record<string, string>;     // AWS tags key-value pairs
+}
+```
+
+#### Filter Examples
+
+```js
+// Exact name matching
+{ schemaName: 'CustomerCreated' }
+{ schemaName: ['CustomerCreated', 'CustomerUpdated'] }
+
+// Prefix matching
+{ prefix: 'Customer' }
+{ prefix: ['Customer', 'User'] }
+
+// Suffix matching  
+{ suffix: 'Created' }
+{ suffix: ['Created', 'Updated'] }
+
+// Contains matching
+{ includes: 'customer' }
+{ includes: ['customer', 'user'] }
+
+// Format matching
+{ dataFormat: 'AVRO' }
+{ dataFormat: ['AVRO', 'JSON'] }
+
+// Tag matching (ALL tags must match)
+{ tags: { team: 'customer' } }
+{ tags: { team: 'customer', env: 'prod' } }
+
+// Combined filters (ALL criteria must match)
+{
+  prefix: 'Customer',
+  dataFormat: 'AVRO', 
+  tags: { env: 'prod' }
+}
+```
+
+### Domain
+
+Defines a domain for organizing related services.
+
+```typescript
+type Domain = {
+  id: string;      // Unique domain identifier
+  name: string;    // Display name for the domain
+  version: string; // Domain version
+}
+```
+
+### AWS Credentials
+
+Custom AWS credentials (use environment variables when possible).
+
+```typescript
+type AwsCredentials = {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;  // For temporary credentials
+}
+```
+
+## Complete Configuration Example
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        // Required
+        region: 'us-east-1',
+        registryName: 'my-event-registry',
+        
+        // Optional - Cross-account access
+        registryArn: 'arn:aws:glue:us-east-1:123456789012:registry/shared-registry',
+        
+        // Optional - Custom credentials (not recommended)
+        credentials: {
+          accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        },
+        
+        // Optional - Domain organization
+        domain: {
+          id: 'ecommerce',
+          name: 'E-commerce Platform',
+          version: '1.0.0'
+        },
+        
+        // Optional - Service mapping
+        services: [
+          {
+            id: 'Customer Service',
+            version: '1.0.0',
+            sends: [
+              { prefix: 'Customer' },
+              { tags: { team: 'customer' } }
+            ],
+            receives: [
+              { schemaName: ['OrderPlaced', 'PaymentProcessed'] },
+              { includes: 'notification' }
+            ]
+          },
+          {
+            id: 'Order Service',
+            version: '1.0.0', 
+            sends: [
+              { prefix: 'Order' },
+              { dataFormat: 'AVRO' }
+            ],
+            receives: [
+              { suffix: ['Created', 'Updated'] },
+              { tags: { env: 'prod', type: 'input' } }
+            ]
+          }
+        ],
+        
+        // Optional - Output configuration
+        format: 'mdx',
+        writeFilesToRoot: false,
+        debug: true
+      },
+    ],
+  ],
+}
+```
+
+## Schema Matching Logic
+
+### Filter Evaluation
+
+When a schema is evaluated against a filter:
+
+1. **Within a filter object**: ALL criteria must match (AND logic)
+2. **Between filter objects**: ANY filter can match (OR logic)  
+3. **Within array values**: ANY value can match (OR logic)
+
+### Examples
+
+```js
+// Schema must start with 'Customer' AND be AVRO format AND have team=customer tag
+{
+  prefix: 'Customer',
+  dataFormat: 'AVRO',
+  tags: { team: 'customer' }
+}
+
+// Schema must contain 'order' OR 'customer' OR 'payment'
+{
+  includes: ['order', 'customer', 'payment']
+}
+
+// Multiple filters - schema matches if it satisfies ANY filter
+sends: [
+  { prefix: 'Customer' },      // OR
+  { tags: { team: 'orders' } } // OR  
+  { dataFormat: 'AVRO' }       // OR
+]
+```
+
+### Priority and Precedence
+
+1. More specific filters take precedence over general ones
+2. Exact `schemaName` matches have highest priority
+3. Combined filters are more specific than single criteria
+4. Schema can only be assigned to one service per filter match
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `AccessDenied` | Insufficient IAM permissions | Check IAM policy has required Glue permissions |
+| `RegistryNotFound` | Registry doesn't exist | Verify registry name and region |
+| `InvalidCredentials` | AWS credentials invalid | Check AWS credential configuration |
+| `SchemaNotFound` | Schema was deleted | Re-run generator to sync with current state |
+
+### Debug Mode
+
+Enable debug mode to troubleshoot issues:
+
+```js
+{
+  debug: true,
+  // ... other config
+}
+```
+
+This will output detailed information about:
+- Schemas being fetched
+- Filter matching results  
+- Service assignments
+- File generation progress
+
+## AWS Permissions Required
+
+The plugin requires these IAM permissions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "glue:ListSchemas",
+        "glue:GetSchema", 
+        "glue:GetSchemaVersion",
+        "glue:GetTags"
+      ],
+      "Resource": [
+        "arn:aws:glue:*:*:registry/*",
+        "arn:aws:glue:*:*:schema/*/*"
+      ]
+    }
+  ]
+}
+```
+
+For cross-account access, additional permissions may be required on the target account's registry.

package/dist/docs/plugins/aws-glue-registry/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "AWS Glue Schema Registry Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "aws-glue-schema-registry",
+    "title": "AWS Glue Schema Registry",
+    "description": "AWS Glue Schema Registry integration documentation for EventCatalog"
+  }
+}

package/dist/docs/plugins/azure-schema-registry/00-intro.md

@@ -0,0 +1,92 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with Azure Schema Registry plugin
+---
+
+<!-- import PluginLicense from '@site/src/components/MDX/PluginLicense'; -->
+
+<!-- <PluginLicense url="#commercial-use" /> -->
+
+---
+
+
+The [EventCatalog Azure Schema Registry plugin](https://github.com/event-catalog/generators/tree/main/packages/generator-azure-schema-registry) allows you to import schemas from Azure Schema Registry into EventCatalog and keep them in sync alongside your documentation. 
+
+<iframe width="100%" height="515" src="https://www.youtube.com/embed/rNDa2JDyr_A?si=uFAbZbAiAxiy9dqJ" 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>
+
+
+:::info
+**What is Azure Schema Registry?**: A schema registry for Azure Event Hubs. Use this to store and manage your schemas for event-driven applications. You can read more about it on the [Microsoft Learn website](https://learn.microsoft.com/en-us/azure/event-hubs/schema-registry-overview).
+:::
+
+### Why use EventCatalog with Azure Schema Registry?
+
+The EventCatalog Azure Schema Registry plugin can provide you with many features, including:
+
+- Keep your schemas in sync with your architecture documentation
+- Automatic versioning; as your schemas change they are versioned in EventCatalog alongside your documentation
+- Understand how your schemas have evolved over time with the Schema diff explorer with the [Schema Explorer](/docs/development/guides/schemas/schema-explorer)
+- Add meaning (markdown) to your schemas. Provide business context to your schemas and add value
+- Quickly find who is producing or consuming your schemas
+- Visualize your Azure Event Hubs architecture with the [EventCatalog Visualizer](/features/visualization)
+- Download and view schemas in EventCatalog (Avro, JSON Schema) or through the [Schema API](/docs/development/guides/schemas/schema-api)
+- Use [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) to get schemas for your LLMs
+
+### How it works
+
+1. Install the Azure Schema Registry plugin
+1. Configure the plugin (schemas, services, domains, message types)
+1. Get an Azure access token using Azure CLI: `az account get-access-token --resource https://eventhubs.azure.net`
+1. Set the token as an environment variable: `AZURE_SCHEMA_REGISTRY_TOKEN`
+1. Run the plugin to import your schemas into EventCatalog
+1. View and deploy your catalog
+
+<!-- ![Example](/img/integrations/azure-schema-registry/azure-example.png) -->
+
+**What are generators?**
+
+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 Azure Schema Registry plugin is a generator. It will import your schemas from your Azure Schema Registry into EventCatalog.
+
+## Authentication
+
+The plugin uses Azure's REST API with Bearer token authentication. You need to provide an Azure access token via the `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable.
+
+:::info Why use the REST API vs the Azure SDK?
+
+The schema registry SDK is limiting and doesn't allow you to fetch all schemas from a registry. It also doesn't allow you to fetch schemas from multiple registries in one configuration.
+
+We use the REST API because it is simpler and more flexible. It doesn't require you to install any Azure SDK packages and works seamlessly across different environments without requiring any code changes.
+
+:::
+
+## 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`._
+
+## License FAQ
+
+### What is the license key for?
+The license key is required to use the Azure Schema Registry 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.