@terreno/api 0.1.0 → 0.2.0

package/src/terrenoApp.ts

@@ -0,0 +1,347 @@
+import * as Sentry from "@sentry/bun";
+import openapi from "@wesleytodd/openapi";
+import cors from "cors";
+import express from "express";
+import qs from "qs";
+
+import type {ModelRouterRegistration} from "./api";
+import {addAuthRoutes, addMeRoutes, setupAuth, type UserModel as UserMongooseModel} from "./auth";
+import {apiErrorMiddleware, apiUnauthorizedMiddleware} from "./errors";
+import {type AuthOptions, logRequests} from "./expressServer";
+import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
+import {type LoggingOptions, logger, setupLogging} from "./logger";
+import {openApiEtagMiddleware} from "./openApiEtag";
+import type {TerrenoPlugin} from "./terrenoPlugin";
+
+type CorsOrigin =
+  | string
+  | boolean
+  | RegExp
+  | Array<boolean | string | RegExp>
+  | ((
+      requestOrigin: string | undefined,
+      callback: (
+        err: Error | null,
+        origin?: boolean | string | RegExp | Array<boolean | string | RegExp>
+      ) => void
+    ) => void);
+
+/**
+ * Configuration options for TerrenoApp.
+ */
+export interface TerrenoAppOptions {
+  /** Mongoose User model with passport-local-mongoose plugin */
+  userModel: UserMongooseModel;
+  /** CORS origin configuration (default: "*") */
+  corsOrigin?: CorsOrigin;
+  /** Logging configuration options */
+  loggingOptions?: LoggingOptions;
+  /** Authentication configuration options */
+  authOptions?: AuthOptions;
+  /** GitHub OAuth configuration (enables GitHub authentication if provided) */
+  githubAuth?: GitHubAuthOptions;
+  /** Skip calling app.listen() in start() method (useful for testing) */
+  skipListen?: boolean;
+  /** Sentry configuration options */
+  sentryOptions?: Sentry.BunOptions;
+  /** Maximum number of array items in query parameters (default: 200) */
+  arrayLimit?: number;
+  /** Whether to log all incoming requests (default: true) */
+  logRequests?: boolean;
+}
+
+/**
+ * Fluent API for building Express applications with Terreno framework.
+ *
+ * TerrenoApp provides an alternative to `setupServer` using a registration
+ * pattern instead of callbacks. Build applications by registering model
+ * routers and plugins, then calling `start()` to begin listening.
+ *
+ * The middleware stack is configured in this order:
+ * 1. CORS
+ * 2. Custom middleware (via addMiddleware)
+ * 3. JSON body parser
+ * 4. Auth routes (/auth/login, /auth/signup, etc.)
+ * 5. JWT authentication setup
+ * 6. Request logging
+ * 7. Sentry scopes
+ * 8. OpenAPI middleware
+ * 9. /auth/me routes
+ * 10. GitHub OAuth routes (if enabled)
+ * 11. Registered model routers and plugins
+ * 12. Error handling middleware
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with model routers
+ * const todoRouter = modelRouter("/todos", Todo, {
+ *   permissions: { list: [Permissions.IsAuthenticated], ... },
+ * });
+ *
+ * const app = new TerrenoApp({ userModel: User })
+ *   .register(todoRouter)
+ *   .register(new HealthApp())
+ *   .start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom middleware
+ * const app = new TerrenoApp({
+ *   userModel: User,
+ *   corsOrigin: ["https://app.example.com"],
+ *   loggingOptions: { logRequests: true },
+ *   githubAuth: {
+ *     clientId: process.env.GITHUB_CLIENT_ID!,
+ *     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     callbackURL: process.env.GITHUB_CALLBACK_URL!,
+ *   },
+ * })
+ *   .addMiddleware((req, res, next) => {
+ *     res.setHeader("X-Custom-Header", "value");
+ *     next();
+ *   })
+ *   .register(todoRouter)
+ *   .register(userRouter)
+ *   .start();
+ * ```
+ *
+ * @see setupServer for the callback-based alternative
+ * @see TerrenoPlugin for creating reusable plugins
+ * @see modelRouter for creating CRUD route registrations
+ */
+export class TerrenoApp {
+  private options: TerrenoAppOptions;
+  private registrations: (ModelRouterRegistration | TerrenoPlugin)[] = [];
+  private middlewareFns: (express.RequestHandler | ((app: express.Application) => void))[] = [];
+
+  /**
+   * Create a new TerrenoApp builder.
+   *
+   * @param options - Application configuration options including user model and auth settings
+   */
+  constructor(options: TerrenoAppOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Register a model router or plugin with the application.
+   *
+   * Model routers are created with `modelRouter("/path", Model, options)` and
+   * provide CRUD endpoints. Plugins implement `TerrenoPlugin` interface and
+   * can register custom routes and middleware.
+   *
+   * Registrations are mounted in the order they are added.
+   *
+   * @param registration - A ModelRouterRegistration from modelRouter() or a TerrenoPlugin instance
+   * @returns This TerrenoApp instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * const todoRouter = modelRouter("/todos", Todo, options);
+   * const healthPlugin = new HealthApp({ path: "/health" });
+   *
+   * app.register(todoRouter).register(healthPlugin);
+   * ```
+   */
+  register(registration: ModelRouterRegistration | TerrenoPlugin): this {
+    this.registrations.push(registration);
+    return this;
+  }
+
+  /**
+   * Add custom Express middleware to the application.
+   *
+   * Middleware is added BEFORE JSON body parsing and authentication setup,
+   * allowing you to modify incoming requests early in the middleware stack.
+   *
+   * @param fn - Express middleware function or a function that configures the app
+   * @returns This TerrenoApp instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * app.addMiddleware((req, res, next) => {
+   *   res.setHeader("X-Request-ID", req.id);
+   *   next();
+   * });
+   * ```
+   */
+  addMiddleware(fn: express.RequestHandler | ((app: express.Application) => void)): this {
+    this.middlewareFns.push(fn);
+    return this;
+  }
+
+  /**
+   * Build the Express application without starting the server.
+   *
+   * Configures the complete middleware stack including:
+   * - CORS, JSON parsing, authentication, logging, Sentry, OpenAPI
+   * - All registered model routers and plugins
+   * - Error handling middleware
+   *
+   * Use this method when you need the Express app instance for testing
+   * or custom server setup. For normal use, call `start()` instead.
+   *
+   * @returns Configured Express application instance
+   *
+   * @example
+   * ```typescript
+   * const app = new TerrenoApp({ userModel: User })
+   *   .register(todoRouter)
+   *   .build();
+   *
+   * // Use app for testing with supertest
+   * await request(app).get("/todos").expect(200);
+   * ```
+   */
+  build(): express.Application {
+    setupLogging(this.options.loggingOptions);
+
+    const app = express();
+    const options = this.options;
+
+    app.set("query parser", (str: string) =>
+      qs.parse(str, {arrayLimit: options.arrayLimit ?? 200})
+    );
+
+    app.use(cors({origin: options.corsOrigin ?? "*"}));
+
+    // Apply custom middleware before JSON parsing
+    for (const fn of this.middlewareFns) {
+      if (fn.length <= 3) {
+        // express.RequestHandler (req, res, next)
+        app.use(fn as express.RequestHandler);
+      } else {
+        // Function that receives the app
+        (fn as (app: express.Application) => void)(app);
+      }
+    }
+
+    app.use(express.json());
+
+    // Auth routes (login/signup/refresh_token) before JWT middleware
+    addAuthRoutes(app, options.userModel as any, options.authOptions);
+    setupAuth(app as any, options.userModel as any);
+
+    if (options.logRequests !== false) {
+      app.use(logRequests);
+    }
+
+    // Store logging options on the response locals
+    app.use((_req, res, next) => {
+      res.locals.loggingOptions = options.loggingOptions;
+      next();
+    });
+
+    // Sentry scopes
+    app.all("*", (req: any, _res: any, next: any) => {
+      const transactionId = req.header("X-Transaction-ID");
+      const sessionId = req.header("X-Session-ID");
+      if (transactionId) {
+        Sentry.getCurrentScope().setTag("transaction_id", transactionId);
+      }
+      if (sessionId) {
+        Sentry.getCurrentScope().setTag("session_id", sessionId);
+      }
+      if (req.user?._id) {
+        Sentry.getCurrentScope().setTag("user", req.user._id);
+      }
+      next();
+    });
+
+    // OpenAPI
+    app.use(openApiEtagMiddleware);
+    const oapi = openapi({
+      info: {
+        description: "Generated docs from an Express api",
+        title: "Express Application",
+        version: "1.0.0",
+      },
+      openapi: "3.0.0",
+    });
+    app.use(oapi);
+
+    if (process.env.ENABLE_SWAGGER === "true") {
+      app.use("/swagger", oapi.swaggerui());
+    }
+
+    addMeRoutes(app, options.userModel as any, options.authOptions);
+
+    // GitHub OAuth
+    if (options.githubAuth) {
+      setupGitHubAuth(app, options.userModel as any, options.githubAuth);
+      addGitHubAuthRoutes(app, options.userModel as any, options.githubAuth, options.authOptions);
+    }
+
+    // Mount registered model routers and plugins
+    for (const registration of this.registrations) {
+      if (this.isModelRouterRegistration(registration)) {
+        app.use(registration.path, registration.router);
+      } else {
+        registration.register(app);
+      }
+    }
+
+    // Inject openApi into model router options for registered routers
+    // The openApi middleware handles this via the oapi instance already mounted on the app
+
+    Sentry.setupExpressErrorHandler(app);
+
+    // Error middleware
+    app.use(apiUnauthorizedMiddleware);
+    app.use(apiErrorMiddleware);
+
+    app.use(function onError(err: any, _req: any, res: any, _next: any) {
+      logger.error(`Fallthrough error: ${err}${err?.stack ? `\n${err.stack}` : ""}}`);
+      Sentry.captureException(err);
+      res.statusCode = 500;
+      res.end(`${res.sentry}\n`);
+    });
+
+    return app;
+  }
+
+  /**
+   * Build the Express application and start listening on the configured port.
+   *
+   * Calls `build()` to configure the application, then starts an HTTP server
+   * listening on the port specified by the `PORT` environment variable (default: 9000).
+   * If `skipListen` option is true, the app is built but the server is not started.
+   *
+   * @returns Configured Express application instance
+   *
+   * @throws Process exits with code 1 if the server fails to start
+   *
+   * @example
+   * ```typescript
+   * // Start server on port 3000
+   * process.env.PORT = "3000";
+   * const app = new TerrenoApp({ userModel: User })
+   *   .register(todoRouter)
+   *   .start();
+   * ```
+   */
+  start(): express.Application {
+    const app = this.build();
+
+    if (!this.options.skipListen) {
+      const port = process.env.PORT || "9000";
+      try {
+        app.listen(port, () => {
+          logger.info(`Listening on port ${port}`);
+        });
+      } catch (error) {
+        logger.error(`Error trying to start HTTP server: ${error}\n${(error as any).stack}`);
+        process.exit(1);
+      }
+    }
+
+    return app;
+  }
+
+  private isModelRouterRegistration(
+    registration: ModelRouterRegistration | TerrenoPlugin
+  ): registration is ModelRouterRegistration {
+    return (registration as ModelRouterRegistration).__type === "modelRouter";
+  }
+}

package/src/terrenoPlugin.ts

@@ -1,5 +1,39 @@
 import type express from "express";
 
+/**
+ * Interface for plugins that can be registered with TerrenoApp.
+ *
+ * Implement this interface to create reusable plugins that encapsulate
+ * routes, middleware, or other Express application setup. Plugins are
+ * registered via `TerrenoApp.register()` and are mounted after core
+ * authentication and OpenAPI middleware.
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin implements TerrenoPlugin {
+ *   register(app: express.Application): void {
+ *     app.get("/my-route", (req, res) => {
+ *       res.json({ status: "ok" });
+ *     });
+ *   }
+ * }
+ *
+ * const app = new TerrenoApp({ userModel: User })
+ *   .register(new MyPlugin())
+ *   .start();
+ * ```
+ *
+ * @see TerrenoApp for the application builder that consumes plugins
+ * @see HealthApp for a built-in plugin example
+ */
 export interface TerrenoPlugin {
+  /**
+   * Register routes and middleware with the Express application.
+   *
+   * Called during `TerrenoApp.build()` after core middleware has been
+   * configured but before error handling middleware is added.
+   *
+   * @param app - The Express application instance to register with
+   */
   register(app: express.Application): void;
 }

package/.claude/CLAUDE.local.md

@@ -1,204 +0,0 @@
-# Terreno
-
-A monorepo containing shared packages for building full-stack applications with React Native and Express/Mongoose.
-
-## Packages
-
-- **api/** - REST API framework built on Express/Mongoose (`@terreno/api`)
-- **ui/** - React Native UI component library (`@terreno/ui`)
-- **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
-- **demo/** - Demo app for showcasing and testing UI components
-- **example-frontend/** - Example Expo app demonstrating full stack usage
-- **example-backend/** - Example Express backend using @terreno/api
-
-## Development
-
-Uses [Bun](https://bun.sh/) as the package manager.
-
-```bash
-bun install              # Install dependencies
-bun run compile          # Compile all packages
-bun run lint             # Lint all packages
-bun run lint:fix         # Fix lint issues
-bun run test             # Run tests in api and ui
-```
-
-### Package-specific commands
-
-```bash
-bun run api:test         # Test API package
-bun run ui:test          # Test UI package
-bun run demo:start       # Start demo app
-bun run frontend:web     # Start frontend example
-bun run backend:dev      # Start backend example
-```
-
-## How the Packages Work Together
-
-The three core packages form a complete full-stack framework:
-
-```
-                           BACKEND
-  @terreno/api
-  - Mongoose models with modelRouter -> CRUD endpoints
-  - Built-in auth (JWT + Passport)
-  - Automatic OpenAPI spec generation
-                              |
-                     /openapi.json
-                              |
-                    RTK Query SDK Codegen
-                              |
-                           FRONTEND
-  @terreno/rtk
-  - Generated hooks from OpenAPI spec
-  - Auth slice with JWT token management
-  - Automatic token refresh
-                              +
-  @terreno/ui
-  - React Native components (Box, Button, TextField, etc.)
-  - TerrenoProvider for theming
-```
-
-### Integration Flow
-
-1. **Backend (api)**: Define Mongoose models, use `modelRouter` to create CRUD endpoints with permissions
-2. **OpenAPI Generation**: `setupServer` automatically generates `/openapi.json`
-3. **SDK Codegen**: Frontend runs `bun run sdk` to generate RTK Query hooks from OpenAPI spec
-4. **Frontend (rtk + ui)**: Use generated hooks with UI components for type-safe API calls
-
-## Example Apps (Keep These Updated!)
-
-The `example-frontend/` and `example-backend/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
-
-1. **Add examples** demonstrating new features
-2. **Update SDK** after backend changes: `cd example-frontend && bun run sdk`
-3. **Verify integration** by running both examples together
-
-### Running the Full Stack
-
-```bash
-# Terminal 1: Start backend
-bun run backend:dev
-
-# Terminal 2: Start frontend
-bun run frontend:web
-```
-
-## Code Style
-
-### TypeScript/JavaScript
-- Use ES module syntax and TypeScript for all code
-- Prefer interfaces over types; avoid enums, use maps
-- Prefer const arrow functions over `function` keyword
-- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`)
-- Use camelCase directories (e.g., `components/authWizard`)
-- Favor named exports
-- Use the RORO pattern (Receive an Object, Return an Object)
-
-### Dates and Time
-- Always use Luxon instead of Date or dayjs
-
-### Error Handling
-- Check error conditions at start of functions and return early
-- Limit nested if statements
-- Use multiline syntax with curly braces for all conditionals
-
-### Testing
-- Use bun test with expect for testing
-
-### Logging
-- Frontend: Use `console.info`, `console.debug`, `console.warn`, or `console.error` for permanent logs
-- Backend: Use `logger.info/warn/error/debug` for permanent logs
-- Use `console.log` only for debugging (to be removed)
-
-### Development Practices
-- Don't apologize for errors: fix them
-- Prioritize modularity, DRY, performance, and security
-- Focus on readability over performance
-- Write complete, functional code without TODOs when possible
-- Comments should describe purpose, not effect
-
-## Package Reference
-
-### @terreno/api
-
-REST API framework providing:
-
-- **modelRouter**: Auto-generates CRUD endpoints for Mongoose models
-- **Permissions**: `IsAuthenticated`, `IsOwner`, `IsAdmin`, `IsAuthenticatedOrReadOnly`
-- **Query Filters**: `OwnerQueryFilter` for filtering list queries by owner
-- **setupServer**: Express server setup with auth, OpenAPI, and middleware
-- **APIError**: Standardized error handling
-- **logger**: Winston-based logging
-
-Key imports:
-```typescript
-import {
-  modelRouter,
-  setupServer,
-  Permissions,
-  OwnerQueryFilter,
-  APIError,
-  logger,
-  asyncHandler,
-  authenticateMiddleware,
-} from "@terreno/api";
-```
-
-### @terreno/ui
-
-React Native component library with 88+ components:
-
-- **Layout**: Box, Page, SplitPage, Card
-- **Forms**: TextField, SelectField, DateTimeField, CheckBox
-- **Display**: Text, Heading, Badge, DataTable
-- **Actions**: Button, IconButton, Link
-- **Feedback**: Spinner, Modal, Toast
-- **Theming**: TerrenoProvider, useTheme
-
-Key imports:
-```typescript
-import {
-  Box,
-  Button,
-  Card,
-  Page,
-  Text,
-  TextField,
-  TerrenoProvider,
-} from "@terreno/ui";
-```
-
-### @terreno/rtk
-
-Redux Toolkit Query integration:
-
-- **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
-- **emptyApi**: Base RTK Query API for code generation
-- **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
-
-Key imports:
-```typescript
-import {generateAuthSlice} from "@terreno/rtk";
-```
-
-## CI/CD Workflows
-
-### Required Secret Validation
-
-GitHub Actions workflows that use secrets or environment variables must validate all required variables are set before using them. Add a validation step early in the job that fails fast with a clear error message listing any missing variables.
-
-```yaml
-- name: Validate required secrets
-  run: |
-    missing=()
-    if [ -z "$VAR_NAME" ]; then missing+=("VAR_NAME"); fi
-    if [ ${#missing[@]} -ne 0 ]; then
-      echo "::error::Missing required secrets: ${missing[*]}"
-      exit 1
-    fi
-```
-
-## Dependency Management
-
-Uses [Bun Catalogs](https://bun.sh/docs/install/catalogs) - shared versions defined in root `package.json` under `catalog`. Reference with `catalog:` in workspace packages.