@eventcatalog/sdk 2.19.0 → 2.21.0

package/dist/index.d.mts

@@ -173,6 +173,7 @@ interface Service extends BaseSchema {
   writesTo?: ResourcePointer[];
   readsFrom?: ResourcePointer[];
   flows?: ResourcePointer[];
+  externalSystem?: boolean;
   specifications?: Specifications | Specification[];
   detailsPanel?: {
     domains?: DetailPanelProperty;
@@ -495,6 +496,364 @@ type SnapshotDiff = {
     relationships: RelationshipChange[];
 };
 
+type FlowStepId = string | number;
+type FlowStepPointer = FlowStepId | {
+    id: FlowStepId;
+    label?: string;
+};
+/**
+ * Input used to create a flow builder.
+ *
+ * This is the normal `Flow` resource shape without requiring `steps` up front.
+ * You can pass existing steps if you want to append to a partially built flow.
+ */
+type FlowBuilderInput = Omit<Flow, 'steps'> & {
+    steps?: FlowStep[];
+};
+/**
+ * Payload for a generic flow step.
+ *
+ * Use generic steps for process milestones that are not messages, services,
+ * actors, external systems, sub-flows, or custom nodes.
+ */
+type FlowStepInput = {
+    id: FlowStepId;
+    title?: string;
+    summary?: string;
+    nextSteps?: FlowStepPointer[];
+};
+/**
+ * Payload for a flow step that references an event, command, or query.
+ */
+type FlowMessageStepInput<TMessageId extends string = string> = FlowStepInput & {
+    message?: {
+        id: TMessageId;
+        version?: string;
+    };
+    version?: string;
+};
+/**
+ * Payload for a flow step that references a service.
+ */
+type FlowServiceStepInput = FlowStepInput & {
+    service?: {
+        id: string;
+        version?: string;
+    };
+    version?: string;
+};
+/**
+ * Payload for a flow step that represents a user or actor.
+ */
+type FlowActorStepInput = FlowStepInput & {
+    actor?: {
+        name: string;
+        summary?: string;
+    };
+    name?: string;
+};
+/**
+ * Payload for a flow step that represents an external system.
+ */
+type FlowExternalSystemStepInput = FlowStepInput & {
+    externalSystem?: {
+        name: string;
+        summary?: string;
+        url?: string;
+    };
+    name?: string;
+    url?: string;
+};
+/**
+ * Payload for a flow step that references another flow.
+ */
+type FlowSubFlowStepInput = FlowStepInput & {
+    flow?: {
+        id: string;
+        version?: string;
+    };
+    version?: string;
+};
+/**
+ * Payload for a custom flow step.
+ */
+type FlowCustomStepInput = FlowStepInput & {
+    custom?: {
+        title: string;
+        icon?: string;
+        type?: string;
+        summary?: string;
+        url?: string;
+        color?: string;
+        properties?: Record<string, string | number>;
+        height?: number;
+        menu?: {
+            label: string;
+            url?: string;
+        }[];
+    };
+    icon?: string;
+    type?: string;
+    url?: string;
+    color?: string;
+    properties?: Record<string, string | number>;
+    height?: number;
+    menu?: {
+        label: string;
+        url?: string;
+    }[];
+};
+/**
+ * Build EventCatalog flow resources using a fluent API.
+ *
+ * `FlowBuilder` is useful when you want to define flows in code and then write
+ * the generated `Flow` resource with `writeFlow`. The builder outputs the normal
+ * EventCatalog `Flow` shape, so the persisted catalog remains standard
+ * markdown/frontmatter.
+ *
+ * `nextSteps` is the authoring API. When `build()` is called, a single next step
+ * is normalized to `next_step` and multiple next steps are normalized to
+ * `next_steps`.
+ *
+ * @example
+ * ```ts
+ * import utils, { FlowBuilder } from '@eventcatalog/sdk';
+ *
+ * const { writeFlow } = utils('/path/to/eventcatalog');
+ *
+ * const flow = FlowBuilder.create({
+ *   id: 'PaymentFlow',
+ *   name: 'Payment Flow',
+ *   version: '1.0.0',
+ *   markdown: '# Payment Flow',
+ * })
+ *   .addStep({
+ *     id: 'Customer places order',
+ *     nextSteps: [{ id: 'PlaceOrder', label: 'places order' }],
+ *   })
+ *   .addMessageStep({
+ *     id: 'PlaceOrder',
+ *     message: { id: 'PlaceOrder' },
+ *     nextSteps: [{ id: 'PaymentService', label: 'process payment' }],
+ *   })
+ *   .addServiceStep({
+ *     id: 'PaymentService',
+ *     service: { id: 'PaymentService' },
+ *   })
+ *   .build();
+ *
+ * await writeFlow(flow);
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { FlowBuilder } from '@eventcatalog/sdk';
+ *
+ * type PaymentMessageId = 'PlaceOrder' | 'PaymentProcessed';
+ *
+ * const flow = FlowBuilder.create<PaymentMessageId>({
+ *   id: 'TypedPaymentFlow',
+ *   name: 'Typed Payment Flow',
+ *   version: '1.0.0',
+ *   markdown: '# Typed Payment Flow',
+ * })
+ *   .addMessageStep({
+ *     id: 'PlaceOrder',
+ *     nextSteps: [{ id: 'PaymentProcessed' }],
+ *   })
+ *   .addMessageStep({
+ *     id: 'PaymentProcessed',
+ *   })
+ *   .build();
+ * ```
+ */
+declare class FlowBuilder<TMessageId extends string = string> {
+    private readonly flowResource;
+    private readonly steps;
+    private readonly order;
+    private constructor();
+    /**
+     * Create a flow builder.
+     *
+     * The created builder can add steps and then produce a normal `Flow` resource
+     * with `build()`.
+     *
+     * @example
+     * ```ts
+     * const flow = FlowBuilder.create({
+     *   id: 'PaymentFlow',
+     *   name: 'Payment Flow',
+     *   version: '1.0.0',
+     *   markdown: '# Payment Flow',
+     * }).build();
+     * ```
+     */
+    static create<TMessageId extends string = string>(flow: FlowBuilderInput): FlowBuilder<TMessageId>;
+    /**
+     * Add a generic flow step.
+     *
+     * Generic steps are useful for business process stages that do not map to
+     * another catalog resource.
+     *
+     * @param step - The step payload.
+     *
+     * @example
+     * ```ts
+     * FlowBuilder.create({
+     *   id: 'OrderFlow',
+     *   name: 'Order Flow',
+     *   version: '1.0.0',
+     *   markdown: '',
+     * })
+     *   .addStep({
+     *     id: 'Calculate',
+     *     title: 'Calculate totals',
+     *     nextSteps: [{ id: 'OrderConfirmed' }],
+     *   });
+     * ```
+     */
+    addStep(step: FlowStepInput): this;
+    /**
+     * Add a message step.
+     *
+     * Message steps can reference an event, command, or query id.
+     *
+     * @param step - The message step payload.
+     *
+     * @example
+     * ```ts
+     * FlowBuilder.create({
+     *   id: 'OrderFlow',
+     *   name: 'Order Flow',
+     *   version: '1.0.0',
+     *   markdown: '',
+     * })
+     *   .addMessageStep({
+     *     id: 'OrderConfirmed',
+     *     title: 'Order confirmed',
+     *     message: { id: 'OrderConfirmed', version: '1.0.0' },
+     *   });
+     * ```
+     */
+    addMessageStep(step: FlowMessageStepInput<TMessageId>): this;
+    /**
+     * Add a service step.
+     *
+     * @param step - The service step payload.
+     *
+     * @example
+     * ```ts
+     * FlowBuilder.create({
+     *   id: 'OrderFlow',
+     *   name: 'Order Flow',
+     *   version: '1.0.0',
+     *   markdown: '',
+     * })
+     *   .addServiceStep({
+     *     id: 'OrderService',
+     *     service: { id: 'OrderService', version: '1.0.0' },
+     *   });
+     * ```
+     */
+    addServiceStep(step: FlowServiceStepInput): this;
+    /**
+     * Add an actor step.
+     *
+     * @param step - The actor step payload.
+     *
+     * @example
+     * ```ts
+     * FlowBuilder.create({
+     *   id: 'OrderFlow',
+     *   name: 'Order Flow',
+     *   version: '1.0.0',
+     *   markdown: '',
+     * })
+     *   .addActorStep({
+     *     id: 'Customer',
+     *     actor: { name: 'Customer' },
+     *   });
+     * ```
+     */
+    addActorStep(step: FlowActorStepInput): this;
+    /**
+     * Add an external system step.
+     *
+     * @param step - The external system step payload.
+     *
+     * @example
+     * ```ts
+     * FlowBuilder.create({
+     *   id: 'PaymentFlow',
+     *   name: 'Payment Flow',
+     *   version: '1.0.0',
+     *   markdown: '',
+     * })
+     *   .addExternalSystemStep({
+     *     id: 'Stripe',
+     *     externalSystem: {
+     *       name: 'Stripe',
+     *       summary: 'Payment provider',
+     *       url: 'https://stripe.com',
+     *     },
+     *   });
+     * ```
+     */
+    addExternalSystemStep(step: FlowExternalSystemStepInput): this;
+    /**
+     * Add a sub-flow step.
+     *
+     * @param step - The sub-flow step payload.
+     *
+     * @example
+     * ```ts
+     * FlowBuilder.create({
+     *   id: 'OrderFlow',
+     *   name: 'Order Flow',
+     *   version: '1.0.0',
+     *   markdown: '',
+     * })
+     *   .addFlowStep({
+     *     id: 'PaymentFlow',
+     *     flow: { id: 'PaymentFlow', version: '1.0.0' },
+     *   });
+     * ```
+     */
+    addFlowStep(step: FlowSubFlowStepInput): this;
+    /**
+     * Add a custom flow step.
+     *
+     * @param step - The custom step payload.
+     *
+     * @example
+     * ```ts
+     * FlowBuilder.create({
+     *   id: 'PaymentFlow',
+     *   name: 'Payment Flow',
+     *   version: '1.0.0',
+     *   markdown: '',
+     * })
+     *   .addCustomStep({
+     *     id: 'ManualReview',
+     *     custom: {
+     *       title: 'Manual review',
+     *       type: 'manual',
+     *     },
+     *   });
+     * ```
+     */
+    addCustomStep(step: FlowCustomStepInput): this;
+    /**
+     * Build the EventCatalog flow resource.
+     *
+     * @returns A `Flow` resource that can be written with `writeFlow`.
+     */
+    build(): Flow;
+    private addStepWithNext;
+    private appendStep;
+    private validateNextSteps;
+}
+
 /**
  * Init the SDK for EventCatalog
  *
@@ -1224,10 +1583,17 @@ declare const _default: (path: string) => {
      */
     writeDomain: (domain: Domain, options?: {
         path?: string;
-        override? /**
-         * Remove an event by an Event id
+        override
+        /**
+         * Remove an event to EventCatalog (modeled on the standard POSIX rm utility)
          *
-         * @param id - The id of the event you want to remove
+         * @param path - The path to your event, e.g. `/Inventory/InventoryAdjusted`
+         *
+         */
+        ? /**
+         * Remove an event to EventCatalog (modeled on the standard POSIX rm utility)
+         *
+         * @param path - The path to your event, e.g. `/Inventory/InventoryAdjusted`
          *
          */: boolean;
         versionExistingContent?: boolean;
@@ -1724,6 +2090,95 @@ declare const _default: (path: string) => {
     getFlows: (options?: {
         latestOnly?: boolean;
     }) => Promise<Flow[]>;
+    /**
+     * Adds a flow to EventCatalog
+     *
+     * @param flow - The flow to write
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlow: (flow: Flow, options?: {
+        path?: string;
+        override?: boolean;
+        versionExistingContent?: boolean;
+        format?: "md" | "mdx";
+    }) => Promise<void>;
+    /**
+     * Adds a versioned flow to EventCatalog
+     *
+     * @param flow - The flow to write
+     *
+     */
+    writeVersionedFlow: (flow: Flow) => Promise<void>;
+    /**
+     * Adds a flow to a domain in EventCatalog
+     *
+     * @param flow - The flow to write to the domain
+     * @param domain - The domain and its id to write the flow to
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlowToDomain: (flow: Flow, domain: {
+        id: string;
+        version?: string;
+    }, options?: {
+        path?: string;
+        format?: "md" | "mdx";
+        override?: boolean;
+    }) => Promise<void>;
+    /**
+     * Adds a flow to a service in EventCatalog
+     *
+     * @param flow - The flow to write to the service
+     * @param service - The service and its id to write the flow to
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlowToService: (flow: Flow, service: {
+        id: string;
+        version?: string;
+    }, options?: {
+        path?: string;
+        format?: "md" | "mdx";
+        override?: boolean;
+    }) => Promise<void>;
+    /**
+     * Remove a flow from EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your flow, e.g. `/PaymentFlow`
+     *
+     */
+    rmFlow: (path: string) => Promise<void>;
+    /**
+     * Remove a flow by a flow id
+     *
+     * @param id - The id of the flow you want to remove
+     *
+     */
+    rmFlowById: (id: string, version?: string, persistFiles?: boolean) => Promise<void>;
+    /**
+     * Moves a given flow id to the version directory
+     * @param id - The id of the flow to version
+     */
+    versionFlow: (id: string) => Promise<void>;
+    /**
+     * Check to see if a flow version exists
+     * @param id - The id of the flow
+     * @param version - The version of the flow (supports semver)
+     * @returns
+     */
+    flowHasVersion: (id: string, version?: string) => Promise<boolean>;
+    /**
+     * Adds a file to the given flow
+     * @param id - The id of the flow to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the flow to add the file to
+     * @returns
+     */
+    addFileToFlow: (id: string, file: {
+        content: string;
+        fileName: string;
+    }, version?: string) => Promise<void>;
     /**
      * ================================
      *            Data Stores
@@ -1801,7 +2256,12 @@ declare const _default: (path: string) => {
     }, options?: {
         path?: string;
         format?: "md" | "mdx";
-        override?: boolean;
+        override? /**
+         * Returns a command from EventCatalog
+         * @param id - The id of the command to retrieve
+         * @param version - Optional id of the version to get (supports semver)
+         * @returns Command|Undefined
+         */: boolean;
     }) => Promise<void>;
     /**
      * ================================
@@ -1989,4 +2449,4 @@ declare const _default: (path: string) => {
     toDSL: (resource: (Event | Command | Query | Service | Domain) | (Event | Command | Query | Service | Domain)[], options: ToDSLOptions) => Promise<string>;
 };
 
-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 Flow, type FlowStep, 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 };
+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 Flow, type FlowActorStepInput, FlowBuilder, type FlowBuilderInput, type FlowCustomStepInput, type FlowExternalSystemStepInput, type FlowMessageStepInput, type FlowServiceStepInput, type FlowStep, type FlowStepInput, type FlowSubFlowStepInput, 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 };