@crossdelta/platform-sdk 0.11.2 → 0.12.0

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

@@ -77,6 +77,56 @@ console.log(`Service running on http://localhost:${port}`)
 
 ---
 
+## Environment Validation (Optional)
+
+For services with required env vars, validate at startup with Zod:
+
+```ts
+// src/config/env.ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  PORT: z.string().transform(Number).default('8080'),
+  PUSHER_INSTANCE_ID: z.string().min(1),
+  PUSHER_SECRET_KEY: z.string().min(1),
+  NATS_URL: z.string().url().default('nats://localhost:4222'),
+})
+
+export type Env = z.infer<typeof envSchema>
+
+// Validate at module load - crashes immediately if invalid
+export const env = envSchema.parse(process.env)
+```
+
+```ts
+// src/index.ts
+import '@crossdelta/telemetry'
+import { Hono } from 'hono'
+import { env } from './config/env'
+
+const app = new Hono()
+
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+app.post('/notify', async (c) => {
+  const data = await c.req.json()
+  // Use validated env
+  await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
+  return c.json({ success: true })
+})
+
+Bun.serve({ port: env.PORT, fetch: app.fetch })
+console.log(`Service running on http://localhost:${env.PORT}`)
+```
+
+**Benefits:**
+- ✅ Fail-fast at startup (not at runtime)
+- ✅ Type-safe env access (`env.PORT` is `number`)
+- ✅ Clear error messages for missing vars
+- ✅ Defaults for optional vars
+
+---
+
 ## Rules
 
 - ✅ `Bun.serve({ port, fetch: app.fetch })`

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

@@ -83,6 +83,58 @@ serve({ fetch: app.fetch, port }, (info) => {
 
 ---
 
+## Environment Validation (Optional)
+
+For services with required env vars, validate at startup with Zod:
+
+```ts
+// src/config/env.ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  PORT: z.string().transform(Number).default('8080'),
+  PUSHER_INSTANCE_ID: z.string().min(1),
+  PUSHER_SECRET_KEY: z.string().min(1),
+  NATS_URL: z.string().url().default('nats://localhost:4222'),
+})
+
+export type Env = z.infer<typeof envSchema>
+
+// Validate at module load - crashes immediately if invalid
+export const env = envSchema.parse(process.env)
+```
+
+```ts
+// src/index.ts
+import '@crossdelta/telemetry'
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import { env } from './config/env'
+
+const app = new Hono()
+
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+app.post('/notify', async (c) => {
+  const data = await c.req.json()
+  // Use validated env
+  await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
+  return c.json({ success: true })
+})
+
+serve({ fetch: app.fetch, port: env.PORT }, (info) => {
+  console.log(`Server running on http://localhost:${info.port}`)
+})
+```
+
+**Benefits:**
+- ✅ Fail-fast at startup (not at runtime)
+- ✅ Type-safe env access (`env.PORT` is `number`)
+- ✅ Clear error messages for missing vars
+- ✅ Defaults for optional vars
+
+---
+
 ## Rules
 
 - ✅ `serve()` from `@hono/node-server`

package/bin/docs/generators/nest.md

@@ -22,9 +22,13 @@
 import { z } from 'zod'
 
 export const envSchema = z.object({
+  PORT: z.string().transform(Number).default('8080'),
   PUSHER_INSTANCE_ID: z.string().min(1),
   PUSHER_SECRET_KEY: z.string().min(1),
+  NATS_URL: z.string().url().default('nats://localhost:4222'),
 })
+
+export type Env = z.infer<typeof envSchema>
 ```
 
 ```ts
@@ -48,17 +52,26 @@ export class AppModule {}
 // ✅ Service uses ConfigService - already validated at startup
 import { Injectable } from '@nestjs/common'
 import { ConfigService } from '@nestjs/config'
+import type { Env } from './config/env.schema'
 
 @Injectable()
 export class MyService {
-  constructor(private config: ConfigService) {}
+  constructor(private config: ConfigService<Env, true>) {}
 
   doSomething() {
-    const instanceId = this.config.getOrThrow<string>('PUSHER_INSTANCE_ID')
+    const instanceId = this.config.get('PUSHER_INSTANCE_ID') // Type-safe!
+    const port = this.config.get('PORT') // number (auto-transformed)
   }
 }
 ```
 
+**Benefits:**
+- ✅ Fail-fast at startup (not at runtime)
+- ✅ Type-safe config access with `ConfigService<Env, true>`
+- ✅ Clear error messages for missing vars
+- ✅ Defaults for optional vars
+- ✅ Auto-transform strings to numbers/booleans
+
 ---
 
 ## 🚨 CRITICAL: NestJS Structure (NO use-cases folder!)

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

@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.1",
+    "@crossdelta/cloudevents": "^0.5.2",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/package.json

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