@eventcatalog/sdk 2.10.0 → 2.12.0

package/dist/index.d.mts

@@ -1,5 +1,332 @@
-import { Event, Command, Query, Channel, Service, Domain, UbiquitousLanguageDictionary, Team, User, CustomDoc, EventCatalog, Message, Entity, Container } from './types.d.mjs';
-export { Badge, BaseSchema, ChannelPointer, ReceivesPointer, ResourceGroup, ResourcePointer, SendsPointer, Specification, Specifications, UbiquitousLanguage } from './types.d.mjs';
+// 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
@@ -696,7 +1023,14 @@ declare const _default: (path: string) => {
      *
      */
     writeDomain: (domain: Domain, options?: {
-        path?: string;
+        path? /**
+         * Adds an event to a service in EventCatalog
+         *
+         * @param event - The event to write to the service
+         * @param service - The service and it's id to write to the event to
+         * @param options - Optional options to write the event
+         *
+         */: string;
         override?: boolean;
         versionExistingContent?: boolean;
         format?: "md" | "mdx";
@@ -802,6 +1136,69 @@ declare const _default: (path: string) => {
         id: string;
         version: string;
     }, version?: string) => Promise<void>;
+    /**
+     * Add an event to a domain by its id.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addEventToDomain } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new event (OrderCreated) that the Orders domain will send
+     * await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '2.0.0' });
+     *
+     * // adds a new event (PaymentProcessed) that the Orders domain will receive
+     * await addEventToDomain('Orders', 'receives', { id: 'PaymentProcessed', version: '2.0.0' });
+     *
+     * ```
+     */
+    addEventToDomain: (id: string, direction: string, message: {
+        id: string;
+        version: string;
+    }, version?: string) => Promise<void>;
+    /**
+     * Add a command to a domain by its id.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addCommandToDomain } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new command (ProcessOrder) that the Orders domain will send
+     * await addCommandToDomain('Orders', 'sends', { id: 'ProcessOrder', version: '2.0.0' });
+     *
+     * // adds a new command (CancelOrder) that the Orders domain will receive
+     * await addCommandToDomain('Orders', 'receives', { id: 'CancelOrder', version: '2.0.0' });
+     *
+     * ```
+     */
+    addCommandToDomain: (id: string, direction: string, message: {
+        id: string;
+        version: string;
+    }, version?: string) => Promise<void>;
+    /**
+     * Add a query to a domain by its id.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addQueryToDomain } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new query (GetOrderStatus) that the Orders domain will send
+     * await addQueryToDomain('Orders', 'sends', { id: 'GetOrderStatus', version: '2.0.0' });
+     *
+     * // adds a new query (GetInventory) that the Orders domain will receive
+     * await addQueryToDomain('Orders', 'receives', { id: 'GetInventory', version: '2.0.0' });
+     *
+     * ```
+     */
+    addQueryToDomain: (id: string, direction: string, message: {
+        id: string;
+        version: string;
+    }, version?: string) => Promise<void>;
     /**
      * ================================
      *            Teams
@@ -1116,8 +1513,111 @@ declare const _default: (path: string) => {
     }, options?: {
         path?: string;
         format?: "md" | "mdx";
+        override? /**
+         * Remove an command to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your command, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */: boolean;
+    }) => Promise<void>;
+    /**
+     * ================================
+     *            Data Products
+     * ================================
+     */
+    /**
+     * Adds a data product to EventCatalog
+     * @param dataProduct - The data product to write
+     * @param options - Optional options to write the data product
+     *
+     */
+    writeDataProduct: (dataProduct: DataProduct, options?: {
+        path?: string;
         override?: boolean;
+        versionExistingContent?: boolean;
+        format?: "md" | "mdx";
+    }) => Promise<void>;
+    /**
+     * Writes a data product to a domain in EventCatalog
+     * @param dataProduct - The data product to write
+     * @param domain - The domain to write the data product to
+     * @param options - Optional options to write the data product
+     *
+     */
+    writeDataProductToDomain: (dataProduct: DataProduct, domain: {
+        id: string;
+        version?: string;
+    }, options?: {
+        path?: string;
+        format?: "md" | "mdx";
+        override? /**
+         * Adds a schema to the given event
+         * @param id - The id of the event to add the schema to
+         * @param schema - Schema contents to add including the content and the file name
+         * @param version - Optional version of the event to add the schema to
+         * @returns
+         */: boolean;
     }) => Promise<void>;
+    /**
+     * Returns a data product from EventCatalog
+     * @param id - The id of the data product to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns DataProduct|Undefined
+     */
+    getDataProduct: (id: string, version?: string) => Promise<DataProduct>;
+    /**
+     * Returns all data products from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns DataProduct[]|Undefined
+     */
+    getDataProducts: (options?: {
+        latestOnly?: boolean;
+    }) => Promise<DataProduct[]>;
+    /**
+     * Version a data product by its id
+     * @param id - The id of the data product to version
+     */
+    versionDataProduct: (id: string) => Promise<void>;
+    /**
+     * Remove a data product by its path
+     * @param path - The path to the data product to remove
+     */
+    rmDataProduct: (path: string) => Promise<void>;
+    /**
+     * Remove a data product by its id
+     * @param id - The id of the data product to remove
+     * @param version - Optional version of the data product to remove
+     */
+    rmDataProductById: (id: string, version?: string, persistFiles?: boolean) => Promise<void>;
+    /**
+     * Check to see if a data product version exists
+     * @param id - The id of the data product
+     * @param version - The version of the data product (supports semver)
+     * @returns
+     */
+    dataProductHasVersion: (id: string, version?: string) => Promise<boolean>;
+    /**
+     * Adds a file to a data product by its id
+     * @param id - The id of the data product to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the data product to add the file to
+     * @returns
+     */
+    addFileToDataProduct: (id: string, file: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
+    /**
+     * Adds a data product to a domain
+     * @param id - The id of the domain
+     * @param dataProduct - The id and version of the data product to add
+     * @param version - (Optional) The version of the domain to add the data product to
+     * @returns
+     */
+    addDataProductToDomain: (id: string, dataProduct: {
+        id: string;
+        version: string;
+    }, version?: string) => Promise<void>;
 };
 
-export { Channel, Command, Container, CustomDoc, 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 };