docs: support version in events reference (#12422)

* docs: support version in events reference * remove changes in events output * remove events emitted in comments * remove customer updated event * check for emitEventStep usage * fixes
2025-05-09 14:34:15 +03:00
parent 091041f2da
commit e09b2a4db5
24 changed files with 91 additions and 636 deletions
--- a/www/utils/generated/events-output.json
+++ b/www/utils/generated/events-output.json
@@ -24,17 +24,6 @@
    ],
    "deprecated": false
  },
-  {
-    "name": "cart.customer_updated",
-    "parentName": "CartWorkflowEvents",
-    "propertyName": "CUSTOMER_UPDATED",
-    "payload": "```ts\n{\n  id, // The ID of the cart\n}\n```",
-    "description": "Emitted when the customer in the cart is updated.",
-    "workflows": [
-      "updateCartWorkflow"
-    ],
-    "deprecated": false
-  },
  {
    "name": "cart.region_updated",
    "parentName": "CartWorkflowEvents",
@@ -233,7 +222,7 @@
    "name": "order-edit.confirmed",
    "parentName": "OrderEditWorkflowEvents",
    "propertyName": "CONFIRMED",
-    "payload": "```ts\n{\n  order_id, // The ID of the order\n  actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order\n}\n```",
+    "payload": "```ts\n{\n  order_id, // The ID of the order\n  actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order\n```",
    "description": "Emitted when an order edit request is confirmed.",
    "workflows": [
      "confirmOrderEditRequestWorkflow"
--- a/www/utils/generated/oas-output/operations/admin/delete_admin_order-edits_[id].ts
+++ b/www/utils/generated/oas-output/operations/admin/delete_admin_order-edits_[id].ts
@@ -79,17 +79,6 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: cancelBeginOrderEditWorkflow
- * x-events:
- *   - name: order-edit.canceled
- *     payload: |-
- *       ```ts
- *       {
- *         order_id, // The ID of the order
- *         actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order
- *       }
- *       ```
- *     description: Emitted when an order edit request is canceled.
- *     deprecated: false
 * 
 */

--- a/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_confirm.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_confirm.ts
@@ -60,16 +60,6 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: confirmOrderEditRequestWorkflow
- * x-events:
- *   - name: order-edit.confirmed
- *     payload: |-
- *       ```ts
- *       {
- *         order_id, // The ID of the order
- *         actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order
- *       ```
- *     description: Emitted when an order edit request is confirmed.
- *     deprecated: false
 * 
 */

--- a/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_request.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_request.ts
@@ -60,17 +60,6 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: requestOrderEditRequestWorkflow
- * x-events:
- *   - name: order-edit.requested
- *     payload: |-
- *       ```ts
- *       {
- *         order_id, // The ID of the order
- *         actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order
- *       }
- *       ```
- *     description: Emitted when an order edit is requested.
- *     deprecated: false
 * 
 */

--- a/www/utils/generated/oas-output/operations/store/post_store_carts_[id].ts
+++ b/www/utils/generated/oas-output/operations/store/post_store_carts_[id].ts
@@ -113,15 +113,6 @@
 *       ```
 *     description: Emitted when a cart's details are updated.
 *     deprecated: false
- *   - name: cart.customer_updated
- *     payload: |-
- *       ```ts
- *       {
- *         id, // The ID of the cart
- *       }
- *       ```
- *     description: Emitted when the customer in the cart is updated.
- *     deprecated: false
 *   - name: cart.region_updated
 *     payload: |-
 *       ```ts
--- a/www/utils/packages/docs-generator/src/classes/kinds/events.ts
+++ b/www/utils/packages/docs-generator/src/classes/kinds/events.ts
@@ -124,8 +124,18 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
      }

      this.workflows[workflowName] = workflowFile
-      if (workflowFile.includes("emitEventStep")) {
-        this.workflowsEmittingEvents[workflowName] = workflowFile
+      // remove comments in case the emitEventStep is commented out
+      const workflowWithoutComments = workflowFile.replace(
+        /\/\*[\s\S]*?\*\/|\/\/.*/g,
+        ""
+      )
+      // the emitEventStep should be mentioned at least twice in the workflow
+      // including the import statement
+      const emitEventStepCount = (
+        workflowWithoutComments.match(/emitEventStep/g) || []
+      ).length
+      if (emitEventStepCount >= 2) {
+        this.workflowsEmittingEvents[workflowName] = workflowWithoutComments
      }
    }
  }
--- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/events-listing.ts
+++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/events-listing.ts
@@ -116,6 +116,21 @@ function formatEventsType(
      }
    }

+    const versionTag = event.comment?.blockTags.find(
+      (tag) => tag.tag === "@version"
+    )
+
+    if (versionTag) {
+      eventName += `\n`
+      const versionText = versionTag.content
+        .map((content) => content.text)
+        .join("")
+        .trim()
+      eventName += `<Tooltip text="This event was added in version v${versionText}">`
+      eventName += `<Badge variant="blue">v${versionText}</Badge>`
+      eventName += `</Tooltip>`
+    }
+
    content.push(`    <Table.Row>`)
    content.push(`      <Table.Cell>\n${eventName}\n</Table.Cell>`)
    content.push(`      <Table.Cell>\n${eventDescription}\n</Table.Cell>`)
@@ -152,6 +167,10 @@ function formatEventsType(
      .join("")
      .trim()

+    const versionTag = event.comment?.blockTags.find(
+      (tag) => tag.tag === "@version"
+    )
+
    content.push(
      getEventHeading({
        titleLevel: subtitleLevel,
@@ -159,6 +178,12 @@ function formatEventsType(
        payload: eventPayload || "",
        deprecated: !!deprecatedTag,
        deprecatedMessage,
+        version: versionTag
+          ? versionTag.content
+              .map((content) => content.text)
+              .join("")
+              .trim()
+          : undefined,
      })
    )
    content.push("")
@@ -191,12 +216,14 @@ function getEventHeading({
  payload,
  deprecated = false,
  deprecatedMessage,
+  version,
 }: {
  titleLevel: number
  eventName: string
  payload: string
  deprecated?: boolean
  deprecatedMessage?: string
+  version?: string
 }) {
  const heading = [eventName]
  if (deprecated) {
@@ -210,6 +237,14 @@ function getEventHeading({
      heading.push(`</Tooltip>`)
    }
  }
+  if (version) {
+    if (deprecated) {
+      heading.push(`\n`)
+    }
+    heading.push(`<Tooltip text="This event was added in version v${version}">`)
+    heading.push(`<Badge variant="blue">v${version}</Badge>`)
+    heading.push(`</Tooltip>`)
+  }
  return `<EventHeader headerLvl="${titleLevel}" headerProps={{ id: "${getEventNameSlug(
    eventName
  )}", children: (<>${heading.join(
--- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-events.ts
+++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-events.ts
@@ -41,10 +41,24 @@ export default function () {
        const eventPayloadFormatted = eventPayload
          .replace("```ts\n", "")
          .replace("\n```", "")
-        const isDeprecated = commentContent.length >= 4
+        const isDeprecatedOrHasVersion = commentContent.length >= 4
+        const deprecatedIndex = isDeprecatedOrHasVersion
+          ? commentContent.slice(3).findIndex((c) => c.trim() === "deprecated")
+          : -1
+        const isDeprecated = deprecatedIndex !== -1
+        const deprecatedText = (
+          isDeprecated ? commentContent[3 + deprecatedIndex] || "" : ""
+        ).trim()
+        const version = isDeprecatedOrHasVersion
+          ? commentContent
+              .slice(3)
+              .find((c) => c.trim().startsWith("version: "))
+          : undefined
+        const versionText = (
+          version ? version.replace("version: ", "") : ""
+        ).trim()

        if (isDeprecated) {
-          const deprecatedText = commentContent[4]?.trim()
          eventNameFormatted += `\n`
          if (deprecatedText) {
            eventNameFormatted += `<Tooltip text="${deprecatedText}">`
@@ -55,6 +69,13 @@ export default function () {
          }
        }

+        if (versionText) {
+          eventNameFormatted += `\n\n`
+          eventNameFormatted += `<Tooltip text="This event was added in version v${versionText}">`
+          eventNameFormatted += `<Badge variant="blue">v${versionText}</Badge>`
+          eventNameFormatted += `</Tooltip>\n`
+        }
+
        str += `    <Table.Row>\n`
        str += `      <Table.Cell>\n${eventNameFormatted}\n</Table.Cell>\n`
        str += `      <Table.Cell>\n${eventDescription}\n</Table.Cell>\n`
--- a/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
+++ b/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
@@ -915,6 +915,12 @@ class WorkflowsPlugin {
            commentText += ` -- ${event.deprecated_message}`
          }
        }
+        if (event.version) {
+          commentText += ` -- version: ${event.version}`
+        }
+        if (event.name === "order-edit.canceled") {
+          console.log(event, commentText)
+        }
        return new CommentTag(`@workflowEvent`, [
          {
            kind: "text",