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

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/examples/index.mdx

@@ -0,0 +1,227 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish a reservation for a multi-item order
+
+The Inventory Service publishes this event when it holds stock for every item in an order. The checkout saga in the Ordering domain consumes it and continues placing the order.
+
+### Payload details
+
+- `reservationId` is the ID to use later in `ReleaseInventory`.
+- `orderId` and `cartId` link the reservation to the order and the cart it came from.
+- `items` holds 2 T-shirts and 1 cap, each by `productId` and `quantity`.
+- `reservedAt` is the UTC time the stock was held.
+
+In total, **3 units** are reserved across 2 products.
+
+### Using this example
+
+The checkout saga should move on to payment for this order. Tests can check that both line items are reserved in full.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the InventoryReserved schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-inventory-reserved.ts
+import { EventsClient } from '@acme/events';
+import type { InventoryReserved } from './schemas/inventory-reserved';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: InventoryReserved = {
+  reservationId: '4e9a1c7d-6b2f-4d8e-9c3a-7f5b0d1e2a86',
+  orderId: '3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27',
+  cartId: '7a1e5c9b-3f8d-4b2e-a6c4-9d0f1b7e3a58',
+  items: [
+    {
+      productId: '0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95',
+      quantity: 2,
+    },
+    {
+      productId: '6c1f9a4e-3d7b-4a2c-8f5e-9b0d2c7a1e38',
+      quantity: 1,
+    },
+  ],
+  reservedAt: '2026-09-14T08:12:45Z',
+};
+
+await client.publish('InventoryReserved', event);
+```
+
+```python publish_inventory_reserved.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "reservationId": "4e9a1c7d-6b2f-4d8e-9c3a-7f5b0d1e2a86",
+    "orderId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+    "cartId": "7a1e5c9b-3f8d-4b2e-a6c4-9d0f1b7e3a58",
+    "items": [
+        {
+            "productId": "0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95",
+            "quantity": 2,
+        },
+        {
+            "productId": "6c1f9a4e-3d7b-4a2c-8f5e-9b0d2c7a1e38",
+            "quantity": 1,
+        },
+    ],
+    "reservedAt": "2026-09-14T08:12:45Z",
+}
+
+client.publish("InventoryReserved", event)
+```
+
+```java PublishInventoryReserved.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class PublishInventoryReserved {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "reservationId", "4e9a1c7d-6b2f-4d8e-9c3a-7f5b0d1e2a86",
+      "orderId", "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+      "cartId", "7a1e5c9b-3f8d-4b2e-a6c4-9d0f1b7e3a58",
+      "items", List.of(
+        Map.of(
+          "productId", "0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95",
+          "quantity", 2
+        ),
+        Map.of(
+          "productId", "6c1f9a4e-3d7b-4a2c-8f5e-9b0d2c7a1e38",
+          "quantity", 1
+        )
+      ),
+      "reservedAt", "2026-09-14T08:12:45Z"
+    );
+
+    client.publish("InventoryReserved", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish a reservation for a cart
+
+Stock can be held for a cart before the order exists. The event then links to the cart only and holds a single hoodie.
+
+### Payload details
+
+- `cartId` is set and `orderId` is omitted because no order has been created yet.
+- `items` holds 1 hoodie.
+- `reservationId`, `items` and `reservedAt` are the required fields.
+
+### Using this example
+
+Use this payload to check that consumers match a reservation by `cartId` when `orderId` is missing.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the InventoryReserved schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-inventory-reserved.ts
+import { EventsClient } from '@acme/events';
+import type { InventoryReserved } from './schemas/inventory-reserved';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: InventoryReserved = {
+  reservationId: '8f3d6b2a-1e9c-4a7f-b5d8-2c0e4a9f6b13',
+  cartId: '2c8f0b6d-5a3e-4c9f-8d1b-6e4a7c0f2b91',
+  items: [
+    {
+      productId: 'd2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72',
+      quantity: 1,
+    },
+  ],
+  reservedAt: '2026-09-14T10:58:21Z',
+};
+
+await client.publish('InventoryReserved', event);
+```
+
+```python publish_inventory_reserved.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "reservationId": "8f3d6b2a-1e9c-4a7f-b5d8-2c0e4a9f6b13",
+    "cartId": "2c8f0b6d-5a3e-4c9f-8d1b-6e4a7c0f2b91",
+    "items": [
+        {
+            "productId": "d2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72",
+            "quantity": 1,
+        },
+    ],
+    "reservedAt": "2026-09-14T10:58:21Z",
+}
+
+client.publish("InventoryReserved", event)
+```
+
+```java PublishInventoryReserved.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class PublishInventoryReserved {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "reservationId", "8f3d6b2a-1e9c-4a7f-b5d8-2c0e4a9f6b13",
+      "cartId", "2c8f0b6d-5a3e-4c9f-8d1b-6e4a7c0f2b91",
+      "items", List.of(
+        Map.of(
+          "productId", "d2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72",
+          "quantity", 1
+        )
+      ),
+      "reservedAt", "2026-09-14T10:58:21Z"
+    );
+
+    client.publish("InventoryReserved", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/examples/index.mdx

@@ -0,0 +1,229 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish a sold-out item for an order
+
+The Inventory Service publishes this event when it cannot reserve stock for an order. The checkout saga consumes it, fails checkout and cancels the order.
+
+### Payload details
+
+- `orderId` and `cartId` identify the order and the cart that was checked out.
+- `unavailableItems` lists the hoodie: `requested` is `1` and `available` is `0`.
+- `checkedAt` is the UTC time of the stock check.
+
+### Using this example
+
+The checkout saga should cancel the order and tell the customer the hoodie is sold out.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the InventoryUnavailable schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-inventory-unavailable.ts
+import { EventsClient } from '@acme/events';
+import type { InventoryUnavailable } from './schemas/inventory-unavailable';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: InventoryUnavailable = {
+  orderId: 'c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53',
+  cartId: '2c8f0b6d-5a3e-4c9f-8d1b-6e4a7c0f2b91',
+  unavailableItems: [
+    {
+      productId: 'd2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72',
+      requested: 1,
+      available: 0,
+    },
+  ],
+  checkedAt: '2026-09-20T17:03:44Z',
+};
+
+await client.publish('InventoryUnavailable', event);
+```
+
+```python publish_inventory_unavailable.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53",
+    "cartId": "2c8f0b6d-5a3e-4c9f-8d1b-6e4a7c0f2b91",
+    "unavailableItems": [
+        {
+            "productId": "d2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72",
+            "requested": 1,
+            "available": 0,
+        },
+    ],
+    "checkedAt": "2026-09-20T17:03:44Z",
+}
+
+client.publish("InventoryUnavailable", event)
+```
+
+```java PublishInventoryUnavailable.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class PublishInventoryUnavailable {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53",
+      "cartId", "2c8f0b6d-5a3e-4c9f-8d1b-6e4a7c0f2b91",
+      "unavailableItems", List.of(
+        Map.of(
+          "productId", "d2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72",
+          "requested", 1,
+          "available", 0
+        )
+      ),
+      "checkedAt", "2026-09-20T17:03:44Z"
+    );
+
+    client.publish("InventoryUnavailable", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish a partial shortage for a cart
+
+A cart asks for more T-shirts and caps than are left. The event lists every short item and links to the cart only, because no order exists yet.
+
+### Payload details
+
+- `unavailableItems` has two entries: 3 T-shirts requested with 1 available, and 2 caps requested with 0 available.
+- `cartId` is set; `orderId` is omitted.
+- `unavailableItems` and `checkedAt` are the only required fields.
+
+The cart is short by **4 units**: 2 T-shirts and 2 caps.
+
+### Using this example
+
+Consumers should show the customer the `available` count for each item so they can reduce the quantity and try again.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the InventoryUnavailable schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-inventory-unavailable.ts
+import { EventsClient } from '@acme/events';
+import type { InventoryUnavailable } from './schemas/inventory-unavailable';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: InventoryUnavailable = {
+  cartId: 'f5d3a8e2-0c7b-4e1f-9a6d-3b8c5e2f0a47',
+  unavailableItems: [
+    {
+      productId: '0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95',
+      requested: 3,
+      available: 1,
+    },
+    {
+      productId: '6c1f9a4e-3d7b-4a2c-8f5e-9b0d2c7a1e38',
+      requested: 2,
+      available: 0,
+    },
+  ],
+  checkedAt: '2026-09-14T08:10:02Z',
+};
+
+await client.publish('InventoryUnavailable', event);
+```
+
+```python publish_inventory_unavailable.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "cartId": "f5d3a8e2-0c7b-4e1f-9a6d-3b8c5e2f0a47",
+    "unavailableItems": [
+        {
+            "productId": "0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95",
+            "requested": 3,
+            "available": 1,
+        },
+        {
+            "productId": "6c1f9a4e-3d7b-4a2c-8f5e-9b0d2c7a1e38",
+            "requested": 2,
+            "available": 0,
+        },
+    ],
+    "checkedAt": "2026-09-14T08:10:02Z",
+}
+
+client.publish("InventoryUnavailable", event)
+```
+
+```java PublishInventoryUnavailable.java
+import com.acme.events.EventsClient;
+import java.util.List;
+import java.util.Map;
+
+public class PublishInventoryUnavailable {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "cartId", "f5d3a8e2-0c7b-4e1f-9a6d-3b8c5e2f0a47",
+      "unavailableItems", List.of(
+        Map.of(
+          "productId", "0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95",
+          "requested", 3,
+          "available", 1
+        ),
+        Map.of(
+          "productId", "6c1f9a4e-3d7b-4a2c-8f5e-9b0d2c7a1e38",
+          "requested", 2,
+          "available", 0
+        )
+      ),
+      "checkedAt", "2026-09-14T08:10:02Z"
+    );
+
+    client.publish("InventoryUnavailable", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/examples/index.mdx

@@ -0,0 +1,186 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Get the stock level of a product in stock
+
+A product page or the checkout asks the Inventory Service how many of a T-shirt it can still sell. The response comes straight from the inventory database.
+
+### Payload details
+
+- The request has one field, `productId`, for the T-shirt.
+- `available` is `42`: units that can still be sold.
+- `reserved` is `6`: units held for checkouts in progress.
+
+### Example response
+
+```json
+{
+  "productId": "0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95",
+  "available": 42,
+  "reserved": 6
+}
+```
+
+### Using this example
+
+A caller should show the product as in stock because `available` is above zero. Use this pair to test stock badges and quantity limits.
+
+The examples use a **fictional Acme Events SDK** to query a payload matching the GetStockLevel schema. The package names and query methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript query-get-stock-level.ts
+import { EventsClient } from '@acme/events';
+import type { GetStockLevelRequest, GetStockLevelResponse } from './schemas/get-stock-level';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: GetStockLevelRequest = {
+  productId: '0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95',
+};
+
+const stock: GetStockLevelResponse = await client.query('GetStockLevel', request);
+
+console.log(stock.available, stock.reserved);
+```
+
+```python query_get_stock_level.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "productId": "0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95",
+}
+
+stock = client.query("GetStockLevel", request)
+print(stock["available"], stock["reserved"])
+```
+
+```java QueryGetStockLevel.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class QueryGetStockLevel {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "productId", "0b8e3d5f-9c2a-4f1e-b7d6-4a2c8e0f3b95"
+    );
+
+    var stock = client.query("GetStockLevel", request);
+    System.out.println(stock.get("available") + " " + stock.get("reserved"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Get the stock level of a sold-out product
+
+The same query for a hoodie that has sold out. No units are held for checkouts, so the Inventory Service leaves out `reserved`.
+
+### Payload details
+
+- The request asks for the hoodie's `productId`.
+- `available` is `0`: the hoodie cannot be sold.
+- `reserved` is omitted, not set to null.
+
+### Example response
+
+```json
+{
+  "productId": "d2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72",
+  "available": 0
+}
+```
+
+### Using this example
+
+A caller should show the hoodie as out of stock and must not treat the missing `reserved` field as an error.
+
+The examples use a **fictional Acme Events SDK** to query a payload matching the GetStockLevel schema. The package names and query methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript query-get-stock-level.ts
+import { EventsClient } from '@acme/events';
+import type { GetStockLevelRequest, GetStockLevelResponse } from './schemas/get-stock-level';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: GetStockLevelRequest = {
+  productId: 'd2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72',
+};
+
+const stock: GetStockLevelResponse = await client.query('GetStockLevel', request);
+
+console.log(stock.productId, stock.available);
+```
+
+```python query_get_stock_level.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "productId": "d2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72",
+}
+
+stock = client.query("GetStockLevel", request)
+print(stock["productId"], stock["available"])
+```
+
+```java QueryGetStockLevel.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class QueryGetStockLevel {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "productId", "d2a5e8c1-7f4b-4e9d-a3c6-1b8f0e5d9a72"
+    );
+
+    var stock = client.query("GetStockLevel", request);
+    System.out.println(stock.get("productId") + " " + stock.get("available"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>