@crossdelta/platform-sdk 0.17.0 → 0.17.2

package/README.md

@@ -411,7 +411,7 @@ export const OrdersCreatedContract = createContract({
 **Handlers** import contracts and delegate to use cases:
 
 ```typescript
-// services/notifications/src/events/orders-created.handler.ts
+// services/notifications/src/events/order-created.handler.ts
 import { handleEvent } from '@crossdelta/cloudevents'
 import { OrdersCreatedContract } from '@my-platform/contracts'
 import { sendOrderNotification } from '../use-cases/send-notification.use-case'

package/bin/docs/generators/nest.md

@@ -236,7 +236,7 @@ export const getService = <T>(serviceClass: Type<T>): T => {
 
 ---
 
-## Event Handler (src/events/orders-created.handler.ts)
+## Event Handler (src/events/order-created.handler.ts)
 
 **Handlers must be thin** - just log and delegate to a service:
 

package/bin/docs/generators/service.md

@@ -96,7 +96,7 @@ cd my-platform
 **What AI generates:**
 1. **Contract** (`packages/contracts/src/events/orders/created.ts`) - With proper Zod schema in domain-grouped structure
 2. **Service** (`services/order-processing/`) - Scaffolded via `pf new hono-micro`
-3. **Event Handler** (`services/order-processing/src/events/orders-created.handler.ts`)
+3. **Event Handler** (`services/order-processing/src/events/order-created.handler.ts`)
 4. **Use-Cases** (`services/order-processing/src/use-cases/`)
 5. **Tests** (`services/order-processing/src/use-cases/*.test.ts`)
 
@@ -110,7 +110,7 @@ pf event add order.created --service services/order-processing
 ```
 
 **What `pf event add` does:**
-- Creates `packages/contracts/src/events/orders-created.mock.json` (test mock)
+- Creates `packages/contracts/src/events/orders/created.mock.json` (test mock)
 - Adds export to `packages/contracts/src/index.ts`
 - Skips contract creation if already exists (AI's schema is preserved!)
 
@@ -133,6 +133,7 @@ pf new hono-micro services/order-processing
 **Step 3: Register event and create handler**
 ```bash
 pf event add order.created --service services/order-processing
+# Creates: src/events/order-created.handler.ts (singular!)
 ```
 
 **Step 4: Implement use-cases**
@@ -151,7 +152,7 @@ mkdir -p packages/contracts/src/events/orders
 pf new hono-micro services/order-processing
 
 # 3. Create handler manually
-# Edit services/order-processing/src/events/orders-created.handler.ts
+# Edit services/order-processing/src/events/order-created.handler.ts
 
 # 4. Implement use-cases
 # Edit services/order-processing/src/use-cases/
@@ -298,8 +299,8 @@ Export named 'OrderCreatedContract' not found in module 'packages/contracts/src/
 ```
 ✅ CORRECT:
 services/my-service/src/events/
-├── orders-created.handler.ts
-└── customers-updated.handler.ts
+├── order-created.handler.ts
+└── customer-updated.handler.ts
 
 ❌ WRONG:
 services/my-service/src/events/handlers/  # NEVER create!
@@ -361,7 +362,7 @@ export const OrdersCreatedContract = createContract({
 export * from './events/orders/created'
 ```
 
-#### `src/events/orders-created.handler.ts`
+#### `src/events/order-created.handler.ts`
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
 import { OrdersCreatedContract, type OrderCreatedData } from '{workspaceScope}/contracts'
@@ -452,6 +453,7 @@ export const OrdersCreatedContract = createContract({
 | **Event Type** | **Singular** | `customer.created` | A single fact |
 | **Schema** | **Singular** | `CustomerCreatedSchema` | One event object |
 | **Type** | **Singular** | `CustomerCreatedData` | One event object |
+| **Handler File** | **SINGULAR** | `customer-created.handler.ts` | Matches event type in kebab-case |
 | **Contract** | **PLURAL** | `CustomersCreatedContract` | Category of events |
 | **Event Folder** | **PLURAL** | `customers/` | Domain (collection) |
 | **Stream** | **PLURAL** | `CUSTOMERS` | Collection of events |
@@ -459,13 +461,13 @@ export const OrdersCreatedContract = createContract({
 
 **The final rule:**
 ```
+Event Type / Handler → singular (customer.created → customer-created.handler.ts)
 Schema / Data        → singular (one event instance)
-Event Type           → singular (one fact)
 Contract             → plural (category of events)
 Stream / Domain      → plural (collection)
 ```
 
-**Key principle:** Contracts represent event collections, Schemas represent event instances.
+**Key principle:** Event handlers match event types (both singular). Contracts represent event collections (plural).
 
 ### File Structure Example
 
@@ -487,14 +489,15 @@ packages/contracts/src/events/
 
 ### Contract Examples
 
-| Event Type | Schema | Type | Contract | Folder | Stream |
-|------------|--------|------|----------|--------|--------|
-| `customer.created` | `CustomerCreatedSchema` | `CustomerCreatedData` | `CustomersCreatedContract` | `customers/` | `CUSTOMERS` |
-| `order.created` | `OrderCreatedSchema` | `OrderCreatedData` | `OrdersCreatedContract` | `orders/` | `ORDERS` |
-| `domain.created` | `DomainCreatedSchema` | `DomainCreatedData` | `DomainsCreatedContract` | `domains/` | `DOMAINS` |
+| Event Type | Schema | Type | Handler | Contract | Folder | Stream |
+|------------|--------|------|---------|----------|--------|--------|
+| `customer.created` | `CustomerCreatedSchema` | `CustomerCreatedData` | `customer-created.handler.ts` | `CustomersCreatedContract` | `customers/` | `CUSTOMERS` |
+| `order.created` | `OrderCreatedSchema` | `OrderCreatedData` | `order-created.handler.ts` | `OrdersCreatedContract` | `orders/` | `ORDERS` |
+| `domain.created` | `DomainCreatedSchema` | `DomainCreatedData` | `domain-created.handler.ts` | `DomainsCreatedContract` | `domains/` | `DOMAINS` |
 
 **Naming Patterns:**
 - Schema/Type: `{SingularDomain}{Action}Schema/Data` - describes one object
+- Handler: `{singular-domain}-{action}.handler.ts` - matches event type in kebab-case
 - Contract: `{PluralDomain}{Action}Contract` - matches folder and stream names
 
 ```typescript
@@ -601,13 +604,14 @@ Combines REST endpoints + NATS consumer.
 ```
 services/my-service/src/
 ├── index.ts
-├── events/orders-created.handler.ts
+├── events/order-created.handler.ts
 └── use-cases/
     ├── process-order.use-case.ts
     └── process-order.test.ts
 
 packages/contracts/src/events/
-└── orders-created.ts
+└── orders/
+    └── created.ts
 ```
 
 **Note:** For NestJS structure, see `nest.md` - NestJS uses Services instead of use-cases.

package/bin/templates/workspace/infra/package.json.hbs

@@ -7,7 +7,7 @@
     "pulumi": "pulumi"
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.6.0",
+    "@crossdelta/cloudevents": "^0.6.1",
     "@crossdelta/infrastructure": "^0.5.3",
     "{{scope}}/contracts": "workspace:*",
     "@pulumi/digitalocean": "^4.55.0",

package/bin/templates/workspace/packages/contracts/README.md.hbs

@@ -96,8 +96,8 @@ pf event add order.created --service services/notifications
 ```
 
 This creates:
-- `packages/contracts/src/events/orders-created.ts` (contract)
-- `packages/contracts/src/events/orders-created.mock.json` (mock)
+- `packages/contracts/src/events/orders/created.ts` (contract)
+- `packages/contracts/src/events/orders/created.mock.json` (mock)
 - Updates `packages/contracts/src/index.ts` (exports)
 
 ### Manual Contract Creation
@@ -161,6 +161,6 @@ pf event publish order.created --data '{"orderId":"test-123"}'
 
 **Naming conventions:**
 - Contracts: `OrdersCreatedContract` (plural namespace)
-- Types: `OrderCreatedData`
-- Files: `orders-created.ts`
-- Event types: `order.created` (plural namespace, dot notation)
+- Types: `OrderCreatedData` (singular)
+- Files: `orders/created.ts` (plural folder, event name)
+- Event types: `order.created` (singular namespace, dot notation)

package/bin/templates/workspace/packages/contracts/package.json.hbs

@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.6.0",
+    "@crossdelta/cloudevents": "^0.6.1",
     "@crossdelta/infrastructure": "^0.5.3",
     "zod": "^4.0.0"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",