@eventcatalog/create-eventcatalog 4.3.12 → 4.3.13

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

@@ -0,0 +1,195 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Submit a five-star review with a title
+
+A customer who bought the classic white T-shirt leaves a full review from their order history page. The storefront sends this command to the Review API, which stores the review and publishes `ReviewSubmitted`.
+
+### Payload details
+
+- `reviewId` is generated by the client, so a retried request does not create a duplicate review.
+- `productId` is `prod_tshirt_classic_white` and `customerId` is `cust_4821`.
+- `rating` is `5`, the top of the 1 to 5 star range.
+- `title` (optional, max 120 characters) and `body` (max 5,000 characters) are both set.
+- `submittedAt` is the UTC time the customer pressed submit.
+
+### Using this example
+
+Check that the Review API accepts the command, stores the review as pending moderation and publishes `ReviewSubmitted` with the same `reviewId`.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the SubmitReview schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-submit-review.ts
+import { EventsClient } from '@acme/events';
+import type { SubmitReview } from './schemas/submit-review';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: SubmitReview = {
+  reviewId: '3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90',
+  productId: 'prod_tshirt_classic_white',
+  customerId: 'cust_4821',
+  rating: 5,
+  title: 'Perfect everyday tee',
+  body: 'Soft, thick cotton and it kept its shape after washing.',
+  submittedAt: '2026-09-14T18:22:10Z',
+};
+
+await client.send('SubmitReview', command);
+```
+
+```python send_submit_review.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "reviewId": "3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90",
+    "productId": "prod_tshirt_classic_white",
+    "customerId": "cust_4821",
+    "rating": 5,
+    "title": "Perfect everyday tee",
+    "body": "Soft, thick cotton and it kept its shape after washing.",
+    "submittedAt": "2026-09-14T18:22:10Z",
+}
+
+client.send("SubmitReview", command)
+```
+
+```java SendSubmitReview.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendSubmitReview {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "reviewId", "3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90",
+      "productId", "prod_tshirt_classic_white",
+      "customerId", "cust_4821",
+      "rating", 5,
+      "title", "Perfect everyday tee",
+      "body", "Soft, thick cotton and it kept its shape after washing.",
+      "submittedAt", "2026-09-14T18:22:10Z"
+    );
+
+    client.send("SubmitReview", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Submit a low rating without a title
+
+A customer returns an oversized hoodie and leaves a short two-star review from the mobile app, skipping the optional title.
+
+### Payload details
+
+- Only the required fields are sent; `title` is omitted.
+- `productId` is `prod_hoodie_oversized_grey` and `customerId` is `cust_1057`.
+- `rating` is `2`, so this review will pull the product's average rating down once it is published.
+- `body` explains the sizing problem in the customer's own words.
+
+### Using this example
+
+Use this payload to test that a review without a `title` is accepted and that low ratings go through the same moderation path as high ones.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the SubmitReview schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-submit-review.ts
+import { EventsClient } from '@acme/events';
+import type { SubmitReview } from './schemas/submit-review';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: SubmitReview = {
+  reviewId: 'a7c4e2d9-1b3f-4c8a-b6e5-9d0f2a1c3e47',
+  productId: 'prod_hoodie_oversized_grey',
+  customerId: 'cust_1057',
+  rating: 2,
+  body: 'Nice fabric but the sleeves are too long for a size M.',
+  submittedAt: '2026-09-15T09:04:33Z',
+};
+
+await client.send('SubmitReview', command);
+```
+
+```python send_submit_review.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "reviewId": "a7c4e2d9-1b3f-4c8a-b6e5-9d0f2a1c3e47",
+    "productId": "prod_hoodie_oversized_grey",
+    "customerId": "cust_1057",
+    "rating": 2,
+    "body": "Nice fabric but the sleeves are too long for a size M.",
+    "submittedAt": "2026-09-15T09:04:33Z",
+}
+
+client.send("SubmitReview", command)
+```
+
+```java SendSubmitReview.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendSubmitReview {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "reviewId", "a7c4e2d9-1b3f-4c8a-b6e5-9d0f2a1c3e47",
+      "productId", "prod_hoodie_oversized_grey",
+      "customerId", "cust_1057",
+      "rating", 2,
+      "body", "Nice fabric but the sleeves are too long for a size M.",
+      "submittedAt", "2026-09-15T09:04:33Z"
+    );
+
+    client.send("SubmitReview", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

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

@@ -0,0 +1,178 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Mark a review as helpful
+
+A shopper finds the five-star review of the classic white T-shirt useful and taps "Helpful". The storefront sends this command to the Review API, which updates the count and publishes `ReviewHelpfulVoted`.
+
+### Payload details
+
+- `reviewId` is the review being voted on.
+- `customerId` is `cust_3314`; each customer can hold one helpful vote per review.
+- `vote` is `helpful`, which adds a vote.
+- `votedAt` is when the customer tapped the button.
+
+### Using this example
+
+Check that the review's helpful count goes up by one and that sending the same vote again does not count twice.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the VoteReviewHelpful schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-vote-review-helpful.ts
+import { EventsClient } from '@acme/events';
+import type { VoteReviewHelpful } from './schemas/vote-review-helpful';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: VoteReviewHelpful = {
+  reviewId: '3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90',
+  customerId: 'cust_3314',
+  vote: 'helpful',
+  votedAt: '2026-09-18T10:02:11Z',
+};
+
+await client.send('VoteReviewHelpful', command);
+```
+
+```python send_vote_review_helpful.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "reviewId": "3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90",
+    "customerId": "cust_3314",
+    "vote": "helpful",
+    "votedAt": "2026-09-18T10:02:11Z",
+}
+
+client.send("VoteReviewHelpful", command)
+```
+
+```java SendVoteReviewHelpful.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendVoteReviewHelpful {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "reviewId", "3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90",
+      "customerId", "cust_3314",
+      "vote", "helpful",
+      "votedAt", "2026-09-18T10:02:11Z"
+    );
+
+    client.send("VoteReviewHelpful", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Remove a helpful vote
+
+The same shopper changes their mind a few seconds later and taps "Helpful" again to undo the vote.
+
+### Payload details
+
+- `reviewId` and `customerId` match the earlier vote.
+- `vote` is `remove`, which takes away the customer's existing vote.
+- `votedAt` is later than the original vote.
+
+### Using this example
+
+Use this payload to test that removing a vote lowers the helpful count by one, and that removing a vote that does not exist leaves the count unchanged.
+
+The examples use a **fictional Acme Events SDK** to send a payload matching the VoteReviewHelpful schema. The package names and send methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript send-vote-review-helpful.ts
+import { EventsClient } from '@acme/events';
+import type { VoteReviewHelpful } from './schemas/vote-review-helpful';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const command: VoteReviewHelpful = {
+  reviewId: '3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90',
+  customerId: 'cust_3314',
+  vote: 'remove',
+  votedAt: '2026-09-18T10:02:47Z',
+};
+
+await client.send('VoteReviewHelpful', command);
+```
+
+```python send_vote_review_helpful.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+command = {
+    "reviewId": "3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90",
+    "customerId": "cust_3314",
+    "vote": "remove",
+    "votedAt": "2026-09-18T10:02:47Z",
+}
+
+client.send("VoteReviewHelpful", command)
+```
+
+```java SendVoteReviewHelpful.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class SendVoteReviewHelpful {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var command = Map.of(
+      "reviewId", "3f2b8c1e-5d4a-4e7b-9a1c-6b2d8e4f7a90",
+      "customerId", "cust_3314",
+      "vote", "remove",
+      "votedAt", "2026-09-18T10:02:47Z"
+    );
+
+    client.send("VoteReviewHelpful", command);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Reviews/services/ReviewAPI/events/review-flagged/examples/index.mdx

@@ -0,0 +1,186 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Publish the first flag on a review
+
+The Review API has recorded a customer's off-topic report against a navy baseball cap review. It publishes this event so the Review Moderation Worker can screen the review again.
+
+### Payload details
+
+- `reviewId` is the flagged review.
+- `productId` is `prod_cap_baseball_navy`, added so consumers do not need to look up the review.
+- `reason` is `off_topic`, copied from the `FlagReview` command.
+- `flagCount` is `1`, meaning this is the first flag the review has received.
+- `flaggedAt` matches the time the flag was raised.
+
+### Using this example
+
+A moderation consumer should queue the review for another screening and decide whether to leave it live or publish `ReviewRejected`.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the ReviewFlagged schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-review-flagged.ts
+import { EventsClient } from '@acme/events';
+import type { ReviewFlagged } from './schemas/review-flagged';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: ReviewFlagged = {
+  reviewId: 'b2d6f8a1-4c3e-4a9b-9f7d-5e1c3a8b0d24',
+  productId: 'prod_cap_baseball_navy',
+  reason: 'off_topic',
+  flagCount: 1,
+  flaggedAt: '2026-09-16T12:40:18Z',
+};
+
+await client.publish('ReviewFlagged', event);
+```
+
+```python publish_review_flagged.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "reviewId": "b2d6f8a1-4c3e-4a9b-9f7d-5e1c3a8b0d24",
+    "productId": "prod_cap_baseball_navy",
+    "reason": "off_topic",
+    "flagCount": 1,
+    "flaggedAt": "2026-09-16T12:40:18Z",
+}
+
+client.publish("ReviewFlagged", event)
+```
+
+```java PublishReviewFlagged.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishReviewFlagged {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "reviewId", "b2d6f8a1-4c3e-4a9b-9f7d-5e1c3a8b0d24",
+      "productId", "prod_cap_baseball_navy",
+      "reason", "off_topic",
+      "flagCount", 1,
+      "flaggedAt", "2026-09-16T12:40:18Z"
+    );
+
+    client.publish("ReviewFlagged", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Publish a repeat abuse flag
+
+A moderator flags a sunset graphic T-shirt review for abuse after two customers have already reported it. The rising `flagCount` tells the moderation worker this review needs urgent attention.
+
+### Payload details
+
+- `productId` is `prod_tshirt_graphic_sunset`.
+- `reason` is `abuse`, the reason on the latest flag.
+- `flagCount` is `3`: the total number of flags on this review, including this one.
+- `flaggedAt` is the time of the latest flag.
+
+### Using this example
+
+Use this payload to test any priority rules, for example that reviews with an `abuse` flag or a high `flagCount` are screened first.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the ReviewFlagged schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-review-flagged.ts
+import { EventsClient } from '@acme/events';
+import type { ReviewFlagged } from './schemas/review-flagged';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: ReviewFlagged = {
+  reviewId: 'd8a3c5e7-2f1b-4e9d-b4a6-7c0e3f5a1b82',
+  productId: 'prod_tshirt_graphic_sunset',
+  reason: 'abuse',
+  flagCount: 3,
+  flaggedAt: '2026-09-17T08:15:00Z',
+};
+
+await client.publish('ReviewFlagged', event);
+```
+
+```python publish_review_flagged.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "reviewId": "d8a3c5e7-2f1b-4e9d-b4a6-7c0e3f5a1b82",
+    "productId": "prod_tshirt_graphic_sunset",
+    "reason": "abuse",
+    "flagCount": 3,
+    "flaggedAt": "2026-09-17T08:15:00Z",
+}
+
+client.publish("ReviewFlagged", event)
+```
+
+```java PublishReviewFlagged.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishReviewFlagged {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "reviewId", "d8a3c5e7-2f1b-4e9d-b4a6-7c0e3f5a1b82",
+      "productId", "prod_tshirt_graphic_sunset",
+      "reason", "abuse",
+      "flagCount", 3,
+      "flaggedAt", "2026-09-17T08:15:00Z"
+    );
+
+    client.publish("ReviewFlagged", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>