@terreno/api 0.13.3 → 0.14.0

package/dist/auth.test.js

@@ -99,22 +99,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var supertest_1 = __importDefault(require("supertest"));
 var api_1 = require("./api");
 var auth_1 = require("./auth");
 var expressServer_1 = require("./expressServer");
 var permissions_1 = require("./permissions");
+var requestContext_1 = require("./requestContext");
 var tests_1 = require("./tests");
 var transformers_1 = require("./transformers");
 var utils_1 = require("./utils");
+var decodeTokenPayload = function (token) {
+    var encodedPayload = token.split(".")[1];
+    return JSON.parse(Buffer.from(encodedPayload, "base64url").toString("utf8"));
+};
 (0, bun_test_1.describe)("auth tests", function () {
     var app;
     var admin;
+    var contextEvents;
     var notAdmin;
     var agent;
     (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
         function addRoutes(router) {
+            var _this = this;
             router.use("/food", (0, api_1.modelRouter)(tests_1.FoodModel, {
                 allowAnonymous: true,
                 permissions: {
@@ -141,6 +149,58 @@ var utils_1 = require("./utils");
                     ownerWriteFields: ["name", "calories", "created"],
                 }),
             }));
+            router.use("/context-food", (0, api_1.modelRouter)(tests_1.FoodModel, {
+                permissions: {
+                    create: [permissions_1.Permissions.IsAuthenticated],
+                    delete: [],
+                    list: [],
+                    read: [],
+                    update: [],
+                },
+                postCreate: function (_value, req) { return __awaiter(_this, void 0, void 0, function () {
+                    var _a, _b;
+                    return __generator(this, function (_c) {
+                        contextEvents.push({
+                            currentSessionId: (_a = (0, requestContext_1.getCurrentRequestContext)()) === null || _a === void 0 ? void 0 : _a.sessionId,
+                            requestId: req.requestId,
+                            sessionId: req.sessionId,
+                            stage: "postCreate",
+                            userId: (_b = req.user) === null || _b === void 0 ? void 0 : _b.id,
+                        });
+                        return [2 /*return*/];
+                    });
+                }); },
+                preCreate: function (body, req) {
+                    var _a, _b, _c, _d;
+                    contextEvents.push({
+                        currentSessionId: (_a = (0, requestContext_1.getCurrentRequestContext)()) === null || _a === void 0 ? void 0 : _a.sessionId,
+                        requestId: req.requestId,
+                        sessionId: req.sessionId,
+                        stage: "preCreate",
+                        userId: (_b = req.user) === null || _b === void 0 ? void 0 : _b.id,
+                    });
+                    return __assign(__assign({}, body), { categories: [], eatenBy: [(_c = req.user) === null || _c === void 0 ? void 0 : _c._id], expiration: "2026-01-01", lastEatenWith: {}, likesIds: [], ownerId: (_d = req.user) === null || _d === void 0 ? void 0 : _d._id, source: { name: "context-test" }, tags: [] });
+                },
+                responseHandler: function (value, method, req) { return __awaiter(_this, void 0, void 0, function () {
+                    var _a, _b, _c, _d, _e, _f, _g, _h;
+                    return __generator(this, function (_j) {
+                        contextEvents.push({
+                            currentSessionId: (_a = (0, requestContext_1.getCurrentRequestContext)()) === null || _a === void 0 ? void 0 : _a.sessionId,
+                            requestId: req.requestId,
+                            sessionId: req.sessionId,
+                            stage: "responseHandler:".concat(method),
+                            userId: (_b = req.user) === null || _b === void 0 ? void 0 : _b.id,
+                        });
+                        return [2 /*return*/, {
+                                id: String(value._id),
+                                requestId: (_c = req.requestId) !== null && _c !== void 0 ? _c : null,
+                                sessionContext: (_e = (_d = (0, requestContext_1.getCurrentRequestContext)()) === null || _d === void 0 ? void 0 : _d.sessionId) !== null && _e !== void 0 ? _e : null,
+                                sessionId: (_f = req.sessionId) !== null && _f !== void 0 ? _f : null,
+                                userId: (_h = (_g = req.user) === null || _g === void 0 ? void 0 : _g.id) !== null && _h !== void 0 ? _h : null,
+                            }];
+                    });
+                }); },
+            }));
         }
         var _a;
         return __generator(this, function (_b) {
@@ -152,6 +212,7 @@ var utils_1 = require("./utils");
                     return [4 /*yield*/, (0, tests_1.setupDb)()];
                 case 1:
                     _a = __read.apply(void 0, [_b.sent(), 2]), admin = _a[0], notAdmin = _a[1];
+                    contextEvents = [];
                     return [4 /*yield*/, Promise.all([
                             tests_1.FoodModel.create({
                                 calories: 1,
@@ -346,6 +407,104 @@ var utils_1 = require("./utils");
             }
         });
     }); });
+    (0, bun_test_1.it)("passes request and session context through modelRouter hooks", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var loginRes, loginTokenPayload, createRes, sessionId;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, agent
+                        .post("/auth/login")
+                        .send({ email: "admin@example.com", password: "securePassword" })
+                        .expect(200)];
+                case 1:
+                    loginRes = _a.sent();
+                    loginTokenPayload = decodeTokenPayload(loginRes.body.data.token);
+                    return [4 /*yield*/, agent
+                            .post("/context-food")
+                            .set("authorization", "Bearer ".concat(loginRes.body.data.token))
+                            .set("X-Request-ID", "model-router-request-1")
+                            .send({ calories: 10, name: "Context Apple" })
+                            .expect(201)];
+                case 2:
+                    createRes = _a.sent();
+                    (0, bun_test_1.expect)(loginTokenPayload.sid).toBeDefined();
+                    sessionId = loginTokenPayload.sid;
+                    if (!sessionId) {
+                        throw new Error("Expected login token to include a session id");
+                    }
+                    (0, bun_test_1.expect)(createRes.headers["x-request-id"]).toBe("model-router-request-1");
+                    (0, bun_test_1.expect)(createRes.headers["x-session-id"]).toBe(sessionId);
+                    (0, bun_test_1.expect)(createRes.body.data.requestId).toBe("model-router-request-1");
+                    (0, bun_test_1.expect)(createRes.body.data.sessionId).toBe(sessionId);
+                    (0, bun_test_1.expect)(createRes.body.data.sessionContext).toBe(sessionId);
+                    (0, bun_test_1.expect)(createRes.body.data.userId).toBe(String(admin._id));
+                    (0, bun_test_1.expect)(contextEvents).toEqual([
+                        {
+                            currentSessionId: sessionId,
+                            requestId: "model-router-request-1",
+                            sessionId: sessionId,
+                            stage: "preCreate",
+                            userId: String(admin._id),
+                        },
+                        {
+                            currentSessionId: sessionId,
+                            requestId: "model-router-request-1",
+                            sessionId: sessionId,
+                            stage: "postCreate",
+                            userId: String(admin._id),
+                        },
+                        {
+                            currentSessionId: sessionId,
+                            requestId: "model-router-request-1",
+                            sessionId: sessionId,
+                            stage: "responseHandler:create",
+                            userId: String(admin._id),
+                        },
+                    ]);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("preserves JWT session id across refresh and request context", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var loginRes, loginTokenPayload, loginRefreshPayload, loginSessionId, refreshRes, refreshedTokenPayload, refreshedRefreshPayload, foodRes;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, agent
+                        .post("/auth/login")
+                        .send({ email: "admin@example.com", password: "securePassword" })
+                        .expect(200)];
+                case 1:
+                    loginRes = _a.sent();
+                    loginTokenPayload = decodeTokenPayload(loginRes.body.data.token);
+                    loginRefreshPayload = decodeTokenPayload(loginRes.body.data.refreshToken);
+                    (0, bun_test_1.expect)(loginTokenPayload.sid).toBeDefined();
+                    loginSessionId = loginTokenPayload.sid;
+                    if (!loginSessionId) {
+                        throw new Error("Expected login token to include a session id");
+                    }
+                    (0, bun_test_1.expect)(loginRefreshPayload.sid).toBe(loginSessionId);
+                    (0, bun_test_1.expect)(loginRes.headers["x-session-id"]).toBe(loginSessionId);
+                    return [4 /*yield*/, agent
+                            .post("/auth/refresh_token")
+                            .send({ refreshToken: loginRes.body.data.refreshToken })
+                            .expect(200)];
+                case 2:
+                    refreshRes = _a.sent();
+                    refreshedTokenPayload = decodeTokenPayload(refreshRes.body.data.token);
+                    refreshedRefreshPayload = decodeTokenPayload(refreshRes.body.data.refreshToken);
+                    (0, bun_test_1.expect)(refreshedTokenPayload.sid).toBe(loginSessionId);
+                    (0, bun_test_1.expect)(refreshedRefreshPayload.sid).toBe(loginSessionId);
+                    (0, bun_test_1.expect)(refreshRes.headers["x-session-id"]).toBe(loginSessionId);
+                    return [4 /*yield*/, agent
+                            .get("/food")
+                            .set("authorization", "Bearer ".concat(refreshRes.body.data.token))
+                            .expect(200)];
+                case 3:
+                    foodRes = _a.sent();
+                    (0, bun_test_1.expect)(foodRes.headers["x-session-id"]).toBe(loginSessionId);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
     (0, bun_test_1.it)("completes token login e2e", function () { return __awaiter(void 0, void 0, void 0, function () {
         var res, _a, userId, token, meRes, mePatchRes, getRes, food, updateRes;
         return __generator(this, function (_b) {

package/dist/betterAuthApp.test.js

@@ -83,6 +83,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var express_1 = __importDefault(require("express"));
 var mongodb_memory_server_1 = require("mongodb-memory-server");

package/dist/betterAuthSetup.d.ts

@@ -15,9 +15,12 @@ export type BetterAuthInstance = ReturnType<typeof betterAuth>;
 /**
  * Options for creating a Better Auth instance.
  */
+export interface MongoClientLike {
+    db: () => any;
+}
 export interface CreateBetterAuthOptions {
     config: BetterAuthConfig;
-    mongoClient: any;
+    mongoClient: MongoClientLike;
     userModel?: UserModel;
 }
 /**
@@ -29,10 +32,6 @@ export declare const createBetterAuth: (options: CreateBetterAuthOptions) => Bet
  * and populates req.user with the application User model.
  */
 export declare const createBetterAuthSessionMiddleware: (auth: BetterAuthInstance, userModel?: UserModel) => (req: Request, _res: Response, next: NextFunction) => Promise<void>;
-/**
- * Syncs a Better Auth user to the application User model.
- * Creates or updates the user as needed.
- */
 export declare const syncBetterAuthUser: (userModel: UserModel, betterAuthUser: BetterAuthUser, oauthProvider?: string) => Promise<any>;
 /**
  * Mounts Better Auth routes on the Express app.
@@ -41,7 +40,7 @@ export declare const mountBetterAuthRoutes: (app: Application, auth: BetterAuthI
 /**
  * Gets the MongoDB client from the mongoose connection.
  */
-export declare const getMongoClientFromMongoose: () => any;
+export declare const getMongoClientFromMongoose: () => MongoClientLike;
 /**
  * Sets up Better Auth user sync hooks.
  * This ensures users created/updated in Better Auth are synced to the application User model.

package/dist/betterAuthSetup.js

@@ -63,6 +63,7 @@ var node_1 = require("better-auth/node");
 var mongoose_1 = __importDefault(require("mongoose"));
 var logger_1 = require("./logger");
 var plugins_1 = require("./plugins");
+var requestContext_1 = require("./requestContext");
 /**
  * Creates a Better Auth instance with MongoDB adapter.
  */
@@ -123,7 +124,7 @@ exports.createBetterAuth = createBetterAuth;
  */
 var createBetterAuthSessionMiddleware = function (auth, userModel) {
     return function (req, _res, next) { return __awaiter(void 0, void 0, void 0, function () {
-        var session, betterAuthUser, appUser, newUser, error_1;
+        var session, betterAuthUser, reqWithSession, appUser, newUser, error_1;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -135,6 +136,7 @@ var createBetterAuthSessionMiddleware = function (auth, userModel) {
                     session = _a.sent();
                     if (!((session === null || session === void 0 ? void 0 : session.user) && (session === null || session === void 0 ? void 0 : session.session))) return [3 /*break*/, 7];
                     betterAuthUser = session.user;
+                    reqWithSession = req;
                     if (!userModel) return [3 /*break*/, 6];
                     return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(userModel, {
                             betterAuthId: betterAuthUser.id,
@@ -142,19 +144,21 @@ var createBetterAuthSessionMiddleware = function (auth, userModel) {
                 case 2:
                     appUser = _a.sent();
                     if (!appUser) return [3 /*break*/, 3];
-                    req.user = appUser;
-                    req.betterAuthSession = session;
+                    reqWithSession.user = appUser;
+                    reqWithSession.betterAuthSession = session;
+                    (0, requestContext_1.updateRequestContextFromRequest)(req);
                     return [3 /*break*/, 5];
                 case 3: return [4 /*yield*/, (0, exports.syncBetterAuthUser)(userModel, betterAuthUser)];
                 case 4:
                     newUser = _a.sent();
-                    req.user = newUser;
-                    req.betterAuthSession = session;
+                    reqWithSession.user = newUser;
+                    reqWithSession.betterAuthSession = session;
+                    (0, requestContext_1.updateRequestContextFromRequest)(req);
                     _a.label = 5;
                 case 5: return [3 /*break*/, 7];
                 case 6:
                     // No user model - just attach the Better Auth user directly
-                    req.user = {
+                    reqWithSession.user = {
                         _id: betterAuthUser.id,
                         admin: false,
                         betterAuthId: betterAuthUser.id,
@@ -162,7 +166,8 @@ var createBetterAuthSessionMiddleware = function (auth, userModel) {
                         id: betterAuthUser.id,
                         name: betterAuthUser.name,
                     };
-                    req.betterAuthSession = session;
+                    reqWithSession.betterAuthSession = session;
+                    (0, requestContext_1.updateRequestContextFromRequest)(req);
                     _a.label = 7;
                 case 7:
                     next();
@@ -178,11 +183,9 @@ var createBetterAuthSessionMiddleware = function (auth, userModel) {
     }); };
 };
 exports.createBetterAuthSessionMiddleware = createBetterAuthSessionMiddleware;
-/**
- * Syncs a Better Auth user to the application User model.
- * Creates or updates the user as needed.
- */
-var syncBetterAuthUser = function (userModel, betterAuthUser, oauthProvider) { return __awaiter(void 0, void 0, void 0, function () {
+var syncBetterAuthUser = function (userModel, betterAuthUser, oauthProvider
+// biome-ignore lint/suspicious/noExplicitAny: return is a consumer-defined user document; tests inspect varied fields
+) { return __awaiter(void 0, void 0, void 0, function () {
     var existingUser, userByEmail, useAsId, newUser, error_2;
     return __generator(this, function (_a) {
         switch (_a.label) {
@@ -192,7 +195,7 @@ var syncBetterAuthUser = function (userModel, betterAuthUser, oauthProvider) { r
                         betterAuthId: betterAuthUser.id,
                     })];
             case 1:
-                existingUser = _a.sent();
+                existingUser = (_a.sent());
                 if (!existingUser) return [3 /*break*/, 3];
                 // Update existing user if needed
                 existingUser.email = betterAuthUser.email;
@@ -207,7 +210,7 @@ var syncBetterAuthUser = function (userModel, betterAuthUser, oauthProvider) { r
                     email: betterAuthUser.email,
                 })];
             case 4:
-                userByEmail = _a.sent();
+                userByEmail = (_a.sent());
                 if (!userByEmail) return [3 /*break*/, 6];
                 // Link existing user to Better Auth
                 userByEmail.betterAuthId = betterAuthUser.id;

package/dist/betterAuthSetup.test.js

@@ -83,6 +83,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var express_1 = __importDefault(require("express"));
 var mongodb_memory_server_1 = require("mongodb-memory-server");

package/dist/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Runtime configuration registry with a fixed resolution order:
+ *
+ *   1. In-process override (Config.setOverride) — highest, for tests/bootstrap
+ *   2. Cached env map — typically loaded from an admin-editable Mongoose document
+ *   3. process.env
+ *   4. Registered default
+ *
+ * Why a registry: every key migrating off raw `process.env` declares its type
+ * and default in one place. That keeps the admin UI honest (no surprise keys),
+ * gives synchronous access without scattered `?? "default"` literals at call
+ * sites, and lets tests assert behavior against a single source of truth.
+ *
+ * Why sync: hundreds of call sites read configuration during request handling
+ * and module init; an async API would force enormous refactors. Callers load
+ * the env map once via `Config.refresh()` after Mongo connects, then read
+ * synchronously from cache.
+ *
+ * The mechanism is agnostic to where the env map comes from. Apps wire up
+ * their backing store with `Config.setEnvLoader(fn)`. The optional
+ * `envConfigurationPlugin` provides a drop-in Mongoose schema integration.
+ */
+export interface ConfigRegistration {
+    /** Default returned when neither override, cache, nor process.env supplies a value. */
+    default?: string;
+    /** Documentation surfaced in the admin UI. */
+    description?: string;
+    /** Marks the key as a secret so admin UI can mask the value. */
+    secret?: boolean;
+}
+export declare const Config: {
+    clearOverrides: () => void;
+    clearRegistryForTesting: () => void;
+    get: (key: string) => string | undefined;
+    getBoolean: (key: string) => boolean;
+    getDefault: (key: string) => string | undefined;
+    getJSON: <T = unknown>(key: string) => T | undefined;
+    getNumber: (key: string) => number | undefined;
+    getRegisteredKeys: () => string[];
+    getRegistration: (key: string) => ConfigRegistration | undefined;
+    isRegistered: (key: string) => boolean;
+    refresh: () => Promise<void>;
+    register: (key: string, registration?: ConfigRegistration) => void;
+    setCachedEnv: (env: Record<string, string> | null) => void;
+    setEnvLoader: (loader: (() => Promise<Record<string, string>>) | null) => void;
+    setOverride: (key: string, value: string | undefined) => void;
+};
+export type ConfigType = typeof Config;

package/dist/config.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Runtime configuration registry with a fixed resolution order:
+ *
+ *   1. In-process override (Config.setOverride) — highest, for tests/bootstrap
+ *   2. Cached env map — typically loaded from an admin-editable Mongoose document
+ *   3. process.env
+ *   4. Registered default
+ *
+ * Why a registry: every key migrating off raw `process.env` declares its type
+ * and default in one place. That keeps the admin UI honest (no surprise keys),
+ * gives synchronous access without scattered `?? "default"` literals at call
+ * sites, and lets tests assert behavior against a single source of truth.
+ *
+ * Why sync: hundreds of call sites read configuration during request handling
+ * and module init; an async API would force enormous refactors. Callers load
+ * the env map once via `Config.refresh()` after Mongo connects, then read
+ * synchronously from cache.
+ *
+ * The mechanism is agnostic to where the env map comes from. Apps wire up
+ * their backing store with `Config.setEnvLoader(fn)`. The optional
+ * `envConfigurationPlugin` provides a drop-in Mongoose schema integration.
+ */
+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 __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.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = void 0;
+var overrides = new Map();
+var cachedEnv = null;
+var envLoader = null;
+// Null-prototype object so lookups don't resolve inherited keys like
+// `constructor` / `toString` as accidentally-registered entries.
+var REGISTRY = Object.create(null);
+/**
+ * Registers a configuration key, its default, and metadata. Re-registration
+ * of the same key throws so duplicates surface at boot.
+ */
+var register = function (key, registration) {
+    if (registration === void 0) { registration = {}; }
+    if (REGISTRY[key]) {
+        throw new Error("Config key \"".concat(key, "\" registered more than once"));
+    }
+    REGISTRY[key] = registration;
+};
+/**
+ * Returns the configured string value for `key`, applying the resolution
+ * order documented at the top of this file. Returns `undefined` if no
+ * source supplies a value and no default was registered.
+ */
+var getString = function (key) {
+    var _a;
+    if (overrides.has(key)) {
+        return overrides.get(key);
+    }
+    if (cachedEnv && key in cachedEnv) {
+        var v = cachedEnv[key];
+        if (v !== undefined && v !== "") {
+            return v;
+        }
+    }
+    // Guard against process.env keys like "toString" / "constructor" inheriting
+    // a function from Object.prototype. Only accept string values.
+    var fromProcess = process.env[key];
+    if (typeof fromProcess === "string" && fromProcess !== "") {
+        return fromProcess;
+    }
+    return (_a = REGISTRY[key]) === null || _a === void 0 ? void 0 : _a.default;
+};
+/**
+ * Returns the configured value as a number. Throws if a value is present but
+ * not finite — silent NaN propagation has bitten apps before.
+ */
+var getNumber = function (key) {
+    var raw = getString(key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    // Number() rejects partially-numeric strings like "5000ms" (returns NaN)
+    // whereas parseFloat would silently truncate to 5000.
+    var parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        throw new Error("Config key \"".concat(key, "\" is not a valid number: ").concat(JSON.stringify(raw)));
+    }
+    return parsed;
+};
+/**
+ * Returns true iff the string value equals "true" (case-insensitive). Mirrors
+ * the existing `process.env.X === "true"` idiom.
+ */
+var getBoolean = function (key) {
+    var raw = getString(key);
+    return raw !== undefined && raw.toLowerCase() === "true";
+};
+/**
+ * Parses a JSON-encoded config value. Returns undefined if unset; throws on
+ * malformed JSON so misconfiguration fails loud at the call site rather than
+ * producing silent runtime errors later.
+ */
+var getJSON = function (key) {
+    var raw = getString(key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error("Config key \"".concat(key, "\" is not valid JSON: ").concat(error.message));
+    }
+};
+/**
+ * Registers a loader that returns the env map (typically backed by an
+ * admin-editable Mongoose document). Called once at app startup before
+ * the first `Config.refresh()`.
+ */
+var setEnvLoader = function (loader) {
+    envLoader = loader;
+};
+/**
+ * Reloads the in-memory cache by invoking the registered env loader. No-op
+ * (clears cache) if no loader has been registered.
+ */
+var refresh = function () { return __awaiter(void 0, void 0, void 0, function () {
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                if (!envLoader) {
+                    cachedEnv = {};
+                    return [2 /*return*/];
+                }
+                return [4 /*yield*/, envLoader()];
+            case 1:
+                cachedEnv = _a.sent();
+                return [2 /*return*/];
+        }
+    });
+}); };
+/** Replaces the cache directly. Intended for the envConfigurationPlugin and tests. */
+var setCachedEnv = function (env) {
+    cachedEnv = env;
+};
+/**
+ * Sets an in-process override for `key`. Highest precedence — wins over
+ * the cached env map. Intended for tests and bootstrap helpers.
+ */
+var setOverride = function (key, value) {
+    overrides.set(key, value);
+};
+/** Clears every override. Call from afterEach in tests. */
+var clearOverrides = function () {
+    overrides.clear();
+};
+/** Returns the registered default (if any) for `key`. */
+var getDefault = function (key) {
+    var _a;
+    return (_a = REGISTRY[key]) === null || _a === void 0 ? void 0 : _a.default;
+};
+/** Returns the registration metadata for `key`, including secret/description. */
+var getRegistration = function (key) {
+    return REGISTRY[key];
+};
+/** Returns the registered keys, sorted. Used by the admin UI. */
+var getRegisteredKeys = function () {
+    return Object.keys(REGISTRY).sort();
+};
+/** Returns true if `key` was registered. */
+var isRegistered = function (key) {
+    return key in REGISTRY;
+};
+/** Removes every registered key. Intended for tests. */
+var clearRegistryForTesting = function () {
+    var e_1, _a;
+    try {
+        for (var _b = __values(Object.keys(REGISTRY)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var key = _c.value;
+            delete REGISTRY[key];
+        }
+    }
+    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; }
+    }
+};
+exports.Config = {
+    clearOverrides: clearOverrides,
+    clearRegistryForTesting: clearRegistryForTesting,
+    get: getString,
+    getBoolean: getBoolean,
+    getDefault: getDefault,
+    getJSON: getJSON,
+    getNumber: getNumber,
+    getRegisteredKeys: getRegisteredKeys,
+    getRegistration: getRegistration,
+    isRegistered: isRegistered,
+    refresh: refresh,
+    register: register,
+    setCachedEnv: setCachedEnv,
+    setEnvLoader: setEnvLoader,
+    setOverride: setOverride,
+};

package/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};