@eventmodelers/cli 0.0.1

package/stacks/supabase/templates/root/server.ts

@@ -0,0 +1,177 @@
+import {join} from 'path';
+import {getApplication, startAPI, WebApiSetup} from '@event-driven-io/emmett-expressjs';
+import {glob} from "glob";
+import express, {Application, Request, Response} from 'express';
+import {jsonBigIntReplacer} from './src/util/sanitize';
+import {requireUser} from "./src/supabase/requireUser";
+import {getKnexInstance, closeDb} from "./src/common/db";
+import swaggerUi from 'swagger-ui-express'
+import {specs} from './src/swagger';
+import cors from 'cors';
+import {findEventstore} from "./src/common/loadPostgresEventstore";
+import {PostgresEventStore} from "@event-driven-io/emmett-postgresql";
+
+async function startServer() {
+
+    const eventStore = await findEventstore()
+    const slicesBase = join(__dirname, 'dist/src/slices');
+    const routesPattern = join(slicesBase, '**/routes{,-*}.js');
+
+    const routeFiles = await glob(routesPattern, {nodir: true});
+    console.log('Found route files:', routeFiles);
+
+    const processorPattern = join(slicesBase, '**/processor{,-*}.js');
+    const processorFiles = await glob(processorPattern, {nodir: true});
+    console.log('Found processor files:', processorFiles);
+
+    // Common routes (e.g. projection replay) are privileged/operational and are
+    // only mounted when explicitly enabled via env.
+    const commonRoutesEnabled = process.env.COMMON_ROUTES_ENABLED === 'true';
+    const commonPattern = join(__dirname, 'src/common/routes{,-*}.@(ts|js)');
+    const commonRouteFiles = commonRoutesEnabled
+        ? await glob(commonPattern, {nodir: true})
+        : [];
+    console.log(commonRoutesEnabled
+        ? `Found common route files: ${commonRouteFiles}`
+        : 'Common routes disabled (set COMMON_ROUTES_ENABLED=true to enable)');
+
+
+    const rootApp: Application = express();
+    rootApp.set('json replacer', jsonBigIntReplacer);
+
+    const corsOrigins = process.env.CORS_ORIGINS?.split(',').map(o => o.trim()) ?? ['http://localhost:3000', 'http://localhost:3001'];
+    rootApp.use(cors({
+        origin: corsOrigins,
+        credentials: true,
+        methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'Content-Encoding',  'accept-encoding', 'Authorization','x-user-id','x-causation-id','x-correlation-id']
+    }));
+
+    const webApis: WebApiSetup[] = [];
+
+    for (const file of routeFiles.concat(commonRouteFiles)) {
+        const webApiModule: { api: () => WebApiSetup } = await import(file);
+        if (typeof webApiModule.api == 'function') {
+            var module = webApiModule.api()
+            webApis.push(module);
+        } else {
+            console.error(`Expected api function to be defined in ${file}`);
+        }
+    }
+
+    const startedProcessors: Array<{ stop: () => Promise<void> }> = [];
+
+    for (const processorFile of processorFiles) {
+        const processor: { processor: { start: (eventStore: PostgresEventStore) => Promise<void>; stop: () => Promise<void> } } = await import(processorFile);
+        if (typeof processor.processor.start == "function") {
+            console.log(`starting processor ${processorFile}`)
+            processor.processor.start(eventStore).catch(err => console.error(`Processor ${processorFile} failed:`, err));
+            startedProcessors.push(processor.processor);
+        }
+    }
+
+    const shutdown = async (signal: string) => {
+        console.log(`${signal} received, shutting down processors...`);
+        await Promise.allSettled(startedProcessors.map(p => p.stop()));
+        await eventStore.close();
+        await closeDb();
+        console.log('shutdown complete');
+        process.exit(0);
+    };
+
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+    // Get the main application from emmett
+    const childApp: Application = getApplication({
+        apis: webApis,
+        disableJsonMiddleware: false,
+        enableDefaultExpressEtag: true,
+    });
+    childApp.set('json replacer', jsonBigIntReplacer);
+
+    // Protected user info endpoint - requires JWT token in Authorization header
+    childApp.get('/api/user', async (req: Request, res: Response) => {
+        console.log('API user route hit'); // Debug log
+        try {
+            const result = await requireUser(req, res, false)
+            if (result.error) {
+                // Response already sent by requireUser if sendUnauthorized=true
+                if (!res.headersSent) {
+                    res.status(401).json({error: result.error})
+                }
+            } else {
+                res.status(200).json({
+                    user_id: result.user.id,
+                    email: result.user.email,
+                    metadata: result.user.user_metadata
+                })
+            }
+        } catch (error) {
+            console.error('Error in /api/user:', error);
+            if (!res.headersSent) {
+                res.status(500).json({error: 'Internal server error'});
+            }
+        }
+    });
+
+    // Swagger UI endpoints
+    childApp.use('/api-docs', swaggerUi.serve);
+    childApp.get('/api-docs', swaggerUi.setup(specs, {
+        swaggerOptions: {
+            urls: [
+                {
+                    url: '/swagger.json',
+                    name: 'JSON',
+                },
+            ],
+        },
+    }));
+
+    // OpenAPI spec endpoint
+    childApp.get('/swagger.json', (req: Request, res: Response) => {
+        res.setHeader('Content-Type', 'application/json');
+        res.send(specs);
+    });
+
+    const port = parseInt(process.env.PORT || '3000', 10);
+    console.log(`> Ready on port ${port}`);
+
+    rootApp.use((req: Request, _res: Response, next) => {
+        console.log(`[${req.method}] ${req.path}`);
+        next();
+    });
+
+    rootApp.use(express.json());
+
+    // Closed-by-default auth gate: every route requires a valid Supabase JWT
+    // except the explicitly public paths below. This guarantees new slice
+    // routes are protected even if a handler forgets to call requireUser.
+    const PUBLIC_PATHS = ['/api-docs', '/swagger.json', '/health'];
+    const isPublicPath = (p: string): boolean =>
+        PUBLIC_PATHS.some(pub => p === pub || p.startsWith(pub + '/'));
+
+    rootApp.use(async (req: Request, res: Response, next) => {
+        if (req.method === 'OPTIONS') return next();      // CORS preflight
+        if (isPublicPath(req.path)) return next();        // docs / health
+        const {error} = await requireUser(req, res);      // sends 401 on failure
+        if (error) return;                                // response already sent
+        next();
+    });
+
+    rootApp.use(childApp)
+    // Start the main application
+    startAPI(rootApp, {port: port});
+
+    process.on('unhandledRejection', (reason, promise) => {
+        console.error('⛔ Unhandled Rejection:', reason);
+        if (reason instanceof Error && reason.stack) {
+            console.error('Stack trace:\n', reason.stack);
+        }
+    });
+}
+
+startServer().catch(error => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});

package/stacks/supabase/templates/root/setup-env.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+prompt() {
+  local var_name="$1"
+  local prompt_text="$2"
+  local value
+  read -rp "$prompt_text: " value
+  if [[ -z "$value" ]]; then
+    echo "Error: $var_name cannot be empty." >&2
+    exit 1
+  fi
+  echo "$value"
+}
+
+prompt_secret() {
+  local var_name="$1"
+  local prompt_text="$2"
+  local value
+  read -rsp "$prompt_text: " value
+  echo "" >&2
+  if [[ -z "$value" ]]; then
+    echo "Error: $var_name cannot be empty." >&2
+    exit 1
+  fi
+  echo "$value"
+}
+
+echo "=== Supabase .env setup ==="
+echo ""
+
+PROJECT_ID=$(prompt SUPABASE_PROJECT_ID "Supabase Project ID")
+DB_PASSWORD=$(prompt_secret SUPABASE_DB_PASSWORD "Database Password")
+PUBLISHABLE_KEY=$(prompt_secret SUPABASE_PUBLISHABLE_KEY "Supabase Publishable Key")
+SECRET_KEY=$(prompt_secret SUPABASE_SECRET_KEY "Supabase Secret Key")
+BACKEND_URL=$(prompt BACKEND_URL "Backend URL (e.g. https://api.eventmodelers.ai)")
+
+cat > .env <<EOF
+SUPABASE_URL=https://${PROJECT_ID}.supabase.co
+SUPABASE_PUBLISHABLE_KEY=${PUBLISHABLE_KEY}
+SUPABASE_DB_URL=postgresql://postgres.${PROJECT_ID}:${DB_PASSWORD}@aws-1-eu-central-1.pooler.supabase.com:5432/postgres?prepareThreshold=0
+SUPABASE_SECRET_KEY=${SECRET_KEY}
+
+BACKEND_URL=${BACKEND_URL}
+
+# Flyway configuration
+FLYWAY_URL=jdbc:postgresql://aws-1-eu-west-1.pooler.supabase.com:6543/postgres?user=postgres.${PROJECT_ID}&password=${DB_PASSWORD}
+FLYWAY_USER=postgres.${PROJECT_ID}
+FLYWAY_PASSWORD=${DB_PASSWORD}
+EOF
+
+echo ""
+echo ".env created successfully."

package/stacks/supabase/templates/root/src/common/assertions.ts

@@ -0,0 +1,6 @@
+export function assertNotEmpty<T>(value: T): NonNullable<T> {
+    if (value === null || value === undefined) {
+        throw new Error("Expected non-empty value");
+    }
+    return value!!;
+}

package/stacks/supabase/templates/root/src/common/db.ts

@@ -0,0 +1,32 @@
+import knex, {Knex} from "knex";
+import pg from "pg";
+
+export const postgresUrl = process.env.SUPABASE_DB_URL ?? "missing-url"
+
+let knexInstance: Knex | null = null;
+let sharedPool: pg.Pool | null = null;
+
+export const getKnexInstance = (): Knex => {
+    if (!knexInstance) {
+        knexInstance = knex({
+            client: 'pg',
+            connection: postgresUrl,
+            pool: { min: 0, max: 5 },
+        });
+    }
+    return knexInstance;
+};
+
+export const getSharedPool = (): pg.Pool => {
+    if (!sharedPool) {
+        sharedPool = new pg.Pool({ connectionString: postgresUrl, max: 5 });
+    }
+    return sharedPool;
+};
+
+export const closeDb = async (): Promise<void> => {
+    await knexInstance?.destroy();
+    await sharedPool?.end();
+    knexInstance = null;
+    sharedPool = null;
+};

package/stacks/supabase/templates/root/src/common/loadPostgresEventstore.ts

@@ -0,0 +1,23 @@
+import {getPostgreSQLEventStore} from "@event-driven-io/emmett-postgresql";
+import {projections} from "@event-driven-io/emmett";
+import {postgresUrl, getSharedPool} from "./db";
+
+let eventStoreInstance: ReturnType<typeof getPostgreSQLEventStore> | null = null;
+
+export const findEventstore = async () => {
+    if (!eventStoreInstance) {
+        eventStoreInstance = getPostgreSQLEventStore(postgresUrl, {
+            schema: {
+                autoMigration: "CreateOrUpdate"
+            },
+            connectionOptions: {
+                pooled: true,
+                pool: getSharedPool(),
+            },
+            projections: projections.inline([
+            ]),
+        });
+        await eventStoreInstance.schema.migrate();
+    }
+    return eventStoreInstance;
+};

package/stacks/supabase/templates/root/src/common/parseEndpoint.ts

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025 Nebulit GmbH
+ * Licensed under the MIT License.
+ */
+
+const serviceURI = "http://localhost:3000"
+
+export function parseEndpoint(endpoint: string, data?: any) {
+    var parsedEndpoint = endpoint?.startsWith("/") ? endpoint.substring(1) : endpoint
+    return serviceURI + "/" + lowercaseFirstCharacter(parsedEndpoint).replace(/{(\w+)}/g, (match, param) => {
+        return param && data && data[param] !== undefined ? data[param] : match;
+    })
+}
+
+
+export function parseQueryEndpoint(
+    endpoint: string,
+    queries?: Record<string, string>
+) {
+    const parsedEndpoint = endpoint.startsWith("/")
+        ? endpoint.substring(1)
+        : endpoint;
+
+    const basePath =
+        serviceURI + "/api/query/" + parsedEndpoint;
+
+    const queryString = queries
+        ? "?" + new URLSearchParams(filterEmptyEntries(queries)).toString()
+        : "";
+
+    return basePath + queryString;
+}
+
+function filterEmptyEntries(queries?: Record<string, string>): Record<string, string> {
+    if (!queries) return {};
+    return Object.fromEntries(
+        Object.entries(queries).filter(([key, value]) => value !== "")
+    );
+}
+
+
+function lowercaseFirstCharacter(inputString: string) {
+    // Check if the string is not empty
+    if (inputString?.length > 0) {
+        // Capitalize the first character and concatenate the rest of the string
+        return inputString.charAt(0).toLowerCase() + inputString.substring(1);
+    } else {
+        // Return an empty string if the input is empty
+        return "";
+    }
+}

package/stacks/supabase/templates/root/src/common/processorDlq.ts

@@ -0,0 +1,28 @@
+import {getKnexInstance} from './db';
+import type {AnyRecordedMessageMetadata, RecordedMessage} from '@event-driven-io/emmett';
+
+export const storeDlqMessage = async (
+    processorId: string,
+    message: RecordedMessage<any, AnyRecordedMessageMetadata>,
+    error: unknown,
+): Promise<void> => {
+
+    try {
+        console.log(`Processing DLQ ${JSON.stringify({ type: message.type, data: message.data, metadata: message.metadata } , (key, value) =>
+            typeof value === 'bigint' ? value.toString() : value
+        )}`)
+        await getKnexInstance()('processor_dlq').insert({
+            processor_id: processorId,
+            stream_id: message.metadata.streamName,
+            event:  JSON.parse(
+                JSON.stringify({ type: message.type, data: message.data, metadata: message.metadata } , (key, value) =>
+                    typeof value === 'bigint' ? value.toString() : value
+                )
+            ),
+            error: error instanceof Error ? error.message : String(error),
+        });
+    } catch (dlqError) {
+        console.error('Failed to write to processor_dlq:', dlqError);
+    }
+};
+

package/stacks/supabase/templates/root/src/common/realtimeBroadcast.ts

@@ -0,0 +1,19 @@
+const url = `${process.env.SUPABASE_URL}/realtime/v1/api/broadcast`;
+const key = process.env.SUPABASE_SECRET_KEY!;
+
+export async function broadcastRealtime(topic: string, event: string, payload: unknown, privateChannel = true): Promise<void> {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${key}`,
+            'apikey': key,
+        },
+        body: JSON.stringify({
+            messages: [{ topic, event, payload, private: privateChannel }],
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`realtime broadcast failed: ${res.status} ${await res.text()}`);
+    }
+}

package/stacks/supabase/templates/root/src/common/replay.ts

@@ -0,0 +1,16 @@
+import {PostgreSQLProjectionDefinition, rebuildPostgreSQLProjections} from "@event-driven-io/emmett-postgresql";
+import {postgresUrl} from "./db";
+import {glob} from "glob";
+import path from "path";
+
+const slicesRoot = path.resolve(__dirname, '../slices');
+
+export const replayProjection = async (projectionName: string): Promise<void> => {
+    const [filePath] = await glob(`**/${projectionName}.{ts|js}`, {cwd: slicesRoot, absolute: true});
+    if (!filePath) throw new Error(`Projection not found: ${projectionName}`);
+
+    const projectionImport = await import(filePath);
+    const projection: PostgreSQLProjectionDefinition = projectionImport[projectionName];
+
+    return rebuildPostgreSQLProjections({projection, connectionString: postgresUrl}).start();
+}

package/stacks/supabase/templates/root/src/common/routes.ts

@@ -0,0 +1,23 @@
+import {Request, Response, Router} from 'express';
+import {WebApiSetup} from "@event-driven-io/emmett-expressjs";
+import {assertNotEmpty} from "../util/assertions";
+import {replayProjection} from "./replay";
+import {requireSysUser} from "../supabase/requireSysUser";
+
+
+export const api =
+    (
+        // external dependencies
+    ): WebApiSetup =>
+        (router: Router): void => {
+
+            router.post('/api/replay/:projection', async (req: Request, res: Response) => {
+                // Replay is a privileged operational action — require a sys user.
+                const {error} = await requireSysUser(req, res); // sends 401/403 on failure
+                if (error) return;
+                const projection = assertNotEmpty(req.params.projection)
+                await replayProjection(projection)
+                res.status(200).json({"projection":projection})
+            });
+        };
+

package/stacks/supabase/templates/root/src/common/testHelpers.ts

@@ -0,0 +1,54 @@
+import {execSync} from 'child_process';
+import {readFileSync, writeFileSync, unlinkSync} from 'fs';
+import {tmpdir} from 'os';
+import {join} from 'path';
+import knex from 'knex';
+
+export async function runFlywayMigrations(connectionString: string): Promise<void> {
+    const stubsPath = join(process.cwd(), 'supabase', 'migrations', '_V0__supabase_stubs.sql');
+    const stubsSql = readFileSync(stubsPath, 'utf8');
+    const db = knex({client: 'pg', connection: connectionString});
+    try {
+        await db.raw(stubsSql);
+    } finally {
+        await db.destroy();
+    }
+
+    const url = new URL(connectionString);
+    const jdbcUrl = `jdbc:postgresql://${url.hostname}:${url.port || 5432}${url.pathname}`;
+    const user = url.username;
+    const password = url.password;
+
+    const tempConfigPath = join(tmpdir(), `flyway-test-${Date.now()}.conf`);
+    const migrationsPath = join(process.cwd(), 'supabase', 'migrations');
+
+    const config = `
+flyway.url=${jdbcUrl}
+flyway.user=${user}
+flyway.password=${password}
+flyway.locations=filesystem:${migrationsPath}
+flyway.schemas=public
+flyway.placeholderReplacement=false
+flyway.validateOnMigrate=true
+flyway.cleanDisabled=false
+`;
+
+    try {
+        writeFileSync(tempConfigPath, config, 'utf8');
+        execSync(`flyway -configFiles=${tempConfigPath} migrate`, {
+            stdio: 'pipe',
+            encoding: 'utf8'
+        });
+    } catch (error: any) {
+        console.error('Flyway migration failed:', error.message);
+        if (error.stdout) console.error('STDOUT:', error.stdout);
+        if (error.stderr) console.error('STDERR:', error.stderr);
+        throw new Error(`Flyway migration failed: ${error.message}`);
+    } finally {
+        try {
+            unlinkSync(tempConfigPath);
+        } catch {
+            // ignore
+        }
+    }
+}

package/stacks/supabase/templates/root/src/supabase/README.md

@@ -0,0 +1,141 @@
+# Supabase JWT Authentication for Backend API
+
+This backend API uses Supabase JWT tokens for authentication. Clients must include a valid JWT token in the
+`Authorization` header.
+
+## Quick Start
+
+1. **Set up environment variables** in `.env`:
+   ```env
+   SUPABASE_URL=http://127.0.0.1:54321
+   SUPABASE_PUBLISHABLE_KEY=your-anon-key-here
+   ```
+
+2. **Start the server**: `npm run dev`
+
+3. **Get a test JWT token**: sign in a user via the Supabase client SDK or `supabase auth` CLI and use the returned `access_token` in your API requests.
+
+## How It Works
+
+1. **Client obtains JWT token** from Supabase (via your frontend app)
+2. **Client sends requests** with `Authorization: Bearer <jwt-token>` header
+3. **Backend verifies JWT** using Supabase and extracts user info
+4. **Protected routes** return user data or 401 Unauthorized
+
+## Usage Examples
+
+### Option 1: Using `requireUser` function
+
+```typescript
+import {requireUser} from './src/supabase/requireUser';
+import {Request, Response} from 'express';
+
+app.get('/api/protected', async (req: Request, res: Response) => {
+    const result = await requireUser(req, res, false);
+
+    if (result.error) {
+        return res.status(401).json({error: result.error});
+    }
+
+    const user = result.user;
+    res.json({
+        message: 'Protected data',
+        userId: user.id,
+        email: user.email
+    });
+});
+```
+
+### Testing with curl
+
+```bash
+# Get JWT token from your Supabase client first
+TOKEN="your-jwt-token-here"
+
+# Test protected endpoint
+curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/user
+
+# Expected response:
+# {
+#   "userId": "...",
+#   "email": "user@example.com",
+#   "metadata": { ... }
+# }
+```
+
+### Testing with JavaScript fetch
+
+```javascript
+const token = supabase.auth.session()?.access_token;
+
+fetch('http://localhost:3000/api/user', {
+    headers: {
+        'Authorization': `Bearer ${token}`
+    }
+})
+    .then(res => res.json())
+    .then(data => console.log(data));
+```
+
+## API Endpoints
+
+### `GET /api/user`
+
+Returns current authenticated user information.
+
+**Headers:**
+
+- `Authorization: Bearer <jwt-token>` (required)
+
+**Success Response (200):**
+
+```json
+{
+    "userId": "uuid",
+    "email": "user@example.com",
+    "metadata": { ... }
+}
+```
+
+**Error Responses:**
+
+- `401 Unauthorized`: Missing or invalid token
+- `500 Internal Server Error`: Server error
+
+## Files
+
+- **`api.ts`**: Supabase client creation
+- **`requireUser.ts`**: JWT verification function
+- **`requireSysUser.ts`**: Requires an authenticated system ("sys") user
+- **`requireOrgaAdmin.ts`**: Requires the caller to be an org admin
+- **`README.md`**: This documentation
+
+## Architecture
+
+```
+Client Request
+    |
+    v
+Authorization: Bearer <JWT>
+    |
+    v
+Express Route
+    |
+    v
+requireUser() / requireSysUser() / requireOrgaAdmin()
+    |
+    v
+Supabase JWT Verification
+    |
+    +---> Valid: Continue with user data
+    |
+    +---> Invalid: Return 401 Unauthorized
+```
+
+## Security Notes
+
+- JWT tokens are verified with Supabase on every request
+- No session storage on the backend (stateless)
+- Tokens expire based on Supabase configuration
+- Always use HTTPS in production
+- Store the anon key securely (use environment variables)

package/stacks/supabase/templates/root/src/supabase/api.ts

@@ -0,0 +1,56 @@
+import {createClient as createSupabaseClient} from '@supabase/supabase-js'
+import {Request} from 'express'
+
+let _serviceClient: ReturnType<typeof createSupabaseClient> | null = null;
+
+export const createServiceClient = () => {
+    if (!_serviceClient) {
+        _serviceClient = createSupabaseClient(
+            process.env.SUPABASE_URL!,
+            process.env.SUPABASE_SECRET_KEY!
+        );
+    }
+    return _serviceClient;
+}
+
+/**
+ * Creates a Supabase client for verifying JWT tokens
+ * Used in backend API endpoints
+ */
+export default function createClient() {
+    return createSupabaseClient(
+        process.env.SUPABASE_URL!,
+        process.env.SUPABASE_PUBLISHABLE_KEY!,
+        {
+            auth: {
+                persistSession: false,
+                autoRefreshToken: false,
+                detectSessionInUrl: false,
+            },
+        }
+    )
+}
+
+/**
+ * Creates an authenticated Supabase client with the user's JWT token
+ * This ensures Row Level Security (RLS) policies are applied with the user's context
+ */
+export async function createAuthenticatedClient(req: Request) {
+    const token = req.headers.authorization?.replace('Bearer ', '') || '';
+    return createSupabaseClient(
+        process.env.SUPABASE_URL!,
+        process.env.SUPABASE_PUBLISHABLE_KEY!,
+        {
+            auth: {
+                persistSession: false,
+                autoRefreshToken: false,
+                detectSessionInUrl: false,
+            },
+            global: {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                },
+            },
+        }
+    );
+}