@eventcatalog/create-eventcatalog 4.3.12-beta.1 → 4.3.13

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/examples/index.mdx

@@ -0,0 +1,246 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Create a multi-item order with its payment authorisation
+
+Stock is reserved and payment is authorised for two T-shirts and a cap. As the final step of the checkout saga, the Checkout Orchestrator sends this command to the Order Service.
+
+### Payload details
+
+- `cartId` and `customerId` link the order to the checked-out cart and the customer.
+- `items` has 2 lines: 2 × Classic White T-shirt at 1,999 pence and 1 × Logo Cap at 1,499 pence. `unitPrice` is per unit, in minor units.
+- `total` is the sum of `quantity` × `unitPrice` across all lines.
+- `currency` is `GBP`.
+- `paymentAuthorizationId` references the hold placed by `AuthorizePayment`, so the funds can be captured.
+
+The total is **3,998 + 1,499 = 5,497 pence (£54.97)**.
+
+### Using this example
+
+The Order Service should store both lines, check that `total` equals the sum of the lines, and publish `OrderCreated` with a total of 5,497 `GBP`.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CreateOrder schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-create-order.ts
+import { EventsClient } from '@acme/events';
+import type { CreateOrder } from './schemas/create-order';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: CreateOrder = {
+  cartId: 'c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
+  customerId: '3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d',
+  items: [
+    {
+      productId: '5e8f2a1b-3c4d-4e5f-8a6b-7c8d9e0f1a2b',
+      quantity: 2,
+      unitPrice: 1999,
+    },
+    {
+      productId: '6f9a3b2c-4d5e-4f6a-9b7c-8d9e0f1a2b3c',
+      quantity: 1,
+      unitPrice: 1499,
+    },
+  ],
+  total: 5497,
+  currency: 'GBP',
+  paymentAuthorizationId: 'auth_7Hk2Qp9LmX4v',
+};
+
+await client.send('CreateOrder', command);
+```
+
+```python send_create_order.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "cartId": "c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+    "customerId": "3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d",
+    "items": [
+        {
+            "productId": "5e8f2a1b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+            "quantity": 2,
+            "unitPrice": 1999,
+        },
+        {
+            "productId": "6f9a3b2c-4d5e-4f6a-9b7c-8d9e0f1a2b3c",
+            "quantity": 1,
+            "unitPrice": 1499,
+        },
+    ],
+    "total": 5497,
+    "currency": "GBP",
+    "paymentAuthorizationId": "auth_7Hk2Qp9LmX4v",
+}
+
+client.send("CreateOrder", command)
+```
+
+```java SendCreateOrder.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class SendCreateOrder {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "cartId", "c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+      "customerId", "3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d",
+      "items", List.of(
+        Map.of(
+          "productId", "5e8f2a1b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+          "quantity", 2,
+          "unitPrice", 1999
+        ),
+        Map.of(
+          "productId", "6f9a3b2c-4d5e-4f6a-9b7c-8d9e0f1a2b3c",
+          "quantity", 1,
+          "unitPrice", 1499
+        )
+      ),
+      "total", 5497,
+      "currency", "GBP",
+      "paymentAuthorizationId", "auth_7Hk2Qp9LmX4v"
+    );
+
+    client.send("CreateOrder", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Create a single-item euro order
+
+A customer in Ireland buys one hoodie priced in euros. The command carries only the required fields and leaves out `paymentAuthorizationId`.
+
+### Payload details
+
+- `items` has one line: 1 × Heavyweight Hoodie at 5,799 cents.
+- `total` equals that single line.
+- `currency` is `EUR`, so `unitPrice` and `total` are in cents.
+- `paymentAuthorizationId` is optional and omitted here.
+
+The total is **5,799 cents (€57.99)**.
+
+### Using this example
+
+Use this to check that the Order Service creates an order without a `paymentAuthorizationId` and keeps the `EUR` currency on the resulting `OrderCreated` event.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CreateOrder schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-create-order.ts
+import { EventsClient } from '@acme/events';
+import type { CreateOrder } from './schemas/create-order';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: CreateOrder = {
+  cartId: 'd2b3c4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e',
+  customerId: '8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e',
+  items: [
+    {
+      productId: '7a0b4c3d-5e6f-4a7b-8c8d-9e0f1a2b3c4d',
+      quantity: 1,
+      unitPrice: 5799,
+    },
+  ],
+  total: 5799,
+  currency: 'EUR',
+};
+
+await client.send('CreateOrder', command);
+```
+
+```python send_create_order.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "cartId": "d2b3c4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
+    "customerId": "8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e",
+    "items": [
+        {
+            "productId": "7a0b4c3d-5e6f-4a7b-8c8d-9e0f1a2b3c4d",
+            "quantity": 1,
+            "unitPrice": 5799,
+        },
+    ],
+    "total": 5799,
+    "currency": "EUR",
+}
+
+client.send("CreateOrder", command)
+```
+
+```java SendCreateOrder.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class SendCreateOrder {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "cartId", "d2b3c4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
+      "customerId", "8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e",
+      "items", List.of(
+        Map.of(
+          "productId", "7a0b4c3d-5e6f-4a7b-8c8d-9e0f1a2b3c4d",
+          "quantity", 1,
+          "unitPrice", 5799
+        )
+      ),
+      "total", 5799,
+      "currency", "EUR"
+    );
+
+    client.send("CreateOrder", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/examples/index.mdx

@@ -0,0 +1,267 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish a customer-requested cancellation
+
+The Order Service has handled a `CancelOrder` command from the customer's account page. It publishes this event so inventory, payments and fulfilment can undo their work.
+
+### Payload details
+
+- `orderId` is the cancelled order.
+- `customerId` is included, so notification services can send a cancellation email.
+- `reason` is `CUSTOMER_REQUESTED`.
+- `cancelledAt` is the ISO-8601 UTC time the cancellation was recorded.
+
+### Using this example
+
+Consumers should release the stock, void the payment authorisation and confirm the cancellation to the customer.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderCancelled schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-cancelled.ts
+import { EventsClient } from '@acme/events';
+import type { OrderCancelled } from './schemas/order-cancelled';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderCancelled = {
+  orderId: 'e3f4a5b6-7c8d-4e9f-a0b1-c2d3e4f5a6b7',
+  customerId: '3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d',
+  reason: 'CUSTOMER_REQUESTED',
+  cancelledAt: '2026-09-12T20:10:05Z',
+};
+
+await client.publish('OrderCancelled', event);
+```
+
+```python publish_order_cancelled.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "e3f4a5b6-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
+    "customerId": "3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d",
+    "reason": "CUSTOMER_REQUESTED",
+    "cancelledAt": "2026-09-12T20:10:05Z",
+}
+
+client.publish("OrderCancelled", event)
+```
+
+```java PublishOrderCancelled.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderCancelled {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "e3f4a5b6-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
+      "customerId", "3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d",
+      "reason", "CUSTOMER_REQUESTED",
+      "cancelledAt", "2026-09-12T20:10:05Z"
+    );
+
+    client.publish("OrderCancelled", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish a cancellation after a payment failure
+
+Capturing the payment failed after the order was created, so the Order Service cancels the order as compensation. The event carries only the required fields.
+
+### Payload details
+
+- `orderId` is the order that could not be paid for.
+- `reason` is `PAYMENT_FAILED`.
+- `customerId` is optional and omitted, so consumers must look the customer up by `orderId` if they need it.
+- `cancelledAt` records when the compensation ran.
+
+### Using this example
+
+Use this to check that consumers handle an event without `customerId`, and that payment services do not try to refund money that was never taken.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderCancelled schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-cancelled.ts
+import { EventsClient } from '@acme/events';
+import type { OrderCancelled } from './schemas/order-cancelled';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderCancelled = {
+  orderId: 'f4a5b6c7-8d9e-4f0a-b1c2-d3e4f5a6b7c8',
+  reason: 'PAYMENT_FAILED',
+  cancelledAt: '2026-09-15T09:02:17Z',
+};
+
+await client.publish('OrderCancelled', event);
+```
+
+```python publish_order_cancelled.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "f4a5b6c7-8d9e-4f0a-b1c2-d3e4f5a6b7c8",
+    "reason": "PAYMENT_FAILED",
+    "cancelledAt": "2026-09-15T09:02:17Z",
+}
+
+client.publish("OrderCancelled", event)
+```
+
+```java PublishOrderCancelled.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderCancelled {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "f4a5b6c7-8d9e-4f0a-b1c2-d3e4f5a6b7c8",
+      "reason", "PAYMENT_FAILED",
+      "cancelledAt", "2026-09-15T09:02:17Z"
+    );
+
+    client.publish("OrderCancelled", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 3. Publish a cancellation because stock ran out
+
+The warehouse finds that the last units of a product are damaged and cannot fulfil the order. The Order Service cancels it and tells downstream systems why.
+
+### Payload details
+
+- `orderId` is the order that cannot be fulfilled.
+- `customerId` is included so the customer can be told and offered an alternative.
+- `reason` is `OUT_OF_STOCK`.
+- `cancelledAt` is the ISO-8601 UTC time of the cancellation.
+
+### Using this example
+
+Consumers should void or refund the payment, and reporting should count this as a stock problem rather than a customer choice.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderCancelled schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-cancelled.ts
+import { EventsClient } from '@acme/events';
+import type { OrderCancelled } from './schemas/order-cancelled';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderCancelled = {
+  orderId: '1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e',
+  customerId: '8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e',
+  reason: 'OUT_OF_STOCK',
+  cancelledAt: '2026-09-16T13:36:50Z',
+};
+
+await client.publish('OrderCancelled', event);
+```
+
+```python publish_order_cancelled.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
+    "customerId": "8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e",
+    "reason": "OUT_OF_STOCK",
+    "cancelledAt": "2026-09-16T13:36:50Z",
+}
+
+client.publish("OrderCancelled", event)
+```
+
+```java PublishOrderCancelled.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderCancelled {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
+      "customerId", "8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e",
+      "reason", "OUT_OF_STOCK",
+      "cancelledAt", "2026-09-16T13:36:50Z"
+    );
+
+    client.publish("OrderCancelled", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/examples/index.mdx

@@ -0,0 +1,171 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish completion of a UK order
+
+The T-shirts and cap from a UK order are delivered two days after purchase. The Order Service publishes this event to mark the end of the order's happy path.
+
+### Payload details
+
+- `orderId` is the order that was fulfilled.
+- `customerId` identifies the customer, so they can be asked for a review.
+- `completedAt` is the ISO-8601 UTC time the delivery was confirmed.
+
+### Using this example
+
+Consumers should close out fulfilment, capture the payment and move the order to completed in reporting.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderCompleted schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-completed.ts
+import { EventsClient } from '@acme/events';
+import type { OrderCompleted } from './schemas/order-completed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderCompleted = {
+  orderId: '4c7e9a2b-1d3f-4b5a-8e6c-2f9d0a1b3c5e',
+  customerId: '3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d',
+  completedAt: '2026-09-13T14:27:09Z',
+};
+
+await client.publish('OrderCompleted', event);
+```
+
+```python publish_order_completed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "4c7e9a2b-1d3f-4b5a-8e6c-2f9d0a1b3c5e",
+    "customerId": "3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d",
+    "completedAt": "2026-09-13T14:27:09Z",
+}
+
+client.publish("OrderCompleted", event)
+```
+
+```java PublishOrderCompleted.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderCompleted {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "4c7e9a2b-1d3f-4b5a-8e6c-2f9d0a1b3c5e",
+      "customerId", "3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d",
+      "completedAt", "2026-09-13T14:27:09Z"
+    );
+
+    client.publish("OrderCompleted", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish completion of an international order
+
+A hoodie shipped to Ireland takes five days to arrive. When the carrier confirms delivery, the Order Service publishes this event.
+
+### Payload details
+
+- `orderId` is the euro order created on 14 September.
+- `customerId` identifies the customer in Ireland.
+- `completedAt` is five days after the order was created, which reporting can use to track international delivery times.
+
+### Using this example
+
+Use this to check that consumers work out delivery time from the order's creation time and `completedAt`, whatever the currency or destination.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderCompleted schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-completed.ts
+import { EventsClient } from '@acme/events';
+import type { OrderCompleted } from './schemas/order-completed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderCompleted = {
+  orderId: 'b5d8e1f2-6a3c-4d7b-9f0e-3a4b5c6d7e8f',
+  customerId: '8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e',
+  completedAt: '2026-09-19T11:48:32Z',
+};
+
+await client.publish('OrderCompleted', event);
+```
+
+```python publish_order_completed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "b5d8e1f2-6a3c-4d7b-9f0e-3a4b5c6d7e8f",
+    "customerId": "8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e",
+    "completedAt": "2026-09-19T11:48:32Z",
+}
+
+client.publish("OrderCompleted", event)
+```
+
+```java PublishOrderCompleted.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderCompleted {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "b5d8e1f2-6a3c-4d7b-9f0e-3a4b5c6d7e8f",
+      "customerId", "8a7c6e5d-2b1f-4c3a-9e8d-7f6a5b4c3d2e",
+      "completedAt", "2026-09-19T11:48:32Z"
+    );
+
+    client.publish("OrderCompleted", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>