@terreno/mcp 0.24.0 → 0.26.0

package/src/docs/versioned/0.25.0/reference/generated/api/functions/markRetryUnsafe.md

@@ -0,0 +1,17 @@
+> **markRetryUnsafe**(`config?`): `AxiosRequestConfig`
+
+Opts a non-idempotent request (POST/PUT/PATCH/DELETE) into the retry policy of a
+createAuthenticatedClient instance: `client.axios.post(url, body, markRetryUnsafe())`.
+Callers must be sure the operation is safe to repeat, and the request body must be
+replayable — JSON objects are fine, but streams/FormData are consumed on first send.
+Has no effect on axios instances not created by createAuthenticatedClient.
+
+## Parameters
+
+### config?
+
+`AxiosRequestConfig` = `{}`
+
+## Returns
+
+`AxiosRequestConfig`

package/src/docs/versioned/0.25.0/reference/generated/api/functions/matchesQuery.md

@@ -0,0 +1,23 @@
+> **matchesQuery**(`doc`, `query`): `boolean`
+
+Check if a document matches a MongoDB-style query in memory.
+
+## Parameters
+
+### doc
+
+`Record`\<`string`, `unknown`\>
+
+The document to test (plain object or Mongoose document)
+
+### query
+
+`Record`\<`string`, `unknown`\>
+
+MongoDB-style query object
+
+## Returns
+
+`boolean`
+
+true if the document matches all query conditions

package/src/docs/versioned/0.25.0/reference/generated/api/functions/normalizeApiError.md

@@ -0,0 +1,32 @@
+> **normalizeApiError**(`error`, `context`): [`NormalizedApiError`](../interfaces/NormalizedApiError.md)
+
+Normalizes an unknown thrown value from an external API call into a stable shape:
+status code, human-readable messages, and a machine classification. Axios errors are
+unwrapped (response body messages extracted); axios errors without a response are
+classified as "network"; non-axios errors fall through to "unknown" with the error
+message preserved.
+
+Raw payload bodies are not carried on the normalized shape — only recognized message
+fields are extracted, and plain-string bodies are truncated. Consumers whose services
+put sensitive data inside those message fields should additionally use a redactError
+hook.
+
+## Parameters
+
+### error
+
+`unknown`
+
+### context
+
+#### apiName
+
+`string`
+
+#### operation
+
+`string`
+
+## Returns
+
+[`NormalizedApiError`](../interfaces/NormalizedApiError.md)

package/src/docs/versioned/0.25.0/reference/generated/api/functions/parseScriptArgs.md

@@ -0,0 +1,35 @@
+> **parseScriptArgs**(`tokens`, `defs?`): `object`
+
+Parse CLI-style tokens into a [ScriptArgs](../interfaces/ScriptArgs.md) accessor. Supports a flexible set
+of conventions so callers and scripts do not need to agree on a rigid format:
+
+- `--name=value` and `--name value`
+- `--flag` (boolean true) and `--no-flag` (boolean false)
+- short aliases `-x` (treated like `--x`)
+- repeated flags collapse into a string array
+- bare tokens become positional arguments
+
+When [declarations](../interfaces/ScriptArgDef.md) are supplied, values are coerced to the
+declared type, defaults are applied, and required args are validated.
+
+## Parameters
+
+### tokens
+
+`string`[]
+
+### defs?
+
+[`ScriptArgDef`](../interfaces/ScriptArgDef.md)[] = `[]`
+
+## Returns
+
+`object`
+
+### args
+
+> **args**: [`ScriptArgs`](../interfaces/ScriptArgs.md)
+
+### errors
+
+> **errors**: `string`[]

package/src/docs/versioned/0.25.0/reference/generated/api/functions/requestContextMiddleware.md

@@ -0,0 +1,26 @@
+> **requestContextMiddleware**(`req`, `res`, `next`): `void`
+
+Express middleware that opens a correlation scope for the request. Mounted early by `TerrenoApp` /
+`setupServer`, it resolves a `requestId` (from request-id/correlation headers, Cloud Trace, or
+W3C `traceparent`, else a new UUID), captures any `jobId`/`sessionId`/trace fields, echoes
+`X-Request-ID` back to the client, and runs the remaining middleware inside the scope so all
+downstream logs are correlated. A later auth-aware pass ([updateRequestContextFromRequest](updateRequestContextFromRequest.md))
+fills in `userId`/`sessionId`.
+
+## Parameters
+
+### req
+
+`Request`
+
+### res
+
+`Response`
+
+### next
+
+`NextFunction`
+
+## Returns
+
+`void`

package/src/docs/versioned/0.25.0/reference/generated/api/functions/runWithRequestContext.md

@@ -0,0 +1,38 @@
+> **runWithRequestContext**\<`T`\>(`context`, `callback`): `T`
+
+Runs `callback` inside a fresh correlation scope so every log line it emits shares the same
+identifiers — the manual equivalent of [requestContextMiddleware](requestContextMiddleware.md) for background jobs,
+cron tasks, scripts, queue consumers, etc. A `requestId` is generated when not supplied, and the
+context is mirrored to Sentry.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### context
+
+`Partial`\<[`RequestContext`](../interfaces/RequestContext.md)\>
+
+### callback
+
+() => `T`
+
+## Returns
+
+`T`
+
+## Example
+
+```typescript
+import {createScopedLogger, runWithRequestContext} from "@terreno/api";
+
+await runWithRequestContext({jobId: "nightly-sync"}, async () => {
+  const log = createScopedLogger({prefix: "[NightlySync]"});
+  log.info("started"); // includes jobId + a generated requestId on every line
+  await sync();
+});
+```

package/src/docs/versioned/0.25.0/reference/generated/api/functions/runWithRequestContextAttributes.md

@@ -0,0 +1,25 @@
+> **runWithRequestContextAttributes**\<`T`\>(`attributes?`, `callback`): `T`
+
+Like [runWithRequestContext](runWithRequestContext.md), but seeds the scope from raw header attributes (for example
+those received on an incoming message or forwarded by another service). Parses Cloud Trace / W3C
+`traceparent` into `traceId`/`spanId` via [getRequestContextFromAttributes](getRequestContextFromAttributes.md).
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### attributes?
+
+`Record`\<`string`, `string` \| `undefined`\> = `{}`
+
+### callback
+
+() => `T`
+
+## Returns
+
+`T`

package/src/docs/versioned/0.25.0/reference/generated/api/functions/withApiErrorHandling.md

@@ -0,0 +1,31 @@
+> **withApiErrorHandling**\<`T`\>(`fn`, `options`): `Promise`\<`T`\>
+
+Wraps an external API call with standardized error handling: failures are normalized
+via normalizeApiError, passed through the optional redactError hook, logged exactly
+once, and rethrown.
+
+In "raw" mode (default) the wrapper logs the normalized shape via the injected logger
+and rethrows the original error. In "apiError" mode the wrapper throws a terreno
+APIError — whose constructor already logs — so the wrapper itself stays silent to
+preserve the log-once contract. The APIError title is stable per JSONAPI convention;
+per-occurrence text goes in `detail`, built from the (redacted) normalized messages.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### fn
+
+() => `Promise`\<`T`\>
+
+### options
+
+[`WithApiErrorHandlingOptions`](../interfaces/WithApiErrorHandlingOptions.md)
+
+## Returns
+
+`Promise`\<`T`\>

package/src/docs/versioned/0.25.0/reference/generated/api/interfaces/AuthenticatedClient.md

@@ -0,0 +1,15 @@
+## Properties
+
+### axios
+
+> **axios**: `AxiosInstance`
+
+***
+
+### invalidateToken
+
+> **invalidateToken**: () => `void`
+
+#### Returns
+
+`void`

package/src/docs/versioned/0.25.0/reference/generated/api/interfaces/CachingSecretProviderOptions.md

@@ -0,0 +1,9 @@
+Options for CachingSecretProvider.
+
+## Properties
+
+### ttlMs?
+
+> `optional` **ttlMs?**: `number`
+
+Time-to-live for cached values, in milliseconds. Defaults to 60_000 (1 minute).

package/src/docs/versioned/0.25.0/reference/generated/api/interfaces/ConfigurationAppOptions.md

@@ -0,0 +1,51 @@
+Options for ConfigurationApp.
+
+## Properties
+
+### basePath?
+
+> `optional` **basePath?**: `string`
+
+Base path for configuration routes. Defaults to "/configuration".
+
+***
+
+### fieldOverrides?
+
+> `optional` **fieldOverrides?**: `Record`\<`string`, \{ `widget?`: `string`; \}\>
+
+Per-field widget overrides (e.g., {"ai.systemPrompt": "markdown"}).
+
+***
+
+### model
+
+> **model**: `Model`\<`any`\>
+
+The Mongoose model with configurationPlugin applied.
+
+***
+
+### permissions?
+
+> `optional` **permissions?**: [`ConfigurationPermissions`](ConfigurationPermissions.md)
+
+Per-route permission overrides. Defaults to admin-only for every route when
+omitted. Supply terreno permission functions (e.g. `[IsStaff]`) to expose
+configuration to a consumer's own permission system.
+
+***
+
+### postUpdate?
+
+> `optional` **postUpdate?**: [`ConfigurationPostUpdateHook`](../type-aliases/ConfigurationPostUpdateHook.md)
+
+Hook run after an update is applied (audit logging).
+
+***
+
+### preUpdate?
+
+> `optional` **preUpdate?**: [`ConfigurationPreUpdateHook`](../type-aliases/ConfigurationPreUpdateHook.md)
+
+Hook run before an update is applied (validation/normalization).

package/src/docs/versioned/0.25.0/reference/generated/api/interfaces/ConfigurationModel.md

@@ -0,0 +1,166 @@
+Convenience type for a Mongoose model with configurationPlugin applied.
+
+Use this when declaring your configuration model to get full type safety:
+```typescript
+export const AppConfig = mongoose.model<AppConfigDocument, ConfigurationModel<AppConfigDocument>>(
+  "AppConfig",
+  appConfigSchema,
+);
+// Then call:
+const name = await AppConfig.getConfig("general.appName"); // typed as string
+const full = await AppConfig.getConfig(); // typed as AppConfigDocument
+```
+
+## Extends
+
+- `Model`\<`T`\>.[`ConfigurationStatics`](ConfigurationStatics.md)\<`T`\>
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`
+
+## Constructors
+
+### Constructor
+
+> **new ConfigurationModel**\<`DocType`\>(`doc?`, `fields?`, `options?`): `Document`\<`unknown`, \{ \}, `T`, \{ \}, \{ \}\> & `Require_id`\<`T`\> *extends* `object` ? `object` & `Require_id`\<`T`\> : `Require_id`\<`T`\> & `object`
+
+#### Parameters
+
+##### doc?
+
+`DocType`
+
+##### fields?
+
+`any`
+
+##### options?
+
+`boolean` \| `AnyObject`
+
+#### Returns
+
+`Document`\<`unknown`, \{ \}, `T`, \{ \}, \{ \}\> & `Require_id`\<`T`\> *extends* `object` ? `object` & `Require_id`\<`T`\> : `Require_id`\<`T`\> & `object`
+
+#### Inherited from
+
+`Model<T>.constructor`
+
+## Methods
+
+### getConfig()
+
+#### Call Signature
+
+> **getConfig**(): `Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>
+
+Get the full singleton configuration document.
+
+##### Returns
+
+`Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>
+
+##### Inherited from
+
+[`ConfigurationStatics`](ConfigurationStatics.md).[`getConfig`](ConfigurationStatics.md#getconfig)
+
+#### Call Signature
+
+> **getConfig**\<`P`\>(`key`): `Promise`\<[`PathValue`](../type-aliases/PathValue.md)\<`T`, `P`\>\>
+
+Get a specific value by dot-notation key.
+
+##### Type Parameters
+
+###### P
+
+`P` *extends* `string`
+
+##### Parameters
+
+###### key
+
+`P`
+
+##### Returns
+
+`Promise`\<[`PathValue`](../type-aliases/PathValue.md)\<`T`, `P`\>\>
+
+##### Inherited from
+
+[`ConfigurationStatics`](ConfigurationStatics.md).[`getConfig`](ConfigurationStatics.md#getconfig)
+
+***
+
+### getSecretFields()
+
+> **getSecretFields**(): [`SecretFieldMeta`](SecretFieldMeta.md)[]
+
+Get secret field metadata discovered from the schema.
+
+#### Returns
+
+[`SecretFieldMeta`](SecretFieldMeta.md)[]
+
+#### Inherited from
+
+[`ConfigurationStatics`](ConfigurationStatics.md).[`getSecretFields`](ConfigurationStatics.md#getsecretfields)
+
+***
+
+### resolveSecrets()
+
+> **resolveSecrets**(`provider?`): `Promise`\<`Map`\<`string`, `string`\>\>
+
+Resolve all secret field values from a provider.
+Uses the provider passed here, or falls back to the one configured in the plugin options.
+Returns an **in-memory** map of path -> value for programmatic use (startup
+self-checks, request-time resolution).
+
+This method never persists resolved values. Secret material must never be
+written to the configuration document.
+
+#### Parameters
+
+##### provider?
+
+[`SecretProvider`](SecretProvider.md)
+
+#### Returns
+
+`Promise`\<`Map`\<`string`, `string`\>\>
+
+#### Inherited from
+
+[`ConfigurationStatics`](ConfigurationStatics.md).[`resolveSecrets`](ConfigurationStatics.md#resolvesecrets)
+
+***
+
+### updateConfig()
+
+> **updateConfig**(`updates`): `Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>
+
+Update the singleton configuration document.
+
+The patch is flattened into MongoDB dotted paths and applied with
+`findOneAndUpdate({$set})`. This preserves sibling fields inside nested
+subdocuments when a partial nested patch is supplied, and tolerates legacy /
+out-of-schema fields already persisted on the document (unlike a full
+`doc.save()`, which throws under `strict: "throw"`).
+
+#### Parameters
+
+##### updates
+
+[`DeepPartial`](../type-aliases/DeepPartial.md)\<`T`\>
+
+#### Returns
+
+`Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>
+
+#### Inherited from
+
+[`ConfigurationStatics`](ConfigurationStatics.md).[`updateConfig`](ConfigurationStatics.md#updateconfig)

package/src/docs/versioned/0.25.0/reference/generated/api/interfaces/ConfigurationPermissions.md

@@ -0,0 +1,45 @@
+Per-route permission overrides for ConfigurationApp. Each value is an array of
+terreno permission functions ([PermissionMethod](../type-aliases/PermissionMethod.md)), AND-combined like
+`modelRouter` permissions. When a route is omitted, the default admin-only
+guard applies.
+
+## Example
+
+```typescript
+permissions: {
+  read: [IsStaff],
+  update: [IsSuperUser],
+}
+```
+
+## Properties
+
+### listSecrets?
+
+> `optional` **listSecrets?**: [`PermissionMethod`](../type-aliases/PermissionMethod.md)\<`unknown`\>[]
+
+Guards `POST {basePath}/list-secrets` and `/validate-secrets`.
+
+***
+
+### meta?
+
+> `optional` **meta?**: [`PermissionMethod`](../type-aliases/PermissionMethod.md)\<`unknown`\>[]
+
+Guards `GET {basePath}/meta` (schema metadata).
+
+***
+
+### read?
+
+> `optional` **read?**: [`PermissionMethod`](../type-aliases/PermissionMethod.md)\<`unknown`\>[]
+
+Guards `GET {basePath}` (current values).
+
+***
+
+### update?
+
+> `optional` **update?**: [`PermissionMethod`](../type-aliases/PermissionMethod.md)\<`unknown`\>[]
+
+Guards `PATCH {basePath}` (update values).

package/src/docs/versioned/0.25.0/reference/generated/api/interfaces/ConfigurationPluginOptions.md

@@ -0,0 +1,30 @@
+Options passed to configurationPlugin.
+
+## Properties
+
+### enforceSingletonIndex?
+
+> `optional` **enforceSingletonIndex?**: `boolean`
+
+When `true`, adds a `_singleton` sentinel field with a unique index to
+enforce the singleton constraint at the database level.
+
+Defaults to `false`. Leave this off when the consuming app already enforces
+a single non-deleted document via the pre-save guard (the default behavior)
+or via its own indexes/soft-delete plugin, to avoid double-enforcement and
+conflicting indexes.
+
+#### Default Value
+
+```ts
+false
+```
+
+***
+
+### secretProvider?
+
+> `optional` **secretProvider?**: [`SecretProvider`](SecretProvider.md)
+
+Secret provider used when resolveSecrets() is called without an explicit provider.
+Typically set during app startup so the model can resolve secrets on demand.

package/src/docs/versioned/0.25.0/reference/generated/api/interfaces/ConfigurationStatics.md

@@ -0,0 +1,107 @@
+Static methods added by configurationPlugin to the Mongoose model.
+
+## Extended by
+
+- [`ConfigurationModel`](ConfigurationModel.md)
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`
+
+## Methods
+
+### getConfig()
+
+#### Call Signature
+
+> **getConfig**(): `Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>
+
+Get the full singleton configuration document.
+
+##### Returns
+
+`Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>
+
+#### Call Signature
+
+> **getConfig**\<`P`\>(`key`): `Promise`\<[`PathValue`](../type-aliases/PathValue.md)\<`T`, `P`\>\>
+
+Get a specific value by dot-notation key.
+
+##### Type Parameters
+
+###### P
+
+`P` *extends* `string`
+
+##### Parameters
+
+###### key
+
+`P`
+
+##### Returns
+
+`Promise`\<[`PathValue`](../type-aliases/PathValue.md)\<`T`, `P`\>\>
+
+***
+
+### getSecretFields()
+
+> **getSecretFields**(): [`SecretFieldMeta`](SecretFieldMeta.md)[]
+
+Get secret field metadata discovered from the schema.
+
+#### Returns
+
+[`SecretFieldMeta`](SecretFieldMeta.md)[]
+
+***
+
+### resolveSecrets()
+
+> **resolveSecrets**(`provider?`): `Promise`\<`Map`\<`string`, `string`\>\>
+
+Resolve all secret field values from a provider.
+Uses the provider passed here, or falls back to the one configured in the plugin options.
+Returns an **in-memory** map of path -> value for programmatic use (startup
+self-checks, request-time resolution).
+
+This method never persists resolved values. Secret material must never be
+written to the configuration document.
+
+#### Parameters
+
+##### provider?
+
+[`SecretProvider`](SecretProvider.md)
+
+#### Returns
+
+`Promise`\<`Map`\<`string`, `string`\>\>
+
+***
+
+### updateConfig()
+
+> **updateConfig**(`updates`): `Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>
+
+Update the singleton configuration document.
+
+The patch is flattened into MongoDB dotted paths and applied with
+`findOneAndUpdate({$set})`. This preserves sibling fields inside nested
+subdocuments when a partial nested patch is supplied, and tolerates legacy /
+out-of-schema fields already persisted on the document (unlike a full
+`doc.save()`, which throws under `strict: "throw"`).
+
+#### Parameters
+
+##### updates
+
+[`DeepPartial`](../type-aliases/DeepPartial.md)\<`T`\>
+
+#### Returns
+
+`Promise`\<`T` & `Document`\<`ObjectId`, `any`, `any`, `Record`\<`string`, `any`\>, \{ \}\>\>