@eventcatalog/sdk 2.11.0 → 2.12.0

package/dist/index.d.ts

@@ -1,5 +1,332 @@
-import { Event, Command, Query, Channel, Service, Domain, UbiquitousLanguageDictionary, Team, User, CustomDoc, EventCatalog, Message, Entity, Container, DataProduct } from './types.d.js';
-export { Badge, BaseSchema, ChannelPointer, DataProductOutputPointer, ReceivesPointer, ResourceGroup, ResourcePointer, SendsPointer, Specification, Specifications, UbiquitousLanguage } from './types.d.js';
+// Base type for all resources (domains, services and messages)
+interface BaseSchema {
+  id: string;
+  name: string;
+  summary?: string;
+  version: string;
+  badges?: Badge[];
+  sidebar?: {
+    badge?: string;
+  };
+  owners?: string[];
+  schemaPath?: string;
+  markdown: string;
+  repository?: {
+    language?: string;
+    url?: string;
+  };
+  deprecated?:
+    | boolean
+    | {
+        date?: string;
+        message?: string;
+      };
+  styles?: {
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+  attachments?:
+    | string[]
+    | {
+        url: string;
+        title?: string;
+        type?: string;
+        description?: string;
+        icon?: string;
+      }[];
+  resourceGroups?: ResourceGroup[];
+  diagrams?: ResourcePointer[];
+  editUrl?: string;
+  draft?: boolean | { title?: string; message?: string };
+  // SDK types
+  schema?: any;
+}
+
+type ResourcePointer = {
+  id: string;
+  version?: string;
+  type?: string;
+};
+
+type SendsPointer = {
+  id: string;
+  version?: string;
+  to?: ChannelPointer[];
+};
+
+type ReceivesPointer = {
+  id: string;
+  version?: string;
+  from?: ChannelPointer[];
+};
+
+interface ResourceGroup {
+  id?: string;
+  title?: string;
+  items: ResourcePointer[];
+  limit?: number;
+  sidebar?: boolean;
+}
+
+interface ChannelPointer extends ResourcePointer {
+  parameters?: Record<string, string>;
+}
+
+type Message = Event | Command | Query;
+
+interface CustomDoc {
+  title: string;
+  summary: string;
+  slug?: string;
+  sidebar?: {
+    label: string;
+    order: number;
+  };
+  owners?: string[];
+  badges?: Badge[];
+  fileName?: string;
+  markdown: string;
+}
+
+interface MessageDetailsPanelProperty {
+  producers?: DetailPanelProperty;
+  consumers?: DetailPanelProperty;
+  channels?: DetailPanelProperty;
+  versions?: DetailPanelProperty;
+  repository?: DetailPanelProperty;
+}
+
+interface Event extends BaseSchema {
+  channels?: ChannelPointer[];
+  detailsPanel?: MessageDetailsPanelProperty;
+}
+interface Command extends BaseSchema {
+  channels?: ChannelPointer[];
+  detailsPanel?: MessageDetailsPanelProperty;
+}
+interface Query extends BaseSchema {
+  channels?: ChannelPointer[];
+  detailsPanel?: MessageDetailsPanelProperty;
+}
+interface Channel extends BaseSchema {
+  address?: string;
+  protocols?: string[];
+  routes?: ChannelPointer[];
+  detailsPanel?: {
+    producers?: DetailPanelProperty;
+    consumers?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    protocols?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+  // parameters?: Record<string, Parameter>;
+  parameters?: {
+    [key: string]: {
+      enum?: string[];
+      default?: string;
+      examples?: string[];
+      description?: string;
+    };
+  };
+}
+
+interface Specifications {
+  asyncapiPath?: string;
+  openapiPath?: string;
+  graphqlPath?: string;
+}
+
+interface Specification {
+  type: 'openapi' | 'asyncapi' | 'graphql';
+  path: string;
+  name?: string;
+}
+
+interface Service extends BaseSchema {
+  sends?: SendsPointer[];
+  receives?: ReceivesPointer[];
+  entities?: ResourcePointer[];
+  writesTo?: ResourcePointer[];
+  readsFrom?: ResourcePointer[];
+  specifications?: Specifications | Specification[];
+  detailsPanel?: {
+    domains?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    specifications?: DetailPanelProperty;
+    entities?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+interface Domain extends BaseSchema {
+  services?: ResourcePointer[];
+  domains?: ResourcePointer[];
+  entities?: ResourcePointer[];
+  dataProducts?: ResourcePointer[];
+  sends?: SendsPointer[];
+  receives?: ReceivesPointer[];
+  detailsPanel?: {
+    parentDomains?: DetailPanelProperty;
+    subdomains?: DetailPanelProperty;
+    services?: DetailPanelProperty;
+    entities?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    ubiquitousLanguage?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+interface Team {
+  id: string;
+  name: string;
+  summary?: string;
+  email?: string;
+  hidden?: boolean;
+  slackDirectMessageUrl?: string;
+  members?: User[];
+  ownedCommands?: Command[];
+  ownedServices?: Service[];
+  ownedEvents?: Event[];
+  markdown: string;
+}
+
+interface User {
+  id: string;
+  name: string;
+  avatarUrl: string;
+  role?: string;
+  hidden?: boolean;
+  email?: string;
+  slackDirectMessageUrl?: string;
+  ownedServices?: Service[];
+  ownedEvents?: Event[];
+  ownedCommands?: Command[];
+  associatedTeams?: Team[];
+  markdown: string;
+}
+
+interface Badge {
+  content: string;
+  backgroundColor: string;
+  textColor: string;
+  icon?: string;
+}
+
+interface UbiquitousLanguage {
+  id: string;
+  name: string;
+  summary?: string;
+  description?: string;
+  icon?: string;
+}
+
+interface UbiquitousLanguageDictionary {
+  dictionary: UbiquitousLanguage[];
+}
+
+interface DetailPanelProperty {
+  visible: boolean;
+}
+
+interface Entity extends BaseSchema {
+  aggregateRoot?: boolean;
+  identifier?: string;
+  properties?: {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+    references?: string;
+    referencesIdentifier?: string;
+    relationType?: string;
+  }[];
+  detailsPanel?: {
+    domains?: DetailPanelProperty;
+    services?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+type DataProductOutputPointer = {
+  id: string;
+  version?: string;
+  contract?: {
+    path: string;
+    name: string;
+    type?: string;
+  };
+};
+
+interface DataProduct extends BaseSchema {
+  inputs?: ResourcePointer[];
+  outputs?: DataProductOutputPointer[];
+  detailsPanel?: {
+    domains?: DetailPanelProperty;
+    inputs?: DetailPanelProperty;
+    outputs?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+declare enum DataClassification {
+  Public = 'public',
+  Internal = 'internal',
+  Confidential = 'confidential',
+  Regulated = 'regulated',
+}
+
+interface Container extends BaseSchema {
+  container_type: 'database' | 'cache' | 'objectStore' | 'searchIndex' | 'dataWarehouse' | 'dataLake' | 'externalSaaS' | 'other';
+  technology?: string;
+  authoritative?: boolean;
+  access_mode?: string;
+  classification?: DataClassification;
+  residency?: string;
+  retention?: string;
+  detailsPanel?: {
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+type EventCatalog = {
+  version: string;
+  catalogVersion: string;
+  createdAt: string;
+  resources: {
+    domains?: ExportedResource<Domain>[];
+    services?: ExportedResource<Service>[];
+    messages?: {
+      events?: ExportedResource<Event>[];
+      queries?: ExportedResource<Query>[];
+      commands?: ExportedResource<Command>[];
+    };
+    teams?: ExportedResource<Team>[];
+    users?: ExportedResource<User>[];
+    channels?: ExportedResource<Channel>[];
+    customDocs?: ExportedResource<CustomDoc>[];
+  };
+};
 
 /**
  * Init the SDK for EventCatalog
@@ -1293,4 +1620,4 @@ declare const _default: (path: string) => {
     }, version?: string) => Promise<void>;
 };
 
-export { Channel, Command, Container, CustomDoc, DataProduct, Domain, Entity, Event, EventCatalog, Message, Query, Service, Team, UbiquitousLanguageDictionary, User, _default as default };
+export { type Badge, type BaseSchema, type Channel, type ChannelPointer, type Command, type Container, type CustomDoc, type DataProduct, type DataProductOutputPointer, type Domain, type Entity, type Event, type EventCatalog, type Message, type Query, type ReceivesPointer, type ResourceGroup, type ResourcePointer, type SendsPointer, type Service, type Specification, type Specifications, type Team, type UbiquitousLanguage, type UbiquitousLanguageDictionary, type User, _default as default };

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@eventcatalog/sdk",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "SDK to integrate with EventCatalog",
+  "bin": {
+    "eventcatalog": "./dist/cli/index.js"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -24,12 +27,17 @@
   ],
   "exports": {
     ".": {
-      "require": "./dist/index.js",
-      "import": "./dist/index.mjs",
       "types": [
         "./dist/index.d.ts",
         "./dist/events.t.ts"
-      ]
+      ],
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    },
+    "./cli-docs": {
+      "types": "./dist/cli-docs.d.ts",
+      "require": "./dist/cli-docs.js",
+      "import": "./dist/cli-docs.mjs"
     }
   },
   "main": "./dist/index.js",
@@ -37,6 +45,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@changesets/cli": "^2.29.8",
+    "commander": "^12.0.0",
     "fs-extra": "^11.3.2",
     "glob": "^11.1.0",
     "gray-matter": "^4.0.3",

package/dist/channels.d.mts

@@ -1,214 +0,0 @@
-import { Channel } from './types.d.mjs';
-
-/**
- * Returns a channel from EventCatalog.
- *
- * You can optionally specify a version to get a specific version of the channel
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * const { getChannel } = utils('/path/to/eventcatalog');
- *
- * // Gets the latest version of the channel
- * const channel = await getChannel('InventoryChannel');
- *
- * // Gets a version of the channel
- * const channel = await getChannel('InventoryChannel', '0.0.1');
- * ```
- */
-declare const getChannel: (directory: string) => (id: string, version?: string) => Promise<Channel>;
-/**
- * Returns all channels from EventCatalog.
- *
- * You can optionally specify if you want to get the latest version of the channels.
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * const { getChannels } = utils('/path/to/eventcatalog');
- *
- * // Gets all channels (and versions) from the catalog
- * const channels = await getChannels();
- *
- * // Gets all channels (only latest version) from the catalog
- * const channels = await getChannels({ latestOnly: true });
- * ```
- */
-declare const getChannels: (directory: string) => (options?: {
-    latestOnly?: boolean;
-}) => Promise<Channel[]>;
-/**
- * Write a channel to EventCatalog.
- *
- * You can optionally override the path of the channel.
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * const { writeChannel } = utils('/path/to/eventcatalog');
- *
- * // Write a channel to the catalog
- * // channel would be written to channels/inventory.{env}.events
- * await writeChannel({
- *   id: 'inventory.{env}.events',
- *   name: 'Inventory channel',
- *   version: '0.0.1',
- *   summary: 'This is a summary',
- *   markdown: '# Hello world',
- *   address: inventory.{env}.events,
- * protocols: ['http'],
- * });
- *
- * // Write a channel to the catalog but override the path
- * // channel would be written to channels/Inventory/InventoryChannel
- * await writeChannel({
- *    id: 'InventoryChannel',
- *    name: 'Update Inventory',
- *    version: '0.0.1',
- *    summary: 'This is a summary',
- *    markdown: '# Hello world',
- *    address: inventory.{env}.events,
- *    protocols: ['http'],
- * }, { path: "/channels/Inventory/InventoryChannel"});
- *
- * // Write a channel to the catalog and override the existing content (if there is any)
- * await writeChannel({
- *    id: 'InventoryChannel',
- *    name: 'Update Inventory',
- *    version: '0.0.1',
- *    summary: 'This is a summary',
- *    markdown: '# Hello world',
- *    address: inventory.{env}.events,
- *    protocols: ['http'],
- * }, { override: true });
- *
- * // Write a channel to the catalog and version the previous version
- * // only works if the new version is greater than the previous version
- * await writeChannel({
- *    id: 'InventoryChannel',
- *    name: 'Update Inventory',
- *    version: '0.0.1',
- *    summary: 'This is a summary',
- *    markdown: '# Hello world',
- *    address: inventory.{env}.events,
- *    protocols: ['http'],
- * }, { versionExistingContent: true });
- * ```
- */
-declare const writeChannel: (directory: string) => (channel: Channel, options?: {
-    path?: string;
-    override?: boolean;
-    versionExistingContent?: boolean;
-    format?: "md" | "mdx";
-}) => Promise<void>;
-/**
- * Delete a channel at it's given path.
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * const { rmChannel } = utils('/path/to/eventcatalog');
- *
- * // removes a channel at the given path (channels dir is appended to the given path)
- * // Removes the channel at channels/InventoryChannel
- * await rmChannel('/InventoryChannel');
- * ```
- */
-declare const rmChannel: (directory: string) => (path: string) => Promise<void>;
-/**
- * Delete a channel by it's id.
- *
- * Optionally specify a version to delete a specific version of the channel.
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * const { rmChannelById } = utils('/path/to/eventcatalog');
- *
- * // deletes the latest InventoryChannel channel
- * await rmChannelById('inventory.{env}.events');
- *
- * // deletes a specific version of the InventoryChannel channel
- * await rmChannelById('inventory.{env}.events', '0.0.1');
- * ```
- */
-declare const rmChannelById: (directory: string) => (id: string, version?: string, persistFiles?: boolean) => Promise<void>;
-/**
- * Version a channel by it's id.
- *
- * Takes the latest channel and moves it to a versioned directory.
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * const { versionChannel } = utils('/path/to/eventcatalog');
- *
- * // moves the latest inventory.{env}.events channel to a versioned directory
- * // the version within that channel is used as the version number.
- * await versionChannel('inventory.{env}.events');
- *
- * ```
- */
-declare const versionChannel: (directory: string) => (id: string) => Promise<void>;
-/**
- * Check to see if the catalog has a version for the given channel.
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * const { channelHasVersion } = utils('/path/to/eventcatalog');
- *
- * // returns true if version is found for the given event and version (supports semver)
- * await channelHasVersion('inventory.{env}.events', '0.0.1');
- * await channelHasVersion('inventory.{env}.events', 'latest');
- * await channelHasVersion('inventory.{env}.events', '0.0.x');*
- *
- * ```
- */
-declare const channelHasVersion: (directory: string) => (id: string, version?: string) => Promise<boolean>;
-/**
- * Add an event/command/query to a channel by it's id.
- *
- * Optionally specify a version to add the message to a specific version of the service.
- *
- * @example
- * ```ts
- * import utils from '@eventcatalog/utils';
- *
- * // Adds an event to the service or command to the service
- * const { addEventToChannel, addCommandToChannel, addQueryToChannel } = utils('/path/to/eventcatalog');
- *
- * // Adds a new event (InventoryUpdatedEvent) that the InventoryService will send
- * await addEventToChannel('InventoryService', 'sends', { event: 'InventoryUpdatedEvent', version: '2.0.0' });
- * * // Adds a new event (OrderComplete) that the InventoryService will receive
- * await addEventToChannel('InventoryService', 'receives', { event: 'OrderComplete', version: '1.0.0' });
- *
- * // Adds a new command (UpdateInventoryCommand) that the InventoryService will send
- * await addCommandToChannel('InventoryService', 'sends', { command: 'UpdateInventoryCommand', version: '2.0.0' });
- * // Adds a new command (VerifyInventory) that the InventoryService will receive
- * await addCommandToChannel('InventoryService', 'receives', { command: 'VerifyInventory', version: '1.0.0' });
- *
- * // Adds a new query (GetInventoryQuery) that the InventoryService will send
- * await addQueryToChannel('InventoryService', 'sends', { query: 'GetInventoryQuery', version: '2.0.0' });
- * // Adds a new query (GetOrder) that the InventoryService will receive
- * await addQueryToChannel('InventoryService', 'receives', { query: 'GetOrder', version: '1.0.0' });
- *
- * ```
- */
-declare const addMessageToChannel: (directory: string, collection: string) => (id: string, _message: {
-    id: string;
-    version: string;
-    parameters?: {
-        [key: string]: string;
-    };
-}, version?: string) => Promise<void>;
-
-export { addMessageToChannel, channelHasVersion, getChannel, getChannels, rmChannel, rmChannelById, versionChannel, writeChannel };