@crossdelta/platform-sdk 0.3.38 → 0.3.40

package/README.md

@@ -156,7 +156,7 @@ my-platform/
 
 ## ⚡ Event-Driven Architecture
 
-Every workspace includes **NATS + JetStream** for event-driven microservices communication using **[`@crossdelta/cloudevents`](https://github.com/orderboss/platform/tree/main/packages/cloudevents)**:
+Every workspace includes **NATS + JetStream** for event-driven microservices communication using **[`@crossdelta/cloudevents`](https://www.npmjs.com/package/@crossdelta/cloudevents)**:
 
 - 🎯 **Type-safe event handlers** with Zod schemas
 - 🔄 **Auto-discovery** of event handlers (`*.event.ts` files)

package/bin/templates/workspace/.github/copilot-instructions.md.hbs

@@ -2,7 +2,13 @@
 
 ## Architecture Overview
 
-Bun-based **monorepo** (Turborepo) with event-driven microservices:
+Bun-based **monorepo** (Tu  }).optional(),
+})
+
+// Export type for use in use-cases
+export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
+
+export default handleEvent() with event-driven microservices:
 
 | Directory | Stack | Purpose |
 |-----------|-------|---------|
@@ -86,7 +92,6 @@ import { z } from 'zod'
 import { sendNotification } from '../use-cases/send-notification.use-case'
 
 const OrderCreatedSchema = z.object({
-  type: z.literal('orders.created'),
   orderId: z.string(),
   customerId: z.string(),
   total: z.number(),
@@ -99,12 +104,30 @@ const OrderCreatedSchema = z.object({
   ).optional(),
 })
 
-export default handleEvent(OrderCreatedSchema, async (data) => {
-  await sendNotification(data)
-})
+// Export type for reuse in other services
+export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
+
+export default handleEvent(
+  {
+    schema: OrderCreatedSchema,
+    type: 'orders.created',
+  },
+  async (data) => {
+    await sendNotification(data)
+  },
+)
 ```
 
-**Schema naming:** Use PascalCase for schema constants (e.g., `OrderCreatedSchema`, `UserUpdatedSchema`)
+**Important:**
+- **Schema** validates only the event data payload (without `type` field)
+- **Event type** is declared in the options object, not in the schema
+- Event type matches the first parameter of `publish()` (e.g., `'orders.created'`)
+- Do NOT include `type: z.literal('...')` in the schema - it's redundant and causes validation errors
+- **Always export the inferred type** using `export type EventName = z.infer<typeof EventSchema>` for use in use-cases
+
+**Naming conventions:**
+- Schema constants: PascalCase with `Schema` suffix (e.g., `OrderCreatedSchema`, `UserUpdatedSchema`)
+- Exported types: PascalCase with `Event` suffix (e.g., `OrderCreatedEvent`, `UserUpdatedEvent`)
 
 ### Service Folder Structure
 
@@ -249,12 +272,46 @@ Format source files with path headers. Paths are relative to the service directo
 
 #### `src/handlers/event-name.event.ts`
 ```typescript
-// event handler code
+import { handleEvent } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+import { businessLogic } from '../use-cases/business-logic.use-case'
+
+const EventDataSchema = z.object({
+  id: z.string(),
+  // ... other fields
+})
+
+// Export type for use in use-cases
+export type EventDataType = z.infer<typeof EventDataSchema>
+
+export default handleEvent(
+  {
+    schema: EventDataSchema,
+    type: 'resource.action',  // e.g., 'orders.created', 'users.updated'
+  },
+  async (data) => {
+    await businessLogic(data)
+  },
+)
 ```
 
 #### `src/use-cases/business-logic.use-case.ts`
 ```typescript
-// business logic code
+import type { EventDataType } from '../handlers/event-name.event'
+
+/**
+ * Business logic that processes the event data.
+ * Uses the exported type from the handler for type safety.
+ */
+export async function businessLogic(data: EventDataType): Promise<void> {
+  // Full type inference from the handler schema
+  console.log('Processing:', data.id)
+  
+  // All business logic here
+  // - Validation
+  // - External API calls
+  // - Database operations
+}
 ```
 
 ### Tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.3.38",
+  "version": "0.3.40",
   "description": "CLI toolkit for scaffolding Turborepo workspaces with Pulumi infrastructure and Hono/NestJS microservices",
   "keywords": [
     "cli",