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

package/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/examples/index.mdx

@@ -0,0 +1,206 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Send a next-day shipment for one parcel
+
+The Carrier Adapter sends this command once an order is ready for shipping and the customer paid for next-day delivery. The carrier creates the shipment and replies with `ShipmentCreated`.
+
+### Payload details
+
+- `orderId` is the packed order being dispatched.
+- `carrier` is `Royal Mail`, the carrier chosen for UK next-day orders.
+- `service` is `NEXT_DAY`, the fastest of the three service levels.
+- `parcelCount` is `1`: two T-shirts and a cap fit in one mailing bag.
+- `destination` is a UK address, so `country` is the two-letter code `GB`.
+
+### Using this example
+
+A carrier stub should accept this command and book one next-day parcel to the Manchester address. Use it to check that `service` and `parcelCount` are passed to the carrier unchanged.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CreateShipment schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-create-shipment.ts
+import { EventsClient } from '@acme/events';
+import type { CreateShipment } from './schemas/create-shipment';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: CreateShipment = {
+  orderId: '3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27',
+  carrier: 'Royal Mail',
+  service: 'NEXT_DAY',
+  parcelCount: 1,
+  destination: {
+    line1: '14 Victoria Road',
+    city: 'Manchester',
+    postcode: 'M14 5RT',
+    country: 'GB',
+  },
+};
+
+await client.send('CreateShipment', command);
+```
+
+```python send_create_shipment.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "orderId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+    "carrier": "Royal Mail",
+    "service": "NEXT_DAY",
+    "parcelCount": 1,
+    "destination": {
+        "line1": "14 Victoria Road",
+        "city": "Manchester",
+        "postcode": "M14 5RT",
+        "country": "GB",
+    },
+}
+
+client.send("CreateShipment", command)
+```
+
+```java SendCreateShipment.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendCreateShipment {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "orderId", "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+      "carrier", "Royal Mail",
+      "service", "NEXT_DAY",
+      "parcelCount", 1,
+      "destination", Map.of(
+        "line1", "14 Victoria Road",
+        "city", "Manchester",
+        "postcode", "M14 5RT",
+        "country", "GB"
+      )
+    );
+
+    client.send("CreateShipment", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Send a shipment with only the required fields
+
+This is the smallest valid command: the order and where it is going. It is used when the order has no delivery preference and the Carrier Adapter leaves carrier and service selection to its own configuration.
+
+### Payload details
+
+- `orderId` and `destination` are the only required fields.
+- `carrier`, `service` and `parcelCount` are omitted, not set to null.
+- `destination.country` is `IE` for an order going to Dublin.
+
+### Using this example
+
+Use this payload to test that the handler accepts a command without the optional fields and does not fail on missing `carrier` or `service`.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the CreateShipment schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-create-shipment.ts
+import { EventsClient } from '@acme/events';
+import type { CreateShipment } from './schemas/create-shipment';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: CreateShipment = {
+  orderId: 'c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53',
+  destination: {
+    line1: '22 Harcourt Street',
+    city: 'Dublin',
+    postcode: 'D02 H364',
+    country: 'IE',
+  },
+};
+
+await client.send('CreateShipment', command);
+```
+
+```python send_create_shipment.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "orderId": "c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53",
+    "destination": {
+        "line1": "22 Harcourt Street",
+        "city": "Dublin",
+        "postcode": "D02 H364",
+        "country": "IE",
+    },
+}
+
+client.send("CreateShipment", command)
+```
+
+```java SendCreateShipment.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendCreateShipment {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "orderId", "c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53",
+      "destination", Map.of(
+        "line1", "22 Harcourt Street",
+        "city", "Dublin",
+        "postcode", "D02 H364",
+        "country", "IE"
+      )
+    );
+
+    client.send("CreateShipment", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/examples/index.mdx

@@ -0,0 +1,172 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish an order packed from a picking job
+
+The Picking Worker publishes this event when every item in a picking job is picked and packed. The Warehouse Service consumes it and publishes `OrderReadyForShipping`.
+
+### Payload details
+
+- `orderId` is the order that was packed.
+- `pickingJobId` is the picking job that collected the items from the shelves.
+- `parcelCount` is `1`: two T-shirts and a cap fit in one mailing bag.
+- `packedAt` is the UTC time the parcel was sealed.
+
+### Using this example
+
+A Warehouse Service consumer should mark the order as ready and publish `OrderReadyForShipping` with the same `orderId`.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderPacked schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-packed.ts
+import { EventsClient } from '@acme/events';
+import type { OrderPacked } from './schemas/order-packed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderPacked = {
+  orderId: '3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27',
+  pickingJobId: 'e8d2a7b4-1c9f-4a6e-b3d5-7f0c2e9a8b61',
+  parcelCount: 1,
+  packedAt: '2026-09-14T09:42:08Z',
+};
+
+await client.publish('OrderPacked', event);
+```
+
+```python publish_order_packed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+    "pickingJobId": "e8d2a7b4-1c9f-4a6e-b3d5-7f0c2e9a8b61",
+    "parcelCount": 1,
+    "packedAt": "2026-09-14T09:42:08Z",
+}
+
+client.publish("OrderPacked", event)
+```
+
+```java PublishOrderPacked.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderPacked {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+      "pickingJobId", "e8d2a7b4-1c9f-4a6e-b3d5-7f0c2e9a8b61",
+      "parcelCount", 1,
+      "packedAt", "2026-09-14T09:42:08Z"
+    );
+
+    client.publish("OrderPacked", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish an order packed by hand
+
+Some orders are packed at a manual packing bench without a picking job, for example a replacement hoodie. The event then carries only the order and the time.
+
+### Payload details
+
+- `orderId` and `packedAt` are the only required fields.
+- `pickingJobId` is omitted because no picking job was used.
+- `parcelCount` is omitted, not set to null.
+
+### Using this example
+
+Use this payload to check that the Warehouse Service still marks the order ready when `pickingJobId` and `parcelCount` are missing.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderPacked schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-packed.ts
+import { EventsClient } from '@acme/events';
+import type { OrderPacked } from './schemas/order-packed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderPacked = {
+  orderId: 'c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53',
+  packedAt: '2026-09-14T11:17:30Z',
+};
+
+await client.publish('OrderPacked', event);
+```
+
+```python publish_order_packed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53",
+    "packedAt": "2026-09-14T11:17:30Z",
+}
+
+client.publish("OrderPacked", event)
+```
+
+```java PublishOrderPacked.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderPacked {
+  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",
+      "packedAt", "2026-09-14T11:17:30Z"
+    );
+
+    client.publish("OrderPacked", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/examples/index.mdx

@@ -0,0 +1,208 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish a packed single-parcel order
+
+The Warehouse Service publishes this event after `OrderPacked` arrives for an order. The Shipping System consumes it and sends `CreateShipment` to the carrier.
+
+### Payload details
+
+- `orderId` and `customerId` link the event back to the order and the customer.
+- `parcelCount` is `1`, so the carrier books a single parcel.
+- `shippingAddress` is a UK address with `country` set to `GB`.
+- `readyAt` is the UTC time the order was marked ready, three minutes after packing finished.
+
+### Using this example
+
+A Shipping System consumer should turn this event into a `CreateShipment` command with the same `orderId`, parcel count and address.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderReadyForShipping schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-ready-for-shipping.ts
+import { EventsClient } from '@acme/events';
+import type { OrderReadyForShipping } from './schemas/order-ready-for-shipping';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderReadyForShipping = {
+  orderId: '3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27',
+  customerId: 'a4c9e2f1-6b7d-4c3e-8f5a-2d1b9e7c6a40',
+  parcelCount: 1,
+  shippingAddress: {
+    line1: '14 Victoria Road',
+    city: 'Manchester',
+    postcode: 'M14 5RT',
+    country: 'GB',
+  },
+  readyAt: '2026-09-14T09:45:12Z',
+};
+
+await client.publish('OrderReadyForShipping', event);
+```
+
+```python publish_order_ready_for_shipping.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+    "customerId": "a4c9e2f1-6b7d-4c3e-8f5a-2d1b9e7c6a40",
+    "parcelCount": 1,
+    "shippingAddress": {
+        "line1": "14 Victoria Road",
+        "city": "Manchester",
+        "postcode": "M14 5RT",
+        "country": "GB",
+    },
+    "readyAt": "2026-09-14T09:45:12Z",
+}
+
+client.publish("OrderReadyForShipping", event)
+```
+
+```java PublishOrderReadyForShipping.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderReadyForShipping {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "orderId", "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b27",
+      "customerId", "a4c9e2f1-6b7d-4c3e-8f5a-2d1b9e7c6a40",
+      "parcelCount", 1,
+      "shippingAddress", Map.of(
+        "line1", "14 Victoria Road",
+        "city", "Manchester",
+        "postcode", "M14 5RT",
+        "country", "GB"
+      ),
+      "readyAt", "2026-09-14T09:45:12Z"
+    );
+
+    client.publish("OrderReadyForShipping", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish with only the required fields
+
+The Warehouse Service may not have the customer or parcel details to hand, for example when an order was packed by hand. The event then carries only the order, the address and the time.
+
+### Payload details
+
+- `orderId`, `shippingAddress` and `readyAt` are the only required fields.
+- `customerId` and `parcelCount` are omitted, not set to null.
+- `shippingAddress.country` is `IE` for an order going to Dublin.
+
+### Using this example
+
+Use this payload to check that consumers handle a missing `parcelCount` and `customerId` without failing.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the OrderReadyForShipping schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-order-ready-for-shipping.ts
+import { EventsClient } from '@acme/events';
+import type { OrderReadyForShipping } from './schemas/order-ready-for-shipping';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: OrderReadyForShipping = {
+  orderId: 'c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53',
+  shippingAddress: {
+    line1: '22 Harcourt Street',
+    city: 'Dublin',
+    postcode: 'D02 H364',
+    country: 'IE',
+  },
+  readyAt: '2026-09-14T11:20:03Z',
+};
+
+await client.publish('OrderReadyForShipping', event);
+```
+
+```python publish_order_ready_for_shipping.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "orderId": "c7e41d92-5b3a-4f86-a1d4-8e2f9b6c0d53",
+    "shippingAddress": {
+        "line1": "22 Harcourt Street",
+        "city": "Dublin",
+        "postcode": "D02 H364",
+        "country": "IE",
+    },
+    "readyAt": "2026-09-14T11:20:03Z",
+}
+
+client.publish("OrderReadyForShipping", event)
+```
+
+```java PublishOrderReadyForShipping.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishOrderReadyForShipping {
+  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",
+      "shippingAddress", Map.of(
+        "line1", "22 Harcourt Street",
+        "city", "Dublin",
+        "postcode", "D02 H364",
+        "country", "IE"
+      ),
+      "readyAt", "2026-09-14T11:20:03Z"
+    );
+
+    client.publish("OrderReadyForShipping", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>