@terreno/mcp 0.23.0 → 0.24.0

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/assertNoActionCollisions.md

@@ -0,0 +1,21 @@
+> **assertNoActionCollisions**\<`T`\>(`model`, `options`): `void`
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### model
+
+`Model`\<`T`\>
+
+### options
+
+`Pick`\<[`ModelRouterOptions`](../interfaces/ModelRouterOptions.md)\<`T`\>, `"instanceActions"` \| `"collectionActions"`\>
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/asyncHandler.md

@@ -0,0 +1,15 @@
+> **asyncHandler**(`fn`, `options?`): (`req`, `res`, `next`) => `void`
+
+## Parameters
+
+### fn
+
+`AsyncHandlerFn`
+
+### options?
+
+[`AsyncHandlerOptions`](../interfaces/AsyncHandlerOptions.md)
+
+## Returns
+
+(`req`, `res`, `next`) => `void`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/authenticateMiddleware.md

@@ -0,0 +1,11 @@
+> **authenticateMiddleware**(`anonymous?`): (`req`, `res`, `next`) => `any`
+
+## Parameters
+
+### anonymous?
+
+`boolean` = `false`
+
+## Returns
+
+(`req`, `res`, `next`) => `any`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/baseUserPlugin.md

@@ -0,0 +1,11 @@
+> **baseUserPlugin**(`schema`): `void`
+
+## Parameters
+
+### schema
+
+`Schema`\<`any`, `any`, `any`, `any`\>
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/buildQuerySchemaFromFields.md

@@ -0,0 +1,30 @@
+> **buildQuerySchemaFromFields**\<`T`\>(`model`, `queryFields?`): `Record`\<`string`, [`OpenApiSchemaProperty`](../interfaces/OpenApiSchemaProperty.md)\>
+
+Build a query parameter schema from a model's Mongoose schema and queryFields array.
+Always includes pagination parameters (limit, page, sort).
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### model
+
+`Model`\<`T`\>
+
+A Mongoose model
+
+### queryFields?
+
+`string`[] = `[]`
+
+Array of field names allowed for querying
+
+## Returns
+
+`Record`\<`string`, [`OpenApiSchemaProperty`](../interfaces/OpenApiSchemaProperty.md)\>
+
+Schema properties suitable for query validation

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/checkModelsStrict.md

@@ -0,0 +1,21 @@
+> **checkModelsStrict**(`ignoredModels?`): `void`
+
+Ensure that all mongoose models are set to strict mode.
+This validates that models will throw errors when attempting to set
+properties that aren't defined in the schema.
+
+## Parameters
+
+### ignoredModels?
+
+`string`[] = `[]`
+
+Array of model names to skip validation for
+
+## Returns
+
+`void`
+
+## Throws
+
+Error if any model is not set to strict mode or missing virtual settings

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/checkPermissions.md

@@ -0,0 +1,29 @@
+> **checkPermissions**\<`T`\>(`method`, `permissions`, `user?`, `obj?`): `Promise`\<`boolean`\>
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### method
+
+[`RESTMethod`](../type-aliases/RESTMethod.md)
+
+### permissions
+
+[`PermissionMethod`](../type-aliases/PermissionMethod.md)\<`T`\>[]
+
+### user?
+
+[`User`](../interfaces/User.md)
+
+### obj?
+
+`T`
+
+## Returns
+
+`Promise`\<`boolean`\>

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/clearQueryStore.md

@@ -0,0 +1,7 @@
+> **clearQueryStore**(): `void`
+
+Clear all subscriptions (for testing).
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/clearRealtimeRegistry.md

@@ -0,0 +1,7 @@
+> **clearRealtimeRegistry**(): `void`
+
+Clear the registry (for testing).
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/computeQueryId.md

@@ -0,0 +1,18 @@
+> **computeQueryId**(`collection`, `query`): `string`
+
+Compute a deterministic queryId from collection and query on the server side.
+This prevents clients from hijacking other subscriptions by providing a colliding queryId.
+
+## Parameters
+
+### collection
+
+`string`
+
+### query
+
+`Record`\<`string`, `any`\>
+
+## Returns
+
+`string`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/configurationPlugin.md

@@ -0,0 +1,48 @@
+> **configurationPlugin**(`schema`, `options?`): `void`
+
+Mongoose schema plugin that adds singleton configuration behavior.
+
+Adds:
+- Pre-save hook enforcing exactly one non-deleted document (soft-delete aware
+  when the schema has a `deleted` path, e.g. via `isDeletedPlugin`)
+- `getConfig()` static: fetches or creates the singleton (full doc or keyed value)
+- `updateConfig(updates)` static: patches the singleton via `findOneAndUpdate({$set})`
+  with dotted paths (preserves sibling subdoc fields; tolerates legacy fields)
+- `getSecretFields()` static: returns metadata for fields with `secret: true`
+- `resolveSecrets(provider?)` static: resolves secret values into an in-memory map,
+  using the plugin provider by default (never persists values)
+- Hard-delete blockers (`deleteOne`/`deleteMany`/`findOneAndDelete`); soft deletes
+  (setting `deleted: true`) are allowed
+
+Soft deletes are allowed and a soft-deleted document does not block creating a
+new singleton. The `_singleton` unique index is opt-in via
+`enforceSingletonIndex` (default off).
+
+Mark fields as secrets using schema path options. Pin a version with the
+optional `secretVersion` option:
+```typescript
+const configSchema = new Schema({
+  apiKey: {
+    type: String,
+    description: "Third-party API key",
+    secret: true,
+    secretName: "my-api-key",
+    secretVersion: "3", // optional — resolves "latest" when omitted
+  },
+});
+configSchema.plugin(configurationPlugin, {secretProvider: new EnvSecretProvider()});
+```
+
+## Parameters
+
+### schema
+
+`Schema`
+
+### options?
+
+[`ConfigurationPluginOptions`](../interfaces/ConfigurationPluginOptions.md)
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/configureOpenApiValidator.md

@@ -0,0 +1,28 @@
+> **configureOpenApiValidator**(`config?`): `void`
+
+Configure the global OpenAPI validator settings.
+Calling this function activates validation — middleware that was previously
+installed as a no-op will begin validating requests.
+
+## Parameters
+
+### config?
+
+`Partial`\<[`OpenApiValidatorConfig`](../interfaces/OpenApiValidatorConfig.md)\> = `{}`
+
+Configuration options to merge with existing config
+
+## Returns
+
+`void`
+
+## Example
+
+```typescript
+configureOpenApiValidator({
+  removeAdditional: true,
+  onAdditionalPropertiesRemoved: (props, req) => {
+    Sentry.captureMessage(`Stripped: ${props.join(", ")} on ${req.method} ${req.path}`);
+  },
+});
+```

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createActionOpenApiMiddleware.md

@@ -0,0 +1,35 @@
+> **createActionOpenApiMiddleware**\<`T`\>(`__namedParameters`): `RequestHandler`
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### \_\_namedParameters
+
+#### action
+
+`BaseActionConfig`\<`unknown`, `unknown`, `unknown`\>
+
+#### actionName
+
+`string`
+
+#### model
+
+`Model`\<`T`\>
+
+#### options
+
+`Partial`\<[`ModelRouterOptions`](../interfaces/ModelRouterOptions.md)\<`T`\>\>
+
+#### scope
+
+`ActionScope`
+
+## Returns
+
+`RequestHandler`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createBetterAuth.md

@@ -0,0 +1,13 @@
+> **createBetterAuth**(`options`): `Auth`
+
+Creates a Better Auth instance with MongoDB adapter.
+
+## Parameters
+
+### options
+
+[`CreateBetterAuthOptions`](../interfaces/CreateBetterAuthOptions.md)
+
+## Returns
+
+`Auth`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createBetterAuthSessionMiddleware.md

@@ -0,0 +1,18 @@
+> **createBetterAuthSessionMiddleware**(`auth`, `userModel?`): (`req`, `_res`, `next`) => `Promise`\<`void`\>
+
+Creates Express middleware that extracts the Better Auth session
+and populates req.user with the application User model.
+
+## Parameters
+
+### auth
+
+`Auth`
+
+### userModel?
+
+[`UserModel`](../interfaces/UserModel.md)
+
+## Returns
+
+(`req`, `_res`, `next`) => `Promise`\<`void`\>

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createFeatureFlaggedLogger.md

@@ -0,0 +1,53 @@
+> **createFeatureFlaggedLogger**(`options`): [`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+Wraps a [ScopedLogger](../interfaces/ScopedLogger.md) so all `debug` / `info` / `warn` / `error` traffic is dropped while
+`isEnabled()` returns false. Use it to keep verbose diagnostics in the code but silent until a
+flag turns them on — no redeploy required.
+
+`isEnabled` is evaluated on **every** call, so it can read any feature-flag source: an
+environment variable, a cached/remote flag map, or a call into `@terreno/feature-flags` from your
+app. (`@terreno/api` deliberately does not import `@terreno/feature-flags` to avoid a package
+cycle — you supply the predicate.)
+
+## Parameters
+
+### options
+
+[`CreateFeatureFlaggedLoggerOptions`](../interfaces/CreateFeatureFlaggedLoggerOptions.md)
+
+The `isEnabled` predicate plus an optional `target` logger and `gateCatch`.
+
+## Returns
+
+[`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+A scoped logger that forwards to `target` only while the flag is enabled.
+
+## See
+
+[createScopedLogger](createScopedLogger.md) for the usual `target`.
+
+## Examples
+
+**Gate a scoped logger behind an env var (flips live, no restart)**
+
+```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
+```
+
+**Drive it from \`@terreno/feature-flags\` 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 (default: false)
+});
+```

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createModelValidators.md

@@ -0,0 +1,74 @@
+> **createModelValidators**\<`T`\>(`model`, `options?`): `object`
+
+Creates validation middleware for use with modelRouter.
+Returns an object with middleware for each operation type.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### model
+
+`Model`\<`T`\>
+
+The Mongoose model
+
+### options?
+
+[`ModelRouterValidationOptions`](../interfaces/ModelRouterValidationOptions.md)
+
+Configuration options
+
+## Returns
+
+`object`
+
+Object with create and update validation middleware
+
+### create
+
+> **create**: (`req`, `res`, `next`) => `void`
+
+#### Parameters
+
+##### req
+
+`Request`
+
+##### res
+
+`Response`
+
+##### next
+
+`NextFunction`
+
+#### Returns
+
+`void`
+
+### update
+
+> **update**: (`req`, `res`, `next`) => `void`
+
+#### Parameters
+
+##### req
+
+`Request`
+
+##### res
+
+`Response`
+
+##### next
+
+`NextFunction`
+
+#### Returns
+
+`void`

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createOpenApiBuilder.md

@@ -0,0 +1,39 @@
+> **createOpenApiBuilder**(`options`): [`OpenApiMiddlewareBuilder`](../classes/OpenApiMiddlewareBuilder.md)
+
+Creates a new OpenAPI middleware builder.
+
+This is the recommended entry point for creating custom OpenAPI middleware.
+It returns a fluent builder that allows you to chain configuration methods.
+
+## Parameters
+
+### options
+
+`Partial`\<[`ModelRouterOptions`](../interfaces/ModelRouterOptions.md)\<`unknown`\>\>
+
+Router options containing the OpenAPI configuration
+
+## Returns
+
+[`OpenApiMiddlewareBuilder`](../classes/OpenApiMiddlewareBuilder.md)
+
+A new OpenApiMiddlewareBuilder instance
+
+## Example
+
+```typescript
+import {createOpenApiBuilder} from "./openApiBuilder";
+
+const statsMiddleware = createOpenApiBuilder(options)
+  .withTags(["analytics"])
+  .withSummary("Get usage statistics")
+  .withQueryParameter("startDate", {type: "string", format: "date"})
+  .withQueryParameter("endDate", {type: "string", format: "date"})
+  .withResponse<{totalUsers: number; activeUsers: number}>(200, {
+    totalUsers: {type: "number", description: "Total registered users"},
+    activeUsers: {type: "number", description: "Users active in period"},
+  })
+  .build();
+
+router.get("/analytics/stats", statsMiddleware, getStatsHandler);
+```

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createRouter.md

@@ -0,0 +1,19 @@
+> **createRouter**(`rootPath`, `addRoutes`, `middleware?`): (`string` \| `Router` \| `RequestHandler`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>)[]
+
+## Parameters
+
+### rootPath
+
+`string`
+
+### addRoutes
+
+[`AddRoutes`](../type-aliases/AddRoutes.md)
+
+### middleware?
+
+`RequestHandler`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>[] = `[]`
+
+## Returns
+
+(`string` \| `Router` \| `RequestHandler`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>)[]

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createRouterWithAuth.md

@@ -0,0 +1,19 @@
+> **createRouterWithAuth**(`rootPath`, `addRoutes`, `middleware?`): (`string` \| `Router` \| `RequestHandler`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>)[]
+
+## Parameters
+
+### rootPath
+
+`string`
+
+### addRoutes
+
+(`router`) => `void`
+
+### middleware?
+
+`RequestHandler`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>[] = `[]`
+
+## Returns
+
+(`string` \| `Router` \| `RequestHandler`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>)[]

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createScopedLogger.md

@@ -0,0 +1,53 @@
+> **createScopedLogger**(`options?`): [`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+Creates a [ScopedLogger](../interfaces/ScopedLogger.md) that prefixes every message and/or attaches stable `labels` to
+every line, so multi-step workflows are easy to group and search.
+
+- `prefix` is prepended to the human-readable message (easy grep / Log Explorer text search) and
+  also stored as the Winston metadata field `terrenoLogPrefix`.
+- `labels` are normalized to strings and stored as the Winston metadata field `terrenoLabels`.
+  They appear in the plain-text ` key=value` suffix (see [formatLogContextSuffix](formatLogContextSuffix.md)) and as
+  discrete fields on structured transports such as `@google-cloud/logging-winston`.
+
+Both ride on a Winston **child logger**, so they merge with — and never overwrite — the
+request/job correlation fields that AsyncLocalStorage injects (`requestId`, `userId`,
+`terrenoRequestLog`, etc.). Avoid label keys that collide with those framework fields:
+`requestId`, `jobId`, `sessionId`, `userId`, `traceId`, `spanId`, `terrenoLogPrefix`,
+`terrenoRequestLog`, `terrenoLabels`.
+
+If both `prefix` and `labels` are empty, the global [logger](../variables/logger.md) is returned unchanged.
+
+## Parameters
+
+### options?
+
+[`CreateScopedLoggerOptions`](../interfaces/CreateScopedLoggerOptions.md) = `{}`
+
+Optional `prefix` token and/or `labels` dimensions for this scope.
+
+## Returns
+
+[`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+A scoped logger sharing the same methods as the global [logger](../variables/logger.md).
+
+## See
+
+[createFeatureFlaggedLogger](createFeatureFlaggedLogger.md) to gate a scoped logger behind a feature flag.
+
+## Example
+
+**Reuse one instance for a whole workflow 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");        // -> "[InvoicePay] Starting capture invoiceId=... attempt=1 requestId=..."
+log.warn("Stripe rate limited, backing off");
+await capture(invoice).catch(log.catch);
+```

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createScriptArgs.md

@@ -0,0 +1,33 @@
+> **createScriptArgs**(`__namedParameters`): `object`
+
+Build a [ScriptArgs](../interfaces/ScriptArgs.md) accessor from a raw values map and optional declarations.
+Applies declared defaults, coerces declared types, and validates required args.
+Returns the accessor plus any validation errors (callers decide how to surface them).
+
+## Parameters
+
+### \_\_namedParameters
+
+#### defs?
+
+[`ScriptArgDef`](../interfaces/ScriptArgDef.md)[] = `[]`
+
+#### positional?
+
+`string`[] = `[]`
+
+#### values
+
+`Record`\<`string`, [`ScriptArgValue`](../type-aliases/ScriptArgValue.md)\>
+
+## Returns
+
+`object`
+
+### args
+
+> **args**: [`ScriptArgs`](../interfaces/ScriptArgs.md)
+
+### errors
+
+> **errors**: `string`[]

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createValidator.md

@@ -0,0 +1,29 @@
+> **createValidator**(`options`): (`req`, `res`, `next`) => `void`
+
+Creates a combined validation middleware for both body and query parameters.
+
+## Parameters
+
+### options
+
+[`CreateValidatorOptions`](../interfaces/CreateValidatorOptions.md)
+
+Configuration for what to validate
+
+## Returns
+
+Express middleware function
+
+(`req`, `res`, `next`) => `void`
+
+## Example
+
+```typescript
+router.post("/search", [
+  openApiMiddleware,
+  createValidator({
+    body: {query: {type: "string", required: true}},
+    query: {limit: {type: "number"}},
+  }),
+], handler);
+```

package/dist/docs/versioned/0.23.0/reference/generated/api/functions/createdUpdatedPlugin.md

@@ -0,0 +1,11 @@
+> **createdUpdatedPlugin**(`schema`): `void`
+
+## Parameters
+
+### schema
+
+`Schema`\<`any`, `any`, `any`, `any`\>
+
+## Returns
+
+`void`