@terreno/api 0.19.0 → 0.20.1

package/dist/configurationPlugin.js

@@ -46,25 +46,108 @@ var __values = (this && this.__values) || function(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;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.configurationPlugin = void 0;
+exports.configurationPlugin = exports.flattenToDotPaths = void 0;
 var errors_1 = require("./errors");
 var logger_1 = require("./logger");
 var plugins_1 = require("./plugins");
 // ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Flattens a nested patch into MongoDB-style dotted paths, recursing into plain
+ * objects only; arrays and other values are treated as leaves.
+ *
+ * @example
+ * flattenToDotPaths({a: {b: 1}}) // => [["a.b", 1]]
+ */
+var flattenToDotPaths = function (obj, prefix) {
+    var e_1, _a;
+    if (prefix === void 0) { prefix = ""; }
+    var out = [];
+    try {
+        for (var _b = __values(Object.entries(obj)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var _d = __read(_c.value, 2), key = _d[0], value = _d[1];
+            var path = prefix ? "".concat(prefix, ".").concat(key) : key;
+            var isPlainObject = value !== null &&
+                typeof value === "object" &&
+                !Array.isArray(value) &&
+                Object.getPrototypeOf(value) === Object.prototype;
+            if (isPlainObject) {
+                out.push.apply(out, __spreadArray([], __read((0, exports.flattenToDotPaths)(value, path)), false));
+            }
+            else {
+                out.push([path, value]);
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return out;
+};
+exports.flattenToDotPaths = flattenToDotPaths;
+/**
+ * Builds the filter used to locate the singleton document. When the schema is
+ * soft-delete aware (has a `deleted` path, e.g. via `isDeletedPlugin`), the
+ * singleton is "the one non-deleted document"; otherwise any document matches.
+ */
+var buildSingletonFilter = function (schema) {
+    return schema.path("deleted") ? { deleted: false } : {};
+};
+// ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
 /**
  * Mongoose schema plugin that adds singleton configuration behavior.
  *
  * Adds:
- * - Pre-save hook enforcing exactly one document
+ * - 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
+ * - `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: fetches secret values, using the plugin provider by default
+ * - `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
  *
- * Mark fields as secrets using schema path options:
+ * 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: {
@@ -72,6 +155,7 @@ var plugins_1 = require("./plugins");
  *     description: "Third-party API key",
  *     secret: true,
  *     secretName: "my-api-key",
+ *     secretVersion: "3", // optional — resolves "latest" when omitted
  *   },
  * });
  * configSchema.plugin(configurationPlugin, {secretProvider: new EnvSecretProvider()});
@@ -81,27 +165,34 @@ var configurationPlugin = function (schema, options) {
     var pluginOptions = options !== null && options !== void 0 ? options : {};
     // Apply findOneOrNone so the singleton lookup avoids bare Model.findOne (idempotent).
     (0, plugins_1.findOneOrNone)(schema);
-    // Add a sentinel field with a unique index to enforce singleton at the DB level.
-    // All config documents get _singleton: "config", and the unique index prevents duplicates.
-    schema.add({
-        _singleton: {
-            default: "config",
-            description: "Sentinel field enforcing singleton constraint",
-            immutable: true,
-            select: false,
-            type: String,
-        },
-    });
-    schema.index({ _singleton: 1 }, { unique: true });
-    // Enforce singleton: only one document allowed (application-level guard)
+    // Optionally add a sentinel field with a unique index to enforce the singleton
+    // at the database level. This is opt-in (default off) so it does not conflict
+    // with consumers that already enforce a single non-deleted document via the
+    // pre-save guard below or via their own soft-delete plugin/indexes.
+    if (pluginOptions.enforceSingletonIndex) {
+        schema.add({
+            _singleton: {
+                default: "config",
+                description: "Sentinel field enforcing singleton constraint",
+                immutable: true,
+                select: false,
+                type: String,
+            },
+        });
+        schema.index({ _singleton: 1 }, { unique: true });
+    }
+    // Enforce singleton: only one non-deleted document allowed (application-level
+    // guard). Soft-delete-aware: a soft-deleted document does not block creating a
+    // new singleton.
     schema.pre("save", function () {
         return __awaiter(this, void 0, void 0, function () {
-            var existing;
+            var filter, existing;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
                         if (!this.isNew) return [3 /*break*/, 2];
-                        return [4 /*yield*/, this.constructor.exists({})];
+                        filter = buildSingletonFilter(schema);
+                        return [4 /*yield*/, this.constructor.exists(filter)];
                     case 1:
                         existing = _a.sent();
                         if (existing) {
@@ -135,14 +226,15 @@ var configurationPlugin = function (schema, options) {
     // Static: get the singleton configuration document or a value at a path (race-safe via upsert)
     schema.statics.getConfig = function (key) {
         return __awaiter(this, void 0, void 0, function () {
-            var findSingleton, config, created, err_1, parts, value, parts_1, parts_1_1, part;
-            var e_1, _a;
+            var singletonFilter, findSingleton, config, created, err_1, parts, value, parts_1, parts_1_1, part;
+            var e_2, _a;
             var _this = this;
             return __generator(this, function (_b) {
                 switch (_b.label) {
                     case 0:
+                        singletonFilter = buildSingletonFilter(this.schema);
                         findSingleton = function () {
-                            return _this.findOneOrNone({});
+                            return _this.findOneOrNone(singletonFilter);
                         };
                         return [4 /*yield*/, findSingleton()];
                     case 1:
@@ -181,32 +273,61 @@ var configurationPlugin = function (schema, options) {
                                 value = value[part];
                             }
                         }
-                        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                        catch (e_2_1) { e_2 = { error: e_2_1 }; }
                         finally {
                             try {
                                 if (parts_1_1 && !parts_1_1.done && (_a = parts_1.return)) _a.call(parts_1);
                             }
-                            finally { if (e_1) throw e_1.error; }
+                            finally { if (e_2) throw e_2.error; }
                         }
                         return [2 /*return*/, value];
                 }
             });
         });
     };
-    // Static: update the singleton configuration document (race-safe)
+    // Static: update the singleton configuration document via $set dotted paths.
+    // Flattening to dotted paths preserves sibling subdoc fields and tolerates
+    // legacy/out-of-schema fields already persisted on the document.
     schema.statics.updateConfig = function (updates) {
         return __awaiter(this, void 0, void 0, function () {
-            var config;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.getConfig()];
+            var singletonFilter, setFields, _a, _b, _c, path, value, updated;
+            var e_3, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        singletonFilter = buildSingletonFilter(this.schema);
+                        setFields = {};
+                        try {
+                            for (_a = __values((0, exports.flattenToDotPaths)(updates)), _b = _a.next(); !_b.done; _b = _a.next()) {
+                                _c = __read(_b.value, 2), path = _c[0], value = _c[1];
+                                setFields[path] = value;
+                            }
+                        }
+                        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                        finally {
+                            try {
+                                if (_b && !_b.done && (_d = _a.return)) _d.call(_a);
+                            }
+                            finally { if (e_3) throw e_3.error; }
+                        }
+                        // Nothing to set — return the current singleton (creating it if missing).
+                        if (Object.keys(setFields).length === 0) {
+                            return [2 /*return*/, this.getConfig()];
+                        }
+                        return [4 /*yield*/, this.findOneAndUpdate(singletonFilter, { $set: setFields }, { new: true, runValidators: true })];
                     case 1:
-                        config = _a.sent();
-                        Object.assign(config, updates);
-                        return [4 /*yield*/, config.save()];
+                        updated = _e.sent();
+                        if (updated) {
+                            return [2 /*return*/, updated];
+                        }
+                        // No singleton yet — create one (with subdocument defaults applied), then
+                        // apply the patch.
+                        return [4 /*yield*/, this.getConfig()];
                     case 2:
-                        _a.sent();
-                        return [2 /*return*/, config];
+                        // No singleton yet — create one (with subdocument defaults applied), then
+                        // apply the patch.
+                        _e.sent();
+                        return [2 /*return*/, this.findOneAndUpdate(singletonFilter, { $set: setFields }, { new: true, runValidators: true }).orFail()];
                 }
             });
         });
@@ -223,6 +344,7 @@ var configurationPlugin = function (schema, options) {
                         path: prefix ? "".concat(prefix, ".").concat(pathName) : pathName,
                         secretName: (_a = opts.secretName) !== null && _a !== void 0 ? _a : pathName,
                         secretProvider: opts.secretProvider,
+                        version: opts.secretVersion,
                     });
                 }
                 // Recurse into subschemas
@@ -238,7 +360,7 @@ var configurationPlugin = function (schema, options) {
     schema.statics.resolveSecrets = function (provider) {
         return __awaiter(this, void 0, void 0, function () {
             var resolvedProvider, secrets, resolved, results, failCount, results_1, results_1_1, result;
-            var e_2, _a;
+            var e_4, _a;
             var _this = this;
             return __generator(this, function (_b) {
                 switch (_b.label) {
@@ -254,7 +376,7 @@ var configurationPlugin = function (schema, options) {
                                 var value;
                                 return __generator(this, function (_a) {
                                     switch (_a.label) {
-                                        case 0: return [4 /*yield*/, resolvedProvider.getSecret(meta.secretName)];
+                                        case 0: return [4 /*yield*/, resolvedProvider.getSecret(meta.secretName, meta.version)];
                                         case 1:
                                             value = _a.sent();
                                             if (value !== null) {
@@ -276,12 +398,12 @@ var configurationPlugin = function (schema, options) {
                                 }
                             }
                         }
-                        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                        catch (e_4_1) { e_4 = { error: e_4_1 }; }
                         finally {
                             try {
                                 if (results_1_1 && !results_1_1.done && (_a = results_1.return)) _a.call(results_1);
                             }
-                            finally { if (e_2) throw e_2.error; }
+                            finally { if (e_4) throw e_4.error; }
                         }
                         if (failCount > 0) {
                             logger_1.logger.warn("".concat(failCount, "/").concat(secrets.length, " secrets failed to resolve"));

package/dist/configurationPlugin.test.js

@@ -89,6 +89,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
 var mongoose_1 = __importStar(require("mongoose"));
 var configurationPlugin_1 = require("./configurationPlugin");
+var plugins_1 = require("./plugins");
 var testConfigSchema = new mongoose_1.Schema({
     apiKey: {
         default: "",
@@ -133,14 +134,47 @@ var simpleSchema = new mongoose_1.Schema({
 });
 simpleSchema.plugin(configurationPlugin_1.configurationPlugin);
 var SimpleConfigModel = (0, mongoose_1.model)("SimpleConfiguration", simpleSchema);
+// --- Schema opting into the _singleton unique index ---
+var indexedSchema = new mongoose_1.Schema({
+    value: { default: "default", description: "A value", type: String },
+});
+indexedSchema.plugin(configurationPlugin_1.configurationPlugin, { enforceSingletonIndex: true });
+var IndexedConfigModel = (0, mongoose_1.model)("IndexedConfiguration", indexedSchema);
+// --- Soft-delete-aware schema ---
+var softDeleteSchema = new mongoose_1.Schema({
+    value: { default: "default", description: "A value", type: String },
+});
+softDeleteSchema.plugin(configurationPlugin_1.configurationPlugin);
+softDeleteSchema.plugin(plugins_1.isDeletedPlugin);
+var SoftDeleteConfigModel = (0, mongoose_1.model)("SoftDeleteConfiguration", softDeleteSchema);
+// --- Schema with a validated field (enum) for runValidators coverage ---
+var validatedSchema = new mongoose_1.Schema({
+    level: {
+        default: "low",
+        description: "Severity level",
+        enum: ["low", "medium", "high"],
+        type: String,
+    },
+});
+validatedSchema.plugin(configurationPlugin_1.configurationPlugin);
+var ValidatedConfigModel = (0, mongoose_1.model)("ValidatedConfiguration", validatedSchema);
 (0, bun_test_1.describe)("configurationPlugin", function () {
     (0, bun_test_1.describe)("schema setup", function () {
-        (0, bun_test_1.it)("adds a _singleton field with unique index", function () {
+        (0, bun_test_1.it)("does not add a _singleton index by default", function () {
             var indexes = SimpleConfigModel.schema.indexes();
             var singletonIndex = indexes.find(function (_a) {
                 var _b = __read(_a, 1), fields = _b[0];
                 return fields._singleton !== undefined;
             });
+            (0, bun_test_1.expect)(singletonIndex).toBeUndefined();
+            (0, bun_test_1.expect)(SimpleConfigModel.schema.path("_singleton")).toBeUndefined();
+        });
+        (0, bun_test_1.it)("adds a _singleton field with unique index when enforceSingletonIndex is true", function () {
+            var indexes = IndexedConfigModel.schema.indexes();
+            var singletonIndex = indexes.find(function (_a) {
+                var _b = __read(_a, 1), fields = _b[0];
+                return fields._singleton !== undefined;
+            });
             (0, bun_test_1.expect)(singletonIndex).toBeDefined();
             (0, bun_test_1.expect)(singletonIndex[1].unique).toBe(true);
         });
@@ -256,6 +290,55 @@ var SimpleConfigModel = (0, mongoose_1.model)("SimpleConfiguration", simpleSchem
                 }
             });
         }); });
+        (0, bun_test_1.it)("passes the discovered secret version to the provider", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var versionedSchema, VersionedModel, received, provider;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        versionedSchema = new mongoose_1.Schema({
+                            token: {
+                                default: "",
+                                description: "Pinned secret",
+                                secret: true,
+                                secretName: "pinned-token",
+                                secretVersion: "5",
+                                type: String,
+                            },
+                        });
+                        versionedSchema.plugin(configurationPlugin_1.configurationPlugin);
+                        VersionedModel = (0, mongoose_1.model)("VersionedConfiguration", versionedSchema);
+                        received = [];
+                        provider = {
+                            getSecret: function (name, version) { return __awaiter(void 0, void 0, void 0, function () {
+                                return __generator(this, function (_a) {
+                                    received.push({ name: name, version: version });
+                                    return [2 /*return*/, "value"];
+                                });
+                            }); },
+                            name: "versioned-provider",
+                        };
+                        return [4 /*yield*/, VersionedModel.resolveSecrets(provider)];
+                    case 1:
+                        _a.sent();
+                        (0, bun_test_1.expect)(received).toEqual([{ name: "pinned-token", version: "5" }]);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("flattenToDotPaths", function () {
+        (0, bun_test_1.it)("flattens nested plain objects into dotted paths", function () {
+            (0, bun_test_1.expect)((0, configurationPlugin_1.flattenToDotPaths)({ a: { b: 1 } })).toEqual([["a.b", 1]]);
+        });
+        (0, bun_test_1.it)("treats arrays as leaves", function () {
+            (0, bun_test_1.expect)((0, configurationPlugin_1.flattenToDotPaths)({ a: [1, 2] })).toEqual([["a", [1, 2]]]);
+        });
+        (0, bun_test_1.it)("treats null as a leaf and keeps top-level keys", function () {
+            (0, bun_test_1.expect)((0, configurationPlugin_1.flattenToDotPaths)({ a: null, b: "x" })).toEqual([
+                ["a", null],
+                ["b", "x"],
+            ]);
+        });
     });
     (0, bun_test_1.describe)("singleton behavior (requires MongoDB)", function () {
         var dbConnected = false;
@@ -425,6 +508,38 @@ var SimpleConfigModel = (0, mongoose_1.model)("SimpleConfiguration", simpleSchem
                 }
             });
         }); });
+        (0, bun_test_1.it)("runs schema validators on updateConfig (rejects invalid enum)", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var _a, ok;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        if (!dbConnected) {
+                            return [2 /*return*/];
+                        }
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, ValidatedConfigModel.collection.drop()];
+                    case 2:
+                        _b.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        _a = _b.sent();
+                        return [3 /*break*/, 4];
+                    case 4: return [4 /*yield*/, ValidatedConfigModel.getConfig()];
+                    case 5:
+                        _b.sent();
+                        return [4 /*yield*/, (0, bun_test_1.expect)(ValidatedConfigModel.updateConfig({ level: "bogus" })).rejects.toThrow()];
+                    case 6:
+                        _b.sent();
+                        return [4 /*yield*/, ValidatedConfigModel.updateConfig({ level: "high" })];
+                    case 7:
+                        ok = _b.sent();
+                        (0, bun_test_1.expect)(ok.level).toBe("high");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
         (0, bun_test_1.it)("prevents deleteOne", function () { return __awaiter(void 0, void 0, void 0, function () {
             var err_1;
             return __generator(this, function (_a) {
@@ -507,4 +622,126 @@ var SimpleConfigModel = (0, mongoose_1.model)("SimpleConfiguration", simpleSchem
             });
         }); });
     });
+    (0, bun_test_1.describe)("soft-delete-aware singleton (requires MongoDB)", function () {
+        var dbConnected = false;
+        (0, bun_test_1.beforeAll)(function () { return __awaiter(void 0, void 0, void 0, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 4, , 5]);
+                        if (!(mongoose_1.default.connection.readyState === 1)) return [3 /*break*/, 1];
+                        dbConnected = true;
+                        return [3 /*break*/, 3];
+                    case 1: return [4 /*yield*/, mongoose_1.default.connect("mongodb://127.0.0.1/terreno-config-test", {
+                            connectTimeoutMS: 3000,
+                            serverSelectionTimeoutMS: 3000,
+                        })];
+                    case 2:
+                        _b.sent();
+                        dbConnected = true;
+                        _b.label = 3;
+                    case 3: return [3 /*break*/, 5];
+                    case 4:
+                        _a = _b.sent();
+                        dbConnected = false;
+                        return [3 /*break*/, 5];
+                    case 5: return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        if (!dbConnected) {
+                            return [2 /*return*/];
+                        }
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, SoftDeleteConfigModel.collection.drop()];
+                    case 2:
+                        _b.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        _a = _b.sent();
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("operates on the non-deleted singleton", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var config, updated;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!dbConnected) {
+                            return [2 /*return*/];
+                        }
+                        return [4 /*yield*/, SoftDeleteConfigModel.getConfig()];
+                    case 1:
+                        config = _a.sent();
+                        (0, bun_test_1.expect)(config.value).toBe("default");
+                        return [4 /*yield*/, SoftDeleteConfigModel.updateConfig({ value: "live" })];
+                    case 2:
+                        updated = _a.sent();
+                        (0, bun_test_1.expect)(updated.value).toBe("live");
+                        (0, bun_test_1.expect)(updated.deleted).toBe(false);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("allows a new singleton after the existing one is soft-deleted", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var first, second;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!dbConnected) {
+                            return [2 /*return*/];
+                        }
+                        return [4 /*yield*/, SoftDeleteConfigModel.getConfig()];
+                    case 1:
+                        first = _a.sent();
+                        // Soft delete by setting deleted: true (allowed)
+                        first.deleted = true;
+                        return [4 /*yield*/, first.save()];
+                    case 2:
+                        _a.sent();
+                        return [4 /*yield*/, SoftDeleteConfigModel.getConfig()];
+                    case 3:
+                        second = _a.sent();
+                        (0, bun_test_1.expect)(second.deleted).toBe(false);
+                        (0, bun_test_1.expect)(second._id.toString()).not.toBe(first._id.toString());
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("does not let updateConfig touch a soft-deleted document", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var first, updated;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!dbConnected) {
+                            return [2 /*return*/];
+                        }
+                        return [4 /*yield*/, SoftDeleteConfigModel.getConfig()];
+                    case 1:
+                        first = _a.sent();
+                        first.deleted = true;
+                        return [4 /*yield*/, first.save()];
+                    case 2:
+                        _a.sent();
+                        return [4 /*yield*/, SoftDeleteConfigModel.updateConfig({ value: "fresh" })];
+                    case 3:
+                        updated = _a.sent();
+                        (0, bun_test_1.expect)(updated.deleted).toBe(false);
+                        (0, bun_test_1.expect)(updated.value).toBe("fresh");
+                        (0, bun_test_1.expect)(updated._id.toString()).not.toBe(first._id.toString());
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
 });

package/dist/secretProviders.d.ts

@@ -15,7 +15,11 @@ import type { SecretProvider } from "./configurationPlugin";
  */
 export declare class EnvSecretProvider implements SecretProvider {
     name: string;
-    getSecret(secretName: string): Promise<string | null>;
+    /**
+     * Resolve a secret from an environment variable. Environment variables have no
+     * versions, so the optional `version` parameter is ignored.
+     */
+    getSecret(secretName: string, _version?: string): Promise<string | null>;
 }
 /**
  * Options for GcpSecretProvider.
@@ -43,5 +47,78 @@ export declare class GcpSecretProvider implements SecretProvider {
     private client;
     constructor(options: GcpSecretProviderOptions);
     private getClient;
-    getSecret(secretName: string): Promise<string | null>;
+    /**
+     * Resolve a secret from Google Cloud Secret Manager.
+     *
+     * @param secretName - A short secret id (e.g. "openai-api-key") or a full
+     *   resource path (e.g. "projects/p/secrets/s" or
+     *   "projects/p/secrets/s/versions/3").
+     * @param version - Optional version to resolve when `secretName` is a short id
+     *   (e.g. "3"). Defaults to "latest". Ignored when `secretName` already
+     *   contains an explicit `/versions/...` suffix.
+     */
+    getSecret(secretName: string, version?: string): Promise<string | null>;
+}
+/**
+ * Secret provider that delegates to an ordered list of providers, returning the
+ * first non-null result.
+ *
+ * A provider that throws is warn-logged (secret name only — never the value) and
+ * resolution falls through to the next provider. This makes it easy to compose a
+ * primary provider with a fallback, e.g. GCP with an environment-variable
+ * fallback:
+ *
+ * @example
+ * ```typescript
+ * const provider = new CompositeSecretProvider([
+ *   new GcpSecretProvider({projectId: "my-project"}),
+ *   new EnvSecretProvider(),
+ * ]);
+ * const key = await provider.getSecret("openai-api-key");
+ * ```
+ */
+export declare class CompositeSecretProvider implements SecretProvider {
+    name: string;
+    private providers;
+    constructor(providers: SecretProvider[]);
+    getSecret(secretName: string, version?: string): Promise<string | null>;
+}
+/**
+ * Options for CachingSecretProvider.
+ */
+export interface CachingSecretProviderOptions {
+    /** Time-to-live for cached values, in milliseconds. Defaults to 60_000 (1 minute). */
+    ttlMs?: number;
+}
+/**
+ * Secret provider that wraps any provider with an in-memory TTL cache.
+ *
+ * Cache entries are keyed by `secretName@version` so that pinned versions are
+ * cached independently. `null` results (secret not found) are cached too, to
+ * avoid hammering the underlying provider for missing secrets. Secret values are
+ * never logged.
+ *
+ * Use `clear()` to drop the entire cache (e.g. on rotation) or `clearKey()` to
+ * invalidate a single secret.
+ *
+ * @example
+ * ```typescript
+ * const provider = new CachingSecretProvider(
+ *   new CompositeSecretProvider([gcp, env]),
+ *   {ttlMs: 30_000}
+ * );
+ * ```
+ */
+export declare class CachingSecretProvider implements SecretProvider {
+    name: string;
+    private provider;
+    private ttlMs;
+    private cache;
+    constructor(provider: SecretProvider, options?: CachingSecretProviderOptions);
+    private cacheKey;
+    getSecret(secretName: string, version?: string): Promise<string | null>;
+    /** Clears the entire cache. Useful on secret rotation and in tests. */
+    clear(): void;
+    /** Invalidates a single cached secret by name (and optional version). */
+    clearKey(secretName: string, version?: string): void;
 }