@eventcatalog/sdk 2.15.1 → 2.17.0

package/dist/index.d.mts

@@ -235,6 +235,12 @@ interface Badge {
   icon?: string;
 }
 
+interface Changelog {
+  createdAt: Date | string;
+  badges?: Badge[];
+  markdown: string;
+}
+
 interface UbiquitousLanguage {
   id: string;
   name: string;
@@ -354,6 +360,86 @@ interface ToDSLOptions {
     hydrate?: boolean;
 }
 
+type SnapshotGitInfo = {
+    branch: string;
+    commit: string;
+    dirty: boolean;
+};
+type SnapshotResources = {
+    domains: Record<string, any>[];
+    services: Record<string, any>[];
+    messages: {
+        events: Record<string, any>[];
+        commands: Record<string, any>[];
+        queries: Record<string, any>[];
+    };
+    channels: Record<string, any>[];
+};
+type CatalogSnapshot = {
+    snapshotVersion: string;
+    catalogVersion: string;
+    label: string;
+    createdAt: string;
+    git?: SnapshotGitInfo;
+    resources: SnapshotResources;
+};
+type SnapshotOptions = {
+    label?: string;
+    outputDir?: string;
+    git?: SnapshotGitInfo;
+};
+type SnapshotResult = {
+    filePath: string;
+    snapshot: CatalogSnapshot;
+};
+type SnapshotMeta = {
+    label: string;
+    createdAt: string;
+    filePath: string;
+    git?: SnapshotGitInfo;
+};
+type SnapshotResourceType = 'event' | 'command' | 'query' | 'service' | 'domain' | 'channel';
+type ResourceChangeType = 'added' | 'removed' | 'modified' | 'versioned';
+type ResourceChange = {
+    resourceId: string;
+    version: string;
+    type: SnapshotResourceType;
+    changeType: ResourceChangeType;
+    changedFields?: string[];
+    previousVersion?: string;
+    newVersion?: string;
+};
+type RelationshipChange = {
+    serviceId: string;
+    serviceVersion: string;
+    resourceId: string;
+    resourceVersion?: string;
+    direction: 'sends' | 'receives';
+    changeType: 'added' | 'removed';
+};
+type DiffSummary = {
+    totalChanges: number;
+    resourcesAdded: number;
+    resourcesRemoved: number;
+    resourcesModified: number;
+    resourcesVersioned: number;
+    relationshipsAdded: number;
+    relationshipsRemoved: number;
+};
+type SnapshotDiff = {
+    snapshotA: {
+        label: string;
+        createdAt: string;
+    };
+    snapshotB: {
+        label: string;
+        createdAt: string;
+    };
+    summary: DiffSummary;
+    resources: ResourceChange[];
+    relationships: RelationshipChange[];
+};
+
 /**
  * Init the SDK for EventCatalog
  *
@@ -389,7 +475,13 @@ declare const _default: (path: string) => {
     writeEvent: (event: Event, options?: {
         path?: string;
         override?: boolean;
-        versionExistingContent?: boolean;
+        versionExistingContent? /**
+         * Adds an event to EventCatalog
+         *
+         * @param event - The event to write
+         * @param options - Optional options to write the event
+         *
+         */: boolean;
         format?: "md" | "mdx";
     }) => Promise<void>;
     /**
@@ -746,18 +838,7 @@ declare const _default: (path: string) => {
     addEventToChannel: (id: string, _message: {
         id: string;
         version: string;
-        parameters
-        /**
-         * Returns a query from EventCatalog
-         * @param id - The id of the query to retrieve
-         * @param version - Optional id of the version to get (supports semver)
-         * @returns Query|Undefined
-         */
-        ? /**
-         * ================================
-         *            Queries
-         * ================================
-         */: {
+        parameters?: {
             [key: string]: string;
         };
     }, version?: string) => Promise<void>;
@@ -780,18 +861,7 @@ declare const _default: (path: string) => {
     addCommandToChannel: (id: string, _message: {
         id: string;
         version: string;
-        parameters
-        /**
-         * Returns a query from EventCatalog
-         * @param id - The id of the query to retrieve
-         * @param version - Optional id of the version to get (supports semver)
-         * @returns Query|Undefined
-         */
-        ? /**
-         * ================================
-         *            Queries
-         * ================================
-         */: {
+        parameters?: {
             [key: string]: string;
         };
     }, version?: string) => Promise<void>;
@@ -814,18 +884,7 @@ declare const _default: (path: string) => {
     addQueryToChannel: (id: string, _message: {
         id: string;
         version: string;
-        parameters
-        /**
-         * Returns a query from EventCatalog
-         * @param id - The id of the query to retrieve
-         * @param version - Optional id of the version to get (supports semver)
-         * @returns Query|Undefined
-         */
-        ? /**
-         * ================================
-         *            Queries
-         * ================================
-         */: {
+        parameters?: {
             [key: string]: string;
         };
     }, version?: string) => Promise<void>;
@@ -844,15 +903,7 @@ declare const _default: (path: string) => {
     writeService: (service: Service, options?: {
         path?: string;
         override?: boolean;
-        versionExistingContent
-        /**
-         * Moves a given event id to the version directory
-         * @param directory
-         */
-        ? /**
-         * Moves a given event id to the version directory
-         * @param directory
-         */: boolean;
+        versionExistingContent?: boolean;
         format?: "md" | "mdx";
     }) => Promise<void>;
     /**
@@ -875,7 +926,14 @@ declare const _default: (path: string) => {
         version?: string;
         direction?: string;
     }, options?: {
-        path?: string;
+        path? /**
+         * Adds a command to a service in EventCatalog
+         *
+         * @param command - The command to write to the service
+         * @param service - The service and it's id to write to the command to
+         * @param options - Optional options to write the command
+         *
+         */: string;
         format?: "md" | "mdx";
         override?: boolean;
     }) => Promise<void>;
@@ -1375,6 +1433,56 @@ declare const _default: (path: string) => {
      * @returns A JSON object with the configuration for the event catalog.
      */
     getEventCatalogConfigurationFile: () => Promise<any>;
+    /**
+     * ================================
+     *            Changelogs
+     * ================================
+     */
+    /**
+     * Writes a changelog entry to a resource in EventCatalog
+     *
+     * @param id - The id of the resource to write the changelog to
+     * @param changelog - The changelog entry to write
+     * @param options - Optional options (version, format)
+     *
+     */
+    writeChangelog: (id: string, changelog: Changelog, options?: {
+        version?: string;
+        format?: "md" | "mdx";
+    }) => Promise<void>;
+    /**
+     * Appends a changelog entry to an existing changelog for a resource.
+     * If no changelog exists, one is created.
+     *
+     * @param id - The id of the resource to append the changelog to
+     * @param changelog - The changelog entry to append
+     * @param options - Optional options (version, format)
+     *
+     */
+    appendChangelog: (id: string, changelog: Changelog, options?: {
+        version?: string;
+        format?: "md" | "mdx";
+    }) => Promise<void>;
+    /**
+     * Returns the changelog for a resource in EventCatalog
+     *
+     * @param id - The id of the resource to get the changelog for
+     * @param options - Optional options (version)
+     * @returns Changelog|Undefined
+     */
+    getChangelog: (id: string, options?: {
+        version?: string;
+    }) => Promise<Changelog | undefined>;
+    /**
+     * Removes the changelog for a resource in EventCatalog
+     *
+     * @param id - The id of the resource to remove the changelog from
+     * @param options - Optional options (version)
+     *
+     */
+    rmChangelog: (id: string, options?: {
+        version?: string;
+    }) => Promise<void>;
     /**
      * ================================
      *            Resources Utils
@@ -1695,7 +1803,11 @@ declare const _default: (path: string) => {
      *
      */
     writeDiagram: (diagram: Diagram, options?: {
-        path?: string;
+        path? /**
+         * Returns all events from EventCatalog
+         * @param latestOnly - optional boolean, set to true to get only latest versions
+         * @returns Event[]|Undefined
+         */: string;
         override?: boolean;
         versionExistingContent?: boolean;
         format?: "md" | "mdx";
@@ -1755,7 +1867,10 @@ declare const _default: (path: string) => {
      * const dsl = await sdk.toDSL(services, { type: 'service', hydrate: true });
      * ```
      */
+    createSnapshot: (options?: SnapshotOptions) => Promise<SnapshotResult>;
+    diffSnapshots: (snapshotAPath: string, snapshotBPath: string) => Promise<SnapshotDiff>;
+    listSnapshots: () => Promise<SnapshotMeta[]>;
     toDSL: (resource: (Event | Command | Query | Service | Domain) | (Event | Command | Query | Service | Domain)[], options: ToDSLOptions) => Promise<string>;
 };
 
-export { type Badge, type BaseSchema, type Channel, type ChannelPointer, type Command, type Container, type CustomDoc, type DataProduct, type DataProductOutputPointer, type Diagram, type Domain, type Entity, type Event, type EventCatalog, type Message, type Operation, 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 };
+export { type Badge, type BaseSchema, type CatalogSnapshot, type Changelog, type Channel, type ChannelPointer, type Command, type Container, type CustomDoc, type DataProduct, type DataProductOutputPointer, type Diagram, type DiffSummary, type Domain, type Entity, type Event, type EventCatalog, type Message, type Operation, type Query, type ReceivesPointer, type RelationshipChange, type ResourceChange, type ResourceChangeType, type ResourceGroup, type ResourcePointer, type SendsPointer, type Service, type SnapshotDiff, type SnapshotGitInfo, type SnapshotMeta, type SnapshotOptions, type SnapshotResourceType, type SnapshotResources, type SnapshotResult, type Specification, type Specifications, type Team, type UbiquitousLanguage, type UbiquitousLanguageDictionary, type User, _default as default };

package/dist/index.d.ts

@@ -235,6 +235,12 @@ interface Badge {
   icon?: string;
 }
 
+interface Changelog {
+  createdAt: Date | string;
+  badges?: Badge[];
+  markdown: string;
+}
+
 interface UbiquitousLanguage {
   id: string;
   name: string;
@@ -354,6 +360,86 @@ interface ToDSLOptions {
     hydrate?: boolean;
 }
 
+type SnapshotGitInfo = {
+    branch: string;
+    commit: string;
+    dirty: boolean;
+};
+type SnapshotResources = {
+    domains: Record<string, any>[];
+    services: Record<string, any>[];
+    messages: {
+        events: Record<string, any>[];
+        commands: Record<string, any>[];
+        queries: Record<string, any>[];
+    };
+    channels: Record<string, any>[];
+};
+type CatalogSnapshot = {
+    snapshotVersion: string;
+    catalogVersion: string;
+    label: string;
+    createdAt: string;
+    git?: SnapshotGitInfo;
+    resources: SnapshotResources;
+};
+type SnapshotOptions = {
+    label?: string;
+    outputDir?: string;
+    git?: SnapshotGitInfo;
+};
+type SnapshotResult = {
+    filePath: string;
+    snapshot: CatalogSnapshot;
+};
+type SnapshotMeta = {
+    label: string;
+    createdAt: string;
+    filePath: string;
+    git?: SnapshotGitInfo;
+};
+type SnapshotResourceType = 'event' | 'command' | 'query' | 'service' | 'domain' | 'channel';
+type ResourceChangeType = 'added' | 'removed' | 'modified' | 'versioned';
+type ResourceChange = {
+    resourceId: string;
+    version: string;
+    type: SnapshotResourceType;
+    changeType: ResourceChangeType;
+    changedFields?: string[];
+    previousVersion?: string;
+    newVersion?: string;
+};
+type RelationshipChange = {
+    serviceId: string;
+    serviceVersion: string;
+    resourceId: string;
+    resourceVersion?: string;
+    direction: 'sends' | 'receives';
+    changeType: 'added' | 'removed';
+};
+type DiffSummary = {
+    totalChanges: number;
+    resourcesAdded: number;
+    resourcesRemoved: number;
+    resourcesModified: number;
+    resourcesVersioned: number;
+    relationshipsAdded: number;
+    relationshipsRemoved: number;
+};
+type SnapshotDiff = {
+    snapshotA: {
+        label: string;
+        createdAt: string;
+    };
+    snapshotB: {
+        label: string;
+        createdAt: string;
+    };
+    summary: DiffSummary;
+    resources: ResourceChange[];
+    relationships: RelationshipChange[];
+};
+
 /**
  * Init the SDK for EventCatalog
  *
@@ -389,7 +475,13 @@ declare const _default: (path: string) => {
     writeEvent: (event: Event, options?: {
         path?: string;
         override?: boolean;
-        versionExistingContent?: boolean;
+        versionExistingContent? /**
+         * Adds an event to EventCatalog
+         *
+         * @param event - The event to write
+         * @param options - Optional options to write the event
+         *
+         */: boolean;
         format?: "md" | "mdx";
     }) => Promise<void>;
     /**
@@ -746,18 +838,7 @@ declare const _default: (path: string) => {
     addEventToChannel: (id: string, _message: {
         id: string;
         version: string;
-        parameters
-        /**
-         * Returns a query from EventCatalog
-         * @param id - The id of the query to retrieve
-         * @param version - Optional id of the version to get (supports semver)
-         * @returns Query|Undefined
-         */
-        ? /**
-         * ================================
-         *            Queries
-         * ================================
-         */: {
+        parameters?: {
             [key: string]: string;
         };
     }, version?: string) => Promise<void>;
@@ -780,18 +861,7 @@ declare const _default: (path: string) => {
     addCommandToChannel: (id: string, _message: {
         id: string;
         version: string;
-        parameters
-        /**
-         * Returns a query from EventCatalog
-         * @param id - The id of the query to retrieve
-         * @param version - Optional id of the version to get (supports semver)
-         * @returns Query|Undefined
-         */
-        ? /**
-         * ================================
-         *            Queries
-         * ================================
-         */: {
+        parameters?: {
             [key: string]: string;
         };
     }, version?: string) => Promise<void>;
@@ -814,18 +884,7 @@ declare const _default: (path: string) => {
     addQueryToChannel: (id: string, _message: {
         id: string;
         version: string;
-        parameters
-        /**
-         * Returns a query from EventCatalog
-         * @param id - The id of the query to retrieve
-         * @param version - Optional id of the version to get (supports semver)
-         * @returns Query|Undefined
-         */
-        ? /**
-         * ================================
-         *            Queries
-         * ================================
-         */: {
+        parameters?: {
             [key: string]: string;
         };
     }, version?: string) => Promise<void>;
@@ -844,15 +903,7 @@ declare const _default: (path: string) => {
     writeService: (service: Service, options?: {
         path?: string;
         override?: boolean;
-        versionExistingContent
-        /**
-         * Moves a given event id to the version directory
-         * @param directory
-         */
-        ? /**
-         * Moves a given event id to the version directory
-         * @param directory
-         */: boolean;
+        versionExistingContent?: boolean;
         format?: "md" | "mdx";
     }) => Promise<void>;
     /**
@@ -875,7 +926,14 @@ declare const _default: (path: string) => {
         version?: string;
         direction?: string;
     }, options?: {
-        path?: string;
+        path? /**
+         * Adds a command to a service in EventCatalog
+         *
+         * @param command - The command to write to the service
+         * @param service - The service and it's id to write to the command to
+         * @param options - Optional options to write the command
+         *
+         */: string;
         format?: "md" | "mdx";
         override?: boolean;
     }) => Promise<void>;
@@ -1375,6 +1433,56 @@ declare const _default: (path: string) => {
      * @returns A JSON object with the configuration for the event catalog.
      */
     getEventCatalogConfigurationFile: () => Promise<any>;
+    /**
+     * ================================
+     *            Changelogs
+     * ================================
+     */
+    /**
+     * Writes a changelog entry to a resource in EventCatalog
+     *
+     * @param id - The id of the resource to write the changelog to
+     * @param changelog - The changelog entry to write
+     * @param options - Optional options (version, format)
+     *
+     */
+    writeChangelog: (id: string, changelog: Changelog, options?: {
+        version?: string;
+        format?: "md" | "mdx";
+    }) => Promise<void>;
+    /**
+     * Appends a changelog entry to an existing changelog for a resource.
+     * If no changelog exists, one is created.
+     *
+     * @param id - The id of the resource to append the changelog to
+     * @param changelog - The changelog entry to append
+     * @param options - Optional options (version, format)
+     *
+     */
+    appendChangelog: (id: string, changelog: Changelog, options?: {
+        version?: string;
+        format?: "md" | "mdx";
+    }) => Promise<void>;
+    /**
+     * Returns the changelog for a resource in EventCatalog
+     *
+     * @param id - The id of the resource to get the changelog for
+     * @param options - Optional options (version)
+     * @returns Changelog|Undefined
+     */
+    getChangelog: (id: string, options?: {
+        version?: string;
+    }) => Promise<Changelog | undefined>;
+    /**
+     * Removes the changelog for a resource in EventCatalog
+     *
+     * @param id - The id of the resource to remove the changelog from
+     * @param options - Optional options (version)
+     *
+     */
+    rmChangelog: (id: string, options?: {
+        version?: string;
+    }) => Promise<void>;
     /**
      * ================================
      *            Resources Utils
@@ -1695,7 +1803,11 @@ declare const _default: (path: string) => {
      *
      */
     writeDiagram: (diagram: Diagram, options?: {
-        path?: string;
+        path? /**
+         * Returns all events from EventCatalog
+         * @param latestOnly - optional boolean, set to true to get only latest versions
+         * @returns Event[]|Undefined
+         */: string;
         override?: boolean;
         versionExistingContent?: boolean;
         format?: "md" | "mdx";
@@ -1755,7 +1867,10 @@ declare const _default: (path: string) => {
      * const dsl = await sdk.toDSL(services, { type: 'service', hydrate: true });
      * ```
      */
+    createSnapshot: (options?: SnapshotOptions) => Promise<SnapshotResult>;
+    diffSnapshots: (snapshotAPath: string, snapshotBPath: string) => Promise<SnapshotDiff>;
+    listSnapshots: () => Promise<SnapshotMeta[]>;
     toDSL: (resource: (Event | Command | Query | Service | Domain) | (Event | Command | Query | Service | Domain)[], options: ToDSLOptions) => Promise<string>;
 };
 
-export { type Badge, type BaseSchema, type Channel, type ChannelPointer, type Command, type Container, type CustomDoc, type DataProduct, type DataProductOutputPointer, type Diagram, type Domain, type Entity, type Event, type EventCatalog, type Message, type Operation, 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 };
+export { type Badge, type BaseSchema, type CatalogSnapshot, type Changelog, type Channel, type ChannelPointer, type Command, type Container, type CustomDoc, type DataProduct, type DataProductOutputPointer, type Diagram, type DiffSummary, type Domain, type Entity, type Event, type EventCatalog, type Message, type Operation, type Query, type ReceivesPointer, type RelationshipChange, type ResourceChange, type ResourceChangeType, type ResourceGroup, type ResourcePointer, type SendsPointer, type Service, type SnapshotDiff, type SnapshotGitInfo, type SnapshotMeta, type SnapshotOptions, type SnapshotResourceType, type SnapshotResources, type SnapshotResult, type Specification, type Specifications, type Team, type UbiquitousLanguage, type UbiquitousLanguageDictionary, type User, _default as default };