@terreno/api 0.3.1 → 0.4.2

package/dist/configurationApp.d.ts

@@ -0,0 +1,91 @@
+import type express from "express";
+import type { Model } from "mongoose";
+import type { TerrenoPlugin } from "./terrenoPlugin";
+/**
+ * Metadata for a single configuration field, sent to the frontend.
+ */
+interface ConfigFieldMeta {
+    type: string;
+    required: boolean;
+    description?: string;
+    enum?: string[];
+    default?: any;
+    secret?: boolean;
+    widget?: string;
+}
+/**
+ * Metadata for a configuration section (nested subschema).
+ */
+interface ConfigSectionMeta {
+    name: string;
+    displayName: string;
+    description?: string;
+    fields: Record<string, ConfigFieldMeta>;
+}
+/**
+ * The config metadata response shape sent to the frontend.
+ */
+export interface ConfigurationMetaResponse {
+    sections: ConfigSectionMeta[];
+}
+/**
+ * Options for ConfigurationApp.
+ */
+export interface ConfigurationAppOptions {
+    /** The Mongoose model with configurationPlugin applied. */
+    model: Model<any>;
+    /** Base path for configuration routes. Defaults to "/configuration". */
+    basePath?: string;
+    /** Per-field widget overrides (e.g., {"ai.systemPrompt": "markdown"}). */
+    fieldOverrides?: Record<string, {
+        widget?: string;
+    }>;
+}
+/**
+ * TerrenoPlugin that provides configuration management endpoints.
+ *
+ * Inspects the Mongoose configuration model to auto-generate:
+ * - `GET {basePath}/meta` — Schema metadata (sections, fields, types, descriptions)
+ * - `GET {basePath}` — Current configuration values
+ * - `PATCH {basePath}` — Update configuration values
+ * - `POST {basePath}/refresh-secrets` — Trigger secret refresh (if provider configured)
+ *
+ * All endpoints require `Permissions.IsAdmin`.
+ *
+ * Nested subschemas in the model become separate sections in the metadata,
+ * making them renderable as cards/accordions in the admin UI.
+ *
+ * @example
+ * ```typescript
+ * import {ConfigurationApp, configurationPlugin} from "@terreno/api";
+ *
+ * const configSchema = new Schema({
+ *   general: { type: new Schema({
+ *     appName: { type: String, description: "App display name", default: "My App" },
+ *     maintenanceMode: { type: Boolean, description: "Enable maintenance mode", default: false },
+ *   })},
+ *   integrations: { type: new Schema({
+ *     openAiKey: { type: String, description: "OpenAI API key", secret: true, secretName: "openai-key" },
+ *   })},
+ * });
+ * configSchema.plugin(configurationPlugin);
+ * const AppConfig = mongoose.model("AppConfig", configSchema);
+ *
+ * new TerrenoApp({ userModel: User })
+ *   .configure(AppConfig)
+ *   .start();
+ * ```
+ */
+export declare class ConfigurationApp implements TerrenoPlugin {
+    private options;
+    constructor(options: ConfigurationAppOptions);
+    register(app: express.Application): void;
+    /**
+     * Builds the metadata response by inspecting the model schema.
+     * Top-level fields with subschemas become sections.
+     * Top-level scalar fields go into a "General" section.
+     */
+    private buildMetadata;
+    private mongooseTypeToString;
+}
+export {};

package/dist/configurationApp.js

@@ -0,0 +1,407 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationApp = void 0;
+var api_1 = require("./api");
+var auth_1 = require("./auth");
+var errors_1 = require("./errors");
+var logger_1 = require("./logger");
+var populate_1 = require("./populate");
+/**
+ * Middleware that requires the user to be an admin.
+ */
+var requireAdmin = function (req, _res, next) {
+    var _a;
+    if (!((_a = req.user) === null || _a === void 0 ? void 0 : _a.admin)) {
+        next(new errors_1.APIError({ status: 403, title: "Admin access required" }));
+        return;
+    }
+    next();
+};
+/**
+ * Extracts field metadata from an OpenAPI properties object, augmented with
+ * secret info from the Mongoose schema.
+ */
+var extractFieldMeta = function (properties, required, schema, prefix, fieldOverrides) {
+    var e_1, _a;
+    var _b, _c, _d;
+    var fields = {};
+    try {
+        for (var _e = __values(Object.entries(properties)), _f = _e.next(); !_f.done; _f = _e.next()) {
+            var _g = __read(_f.value, 2), key = _g[0], prop = _g[1];
+            var fullPath = prefix ? "".concat(prefix, ".").concat(key) : key;
+            var schemaPath = schema.path(fullPath);
+            var opts = schemaPath === null || schemaPath === void 0 ? void 0 : schemaPath.options;
+            fields[key] = {
+                default: prop.default,
+                description: (_b = opts === null || opts === void 0 ? void 0 : opts.description) !== null && _b !== void 0 ? _b : prop.description,
+                enum: prop.enum,
+                required: required.includes(key),
+                secret: (opts === null || opts === void 0 ? void 0 : opts.secret) === true,
+                type: (_c = prop.type) !== null && _c !== void 0 ? _c : "string",
+            };
+            // Apply field overrides
+            if ((_d = fieldOverrides === null || fieldOverrides === void 0 ? void 0 : fieldOverrides[fullPath]) === null || _d === void 0 ? void 0 : _d.widget) {
+                fields[key].widget = fieldOverrides[fullPath].widget;
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_f && !_f.done && (_a = _e.return)) _a.call(_e);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return fields;
+};
+/**
+ * System fields to skip in configuration sections.
+ */
+var SYSTEM_FIELDS = new Set(["_id", "_singleton", "id", "__v", "created", "updated", "deleted"]);
+var SECRET_REDACTED = "********";
+/**
+ * Redacts secret field values in a configuration object.
+ * Replaces values at secret paths with a placeholder string.
+ */
+var redactSecrets = function (obj, secretFields) {
+    var e_2, _a;
+    var redacted = __assign({}, obj);
+    try {
+        for (var secretFields_1 = __values(secretFields), secretFields_1_1 = secretFields_1.next(); !secretFields_1_1.done; secretFields_1_1 = secretFields_1.next()) {
+            var field = secretFields_1_1.value;
+            var parts = field.path.split(".");
+            var current = redacted;
+            for (var i = 0; i < parts.length - 1; i++) {
+                if (current[parts[i]] != null && typeof current[parts[i]] === "object") {
+                    current[parts[i]] = __assign({}, current[parts[i]]);
+                    current = current[parts[i]];
+                }
+                else {
+                    current = null;
+                    break;
+                }
+            }
+            var lastKey = parts[parts.length - 1];
+            if (current != null && current[lastKey] != null && current[lastKey] !== "") {
+                current[lastKey] = SECRET_REDACTED;
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (secretFields_1_1 && !secretFields_1_1.done && (_a = secretFields_1.return)) _a.call(secretFields_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return redacted;
+};
+/**
+ * Converts a camelCase or PascalCase string into a display-friendly title.
+ */
+var toDisplayName = function (name) {
+    return name
+        .replace(/([A-Z])/g, " $1")
+        .replace(/^./, function (s) { return s.toUpperCase(); })
+        .trim();
+};
+/**
+ * TerrenoPlugin that provides configuration management endpoints.
+ *
+ * Inspects the Mongoose configuration model to auto-generate:
+ * - `GET {basePath}/meta` — Schema metadata (sections, fields, types, descriptions)
+ * - `GET {basePath}` — Current configuration values
+ * - `PATCH {basePath}` — Update configuration values
+ * - `POST {basePath}/refresh-secrets` — Trigger secret refresh (if provider configured)
+ *
+ * All endpoints require `Permissions.IsAdmin`.
+ *
+ * Nested subschemas in the model become separate sections in the metadata,
+ * making them renderable as cards/accordions in the admin UI.
+ *
+ * @example
+ * ```typescript
+ * import {ConfigurationApp, configurationPlugin} from "@terreno/api";
+ *
+ * const configSchema = new Schema({
+ *   general: { type: new Schema({
+ *     appName: { type: String, description: "App display name", default: "My App" },
+ *     maintenanceMode: { type: Boolean, description: "Enable maintenance mode", default: false },
+ *   })},
+ *   integrations: { type: new Schema({
+ *     openAiKey: { type: String, description: "OpenAI API key", secret: true, secretName: "openai-key" },
+ *   })},
+ * });
+ * configSchema.plugin(configurationPlugin);
+ * const AppConfig = mongoose.model("AppConfig", configSchema);
+ *
+ * new TerrenoApp({ userModel: User })
+ *   .configure(AppConfig)
+ *   .start();
+ * ```
+ */
+var ConfigurationApp = /** @class */ (function () {
+    function ConfigurationApp(options) {
+        this.options = options;
+    }
+    ConfigurationApp.prototype.register = function (app) {
+        var _this = this;
+        var _a, _b, _c, _d;
+        var basePath = (_a = this.options.basePath) !== null && _a !== void 0 ? _a : "/configuration";
+        var ConfigModel = this.options.model;
+        var schema = ConfigModel.schema;
+        // Build metadata by inspecting the schema
+        var meta = this.buildMetadata(ConfigModel, schema);
+        // GET /configuration/meta — schema metadata for the frontend
+        app.get("".concat(basePath, "/meta"), (0, auth_1.authenticateMiddleware)(), requireAdmin, function (_req, res) {
+            return res.json(meta);
+        });
+        // Discover secret fields once at registration time
+        var secretFields = (_d = (_c = (_b = ConfigModel).getSecretFields) === null || _c === void 0 ? void 0 : _c.call(_b)) !== null && _d !== void 0 ? _d : [];
+        // GET /configuration — current values (secrets redacted)
+        app.get("".concat(basePath), (0, auth_1.authenticateMiddleware)(), requireAdmin, (0, api_1.asyncHandler)(function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
+            var config, data;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, ConfigModel.getConfig()];
+                    case 1:
+                        config = _a.sent();
+                        data = redactSecrets(config.toJSON(), secretFields);
+                        return [2 /*return*/, res.json({ data: data })];
+                }
+            });
+        }); }));
+        // PATCH /configuration — update values (secrets redacted in response)
+        app.patch("".concat(basePath), (0, auth_1.authenticateMiddleware)(), requireAdmin, (0, api_1.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+            var _a, _s, _i, _v, safeBody, config, data;
+            var _b, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        _a = req.body, _s = _a._singleton, _i = _a._id, _v = _a.__v, safeBody = __rest(_a, ["_singleton", "_id", "__v"]);
+                        return [4 /*yield*/, ConfigModel.updateConfig(safeBody)];
+                    case 1:
+                        config = _d.sent();
+                        logger_1.logger.info("Configuration updated by ".concat((_c = (_b = req.user) === null || _b === void 0 ? void 0 : _b.email) !== null && _c !== void 0 ? _c : "unknown"));
+                        data = redactSecrets(config.toJSON(), secretFields);
+                        return [2 /*return*/, res.json({ data: data })];
+                }
+            });
+        }); }));
+        // POST /configuration/list-secrets — list secret fields and optionally resolve from provider
+        app.post("".concat(basePath, "/list-secrets"), (0, auth_1.authenticateMiddleware)(), requireAdmin, (0, api_1.asyncHandler)(function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
+            var resolved, updates, resolved_1, resolved_1_1, _a, path, value;
+            var e_3, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0: return [4 /*yield*/, ConfigModel.resolveSecrets()];
+                    case 1:
+                        resolved = _c.sent();
+                        if (!(resolved.size > 0)) return [3 /*break*/, 3];
+                        updates = {};
+                        try {
+                            for (resolved_1 = __values(resolved), resolved_1_1 = resolved_1.next(); !resolved_1_1.done; resolved_1_1 = resolved_1.next()) {
+                                _a = __read(resolved_1_1.value, 2), path = _a[0], value = _a[1];
+                                updates[path] = value;
+                            }
+                        }
+                        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                        finally {
+                            try {
+                                if (resolved_1_1 && !resolved_1_1.done && (_b = resolved_1.return)) _b.call(resolved_1);
+                            }
+                            finally { if (e_3) throw e_3.error; }
+                        }
+                        return [4 /*yield*/, ConfigModel.updateConfig(updates)];
+                    case 2:
+                        _c.sent();
+                        logger_1.logger.info("Refreshed ".concat(resolved.size, "/").concat(secretFields.length, " secrets"));
+                        _c.label = 3;
+                    case 3: return [2 /*return*/, res.json({
+                            message: "Resolved ".concat(resolved.size, "/").concat(secretFields.length, " secrets."),
+                            resolved: resolved.size,
+                            secretFields: secretFields.map(function (s) { return ({ path: s.path, secretName: s.secretName }); }),
+                            total: secretFields.length,
+                        })];
+                }
+            });
+        }); }));
+        logger_1.logger.info("Configuration routes mounted at ".concat(basePath));
+    };
+    /**
+     * Builds the metadata response by inspecting the model schema.
+     * Top-level fields with subschemas become sections.
+     * Top-level scalar fields go into a "General" section.
+     */
+    ConfigurationApp.prototype.buildMetadata = function (_model, schema) {
+        var _this = this;
+        var sections = [];
+        var generalFields = {};
+        // Walk top-level paths
+        schema.eachPath(function (pathName, schemaType) {
+            var e_4, _a;
+            var _b, _c;
+            if (SYSTEM_FIELDS.has(pathName)) {
+                return;
+            }
+            var subSchema = schemaType.schema;
+            if (subSchema) {
+                // This is a nested subschema — make it a section
+                var _d = (0, populate_1.getOpenApiSpecForModel)({
+                    modelName: pathName,
+                    schema: subSchema,
+                }), properties = _d.properties, required = _d.required;
+                // Filter out system fields from the subschema too
+                var filteredProperties = {};
+                var filteredRequired = [];
+                try {
+                    for (var _e = __values(Object.entries(properties)), _f = _e.next(); !_f.done; _f = _e.next()) {
+                        var _g = __read(_f.value, 2), key = _g[0], val = _g[1];
+                        if (!SYSTEM_FIELDS.has(key)) {
+                            filteredProperties[key] = val;
+                            if (required.includes(key)) {
+                                filteredRequired.push(key);
+                            }
+                        }
+                    }
+                }
+                catch (e_4_1) { e_4 = { error: e_4_1 }; }
+                finally {
+                    try {
+                        if (_f && !_f.done && (_a = _e.return)) _a.call(_e);
+                    }
+                    finally { if (e_4) throw e_4.error; }
+                }
+                var sectionFields = extractFieldMeta(filteredProperties, filteredRequired, schema, pathName, _this.options.fieldOverrides);
+                // Get description from the parent path options
+                var opts = schemaType.options;
+                sections.push({
+                    description: opts === null || opts === void 0 ? void 0 : opts.description,
+                    displayName: toDisplayName(pathName),
+                    fields: sectionFields,
+                    name: pathName,
+                });
+            }
+            else {
+                // Scalar top-level field — goes into "General" section
+                var opts = schemaType.options;
+                var fullPath = pathName;
+                generalFields[pathName] = {
+                    default: opts === null || opts === void 0 ? void 0 : opts.default,
+                    description: opts === null || opts === void 0 ? void 0 : opts.description,
+                    enum: opts === null || opts === void 0 ? void 0 : opts.enum,
+                    required: (opts === null || opts === void 0 ? void 0 : opts.required) === true,
+                    secret: (opts === null || opts === void 0 ? void 0 : opts.secret) === true,
+                    type: _this.mongooseTypeToString(schemaType),
+                };
+                if ((_c = (_b = _this.options.fieldOverrides) === null || _b === void 0 ? void 0 : _b[fullPath]) === null || _c === void 0 ? void 0 : _c.widget) {
+                    generalFields[pathName].widget = _this.options.fieldOverrides[fullPath].widget;
+                }
+            }
+        });
+        // Add general fields section if there are any
+        if (Object.keys(generalFields).length > 0) {
+            sections.unshift({
+                displayName: "General",
+                fields: generalFields,
+                name: "__root__",
+            });
+        }
+        return { sections: sections };
+    };
+    ConfigurationApp.prototype.mongooseTypeToString = function (schemaType) {
+        var _a;
+        var instance = (_a = schemaType.instance) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+        if (instance === "objectid") {
+            return "string";
+        }
+        return instance !== null && instance !== void 0 ? instance : "string";
+    };
+    return ConfigurationApp;
+}());
+exports.ConfigurationApp = ConfigurationApp;

package/dist/configurationPlugin.d.ts

@@ -0,0 +1,102 @@
+import type { Document, Model, Schema } from "mongoose";
+/**
+ * Metadata for a secret field discovered by the configuration plugin.
+ */
+export interface SecretFieldMeta {
+    path: string;
+    secretProvider?: string;
+    secretName: string;
+}
+/**
+ * Interface for adapters that resolve secret values from external providers.
+ */
+export interface SecretProvider {
+    name: string;
+    getSecret(secretName: string): Promise<string | null>;
+}
+/**
+ * Options passed to configurationPlugin.
+ */
+export interface ConfigurationPluginOptions {
+    /**
+     * Secret provider used when resolveSecrets() is called without an explicit provider.
+     * Typically set during app startup so the model can resolve secrets on demand.
+     */
+    secretProvider?: SecretProvider;
+}
+/**
+ * All dot-notation paths for a type T.
+ * @example Paths<{a: {b: string}; c: number}> = "a" | "a.b" | "c"
+ */
+export type Paths<T extends object> = {
+    [K in keyof T & string]: T[K] extends object ? K | `${K}.${Paths<T[K]>}` : K;
+}[keyof T & string];
+/**
+ * The value type at a dot-notation path P within type T.
+ * @example PathValue<{a: {b: string}}, "a.b"> = string
+ */
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<NonNullable<T[K]>, Rest> : never : P extends keyof T ? T[P] : never;
+/**
+ * Deeply partial version of T, for use in updateConfig.
+ */
+export type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * Static methods added by configurationPlugin to the Mongoose model.
+ */
+export interface ConfigurationStatics<T extends object> {
+    /** Get the full singleton configuration document. */
+    getConfig(): Promise<T & Document>;
+    /** Get a specific value by dot-notation key. */
+    getConfig<P extends Paths<T>>(key: P): Promise<PathValue<T, P>>;
+    /** Update the singleton configuration document (deep merge). */
+    updateConfig(updates: DeepPartial<T>): Promise<T & Document>;
+    /** Get secret field metadata discovered from the schema. */
+    getSecretFields(): SecretFieldMeta[];
+    /**
+     * 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 a map of path -> value.
+     */
+    resolveSecrets(provider?: SecretProvider): Promise<Map<string, string>>;
+}
+/**
+ * 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
+ * ```
+ */
+export type ConfigurationModel<T extends object> = Model<T> & ConfigurationStatics<T>;
+/**
+ * Mongoose schema plugin that adds singleton configuration behavior.
+ *
+ * Adds:
+ * - Pre-save hook enforcing exactly one document
+ * - `getConfig()` static: fetches or creates the singleton (full doc or keyed value)
+ * - `updateConfig(updates)` static: patches the singleton
+ * - `getSecretFields()` static: returns metadata for fields with `secret: true`
+ * - `resolveSecrets(provider?)` static: fetches secret values, using the plugin provider by default
+ *
+ * Mark fields as secrets using schema path options:
+ * ```typescript
+ * const configSchema = new Schema({
+ *   apiKey: {
+ *     type: String,
+ *     description: "Third-party API key",
+ *     secret: true,
+ *     secretName: "my-api-key",
+ *   },
+ * });
+ * configSchema.plugin(configurationPlugin, {secretProvider: new EnvSecretProvider()});
+ * ```
+ */
+export declare const configurationPlugin: (schema: Schema, options?: ConfigurationPluginOptions) => void;