@crossdelta/platform-sdk 0.16.4 → 0.16.6

package/bin/docs/generators/code-style.md

@@ -15,7 +15,7 @@
 ```ts
 // ✅ CORRECT - sorted alphabetically, type imports first
 import type { DomainCreatedData } from '{workspaceScope}/contracts'
-import type { OrdersCreatedData } from '@scope/contracts'
+import type { OrderCreatedData } from '@scope/contracts'
 import { handleEvent } from '@crossdelta/cloudevents'
 import PusherPushNotifications from '@pusher/push-notifications-server'
 
@@ -24,7 +24,7 @@ import PusherPushNotifications from '@pusher/push-notifications-server'
 import type { DomainCreatedData } from '{workspaceScope}/contracts'
 
 // ❌ WRONG - missing 'type' keyword
-import { OrdersCreatedData } from '@scope/contracts'
+import { OrderCreatedData } from '@scope/contracts'
 
 // ❌ WRONG - unused imports
 import { handleEvent, publish } from '@crossdelta/cloudevents'
@@ -51,7 +51,7 @@ const apiKey = process.env.API_KEY!  // no assertions
 |------|------------|---------|
 | Files | kebab-case | `send-notification.use-case.ts` |
 | Contracts | PascalCase | `OrdersCreatedContract` |
-| Types | PascalCase + Data | `OrdersCreatedData` |
+| Types | PascalCase + Data | `OrderCreatedData` |
 
 ---
 

package/bin/docs/generators/hono-bun.md

@@ -83,7 +83,7 @@ consumeJetStreams({
 ```
 
 **CRITICAL:** Stream names MUST be PLURAL:
-- ✅ `streams: ['ORDERS']` - for orders.created event
+- ✅ `streams: ['ORDERS']` - for order.created event
 - ✅ `streams: ['DOMAINS']` - for domain.created event
 - ❌ `streams: ['ORDER']` - WRONG (singular)
 - ❌ `streams: ['DOMAIN']` - WRONG (singular)
@@ -104,7 +104,7 @@ app.get('/health', (c) => c.json({ status: 'ok' }))
 
 app.post('/orders', async (c) => {
   const data = await c.req.json()
-  await publish('orders.created', data)
+  await publish('order.created', data)
   return c.json({ success: true })
 })
 

package/bin/docs/generators/hono-node.md

@@ -86,7 +86,7 @@ consumeJetStreams({
 ```
 
 **CRITICAL:** Stream names MUST be PLURAL:
-- ✅ `streams: ['ORDERS']` - for orders.created event
+- ✅ `streams: ['ORDERS']` - for order.created event
 - ✅ `streams: ['DOMAINS']` - for domain.created event
 - ❌ `streams: ['ORDER']` - WRONG (singular)
 - ❌ `streams: ['DOMAIN']` - WRONG (singular)
@@ -108,7 +108,7 @@ app.get('/health', (c) => c.json({ status: 'ok' }))
 
 app.post('/orders', async (c) => {
   const data = await c.req.json()
-  await publish('orders.created', data)
+  await publish('order.created', data)
   return c.json({ success: true })
 })
 

package/bin/docs/generators/nest.md

@@ -242,12 +242,12 @@ export const getService = <T>(serviceClass: Type<T>): T => {
 
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract, type OrdersCreatedData } from '{workspaceScope}/contracts'
+import { OrdersCreatedContract, type OrderCreatedData } from '{workspaceScope}/contracts'
 import { getService } from '../app.context'
 import { OrdersService } from '../orders/orders.service'
 
-export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
-  console.log(`[orders.created] Processing orderId=${data.orderId}`)
+export default handleEvent(OrdersCreatedContract, async (data: OrderCreatedData) => {
+  console.log(`[order.created] Processing orderId=${data.orderId}`)
   const ordersService = getService(OrdersService)
   await ordersService.processOrder(data)
 })

package/bin/docs/generators/service.md

@@ -55,7 +55,7 @@ const port = Number(process.env.MY_HONO_SERVICE_PORT) || 8080
 ```typescript
 // 1. Contract defines routing
 export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
+  type: 'order.created',
   channel: { stream: 'ORDERS' },
   schema: OrderSchema,
 })
@@ -90,7 +90,7 @@ cd my-platform
 
 #### Option A: AI Generation (via GitHub Copilot Chat)
 ```
-"Create an order processing service that consumes orders.created events"
+"Create an order processing service that consumes order.created events"
 ```
 
 **What AI generates:**
@@ -106,7 +106,7 @@ pf new hono-micro services/order-processing -y
 ```
 
 ```post-commands
-pf event add orders.created --service services/order-processing
+pf event add order.created --service services/order-processing
 ```
 
 **What `pf event add` does:**
@@ -119,10 +119,10 @@ pf event add orders.created --service services/order-processing
 **Step 1: Create contract with CLI**
 ```bash
 # Create contract with schema
-pf event add orders.created --fields "orderId:string,total:number,customerId:string"
+pf event add order.created --fields "orderId:string,total:number,customerId:string"
 
 # Or with JSON schema
-pf event add orders.created --schema '{"orderId":"string","total":"number"}'
+pf event add order.created --schema '{"orderId":"string","total":"number"}'
 ```
 
 **Step 2: Scaffold service**
@@ -132,7 +132,7 @@ pf new hono-micro services/order-processing
 
 **Step 3: Register event and create handler**
 ```bash
-pf event add orders.created --service services/order-processing
+pf event add order.created --service services/order-processing
 ```
 
 **Step 4: Implement use-cases**
@@ -248,8 +248,8 @@ The exact command depends on the framework - see the framework-specific docs:
 **For Event Consumer services, include a `post-commands` block with ALL events:**
 
 ```post-commands
-pf event add orders.created --service services/my-service
-pf event add customers.updated --service services/my-service
+pf event add order.created --service services/my-service
+pf event add customer.updated --service services/my-service
 ```
 
 **What `pf event add` creates:**
@@ -321,7 +321,7 @@ export const OrdersCreatedHandler = handleEvent(...)
 
 ```ts
 export default handleEvent(OrdersCreatedContract, async (data) => {
-  console.log(`[orders.created] Processing orderId=${data.orderId}`)  // ✅ console.log
+  console.log(`[order.created] Processing orderId=${data.orderId}`)  // ✅ console.log
   await processOrder(data)
 })
 ```
@@ -341,18 +341,18 @@ pf new hono-micro services/my-service -y
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-export const OrdersCreatedSchema = z.object({
+export const OrderCreatedSchema = z.object({
   orderId: z.string(),
   total: z.number(),
 })
 
+export type OrderCreatedData = z.infer<typeof OrderCreatedSchema>
+
 export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
+  type: 'order.created',
   channel: { stream: 'ORDERS' },
-  schema: OrdersCreatedSchema,
+  schema: OrderCreatedSchema,
 })
-
-export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 ```
 
 #### `packages/contracts/src/index.ts`
@@ -364,10 +364,10 @@ export * from './events/orders/created'
 #### `src/events/orders-created.handler.ts`
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract, type OrdersCreatedData } from '{workspaceScope}/contracts'
+import { OrdersCreatedContract, type OrderCreatedData } from '{workspaceScope}/contracts'
 import { processOrder } from '../use-cases/process-order.use-case'
 
-export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
+export default handleEvent(OrdersCreatedContract, async (data: OrderCreatedData) => {
   console.log('📦 Processing order:', data.orderId)
   await processOrder(data)
 })
@@ -375,15 +375,15 @@ export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData
 
 #### `src/use-cases/process-order.use-case.ts`
 ```ts
-import type { OrdersCreatedData } from '{workspaceScope}/contracts'
+import type { OrderCreatedData } from '{workspaceScope}/contracts'
 
-export const processOrder = async (data: OrdersCreatedData): Promise<void> => {
+export const processOrder = async (data: OrderCreatedData): Promise<void> => {
   console.log('Processing:', data.orderId)
 }
 ```
 
 ```post-commands
-pf event add orders.created --service services/my-service
+pf event add order.created --service services/my-service
 ```
 
 ```dependencies
@@ -418,14 +418,24 @@ await notifyUser(data.userId)         // ❌ WRONG - userId not in schema!
 ## Contract Schema (Zod 4 Syntax)
 
 ```ts
-export const OrdersCreatedSchema = z.object({
+export const OrderCreatedSchema = z.object({
   orderId: z.string(),
   email: z.string().email(),        // ✅ Zod 4: no params
   total: z.number(),
   createdAt: z.string().datetime(), // ✅ Zod 4: no params
 })
+
+export type OrderCreatedData = z.infer<typeof OrderCreatedSchema>
+
+export const OrdersCreatedContract = createContract({
+  type: 'order.created',
+  channel: { stream: 'ORDERS' },
+  schema: OrderCreatedSchema,  // ← Singular schema
+})
 ```
 
+**Pattern:** Schema is singular (describes one object), Contract is plural (represents stream)
+
 **Zod 4 Quick Reference:**
 - ✅ `z.string().email()` - no params
 - ✅ `z.string().url()` - no params
@@ -439,14 +449,23 @@ export const OrdersCreatedSchema = z.object({
 
 | Component | Format | Example | Reason |
 |-----------|--------|---------|--------|
-| **Event Type** | **Singular** | `customer.created` | Describes a single event |
-| **Event Folder** | **PLURAL** | `customers/` | Domain grouping (matches stream) |
-| **Stream** | **PLURAL** | `CUSTOMERS` | Collection of events for a domain |
-| **Mock Files** | **PLURAL folder** | `customers/created.mock.json` | Must match event folder |
+| **Event Type** | **Singular** | `customer.created` | A single fact |
+| **Schema** | **Singular** | `CustomerCreatedSchema` | One event object |
+| **Type** | **Singular** | `CustomerCreatedData` | One event object |
+| **Contract** | **PLURAL** | `CustomersCreatedContract` | Category of events |
+| **Event Folder** | **PLURAL** | `customers/` | Domain (collection) |
+| **Stream** | **PLURAL** | `CUSTOMERS` | Collection of events |
+| **Mock Files** | **PLURAL folder** | `customers/created.mock.json` | Matches event folder |
+
+**The final rule:**
+```
+Schema / Data        → singular (one event instance)
+Event Type           → singular (one fact)
+Contract             → plural (category of events)
+Stream / Domain      → plural (collection)
+```
 
-**Merksatz:**
-- **Singular** describes an event
-- **Plural** describes a domain
+**Key principle:** Contracts represent event collections, Schemas represent event instances.
 
 ### File Structure Example
 
@@ -468,20 +487,25 @@ packages/contracts/src/events/
 
 ### Contract Examples
 
-| Event Type | Contract | Folder | Stream |
-|------------|----------|--------|--------|
-| `customer.created` | `CustomersCreatedContract` | `customers/` | `CUSTOMERS` ✅ |
-| `order.created` | `OrdersCreatedContract` | `orders/` | `ORDERS` ✅ |
-| `domain.created` | `DomainsCreatedContract` | `domains/` | `DOMAINS` ✅ |
+| 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` |
 
-**Naming Pattern:** `{PluralDomain}{Action}Contract` - matches folder and stream names
+**Naming Patterns:**
+- Schema/Type: `{SingularDomain}{Action}Schema/Data` - describes one object
+- Contract: `{PluralDomain}{Action}Contract` - matches folder and stream names
 
 ```typescript
 // ✅ CORRECT
+export const CustomerCreatedSchema = z.object({ ... })
+export type CustomerCreatedData = z.infer<typeof CustomerCreatedSchema>
+
 export const CustomersCreatedContract = createContract({
   type: 'customer.created',         // Singular event type
   channel: { stream: 'CUSTOMERS' }, // Plural stream (matches contract name prefix)
-  schema: CustomersCreatedSchema,
+  schema: CustomerCreatedSchema,    // Singular schema
 })
 
 // Folder: packages/contracts/src/events/customers/created.ts    ✅ PLURAL
@@ -498,7 +522,7 @@ export const CustomerCreatedContract = createContract({
 export const CustomersCreatedContract = createContract({
   type: 'customer.created',
   channel: { stream: 'CUSTOMER' },  // ❌ Wrong! Should be CUSTOMERS (plural)
-  schema: CustomersCreatedSchema,
+  schema: CustomerCreatedSchema,
 })
 ```
 
@@ -514,7 +538,7 @@ consumeJetStreams({
   discover: './src/events/**/*.handler.ts',
 })
 
-// ✅ CORRECT - orders.created event → ORDERS stream
+// ✅ CORRECT - order.created event → ORDERS stream
 consumeJetStreams({
   streams: ['ORDERS'],  // ✅ Plural!
   consumer: 'my-service',

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

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

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

@@ -12,7 +12,7 @@ This package contains **shared event definitions** (contracts) for events that a
 src/
 ├── events/                    # Event contracts grouped by domain
 │   ├── orders/               # Orders domain
-│   │   ├── created.ts        # orders.created event
+│   │   ├── created.ts        # order.created event
 │   │   ├── updated.ts        # orders.updated event
 │   │   └── index.ts          # Re-exports
 │   ├── customers/            # Customers domain
@@ -35,7 +35,7 @@ src/
 ### Using the CLI (Recommended)
 
 ```bash
-pf event add products.created --fields "productId:string,name:string,price:number"
+pf event add product.created --fields "productId:string,name:string,price:number"
 ```
 
 This will create `src/events/products/created.ts` with proper domain structure.
@@ -50,9 +50,9 @@ See [Adding Events](#manual-creation) section below.
 
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+import { OrdersCreatedContract, type OrderCreatedData } from '{{scope}}/contracts'
 
-export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
+export default handleEvent(OrdersCreatedContract, async (data: OrderCreatedData) => {
   // data is fully typed from contract
   console.log(data.orderId, data.customerId)
 })
@@ -76,9 +76,9 @@ await publish(OrdersCreatedContract, {
 ### In Use-Cases
 
 ```ts
-import type { OrdersCreatedData } from '{{scope}}/contracts'
+import type { OrderCreatedData } from '{{scope}}/contracts'
 
-export const processOrder = async (data: OrdersCreatedData) => {
+export const processOrder = async (data: OrderCreatedData) => {
   // Use typed event data
 }
 ```
@@ -89,10 +89,10 @@ Contracts are **auto-generated** when you create event handlers:
 
 ```bash
 # 1. Create service with event handler
-pf new hono-micro notifications --ai -d "Sends emails on orders.created events"
+pf new hono-micro notifications --ai -d "Sends emails on order.created events"
 
 # 2. Add event (creates contract, mock, handler)
-pf event add orders.created --service services/notifications
+pf event add order.created --service services/notifications
 ```
 
 This creates:
@@ -107,7 +107,7 @@ This creates:
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-export const OrdersCreatedSchema = z.object({
+export const OrderCreatedSchema = z.object({
   orderId: z.string(),
   customerId: z.string(),
   total: z.number(),
@@ -119,17 +119,17 @@ export const OrdersCreatedSchema = z.object({
 })
 
 export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
+  type: 'order.created',
   channel: { stream: 'ORDERS' },  // Stream routing metadata
-  schema: OrdersCreatedSchema,
+  schema: OrderCreatedSchema,
 })
 
-export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
+export type OrderCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 ```
 
 **Channel Metadata:**
 - `stream` - NATS JetStream stream name (e.g., `ORDERS`)
-- `subject` - Optional, defaults to event type (e.g., `orders.created`)
+- `subject` - Optional, defaults to event type (e.g., `order.created`)
 
 **Stream Materialization:**
 1. **Development**: `pf dev` scans contracts and auto-creates ephemeral streams from channel metadata
@@ -144,10 +144,10 @@ See [`infra/streams/README.md`](../../infra/streams/README.md) for details.
 pf event list
 
 # Publish mock event
-pf event publish orders.created
+pf event publish order.created
 
 # Publish with custom data
-pf event publish orders.created --data '{"orderId":"test-123"}'
+pf event publish order.created --data '{"orderId":"test-123"}'
 ```
 
 ## Guidelines
@@ -161,6 +161,6 @@ pf event publish orders.created --data '{"orderId":"test-123"}'
 
 **Naming conventions:**
 - Contracts: `OrdersCreatedContract` (plural namespace)
-- Types: `OrdersCreatedData`
+- Types: `OrderCreatedData`
 - Files: `orders-created.ts`
-- Event types: `orders.created` (plural namespace, dot notation)
+- Event types: `order.created` (plural namespace, dot notation)

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.16.4",
+  "version": "0.16.6",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",
@@ -93,29 +93,6 @@
   "test:watch": "bun test --watch"
 },
 "schematics": "./dist/schematics/collection.json",
-"esbuild": {
-  "external": [
-    "@crossdelta/infrastructure",
-    "@faker-js/faker",
-    "@inquirer/prompts",
-    "ai",
-    "@ai-sdk/openai",
-    "@ai-sdk/anthropic",
-    "handlebars",
-    "listr2",
-    "enquirer",
-    "execa",
-    "globby",
-    "fs-extra",
-    "chalk",
-    "ora",
-    "jiti",
-    "zod",
-    "ts-morph",
-    "commander",
-    "chokidar"
-  ]
-},
 "dependencies": {
   "@ai-sdk/anthropic": "^2.0.53",
   "@ai-sdk/openai": "^2.0.79",