@terreno/api 0.0.18 → 0.1.0

package/.github/copilot-instructions.md

@@ -0,0 +1,333 @@
+# 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`)
+- **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp-server`)
+- **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
+bun run mcp:build        # Build MCP server
+bun run mcp:start        # Start MCP server
+```
+
+## 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";
+```
+
+#### modelRouter Usage
+
+```typescript
+import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
+
+const router = modelRouter(YourModel, {
+  permissions: {
+    list: [Permissions.IsAuthenticated],
+    create: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+    delete: [],  // Disabled
+  },
+  sort: "-created",
+  queryFields: ["_id", "type", "name"],
+});
+```
+
+#### Custom Routes
+
+For non-CRUD endpoints, use the OpenAPI builder:
+
+```typescript
+import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
+
+router.get("/yourRoute/:id", [
+  authenticateMiddleware(),
+  createOpenApiBuilder(options)
+    .withTags(["yourTag"])
+    .withSummary("Brief summary")
+    .withPathParameter("id", {type: "string"})
+    .withResponse(200, {data: {type: "object"}})
+    .build(),
+], asyncHandler(async (req, res) => {
+  return res.json({data: result});
+}));
+```
+
+#### API Conventions
+
+- Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
+- Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
+- Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
+- All model types live in `src/modelInterfaces.ts`
+- In routes: `req.user` is `UserDocument | undefined`
+- In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
+
+### @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";
+```
+
+#### UI Component Examples
+
+Layout with Box:
+```typescript
+<Box direction="row" padding={4} gap={2} alignItems="center">
+  <Text>Content</Text>
+  <Button text="Action" />
+</Box>
+```
+
+Buttons:
+```typescript
+<Button
+  text="Submit"
+  variant="primary"  // 'primary' | 'secondary' | 'outline' | 'ghost'
+  onClick={handleSubmit}
+  loading={isLoading}
+  iconName="check"
+/>
+```
+
+Forms:
+```typescript
+<TextField
+  label="Email"
+  value={email}
+  onChangeText={setEmail}
+  error={emailError}
+  helperText="Enter a valid email"
+/>
+```
+
+Modals:
+```typescript
+<Modal
+  title="Confirm Action"
+  visible={isVisible}
+  primaryButtonText="Confirm"
+  secondaryButtonText="Cancel"
+  onDismiss={() => setIsVisible(false)}
+  onPrimaryAction={handleConfirm}
+>
+  <Text>Are you sure?</Text>
+</Modal>
+```
+
+#### UI Common Pitfalls
+
+- Don't use inline styles when theme values are available
+- Don't use raw `View`/`Text` when `Box`/@terreno/ui `Text` are available
+- Don't forget loading and error states
+- Don't use `style` prop when equivalent props exist (`padding`, `margin`)
+- Never modify `openApiSdk.ts` manually
+
+### @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";
+```
+
+Always use generated SDK hooks - never use `axios` or `request` directly:
+
+```typescript
+// Correct
+import {useGetYourRouteQuery} from "@/store/openApiSdk";
+const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
+
+// Wrong - don't use axios directly
+// const result = await axios.get("/api/yourRoute/value");
+```
+
+## React Best Practices (Frontend Packages)
+
+- Use functional components with `React.FC` type
+- Import hooks directly: `import {useEffect, useMemo} from 'react'`
+- Always provide return types for functions
+- Add explanatory comment above each `useEffect`
+- Wrap callbacks in `useCallback`
+- Prefer const arrow functions
+- Use inline styles over `StyleSheet.create`
+- Use Luxon for date operations
+- Place static content and interfaces at beginning of file
+- Minimize `use client`, `useEffect`, and `setState`
+- Always support React-Native Web
+
+## 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.

package/AGENTS.md

@@ -7,13 +7,14 @@ A monorepo containing shared packages for building full-stack applications with
 - **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`)
+- **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp-server`)
 - **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. Use `yarn` commands, not `npm`.
+Uses [Bun](https://bun.sh/) as the package manager.
 
 ```bash
 bun install              # Install dependencies
@@ -31,6 +32,8 @@ 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
+bun run mcp:build        # Build MCP server
+bun run mcp:start        # Start MCP server
 ```
 
 ## How the Packages Work Together
@@ -68,10 +71,10 @@ The three core packages form a complete full-stack framework:
 
 ## Example Apps (Keep These Updated!)
 
-The `frontend-example/` and `backend-example/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
+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 frontend-example && bun run sdk`
+2. **Update SDK** after backend changes: `cd example-frontend && bun run sdk`
 3. **Verify integration** by running both examples together
 
 ### Running the Full Stack
@@ -308,6 +311,23 @@ const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
 - Minimize `use client`, `useEffect`, and `setState`
 - Always support React-Native Web
 
+## 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.

package/README.md

@@ -9,6 +9,14 @@ These APIs integrate with @terreno/rtk to create consistent types on the fronten
 and backend, and automatically generated React hooks to fetch, query, and modify
 model instances.
 
+## Features
+
+- **modelRouter** — Automatic CRUD endpoints for Mongoose models
+- **Authentication** — JWT with email/password and GitHub OAuth support
+- **Permissions** — Fine-grained access control (IsAuthenticated, IsOwner, IsAdmin, etc.)
+- **OpenAPI** — Automatic spec generation from models and routes
+- **Logging** — Winston-based logging with Google Cloud and Sentry support
+
 ## Getting started
 
 To install:
@@ -46,12 +54,25 @@ const eventSchema = new Schema({
 Assuming we have a model:
 
     const foodSchema = new Schema<Food>({
-      name: String,
-      hidden: {type: Boolean, default: false},
-      ownerId: {type: "ObjectId", ref: "User"},
+      name: {
+        description: "Name of the food item",
+        type: String,
+      },
+      hidden: {
+        description: "Whether the food is hidden from the list",
+        type: Boolean,
+        default: false,
+      },
+      ownerId: {
+        description: "The user who added this food",
+        type: "ObjectId",
+        ref: "User",
+      },
     });
     export const FoodModel = model("Food", foodSchema);
 
+**Important:** Every field must include a `description` property. This requirement ensures that the auto-generated OpenAPI specification and SDK have meaningful documentation for all fields.
+
 We can expose this model as an API like this:
 
     import express from "express";
@@ -99,6 +120,55 @@ Now we can perform operations on the Food model in a standard REST way. We've al
 
 You can create your own permissions functions. Check permissions.ts for some examples of how to write them.
 
+## Authentication
+
+@terreno/api includes built-in authentication with JWT and OAuth support.
+
+### Email/Password Authentication
+
+Built-in email/password authentication using `passport-local-mongoose`:
+
+```typescript
+import {setupServer} from "@terreno/api";
+import {User} from "./models/user";
+
+setupServer({
+  userModel: User,
+  addRoutes: (router) => {
+    // Your routes here
+  },
+});
+```
+
+This automatically adds:
+- `POST /auth/signup` — User registration
+- `POST /auth/login` — Authentication
+- `POST /auth/refresh_token` — Token refresh
+- `GET /auth/me` — Get current user
+- `PATCH /auth/me` — Update current user
+
+### GitHub OAuth
+
+Add GitHub OAuth login to your API:
+
+```typescript
+import {githubUserPlugin, setupServer} from "@terreno/api";
+
+// Add GitHub fields to user schema
+userSchema.plugin(githubUserPlugin);
+
+setupServer({
+  userModel: User,
+  githubAuth: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    callbackURL: process.env.GITHUB_CALLBACK_URL!,
+  },
+});
+```
+
+**Learn more:** See the [GitHub OAuth how-to guide](../docs/how-to/add-github-oauth.md) for complete setup instructions.
+
 ## Sentry
 To enable Sentry, create a "src/sentryInstrumment.ts" file in your project.
 

package/dist/api.d.ts

@@ -1,6 +1,7 @@
 import express, { type NextFunction, type Request, type Response } from "express";
 import mongoose, { type Document, type Model } from "mongoose";
 import { type User } from "./auth";
+import { type ModelRouterValidationOptions } from "./openApiValidator";
 import { type RESTPermissions } from "./permissions";
 import type { PopulatePath } from "./populate";
 import { type TerrenoTransformer } from "./transformers";
@@ -203,6 +204,19 @@ export interface ModelRouterOptions<T> {
      * that you want to be documented and typed in the SDK.
      */
     openApiExtraModelProperties?: any;
+    /**
+     * Enable runtime validation of request bodies against the OpenAPI schema.
+     * When enabled, requests that don't match the documented schema will return 400 errors.
+     *
+     * Can be set to:
+     * - `true`: Enable validation for create and update operations
+     * - `false`: Disable validation (default)
+     * - Object with `validateCreate` and `validateUpdate` booleans for fine-grained control
+     *
+     * Note: Global validation can be enabled via `configureOpenApiValidator()`.
+     * This option overrides the global setting for this specific router.
+     */
+    validation?: boolean | ModelRouterValidationOptions;
 }
 /**
  * Create a set of CRUD routes given a Mongoose model and configuration options.
@@ -211,6 +225,59 @@ export interface ModelRouterOptions<T> {
  * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
  */
 export declare function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router;
-export declare const asyncHandler: (fn: any) => (req: Request, res: Response, next: NextFunction) => Promise<any>;
+/**
+ * Options for the asyncHandler function.
+ */
+export interface AsyncHandlerOptions {
+    /**
+     * Schema for validating request body.
+     * When provided and validation is enabled, the request body will be validated
+     * against this schema before the handler runs.
+     */
+    bodySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+    /**
+     * Schema for validating query parameters.
+     * When provided and validation is enabled, query params will be validated
+     * against this schema before the handler runs.
+     */
+    querySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+    /**
+     * Override global validation setting for this handler.
+     * - `true`: Enable validation regardless of global setting
+     * - `false`: Disable validation regardless of global setting
+     * - `undefined`: Use global setting
+     */
+    validate?: boolean;
+}
+/**
+ * Wraps async route handlers to properly catch and forward errors.
+ *
+ * Since Express doesn't handle async routes well, wrap them with this function.
+ * Optionally supports integrated request validation.
+ *
+ * @param fn - The async route handler function
+ * @param options - Optional configuration for validation
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage without validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code
+ * }));
+ *
+ * // With integrated validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code - body is already validated
+ * }, {
+ *   bodySchema: {
+ *     name: {type: "string", required: true},
+ *     email: {type: "string", format: "email", required: true},
+ *   },
+ *   validate: true,
+ * }));
+ * ```
+ */
+export declare const asyncHandler: (fn: any, options?: AsyncHandlerOptions) => (req: Request, res: Response, next: NextFunction) => void;
 export declare const gooseRestRouter: typeof modelRouter;
 export type GooseRESTOptions<T> = ModelRouterOptions<T>;