@facetlayer/prism-framework 0.4.0 → 0.4.1

package/docs/cors-setup.md

@@ -0,0 +1,172 @@
+---
+name: cors-setup
+description: How to configure CORS (Cross-Origin Resource Sharing) for your Prism API server
+---
+
+# CORS Setup
+
+This guide explains how to configure CORS (Cross-Origin Resource Sharing) for your Prism Framework API server.
+
+## Overview
+
+CORS controls which web origins can make requests to your API. The Prism Framework includes built-in CORS middleware that handles preflight requests and sets appropriate headers.
+
+## Configuration Options
+
+Pass a `corsConfig` object to `startServer` (see `server-setup` doc for full `startServer` details):
+
+```typescript
+await startServer({
+  app,
+  port: 4000,
+  corsConfig: {
+    webBaseUrl: 'example.com',
+  },
+});
+```
+
+### CorsConfig Interface
+
+```typescript
+interface CorsConfig {
+  /** Base URL for web application (e.g., 'example.com' or 'https://example.com') */
+  webBaseUrl?: string;
+
+  /** Allow any localhost origin (http://localhost:*) for local development */
+  allowLocalhost?: boolean;
+
+  /** @deprecated Use `allowLocalhost` instead */
+  enableTestEndpoints?: boolean;
+}
+```
+
+## Option Details
+
+### webBaseUrl
+
+Specifies the production web domain that is allowed to make cross-origin requests.
+
+- **Format**: Domain only (e.g., `'example.com'`) or full URL (e.g., `'https://example.com'`)
+- **Behavior**: Allows requests from `https://{webBaseUrl}`
+- **Typical usage**: Set via environment variable `WEB_BASE_URL`
+
+```typescript
+corsConfig: {
+  webBaseUrl: process.env.WEB_BASE_URL,  // e.g., 'myapp.example.com'
+}
+```
+
+### allowLocalhost
+
+Enables CORS for any `http://localhost:*` origin (any port). This is the recommended setting for local development where the API server and frontend run on different ports.
+
+- **Default**: `false`
+- **When `true`**: Allows any localhost origin for development
+- **When `false`**: Localhost origins are blocked
+- **Typical usage**: Enable in development, disable in production
+
+```typescript
+corsConfig: {
+  allowLocalhost: process.env.NODE_ENV !== 'production',
+}
+```
+
+### enableTestEndpoints (deprecated)
+
+Use `allowLocalhost` instead. When both are set, `allowLocalhost` takes precedence.
+
+## Environment Variable Pattern
+
+A common pattern is to configure CORS via environment variables:
+
+```bash
+# .env (development)
+WEB_BASE_URL=localhost:3000
+ALLOW_LOCALHOST=true
+
+# .env (production)
+WEB_BASE_URL=myapp.example.com
+ALLOW_LOCALHOST=false
+```
+
+```typescript
+corsConfig: {
+  webBaseUrl: process.env.WEB_BASE_URL,
+  allowLocalhost: process.env.ALLOW_LOCALHOST === 'true',
+}
+```
+
+## CORS Headers
+
+The middleware automatically sets these headers on all responses:
+
+| Header | Value |
+|--------|-------|
+| `Access-Control-Allow-Credentials` | `true` |
+| `Access-Control-Allow-Methods` | `GET, POST, PUT, DELETE, OPTIONS, PATCH` |
+| `Access-Control-Allow-Headers` | `Origin, X-Requested-With, Content-Type, Accept, Authorization, Cookie, Cache-Control` |
+| `Access-Control-Max-Age` | `86400` (24 hours) |
+
+## Preflight Requests
+
+The middleware automatically handles OPTIONS preflight requests by returning HTTP 200 with the appropriate CORS headers.
+
+## Security Notes
+
+- **Whitelist-based**: Only explicitly allowed origins receive the `Access-Control-Allow-Origin` header
+- **No wildcards**: The middleware uses specific domain matching instead of `*`
+- **Credentials enabled**: Supports cookie-based authentication
+- **Non-matching origins**: Requests from non-allowed origins do not receive CORS headers, causing the browser to block the response
+
+## Examples
+
+### Development Setup (localhost only)
+
+```typescript
+await startServer({
+  app,
+  port: 4000,
+  corsConfig: {
+    allowLocalhost: true,
+  },
+});
+```
+
+### Production Setup
+
+```typescript
+await startServer({
+  app,
+  port: 4000,
+  corsConfig: {
+    webBaseUrl: 'myapp.example.com',
+  },
+});
+```
+
+### Combined Setup (development + production)
+
+```typescript
+await startServer({
+  app,
+  port: parseInt(process.env.PRISM_API_PORT, 10),
+  corsConfig: {
+    webBaseUrl: process.env.WEB_BASE_URL,
+    allowLocalhost: process.env.ALLOW_LOCALHOST === 'true',
+  },
+});
+```
+
+## Troubleshooting
+
+### "No 'Access-Control-Allow-Origin' header" error
+
+This means the requesting origin is not allowed. Check:
+
+1. For localhost development: Ensure `allowLocalhost: true` is set
+2. For production: Ensure `webBaseUrl` matches your frontend's domain
+3. The request origin uses the correct protocol (https for production)
+
+### Preflight requests failing
+
+Ensure your server is running and the CORS middleware is configured. The middleware handles OPTIONS requests automatically.

package/docs/creating-services.md

@@ -0,0 +1,220 @@
+---
+name: creating-services
+description: How to create services with endpoints, middleware, and database schemas
+---
+
+# Creating Services
+
+Services are the building blocks of a Prism Framework application. Each service is self-contained and can define endpoints, middleware, database schemas, and background jobs.
+
+## ServiceDefinition Interface
+
+```typescript
+interface ServiceDefinition {
+  /** Unique name identifying this service */
+  name: string;
+
+  /** API endpoints provided by this service */
+  endpoints?: EndpointDefinition[];
+
+  /** Express middleware scoped to specific paths */
+  middleware?: MiddlewareDefinition[];
+
+  /** SQLite database schemas, keyed by database name */
+  databases?: Record<string, {
+    statements: string[];  // SQL CREATE TABLE / CREATE INDEX statements
+  }>;
+
+  /** Async callback to start background jobs when the app initializes */
+  startJobs?: () => Promise<void>;
+}
+```
+
+All fields except `name` are optional. A service can provide any combination of endpoints, middleware, databases, and background jobs.
+
+## Basic Service Structure
+
+```typescript
+import { ServiceDefinition, createEndpoint } from '@facetlayer/prism-framework';
+import { z } from 'zod';
+
+export const definition: ServiceDefinition = {
+  name: 'my-service',
+
+  // API endpoints
+  endpoints: [
+    // ... endpoint definitions
+  ],
+
+  // Optional middleware
+  middleware: [
+    // ... middleware definitions
+  ],
+
+  // Optional database schemas
+  databases: {
+    user: {
+      statements: [
+        // SQL statements for user database
+      ],
+    },
+  },
+
+  // Optional background jobs
+  startJobs: async () => {
+    // Initialize background tasks
+  },
+};
+```
+
+## Defining Endpoints
+
+Endpoints are defined with type safety using Zod schemas:
+
+```typescript
+const GetUserRequest = z.object({
+  userId: z.string(),
+});
+
+const GetUserResponse = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+});
+
+const getUserEndpoint = createEndpoint({
+  method: 'GET',
+  path: '/users/:userId',
+  requestSchema: GetUserRequest,
+  responseSchema: GetUserResponse,
+  requires: ['authenticated-user'], // Optional requirements
+  handler: async (input) => {
+    // input is typed as z.infer<typeof GetUserRequest>
+    const user = await getUserById(input.userId);
+    return user; // Must match GetUserResponse schema
+  },
+});
+```
+
+### Endpoint Methods
+
+Supported HTTP methods:
+- `GET`
+- `POST`
+- `PUT`
+- `DELETE`
+- `PATCH`
+
+### Request Data
+
+The framework automatically combines data from:
+- Request body (`req.body`)
+- URL parameters (`req.params`)
+- Query parameters (`req.query`)
+
+All are merged and validated against the `requestSchema`.
+
+### Requirements
+
+The `requires` array can specify:
+- `'authenticated-user'` - Requires an authenticated user (checks for user resource in context)
+
+Applications can extend this by providing custom middleware or handlers.
+
+## Server-Sent Events (SSE)
+
+For streaming responses, return an object with a `startSse` method:
+
+```typescript
+createEndpoint({
+  method: 'GET',
+  path: '/stream',
+  handler: async () => {
+    return {
+      startSse: (sse: SseResponse) => {
+        // Send events
+        sse.send({ message: 'Hello' });
+        sse.send({ message: 'World' });
+
+        // Close when done
+        sse.close();
+
+        // Or handle client disconnect
+        sse.onClose(() => {
+          console.log('Client disconnected');
+        });
+      },
+    };
+  },
+});
+```
+
+## Adding Middleware
+
+Middleware can be path-specific:
+
+```typescript
+export const definition: ServiceDefinition = {
+  name: 'my-service',
+  middleware: [
+    {
+      path: '/admin/*',
+      handler: (req, res, next) => {
+        // Check admin permissions
+        if (!isAdmin(req)) {
+          return res.status(403).json({ error: 'Forbidden' });
+        }
+        next();
+      },
+    },
+  ],
+};
+```
+
+## Database Schemas
+
+Define database schemas per database:
+
+```typescript
+export const definition: ServiceDefinition = {
+  name: 'users',
+  databases: {
+    user: {
+      statements: [
+        `CREATE TABLE IF NOT EXISTS users (
+          id INTEGER PRIMARY KEY,
+          email TEXT UNIQUE NOT NULL,
+          name TEXT,
+          created_at DATETIME DEFAULT (datetime('now', 'utc') || 'Z')
+        )`,
+        `CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)`,
+      ],
+    },
+    project: {
+      statements: [
+        // Project-specific tables
+      ],
+    },
+  },
+};
+```
+
+## Background Jobs
+
+Services can start background jobs when the application initializes:
+
+```typescript
+export const definition: ServiceDefinition = {
+  name: 'cleanup',
+  startJobs: async () => {
+    // Run periodic cleanup
+    setInterval(async () => {
+      await cleanupOldData();
+    }, 60 * 60 * 1000); // Every hour
+  },
+};
+```
+
+## Error Handling
+
+Use the built-in HTTP error classes to return proper status codes from handlers. See the `error-handling` doc for the full list of available error classes and usage patterns.

package/docs/database-setup.md

@@ -0,0 +1,134 @@
+---
+name: database-setup
+description: How to set up a local SQLite database for your backend application
+---
+
+# Database Setup
+
+This guide covers setting up a local SQLite database for your Prism Framework backend application using the `@facetlayer/sqlite-wrapper` library.
+
+## Directory Structure
+
+Set up the database as a backend "service" with its own folder inside the `./src` directory:
+
+```
+src/
+├── _main/
+│   └── index.ts
+├── user-database/
+│   └── db.ts
+└── other-services/
+    └── ...
+```
+
+## Installation
+
+Install the required packages:
+
+```bash
+pnpm add @facetlayer/sqlite-wrapper better-sqlite3
+pnpm add -D @types/better-sqlite3
+```
+
+## Database Configuration
+
+Create a database module at `src/user-database/db.ts`:
+
+```typescript
+import { DatabaseLoader, SqliteDatabase } from '@facetlayer/sqlite-wrapper';
+import { toConsoleLog } from '@facetlayer/streams';
+import BetterSqliteDatabase from 'better-sqlite3';
+import Path from 'path';
+
+let db: SqliteDatabase | null = null;
+
+const schema = {
+  name: 'MyAppDatabase',
+  statements: [
+    `create table users (
+      id integer primary key autoincrement,
+      email text not null unique,
+      created_at integer not null default (strftime('%s', 'now'))
+    )`,
+    `create index idx_users_email on users(email)`,
+  ]
+}
+
+export function getDatabase(): SqliteDatabase {
+  const DATABASE_DIR = process.env.DATABASE_DIR;
+  if (!DATABASE_DIR) {
+    throw new Error('DATABASE_DIR is not set');
+  }
+
+  if (!db) {
+    const loader = new DatabaseLoader({
+      filename: Path.join(DATABASE_DIR, 'app.db'),
+      loadDatabase: (filename) => new BetterSqliteDatabase(filename),
+      migrationBehavior: 'safe-upgrades',
+      schema,
+      logs: toConsoleLog('[database]'),
+    });
+
+    db = loader.load();
+  }
+  return db;
+}
+```
+
+## Environment Variable
+
+The `DATABASE_DIR` environment variable must be set to specify where the database file will be stored.
+
+For local development, create a `.env` file:
+
+```
+DATABASE_DIR=./data
+```
+
+Make sure the directory exists:
+
+```bash
+mkdir -p ./data
+```
+
+## Using the Database
+
+Import and use the database in your services:
+
+```typescript
+import { getDatabase } from '../user-database/db';
+
+export async function createUser(email: string) {
+  const db = getDatabase();
+  const stmt = db.prepare('INSERT INTO users (email) VALUES (?)');
+  const result = stmt.run(email);
+  return result.lastInsertRowid;
+}
+
+export async function getUserByEmail(email: string) {
+  const db = getDatabase();
+  const stmt = db.prepare('SELECT * FROM users WHERE email = ?');
+  return stmt.get(email);
+}
+```
+
+## Schema Migrations
+
+The `DatabaseLoader` handles schema migrations automatically with the `migrationBehavior` option:
+
+- `'safe-upgrades'` - Automatically applies safe migrations (adding tables, columns, indexes)
+- `'strict'` - Only creates schema on first run, no automatic migrations
+
+For complex migrations, add new statements to the `statements` array. The loader will apply them in order.
+
+## Multiple Databases
+
+If your application needs multiple databases, create separate modules with different schemas and filenames:
+
+```typescript
+// src/user-database/db.ts
+export function getUserDatabase(): SqliteDatabase { ... }
+
+// src/project-database/db.ts
+export function getProjectDatabase(): SqliteDatabase { ... }
+```

package/docs/endpoint-tools.md

@@ -43,8 +43,6 @@ Calls an endpoint on a running server.
 
 ### Basic Usage
 
-**Important:** Do not use the `/api` prefix in endpoint paths. Use the path directly as defined in the endpoint.
-
 ```bash
 # GET request
 prism call /users
@@ -101,15 +99,7 @@ Response: {"id":"123","name":"John","email":"john@example.com"}
 
 1. **Check the server is running** - Start your API server
 2. **Verify PRISM_API_PORT** - Ensure `.env` contains `PRISM_API_PORT` matching your server port
-3. **Check dotenv is loaded** - Your server must load the `.env` file:
-
-```typescript
-import { config } from 'dotenv';
-config({ path: '.env' });
-
-const PORT = parseInt(process.env.PRISM_API_PORT, 10);
-await startServer({ app, port: PORT });
-```
+3. **Check dotenv is loaded** - Your server must load the `.env` file (see `env-files` doc)
 
 ### "Endpoint not found"
 

package/docs/env-files.md

@@ -53,6 +53,17 @@ const apiUrl = import.meta.env.VITE_API_URL;
 
 See the `vite-setup` doc in `@facetlayer/prism-framework-ui` for more details.
 
+## Loading .env in the Backend
+
+Use `dotenv` to load your `.env` file early in your server entry point:
+
+```typescript
+import { config } from 'dotenv';
+config({ path: '.env' });
+```
+
+This should be called before accessing any `process.env` values. The `dotenv` package is included when you install `@facetlayer/prism-framework`'s recommended dependencies (see `getting-started` doc).
+
 # Port assignment
 
 It's recommended to use the `@facetlayer/port-assignment` tool if you need to assign new unique port numbers.
@@ -61,4 +72,4 @@ Example:
 
     npx @facetlayer/port-assignment claim --name <project name>
 
-Run `npx @facetlayer/port-assigment list-docs` for more documentation.
+Run `npx @facetlayer/port-assignment list-docs` for more documentation.

package/docs/error-handling.md

@@ -0,0 +1,70 @@
+---
+name: error-handling
+description: HTTP error classes for returning proper status codes from endpoint handlers
+---
+
+# Error Handling
+
+Prism Framework provides built-in HTTP error classes. Throw these from endpoint handlers or middleware to return the appropriate status code and error message.
+
+## Usage
+
+```typescript
+import { NotFoundError, BadRequestError } from '@facetlayer/prism-framework';
+
+handler: async (input) => {
+  if (!input.userId) {
+    throw new BadRequestError('User ID is required');
+  }
+
+  const user = await getUserById(input.userId);
+  if (!user) {
+    throw new NotFoundError('User not found');
+  }
+
+  return user;
+}
+```
+
+## Available Error Classes
+
+| Class | Status Code |
+|-------|-------------|
+| `BadRequestError` | 400 |
+| `UnauthorizedError` | 401 |
+| `ForbiddenError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `ValidationError` | 422 |
+| `NotImplementedError` | 501 |
+| `ServiceUnavailableError` | 503 |
+| `HttpError` | Custom status code |
+
+## Custom Status Codes
+
+Use `HttpError` for status codes not covered by the named classes:
+
+```typescript
+import { HttpError } from '@facetlayer/prism-framework';
+
+throw new HttpError(429, 'Too many requests');
+```
+
+## Authorization Errors
+
+For authorization-related errors, use `UnauthorizedError` (not logged in) and `ForbiddenError` (logged in but not allowed):
+
+```typescript
+import { UnauthorizedError, ForbiddenError } from '@facetlayer/prism-framework';
+
+const user = context.auth.getResource('user');
+if (!user) {
+  throw new UnauthorizedError('Authentication required');
+}
+
+if (!context.auth.hasPermission('delete:projects')) {
+  throw new ForbiddenError('Insufficient permissions');
+}
+```
+
+See the `authorization` doc for more on how auth and permissions work.

package/docs/getting-started.md

@@ -12,14 +12,11 @@ description: Guide for setting up a new Prism Framework project with type-safe A
 This includes the following NPM libraries:
 
 ### `@facetlayer/prism-framework`
- - Base library with tooling for various development and testing tasks
- - Should be installed at the top level in the devDependencies section
- - First place to look for documentation (`prism list-docs`)
-
-### `@facetlayer/prism-framework-api`
- - Backend API framework
- - Can be hosted on HTTP with Express.js
+ - Base library with backend API framework, CLI tooling, and development tools
+ - Includes the server framework (Express.js), endpoint definitions, authorization, and more
  - Also supports other launch methods such as IPC for Electron
+ - Should be installed at the top level
+ - First place to look for documentation (`prism list-docs`)
 
 ### `@facetlayer/prism-framework-ui`
  - Helpers for React-based frontend web apps
@@ -41,7 +38,7 @@ Some ways to set up the repo for a Prism project:
 ### Option 1: API in separate directory
 
  - `./api` - Backend API
-   - `./api/package.json` - Contains prism-framework-api
+   - `./api/package.json` - Contains prism-framework
    - `./api/src/` - Backend service implementation
  - `./web` or `./ui` - Frontend web app
    - `./web/package.json` - Contains Next.js or Vite, and prism-framework-ui
@@ -49,7 +46,7 @@ Some ways to set up the repo for a Prism project:
 
 ### Option 2: API in top level directory
 
- - `./package.json` - Contains prism-framework-api
+ - `./package.json` - Contains prism-framework
  - `./src` - Backend API source code
  - `./web` or `./ui` - Frontend web app
    - `./web/package.json` - Contains Next.js or Vite, and prism-framework-ui
@@ -69,7 +66,20 @@ Some ways to set up the repo for a Prism project:
 
 The top level of the project should have these dependencies:
 
-    `pnpm add typescript dotenv @facetlayer/prism-framework`
+    `pnpm add typescript dotenv @facetlayer/prism-framework zod@^4`
+
+## Environment setup
+
+Create a `.env` file next to your backend code with at minimum:
+
+    PRISM_API_PORT=<port number>
+    DATABASE_DIR=data
+
+Use `@facetlayer/port-assignment` to claim a unique port for your project:
+
+    npx @facetlayer/port-assignment claim --name <project name>
+
+See the `env-files` doc (`prism get-doc env-files`) for the full list of recommended environment variables for both backend and frontend.
 
 ## Local service management
 
@@ -81,6 +91,6 @@ Examples:
    `candle list-docs`
 
  Set up services in the .candle.json file:
-   `candle add-service api "node --watch src/_main/api.ts" --root ./api
-   `candle add-service web "pnpm dev" --root ./web
+   `candle add-service api "node --watch src/_main/api.ts" --root ./api`
+   `candle add-service web "pnpm dev" --root ./web`