@terreno/mcp 57.1.0 → 57.2.0

package/src/docs/versioned/0.27.0/reference/api.md

@@ -1,1276 +0,0 @@
-# @terreno/api
-
-REST API framework built on Express and Mongoose. Provides modelRouter (CRUD endpoints), JWT auth, permissions, and OpenAPI generation.
-
-## Table of Contents
-
-- [Server Setup](#server-setup)
-- [Authentication](#authentication)
-- [Model Schema Conventions](#model-schema-conventions)
-- [Mongoose Plugins](#mongoose-plugins)
-- [Request Validation](#request-validation)
-- [Middleware](#middleware)
-- [Logging & Tracing](#logging--tracing)
-- [Extensibility](#extensibility)
-- [Webhooks & Notifications](#webhooks--notifications)
-- [HTTP Client](#http-client)
-- [Utilities](#utilities)
-- [Script Helpers](#script-helpers)
-
-## Key exports
-
-- `TerrenoApp`, `setupServer`, `modelRouter`, `Permissions`, `OwnerQueryFilter`
-- `APIError`, `logger`, `asyncHandler`, `authenticateMiddleware`
-- Logging: `logger`, `createScopedLogger`, `createFeatureFlaggedLogger`, `setupLogging`, `formatLogContextSuffix`
-- Correlation: `runWithRequestContext`, `getCurrentLogContext`, `requestContextMiddleware`, `REQUEST_CONTEXT_ATTRIBUTE_NAMES`
-- `createOpenApiBuilder`
-- `githubUserPlugin`, `setupGitHubAuth`, `addGitHubAuthRoutes`
-- Mongoose plugins: `findExactlyOne`, `findOneOrNone`, `upsertPlugin`, `DateOnly`
-- Validation: `configureOpenApiValidator`, `validateRequestBody`, `validateQueryParams`, `createValidator`
-- Middleware: `openApiEtagMiddleware`, `sentryAppVersionMiddleware`
-- Extensibility: `TerrenoPlugin` interface
-- Notifiers: `sendSlackMessage`, `sendGoogleChatMessage`, `sendZoomMessage`
-- HTTP client: `createAuthenticatedClient`, `withApiErrorHandling`, `normalizeApiError`, `markRetryUnsafe`
-
-## Server Setup
-
-Two patterns for building Terreno APIs:
-
-### TerrenoApp (Recommended)
-
-Fluent API with a register pattern:
-
-``````typescript
-import {TerrenoApp, modelRouter} from "@terreno/api";
-import {User, Todo} from "./models";
-
-const todoRouter = modelRouter("/todos", Todo, {
-  permissions: {
-    list: [Permissions.IsAuthenticated],
-    create: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-    delete: [Permissions.IsOwner],
-  },
-  queryFilter: OwnerQueryFilter,
-});
-
-const app = new TerrenoApp({userModel: User})
-  .register(todoRouter)
-  .register(userRouter)
-  .start();
-``````
-
-**Methods:**
-- `register(registration)` — Register `ModelRouterRegistration` or `TerrenoPlugin`
-- `addMiddleware(fn)` — Add Express middleware
-- `build()` — Build Express app without listening
-- `start()` — Build and start server
-
-### setupServer (Legacy)
-
-Callback-based pattern:
-
-``````typescript
-import {setupServer, modelRouter} from "@terreno/api";
-
-setupServer({
-  userModel: User,
-  addRoutes: (router) => {
-    router.use("/todos", modelRouter(Todo, options));
-  },
-});
-``````
-
-Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI).
-
-## Authentication
-
-@terreno/api includes built-in authentication with multiple strategies:
-
-### Email/Password Authentication
-
-JWT-based authentication using `passport-local-mongoose`:
-
-``````typescript
-import {setupServer} from "@terreno/api";
-
-setupServer({
-  userModel: User,
-  authOptions: {
-    generateJWTPayload: (user) => ({
-      sub: user._id,
-      admin: user.admin,
-    }),
-  },
-});
-``````
-
-**Endpoints:**
-- `POST /auth/signup` — Create user account
-- `POST /auth/login` — Authenticate with email/password
-- `POST /auth/refresh_token` — Refresh access token
-- `GET /auth/me` — Get current user profile
-- `PATCH /auth/me` — Update current user profile
-
-**Environment variables:**
-- `TOKEN_SECRET` — JWT signing secret (required)
-- `TOKEN_ISSUER` — JWT issuer claim (required)
-- `REFRESH_TOKEN_SECRET` — Refresh token secret (required)
-- `SESSION_SECRET` — Express session secret (required)
-- `TOKEN_EXPIRES_IN` — Token expiration (default: `15m`)
-- `REFRESH_TOKEN_EXPIRES_IN` — Refresh token expiration (default: `30d`)
-- `SIGNUP_DISABLED` — Set to `"true"` to disable user signup endpoint
-
-### GitHub OAuth Authentication
-
-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!,
-    scope: ["user:email"],
-    allowAccountLinking: true,
-  },
-});
-``````
-
-**Endpoints (when configured):**
-- `GET /auth/github` — Initiate OAuth flow
-- `GET /auth/github/callback` — OAuth callback handler
-- `GET /auth/github/link` — Link GitHub to authenticated user (requires JWT)
-- `DELETE /auth/github/unlink` — Unlink GitHub from account (requires JWT)
-
-**Learn more:** [Add GitHub OAuth authentication](../how-to/add-github-oauth.md)
-
-### Better Auth Authentication
-
-Add Better Auth as an alternative authentication system with built-in social OAuth:
-
-``````typescript
-import {BetterAuthApp, TerrenoApp} from "@terreno/api";
-
-const betterAuthConfig = {
-  enabled: true,
-  secret: process.env.BETTER_AUTH_SECRET,
-  baseURL: process.env.BETTER_AUTH_URL,
-  trustedOrigins: ["yourapp://", "exp://"],
-  googleOAuth: {
-    clientId: process.env.GOOGLE_CLIENT_ID!,
-    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-  },
-  githubOAuth: {
-    clientId: process.env.GITHUB_CLIENT_ID!,
-    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-  },
-};
-
-const app = new TerrenoApp({userModel: User});
-app.register(new BetterAuthApp({config: betterAuthConfig, userModel: User}));
-const server = app.start();
-``````
-
-**Endpoints (when enabled):**
-- `POST /api/auth/signup/email` — Email/password signup
-- `POST /api/auth/signin/email` — Email/password signin
-- `GET /api/auth/signin/{provider}` — Initiate OAuth (google, github, apple)
-- `GET /api/auth/callback/{provider}` — OAuth callback
-- `POST /api/auth/signout` — Sign out
-- `GET /api/auth/session` — Get session
-
-**Environment variables:**
-- `AUTH_PROVIDER` — Set to `"better-auth"` to enable (default: `"jwt"`)
-- `BETTER_AUTH_SECRET` — Session encryption secret (required)
-- `BETTER_AUTH_URL` — Base URL for auth server (required)
-- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` — Google OAuth (optional)
-- `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` — GitHub OAuth (optional)
-- `APPLE_CLIENT_ID` / `APPLE_CLIENT_SECRET` — Apple Sign In (optional)
-
-**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
-
-## Model Schema Conventions
-
-### Required field descriptions
-
-**Every field in a Mongoose schema must include a `description` property.** Descriptions are extracted by `mongoose-to-swagger` and included in the generated OpenAPI specification, making your API documentation and auto-generated SDK significantly more useful.
-
-``````typescript
-const schema = new mongoose.Schema<Document, Model>({
-  title: {
-    description: "The title of the item",
-    type: String,
-    required: true,
-  },
-  status: {
-    description: "Current processing status",
-    type: String,
-    enum: ["pending", "active", "completed"],
-    default: "pending",
-  },
-  ownerId: {
-    description: "The user who owns this item",
-    type: mongoose.Schema.Types.ObjectId,
-    ref: "User",
-    required: true,
-  },
-});
-``````
-
-### Writing good descriptions
-
-- Keep them concise (one sentence is usually enough)
-- Explain the field's purpose, not its type
-- Use active voice: "The user who owns..." not "Owner of..."
-- Include important constraints: "Email address (must be unique)"
-
-### Benefits
-
-Field descriptions appear in:
-- OpenAPI spec at `/openapi.json`
-- Generated SDK type definitions
-- API documentation (Swagger UI if enabled)
-- IDE autocomplete hints when using the SDK
-
-## Mongoose Plugins
-
-@terreno/api provides several Mongoose plugins to extend model functionality with common patterns.
-
-### findExactlyOne & findOneOrNone
-
-**Critical:** Never use `Model.findOne` directly. Use these plugins instead to prevent ambiguous queries.
-
-``````typescript
-import {findExactlyOne, findOneOrNone} from "@terreno/api";
-
-// In your schema
-todoSchema.plugin(findExactlyOne);
-todoSchema.plugin(findOneOrNone);
-
-// Usage
-const todo = await Todo.findExactlyOne({_id: id}); // Throws if 0 or multiple found
-const maybeUser = await User.findOneOrNone({email}); // Returns null if none, throws if multiple
-``````
-
-**Why these matter:**
-- `findOne()` returns a **random document** if multiple match (non-deterministic)
-- `findExactlyOne()` throws `APIError` (404) if none found, (500) if multiple found
-- `findOneOrNone()` returns `null` if none found, throws (500) if multiple found
-
-### upsertPlugin
-
-Create or update a document atomically.
-
-``````typescript
-import {upsertPlugin, type HasUpsert} from "@terreno/api";
-
-todoSchema.plugin(upsertPlugin);
-
-// TypeScript: Extend your model interface
-interface TodoModel extends DefaultModel<TodoDocument>, HasUpsert<TodoDocument> {}
-
-// Usage
-const todo = await Todo.upsert(
-  {userId: user._id, taskId: task.id}, // Conditions
-  {status: "completed", completedAt: new Date()} // Update
-);
-// Creates new if none exists, updates if found, throws if multiple match
-``````
-
-### DateOnly Schema Type
-
-Custom Mongoose type for date-only fields (no time component).
-
-``````typescript
-import {Schema} from "mongoose";
-import {DateOnly} from "@terreno/api";
-
-// IMPORTANT: Register early in your app entry point (before models are loaded)
-(Schema.Types as any).DateOnly = DateOnly;
-
-// Then use in schemas
-const eventSchema = new Schema({
-  eventDate: {
-    type: Schema.Types.DateOnly,
-    description: "Date of the event (no time component)",
-  },
-});
-
-// Automatically strips time when setting or fetching
-event.eventDate = new Date("2026-02-15T14:30:00Z");
-console.log(event.eventDate); // 2026-02-15T00:00:00.000Z
-``````
-
-**Features:**
-- Automatically converts to UTC midnight
-- Supports comparison operators (`$gt`, `$gte`, `$lt`, `$lte`)
-- Throws `CastError` for invalid dates
-
-### createdUpdatedPlugin
-
-Adds `created` and `updated` timestamp fields with automatic management.
-
-``````typescript
-import {createdUpdatedPlugin} from "@terreno/api";
-
-schema.plugin(createdUpdatedPlugin);
-
-// Adds two fields:
-// - created: Date (set on first save)
-// - updated: Date (set on every save/update)
-
-// Disable for specific saves
-doc.disableCreatedUpdatedPlugin = true;
-await doc.save();
-``````
-
-### isDeletedPlugin
-
-Soft delete support with automatic query filtering.
-
-``````typescript
-import {isDeletedPlugin, type IsDeleted} from "@terreno/api";
-
-schema.plugin(isDeletedPlugin, false); // Default: not deleted
-
-// Adds:
-// - deleted: boolean (default: false)
-// - Automatic filtering in find() and findOne() queries
-
-// Normal queries exclude deleted docs
-const todos = await Todo.find({}); // Only non-deleted
-
-// Explicitly query deleted docs
-const deleted = await Todo.find({deleted: true});
-
-// Soft delete
-todo.deleted = true;
-await todo.save();
-``````
-
-### isDisabledPlugin
-
-Disable user accounts (returns 401 for disabled users).
-
-``````typescript
-import {isDisabledPlugin} from "@terreno/api";
-
-userSchema.plugin(isDisabledPlugin, false);
-
-// Adds disabled: boolean field
-user.disabled = true;
-await user.save();
-// User will receive 401 on authentication attempts
-``````
-
-### baseUserPlugin
-
-Base fields for user models.
-
-``````typescript
-import {baseUserPlugin, type BaseUser} from "@terreno/api";
-
-userSchema.plugin(baseUserPlugin);
-
-// Adds:
-// - email: string (indexed)
-// - admin: boolean (default: false)
-``````
-
-### firebaseJWTPlugin
-
-Firebase authentication integration.
-
-``````typescript
-import {firebaseJWTPlugin} from "@terreno/api";
-
-userSchema.plugin(firebaseJWTPlugin);
-
-// Adds:
-// - firebaseId: string (indexed)
-``````
-
-### Default Plugin Bundle
-
-Many schemas use these together:
-
-``````typescript
-import {createdUpdatedPlugin, isDeletedPlugin, findExactlyOne, findOneOrNone} from "@terreno/api";
-
-export const addDefaultPlugins = (schema) => {
-  schema.plugin(createdUpdatedPlugin);
-  schema.plugin(isDeletedPlugin);
-  schema.plugin(findExactlyOne);
-  schema.plugin(findOneOrNone);
-};
-
-// Apply to all schemas
-todoSchema.plugin(addDefaultPlugins);
-``````
-
-## Request Validation
-
-@terreno/api provides runtime validation of incoming requests against OpenAPI schemas using [AJV](https://ajv.js.org/). Validation is opt-in and can be enabled globally or per-route.
-
-### Enabling Validation
-
-Call `configureOpenApiValidator()` at server startup to enable validation:
-
-``````typescript
-import {configureOpenApiValidator, setupServer} from "@terreno/api";
-
-// Enable validation before setting up the server
-configureOpenApiValidator({
-  removeAdditional: true,
-  coerceTypes: true,
-  logValidationErrors: true,
-  onAdditionalPropertiesRemoved: (props, req) => {
-    logger.warn(`Stripped properties: ${props.join(", ")} on ${req.method} ${req.path}`);
-  },
-});
-
-setupServer({
-  userModel: User,
-  addRoutes: (router) => {
-    // Routes will automatically validate when enabled
-  },
-});
-``````
-
-**Configuration options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `validateRequests` | boolean | `true` | Enable request body validation |
-| `validateResponses` | boolean | `false` | Enable response validation (performance cost) |
-| `coerceTypes` | boolean | `true` | Convert types (e.g., `"123"` → `123`) |
-| `removeAdditional` | boolean | `true` | Strip properties not in schema |
-| `logValidationErrors` | boolean | `true` | Log validation failures |
-| `onValidationError` | function | throws APIError | Custom error handler |
-| `onAdditionalPropertiesRemoved` | function | undefined | Callback when props are stripped |
-
-### Using with modelRouter
-
-When validation is enabled globally, modelRouter automatically validates create and update requests:
-
-``````typescript
-import {modelRouter, Permissions} from "@terreno/api";
-
-router.use("/todos", modelRouter(Todo, {
-  permissions: {
-    create: [Permissions.IsAuthenticated],
-    update: [Permissions.IsOwner],
-  },
-  // Validation happens automatically based on Mongoose schema
-}));
-``````
-
-### Manual Validation
-
-For custom routes, use validation middleware directly:
-
-``````typescript
-import {validateRequestBody, validateQueryParams, createOpenApiBuilder} from "@terreno/api";
-
-router.post("/search", [
-  createOpenApiBuilder()
-    .withRequestBody({
-      query: {type: "string", required: true},
-      filters: {type: "object"},
-    })
-    .build(),
-  validateRequestBody({
-    query: {type: "string", required: true},
-    filters: {type: "object"},
-  }),
-  asyncHandler(async (req, res) => {
-    // req.body is validated and coerced
-    const {query, filters} = req.body;
-    return res.json({results: []});
-  }),
-]);
-``````
-
-### Validating Query Parameters
-
-``````typescript
-import {validateQueryParams} from "@terreno/api";
-
-router.get("/items", [
-  validateQueryParams({
-    limit: {type: "number"},
-    status: {type: "string", enum: ["active", "inactive"]},
-  }),
-  asyncHandler(async (req, res) => {
-    // req.query is validated and type-coerced
-    const {limit, status} = req.query;
-    return res.json({items: []});
-  }),
-]);
-``````
-
-### Combined Validation
-
-Validate both body and query in a single middleware:
-
-``````typescript
-import {createValidator} from "@terreno/api";
-
-router.post("/search", [
-  createValidator({
-    body: {query: {type: "string", required: true}},
-    query: {limit: {type: "number"}, page: {type: "number"}},
-  }),
-  asyncHandler(async (req, res) => {
-    // Both req.body and req.query are validated
-    return res.json({results: []});
-  }),
-]);
-``````
-
-### Model-based Validation
-
-Generate validators directly from Mongoose models:
-
-``````typescript
-import {validateModelRequestBody, getSchemaFromModel} from "@terreno/api";
-
-// Use model schema for validation
-router.post("/todos", [
-  authenticateMiddleware(),
-  validateModelRequestBody(Todo),
-  asyncHandler(async (req, res) => {
-    // req.body validated against Todo schema
-    const todo = await Todo.create(req.body);
-    return res.json({data: todo});
-  }),
-]);
-``````
-
-### Validation Behavior
-
-**When `removeAdditional: true`:**
-- Extra properties are silently removed from request body
-- `onAdditionalPropertiesRemoved` callback fires if configured
-- Useful for preventing client-side injection of unexpected fields
-
-**When `coerceTypes: true`:**
-- Query strings are converted to correct types (`"10"` → `10`)
-- Request body values are coerced when possible
-- Reduces type mismatch errors from URL parameters
-
-**Error response format:**
-``````json
-{
-  "errors": [{
-    "status": "400",
-    "title": "Request validation failed",
-    "detail": "/body/email: must be a valid email",
-    "source": {"pointer": "/body"},
-    "meta": {
-      "validationErrors": "[{\"path\":\"/email\",\"message\":\"must be a valid email\"}]"
-    }
-  }]
-}
-``````
-
-**Performance considerations:**
-- Validators are compiled once and cached
-- Minimal overhead after first request (~1-2ms for typical schemas)
-- Response validation is disabled by default due to performance cost
-- Use in development/staging to catch API contract violations
-
-**Learn more:** See `api/src/openApiValidator.ts` for advanced usage and `api/src/api.ts` for modelRouter integration.
-
-## Middleware
-
-### openApiEtagMiddleware
-
-Adds ETag support to the `/openapi.json` endpoint for efficient caching.
-
-``````typescript
-import {openApiEtagMiddleware} from "@terreno/api";
-
-// Add before OpenAPI middleware in setupServer
-app.use(openApiEtagMiddleware);
-``````
-
-**Features:**
-- Generates SHA-256 ETag from OpenAPI spec content
-- Returns `304 Not Modified` when spec hasn't changed
-- Reduces bandwidth for clients polling OpenAPI spec
-- Automatically included in `setupServer()`
-
-**Benefits:**
-- SDK code generation tools can skip regeneration if spec unchanged
-- Faster frontend builds in CI/CD pipelines
-- Reduced server load for large OpenAPI specs
-
-### sentryAppVersionMiddleware
-
-Captures app version from request headers and adds to Sentry scope for error filtering.
-
-``````typescript
-import {sentryAppVersionMiddleware} from "@terreno/api";
-
-app.use(sentryAppVersionMiddleware);
-``````
-
-**Expected header:** `App-Version: 1.2.3`
-
-**Sentry tag:** `app_version: 1.2.3`
-
-**Use case:** Filter Sentry errors by app version to identify version-specific bugs.
-
-## Logging & Tracing
-
-@terreno/api ships a Winston-based logger plus two helpers — **scoped loggers** and
-**feature-flagged loggers** — and automatic **request correlation** so a single request or
-background job can be followed across many log lines, both in plain-text consoles and in structured
-transports (Google Cloud Logging, Sentry).
-
-> Never use `console.log` for permanent server logs — use `logger` or a scoped logger. Request
-> logging already redacts `password` on bodies; never log secrets, full auth tokens, or raw
-> passwords.
-
-### Quick reference
-
-| Export | Purpose |
-|--------|---------|
-| `logger` | Global logger: `debug` / `info` / `warn` / `error` / `catch`. |
-| `createScopedLogger(options)` | Logger that prepends a `prefix` and/or attaches `labels` to every line. |
-| `createFeatureFlaggedLogger(options)` | Wraps a logger behind an `isEnabled()` gate (feature flags, env, etc.). |
-| `setupLogging(options)` | Configures transports and levels (console/file + custom transports). |
-| `formatLogContextSuffix(fields)` | Builds the trailing ` key=value` suffix (for custom formatters/tests). |
-| `runWithRequestContext(ctx, cb)` | Opens a correlation scope for jobs/scripts (HTTP gets one automatically). |
-| `getCurrentLogContext()` | Reads the active correlation fields as a plain object. |
-| `REQUEST_CONTEXT_ATTRIBUTE_NAMES` | Header names for propagating correlation to other services. |
-
-### The global logger
-
-``````typescript
-import {logger} from "@terreno/api";
-
-logger.info("Server started", {port: 4000});
-logger.warn("Slow query", {ms: 500});
-logger.error("Failed to process", {error});
-logger.debug("Request details", {body: req.body});
-
-// `.catch` logs and captures the exception — handy as a promise handler:
-await chargeCard(id).catch(logger.catch);
-``````
-
-Each method writes through Winston (console/file transports) and, when `USE_SENTRY_LOGGING=true`,
-mirrors the line to Sentry with the active request context attached.
-
-### Scoped loggers
-
-Use **`createScopedLogger`** when a handler, job, or service runs multiple steps and you want a
-consistent prefix and/or extra dimensions on every line. Create the logger once and reuse the same
-instance for the whole operation so every line shares identifiers.
-
-``````typescript
-import {createScopedLogger} from "@terreno/api";
-
-const log = createScopedLogger({
-  prefix: "[InvoicePay]",
-  labels: {invoiceId: invoice._id.toString(), attempt: String(attemptNumber)},
-});
-
-log.info("Starting capture");
-log.warn("Stripe rate limited, backing off");
-await capture(invoice).catch(log.catch);
-``````
-
-This produces lines like:
-
-``````text
-info: [InvoicePay] Starting capture invoiceId=665f… attempt=1 requestId=…
-``````
-
-- **`prefix`** — prepended to the human-readable message (easy grep / Log Explorer text search) and
-  also stored as the Winston metadata field **`terrenoLogPrefix`** so structured transports get it
-  as its own field, not only embedded in `message`.
-- **`labels`** — normalized to strings and stored as the Winston metadata field **`terrenoLabels`**.
-  They appear in the same ` key=value` suffix as request fields and are emitted as discrete fields
-  for structured transports (for example `@google-cloud/logging-winston`).
-
-**Reserved keys:** do not use label keys that collide with framework metadata — `requestId`,
-`jobId`, `sessionId`, `userId`, `traceId`, `spanId`, `terrenoLogPrefix`, `terrenoRequestLog`,
-`terrenoLabels`. Prefer domain names: `invoiceId`, `syncBatchId`, `webhookDeliveryId`.
-
-If both `prefix` and `labels` are empty, `createScopedLogger({})` returns the global `logger` (the
-same object).
-
-### Feature-flagged (toggle) logging
-
-Use **`createFeatureFlaggedLogger`** to keep verbose diagnostics in the code but silent until a
-flag turns them on — no redeploy required. All `debug` / `info` / `warn` / `error` calls are
-dropped while `isEnabled()` returns false.
-
-`isEnabled` is evaluated on **every** call, so flags can flip without a process restart. Wire it to
-any source: an environment variable, a cached/remote flag map, or a call into a feature-flag service
-from your app.
-
-``````typescript
-import {createFeatureFlaggedLogger, createScopedLogger} from "@terreno/api";
-
-const jobLog = createFeatureFlaggedLogger({
-  isEnabled: () => process.env.JOB_TRACE_LOGS === "true",
-  target: createScopedLogger({prefix: "[Job]", labels: {jobName: "nightly-sync"}}),
-});
-
-jobLog.info("step 1"); // silent unless JOB_TRACE_LOGS=true
-``````
-
-Driving it from a feature-flag service in app code:
-
-``````typescript
-const debugLog = createFeatureFlaggedLogger({
-  isEnabled: () => flags.isEnabled("debug.billing"),
-  target: createScopedLogger({prefix: "[Billing]"}),
-  gateCatch: true, // also silence `catch` while the flag is off
-});
-``````
-
-Options:
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `isEnabled` | — (required) | `() => boolean` predicate; checked on every log call. |
-| `target` | global `logger` | The `ScopedLogger` (or `logger`) that receives forwarded lines. |
-| `gateCatch` | `false` | When `false`, `catch` still records errors while disabled (so `promise.catch(log.catch)` keeps working). Set `true` to silence `catch` too. |
-
-> `@terreno/api` deliberately does **not** import a feature-flags package — you pass the predicate.
-> This avoids a package cycle and lets the gate read from anywhere.
-
-### How loggers correlate
-
-While a request or job scope is active, **every** log line — from `logger`, a scoped logger, or a
-feature-flagged logger — is automatically enriched with correlation fields. You never thread them
-through function arguments. This is built on Node's `AsyncLocalStorage` (see `requestContext.ts`).
-
-What you get:
-
-- **HTTP requests**: `requestContextMiddleware` (mounted early by `TerrenoApp` / `setupServer`)
-  resolves a `requestId` from incoming headers (`x-request-id`, `x-correlation-id`,
-  `x-cloud-trace-context`, W3C `traceparent`, …) or generates one, echoes it back as the
-  `X-Request-ID` response header, and runs the request inside the scope. After auth runs, `userId`
-  and `sessionId` are added.
-- **Correlation fields**: `requestId`, `jobId`, `sessionId`, `userId`, `traceId`, `spanId` (when
-  available) are merged onto every line as top-level Winston metadata.
-- **Structured object**: every line also carries **`terrenoRequestLog`**: `{requestId, userId}`
-  (with `userId: null` for anonymous requests) so Log Explorer and BigQuery can always filter on a
-  single nested object. This object is structured metadata only — it is not repeated in the
-  plain-text suffix.
-- **Plain-text suffix**: console/file lines append a ` key=value` suffix built by
-  `formatLogContextSuffix`, including `logPrefix=…` and any scoped `labels`.
-
-Correlating background jobs, cron tasks, and scripts — wrap the work in `runWithRequestContext` so
-it gets the same treatment as an HTTP request:
-
-``````typescript
-import {createScopedLogger, runWithRequestContext} from "@terreno/api";
-
-await runWithRequestContext({jobId: "nightly-sync"}, async () => {
-  const log = createScopedLogger({prefix: "[NightlySync]"});
-  log.info("started"); // every line includes jobId + a generated requestId
-  await sync();
-});
-``````
-
-Propagating correlation to other services (so the same `requestId` / `traceId` follows the call):
-
-``````typescript
-import {getCurrentRequestContextAttributes} from "@terreno/api";
-
-await fetch(downstreamUrl, {headers: getCurrentRequestContextAttributes()});
-``````
-
-### Configuring transports
-
-`setupLogging` is called for you by `TerrenoApp` / `setupServer` (pass `loggingOptions`). Console
-and file transports are enabled by default; add custom transports (such as Google Cloud Logging) to
-forward the structured metadata above:
-
-``````typescript
-import {setupLogging} from "@terreno/api";
-import {LoggingWinston} from "@google-cloud/logging-winston";
-
-setupLogging({
-  level: "info",
-  disableFileLogging: isDeployed,
-  disableConsoleColors: isDeployed,
-  transports: isDeployed ? [new LoggingWinston()] : [],
-});
-``````
-
-When deployed, Winston metadata (`terrenoRequestLog`, `terrenoLabels`, `terrenoLogPrefix`, and the
-top-level request fields) flows into Google Cloud Logging `jsonPayload` for Log Explorer filtering.
-To correlate with Cloud Trace, ensure clients or load balancers send `x-cloud-trace-context` or W3C
-`traceparent`.
-
-### Message style
-
-- Start with what happened, then optional detail: `User export finished`, not `finished`.
-- Use **low-cardinality** prefixes in brackets (`[WebhookStripe]`, `[NightlyJob]`); put unique IDs
-  in `labels`, not in the prefix.
-- Keep the first ~80 characters useful for grouping; push highly variable data to the end or into
-  splat args.
-
-## Extensibility
-
-### TerrenoPlugin Interface
-
-The `TerrenoPlugin` interface provides a standard way to extend Terreno applications with reusable functionality.
-
-``````typescript
-import type {TerrenoPlugin} from "@terreno/api";
-import type express from "express";
-
-export interface TerrenoPlugin {
-  register(app: express.Application): void;
-}
-``````
-
-**Creating a plugin:**
-
-``````typescript
-import type {TerrenoPlugin} from "@terreno/api";
-import type express from "express";
-
-export class MyPlugin implements TerrenoPlugin {
-  private options: MyPluginOptions;
-
-  constructor(options?: MyPluginOptions) {
-    this.options = options ?? {};
-  }
-
-  register(app: express.Application): void {
-    // Add routes, middleware, or other setup
-    app.get("/my-plugin/status", (_req, res) => {
-      res.json({status: "ok"});
-    });
-  }
-}
-``````
-
-**Using a plugin:**
-
-``````typescript
-import {setupServer} from "@terreno/api";
-import {MyPlugin} from "./plugins/myPlugin";
-
-const myPlugin = new MyPlugin({enabled: true});
-
-setupServer({
-  userModel: User,
-  addRoutes: (router) => {
-    // Register the plugin
-    myPlugin.register(router as any);
-  },
-});
-``````
-
-**Example: Health Check Plugin**
-
-See `@terreno/api-health` for a complete plugin implementation:
-
-``````typescript
-import {HealthApp} from "@terreno/api-health";
-
-const healthCheck = new HealthApp({
-  enabled: true,
-  path: "/health",
-  check: async () => {
-    const dbConnected = await checkDatabaseConnection();
-    return {
-      healthy: dbConnected,
-      details: {database: dbConnected ? "connected" : "disconnected"},
-    };
-  },
-});
-
-setupServer({
-  userModel: User,
-  addRoutes: (router) => {
-    healthCheck.register(router as any);
-  },
-});
-``````
-
-**Plugin patterns:**
-- **Conditional registration:** Check options to enable/disable functionality
-- **Route registration:** Add custom endpoints (health checks, admin panels, webhooks)
-- **Middleware injection:** Add request/response interceptors
-- **Service initialization:** Connect to external services (monitoring, analytics)
-
-**Benefits:**
-- Reusable across multiple Terreno projects
-- Testable in isolation
-- Optional/configurable functionality
-- Clean separation of concerns
-
-## Webhooks & Notifications
-
-### Slack Notifications
-
-``````typescript
-import {sendSlackMessage} from "@terreno/api";
-
-await sendSlackMessage({
-  webhookUrl: process.env.SLACK_WEBHOOK_URL,
-  message: "Deployment complete",
-  blocks: [
-    {
-      type: "section",
-      text: {type: "mrkdwn", text: "*Deployment Status*\nVersion 1.2.3 deployed successfully"},
-    },
-  ],
-});
-``````
-
-### Google Chat Notifications
-
-``````typescript
-import {sendGoogleChatMessage} from "@terreno/api";
-
-await sendGoogleChatMessage({
-  webhookUrl: process.env.GOOGLE_CHAT_WEBHOOK_URL,
-  message: "Build failed",
-  sections: [
-    {
-      header: "Build Status",
-      widgets: [{textParagraph: {text: "Branch: main\nStatus: Failed"}}],
-    },
-  ],
-});
-``````
-
-### Zoom Notifications
-
-``````typescript
-import {sendZoomMessage} from "@terreno/api";
-
-await sendZoomMessage({
-  webhookUrl: process.env.ZOOM_WEBHOOK_URL,
-  message: "Server health alert",
-});
-``````
-
-**Common use cases:**
-- CI/CD pipeline notifications
-- Error alerts
-- Deployment confirmations
-- Health check failures
-
-## HTTP Client
-
-Utilities for calling **external** third-party APIs with consistent auth, retry, and error handling. See the how-to guide: [Call external APIs](../how-to/call-external-apis.md).
-
-### createAuthenticatedClient
-
-Axios instance factory with a pluggable auth strategy, lazy token caching, and a retry policy for transient failures.
-
-``````typescript
-import {createAuthenticatedClient} from "@terreno/api";
-
-const client = createAuthenticatedClient({
-  apiName: "widgetService",
-  auth: {getToken: async () => fetchServiceToken(), type: "bearer"},
-  baseURL: "https://api.widgets.example/v2",
-  retry: {maxAttempts: 3}, // optional; shown with defaults below
-});
-
-const response = await client.axios.get("/widgets/123");
-client.invalidateToken(); // drop the cached token; next request re-authenticates
-``````
-
-**Auth strategies** (`auth` option):
-- `{type: "bearer", getToken}` — caller-supplied async token fetcher, cached until invalidated
-- `{type: "oauth2", tokenUrl, credentials, refreshOn401}` — client-credentials grant handled internally; `refreshOn401: true` refreshes and retries exactly once on a 401
-- `{type: "apiKey", header, getKey}` — key sent on the named header
-
-**Retry policy** (`retry` option, all fields optional):
-
-| Field | Default | Meaning |
-|---|---|---|
-| `maxAttempts` | `3` | Total attempts including the first request |
-| `retryOn` | `["rateLimited", "server", "network"]` | Failure classifications to retry |
-| `baseDelayMs` | `250` | Base for exponential backoff with jitter |
-| `maxDelayMs` | `30000` | Ceiling for any single delay, including `Retry-After` values |
-
-Only idempotent methods (GET/HEAD/OPTIONS) are retried by default. Opt a request in with `markRetryUnsafe(config?)` when the operation is safe to repeat and its body is replayable.
-
-**Why:** external integrations otherwise duplicate token plumbing and diverge on retry behavior; centralizing them makes rate-limit handling and credential rotation consistent, and makes non-idempotent retries an explicit, reviewable choice.
-
-### normalizeApiError
-
-Pure function converting any thrown value into a stable, log-safe shape.
-
-``````typescript
-import {normalizeApiError} from "@terreno/api";
-
-const normalized = normalizeApiError(error, {apiName: "widgetService", operation: "getWidget"});
-// {isAxios, statusCode, messages, classification, apiName, operation}
-``````
-
-`classification` is one of `"rateLimited" | "unauthorized" | "notFound" | "validation" | "server" | "network" | "unknown"`. Messages are extracted only from recognized body fields (`{message}`, JSONAPI `{errors: [{title, detail}]}`, plain strings truncated to 500 chars) — raw payload bodies never reach the normalized shape.
-
-### withApiErrorHandling
-
-Call-site wrapper: normalize → optional `redactError` hook → log exactly once → rethrow.
-
-``````typescript
-import {withApiErrorHandling} from "@terreno/api";
-
-const response = await withApiErrorHandling(() => client.axios.get(`/widgets/${id}`), {
-  apiName: "widgetService",
-  operation: "getWidget",
-  rethrowAs: "apiError", // optional; default "raw" rethrows the original error
-});
-``````
-
-With `rethrowAs: "apiError"` the failure is converted to a terreno `APIError` (stable title, per-occurrence `detail`, classification in `meta`) suitable for route handlers. Works with SDK-based integrations too — it does not require `createAuthenticatedClient`.
-
-## Utilities
-
-### checkModelsStrict
-
-Validates all registered Mongoose models use strict mode and virtual settings.
-
-``````typescript
-import {checkModelsStrict} from "@terreno/api";
-
-// Run in non-production environments at startup
-if (process.env.NODE_ENV !== "production") {
-  checkModelsStrict();
-}
-``````
-
-**Checks:**
-- `strict: "throw"` or `strict: true` (prevents accidental field additions)
-- `toJSON: {virtuals: true}` (includes virtual fields in JSON output)
-- `toObject: {virtuals: true}` (includes virtual fields in plain objects)
-
-**Throws:** Detailed error listing all non-compliant models
-
-**Why:** Prevents subtle bugs from schema misconfigurations that only appear in production.
-
-### isValidObjectId
-
-Better ObjectId validation than Mongoose's built-in validator.
-
-``````typescript
-import {isValidObjectId} from "@terreno/api";
-
-// Mongoose's isValidObjectId has false positives
-console.log(mongoose.isValidObjectId("123456789012")); // true (wrong!)
-
-// @terreno/api's version correctly validates
-console.log(isValidObjectId("123456789012")); // false (correct)
-console.log(isValidObjectId("507f1f77bcf86cd799439011")); // true
-``````
-
-**Fix:** Checks length is exactly 24 hex characters, not just 12+ characters.
-
-### timeout
-
-Promise-based timeout utility.
-
-``````typescript
-import {timeout} from "@terreno/api";
-
-// Wait 1 second
-await timeout(1000);
-
-// Use in retry logic
-for (let i = 0; i < 3; i++) {
-  try {
-    await someOperation();
-    break;
-  } catch (error) {
-    if (i < 2) await timeout(1000 * Math.pow(2, i)); // Exponential backoff
-  }
-}
-``````
-
-## Script Helpers
-
-### wrapScript
-
-Error handling wrapper for scripts and cron jobs.
-
-``````typescript
-import {wrapScript} from "@terreno/api";
-
-wrapScript(async () => {
-  // Your script logic
-  await processData();
-  console.log("Script completed successfully");
-});
-``````
-
-**Features:**
-- Catches and logs exceptions via `logger.catch()`
-- Sends errors to Sentry
-- Exits with code 1 on error, 0 on success
-- Ensures process doesn't hang on uncaught errors
-
-### cronjob
-
-Schedule recurring tasks with error handling.
-
-``````typescript
-import {cronjob} from "@terreno/api";
-
-// Run every hour
-cronjob("0 * * * *", async () => {
-  await cleanupOldData();
-}, {
-  name: "Cleanup Job",
-  runOnInit: false, // Run immediately on start?
-});
-``````
-
-**Features:**
-- Uses `node-cron` syntax
-- Automatic error logging
-- Named jobs for monitoring
-- Optional immediate execution
-
-**Cron syntax:** `"minute hour day month weekday"`
-- `"*/5 * * * *"` — Every 5 minutes
-- `"0 0 * * *"` — Daily at midnight
-- `"0 */6 * * *"` — Every 6 hours
-
-## Deprecations
-
-### transformer (modelRouter option)
-
-**Deprecated:** Use lifecycle hooks instead (`preCreate`, `postCreate`, etc.)
-
-``````typescript
-// Old (deprecated)
-modelRouter(Model, {
-  transformer: (doc) => ({...doc, computed: true}),
-});
-
-// New (use responseHandler)
-modelRouter(Model, {
-  responseHandler: (doc, method) => ({...doc, computed: true}),
-});
-``````
-
-### responseSerializer (modelRouter option)
-
-**Deprecated:** Use `responseHandler` instead.
-
-``````typescript
-// Old (deprecated)
-modelRouter(Model, {
-  responseSerializer: (doc) => serialize(doc),
-});
-
-// New
-modelRouter(Model, {
-  responseHandler: (doc, method) => serialize(doc),
-});
-``````
-
-## Environment Variables
-
-Complete reference of environment variables used by @terreno/api:
-
-### Authentication
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `TOKEN_SECRET` | Yes | — | JWT signing secret (use long random string) |
-| `TOKEN_ISSUER` | Yes | — | JWT issuer claim (e.g., "your-app-name") |
-| `REFRESH_TOKEN_SECRET` | Yes | — | Refresh token secret (different from TOKEN_SECRET) |
-| `SESSION_SECRET` | Yes | — | Express session secret |
-| `TOKEN_EXPIRES_IN` | No | `15m` | Access token expiration (e.g., "15m", "1h") |
-| `REFRESH_TOKEN_EXPIRES_IN` | No | `30d` | Refresh token expiration (e.g., "7d", "30d") |
-| `SIGNUP_DISABLED` | No | — | Set to `"true"` to disable POST /auth/signup endpoint |
-
-### Server Configuration
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `PORT` | No | `3000` | HTTP server port |
-| `NODE_ENV` | No | `development` | Environment: `development`, `production`, `test` |
-| `MONGO_URI` or `MONGO_CONNECTION` | Yes | — | MongoDB connection string |
-| `ENABLE_SWAGGER` | No | — | Set to `"true"` to enable Swagger UI at `/docs` |
-| `WEBSOCKET_PORT` | No | `PORT + 1` | Socket.io server port (if using WebSockets) |
-
-### Logging & Monitoring
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `USE_SENTRY_LOGGING` | No | — | Set to `"true"` to enable Sentry error tracking |
-| `SENTRY_DSN` | No | — | Sentry Data Source Name (required if USE_SENTRY_LOGGING=true) |
-| `SENTRY_TRACES_SAMPLE_RATE` | No | `0.1` | Sentry trace sampling rate (0.0 to 1.0) |
-| `DISABLE_LOG_ALL_REQUESTS` | No | — | Set to `"true"` to disable request logging |
-| `SLOW_REQUEST_THRESHOLD_MS` | No | `3000` | Log warning for requests slower than this (milliseconds) |
-| `SLOW_DB_QUERY_THRESHOLD_MS` | No | `1000` | Log warning for database queries slower than this |
-
-### Webhooks & Notifications
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `SLACK_WEBHOOKS` | No | — | JSON object mapping names to Slack webhook URLs: `{"default":"https://..."}` |
-| `GOOGLE_CHAT_WEBHOOKS` | No | — | JSON object mapping names to Google Chat webhook URLs |
-| `ZOOM_CHAT_WEBHOOKS` | No | — | JSON object mapping names to Zoom webhook URLs |
-| `WEBHOOK_SECRET` | No | — | Secret for validating incoming webhook signatures |
-
-### Google Cloud Platform (Optional)
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `GCP_PROJECT` | No | — | Google Cloud project ID (for Cloud Tasks, etc.) |
-| `GCP_LOCATION` | No | — | GCP region (e.g., "us-central1") |
-| `GCP_SERVICE_ACCOUNT_EMAIL` | No | — | Service account email for authentication |
-| `GCP_TASKS_NOTIFICATIONS_QUEUE` | No | — | Cloud Tasks queue name for notifications |
-| `GCP_TASK_PROCESSOR_QUEUE` | No | — | Cloud Tasks queue name for background jobs |
-
-### Other
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `VALKEY_URL` | No | — | Valkey/Redis connection URL (for caching) |
-| `GEMINI_API_KEY` | No | — | Google Gemini API key (if using AI features) |
-
-**Example `.env` file:**
-
-``````env
-# Required
-TOKEN_SECRET=your-long-random-secret-here
-TOKEN_ISSUER=my-app
-REFRESH_TOKEN_SECRET=different-long-random-secret
-SESSION_SECRET=session-secret-here
-MONGO_URI=mongodb://localhost:27017/myapp
-
-# Optional
-NODE_ENV=development
-PORT=4000
-ENABLE_SWAGGER=true
-USE_SENTRY_LOGGING=true
-SENTRY_DSN=https://...@sentry.io/...
-``````
-
-## Learn more
-
-- [How to create a model](../how-to/create-a-model.md)
-- [Add GitHub OAuth](../how-to/add-github-oauth.md)
-- [Authentication architecture](../explanation/authentication.md)
-- [API package source](../../api/src/)
-- [AI assistant rules](./.cursor/rules/api/)