@eventcatalog/connectors 0.1.0 → 0.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 Connectors for syncing external systems into EventCatalog.
 
+## GitHub
+
 ```js
 // eventcatalog.config.js
 import { githubDirectory } from "@eventcatalog/connectors";
@@ -20,6 +22,63 @@ export default {
 };
 ```
 
+## Microsoft Entra ID
+
+Sync selected Microsoft Entra ID groups into EventCatalog teams, and sync their
+direct user members into EventCatalog users.
+
+```js
+// eventcatalog.config.js
+import { microsoftEntraDirectory } from "@eventcatalog/connectors";
+
+export default {
+  directory: {
+    sources: [
+      microsoftEntraDirectory({
+        tenantId: process.env.AZURE_TENANT_ID,
+        clientId: process.env.AZURE_CLIENT_ID,
+        clientSecret: process.env.AZURE_CLIENT_SECRET,
+        groups: [
+          {
+            id: "00000000-0000-0000-0000-000000000000",
+            alias: "platform",
+          },
+          {
+            displayName: "Architecture Guild",
+          },
+        ],
+      }),
+    ],
+  },
+};
+```
+
+The connector uses Microsoft Graph with the OAuth client credentials flow.
+Create an app registration in Microsoft Entra ID, add read-only Microsoft Graph
+application permissions for reading groups, users, and group members, grant
+admin consent, then create a client secret for the build environment.
+
+Groups can be configured by stable `id` or exact `displayName`. Group IDs are
+recommended. If a `displayName` lookup finds no groups or multiple groups, the
+connector fails and asks you to use the group ID.
+
+Selected groups become EventCatalog teams. Team IDs use `alias` when provided,
+otherwise they are slugified from the Entra group display name. Only direct user
+members are synced. Disabled users are excluded by default; set
+`includeDisabledUsers: true` to include them.
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [{ id: "00000000-0000-0000-0000-000000000000" }],
+  includeDisabledUsers: true,
+  graphBaseUrl: "https://graph.microsoft.com/v1.0",
+  tokenUrl: "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token",
+});
+```
+
 External directory sources require EventCatalog Scale when loaded by EventCatalog.
 
 Custom directory sources can use the same contract:

package/dist/index.d.mts

@@ -22,7 +22,7 @@ type DirectoryEntrySource = {
 type DirectoryUser = {
     id: string;
     name: string;
-    avatarUrl: string;
+    avatarUrl?: string;
     role?: string;
     email?: string;
     markdown?: string;
@@ -65,6 +65,57 @@ type DirectorySource = {
  * Defines a custom directory source with type inference for connector authors.
  */
 declare const defineDirectorySource: <TSource extends DirectorySource>(source: TSource) => TSource;
+/**
+ * Describes where a synced schema came from.
+ */
+type SchemaEntrySource = {
+    /** Provider identifier, for example `git`, `github`, `confluent`, or `eventbridge`. */
+    provider: string;
+    /** Optional provider-specific identifier for the external schema. */
+    id?: string;
+    /** Optional URL back to the schema source. */
+    url?: string;
+    /** Optional version/ref/branch for versioned sources. */
+    ref?: string;
+    /** Optional branch for git-backed schema sources. */
+    branch?: string;
+    /** Optional path inside the source. */
+    path?: string;
+    [key: string]: unknown;
+};
+/**
+ * Schema returned by an external schema source.
+ */
+type SchemaEntry = {
+    id: string;
+    name?: string;
+    format?: string;
+    content: string;
+    source: SchemaEntrySource;
+};
+type SchemaResolveContext = {
+    /** Absolute path to the message file that referenced the schema. */
+    messageFilePath?: string;
+};
+/**
+ * Loads schemas from an external source.
+ *
+ * EventCatalog calls schema sources during content sync to resolve schema
+ * references from messages into generated schema collection entries.
+ */
+type SchemaSource = {
+    type: "schemas";
+    /** Stable source identifier used in schema refs, for example `contracts`. */
+    name: string;
+    /** Returns true when this source can resolve the given schema ref. */
+    canResolve: (ref: string) => boolean;
+    /** Resolves a schema ref into schema content and source metadata. */
+    resolve: (ref: string, context?: SchemaResolveContext) => Promise<SchemaEntry | undefined>;
+};
+/**
+ * Defines a custom schema source with type inference for connector authors.
+ */
+declare const defineSchemaSource: <TSource extends SchemaSource>(source: TSource) => TSource;
 
 type GitHubDirectoryOptions = {
     org: string;
@@ -75,4 +126,40 @@ type GitHubDirectoryOptions = {
 };
 declare const githubDirectory: (options: GitHubDirectoryOptions) => DirectorySource;
 
-export { type DirectoryEntrySource, type DirectorySource, type DirectoryTeam, type DirectoryUser, defineDirectorySource, githubDirectory };
+type MicrosoftEntraGroupInput = string | {
+    id: string;
+    alias?: string;
+} | {
+    displayName: string;
+    alias?: string;
+};
+type MicrosoftEntraDirectoryOptions = {
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+    groups: MicrosoftEntraGroupInput[];
+    users?: boolean;
+    includeDisabledUsers?: boolean;
+    graphBaseUrl?: string;
+    tokenUrl?: string;
+};
+declare const microsoftEntraDirectory: (options: MicrosoftEntraDirectoryOptions) => DirectorySource;
+
+type GitSchemaSourceOptions = {
+    /**
+     * Stable source name used in schema refs, for example:
+     * `git://contracts/events/OrderPlaced.schema.json`.
+     */
+    name: string;
+    /** Git repository URL. Supports any URL your local git can clone. */
+    url: string;
+    /** Branch to clone. */
+    branch?: string;
+    /** Optional directory inside the repository that contains schemas. */
+    directory?: string;
+    /** Optional HTTPS token. SSH auth is handled by the local git environment. */
+    token?: string;
+};
+declare const gitSchemaSource: (options: GitSchemaSourceOptions) => SchemaSource;
+
+export { type DirectoryEntrySource, type DirectorySource, type DirectoryTeam, type DirectoryUser, type SchemaEntry, type SchemaEntrySource, type SchemaResolveContext, type SchemaSource, defineDirectorySource, defineSchemaSource, gitSchemaSource, githubDirectory, microsoftEntraDirectory };

package/dist/index.d.ts

@@ -22,7 +22,7 @@ type DirectoryEntrySource = {
 type DirectoryUser = {
     id: string;
     name: string;
-    avatarUrl: string;
+    avatarUrl?: string;
     role?: string;
     email?: string;
     markdown?: string;
@@ -65,6 +65,57 @@ type DirectorySource = {
  * Defines a custom directory source with type inference for connector authors.
  */
 declare const defineDirectorySource: <TSource extends DirectorySource>(source: TSource) => TSource;
+/**
+ * Describes where a synced schema came from.
+ */
+type SchemaEntrySource = {
+    /** Provider identifier, for example `git`, `github`, `confluent`, or `eventbridge`. */
+    provider: string;
+    /** Optional provider-specific identifier for the external schema. */
+    id?: string;
+    /** Optional URL back to the schema source. */
+    url?: string;
+    /** Optional version/ref/branch for versioned sources. */
+    ref?: string;
+    /** Optional branch for git-backed schema sources. */
+    branch?: string;
+    /** Optional path inside the source. */
+    path?: string;
+    [key: string]: unknown;
+};
+/**
+ * Schema returned by an external schema source.
+ */
+type SchemaEntry = {
+    id: string;
+    name?: string;
+    format?: string;
+    content: string;
+    source: SchemaEntrySource;
+};
+type SchemaResolveContext = {
+    /** Absolute path to the message file that referenced the schema. */
+    messageFilePath?: string;
+};
+/**
+ * Loads schemas from an external source.
+ *
+ * EventCatalog calls schema sources during content sync to resolve schema
+ * references from messages into generated schema collection entries.
+ */
+type SchemaSource = {
+    type: "schemas";
+    /** Stable source identifier used in schema refs, for example `contracts`. */
+    name: string;
+    /** Returns true when this source can resolve the given schema ref. */
+    canResolve: (ref: string) => boolean;
+    /** Resolves a schema ref into schema content and source metadata. */
+    resolve: (ref: string, context?: SchemaResolveContext) => Promise<SchemaEntry | undefined>;
+};
+/**
+ * Defines a custom schema source with type inference for connector authors.
+ */
+declare const defineSchemaSource: <TSource extends SchemaSource>(source: TSource) => TSource;
 
 type GitHubDirectoryOptions = {
     org: string;
@@ -75,4 +126,40 @@ type GitHubDirectoryOptions = {
 };
 declare const githubDirectory: (options: GitHubDirectoryOptions) => DirectorySource;
 
-export { type DirectoryEntrySource, type DirectorySource, type DirectoryTeam, type DirectoryUser, defineDirectorySource, githubDirectory };
+type MicrosoftEntraGroupInput = string | {
+    id: string;
+    alias?: string;
+} | {
+    displayName: string;
+    alias?: string;
+};
+type MicrosoftEntraDirectoryOptions = {
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+    groups: MicrosoftEntraGroupInput[];
+    users?: boolean;
+    includeDisabledUsers?: boolean;
+    graphBaseUrl?: string;
+    tokenUrl?: string;
+};
+declare const microsoftEntraDirectory: (options: MicrosoftEntraDirectoryOptions) => DirectorySource;
+
+type GitSchemaSourceOptions = {
+    /**
+     * Stable source name used in schema refs, for example:
+     * `git://contracts/events/OrderPlaced.schema.json`.
+     */
+    name: string;
+    /** Git repository URL. Supports any URL your local git can clone. */
+    url: string;
+    /** Branch to clone. */
+    branch?: string;
+    /** Optional directory inside the repository that contains schemas. */
+    directory?: string;
+    /** Optional HTTPS token. SSH auth is handled by the local git environment. */
+    token?: string;
+};
+declare const gitSchemaSource: (options: GitSchemaSourceOptions) => SchemaSource;
+
+export { type DirectoryEntrySource, type DirectorySource, type DirectoryTeam, type DirectoryUser, type SchemaEntry, type SchemaEntrySource, type SchemaResolveContext, type SchemaSource, defineDirectorySource, defineSchemaSource, gitSchemaSource, githubDirectory, microsoftEntraDirectory };