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

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/examples/index.mdx

@@ -0,0 +1,186 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Confirm a full refund
+
+Stripe completes the full refund for the cancelled T-shirt and cap order. The StripeWebhookEndpoint publishes `RefundProcessed` and the PaymentWorker records the refund as complete.
+
+### Payload details
+
+- `refundId` matches the `RefundRequested` event that started the refund.
+- `paymentId` is the original charge that was refunded.
+- `amount` is the full original charge, in pence.
+
+The customer received **4,298 pence (£42.98)**.
+
+### Using this example
+
+Consumers should match `refundId` to the pending refund and mark it complete. Tests can assert that `amount` equals the requested refund.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the RefundProcessed schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-refund-processed.ts
+import { EventsClient } from '@acme/events';
+import type { RefundProcessed } from './schemas/refund-processed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: RefundProcessed = {
+  refundId: 'b5e477d7-f910-43f5-a371-e9f3f53cfaa2',
+  paymentId: '586e57ab-77a9-406a-945d-4619c76a582e',
+  amount: 4298,
+  currency: 'GBP',
+  processedAt: '2026-09-11T14:05:31Z',
+};
+
+await client.publish('RefundProcessed', event);
+```
+
+```python publish_refund_processed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "refundId": "b5e477d7-f910-43f5-a371-e9f3f53cfaa2",
+    "paymentId": "586e57ab-77a9-406a-945d-4619c76a582e",
+    "amount": 4298,
+    "currency": "GBP",
+    "processedAt": "2026-09-11T14:05:31Z",
+}
+
+client.publish("RefundProcessed", event)
+```
+
+```java PublishRefundProcessed.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishRefundProcessed {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "refundId", "b5e477d7-f910-43f5-a371-e9f3f53cfaa2",
+      "paymentId", "586e57ab-77a9-406a-945d-4619c76a582e",
+      "amount", 4298,
+      "currency", "GBP",
+      "processedAt", "2026-09-11T14:05:31Z"
+    );
+
+    client.publish("RefundProcessed", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Confirm a partial refund
+
+Stripe refunds one returned hoodie from the guest order. Only part of the original €164.97 payment is returned.
+
+### Payload details
+
+- `amount` is one hoodie at €54.99, in cents.
+- `currency` is `EUR`, the same as the original charge.
+
+The customer received **5,499 cents (€54.99)**; 10,998 cents (€109.98) stays charged.
+
+### Using this example
+
+Use this payload to check that consumers record a partial refund without marking the whole payment as refunded.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the RefundProcessed schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-refund-processed.ts
+import { EventsClient } from '@acme/events';
+import type { RefundProcessed } from './schemas/refund-processed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: RefundProcessed = {
+  refundId: 'f57e3268-60d1-4b1d-96e9-c27d47992d47',
+  paymentId: '41651c3f-fa8e-40fc-a217-a83929d15081',
+  amount: 5499,
+  currency: 'EUR',
+  processedAt: '2026-09-21T09:40:22Z',
+};
+
+await client.publish('RefundProcessed', event);
+```
+
+```python publish_refund_processed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "refundId": "f57e3268-60d1-4b1d-96e9-c27d47992d47",
+    "paymentId": "41651c3f-fa8e-40fc-a217-a83929d15081",
+    "amount": 5499,
+    "currency": "EUR",
+    "processedAt": "2026-09-21T09:40:22Z",
+}
+
+client.publish("RefundProcessed", event)
+```
+
+```java PublishRefundProcessed.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishRefundProcessed {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "refundId", "f57e3268-60d1-4b1d-96e9-c27d47992d47",
+      "paymentId", "41651c3f-fa8e-40fc-a217-a83929d15081",
+      "amount", 5499,
+      "currency", "EUR",
+      "processedAt", "2026-09-21T09:40:22Z"
+    );
+
+    client.publish("RefundProcessed", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/examples/index.mdx

@@ -0,0 +1,183 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish a small rise in a product's rating
+
+A five-star review for the classic white T-shirt has just been published. The Rating Aggregator recalculates the product's rating and publishes this event so the storefront and search can refresh it.
+
+### Payload details
+
+- `productId` is `prod_tshirt_classic_white`.
+- `reviewCount` is `128`: the 127 earlier published reviews plus the new one.
+- `averageRating` is `4.6`, rounded to two decimal places and within the 0 to 5 range.
+- `updatedAt` is when the aggregate was recalculated.
+
+The product now has **589 stars across 128 reviews**, so the average is 589 / 128 = **4.60** (up from 584 / 127 = 4.598).
+
+### Using this example
+
+Consumers should replace any cached rating for this `productId` with `averageRating` and `reviewCount` rather than trying to apply a delta.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the RatingUpdated schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-rating-updated.ts
+import { EventsClient } from '@acme/events';
+import type { RatingUpdated } from './schemas/rating-updated';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: RatingUpdated = {
+  productId: 'prod_tshirt_classic_white',
+  averageRating: 4.6,
+  reviewCount: 128,
+  updatedAt: '2026-09-14T18:23:05Z',
+};
+
+await client.publish('RatingUpdated', event);
+```
+
+```python publish_rating_updated.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "productId": "prod_tshirt_classic_white",
+    "averageRating": 4.6,
+    "reviewCount": 128,
+    "updatedAt": "2026-09-14T18:23:05Z",
+}
+
+client.publish("RatingUpdated", event)
+```
+
+```java PublishRatingUpdated.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishRatingUpdated {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "productId", "prod_tshirt_classic_white",
+      "averageRating", 4.6,
+      "reviewCount", 128,
+      "updatedAt", "2026-09-14T18:23:05Z"
+    );
+
+    client.publish("RatingUpdated", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish a drop in a product's rating
+
+A two-star review for the oversized grey hoodie has been published. With only a few reviews, one low rating moves the average noticeably.
+
+### Payload details
+
+- `productId` is `prod_hoodie_oversized_grey`.
+- `reviewCount` is `7`: six earlier reviews plus the new two-star review.
+- `averageRating` is `4.14`, rounded to two decimal places.
+- `updatedAt` is when the aggregate was recalculated.
+
+The six earlier reviews had **27 stars** (average 4.50). Adding 2 gives **29 stars across 7 reviews**, so the average is 29 / 7 = **4.14**.
+
+### Using this example
+
+Use this payload to check that product pages and search results show the lower rating, and that any "4.5 stars and up" filter no longer includes this product.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the RatingUpdated schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-rating-updated.ts
+import { EventsClient } from '@acme/events';
+import type { RatingUpdated } from './schemas/rating-updated';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: RatingUpdated = {
+  productId: 'prod_hoodie_oversized_grey',
+  averageRating: 4.14,
+  reviewCount: 7,
+  updatedAt: '2026-09-15T09:05:41Z',
+};
+
+await client.publish('RatingUpdated', event);
+```
+
+```python publish_rating_updated.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "productId": "prod_hoodie_oversized_grey",
+    "averageRating": 4.14,
+    "reviewCount": 7,
+    "updatedAt": "2026-09-15T09:05:41Z",
+}
+
+client.publish("RatingUpdated", event)
+```
+
+```java PublishRatingUpdated.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishRatingUpdated {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "productId", "prod_hoodie_oversized_grey",
+      "averageRating", 4.14,
+      "reviewCount", 7,
+      "updatedAt", "2026-09-15T09:05:41Z"
+    );
+
+    client.publish("RatingUpdated", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/examples/index.mdx

@@ -0,0 +1,183 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Flag an off-topic review with notes
+
+A shopper reading reviews for the navy baseball cap reports one that only complains about delivery times. The storefront sends this command to the Review API, which records the flag and publishes `ReviewFlagged`.
+
+### Payload details
+
+- `reviewId` is the published review being reported.
+- `flaggedBy` is the customer id `cust_2290`.
+- `reason` is `off_topic`, one of `spam`, `abuse`, `off_topic`, `inappropriate` or `other`.
+- `notes` (optional, max 1,000 characters) gives the moderator some context.
+- `flaggedAt` is when the customer sent the report.
+
+### Using this example
+
+Check that the Review API stores the flag and publishes `ReviewFlagged` with the same `reviewId` and `reason`.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the FlagReview schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-flag-review.ts
+import { EventsClient } from '@acme/events';
+import type { FlagReview } from './schemas/flag-review';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: FlagReview = {
+  reviewId: 'b2d6f8a1-4c3e-4a9b-9f7d-5e1c3a8b0d24',
+  flaggedBy: 'cust_2290',
+  reason: 'off_topic',
+  notes: 'This is about delivery times, not the cap itself.',
+  flaggedAt: '2026-09-16T12:40:18Z',
+};
+
+await client.send('FlagReview', command);
+```
+
+```python send_flag_review.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "reviewId": "b2d6f8a1-4c3e-4a9b-9f7d-5e1c3a8b0d24",
+    "flaggedBy": "cust_2290",
+    "reason": "off_topic",
+    "notes": "This is about delivery times, not the cap itself.",
+    "flaggedAt": "2026-09-16T12:40:18Z",
+}
+
+client.send("FlagReview", command)
+```
+
+```java SendFlagReview.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendFlagReview {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "reviewId", "b2d6f8a1-4c3e-4a9b-9f7d-5e1c3a8b0d24",
+      "flaggedBy", "cust_2290",
+      "reason", "off_topic",
+      "notes", "This is about delivery times, not the cap itself.",
+      "flaggedAt", "2026-09-16T12:40:18Z"
+    );
+
+    client.send("FlagReview", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Flag an abusive review as a moderator
+
+A moderator doing a routine check spots an abusive review on the sunset graphic T-shirt and flags it from the moderation console, without adding notes.
+
+### Payload details
+
+- `flaggedBy` is the moderator id `mod_017`; the same field holds customer or moderator ids.
+- `reason` is `abuse`.
+- `notes` is omitted because it is optional.
+- `flaggedAt` is the UTC time of the flag.
+
+### Using this example
+
+Use this payload to test that flags from moderators and customers follow the same path, and that a missing `notes` field is accepted.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the FlagReview schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-flag-review.ts
+import { EventsClient } from '@acme/events';
+import type { FlagReview } from './schemas/flag-review';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: FlagReview = {
+  reviewId: 'd8a3c5e7-2f1b-4e9d-b4a6-7c0e3f5a1b82',
+  flaggedBy: 'mod_017',
+  reason: 'abuse',
+  flaggedAt: '2026-09-17T08:15:00Z',
+};
+
+await client.send('FlagReview', command);
+```
+
+```python send_flag_review.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "reviewId": "d8a3c5e7-2f1b-4e9d-b4a6-7c0e3f5a1b82",
+    "flaggedBy": "mod_017",
+    "reason": "abuse",
+    "flaggedAt": "2026-09-17T08:15:00Z",
+}
+
+client.send("FlagReview", command)
+```
+
+```java SendFlagReview.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendFlagReview {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "reviewId", "d8a3c5e7-2f1b-4e9d-b4a6-7c0e3f5a1b82",
+      "flaggedBy", "mod_017",
+      "reason", "abuse",
+      "flaggedAt", "2026-09-17T08:15:00Z"
+    );
+
+    client.send("FlagReview", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>