@eventcatalog/create-eventcatalog 4.3.12 → 4.3.13

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/examples/index.mdx

@@ -0,0 +1,170 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Remove a T-shirt line completely
+
+A shopper clicks **Remove** next to the T-shirt in their basket. The storefront sends `RemoveItemFromCart` without a quantity, so the Cart API deletes the whole line.
+
+### Payload details
+
+- `cartId` identifies the shopper's cart.
+- `productId` is the T-shirt to remove.
+- `quantity` is omitted, which means "remove the item entirely".
+
+### Using this example
+
+Check that the T-shirt line no longer exists in the cart, whatever quantity it had before.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the RemoveItemFromCart schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-remove-item-from-cart.ts
+import { EventsClient } from '@acme/events';
+import type { RemoveItemFromCart } from './schemas/remove-item-from-cart';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: RemoveItemFromCart = {
+  cartId: 'a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24',
+  productId: '0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93',
+};
+
+await client.send('RemoveItemFromCart', command);
+```
+
+```python send_remove_item_from_cart.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "cartId": "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+    "productId": "0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93",
+}
+
+client.send("RemoveItemFromCart", command)
+```
+
+```java SendRemoveItemFromCart.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendRemoveItemFromCart {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "cartId", "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+      "productId", "0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93"
+    );
+
+    client.send("RemoveItemFromCart", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Reduce the number of caps
+
+The shopper has three caps in the cart and lowers the quantity to one. The storefront sends `RemoveItemFromCart` with a quantity of 2, and the Cart API decreases the line.
+
+### Payload details
+
+- `cartId` is the same cart as in the first example.
+- `productId` is the cap.
+- `quantity` is `2`, the number of units to take away (minimum 1).
+
+The cap line goes from **3 units to 1 unit**.
+
+### Using this example
+
+Check that the cap line keeps 1 unit, and that removing a product that is not in the cart returns a `404` response.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the RemoveItemFromCart schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-remove-item-from-cart.ts
+import { EventsClient } from '@acme/events';
+import type { RemoveItemFromCart } from './schemas/remove-item-from-cart';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: RemoveItemFromCart = {
+  cartId: 'a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24',
+  productId: '8d4f6a2c-3e5b-4c7d-9f1a-5b7d9e3c1a46',
+  quantity: 2,
+};
+
+await client.send('RemoveItemFromCart', command);
+```
+
+```python send_remove_item_from_cart.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "cartId": "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+    "productId": "8d4f6a2c-3e5b-4c7d-9f1a-5b7d9e3c1a46",
+    "quantity": 2,
+}
+
+client.send("RemoveItemFromCart", command)
+```
+
+```java SendRemoveItemFromCart.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendRemoveItemFromCart {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "cartId", "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+      "productId", "8d4f6a2c-3e5b-4c7d-9f1a-5b7d9e3c1a46",
+      "quantity", 2
+    );
+
+    client.send("RemoveItemFromCart", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/examples/index.mdx

@@ -0,0 +1,275 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish a single-item checkout
+
+A customer checks out a cart with two T-shirts and no voucher. The Cart API publishes `CartCheckedOut`, and downstream systems use it to create the order and take payment.
+
+### Payload details
+
+- `eventId` and `occurredAt` identify this event and when the checkout happened (UTC).
+- `items` holds one line: 2 T-shirts at a `unitPrice` of 2,000 pence each.
+- `subtotal` and `discount` are omitted because no discount applied.
+- `currency` is `GBP`, so all amounts are in pence.
+
+The total is **2 × 2,000 = 4,000 pence (£40.00)**.
+
+### Using this example
+
+Check that the order created from this event has one line and a total of 4,000 pence, and that a missing `discount` is treated as zero.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the CartCheckedOut schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-cart-checked-out.ts
+import { EventsClient } from '@acme/events';
+import type { CartCheckedOut } from './schemas/cart-checked-out';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: CartCheckedOut = {
+  eventId: 'e4b7c1d9-2f6a-4e8b-a3c5-7d9f1b3e5a02',
+  occurredAt: '2026-09-11T08:12:45Z',
+  cartId: 'c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f',
+  customerId: '7a1e5c9d-8b3f-4f2a-a6d4-2e9c0b7f3d51',
+  items: [
+    {
+      productId: '0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93',
+      quantity: 2,
+      unitPrice: 2000,
+    },
+  ],
+  total: 4000,
+  currency: 'GBP',
+};
+
+await client.publish('CartCheckedOut', event);
+```
+
+```python publish_cart_checked_out.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "eventId": "e4b7c1d9-2f6a-4e8b-a3c5-7d9f1b3e5a02",
+    "occurredAt": "2026-09-11T08:12:45Z",
+    "cartId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
+    "customerId": "7a1e5c9d-8b3f-4f2a-a6d4-2e9c0b7f3d51",
+    "items": [
+        {
+            "productId": "0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93",
+            "quantity": 2,
+            "unitPrice": 2000,
+        },
+    ],
+    "total": 4000,
+    "currency": "GBP",
+}
+
+client.publish("CartCheckedOut", event)
+```
+
+```java PublishCartCheckedOut.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class PublishCartCheckedOut {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "eventId", "e4b7c1d9-2f6a-4e8b-a3c5-7d9f1b3e5a02",
+      "occurredAt", "2026-09-11T08:12:45Z",
+      "cartId", "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
+      "customerId", "7a1e5c9d-8b3f-4f2a-a6d4-2e9c0b7f3d51",
+      "items", List.of(
+        Map.of(
+          "productId", "0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93",
+          "quantity", 2,
+          "unitPrice", 2000
+        )
+      ),
+      "total", 4000,
+      "currency", "GBP"
+    );
+
+    client.publish("CartCheckedOut", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish a multi-item checkout with a discount
+
+A customer checks out T-shirts, a hoodie and a cap with the `AUTUMN10` voucher. The event carries the subtotal, the discount and the final total so consumers do not need to reprice the cart.
+
+### Payload details
+
+- `items` has three lines: 2 T-shirts at 2,000, 1 hoodie at 4,500 and 1 cap at 1,500 pence.
+- `subtotal` is the total before discounts.
+- `discount` is the 10% voucher saving.
+- `total` is `subtotal` minus `discount`.
+
+The subtotal is **4,000 + 4,500 + 1,500 = 10,000 pence (£100.00)**, the discount is **1,000 pence (£10.00)** and the total is **9,000 pence (£90.00)**.
+
+### Using this example
+
+Check that the payment is taken for 9,000 pence, not the subtotal, and that the order has three lines.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the CartCheckedOut schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-cart-checked-out.ts
+import { EventsClient } from '@acme/events';
+import type { CartCheckedOut } from './schemas/cart-checked-out';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: CartCheckedOut = {
+  eventId: 'f6a2d8c4-9b1e-4a7d-b5c3-1e7f9a2d4c68',
+  occurredAt: '2026-09-14T17:30:05Z',
+  cartId: 'a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24',
+  customerId: '3f2c8a91-6b4e-4d7a-9c1f-8e5b2a7d4c60',
+  items: [
+    {
+      productId: '0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93',
+      quantity: 2,
+      unitPrice: 2000,
+    },
+    {
+      productId: '5b9d3e7f-1a2c-4b6d-8e0f-2c4a6e8b0d15',
+      quantity: 1,
+      unitPrice: 4500,
+    },
+    {
+      productId: '8d4f6a2c-3e5b-4c7d-9f1a-5b7d9e3c1a46',
+      quantity: 1,
+      unitPrice: 1500,
+    },
+  ],
+  subtotal: 10000,
+  discount: 1000,
+  total: 9000,
+  currency: 'GBP',
+};
+
+await client.publish('CartCheckedOut', event);
+```
+
+```python publish_cart_checked_out.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "eventId": "f6a2d8c4-9b1e-4a7d-b5c3-1e7f9a2d4c68",
+    "occurredAt": "2026-09-14T17:30:05Z",
+    "cartId": "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+    "customerId": "3f2c8a91-6b4e-4d7a-9c1f-8e5b2a7d4c60",
+    "items": [
+        {
+            "productId": "0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93",
+            "quantity": 2,
+            "unitPrice": 2000,
+        },
+        {
+            "productId": "5b9d3e7f-1a2c-4b6d-8e0f-2c4a6e8b0d15",
+            "quantity": 1,
+            "unitPrice": 4500,
+        },
+        {
+            "productId": "8d4f6a2c-3e5b-4c7d-9f1a-5b7d9e3c1a46",
+            "quantity": 1,
+            "unitPrice": 1500,
+        },
+    ],
+    "subtotal": 10000,
+    "discount": 1000,
+    "total": 9000,
+    "currency": "GBP",
+}
+
+client.publish("CartCheckedOut", event)
+```
+
+```java PublishCartCheckedOut.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class PublishCartCheckedOut {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "eventId", "f6a2d8c4-9b1e-4a7d-b5c3-1e7f9a2d4c68",
+      "occurredAt", "2026-09-14T17:30:05Z",
+      "cartId", "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+      "customerId", "3f2c8a91-6b4e-4d7a-9c1f-8e5b2a7d4c60",
+      "items", List.of(
+        Map.of(
+          "productId", "0e8f4b2a-7c1d-4f3e-9a5b-6d2c8e1f7a93",
+          "quantity", 2,
+          "unitPrice", 2000
+        ),
+        Map.of(
+          "productId", "5b9d3e7f-1a2c-4b6d-8e0f-2c4a6e8b0d15",
+          "quantity", 1,
+          "unitPrice", 4500
+        ),
+        Map.of(
+          "productId", "8d4f6a2c-3e5b-4c7d-9f1a-5b7d9e3c1a46",
+          "quantity", 1,
+          "unitPrice", 1500
+        )
+      ),
+      "subtotal", 10000,
+      "discount", 1000,
+      "total", 9000,
+      "currency", "GBP"
+    );
+
+    client.publish("CartCheckedOut", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/examples/index.mdx

@@ -0,0 +1,207 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Calculate a voucher discount
+
+During checkout, the Cart API sends `CalculateDiscount` with the customer's `AUTUMN10` code. The Promotion Service checks the promotion rules and returns the discount, and also publishes `DiscountCalculated`.
+
+### Payload details
+
+- `cartId` and `customerId` identify the cart and its owner.
+- `subtotal` is 10,000 pence, the cart total before discounts.
+- `currency` is `GBP`.
+- `promotionCode` is `AUTUMN10`, a 10% off voucher.
+- The response `discount` is in pence, and `appliedPromotions` lists the promotions used.
+
+10% of 10,000 pence gives a discount of **1,000 pence (£10.00)**.
+
+### Example response
+
+```json
+{
+  "discount": 1000,
+  "appliedPromotions": ["AUTUMN10"]
+}
+```
+
+### Using this example
+
+Check that the discount is 1,000 pence and that `AUTUMN10` appears in `appliedPromotions`.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CalculateDiscount schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-calculate-discount.ts
+import { EventsClient } from '@acme/events';
+import type { CalculateDiscountRequest, CalculateDiscountResponse } from './schemas/calculate-discount';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: CalculateDiscountRequest = {
+  cartId: 'a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24',
+  customerId: '3f2c8a91-6b4e-4d7a-9c1f-8e5b2a7d4c60',
+  subtotal: 10000,
+  currency: 'GBP',
+  promotionCode: 'AUTUMN10',
+};
+
+const result: CalculateDiscountResponse = await client.send('CalculateDiscount', request);
+
+console.log(result.discount, result.appliedPromotions);
+```
+
+```python send_calculate_discount.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "cartId": "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+    "customerId": "3f2c8a91-6b4e-4d7a-9c1f-8e5b2a7d4c60",
+    "subtotal": 10000,
+    "currency": "GBP",
+    "promotionCode": "AUTUMN10",
+}
+
+result = client.send("CalculateDiscount", request)
+print(result["discount"], result.get("appliedPromotions", []))
+```
+
+```java SendCalculateDiscount.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendCalculateDiscount {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "cartId", "a7c3e9f1-2b4d-4e6a-8f1c-3d5b7e9a1c24",
+      "customerId", "3f2c8a91-6b4e-4d7a-9c1f-8e5b2a7d4c60",
+      "subtotal", 10000,
+      "currency", "GBP",
+      "promotionCode", "AUTUMN10"
+    );
+
+    var result = client.send("CalculateDiscount", request);
+    System.out.println(result.get("discount"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Price a cart with no applicable promotions
+
+A customer checks out two T-shirts without a voucher. The Cart API still asks the Promotion Service for a discount, in case an automatic promotion applies.
+
+### Payload details
+
+- `cartId` identifies the cart.
+- `customerId` and `promotionCode` are optional and omitted here, so only automatic promotions are checked.
+- `subtotal` is 4,000 pence (£40.00) in `GBP`.
+- The response `discount` is `0` and `appliedPromotions` is omitted.
+
+### Example response
+
+```json
+{
+  "discount": 0
+}
+```
+
+### Using this example
+
+Check that the Cart API accepts a zero discount and a missing `appliedPromotions` list, and keeps the total at 4,000 pence.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CalculateDiscount schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-calculate-discount.ts
+import { EventsClient } from '@acme/events';
+import type { CalculateDiscountRequest, CalculateDiscountResponse } from './schemas/calculate-discount';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: CalculateDiscountRequest = {
+  cartId: 'c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f',
+  subtotal: 4000,
+  currency: 'GBP',
+};
+
+const result: CalculateDiscountResponse = await client.send('CalculateDiscount', request);
+
+console.log(result.discount, result.appliedPromotions);
+```
+
+```python send_calculate_discount.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "cartId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
+    "subtotal": 4000,
+    "currency": "GBP",
+}
+
+result = client.send("CalculateDiscount", request)
+print(result["discount"], result.get("appliedPromotions", []))
+```
+
+```java SendCalculateDiscount.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendCalculateDiscount {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "cartId", "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
+      "subtotal", 4000,
+      "currency", "GBP"
+    );
+
+    var result = client.send("CalculateDiscount", request);
+    System.out.println(result.get("discount"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>