@eventcatalog/create-eventcatalog 4.3.12 → 4.3.14-beta.0

package/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/examples/index.mdx

@@ -0,0 +1,179 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Authorise payment for a UK cart
+
+Once stock is reserved for two T-shirts and a cap, the Checkout Orchestrator asks the payment provider to place a hold for the cart total. The funds are captured after the order is created.
+
+### Payload details
+
+- `cartId` matches the cart whose stock has just been reserved.
+- `customerId` identifies the paying customer.
+- `amount` is in pence: 2 × 1,999 (T-shirts) + 1 × 1,499 (cap).
+- `currency` is `GBP`, a three-letter ISO 4217 code.
+
+The amount to authorise is **5,497 pence (£54.97)**.
+
+### Using this example
+
+The payment handler should place a hold of exactly 5,497 pence on the customer's payment method and return an authorisation ID for the `CreateOrder` step.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the AuthorizePayment schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-authorize-payment.ts
+import { EventsClient } from '@acme/events';
+import type { AuthorizePayment } from './schemas/authorize-payment';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: AuthorizePayment = {
+  cartId: 'c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
+  customerId: '3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d',
+  amount: 5497,
+  currency: 'GBP',
+};
+
+await client.send('AuthorizePayment', command);
+```
+
+```python send_authorize_payment.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",
+    "amount": 5497,
+    "currency": "GBP",
+}
+
+client.send("AuthorizePayment", command)
+```
+
+```java SendAuthorizePayment.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendAuthorizePayment {
+  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",
+      "amount", 5497,
+      "currency", "GBP"
+    );
+
+    client.send("AuthorizePayment", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Authorise a euro payment with only the required fields
+
+A cart with one hoodie is priced in euros. The orchestrator sends only the required fields, leaving out the optional `customerId`.
+
+### Payload details
+
+- `cartId` identifies the cart; there is no `customerId`.
+- `amount` is in cents: 1 × 5,799 for the hoodie.
+- `currency` is `EUR`, showing that amounts are not always in pounds.
+
+The amount to authorise is **5,799 cents (€57.99)**.
+
+### Using this example
+
+Use this to check that the payment handler reads `amount` in the minor units of `currency`, and does not need a `customerId` to authorise.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the AuthorizePayment schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-authorize-payment.ts
+import { EventsClient } from '@acme/events';
+import type { AuthorizePayment } from './schemas/authorize-payment';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: AuthorizePayment = {
+  cartId: 'd2b3c4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e',
+  amount: 5799,
+  currency: 'EUR',
+};
+
+await client.send('AuthorizePayment', command);
+```
+
+```python send_authorize_payment.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "cartId": "d2b3c4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
+    "amount": 5799,
+    "currency": "EUR",
+}
+
+client.send("AuthorizePayment", command)
+```
+
+```java SendAuthorizePayment.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendAuthorizePayment {
+  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",
+      "amount", 5799,
+      "currency", "EUR"
+    );
+
+    client.send("AuthorizePayment", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/examples/index.mdx

@@ -0,0 +1,215 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Reserve stock for a multi-item cart
+
+A signed-in customer checks out a cart with two T-shirts and a cap. The Checkout Orchestrator sends this command first, so the stock is held while payment is authorised.
+
+### Payload details
+
+- `cartId` identifies the cart being checked out; the same ID is used for the payment authorisation and the order that follow.
+- `customerId` is included because the customer is signed in, so the reservation can be traced back to them.
+- `items` holds one entry per product: 2 Classic White T-shirts and 1 Logo Cap, each identified by its `productId`.
+- Every `quantity` is a whole number of at least 1.
+
+In total, **3 units** across **2 products** are reserved.
+
+### Using this example
+
+The inventory handler should hold 2 T-shirts and 1 cap against this `cartId` and reply with a successful reservation. Release the hold if the saga later compensates.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the ReserveInventory schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-reserve-inventory.ts
+import { EventsClient } from '@acme/events';
+import type { ReserveInventory } from './schemas/reserve-inventory';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: ReserveInventory = {
+  cartId: 'c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
+  customerId: '3f2b8c1e-7a4d-4e9b-9c6f-1d2e3a4b5c6d',
+  items: [
+    {
+      productId: '5e8f2a1b-3c4d-4e5f-8a6b-7c8d9e0f1a2b',
+      quantity: 2,
+    },
+    {
+      productId: '6f9a3b2c-4d5e-4f6a-9b7c-8d9e0f1a2b3c',
+      quantity: 1,
+    },
+  ],
+};
+
+await client.send('ReserveInventory', command);
+```
+
+```python send_reserve_inventory.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,
+        },
+        {
+            "productId": "6f9a3b2c-4d5e-4f6a-9b7c-8d9e0f1a2b3c",
+            "quantity": 1,
+        },
+    ],
+}
+
+client.send("ReserveInventory", command)
+```
+
+```java SendReserveInventory.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class SendReserveInventory {
+  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
+        ),
+        Map.of(
+          "productId", "6f9a3b2c-4d5e-4f6a-9b7c-8d9e0f1a2b3c",
+          "quantity", 1
+        )
+      )
+    );
+
+    client.send("ReserveInventory", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Reserve a single item with only the required fields
+
+A cart holds one hoodie and the orchestrator has no customer to attach. It sends the smallest valid command: the cart and its items.
+
+### Payload details
+
+- `cartId` is the only identifier sent; the optional `customerId` is omitted.
+- `items` holds a single entry: 1 Heavyweight Hoodie.
+- `productId` and `quantity` are both required for every item.
+
+### Using this example
+
+Use this to check that the inventory handler accepts a reservation without a `customerId` and keys the hold on `cartId` alone.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the ReserveInventory schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-reserve-inventory.ts
+import { EventsClient } from '@acme/events';
+import type { ReserveInventory } from './schemas/reserve-inventory';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: ReserveInventory = {
+  cartId: 'd2b3c4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e',
+  items: [
+    {
+      productId: '7a0b4c3d-5e6f-4a7b-8c8d-9e0f1a2b3c4d',
+      quantity: 1,
+    },
+  ],
+};
+
+await client.send('ReserveInventory', command);
+```
+
+```python send_reserve_inventory.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "cartId": "d2b3c4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
+    "items": [
+        {
+            "productId": "7a0b4c3d-5e6f-4a7b-8c8d-9e0f1a2b3c4d",
+            "quantity": 1,
+        },
+    ],
+}
+
+client.send("ReserveInventory", command)
+```
+
+```java SendReserveInventory.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class SendReserveInventory {
+  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",
+      "items", List.of(
+        Map.of(
+          "productId", "7a0b4c3d-5e6f-4a7b-8c8d-9e0f1a2b3c4d",
+          "quantity", 1
+        )
+      )
+    );
+
+    client.send("ReserveInventory", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

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

@@ -0,0 +1,163 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Cancel an order at the customer's request
+
+Shortly after ordering a hoodie and two caps, the customer changes their mind and cancels from their account page. The storefront sends this command to the Order Service.
+
+### Payload details
+
+- `orderId` identifies the order to cancel; it must not be completed yet.
+- `reason` is `CUSTOMER_REQUESTED`, the customer's own choice.
+
+### Using this example
+
+The Order Service should release the reserved stock, void the payment authorisation and publish `OrderCancelled` with the same `orderId` and `reason`.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CancelOrder schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-cancel-order.ts
+import { EventsClient } from '@acme/events';
+import type { CancelOrder } from './schemas/cancel-order';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: CancelOrder = {
+  orderId: 'e3f4a5b6-7c8d-4e9f-a0b1-c2d3e4f5a6b7',
+  reason: 'CUSTOMER_REQUESTED',
+};
+
+await client.send('CancelOrder', command);
+```
+
+```python send_cancel_order.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "orderId": "e3f4a5b6-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
+    "reason": "CUSTOMER_REQUESTED",
+}
+
+client.send("CancelOrder", command)
+```
+
+```java SendCancelOrder.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendCancelOrder {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "orderId", "e3f4a5b6-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
+      "reason", "CUSTOMER_REQUESTED"
+    );
+
+    client.send("CancelOrder", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Cancel an order flagged as fraud
+
+The fraud team reviews a suspicious order and blocks it before it ships. Their tooling sends this command so the order never reaches fulfilment.
+
+### Payload details
+
+- `orderId` identifies the flagged order.
+- `reason` is `FRAUD`, which downstream systems can use to skip customer notifications and refund flows.
+
+### Using this example
+
+Use this to check that the handler accepts the `FRAUD` reason and that the resulting `OrderCancelled` event carries it unchanged.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CancelOrder schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-cancel-order.ts
+import { EventsClient } from '@acme/events';
+import type { CancelOrder } from './schemas/cancel-order';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: CancelOrder = {
+  orderId: 'a6b7c8d9-0e1f-4a2b-8c3d-e4f5a6b7c8d9',
+  reason: 'FRAUD',
+};
+
+await client.send('CancelOrder', command);
+```
+
+```python send_cancel_order.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "orderId": "a6b7c8d9-0e1f-4a2b-8c3d-e4f5a6b7c8d9",
+    "reason": "FRAUD",
+}
+
+client.send("CancelOrder", command)
+```
+
+```java SendCancelOrder.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendCancelOrder {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "orderId", "a6b7c8d9-0e1f-4a2b-8c3d-e4f5a6b7c8d9",
+      "reason", "FRAUD"
+    );
+
+    client.send("CancelOrder", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>