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

package/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/examples/index.mdx

@@ -0,0 +1,194 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish a profile change
+
+A customer changed their surname and email address in account settings. The Customer API publishes this event so systems such as order notifications and marketing can update their copy of the customer.
+
+### Payload details
+
+- `eventId` is a unique UUID for this event, and `occurredAt` is the ISO-8601 UTC time of the change.
+- `customerId` identifies the customer that changed.
+- `changes` holds only the fields that changed, with their new values: `email` and `name`.
+- `status` is not in `changes`, so it did not change.
+
+### Using this example
+
+Use this to check that consumers apply only the fields present in `changes` and leave everything else as it was.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the CustomerUpdated schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-customer-updated.ts
+import { EventsClient } from '@acme/events';
+import type { CustomerUpdated } from './schemas/customer-updated';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: CustomerUpdated = {
+  eventId: '7b9d2f4a-6c8e-4a1b-b3d5-9f1e3a5c7b20',
+  occurredAt: '2026-09-11T08:12:45Z',
+  customerId: '3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c',
+  changes: {
+    email: 'amelia.hart-jones@example.com',
+    name: 'Amelia Hart-Jones',
+  },
+};
+
+await client.publish('CustomerUpdated', event);
+```
+
+```python publish_customer_updated.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "eventId": "7b9d2f4a-6c8e-4a1b-b3d5-9f1e3a5c7b20",
+    "occurredAt": "2026-09-11T08:12:45Z",
+    "customerId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c",
+    "changes": {
+        "email": "amelia.hart-jones@example.com",
+        "name": "Amelia Hart-Jones",
+    },
+}
+
+client.publish("CustomerUpdated", event)
+```
+
+```java PublishCustomerUpdated.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishCustomerUpdated {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "eventId", "7b9d2f4a-6c8e-4a1b-b3d5-9f1e3a5c7b20",
+      "occurredAt", "2026-09-11T08:12:45Z",
+      "customerId", "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c",
+      "changes", Map.of(
+        "email", "amelia.hart-jones@example.com",
+        "name", "Amelia Hart-Jones"
+      )
+    );
+
+    client.publish("CustomerUpdated", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish a status change
+
+The fraud team suspended an account after a chargeback. The event carries a single change, so consumers such as checkout and order fulfilment can stop processing new orders for this customer.
+
+### Payload details
+
+- `eventId` and `occurredAt` identify this event and when the account was suspended.
+- `customerId` identifies the suspended customer.
+- `changes.status` is `SUSPENDED`. The schema requires at least one field in `changes`, and here there is exactly one.
+- `email` and `name` are not in `changes`, so they did not change.
+
+### Using this example
+
+Use this to check that consumers react to a `status` change on its own, for example by blocking checkout for `SUSPENDED` customers.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the CustomerUpdated schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-customer-updated.ts
+import { EventsClient } from '@acme/events';
+import type { CustomerUpdated } from './schemas/customer-updated';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: CustomerUpdated = {
+  eventId: 'e4f6a8b0-3c5d-4e7f-9a1b-6c8d0e2f4a36',
+  occurredAt: '2026-09-15T14:03:19Z',
+  customerId: 'c9a4e2f7-1b3d-4c8e-a5f6-7d2e9b0c4a13',
+  changes: {
+    status: 'SUSPENDED',
+  },
+};
+
+await client.publish('CustomerUpdated', event);
+```
+
+```python publish_customer_updated.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "eventId": "e4f6a8b0-3c5d-4e7f-9a1b-6c8d0e2f4a36",
+    "occurredAt": "2026-09-15T14:03:19Z",
+    "customerId": "c9a4e2f7-1b3d-4c8e-a5f6-7d2e9b0c4a13",
+    "changes": {
+        "status": "SUSPENDED",
+    },
+}
+
+client.publish("CustomerUpdated", event)
+```
+
+```java PublishCustomerUpdated.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishCustomerUpdated {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "eventId", "e4f6a8b0-3c5d-4e7f-9a1b-6c8d0e2f4a36",
+      "occurredAt", "2026-09-15T14:03:19Z",
+      "customerId", "c9a4e2f7-1b3d-4c8e-a5f6-7d2e9b0c4a13",
+      "changes", Map.of(
+        "status", "SUSPENDED"
+      )
+    );
+
+    client.publish("CustomerUpdated", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/examples/index.mdx

@@ -0,0 +1,194 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Fetch an active customer's profile
+
+The storefront account page asks the Customer API for the signed-in customer so it can show their name and email address. The Customer API reads the record from the customer database and returns it.
+
+### Payload details
+
+- `request.customerId` is the UUID of the customer to look up, taken from the customer's session.
+- The response includes every field: `email`, `name` and `registeredAt` alongside the required `customerId` and `status`.
+- `status` is `ACTIVE`, so the customer can browse, check out and manage their account as normal.
+- `registeredAt` is an ISO-8601 UTC timestamp showing when the account was created.
+
+### Example response
+
+```json
+{
+  "customerId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c",
+  "email": "amelia.hart@example.com",
+  "name": "Amelia Hart",
+  "status": "ACTIVE",
+  "registeredAt": "2026-03-14T10:22:05Z"
+}
+```
+
+### Using this example
+
+Use this to check that the account page renders the customer's name and email, and that the returned `customerId` matches the one requested.
+
+The examples use a **fictional Acme Events SDK** to query a payload matching the GetCustomer schema. The package names and query methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript query-get-customer.ts
+import { EventsClient } from '@acme/events';
+import type { GetCustomerRequest, GetCustomerResponse } from './schemas/get-customer';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: GetCustomerRequest = {
+  customerId: '3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c',
+};
+
+const customer: GetCustomerResponse = await client.query('GetCustomer', request);
+
+console.log(customer.name, customer.email);
+```
+
+```python query_get_customer.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "customerId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c",
+}
+
+customer = client.query("GetCustomer", request)
+
+print(customer["name"], customer["email"])
+```
+
+```java QueryGetCustomer.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class QueryGetCustomer {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "customerId", "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c"
+    );
+
+    var customer = client.query("GetCustomer", request);
+
+    System.out.println(customer.get("name") + " " + customer.get("email"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Check a suspended customer before checkout
+
+Before accepting an order, the checkout flow queries the customer to confirm the account is in good standing. This customer has been suspended, so checkout should stop and point them to support.
+
+### Payload details
+
+- `request.customerId` identifies the customer placing the order.
+- The response contains only the required fields: `customerId`, `email` and `status`. The optional `name` and `registeredAt` are omitted.
+- `status` is `SUSPENDED`, which means the account exists but must not be allowed to place orders.
+
+### Example response
+
+```json
+{
+  "customerId": "c9a4e2f7-1b3d-4c8e-a5f6-7d2e9b0c4a13",
+  "email": "tom.okafor@example.co.uk",
+  "status": "SUSPENDED"
+}
+```
+
+### Using this example
+
+Use this to check that callers cope with a response that has no `name` or `registeredAt`, and that checkout blocks any customer whose `status` is not `ACTIVE`.
+
+The examples use a **fictional Acme Events SDK** to query a payload matching the GetCustomer schema. The package names and query methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript query-get-customer.ts
+import { EventsClient } from '@acme/events';
+import type { GetCustomerRequest, GetCustomerResponse } from './schemas/get-customer';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: GetCustomerRequest = {
+  customerId: 'c9a4e2f7-1b3d-4c8e-a5f6-7d2e9b0c4a13',
+};
+
+const customer: GetCustomerResponse = await client.query('GetCustomer', request);
+
+console.log(customer.status, customer.email);
+```
+
+```python query_get_customer.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "customerId": "c9a4e2f7-1b3d-4c8e-a5f6-7d2e9b0c4a13",
+}
+
+customer = client.query("GetCustomer", request)
+
+print(customer["status"], customer["email"])
+```
+
+```java QueryGetCustomer.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class QueryGetCustomer {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "customerId", "c9a4e2f7-1b3d-4c8e-a5f6-7d2e9b0c4a13"
+    );
+
+    var customer = client.query("GetCustomer", request);
+
+    System.out.println(customer.get("status") + " " + customer.get("email"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/examples/index.mdx

@@ -0,0 +1,198 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Sign a customer in from the storefront
+
+A customer signs in on the web storefront to view their orders. The OAuth API checks the credentials against the user directory, returns an access token and publishes `CustomerAuthenticated`.
+
+### Payload details
+
+- `request.email` and `request.password` are the credentials the customer typed in.
+- `response.accessToken` is the token the storefront sends with later API calls.
+- `response.tokenType` is always `Bearer`.
+- `response.expiresIn` is the token lifetime in seconds: **3,600 seconds (1 hour)**.
+
+### Example response
+
+```json
+{
+  "accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIzZjJiOGMxZSJ9.kX9vQ2Lm",
+  "tokenType": "Bearer",
+  "expiresIn": 3600
+}
+```
+
+### Using this example
+
+Use this to check that a valid sign-in returns a `Bearer` token, and that the client refreshes or re-authenticates before `expiresIn` runs out.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the AuthenticateCustomer schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-authenticate-customer.ts
+import { EventsClient } from '@acme/events';
+import type { AuthenticateCustomerRequest, AuthenticateCustomerResponse } from './schemas/authenticate-customer';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: AuthenticateCustomerRequest = {
+  email: 'amelia.hart@example.com',
+  password: 'Blue-Tshirt-42!',
+};
+
+const token: AuthenticateCustomerResponse = await client.send('AuthenticateCustomer', request);
+
+console.log(token.tokenType, token.expiresIn);
+```
+
+```python send_authenticate_customer.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "email": "amelia.hart@example.com",
+    "password": "Blue-Tshirt-42!",
+}
+
+token = client.send("AuthenticateCustomer", request)
+
+print(token["tokenType"], token["expiresIn"])
+```
+
+```java SendAuthenticateCustomer.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendAuthenticateCustomer {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "email", "amelia.hart@example.com",
+      "password", "Blue-Tshirt-42!"
+    );
+
+    var token = client.send("AuthenticateCustomer", request);
+
+    System.out.println(token.get("tokenType") + " " + token.get("expiresIn"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Sign a customer in during checkout
+
+A returning customer signs in part-way through checking out a basket of caps. The OAuth API issues a short-lived token that only needs to last until the order is placed.
+
+### Payload details
+
+- `request.email` and `request.password` are the customer's credentials.
+- `response.tokenType` is `Bearer`.
+- `response.expiresIn` is **900 seconds (15 minutes)**, so the client must handle the token expiring and ask the customer to sign in again.
+
+### Example response
+
+```json
+{
+  "accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjOWE0ZTJmNyJ9.pR4tZ8Wn",
+  "tokenType": "Bearer",
+  "expiresIn": 900
+}
+```
+
+### Using this example
+
+Use this to check that the client reads `expiresIn` rather than assuming a fixed lifetime, and prompts for sign-in again once the token has expired.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the AuthenticateCustomer schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-authenticate-customer.ts
+import { EventsClient } from '@acme/events';
+import type { AuthenticateCustomerRequest, AuthenticateCustomerResponse } from './schemas/authenticate-customer';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const request: AuthenticateCustomerRequest = {
+  email: 'tom.okafor@example.co.uk',
+  password: 'Hoodie-Season-2026',
+};
+
+const token: AuthenticateCustomerResponse = await client.send('AuthenticateCustomer', request);
+
+console.log(token.tokenType, token.expiresIn);
+```
+
+```python send_authenticate_customer.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+request = {
+    "email": "tom.okafor@example.co.uk",
+    "password": "Hoodie-Season-2026",
+}
+
+token = client.send("AuthenticateCustomer", request)
+
+print(token["tokenType"], token["expiresIn"])
+```
+
+```java SendAuthenticateCustomer.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendAuthenticateCustomer {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var request = Map.of(
+      "email", "tom.okafor@example.co.uk",
+      "password", "Hoodie-Season-2026"
+    );
+
+    var token = client.send("AuthenticateCustomer", request);
+
+    System.out.println(token.get("tokenType") + " " + token.get("expiresIn"));
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>