@terreno/mcp 0.22.2 → 0.23.1

package/src/docs/versioned/0.23.0/explanation/modular-api-design.md

@@ -0,0 +1,228 @@
+# Modular API Design
+
+**Status**: 🚧 Planned for v2.0.0
+
+## The Problem
+
+As Terreno has grown, the `setupServer()` function has become increasingly difficult to extend and customize. When setting up new backends, several pain points emerge:
+
+1. **Configuration scattered across environment variables and options** — Some settings come from env vars (tokens, secrets), others from the options object, making it unclear what needs to be configured
+
+2. **All-or-nothing middleware** — Built-in middleware (CORS, body parsing, auth) can't be disabled or customized without editing the framework code
+
+3. **Limited extensibility** — Adding features like an admin panel requires touching multiple places in the middleware stack, making installation instructions tedious and error-prone
+
+4. **No lifecycle hooks** — Can't inject custom logic at precise points in server initialization or request handling
+
+5. **Rigid architecture** — Hard to build modular "apps" (like Django apps) that can be installed with a single call
+
+## The Solution: TerrenoApp
+
+The new `TerrenoApp` class addresses these issues with a **fluent builder API** inspired by Django and modern Node.js frameworks:
+
+``````typescript
+const app = TerrenoApp.create({
+  auth: {
+    userModel: User,
+    token: {secret: process.env.TOKEN_SECRET!, issuer: "myapp"},
+  },
+  middleware: {
+    cors: {enabled: true, origin: ["https://myapp.com"]},
+    helmet: {enabled: true},
+    rateLimit: {enabled: true, max: 100},
+  },
+  health: {
+    enabled: true,
+    check: async () => ({healthy: true, uptime: process.uptime()}),
+  },
+})
+  .addModelRouter("/todos", Todo, {list: [IsAuthenticated]})
+  .addRoute("/webhooks", webhookRouter)
+  .enableWebSocket({path: "/ws"})
+  .start();
+``````
+
+### Key Improvements
+
+#### 1. Configuration over Environment Variables
+
+All settings are explicit options, not env vars. This makes configuration:
+- **Discoverable**: TypeScript autocomplete shows all available options
+- **Testable**: Easy to swap configurations between environments
+- **Documented**: JSDoc on each option explains its purpose
+
+Environment variables can still be used, but they're passed in explicitly:
+
+``````typescript
+auth: {
+  token: {
+    secret: process.env.TOKEN_SECRET!,  // Explicit, not implicit
+    issuer: process.env.TOKEN_ISSUER!,
+  },
+}
+``````
+
+#### 2. Toggleable Middleware
+
+Every piece of built-in middleware can be enabled, disabled, or customized:
+
+``````typescript
+middleware: {
+  cors: false,                    // Disable entirely
+  json: {limit: "10mb"},          // Customize
+  helmet: {enabled: true},        // Enable with defaults
+  rateLimit: {                    // Enable with custom config
+    windowMs: 15 * 60 * 1000,
+    max: 100,
+  },
+}
+``````
+
+#### 3. Comprehensive Hooks
+
+Hooks allow custom logic at every stage:
+
+``````typescript
+hooks: {
+  onAppCreated: (app) => {
+    // Just after Express app created
+  },
+  onAuthReady: (app) => {
+    // After auth middleware configured, before routes
+  },
+  onRoutesReady: (app) => {
+    // After all routes added, before error handlers
+  },
+  onReady: (app) => {
+    // App fully configured, before listening
+  },
+  onListening: (server, port) => {
+    // Server started
+  },
+  onRequest: (req, res) => {
+    // On every incoming request
+  },
+  onError: (error, req, res) => {
+    // On every error
+  },
+  onShutdown: async () => {
+    // On graceful shutdown
+  },
+}
+``````
+
+These hooks enable advanced use cases like:
+- Custom admin-only auth checks inserted after built-in auth
+- Request-level metrics and tracing
+- Cleanup tasks on shutdown (close DB connections, flush logs)
+
+#### 4. Fluent API
+
+Instead of a single large options object, configuration happens through chained method calls:
+
+``````typescript
+TerrenoApp.create({auth, middleware})
+  .addModelRouter("/users", User, permissions)
+  .addModelRouter("/posts", Post, permissions)
+  .addRoute("/webhooks", webhookRouter)
+  .addMiddleware(customMiddleware, {path: "/admin"})
+  .enableWebSocket({path: "/ws"})
+  .start();
+``````
+
+This is:
+- **More readable**: Each line is a clear intent
+- **More flexible**: Add routes and middleware in any order
+- **Easier to extend**: New methods can be added without breaking existing code
+
+#### 5. Foundation for Modular Apps
+
+The new architecture enables installable "apps" (like Django's app system):
+
+``````typescript
+import {adminApp} from "@terreno/admin";
+
+TerrenoApp.create({auth})
+  .install(adminApp({
+    models: [User, Post, Todo],
+    permissions: [IsAdmin],
+  }))
+  .start();
+``````
+
+This would be nearly impossible with `setupServer()` because installing an app requires:
+- Adding routes at a specific point in the stack
+- Registering middleware
+- Adding hooks for initialization
+- Merging OpenAPI specs
+
+With TerrenoApp, an "app" is just a function that receives the `TerrenoApp` instance and calls its methods.
+
+## Design Principles
+
+### 1. Explicit over Implicit
+
+Settings are passed in, not read from global state (env vars). This makes dependencies clear and testing easier.
+
+### 2. Composable over Monolithic
+
+Features are added via method calls, not configured via a mega-options object. This allows fine-grained control.
+
+### 3. Progressive Disclosure
+
+Simple cases are simple:
+
+``````typescript
+TerrenoApp.create({auth: {userModel: User, token: {...}}})
+  .addModelRouter("/todos", Todo, {list: [IsAuthenticated]})
+  .start();
+``````
+
+Complex cases are possible:
+
+``````typescript
+TerrenoApp.create({auth, middleware, health, logging, hooks})
+  .addModelRouter("/todos", Todo, {...})
+  .addRoute("/webhooks", webhookRouter, {openapi: {...}})
+  .addMiddleware(customMiddleware, {position: "afterAuth"})
+  .addErrorHandlingMiddleware(sentryErrorHandler)
+  .enableWebSocket({path: "/ws", authenticate, onConnection, onMessage})
+  .start();
+``````
+
+### 4. Backward Compatibility (Initially)
+
+The implementation plan originally aimed for backward compatibility with `setupServer()`, but the final design makes this a **breaking change**. This is intentional:
+
+- Allows cleaner architecture without maintaining two code paths
+- Forces migration to better patterns
+- Provides opportunity to fix long-standing API warts
+
+Migration will be supported with:
+- Detailed migration guide
+- Deprecation warnings in v2.0.0-beta
+- `setupServer()` available but deprecated in v2.0.0
+- Removal in v3.0.0, giving users time to migrate
+
+## Implementation Status
+
+**Current**: Planning phase (implementation plan merged)
+
+**Next steps**:
+1. ✅ Write implementation plan
+2. ✅ Gather community feedback
+3. 🚧 Implement core TerrenoApp class with tests
+4. 🚧 Update example-backend to demonstrate new API
+5. 🚧 Write migration guide with real examples
+6. 🚧 Publish v2.0.0-beta for testing
+7. 🚧 Address feedback and publish v2.0.0
+
+## Learn More
+
+- 📖 [Implementation plan](../implementationPlans/ModularAPI.md) — Full technical specification
+- 💬 [GitHub PR #149](https://github.com/FlourishHealth/terreno/pull/149) — Discussion and feedback
+
+## Related
+
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Authentication architecture](authentication.md) — How JWT and OAuth work in Terreno

package/src/docs/versioned/0.23.0/how-to/README.md

@@ -0,0 +1,20 @@
+# How-to Guides
+
+Problem-oriented, practical steps. Use these when you know what you want to do.
+
+## Contents
+
+- [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
+- [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
+
+## Coming Soon
+
+- [Add feature flags](add-feature-flags.md) — Add feature flags and A/B testing to your app
+- Add custom permissions
+- Implement file uploads
+- Configure email notifications
+- Customize AI workflows
+- Set up custom CI/CD pipelines

package/src/docs/versioned/0.23.0/how-to/add-feature-flags.md

@@ -0,0 +1,115 @@
+# Add Feature Flags
+
+Add feature flags and A/B testing to your Terreno app using `@terreno/feature-flags`.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- `@terreno/admin-backend` registered for the admin panel (optional but recommended)
+
+## Steps
+
+### 1. Install the package
+
+```bash
+bun add @terreno/feature-flags
+```
+
+### 2. Register the backend plugin
+
+In your server file, register `FeatureFlagsApp` and add the admin config:
+
+```typescript
+import {TerrenoApp} from "@terreno/api";
+import {AdminApp} from "@terreno/admin-backend";
+import {FeatureFlagsApp, featureFlagAdminConfig} from "@terreno/feature-flags";
+
+// Define segment functions to classify users for targeting rules
+const segments = {
+  "pro-users": (user) => user.plan === "pro",
+  "beta-testers": (user) => user.betaTester === true,
+  "internal-team": (user) => user.email?.endsWith("@mycompany.com"),
+};
+
+new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp({segments}))
+  .register(
+    new AdminApp({
+      models: [
+        featureFlagAdminConfig,  // adds Feature Flags to the admin panel
+        // ...your other models
+      ],
+    })
+  )
+  .start();
+```
+
+`featureFlagAdminConfig` is a pre-configured admin model config exported by the package. It sets up the display name, list fields, route path, and model reference so you don't need to configure them manually.
+
+### 3. Regenerate the frontend SDK
+
+After adding the backend routes, regenerate the SDK so the frontend can call the new endpoints (with the example backend running, or set `OPENAPI_URL` to your deployed `openapi.json`):
+
+```bash
+cd your-frontend && bun run sdk
+```
+
+Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/rtk` so OpenFeature domain, cache keying, and optional socket refetch stay consistent.
+
+### 4. Use feature flags in the frontend
+
+**Recommended (OpenFeature):** add `@openfeature/react-sdk` to the app, wrap the tree (or the subtree that reads flags) in `<OpenFeatureProvider domain="feature-flags">`, and call `useTerrenoFeatureFlags(terrenoApi, {userId, socket})` once after auth so the OpenFeature client receives `GET /feature-flags/flagConfiguration`. Then use standard hooks such as `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
+
+**Back-compat:** `useFeatureFlags(terrenoApi)` from `@terreno/rtk` still returns `{flags, getFlag, getVariant, isLoading, …}` with the same semantics as before; it uses `/flagConfiguration` under the hood. You do not need to call a generated RTK hook for `/flagConfiguration` directly.
+
+```typescript
+import {useBooleanFlagValue} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags, useSelectCurrentUserId} from "@terreno/rtk";
+import {terrenoApi} from "@/store/sdk";
+
+const GatedBanner: React.FC = () => {
+  const userId = useSelectCurrentUserId();
+  useTerrenoFeatureFlags(terrenoApi, {userId, skip: !userId});
+  const showBanner = useBooleanFlagValue("new-ui", false);
+  return showBanner ? <NewUI /> : null;
+};
+```
+
+```typescript
+import {useFeatureFlags} from "@terreno/rtk";
+import {terrenoApi} from "@/store/sdk";
+
+const LegacyStyle: React.FC = () => {
+  const {getFlag, isLoading} = useFeatureFlags(terrenoApi);
+
+  if (isLoading) {
+    return <Spinner />;
+  }
+
+  const showNewUI = getFlag("new-ui");
+
+  return showNewUI ? <NewUI /> : <OldUI />;
+};
+```
+
+### 4b. Live updates (optional)
+
+To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
+
+On the client, pass the same Socket.io **client** into `useTerrenoFeatureFlags` / `useFeatureFlags` as `socket`; the hook listens for `featureFlagsChanged` (or `socketEventName`) and refetches `/flagConfiguration`. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
+
+### 5. Create flags via the admin panel
+
+Navigate to the admin panel in your app. The "Feature Flags" card appears automatically. Create a flag with:
+
+- **Key**: unique identifier, e.g. `new-ui`
+- **Name**: human-readable label
+- **Type**: `boolean` for on/off toggles, `variant` for A/B tests
+- **Enabled**: global kill switch
+- **Rules**: optional targeting (field-based or segment-based)
+- **Rollout Percentage**: gradual rollout for boolean flags (default 100%)
+
+## Next steps
+
+- See the [reference docs](../reference/feature-flags.md) for the full API, targeting rules, and variant flags
+- See `example-backend/src/server.ts` for a complete working example

package/src/docs/versioned/0.23.0/how-to/add-github-oauth.md

@@ -0,0 +1,316 @@
+# Add GitHub OAuth Authentication
+
+Add GitHub OAuth login to your @terreno/api backend. Users can authenticate with their GitHub account, and optionally link GitHub to existing password-based accounts.
+
+## Prerequisites
+
+- Existing @terreno/api backend with `setupServer()` configured
+- User model with authentication set up
+- GitHub OAuth application (see [Creating a GitHub OAuth App](#creating-a-github-oauth-app))
+
+## Step 1: Install Dependencies
+
+GitHub OAuth support uses `passport-github2`, which is already included as a dependency in @terreno/api.
+
+## Step 2: Add GitHub Fields to User Model
+
+Apply the `githubUserPlugin` to your user schema to add GitHub authentication fields:
+
+``````typescript
+import {githubUserPlugin} from "@terreno/api";
+import mongoose from "mongoose";
+
+const userSchema = new mongoose.Schema({
+  email: {
+    description: "User's email address",
+    type: String,
+    unique: true,
+    required: true,
+  },
+  name: {
+    description: "User's display name",
+    type: String,
+  },
+  admin: {
+    description: "Whether the user has admin privileges",
+    type: Boolean,
+    default: false,
+  },
+});
+
+// Add GitHub authentication fields
+userSchema.plugin(githubUserPlugin);
+
+export const User = mongoose.model("User", userSchema);
+``````
+
+The plugin adds these fields:
+- `githubId` — GitHub user ID (unique, indexed)
+- `githubUsername` — GitHub username
+- `githubProfileUrl` — GitHub profile URL
+- `githubAvatarUrl` — GitHub avatar image URL
+
+## Step 3: Configure GitHub OAuth
+
+Add GitHub authentication configuration to your `setupServer()` call:
+
+``````typescript
+import {setupServer} from "@terreno/api";
+import {User} from "./models/user";
+
+setupServer({
+  userModel: User,
+  addRoutes: (router, options) => {
+    // Your route setup
+  },
+  githubAuth: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    callbackURL: process.env.GITHUB_CALLBACK_URL || "http://localhost:4000/auth/github/callback",
+    scope: ["user:email"], // Optional, defaults to ["user:email"]
+    allowAccountLinking: true, // Optional, defaults to true
+  },
+});
+``````
+
+### Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `clientId` | string | Yes | GitHub OAuth Client ID |
+| `clientSecret` | string | Yes | GitHub OAuth Client Secret |
+| `callbackURL` | string | Yes | OAuth callback URL (must match GitHub app settings) |
+| `scope` | string[] | No | OAuth scopes (default: `["user:email"]`) |
+| `allowAccountLinking` | boolean | No | Allow linking GitHub to existing accounts (default: `true`) |
+| `findOrCreateUser` | function | No | Custom user creation/lookup handler |
+
+## Step 4: Set Environment Variables
+
+Add these to your `.env` file:
+
+``````bash
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+GITHUB_CALLBACK_URL=http://localhost:4000/auth/github/callback
+``````
+
+**Important:** Never commit secrets to version control. Use different values for development, staging, and production.
+
+## Step 5: Test the Integration
+
+The following routes are automatically added when `githubAuth` is configured:
+
+### Login with GitHub
+
+``````http
+GET /auth/github
+``````
+
+Redirects users to GitHub for authentication. Optional query parameter:
+- `returnTo` — URL to redirect after successful authentication (tokens will be appended as query params)
+
+### OAuth Callback
+
+``````http
+GET /auth/github/callback
+``````
+
+Handles the GitHub OAuth callback. Returns JSON with tokens:
+
+``````json
+{
+  "data": {
+    "token": "eyJhbGc...",
+    "refreshToken": "eyJhbGc...",
+    "userId": "507f1f77bcf86cd799439011"
+  }
+}
+``````
+
+### Link GitHub Account (Requires Auth)
+
+``````http
+GET /auth/github/link
+Authorization: Bearer <jwt-token>
+``````
+
+Links GitHub to the authenticated user's existing account. Redirects to GitHub, then back to callback.
+
+### Unlink GitHub Account (Requires Auth)
+
+``````http
+DELETE /auth/github/unlink
+Authorization: Bearer <jwt-token>
+``````
+
+Removes GitHub authentication from the user's account. Returns:
+
+``````json
+{
+  "data": {
+    "message": "GitHub account unlinked successfully"
+  }
+}
+``````
+
+**Note:** Users must have a password set before unlinking GitHub.
+
+## Authentication Flow
+
+### New User Registration
+
+1. User clicks "Sign in with GitHub"
+2. Frontend redirects to `GET /auth/github?returnTo=<frontend-url>`
+3. User authorizes on GitHub
+4. Backend receives callback, creates new user with GitHub profile data
+5. Backend generates JWT tokens
+6. Backend redirects to `returnTo` URL with tokens in query params
+7. Frontend stores tokens and logs user in
+
+### Existing User Login
+
+If a user with the same GitHub ID already exists, they are logged in automatically.
+
+### Account Linking
+
+1. User logs in with email/password
+2. User clicks "Link GitHub Account"
+3. Frontend makes authenticated request to `GET /auth/github/link`
+4. User authorizes on GitHub
+5. Backend links GitHub ID to existing user account
+6. User can now log in with either method
+
+## Custom User Creation
+
+For advanced use cases, provide a custom `findOrCreateUser` function:
+
+``````typescript
+setupServer({
+  githubAuth: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    callbackURL: process.env.GITHUB_CALLBACK_URL!,
+    findOrCreateUser: async (profile, accessToken, refreshToken, existingUser) => {
+      // Custom logic for finding or creating users
+      // - profile: GitHub profile data
+      // - accessToken: GitHub access token
+      // - refreshToken: GitHub refresh token (if available)
+      // - existingUser: If user is authenticated, their user document
+      
+      if (existingUser) {
+        // Link GitHub to existing user
+        existingUser.githubId = profile.id;
+        existingUser.githubUsername = profile.username;
+        await existingUser.save();
+        return existingUser;
+      }
+      
+      // Find or create user based on GitHub ID or email
+      let user = await User.findOne({githubId: profile.id});
+      if (!user && profile.emails?.[0]?.value) {
+        user = await User.findOne({email: profile.emails[0].value});
+      }
+      
+      if (!user) {
+        user = await User.create({
+          githubId: profile.id,
+          githubUsername: profile.username,
+          email: profile.emails?.[0]?.value,
+          name: profile.displayName,
+        });
+      }
+      
+      return user;
+    },
+  },
+});
+``````
+
+## Frontend Integration
+
+### React Native / Expo
+
+Use `expo-auth-session` for OAuth flow:
+
+``````typescript
+import * as AuthSession from "expo-auth-session";
+
+const redirectUri = AuthSession.makeRedirectUri();
+
+const handleGitHubLogin = async () => {
+  const result = await AuthSession.startAsync({
+    authUrl: `https://api.yourapp.com/auth/github?returnTo=${redirectUri}`,
+  });
+  
+  if (result.type === "success") {
+    const {token, refreshToken, userId} = result.params;
+    // Store tokens and log in user
+  }
+};
+``````
+
+### Web
+
+Simple redirect flow:
+
+``````typescript
+const handleGitHubLogin = () => {
+  window.location.href = `https://api.yourapp.com/auth/github?returnTo=${window.location.origin}/auth/callback`;
+};
+
+// On callback page (/auth/callback)
+const urlParams = new URLSearchParams(window.location.search);
+const token = urlParams.get("token");
+const refreshToken = urlParams.get("refreshToken");
+const userId = urlParams.get("userId");
+// Store tokens and redirect to app
+``````
+
+## Creating a GitHub OAuth App
+
+1. Go to GitHub Settings → Developer settings → OAuth Apps
+2. Click "New OAuth App"
+3. Fill in:
+   - **Application name**: Your App Name
+   - **Homepage URL**: `http://localhost:4000` (dev) or your production URL
+   - **Authorization callback URL**: `http://localhost:4000/auth/github/callback`
+4. Click "Register application"
+5. Copy the Client ID
+6. Generate a new Client Secret and copy it
+7. Add both to your `.env` file
+
+**Production:** Create a separate OAuth app for production with your production callback URL.
+
+## Security Considerations
+
+- **Never expose client secrets** — They should only exist on the backend
+- **Use HTTPS in production** — GitHub OAuth requires HTTPS for production callbacks
+- **Validate redirect URLs** — Only allow trusted domains in `returnTo` parameters
+- **Scope minimization** — Only request GitHub scopes your app actually needs
+- **Token storage** — Store tokens securely on the frontend (SecureStore on mobile, httpOnly cookies on web)
+
+## Troubleshooting
+
+### "GitHub authentication failed"
+
+- Verify `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are correct
+- Check that callback URL in GitHub app settings matches `GITHUB_CALLBACK_URL`
+- Ensure user grants all requested permissions
+
+### "This GitHub account is already linked to another user"
+
+A different user has already linked this GitHub account. Users must unlink it first or use a different GitHub account.
+
+### "Account linking is disabled"
+
+Set `allowAccountLinking: true` in `githubAuth` configuration.
+
+### Tokens not included in callback
+
+If using `returnTo`, tokens are appended as query parameters. Check that your frontend is reading them correctly.
+
+## Learn More
+
+- [Authentication architecture](../explanation/authentication.md)
+- [API reference](../reference/api.md)
+- [GitHub OAuth documentation](https://docs.github.com/en/developers/apps/building-oauth-apps)