@crossdelta/platform-sdk 0.13.0 → 0.13.2

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

@@ -1,166 +0,0 @@
-# {{scope}}/contracts
-
-Shared event contracts for cross-service event consumption.
-
-## Purpose
-
-This package contains **shared event definitions** (contracts) for events that are consumed by multiple services. When an event is used by more than one service, define it here to ensure type consistency across the platform.
-
-## Structure
-
-```
-src/
-├── events/                    # Event contracts grouped by domain
-│   ├── orders/               # Orders domain
-│   │   ├── created.ts        # orders.created event
-│   │   ├── updated.ts        # orders.updated event
-│   │   └── index.ts          # Re-exports
-│   ├── customers/            # Customers domain
-│   │   ├── updated.ts        # customers.updated event
-│   │   └── index.ts          # Re-exports
-│   └── index.ts              # Re-exports all domains
-├── stream-policies.ts        # NATS JetStream retention policies
-└── index.ts                  # Main export file
-```
-
-**Contract files contain:**
-- Zod schema definition
-- Contract object (type + schema + **channel metadata**)
-- TypeScript type inference
-
-**Channel metadata** defines which NATS JetStream stream the event belongs to. This enables infrastructure-as-code workflows where streams are auto-created in dev (`pf dev`) and materialized via Pulumi in production.
-
-## Adding New Events
-
-### Using the CLI (Recommended)
-
-```bash
-pf event add products.created --fields "productId:string,name:string,price:number"
-```
-
-This will create `src/events/products/created.ts` with proper domain structure.
-
-### Manual Creation
-
-See [Adding Events](#manual-creation) section below.
-
-## Usage
-
-### In Event Handlers (Consumers)
-
-```ts
-import { handleEvent } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
-
-export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
-  // data is fully typed from contract
-  console.log(data.orderId, data.customerId)
-})
-```
-
-### In Publishers (REST APIs)
-
-```ts
-import { publish } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract } from '{{scope}}/contracts'
-
-// Type-safe publishing with contract
-await publish(OrdersCreatedContract, {
-  orderId: 'order-123',
-  customerId: 'cust-456',
-  total: 99.99,
-  items: [...]
-})
-```
-
-### In Use-Cases
-
-```ts
-import type { OrdersCreatedData } from '{{scope}}/contracts'
-
-export const processOrder = async (data: OrdersCreatedData) => {
-  // Use typed event data
-}
-```
-
-## Adding New Contracts
-
-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"
-
-# 2. Add event (creates contract, mock, handler)
-pf event add orders.created --service services/notifications
-```
-
-This creates:
-- `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
-
-```ts
-// packages/contracts/src/events/orders/created.ts
-import { createContract } from '@crossdelta/cloudevents'
-import { z } from 'zod'
-
-export const OrdersCreatedSchema = z.object({
-  orderId: z.string(),
-  customerId: z.string(),
-  total: z.number(),
-  items: z.array(z.object({
-    productId: z.string(),
-    quantity: z.number(),
-    price: z.number(),
-  })),
-})
-
-export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
-  channel: { stream: 'ORDERS' },  // Stream routing metadata
-  schema: OrdersCreatedSchema,
-})
-
-export type OrdersCreatedData = 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`)
-
-**Stream Materialization:**
-1. **Development**: `pf dev` scans contracts and auto-creates ephemeral streams from channel metadata
-2. **Production**: Pulumi collects streams from contracts and materializes with retention policies
-
-See [`infra/streams/README.md`](../../infra/streams/README.md) for details.
-
-## Testing with Mocks
-
-```bash
-# List all available events
-pf event list
-
-# Publish mock event
-pf event publish orders.created
-
-# Publish with custom data
-pf event publish orders.created --data '{"orderId":"test-123"}'
-```
-
-## Guidelines
-
-- ✅ Use contracts for **shared events** (multi-consumer)
-- ✅ Export both contract and inferred type
-- ✅ Keep contracts minimal and focused
-- ✅ Generate mocks for all contracts
-- ❌ Don't put business logic in contracts
-- ❌ Don't include event handlers in this package
-
-**Naming conventions:**
-- Contracts: `OrdersCreatedContract` (plural namespace)
-- Types: `OrdersCreatedData`
-- Files: `orders-created.ts`
-- Event types: `orders.created` (plural namespace, dot notation)

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

@@ -1,22 +0,0 @@
-{
-  "name": "{{scope}}/contracts",
-  "private": true,
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    }
-  },
-  "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.3",
-    "@crossdelta/infrastructure": "^0.5.0",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "typescript": "^5.7.2"
-  }
-}

package/bin/templates/workspace/packages/contracts/src/events/index.ts

@@ -1,16 +0,0 @@
-/**
- * Event Contracts Index
- *
- * Re-exports all event contracts for convenient importing.
- * Services can import from '{{scope}}/contracts' instead of deep imports.
- *
- * Structure:
- * - events/<domain>/<event>.ts - Individual event contracts
- * - events/<domain>/index.ts - Domain-specific exports
- * - This file: Re-exports all domains
- */
-
-// Add your event domains here as you create them:
-// export * from './orders'
-// export * from './customers'
-// export * from './products'

package/bin/templates/workspace/packages/contracts/src/index.ts

@@ -1,10 +0,0 @@
-// Export your event contracts and schemas here
-// Use the CLI to generate contracts:
-//
-//   pf event add orders.created --fields "orderId:string,total:number"
-//
-// This will create: src/events/orders/created.ts
-// Then uncomment the exports below:
-
-// export * from './events'
-// export * from './stream-policies'

package/bin/templates/workspace/packages/contracts/src/stream-policies.ts.hbs

@@ -1,40 +0,0 @@
-/**
- * {{workspaceName}} Stream Policies
- *
- * Business rules for NATS JetStream stream configuration.
- * Defines retention, replication, and storage policies per stream.
- *
- * Architecture:
- * - This file: Business rules (data)
- * - @crossdelta/infrastructure: Deployment logic
- * - infra/streams: Connects business rules + deployment logic
- */
-
-import type { StreamPolicy } from '@crossdelta/infrastructure'
-
-// Time constants for readability
-const DAYS = 24 * 60 * 60 * 1000
-const MB = 1024 * 1024
-
-/**
- * Stream-specific policies
- * Add entries here as you create new streams via event contracts
- */
-export const STREAM_POLICIES: Record<string, Partial<StreamPolicy>> = {
-  // Example:
-  // ORDERS: {
-  //   maxAge: 14 * DAYS,
-  //   replicas: 3,
-  // },
-}
-
-/**
- * Default stream policy
- * Applied to all streams without specific overrides
- */
-export const DEFAULT_POLICY: Partial<StreamPolicy> = {
-  maxAge: 7 * DAYS, // 7 days default retention
-  storage: 'file', // Persistent storage
-  replicas: 1, // Single replica for non-critical streams
-  maxMsgSize: 1 * MB, // 1MB max message size
-}

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

@@ -1,7 +0,0 @@
-{
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"]
-}

package/bin/templates/workspace/pnpm-workspace.yaml.hbs

@@ -1,5 +0,0 @@
-packages:
-  - 'packages/*'
-  - 'apps/*'
-  - 'services/*'
-  - 'infra'

package/bin/templates/workspace/turbo.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://turborepo.org/schema.json",
-  "tasks": {
-    "start:dev": {
-      "cache": false,
-      "persistent": true
-    },
-    "sync-templates": {
-      "cache": false
-    },
-    "sync-templates:check": {
-      "cache": false
-    },
-    "pulumi": {},
-    "build": {
-      "cache": false
-    },
-    "test": {
-      "cache": false
-    },
-    "format": {
-      "cache": false
-    },
-    "lint": {
-      "cache": false
-    },
-    "preview": {
-      "cache": false,
-      "persistent": true
-    }
-  },
-  "ui": "tui",
-  "concurrency": "50",
-  "globalPassThroughEnv": [
-    "*"
-  ]
-}

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

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://turborepo.org/schema.json",
-  "tasks": {
-    "start:dev": {
-      "cache": false,
-      "persistent": true
-    },
-    "pulumi": {},
-    "build": {
-      "cache": false
-    },
-    "test": {
-      "cache": false
-    },
-    "format": {
-      "cache": false
-    },
-    "lint": {
-      "cache": false
-    },
-    "preview": {
-      "cache": false,
-      "persistent": true
-    }
-  },
-  "ui": "tui",
-  "concurrency": "50",
-  "globalPassThroughEnv": ["*"]
-}