@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/owners/03-create-user.md

@@ -0,0 +1,99 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog users
+sidebar_label: Create a user
+title: Create a user
+description: Create and manage users within EventCatalog.
+---
+
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A user represents a person who owns, maintains, or can answer questions about resources in your architecture.
+
+![Example user page](../img/users/example.png)
+
+## Adding a new user
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog user">
+Read https://www.eventcatalog.dev/docs/development/guides/owners/create-user.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/users.md then help me create a new EventCatalog user in my catalog.
+
+Ask me for the user id, name, role, email, avatar URL if known, Slack or Microsoft Teams contact URL if known, and any teams they belong to. Then create the correct users/{'{user-id}'}.mdx file with frontmatter and starter markdown.
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can create the user file and add the right ownership/contact metadata.
+
+### Manual Creation
+
+Users live in the `/users` folder.
+
+Create one `.mdx` file for each user.
+
+<ProjectTree
+  items={[
+    {
+      name: 'users',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'dboyne.mdx', highlight: true }],
+    },
+  ]}
+/>
+
+## Create the user file
+
+Create a user file with frontmatter and markdown content.
+
+```md title="/users/dboyne.mdx"
+---
+# id of the user, used for references from resources
+id: dboyne
+
+# display name for the user
+name: David Boyne
+
+# optional URL path for a profile image
+avatarUrl: https://github.com/dboyne.png
+
+# user's role in the company
+role: Lead developer
+
+# optional user email address
+email: david@example.com
+
+# optional Slack URL to contact the user
+slackDirectMessageUrl: https://yourteam.slack.com/team/dboyne
+
+# optional teams this user belongs to
+associatedTeams:
+  - payments-platform
+---
+
+## Overview
+
+David works on platform architecture and helps teams document their event-driven systems.
+```
+
+Once the file is added, the user appears in EventCatalog and can be referenced by resources or teams.
+
+## Add users to teams
+
+Teams can reference users in their `members` array:
+
+```md title="/teams/payments-platform.mdx"
+---
+id: payments-platform
+name: Payments Platform
+members:
+  - dboyne
+---
+```
+
+## Next steps
+
+- [Create a team](/docs/development/guides/owners/create-team)
+- [Review the users reference](/docs/development/guides/owners/users-reference)
+- [Sync users from external systems](/docs/development/guides/owners/automated-teams-and-users)

package/dist/docs/development/guides/owners/05-teams-reference.md

@@ -0,0 +1,144 @@
+---
+keywords:
+- EventCatalog teams
+- Team frontmatter
+sidebar_position: 4
+sidebar_label: Teams reference
+title: Teams reference
+description: Frontmatter fields and paths for teams in EventCatalog.
+---
+
+This page lists the fields and paths supported by teams.
+
+## Paths
+
+Teams are created in the `teams` folder:
+
+```txt
+/teams/{team-id}.mdx
+```
+
+Teams can also be synced from directory sources such as GitHub or Microsoft Entra.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/teams/{team-id}` | Team documentation page. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the team. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: payments-platform
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the team.
+
+```md title="Example"
+---
+name: Payments Platform
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the team.
+
+```md title="Example"
+---
+summary: Owns payment processing and refund workflows.
+---
+```
+
+### `email` {#email}
+
+- Type: `string`
+
+Team email address.
+
+```md title="Example"
+---
+email: payments@example.com
+---
+```
+
+### `hidden` {#hidden}
+
+- Type: `boolean`
+
+Hide the team from generated lists.
+
+```md title="Example"
+---
+hidden: true
+---
+```
+
+### `slackDirectMessageUrl` {#slackDirectMessageUrl}
+
+- Type: `string`
+
+Slack URL for contacting the team.
+
+```md title="Example"
+---
+slackDirectMessageUrl: https://slack.example.com/team/payments
+---
+```
+
+### `msTeamsDirectMessageUrl` {#msTeamsDirectMessageUrl}
+
+- Type: `string`
+
+Microsoft Teams URL for contacting the team.
+
+```md title="Example"
+---
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/channel/example
+---
+```
+
+### `members` {#members}
+
+- Type: `array`
+
+Users that belong to the team.
+
+```md title="Example"
+---
+members:
+  - dboyne
+---
+```
+
+## Example
+
+```md
+---
+id: payments-platform
+name: Payments Platform
+summary: Owns payment processing and refund workflows.
+members:
+  - dboyne
+ownedServices:
+  - payment-api
+ownedEvents:
+  - PaymentAuthorized
+---
+```

package/dist/docs/development/guides/owners/06-users-reference.md

@@ -0,0 +1,128 @@
+---
+keywords:
+- EventCatalog users
+- User frontmatter
+sidebar_position: 5
+sidebar_label: Users reference
+title: Users reference
+description: Frontmatter fields and paths for users in EventCatalog.
+---
+
+This page lists the fields and paths supported by users.
+
+## Paths
+
+Users are created in the `users` folder:
+
+```txt
+/users/{user-id}.mdx
+```
+
+Users can also be synced from directory sources such as GitHub or Microsoft Entra.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/users/{user-id}` | User documentation page. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the user. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: dboyne
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the user.
+
+```md title="Example"
+---
+name: David Boyne
+---
+```
+
+## Optional fields
+
+### `avatarUrl` {#avatarUrl}
+
+- Type: `string`
+
+Avatar URL for the user.
+
+```md title="Example"
+---
+avatarUrl: https://github.com/dboyne.png
+---
+```
+
+### `role` {#role}
+
+- Type: `string`
+
+User role or title.
+
+```md title="Example"
+---
+role: Staff Engineer
+---
+```
+
+### `email` {#email}
+
+- Type: `string`
+
+User email address.
+
+```md title="Example"
+---
+email: david@example.com
+---
+```
+
+### `hidden` {#hidden}
+
+- Type: `boolean`
+
+Hide the user from generated lists.
+
+```md title="Example"
+---
+hidden: true
+---
+```
+
+### `slackDirectMessageUrl` {#slackDirectMessageUrl}
+
+- Type: `string`
+
+Slack direct message URL.
+
+```md title="Example"
+---
+slackDirectMessageUrl: https://slack.example.com/team/dboyne
+---
+```
+
+### `msTeamsDirectMessageUrl` {#msTeamsDirectMessageUrl}
+
+- Type: `string`
+
+Microsoft Teams direct message URL.
+
+```md title="Example"
+---
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/example
+---
+```
+

package/dist/docs/development/guides/owners/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Teams & Users",
-  "position": 11,
+  "position": 6,
   "collapsible": true,
   "collapsed": true,
   "link": {
@@ -8,4 +8,4 @@
     "slug": "/owners",
     "description": "A collection of guides to help you understand owners and how they work with EventCatalog."
   }
-}
+}

package/dist/docs/development/guides/owners/automated-teams-and-users/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Automated teams and users",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/guides/owners/automated-teams-and-users",
+    "description": "A collection of guides to help you sync teams and users into EventCatalog from external systems."
+  }
+}

package/dist/docs/development/guides/owners/automated-teams-and-users/create-your-own-connector.md

@@ -0,0 +1,108 @@
+---
+sidebar_position: 3
+slug: /development/guides/owners/create-your-own-connector
+keywords:
+- EventCatalog custom directory connector
+- defineDirectorySource
+sidebar_label: Create your own connector
+title: Create your own connector
+description: Build a custom directory connector to sync users and teams from any provider.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+<AddedIn version="3.44.0" pkg="@eventcatalog/connectors" />
+
+Connectors are how EventCatalog imports and syncs users and teams from an external source so you can assign them as owners on resources in your catalog. EventCatalog ships with built-in connectors (such as [Sync from GitHub](/docs/development/guides/owners/sync-from-github) and [Sync from Microsoft Entra ID](/docs/development/guides/owners/sync-from-microsoft-entra)), but if your team uses a different system &mdash; an internal HR tool, an LDAP directory, a SaaS like Okta, or anything else &mdash; you can write your own connector with a small amount of custom code.
+
+A custom connector is a JavaScript function you define that returns a list of users and teams. EventCatalog runs it on startup and treats the results the same as any other connector. You build it using `defineDirectorySource` from `@eventcatalog/connectors` and register it in the same `directory.sources` array used by the built-in connectors.
+
+```mermaid
+flowchart LR
+    SRC[Your source<br/>e.g. LDAP, Okta, HR tool] --> C[Your custom connector]
+    C --> EC[EventCatalog]
+    EC --> U[Users & Teams]
+```
+
+## Build a connector
+
+A connector is an object with a `type`, a `name`, and at least one of `loadUsers` or `loadTeams`:
+
+```js title="connectors/company-directory.js"
+import { defineDirectorySource } from '@eventcatalog/connectors';
+
+export const companyDirectory = defineDirectorySource({
+  type: 'directory',
+  name: 'company-directory',
+
+  async loadTeams() {
+    // Call your external API here (e.g. LDAP, Okta, your HR system)
+    // and return the teams in the shape below.
+    return [
+      {
+        id: 'platform',
+        name: 'Platform',
+        summary: 'Platform engineering team.',
+        members: ['alice'],
+        source: {
+          provider: 'company-directory',
+        },
+      },
+    ];
+  },
+
+  async loadUsers() {
+    // Call your external API here to fetch users
+    // and return them in the shape below.
+    return [
+      {
+        id: 'alice',
+        name: 'Alice',
+        avatarUrl: 'https://example.com/alice.png',
+        source: {
+          provider: 'company-directory',
+        },
+      },
+    ];
+  },
+});
+```
+
+Register it in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+import { companyDirectory } from './connectors/company-directory.js';
+
+export default {
+  // ... rest of config
+  directory: {
+    sources: [companyDirectory],
+  },
+};
+```
+
+## User shape
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | Unique identifier. Matches the `id` used to reference the user as an owner. |
+| `name` | `string` | Yes | Display name. |
+| `avatarUrl` | `string` | No | URL to a profile image. |
+| `role` | `string` | No | Job title or role description. |
+| `email` | `string` | No | Contact email address. |
+| `markdown` | `string` | No | Markdown body rendered on the user's page. |
+| `source` | `object` | No | Provider metadata. The `provider` field is used for the source badge in the UI. |
+
+## Team shape
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | Unique identifier. Matches the `id` used to reference the team as an owner. |
+| `name` | `string` | Yes | Display name. |
+| `summary` | `string` | No | Short description. |
+| `members` | `string[]` | No | List of user `id` values who belong to the team. |
+| `email` | `string` | No | Contact email address. |
+| `markdown` | `string` | No | Markdown body rendered on the team's page. |
+| `source` | `object` | No | Provider metadata. The `provider` field is used for the source badge in the UI. |

package/dist/docs/development/guides/owners/automated-teams-and-users/sync-from-github.md

@@ -0,0 +1,156 @@
+---
+sidebar_position: 1
+slug: /development/guides/owners/sync-from-github
+keywords:
+- EventCatalog GitHub connector
+- sync GitHub teams users
+- directory connector
+sidebar_label: Sync from GitHub
+title: Sync from GitHub
+description: Sync GitHub organization teams and members into EventCatalog as users and teams.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+In EventCatalog, you can import and sync your users and teams directly from GitHub. Instead of adding people and teams by hand, you point EventCatalog at your GitHub organization and the catalog stays in sync with it automatically. Once synced, your GitHub teams and users can be assigned as owners on any resource in the catalog (services, events, domains, and more).
+
+```mermaid
+flowchart LR
+    GH[GitHub org] --> C[GitHub connector]
+    C --> EC[EventCatalog]
+    EC --> U[Users & Teams]
+```
+
+## Why sync from GitHub
+
+Teams and users in EventCatalog are used to assign ownership to resources such as services, events, and domains. Keeping that ownership data accurate requires the user and team lists to reflect who actually works on each system. Syncing from GitHub automates that by pulling the data from an org you already manage.
+
+## How it works
+
+When EventCatalog starts, the connector fetches users and teams from GitHub. They appear in the catalog alongside any users and teams you have defined locally, and each synced entry is marked as read-only with a link back to the source record on GitHub.
+
+## Install
+
+```bash
+npm install @eventcatalog/connectors
+```
+
+## Configure
+
+Import `githubDirectory` and add it to the `directory.sources` array in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+import { githubDirectory } from '@eventcatalog/connectors';
+
+export default {
+  // ... rest of config
+  directory: {
+    sources: [
+      githubDirectory({
+        org: 'your-org',
+        token: process.env.GITHUB_TOKEN,
+        teams: ['platform', 'architecture'],
+        users: true,
+      }),
+    ],
+  },
+};
+```
+
+## Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `org` | `string` | Yes | GitHub organization slug. |
+| `teams` | `string[]` | Yes | One or more team slugs to sync. At least one is required. |
+| `token` | `string` | No | Personal access token or GitHub App installation token. Required for private organizations and to avoid rate limits. |
+| `users` | `boolean` | No | When `true` (default), members of every synced team are also synced as users. Set to `false` to sync teams only. |
+| `baseUrl` | `string` | No | Override the GitHub API base URL. Useful for GitHub Enterprise Server instances. |
+
+## GitHub token
+
+Pass a token via an environment variable so it is never committed to source control:
+
+```bash
+GITHUB_TOKEN=ghp_yourtoken npx eventcatalog dev
+```
+
+The token needs the following permissions:
+
+- `read:org` - to read teams and their members in the organization.
+
+For public organizations the connector works without a token, but GitHub rate limits unauthenticated requests to 60 per hour.
+
+## What gets synced
+
+### Teams
+
+Each team slug listed in the `teams` option is fetched from the GitHub API. The connector creates a team entry with:
+
+- `id` set to the team slug.
+- `name` taken from the GitHub team display name.
+- `summary` taken from the GitHub team description.
+- A read-only note linking back to the team on GitHub.
+
+### Users
+
+When `users` is `true`, every member of each synced team is fetched and created as a user entry with:
+
+- `id` set to the GitHub username (login).
+- `name` set to the GitHub username.
+- `avatarUrl` set to the GitHub avatar URL.
+- A read-only note linking back to the user's GitHub profile.
+
+A user who belongs to multiple synced teams is only written once.
+
+## Use synced owners
+
+Synced teams and users behave identically to hand-authored ones. Reference them by their `id` in any resource frontmatter:
+
+```yaml title="services/order-service/index.md"
+---
+id: OrderService
+name: Order Service
+owners:
+  - platform
+  - jsmith
+---
+```
+
+## Conflict strategy
+
+When a locally authored user or team shares the same `id` as one returned by the connector, EventCatalog uses the `conflictStrategy` setting to decide what to do.
+
+| Strategy | Behaviour |
+|---|---|
+| `local-wins` (default) | The local file is kept and the external entry is skipped. |
+| `source-wins` | The external entry overwrites the local file. |
+| `error` | EventCatalog throws an error and stops the build. |
+
+Configure the strategy in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... rest of config
+  directory: {
+    conflictStrategy: 'local-wins',
+    sources: [ /* ... */ ],
+  },
+};
+```
+
+## GitHub Enterprise Server
+
+Set the `baseUrl` option to your GHES API endpoint:
+
+```js
+githubDirectory({
+  org: 'your-org',
+  token: process.env.GITHUB_TOKEN,
+  teams: ['platform'],
+  baseUrl: 'https://github.example.com/api/v3',
+})
+```