@eventcatalog/sdk 2.17.3 → 2.18.0

package/dist/index.d.mts

@@ -54,12 +54,14 @@ type ResourcePointer = {
 type SendsPointer = {
   id: string;
   version?: string;
+  fields?: string[];
   to?: ChannelPointer[];
 };
 
 type ReceivesPointer = {
   id: string;
   version?: string;
+  fields?: string[];
   from?: ChannelPointer[];
 };
 
@@ -103,6 +105,9 @@ interface MessageDetailsPanelProperty {
   channels?: DetailPanelProperty;
   versions?: DetailPanelProperty;
   repository?: DetailPanelProperty;
+  owners?: DetailPanelProperty;
+  changelog?: DetailPanelProperty;
+  attachments?: DetailPanelProperty;
 }
 
 interface Event extends BaseSchema {
@@ -473,7 +478,11 @@ declare const _default: (path: string) => {
      *
      */
     writeEvent: (event: Event, 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";
@@ -490,7 +499,12 @@ declare const _default: (path: string) => {
         id: string;
         version?: string;
     }, options?: {
-        path?: string;
+        path? /**
+         * Remove an event by an Event id
+         *
+         * @param id - The id of the event you want to remove
+         *
+         */: string;
         format?: "md" | "mdx";
         override?: boolean;
     }) => Promise<void>;
@@ -546,6 +560,15 @@ declare const _default: (path: string) => {
      * @returns
      */
     eventHasVersion: (id: string, version?: string) => Promise<boolean>;
+    addExampleToEvent: (id: string, example: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
+    getExamplesFromEvent: (id: string, version?: string) => Promise<{
+        fileName: string;
+        content: string;
+    }[]>;
+    removeExampleFromEvent: (id: string, fileName: string, version?: string) => Promise<void>;
     /**
      * ================================
      *            Commands
@@ -650,6 +673,15 @@ declare const _default: (path: string) => {
      * @returns
      */
     commandHasVersion: (id: string, version?: string) => Promise<boolean>;
+    addExampleToCommand: (id: string, example: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
+    getExamplesFromCommand: (id: string, version?: string) => Promise<{
+        fileName: string;
+        content: string;
+    }[]>;
+    removeExampleFromCommand: (id: string, fileName: string, version?: string) => Promise<void>;
     /**
      * ================================
      *            Queries
@@ -754,6 +786,15 @@ declare const _default: (path: string) => {
      * @returns
      */
     queryHasVersion: (id: string, version?: string) => Promise<boolean>;
+    addExampleToQuery: (id: string, example: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
+    getExamplesFromQuery: (id: string, version?: string) => Promise<{
+        fileName: string;
+        content: string;
+    }[]>;
+    removeExampleFromQuery: (id: string, fileName: string, version?: string) => Promise<void>;
     /**
      * ================================
      *            Channels
@@ -1011,6 +1052,12 @@ declare const _default: (path: string) => {
     addEventToService: (id: string, direction: string, event: {
         id: string;
         version: string;
+        fields? /**
+         * Remove an channel to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your channel, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a data store to a service by it's id.
@@ -1054,6 +1101,12 @@ declare const _default: (path: string) => {
     addCommandToService: (id: string, direction: string, event: {
         id: string;
         version: string;
+        fields? /**
+         * Remove an channel to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your channel, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a query to a service by it's id.
@@ -1077,6 +1130,12 @@ declare const _default: (path: string) => {
     addQueryToService: (id: string, direction: string, event: {
         id: string;
         version: string;
+        fields? /**
+         * Remove an channel to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your channel, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add an entity to a service by its id.
@@ -1261,6 +1320,7 @@ declare const _default: (path: string) => {
     addEventToDomain: (id: string, direction: string, message: {
         id: string;
         version: string;
+        fields?: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a command to a domain by its id.
@@ -1282,6 +1342,7 @@ declare const _default: (path: string) => {
     addCommandToDomain: (id: string, direction: string, message: {
         id: string;
         version: string;
+        fields?: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a query to a domain by its id.
@@ -1303,6 +1364,7 @@ declare const _default: (path: string) => {
     addQueryToDomain: (id: string, direction: string, message: {
         id: string;
         version: string;
+        fields?: string[];
     }, version?: string) => Promise<void>;
     /**
      * ================================
@@ -1678,7 +1740,11 @@ declare const _default: (path: string) => {
         version?: string;
     }, options?: {
         path?: string;
-        format?: "md" | "mdx";
+        format? /**
+         * Returns all commands from EventCatalog
+         * @param latestOnly - optional boolean, set to true to get only latest versions
+         * @returns Command[]|Undefined
+         */: "md" | "mdx";
         override?: boolean;
     }) => Promise<void>;
     /**

package/dist/index.d.ts

@@ -54,12 +54,14 @@ type ResourcePointer = {
 type SendsPointer = {
   id: string;
   version?: string;
+  fields?: string[];
   to?: ChannelPointer[];
 };
 
 type ReceivesPointer = {
   id: string;
   version?: string;
+  fields?: string[];
   from?: ChannelPointer[];
 };
 
@@ -103,6 +105,9 @@ interface MessageDetailsPanelProperty {
   channels?: DetailPanelProperty;
   versions?: DetailPanelProperty;
   repository?: DetailPanelProperty;
+  owners?: DetailPanelProperty;
+  changelog?: DetailPanelProperty;
+  attachments?: DetailPanelProperty;
 }
 
 interface Event extends BaseSchema {
@@ -473,7 +478,11 @@ declare const _default: (path: string) => {
      *
      */
     writeEvent: (event: Event, 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";
@@ -490,7 +499,12 @@ declare const _default: (path: string) => {
         id: string;
         version?: string;
     }, options?: {
-        path?: string;
+        path? /**
+         * Remove an event by an Event id
+         *
+         * @param id - The id of the event you want to remove
+         *
+         */: string;
         format?: "md" | "mdx";
         override?: boolean;
     }) => Promise<void>;
@@ -546,6 +560,15 @@ declare const _default: (path: string) => {
      * @returns
      */
     eventHasVersion: (id: string, version?: string) => Promise<boolean>;
+    addExampleToEvent: (id: string, example: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
+    getExamplesFromEvent: (id: string, version?: string) => Promise<{
+        fileName: string;
+        content: string;
+    }[]>;
+    removeExampleFromEvent: (id: string, fileName: string, version?: string) => Promise<void>;
     /**
      * ================================
      *            Commands
@@ -650,6 +673,15 @@ declare const _default: (path: string) => {
      * @returns
      */
     commandHasVersion: (id: string, version?: string) => Promise<boolean>;
+    addExampleToCommand: (id: string, example: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
+    getExamplesFromCommand: (id: string, version?: string) => Promise<{
+        fileName: string;
+        content: string;
+    }[]>;
+    removeExampleFromCommand: (id: string, fileName: string, version?: string) => Promise<void>;
     /**
      * ================================
      *            Queries
@@ -754,6 +786,15 @@ declare const _default: (path: string) => {
      * @returns
      */
     queryHasVersion: (id: string, version?: string) => Promise<boolean>;
+    addExampleToQuery: (id: string, example: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
+    getExamplesFromQuery: (id: string, version?: string) => Promise<{
+        fileName: string;
+        content: string;
+    }[]>;
+    removeExampleFromQuery: (id: string, fileName: string, version?: string) => Promise<void>;
     /**
      * ================================
      *            Channels
@@ -1011,6 +1052,12 @@ declare const _default: (path: string) => {
     addEventToService: (id: string, direction: string, event: {
         id: string;
         version: string;
+        fields? /**
+         * Remove an channel to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your channel, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a data store to a service by it's id.
@@ -1054,6 +1101,12 @@ declare const _default: (path: string) => {
     addCommandToService: (id: string, direction: string, event: {
         id: string;
         version: string;
+        fields? /**
+         * Remove an channel to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your channel, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a query to a service by it's id.
@@ -1077,6 +1130,12 @@ declare const _default: (path: string) => {
     addQueryToService: (id: string, direction: string, event: {
         id: string;
         version: string;
+        fields? /**
+         * Remove an channel to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your channel, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add an entity to a service by its id.
@@ -1261,6 +1320,7 @@ declare const _default: (path: string) => {
     addEventToDomain: (id: string, direction: string, message: {
         id: string;
         version: string;
+        fields?: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a command to a domain by its id.
@@ -1282,6 +1342,7 @@ declare const _default: (path: string) => {
     addCommandToDomain: (id: string, direction: string, message: {
         id: string;
         version: string;
+        fields?: string[];
     }, version?: string) => Promise<void>;
     /**
      * Add a query to a domain by its id.
@@ -1303,6 +1364,7 @@ declare const _default: (path: string) => {
     addQueryToDomain: (id: string, direction: string, message: {
         id: string;
         version: string;
+        fields?: string[];
     }, version?: string) => Promise<void>;
     /**
      * ================================
@@ -1678,7 +1740,11 @@ declare const _default: (path: string) => {
         version?: string;
     }, options?: {
         path?: string;
-        format?: "md" | "mdx";
+        format? /**
+         * Returns all commands from EventCatalog
+         * @param latestOnly - optional boolean, set to true to get only latest versions
+         * @returns Command[]|Undefined
+         */: "md" | "mdx";
         override?: boolean;
     }) => Promise<void>;
     /**

package/dist/index.js

@@ -862,6 +862,11 @@ var copyDir = async (catalogDir, source, target, filter) => {
   });
   import_node_fs.default.rmSync(tmpDirectory, { recursive: true });
 };
+var buildMessagePointer = (message) => {
+  const pointer = { id: message.id, version: message.version };
+  if (message.fields) pointer.fields = message.fields;
+  return pointer;
+};
 var uniqueVersions = (messages) => {
   const uniqueSet = /* @__PURE__ */ new Set();
   return messages.filter((message) => {
@@ -1096,6 +1101,55 @@ var getFileFromResource = async (catalogDir, id, file, version) => {
 var getVersionedDirectory = (sourceDirectory, version) => {
   return (0, import_path.join)(sourceDirectory, "versioned", version);
 };
+var CONFIG_FILES = ["examples.config.yaml", "examples.config.yml", "examples.config.json"];
+function resolveExamplePath(examplesDir, fileName) {
+  const resolved = import_node_path3.default.resolve(examplesDir, fileName);
+  if (!resolved.startsWith(import_node_path3.default.resolve(examplesDir) + import_node_path3.default.sep) && resolved !== import_node_path3.default.resolve(examplesDir)) {
+    throw new Error(`Invalid example fileName: path traversal detected in "${fileName}"`);
+  }
+  return resolved;
+}
+var addExampleToResource = async (catalogDir, id, example, version) => {
+  const pathToResource = await findFileById(catalogDir, id, version);
+  if (!pathToResource) throw new Error("Cannot find directory to write example to");
+  const examplesDir = (0, import_path.join)((0, import_path.dirname)(pathToResource), "examples");
+  const targetPath = resolveExamplePath(examplesDir, example.fileName);
+  import_node_fs2.default.mkdirSync(import_node_path3.default.dirname(targetPath), { recursive: true });
+  import_node_fs2.default.writeFileSync(targetPath, example.content);
+};
+var getExamplesFromResource = async (catalogDir, id, version) => {
+  const pathToResource = await findFileById(catalogDir, id, version);
+  if (!pathToResource) throw new Error("Cannot find resource");
+  const examplesDir = (0, import_path.join)((0, import_path.dirname)(pathToResource), "examples");
+  if (!import_node_fs2.default.existsSync(examplesDir)) return [];
+  const collectFiles = (dir, baseDir) => {
+    const results = [];
+    const entries = import_node_fs2.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = (0, import_path.join)(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...collectFiles(fullPath, baseDir));
+      } else if (entry.isFile() && !CONFIG_FILES.includes(entry.name)) {
+        results.push({
+          fileName: import_node_path3.default.relative(baseDir, fullPath),
+          content: import_node_fs2.default.readFileSync(fullPath, "utf-8")
+        });
+      }
+    }
+    return results;
+  };
+  return collectFiles(examplesDir, examplesDir).sort((a, b) => a.fileName.localeCompare(b.fileName));
+};
+var removeExampleFromResource = async (catalogDir, id, fileName, version) => {
+  const pathToResource = await findFileById(catalogDir, id, version);
+  if (!pathToResource) throw new Error("Cannot find resource");
+  const examplesDir = (0, import_path.join)((0, import_path.dirname)(pathToResource), "examples");
+  const examplePath = resolveExamplePath(examplesDir, fileName);
+  if (!import_node_fs2.default.existsSync(examplePath)) {
+    throw new Error(`Example file ${fileName} does not exist in resource ${id}${version ? ` v(${version})` : ""}`);
+  }
+  import_node_fs2.default.unlinkSync(examplePath);
+};
 var isLatestVersion = async (catalogDir, id, version) => {
   const resource = await getResource(catalogDir, id, version);
   if (!resource) return false;
@@ -1136,6 +1190,9 @@ var eventHasVersion = (directory) => async (id, version) => {
   const file = await findFileById(directory, id, version);
   return !!file;
 };
+var addExampleToEvent = (directory) => async (id, example, version) => addExampleToResource(directory, id, example, version);
+var getExamplesFromEvent = (directory) => async (id, version) => getExamplesFromResource(directory, id, version);
+var removeExampleFromEvent = (directory) => async (id, fileName, version) => removeExampleFromResource(directory, id, fileName, version);
 
 // src/commands.ts
 var import_promises3 = __toESM(require("fs/promises"));
@@ -1171,6 +1228,9 @@ var commandHasVersion = (directory) => async (id, version) => {
   const file = await findFileById(directory, id, version);
   return !!file;
 };
+var addExampleToCommand = (directory) => async (id, example, version) => addExampleToResource(directory, id, example, version);
+var getExamplesFromCommand = (directory) => async (id, version) => getExamplesFromResource(directory, id, version);
+var removeExampleFromCommand = (directory) => async (id, fileName, version) => removeExampleFromResource(directory, id, fileName, version);
 
 // src/queries.ts
 var import_promises4 = __toESM(require("fs/promises"));
@@ -1208,6 +1268,9 @@ var queryHasVersion = (directory) => async (id, version) => {
   const file = await findFileById(directory, id, version);
   return !!file;
 };
+var addExampleToQuery = (directory) => async (id, example, version) => addExampleToResource(directory, id, example, version);
+var getExamplesFromQuery = (directory) => async (id, version) => getExamplesFromResource(directory, id, version);
+var removeExampleFromQuery = (directory) => async (id, fileName, version) => removeExampleFromResource(directory, id, fileName, version);
 
 // src/services.ts
 var import_promises5 = __toESM(require("fs/promises"));
@@ -1306,7 +1369,7 @@ var addMessageToService = (directory) => async (id, direction, event, version) =
         return;
       }
     }
-    service.sends.push({ id: event.id, version: event.version });
+    service.sends.push(buildMessagePointer(event));
   } else if (direction === "receives") {
     if (service.receives === void 0) {
       service.receives = [];
@@ -1316,7 +1379,7 @@ var addMessageToService = (directory) => async (id, direction, event, version) =
         return;
       }
     }
-    service.receives.push({ id: event.id, version: event.version });
+    service.receives.push(buildMessagePointer(event));
   } else {
     throw new Error(`Direction ${direction} is invalid, only 'receives' and 'sends' are supported`);
   }
@@ -1536,7 +1599,7 @@ var addMessageToDomain = (directory) => async (id, direction, message, version)
         return;
       }
     }
-    domain.sends.push({ id: message.id, version: message.version });
+    domain.sends.push(buildMessagePointer(message));
   } else if (direction === "receives") {
     if (domain.receives === void 0) {
       domain.receives = [];
@@ -1546,7 +1609,7 @@ var addMessageToDomain = (directory) => async (id, direction, message, version)
         return;
       }
     }
-    domain.receives.push({ id: message.id, version: message.version });
+    domain.receives.push(buildMessagePointer(message));
   } else {
     throw new Error(`Direction ${direction} is invalid, only 'receives' and 'sends' are supported`);
   }
@@ -2592,6 +2655,9 @@ var src_default = (path8) => {
      * @returns
      */
     eventHasVersion: eventHasVersion((0, import_node_path22.join)(path8)),
+    addExampleToEvent: addExampleToEvent((0, import_node_path22.join)(path8)),
+    getExamplesFromEvent: getExamplesFromEvent((0, import_node_path22.join)(path8)),
+    removeExampleFromEvent: removeExampleFromEvent((0, import_node_path22.join)(path8)),
     /**
      * ================================
      *            Commands
@@ -2669,6 +2735,9 @@ var src_default = (path8) => {
      * @returns
      */
     commandHasVersion: commandHasVersion((0, import_node_path22.join)(path8)),
+    addExampleToCommand: addExampleToCommand((0, import_node_path22.join)(path8)),
+    getExamplesFromCommand: getExamplesFromCommand((0, import_node_path22.join)(path8)),
+    removeExampleFromCommand: removeExampleFromCommand((0, import_node_path22.join)(path8)),
     /**
      * ================================
      *            Queries
@@ -2746,6 +2815,9 @@ var src_default = (path8) => {
      * @returns
      */
     queryHasVersion: queryHasVersion((0, import_node_path22.join)(path8)),
+    addExampleToQuery: addExampleToQuery((0, import_node_path22.join)(path8)),
+    getExamplesFromQuery: getExamplesFromQuery((0, import_node_path22.join)(path8)),
+    removeExampleFromQuery: removeExampleFromQuery((0, import_node_path22.join)(path8)),
     /**
      * ================================
      *            Channels