@nebulit/embuilder 0.1.39

package/templates/.claude/skills/slice-state-change/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: slice-state-change
+description: builds a state-change slice from an event model
+---
+
+## Overview
+
+State Change Slices are slices that change the system by processing a command. Each slice implements the Command-Event pattern using event sourcing.
+
+## Critical Requirements
+
+### Restaurant ID Requirement
+- **CRITICAL**: ALL events MUST have `restaurantId` in their metadata (camelCase)
+- **NEVER** use `locationId` or `location_id` - these are outdated and forbidden
+- **CRITICAL**: ALL database tables MUST have a `restaurant_id` column (snake_case)
+- This ensures proper multi-tenancy and data isolation
+
+## Implementation Steps
+
+When creating a state-change slice, you MUST create the following files in `src/slices/{SliceName}/`:
+
+1. **{SliceName}Command.ts** - Command handler implementation
+2. **{SliceName}.test.ts** - Test specifications
+3. **routes.ts** - API endpoint (unless explicitly told not to)
+4. **src/slices/{SliceName}/ui-prompt.md - prompt to build the UI
+
+
+## Command Handler Structure
+
+Every Command handler file follows this pattern:
+
+### 1. Imports
+```typescript
+import type {Command} from '@event-driven-io/emmett'
+import {CommandHandler} from '@event-driven-io/emmett';
+import {ContextEvents} from "../../events/ContextEvents";
+import {findEventstore} from "../../common/loadPostgresEventstore";
+```
+
+### 2. Command Type Definition
+Define the command with:
+- Command name (matches slice name)
+- Data fields from specification
+- Standard metadata fields
+
+```typescript
+export type {CommandName}Command = Command<'{CommandName}', {
+    // data fields from spec
+},
+    {
+        correlation_id?: string,
+        causation_id?: string,
+        now?: Date,
+        streamName?: string,
+    }>;
+```
+
+### 3. State Type
+Define state needed for business logic validation:
+```typescript
+export type {CommandName}State = {
+    // fields needed for validation
+    // often empty {} if no validation needed
+}
+
+export const {CommandName}InitialState = (): {CommandName}State => ({
+    // initial state
+});
+```
+
+### 4. Evolve Function
+Updates state based on events (event sourcing projection):
+```typescript
+export const evolve = (
+    state: {CommandName}State,
+    event: ContextEvents,
+): {CommandName}State => {
+    const {type, data} = event;
+
+    switch (type) {
+        case "{EventName}":
+            // update state based on event
+            return { ...state, /* updates */ };
+        default:
+            return state;
+    }
+};
+```
+
+### 5. Decide Function
+Business logic that validates command and returns events:
+```typescript
+export const decide = (
+    command: {CommandName}Command,
+    state: {CommandName}State,
+): ContextEvents[] => {
+    // validation logic
+    // throw errors if validation fails
+
+    return [{
+        type: '{EventName}',
+        data: {
+            // event data fields
+        },
+        metadata: {
+            correlation_id: command.metadata?.correlation_id,
+            causation_id: command.metadata?.causation_id,
+            // these 2 are mandatory
+            restaurantId: command.metadata?.restaurantId,
+            userId: command.metadata?.userId
+        }
+    }];
+};
+```
+
+### 6. Command Handler & Export
+```typescript
+const {CommandName}CommandHandler = CommandHandler<{CommandName}State, ContextEvents>({
+    evolve,
+    initialState: {CommandName}InitialState
+});
+
+export const handle{CommandName} = async (id: string, command: {CommandName}Command) => {
+    const eventStore = await findEventstore()
+    const result = await {CommandName}CommandHandler(eventStore, id, (state: {CommandName}State) => decide(command, state))
+    return {
+        nextExpectedStreamVersion: result.nextExpectedStreamVersion,
+        lastEventGlobalPosition: result.lastEventGlobalPosition
+    }
+}
+```
+
+## Key Patterns
+
+### Metadata Handling
+- **Optional chaining**: Use `command.metadata?.correlation_id` (some examples use this)
+- **Direct access**: Use `command.metadata.correlation_id` (other examples use this)
+- **CRITICAL**: ALWAYS use `restaurantId` (camelCase) - NEVER use `locationId` or `location_id` (outdated)
+- restaurantId: command.metadata?.restaurantId,
+- userId: command.metadata?.userId
+- Be consistent within your implementation
+
+### Destructuring
+Two patterns observed:
+1. Direct access: `command.data.fieldName`
+2. Destructure: `const {field1, field2} = command.data;`
+
+Both are acceptable - choose based on readability.
+
+### State Validation
+- Only include fields in state that are needed for validation
+- Many simple commands have empty state `{}`
+- Complex validations (like AddLocation) track sets or maps in state
+
+## Testing
+
+Every command MUST have tests using DeciderSpecification:
+
+```typescript
+import {DeciderSpecification} from '@event-driven-io/emmett';
+import {{CommandName}Command, {CommandName}State, decide, evolve} from "./{CommandName}Command";
+import {describe, it} from "node:test";
+
+describe('{CommandName} Specification', () => {
+    const given = DeciderSpecification.for({
+        decide,
+        evolve,
+        initialState: () => ({})
+    });
+
+    it('spec: {test description}', () => {
+        const command: {CommandName}Command = {
+            type: '{CommandName}',
+            data: {
+                // test data
+            },
+            metadata: {now: new Date()},
+        }
+
+        given([/* precondition events */])
+            .when(command)
+            .then([{
+                type: '{EventName}',
+                data: {
+                    // expected event data
+                },
+                metadata: {}
+            }])
+    });
+});
+```
+
+## Routes (API Endpoint)
+
+Unless explicitly told not to, create a routes.ts file:
+
+```typescript
+import {Router, Request, Response} from 'express';
+import {{CommandName}Command, handle{CommandName}} from './{CommandName}Command';
+import {requireUser} from "../../supabase/requireUser";
+import {WebApiSetup} from "@event-driven-io/emmett-expressjs";
+import {assertNotEmpty} from "../../common/assertions";
+
+export type {CommandName}RequestPayload = {
+    // fields matching command data (all optional with ?)
+}
+
+export type {CommandName}Request = Request<
+    Partial<{ id: string }>,
+    unknown,
+    Partial<{CommandName}RequestPayload>
+>;
+
+export const api =
+    (
+        // external dependencies
+    ): WebApiSetup =>
+        (router: Router): void => {
+            router.post('/api/{commandname}/:id', requireRestaurantAccess, async (req: {CommandName}Request, res: Response) => {
+                const principal = await requireUser(req, res, false);
+                if (principal.error) {
+                    return res.status(401).json(principal);
+                }
+
+                const correlation_id = req.header("correlation_id") ?? req.params.id
+                const causation_id = req.params.id
+                const restaurantId = (req as any).restaurant_id
+                const userId = (req as any).user_id
+
+                try {
+                    const command: {CommandName}Command = {
+                        data: {
+                            // map from req.body with assertNotEmpty
+                        },
+                        metadata: {
+                            correlation_id: correlation_id,
+                            causation_id: causation_id
+                        },
+                        type: "{CommandName}"
+                    }
+
+                    if (!req.params.id) throw "no id provided"
+
+                    const result = await handle{CommandName}(assertNotEmpty(req.params.id), command);
+
+                    res.set("correlation_id", correlation_id)
+                    res.set("causation_id", causation_id)
+
+                    return res.status(200).json({
+                        ok: true,
+                        next_expected_stream_version: result.nextExpectedStreamVersion?.toString(),
+                        last_event_global_position: result.lastEventGlobalPosition?.toString()
+                    });
+                } catch (err) {
+                    console.error(err);
+                    return res.status(500).json({ok: false, error: 'Server error'});
+                }
+            });
+        };
+```
+
+## Business Logic
+
+In *Command.ts
+Evolve-Function provides the state we can use to validate:
+
+```
+export const evolve = (
+    state: PlanVacationState,
+    event: ContextEvents,
+): PlanVacationState => {
+    const {type, data} = event;
+
+    switch (type) {
+        // case "..Event":
+        case 'VacationPlanned':
+            state.plannedVacations.push({id: event.data.vacation_id, from: event.data.from, to: event.data.to})
+            return state;
+        case 'VacationCancelled':
+            state.plannedVacations = state.plannedVacations.filter(it => it.id !== event.data.vacation_id)
+            return state;
+        default:
+            return state;
+    }
+};
+
+```
+
+The Decide-Function then makes the decision ( success or error )
+```
+export const decide = (
+    command: PlanVacationCommand,
+    state: PlanVacationState,
+): ContextEvents[] => {
+
+    state.plannedVacations.forEach(vacation => {
+        if (
+            command.data.from <= vacation.to &&
+            command.data.to >= vacation.from
+        ) {
+            throw {error: "conflicting_vacations"}
+        }
+    })
+
+    return [{
+        type: "VacationPlanned",
+        data: {
+          ...
+        },
+        metadata: {
+            ...
+        }
+    }]
+};
+```
+
+## Error  Handling
+
+In routes.ts, define an error mapper:
+```
+const errorMapping = (error:string): string => {
+
+    switch(error) {
+        case "conflicting_vacations" : return "Achtung, Betriebsurlaub überschneidet sich."
+        default: return "Leider ist ein Fehler aufgetreten"
+    }
+}
+```
+
+use this directly in the route.
+
+```
+  router.post('/api/planvacation/:id', requireRestaurantAccess, async (req: PlanVacationRequest, res: Response) => {
+                ...
+                } catch (err:any) {
+                    console.error(err);
+                    return res.status(500).json({ok: false, error:  errorMapping(err.error)});
+                }
+            });
+        };
+```
+
+## slice json
+in each slice folder, generate a file .slice.json
+```
+{
+    "id" : "<slice id>",
+    "slice": "<slice title>",
+    "context": "<contextx>",
+    "link": "https://miro.com/app/board/<board-id>=/?moveToWidget=<slice id>"
+}
+```
+
+## References
+
+- See `templates/AddLocation` for samples
+
+## UI Prompt
+
+```
+to build the UI - use this endpont "endpoint URL"
+
+Payload example:
+<payload example as JSON>
+
+make sure to put endpoints into the api.ts and follow the rules:
+- provide all headers
+
+```

package/templates/.claude/skills/slice-state-change/templates/AddLocation/AddLocation.test.ts.sample

@@ -0,0 +1,76 @@
+import {DeciderSpecification} from '@event-driven-io/emmett';
+import {AddLocationCommand, AddLocationInitialState, decide, evolve} from "./AddLocationCommand";
+import {describe, it} from "node:test";
+
+
+describe('AddLocation Specification', () => {
+
+    const given = DeciderSpecification.for({
+        decide,
+        evolve,
+        initialState: AddLocationInitialState
+    });
+
+    it('spec: Add Location - scenario', () => {
+
+        const command: AddLocationCommand = {
+            type: 'AddLocation',
+            data: {
+                city: "New York",
+                housenumber: "123",
+                name: "Main Office",
+                street: "Broadway",
+                zipCode: "10001",
+                location_id: "7771b53c-b378-4f10-a6b7-16f837316960"
+            },
+            metadata: {now: new Date()},
+        }
+
+        given([])
+            .when(command)
+            .then([{
+                type: 'LocationAdded',
+                data: {
+                    city: command.data.city,
+                    housenumber: command.data.housenumber,
+                    name: command.data.name,
+                    street: command.data.street,
+                    zipCode: command.data.zipCode,
+                    location_id: command.data.location_id
+                },
+                metadata: {}
+            }])
+    });
+
+    it('spec: Add duplicate Location - scenario', () => {
+
+        const command: AddLocationCommand = {
+            type: 'AddLocation',
+            data: {
+                city: "Boston",
+                housenumber: "456",
+                name: "Branch Office",
+                street: "Main St",
+                zipCode: "02101",
+                location_id: "7771b53c-b378-4f10-a6b7-16f837316960"
+            },
+            metadata: {now: new Date()},
+        }
+
+        given([{
+            type: 'LocationAdded',
+            data: {
+                city: "New York",
+                housenumber: "123",
+                name: "Main Office",
+                street: "Broadway",
+                zipCode: "10001",
+                location_id: "7771b53c-b378-4f10-a6b7-16f837316960"
+            },
+            metadata: {}
+        }])
+            .when(command)
+            .thenThrows()
+    });
+
+});

package/templates/.claude/skills/slice-state-change/templates/AddLocation/AddLocationCommand.ts.sample

@@ -0,0 +1,84 @@
+import type {Command} from '@event-driven-io/emmett'
+import {CommandHandler} from '@event-driven-io/emmett';
+import {ContextEvents} from "../../events/ContextEvents";
+import {findEventstore} from "../../common/loadPostgresEventstore";
+
+export type AddLocationCommand = Command<'AddLocation', {
+    city: string,
+    housenumber: string,
+    name: string,
+    street: string,
+    zipCode: string,
+    location_id: string
+},
+    {
+        correlation_id?: string,
+        causation_id?: string,
+        now?: Date,
+        streamName?: string,
+    }>;
+
+export type AddLocationState = {
+    locationIds: Set<string>;
+}
+
+export const AddLocationInitialState = (): AddLocationState => ({
+    locationIds: new Set(),
+});
+
+export const evolve = (
+    state: AddLocationState,
+    event: ContextEvents,
+): AddLocationState => {
+    const {type, data} = event;
+
+    switch (type) {
+        case "LocationAdded":
+            return {
+                ...state,
+                locationIds: new Set([...state.locationIds, data.location_id])
+            };
+        default:
+            return state;
+    }
+};
+
+export const decide = (
+    command: AddLocationCommand,
+    state: AddLocationState,
+): ContextEvents[] => {
+    // Check if location with same location_id already exists
+    if (state.locationIds.has(command.data.location_id)) {
+        throw new Error('location must be unique');
+    }
+
+    return [{
+        type: "LocationAdded",
+        data: {
+            city: command.data.city,
+            housenumber: command.data.housenumber,
+            name: command.data.name,
+            street: command.data.street,
+            zipCode: command.data.zipCode,
+            location_id: command.data.location_id
+        }, metadata: {
+            correlation_id: command.metadata?.correlation_id,
+            causation_id: command.metadata?.causation_id
+        }
+    }]
+};
+
+
+const AddLocationCommandHandler = CommandHandler<AddLocationState, ContextEvents>({
+    evolve,
+    initialState: AddLocationInitialState
+});
+
+export const handleAddLocation = async (id: string, command: AddLocationCommand) => {
+    const eventStore = await findEventstore()
+    const result = await AddLocationCommandHandler(eventStore, id, (state: AddLocationState) => decide(command, state))
+    return {
+        nextExpectedStreamVersion: result.nextExpectedStreamVersion,
+        lastEventGlobalPosition: result.lastEventGlobalPosition
+    }
+}

package/templates/.claude/skills/slice-state-change/templates/AddLocation/routes.ts.sample

@@ -0,0 +1,73 @@
+import {Request, Response, Router} from 'express';
+import {AddLocationCommand, handleAddLocation} from './AddLocationCommand';
+import {requireUser} from "../../supabase/requireUser";
+import {WebApiSetup} from "@event-driven-io/emmett-expressjs";
+import {assertNotEmpty} from "../../util/assertions";
+
+export type AddLocationRequestPayload = {
+    city?: string,
+    housenumber?: string,
+    name?: string,
+    street?: string,
+    zipCode?: string,
+    location_id?: string
+}
+
+export type AddLocationRequest = Request<
+    Partial<{ id: string }>,
+    unknown,
+    Partial<AddLocationRequestPayload>
+>;
+
+export const api =
+    (
+        // external dependencies
+    ): WebApiSetup =>
+        (router: Router): void => {
+            router.post('/api/addlocation/:id', requireRestaurantAccess, async (req: AddLocationRequest, res: Response) => {
+                const principal = await requireUser(req, res, false);
+                if (principal.error) {
+                    return res.status(401).json(principal);
+                }
+
+                const correlation_id = req.header("correlation_id") ?? req.params.id
+                const causation_id = req.params.id
+
+                try {
+                    const command: AddLocationCommand = {
+                        data: {
+                            city: assertNotEmpty(req.body.city),
+                            housenumber: assertNotEmpty(req.body.housenumber),
+                            name: assertNotEmpty(req.body.name),
+                            street: assertNotEmpty(req.body.street),
+                            zipCode: assertNotEmpty(req.body.zipCode),
+                            location_id: assertNotEmpty(req.body.location_id)
+                        },
+                        metadata: {
+                            correlation_id: correlation_id,
+                            causation_id: causation_id
+                        },
+                        type: "AddLocation"
+                    }
+
+                    if (!req.params.id) throw "no id provided"
+
+                    const result = await handleAddLocation(assertNotEmpty(req.params.id), command);
+
+                    res.set("correlation_id", correlation_id)
+                    res.set("causation_id", causation_id)
+
+                    return res.status(200).json({
+                        ok: true,
+                        next_expected_stream_version: result.nextExpectedStreamVersion?.toString(),
+                        last_event_global_position: result.lastEventGlobalPosition?.toString()
+                    });
+                } catch (err) {
+                    console.error(err);
+                    if (err instanceof Error && err.message === 'location must be unique') {
+                        return res.status(409).json({ok: false, error: 'location must be unique'});
+                    }
+                    return res.status(500).json({ok: false, error: 'Server error'});
+                }
+            });
+        };

package/templates/.claude/skills/slice-state-change/templates/README.md

@@ -0,0 +1,46 @@
+# State-Change Slice Templates
+
+This folder contains real working examples from the codebase to use as templates.
+
+## Simple Example: AddTable
+
+**Files:**
+- `sample.ts.sample` - Command handler
+- `sample-test.ts.sample` - Tests
+- `routes.ts.sample` - API endpoint
+
+**Use this when:**
+- No business logic validation needed
+- Simple event emission
+- Empty state `{}`
+- Direct command-to-event mapping
+
+**Key features:**
+- Destructuring pattern for command data
+- Direct metadata access (no optional chaining)
+- Simple decide function with no validation
+
+## Complex Example with Validation: AddLocation
+
+**Files:**
+- `AddLocation/AddLocationCommand.ts.sample` - Command handler
+- `AddLocation/AddLocation.test.ts.sample` - Tests with validation scenarios
+- `AddLocation/routes.ts.sample` - API endpoint with error handling
+
+**Use this when:**
+- Business logic validation required
+- State tracking needed (e.g., tracking unique IDs)
+- Error conditions must be tested
+- Custom error handling in API
+
+**Key features:**
+- State management with Set for uniqueness checking
+- Evolve function that updates state
+- Validation in decide function with error throwing
+- Multiple test scenarios (success and error cases)
+- Custom HTTP status codes (409 for conflict)
+- Specific error message handling in routes
+
+## Other Files
+
+- `sample-input.json` - Example JSON input structure for event modeling