@terreno/api 0.11.8 → 0.11.9

package/dist/betterAuthSetup.js

@@ -62,6 +62,7 @@ var mongodb_1 = require("better-auth/adapters/mongodb");
 var node_1 = require("better-auth/node");
 var mongoose_1 = __importDefault(require("mongoose"));
 var logger_1 = require("./logger");
+var plugins_1 = require("./plugins");
 /**
  * Creates a Better Auth instance with MongoDB adapter.
  */
@@ -135,7 +136,9 @@ var createBetterAuthSessionMiddleware = function (auth, userModel) {
                     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;
                     if (!userModel) return [3 /*break*/, 6];
-                    return [4 /*yield*/, userModel.findOne({ betterAuthId: betterAuthUser.id })];
+                    return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(userModel, {
+                            betterAuthId: betterAuthUser.id,
+                        })];
                 case 2:
                     appUser = _a.sent();
                     if (!appUser) return [3 /*break*/, 3];
@@ -185,7 +188,9 @@ var syncBetterAuthUser = function (userModel, betterAuthUser, oauthProvider) { r
         switch (_a.label) {
             case 0:
                 _a.trys.push([0, 8, , 9]);
-                return [4 /*yield*/, userModel.findOne({ betterAuthId: betterAuthUser.id })];
+                return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(userModel, {
+                        betterAuthId: betterAuthUser.id,
+                    })];
             case 1:
                 existingUser = _a.sent();
                 if (!existingUser) return [3 /*break*/, 3];
@@ -198,7 +203,9 @@ var syncBetterAuthUser = function (userModel, betterAuthUser, oauthProvider) { r
             case 2:
                 _a.sent();
                 return [2 /*return*/, existingUser];
-            case 3: return [4 /*yield*/, userModel.findOne({ email: betterAuthUser.email })];
+            case 3: return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(userModel, {
+                    email: betterAuthUser.email,
+                })];
             case 4:
                 userByEmail = _a.sent();
                 if (!userByEmail) return [3 /*break*/, 6];

package/dist/githubAuth.d.ts

@@ -46,12 +46,12 @@ export interface GitHubUserFields {
  * userSchema.plugin(githubUserPlugin);
  * ```
  */
-export declare function githubUserPlugin(schema: any): void;
+export declare const githubUserPlugin: (schema: any) => void;
 /**
  * Sets up GitHub OAuth authentication strategy.
  * Call this after setupAuth() in your server initialization.
  */
-export declare function setupGitHubAuth(_app: express.Application, userModel: UserModel, githubOptions: GitHubAuthOptions): void;
+export declare const setupGitHubAuth: (_app: express.Application, userModel: UserModel, githubOptions: GitHubAuthOptions) => void;
 /**
  * Adds GitHub OAuth routes to the Express application.
  *
@@ -61,4 +61,4 @@ export declare function setupGitHubAuth(_app: express.Application, userModel: Us
  * - POST /auth/github/link - Links GitHub account to authenticated user (requires JWT auth)
  * - DELETE /auth/github/unlink - Unlinks GitHub account from authenticated user (requires JWT auth)
  */
-export declare function addGitHubAuthRoutes(app: express.Application, userModel: UserModel, githubOptions: GitHubAuthOptions, authOptions?: AuthOptions): void;
+export declare const addGitHubAuthRoutes: (app: express.Application, userModel: UserModel, githubOptions: GitHubAuthOptions, authOptions?: AuthOptions) => void;

package/dist/githubAuth.js

@@ -39,14 +39,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.githubUserPlugin = githubUserPlugin;
-exports.setupGitHubAuth = setupGitHubAuth;
-exports.addGitHubAuthRoutes = addGitHubAuthRoutes;
+exports.addGitHubAuthRoutes = exports.setupGitHubAuth = exports.githubUserPlugin = void 0;
 var passport_1 = __importDefault(require("passport"));
 var passport_github2_1 = require("passport-github2");
 var auth_1 = require("./auth");
 var errors_1 = require("./errors");
 var logger_1 = require("./logger");
+var plugins_1 = require("./plugins");
 /**
  * Plugin to add GitHub authentication fields to a user schema.
  * Apply this plugin to your User schema if you want to enable GitHub auth.
@@ -58,20 +57,20 @@ var logger_1 = require("./logger");
  * userSchema.plugin(githubUserPlugin);
  * ```
  */
-function githubUserPlugin(schema) {
+var githubUserPlugin = function (schema) {
     schema.add({
         githubAvatarUrl: { type: String },
         githubId: { index: true, sparse: true, type: String, unique: true },
         githubProfileUrl: { type: String },
         githubUsername: { type: String },
     });
-}
+};
+exports.githubUserPlugin = githubUserPlugin;
 /**
  * Sets up GitHub OAuth authentication strategy.
  * Call this after setupAuth() in your server initialization.
  */
-function setupGitHubAuth(_app, userModel, githubOptions) {
-    var _this = this;
+var setupGitHubAuth = function (_app, userModel, githubOptions) {
     var _a;
     var scope = (_a = githubOptions.scope) !== null && _a !== void 0 ? _a : ["user:email"];
     passport_1.default.use("github", new passport_github2_1.Strategy({
@@ -80,7 +79,7 @@ function setupGitHubAuth(_app, userModel, githubOptions) {
         clientSecret: githubOptions.clientSecret,
         passReqToCallback: true,
         scope: scope,
-    }, (function (req, accessToken, refreshToken, profile, done) { return __awaiter(_this, void 0, void 0, function () {
+    }, (function (req, accessToken, refreshToken, profile, done) { return __awaiter(void 0, void 0, void 0, function () {
         var existingUser, user, githubId, existingGitHubUser, user, email, existingEmailUser, newUser, error_1;
         var _a, _b, _c, _d, _e, _f, _g, _h;
         return __generator(this, function (_j) {
@@ -95,7 +94,7 @@ function setupGitHubAuth(_app, userModel, githubOptions) {
                     return [2 /*return*/, done(null, user)];
                 case 2:
                     githubId = profile.id;
-                    return [4 /*yield*/, userModel.findOne({ githubId: githubId })];
+                    return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(userModel, { githubId: githubId })];
                 case 3:
                     existingGitHubUser = _j.sent();
                     if (!existingUser) return [3 /*break*/, 7];
@@ -129,7 +128,7 @@ function setupGitHubAuth(_app, userModel, githubOptions) {
                     }
                     email = (_d = (_c = profile.emails) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.value;
                     if (!email) return [3 /*break*/, 11];
-                    return [4 /*yield*/, userModel.findOne({ email: email })];
+                    return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(userModel, { email: email })];
                 case 8:
                     existingEmailUser = _j.sent();
                     if (!existingEmailUser) return [3 /*break*/, 11];
@@ -167,7 +166,8 @@ function setupGitHubAuth(_app, userModel, githubOptions) {
             }
         });
     }); })));
-}
+};
+exports.setupGitHubAuth = setupGitHubAuth;
 /**
  * Adds GitHub OAuth routes to the Express application.
  *
@@ -177,8 +177,7 @@ function setupGitHubAuth(_app, userModel, githubOptions) {
  * - POST /auth/github/link - Links GitHub account to authenticated user (requires JWT auth)
  * - DELETE /auth/github/unlink - Unlinks GitHub account from authenticated user (requires JWT auth)
  */
-function addGitHubAuthRoutes(app, userModel, githubOptions, authOptions) {
-    var _this = this;
+var addGitHubAuthRoutes = function (app, userModel, githubOptions, authOptions) {
     var router = require("express").Router();
     // Initiate GitHub OAuth flow
     router.get("/github", function (req, _res, next) {
@@ -194,7 +193,7 @@ function addGitHubAuthRoutes(app, userModel, githubOptions, authOptions) {
     router.get("/github/callback", passport_1.default.authenticate("github", {
         failureRedirect: "/auth/github/failure",
         session: false,
-    }), function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+    }), function (req, res) { return __awaiter(void 0, void 0, void 0, function () {
         var tokens, returnTo, url, error_2;
         var _a, _b, _c, _d;
         return __generator(this, function (_e) {
@@ -249,7 +248,7 @@ function addGitHubAuthRoutes(app, userModel, githubOptions, authOptions) {
             })(req, res, next);
         }, passport_1.default.authenticate("github", { session: false }));
         // Unlink GitHub from user account
-        router.delete("/github/unlink", passport_1.default.authenticate("jwt", { session: false }), function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+        router.delete("/github/unlink", passport_1.default.authenticate("jwt", { session: false }), function (req, res) { return __awaiter(void 0, void 0, void 0, function () {
             var user, hasPassword, error_3;
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -290,4 +289,5 @@ function addGitHubAuthRoutes(app, userModel, githubOptions, authOptions) {
         }); });
     }
     app.use("/auth", router);
-}
+};
+exports.addGitHubAuthRoutes = addGitHubAuthRoutes;

package/dist/middleware.test.d.ts

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

package/dist/middleware.test.js

@@ -0,0 +1,82 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var Sentry = __importStar(require("@sentry/bun"));
+var middleware_1 = require("./middleware");
+var buildReq = function (headers) {
+    return {
+        get: function (name) { return headers[name]; },
+    };
+};
+var buildNext = function () { return (0, bun_test_1.mock)(function () { }); };
+(0, bun_test_1.describe)("sentryAppVersionMiddleware", function () {
+    var setTagMock;
+    (0, bun_test_1.beforeEach)(function () {
+        // bunSetup.ts mocks @sentry/bun so that getCurrentScope() returns a scope
+        // with a Bun mock setTag. Clear that mock between tests so each assertion
+        // sees only its own calls.
+        setTagMock = Sentry.getCurrentScope().setTag;
+        setTagMock.mockClear();
+    });
+    (0, bun_test_1.it)("sets the app_version tag when the App-Version header is present", function () {
+        var next = buildNext();
+        var req = buildReq({ "App-Version": "1.2.3" });
+        (0, middleware_1.sentryAppVersionMiddleware)(req, {}, next);
+        (0, bun_test_1.expect)(setTagMock).toHaveBeenCalledTimes(1);
+        (0, bun_test_1.expect)(setTagMock.mock.calls[0]).toEqual(["app_version", "1.2.3"]);
+        (0, bun_test_1.expect)(next).toHaveBeenCalledTimes(1);
+    });
+    (0, bun_test_1.it)("does not set a tag when the App-Version header is missing", function () {
+        var next = buildNext();
+        var req = buildReq({});
+        (0, middleware_1.sentryAppVersionMiddleware)(req, {}, next);
+        (0, bun_test_1.expect)(setTagMock).not.toHaveBeenCalled();
+        (0, bun_test_1.expect)(next).toHaveBeenCalledTimes(1);
+    });
+    (0, bun_test_1.it)("does not set a tag when the App-Version header is an empty string", function () {
+        var next = buildNext();
+        var req = buildReq({ "App-Version": "" });
+        (0, middleware_1.sentryAppVersionMiddleware)(req, {}, next);
+        (0, bun_test_1.expect)(setTagMock).not.toHaveBeenCalled();
+        (0, bun_test_1.expect)(next).toHaveBeenCalledTimes(1);
+    });
+    (0, bun_test_1.it)("calls next exactly once with no arguments when the header is present", function () {
+        var next = buildNext();
+        (0, middleware_1.sentryAppVersionMiddleware)(buildReq({ "App-Version": "9.9.9" }), {}, next);
+        (0, bun_test_1.expect)(next).toHaveBeenCalledTimes(1);
+        (0, bun_test_1.expect)(next.mock.calls[0]).toHaveLength(0);
+    });
+});

package/dist/notifiers/googleChatNotifier.js

@@ -108,7 +108,7 @@ var sendToGoogleChat = function (messageText_1) {
         args_1[_i - 1] = arguments[_i];
     }
     return __awaiter(void 0, __spreadArray([messageText_1], __read(args_1), false), void 0, function (messageText, _a) {
-        var chatWebhooksString, msg, chatWebhooks, chatChannel, chatWebhookUrl, msg, formattedMessageText, error_1;
+        var chatWebhooksString, msg, chatWebhooks, chatChannel, chatWebhookUrl, msg, formattedMessageText, error_1, errorObj;
         var _b, _c, _d;
         var _e = _a === void 0 ? {} : _a, channel = _e.channel, _f = _e.shouldThrow, shouldThrow = _f === void 0 ? false : _f, env = _e.env;
         return __generator(this, function (_g) {
@@ -143,12 +143,13 @@ var sendToGoogleChat = function (messageText_1) {
                     return [3 /*break*/, 4];
                 case 3:
                     error_1 = _g.sent();
-                    logger_1.logger.error("Error posting to Google Chat: ".concat((_c = error_1.text) !== null && _c !== void 0 ? _c : error_1.message));
+                    errorObj = error_1;
+                    logger_1.logger.error("Error posting to Google Chat: ".concat((_c = errorObj.text) !== null && _c !== void 0 ? _c : errorObj.message));
                     Sentry.captureException(error_1);
                     if (shouldThrow) {
                         throw new errors_1.APIError({
                             status: 500,
-                            title: "Error posting to Google Chat: ".concat((_d = error_1.text) !== null && _d !== void 0 ? _d : error_1.message),
+                            title: "Error posting to Google Chat: ".concat((_d = errorObj.text) !== null && _d !== void 0 ? _d : errorObj.message),
                         });
                     }
                     return [3 /*break*/, 4];

package/dist/plugins.d.ts

@@ -1,4 +1,4 @@
-import { type Document, type Schema, SchemaType, type SchemaTypeOptions } from "mongoose";
+import mongoose, { type Document, type FilterQuery, type Schema, SchemaType, type SchemaTypeOptions } from "mongoose";
 import { type APIErrorConstructor } from "./errors";
 export interface BaseUser {
     admin: boolean;
@@ -31,6 +31,17 @@ export declare const firebaseJWTPlugin: (schema: Schema) => void;
  * @param schema Mongoose Schema
  */
 export declare const findOneOrNone: <T>(schema: Schema<T>) => void;
+/**
+ * Helper that performs a `findOneOrNone` lookup against any Mongoose model. Returns the matching
+ * document, `null` if none match, or throws if more than one matches. If the model's schema has
+ * the {@link findOneOrNone} plugin applied, the plugin static is used; otherwise the lookup is
+ * performed directly via `model.find(...)`. Prefer this helper from framework code where the
+ * consumer's model may or may not have the plugin installed.
+ * @param model Mongoose Model
+ * @param query Mongoose query object
+ * @param errorArgs Optional overrides for the thrown {@link APIError} when multiple match
+ */
+export declare const findOneOrNoneFor: <T>(model: mongoose.Model<T>, query: FilterQuery<T>, errorArgs?: Partial<APIErrorConstructor>) => Promise<(Document & T) | null>;
 /**
  * This adds a static method `Model.findExactlyOne` to the schema. This or findOneOrNone should replace `Model.findOne`
  * in most instances.

package/dist/plugins.js

@@ -95,7 +95,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
     }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DateOnly = exports.upsertPlugin = exports.findExactlyOne = exports.findOneOrNone = exports.firebaseJWTPlugin = exports.createdUpdatedPlugin = exports.isDisabledPlugin = exports.isDeletedPlugin = exports.baseUserPlugin = void 0;
+exports.DateOnly = exports.upsertPlugin = exports.findExactlyOne = exports.findOneOrNoneFor = exports.findOneOrNone = exports.firebaseJWTPlugin = exports.createdUpdatedPlugin = exports.isDisabledPlugin = exports.isDeletedPlugin = exports.baseUserPlugin = void 0;
 var luxon_1 = require("luxon");
 var mongoose_1 = __importStar(require("mongoose"));
 var errors_1 = require("./errors");
@@ -199,6 +199,39 @@ var findOneOrNone = function (schema) {
     };
 };
 exports.findOneOrNone = findOneOrNone;
+/**
+ * Helper that performs a `findOneOrNone` lookup against any Mongoose model. Returns the matching
+ * document, `null` if none match, or throws if more than one matches. If the model's schema has
+ * the {@link findOneOrNone} plugin applied, the plugin static is used; otherwise the lookup is
+ * performed directly via `model.find(...)`. Prefer this helper from framework code where the
+ * consumer's model may or may not have the plugin installed.
+ * @param model Mongoose Model
+ * @param query Mongoose query object
+ * @param errorArgs Optional overrides for the thrown {@link APIError} when multiple match
+ */
+var findOneOrNoneFor = function (model, query, errorArgs) { return __awaiter(void 0, void 0, void 0, function () {
+    var withStatic, results;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                withStatic = model;
+                if (typeof withStatic.findOneOrNone === "function") {
+                    return [2 /*return*/, withStatic.findOneOrNone(query, errorArgs)];
+                }
+                return [4 /*yield*/, model.find(query)];
+            case 1:
+                results = _a.sent();
+                if (results.length === 0) {
+                    return [2 /*return*/, null];
+                }
+                if (results.length > 1) {
+                    throw new errors_1.APIError(__assign({ detail: "query: ".concat(JSON.stringify(query)), status: 500, title: "".concat(model.modelName, ".findOne query returned multiple documents") }, errorArgs));
+                }
+                return [2 /*return*/, results[0]];
+        }
+    });
+}); };
+exports.findOneOrNoneFor = findOneOrNoneFor;
 /**
  * This adds a static method `Model.findExactlyOne` to the schema. This or findOneOrNone should replace `Model.findOne`
  * in most instances.

package/dist/plugins.test.js

@@ -278,6 +278,188 @@ var StuffModel = (0, mongoose_1.model)("Stuff", stuffSchema);
         });
     }); });
 });
+var bareThingSchema = new mongoose_1.Schema({
+    name: { description: "The name of the bare item", type: String },
+    ownerId: { description: "The owner of the bare item", type: String },
+});
+var BareThingModel = (0, mongoose_1.model)("BareThing", bareThingSchema);
+(0, bun_test_1.describe)("findOneOrNoneFor", function () {
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, StuffModel.deleteMany({})];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, BareThingModel.deleteMany({})];
+                case 2:
+                    _a.sent();
+                    return [4 /*yield*/, (0, tests_1.setupDb)()];
+                case 3:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.describe)("when the schema has the findOneOrNone plugin", function () {
+        var things;
+        (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: return [4 /*yield*/, Promise.all([
+                            StuffModel.create({ name: "Things", ownerId: "123" }),
+                            StuffModel.create({ name: "StuffNThings", ownerId: "123" }),
+                        ])];
+                    case 1:
+                        _a = __read.apply(void 0, [_b.sent(), 1]), things = _a[0];
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("returns null with no matches", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(StuffModel, { name: "OtherStuff" })];
+                    case 1:
+                        result = _a.sent();
+                        (0, bun_test_1.expect)(result).toBeNull();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("returns a single match", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(StuffModel, { name: "Things" })];
+                    case 1:
+                        result = _a.sent();
+                        (0, bun_test_1.expect)(result).not.toBeNull();
+                        (0, bun_test_1.expect)(result === null || result === void 0 ? void 0 : result._id.toString()).toBe(things._id.toString());
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("throws when multiple documents match", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var fn;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        fn = function () { return (0, plugins_1.findOneOrNoneFor)(StuffModel, { ownerId: "123" }); };
+                        return [4 /*yield*/, (0, bun_test_1.expect)(fn()).rejects.toThrow(/Stuff\.findOne query returned multiple documents/)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("forwards errorArgs to the thrown APIError", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var fn, error_2;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        fn = function () {
+                            return (0, plugins_1.findOneOrNoneFor)(StuffModel, { ownerId: "123" }, { status: 400, title: "Oh no!" });
+                        };
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, fn()];
+                    case 2:
+                        _a.sent();
+                        throw new Error("Expected promise to reject");
+                    case 3:
+                        error_2 = _a.sent();
+                        (0, bun_test_1.expect)(error_2.title).toBe("Oh no!");
+                        (0, bun_test_1.expect)(error_2.status).toBe(400);
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("when the schema does NOT have the findOneOrNone plugin", function () {
+        var bareThings;
+        (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: return [4 /*yield*/, Promise.all([
+                            BareThingModel.create({ name: "Things", ownerId: "123" }),
+                            BareThingModel.create({ name: "StuffNThings", ownerId: "123" }),
+                        ])];
+                    case 1:
+                        _a = __read.apply(void 0, [_b.sent(), 1]), bareThings = _a[0];
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("returns null with no matches", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(BareThingModel, { name: "OtherStuff" })];
+                    case 1:
+                        result = _a.sent();
+                        (0, bun_test_1.expect)(result).toBeNull();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("returns a single match", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var result;
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0: return [4 /*yield*/, (0, plugins_1.findOneOrNoneFor)(BareThingModel, { name: "Things" })];
+                    case 1:
+                        result = _c.sent();
+                        (0, bun_test_1.expect)(result).not.toBeNull();
+                        (0, bun_test_1.expect)((_a = result === null || result === void 0 ? void 0 : result._id) === null || _a === void 0 ? void 0 : _a.toString()).toBe((_b = bareThings._id) === null || _b === void 0 ? void 0 : _b.toString());
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("throws when multiple documents match", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var fn;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        fn = function () { return (0, plugins_1.findOneOrNoneFor)(BareThingModel, { ownerId: "123" }); };
+                        return [4 /*yield*/, (0, bun_test_1.expect)(fn()).rejects.toThrow(/BareThing\.findOne query returned multiple documents/)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("forwards errorArgs to the thrown APIError", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var fn, error_3;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        fn = function () {
+                            return (0, plugins_1.findOneOrNoneFor)(BareThingModel, { ownerId: "123" }, { status: 400, title: "Oh no!" });
+                        };
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, fn()];
+                    case 2:
+                        _a.sent();
+                        throw new Error("Expected promise to reject");
+                    case 3:
+                        error_3 = _a.sent();
+                        (0, bun_test_1.expect)(error_3.title).toBe("Oh no!");
+                        (0, bun_test_1.expect)(error_3.status).toBe(400);
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+});
 (0, bun_test_1.describe)("findExactlyOne", function () {
     var things;
     (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
@@ -345,7 +527,7 @@ var StuffModel = (0, mongoose_1.model)("Stuff", stuffSchema);
         });
     }); });
     (0, bun_test_1.it)("throws custom error with two matches.", function () { return __awaiter(void 0, void 0, void 0, function () {
-        var fn, error_2;
+        var fn, error_4;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -359,11 +541,11 @@ var StuffModel = (0, mongoose_1.model)("Stuff", stuffSchema);
                     // If the promise doesn't reject, the test should fail
                     throw new Error("Expected promise to reject");
                 case 3:
-                    error_2 = _a.sent();
+                    error_4 = _a.sent();
                     // Check if the error has title and status properties
-                    (0, bun_test_1.expect)(error_2.title).toBe("Oh no!");
-                    (0, bun_test_1.expect)(error_2.status).toBe(400);
-                    (0, bun_test_1.expect)(error_2.detail).toBe('query: {"ownerId":"123"}');
+                    (0, bun_test_1.expect)(error_4.title).toBe("Oh no!");
+                    (0, bun_test_1.expect)(error_4.status).toBe(400);
+                    (0, bun_test_1.expect)(error_4.detail).toBe('query: {"ownerId":"123"}');
                     return [3 /*break*/, 4];
                 case 4: return [2 /*return*/];
             }
@@ -526,7 +708,7 @@ var StuffModel = (0, mongoose_1.model)("Stuff", stuffSchema);
 });
 (0, bun_test_1.describe)("DateOnly", function () {
     (0, bun_test_1.it)("throws error with invalid date", function () { return __awaiter(void 0, void 0, void 0, function () {
-        var error_3;
+        var error_5;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -540,8 +722,8 @@ var StuffModel = (0, mongoose_1.model)("Stuff", stuffSchema);
                     _a.sent();
                     return [3 /*break*/, 3];
                 case 2:
-                    error_3 = _a.sent();
-                    (0, bun_test_1.expect)(error_3.message).toMatch(/Cast to DateOnly failed/);
+                    error_5 = _a.sent();
+                    (0, bun_test_1.expect)(error_5.message).toMatch(/Cast to DateOnly failed/);
                     return [2 /*return*/];
                 case 3: throw new Error("Expected error was not thrown");
             }

package/dist/types/consentForm.d.ts

@@ -7,8 +7,10 @@ export interface ConsentFormCheckbox {
 }
 export type ConsentFormType = "agreement" | "privacy" | "hipaa" | "research" | "terms" | "custom";
 export type ConsentFormMethods = {};
-export type ConsentFormStatics = FindExactlyOnePlugin<ConsentFormDocument> & FindOneOrNonePlugin<ConsentFormDocument>;
-export type ConsentFormModel = mongoose.Model<ConsentFormDocument, object, ConsentFormMethods> & ConsentFormStatics;
+export interface ConsentFormStatics extends FindExactlyOnePlugin<ConsentFormDocument>, FindOneOrNonePlugin<ConsentFormDocument> {
+}
+export interface ConsentFormModel extends mongoose.Model<ConsentFormDocument, object, ConsentFormMethods>, ConsentFormStatics {
+}
 export interface ConsentFormDocument extends mongoose.Document {
     _id: mongoose.Types.ObjectId;
     title: string;

package/package.json

@@ -104,5 +104,5 @@
     "updateSnapshot": "bun test --update-snapshots"
   },
   "types": "dist/index.d.ts",
-  "version": "0.11.8"
+  "version": "0.11.9"
 }

package/src/betterAuthSetup.ts

@@ -13,6 +13,7 @@ import mongoose from "mongoose";
 import type {UserModel} from "./auth";
 import type {BetterAuthConfig, BetterAuthSessionData, BetterAuthUser} from "./betterAuth";
 import {logger} from "./logger";
+import {findOneOrNoneFor} from "./plugins";
 
 /**
  * The Better Auth instance type.
@@ -109,7 +110,9 @@ export const createBetterAuthSessionMiddleware = (
 
         if (userModel) {
           // Look up the application user by betterAuthId
-          const appUser = await userModel.findOne({betterAuthId: betterAuthUser.id});
+          const appUser = await findOneOrNoneFor(userModel, {
+            betterAuthId: betterAuthUser.id,
+          });
           if (appUser) {
             (req as any).user = appUser;
             (req as any).betterAuthSession = session;
@@ -151,7 +154,9 @@ export const syncBetterAuthUser = async (
   oauthProvider?: string
 ): Promise<any> => {
   try {
-    const existingUser: any = await userModel.findOne({betterAuthId: betterAuthUser.id});
+    const existingUser: any = await findOneOrNoneFor(userModel, {
+      betterAuthId: betterAuthUser.id,
+    });
 
     if (existingUser) {
       // Update existing user if needed
@@ -164,7 +169,9 @@ export const syncBetterAuthUser = async (
     }
 
     // Check if user exists by email (migration case)
-    const userByEmail: any = await userModel.findOne({email: betterAuthUser.email});
+    const userByEmail: any = await findOneOrNoneFor(userModel, {
+      email: betterAuthUser.email,
+    });
     if (userByEmail) {
       // Link existing user to Better Auth
       userByEmail.betterAuthId = betterAuthUser.id;

package/src/githubAuth.ts

@@ -5,6 +5,7 @@ import {generateTokens, type UserModel} from "./auth";
 import {APIError} from "./errors";
 import type {AuthOptions} from "./expressServer";
 import {logger} from "./logger";
+import {findOneOrNoneFor} from "./plugins";
 
 /** Options for configuring GitHub OAuth authentication */
 export interface GitHubAuthOptions {
@@ -57,24 +58,24 @@ export interface GitHubUserFields {
  * userSchema.plugin(githubUserPlugin);
  * ```
  */
-export function githubUserPlugin(schema: any) {
+export const githubUserPlugin = (schema: any): void => {
   schema.add({
     githubAvatarUrl: {type: String},
     githubId: {index: true, sparse: true, type: String, unique: true},
     githubProfileUrl: {type: String},
     githubUsername: {type: String},
   });
-}
+};
 
 /**
  * Sets up GitHub OAuth authentication strategy.
  * Call this after setupAuth() in your server initialization.
  */
-export function setupGitHubAuth(
+export const setupGitHubAuth = (
   _app: express.Application,
   userModel: UserModel,
   githubOptions: GitHubAuthOptions
-) {
+): void => {
   const scope = githubOptions.scope ?? ["user:email"];
 
   passport.use(
@@ -112,7 +113,7 @@ export function setupGitHubAuth(
           const githubId = profile.id;
 
           // Check if user with this GitHub ID already exists
-          const existingGitHubUser = await userModel.findOne({githubId} as any);
+          const existingGitHubUser = await findOneOrNoneFor(userModel, {githubId});
 
           // Case 1: User is authenticated and wants to link GitHub account
           if (existingUser) {
@@ -155,7 +156,7 @@ export function setupGitHubAuth(
 
           // Check if user with this email already exists
           if (email) {
-            const existingEmailUser = await userModel.findOne({email} as any);
+            const existingEmailUser = await findOneOrNoneFor(userModel, {email});
             if (existingEmailUser) {
               // If account linking is allowed, link GitHub to existing email account
               if (githubOptions.allowAccountLinking !== false) {
@@ -195,7 +196,7 @@ export function setupGitHubAuth(
       }) as any
     ) as passport.Strategy
   );
-}
+};
 
 /**
  * Adds GitHub OAuth routes to the Express application.
@@ -206,12 +207,12 @@ export function setupGitHubAuth(
  * - POST /auth/github/link - Links GitHub account to authenticated user (requires JWT auth)
  * - DELETE /auth/github/unlink - Unlinks GitHub account from authenticated user (requires JWT auth)
  */
-export function addGitHubAuthRoutes(
+export const addGitHubAuthRoutes = (
   app: express.Application,
   userModel: UserModel,
   githubOptions: GitHubAuthOptions,
   authOptions?: AuthOptions
-): void {
+): void => {
   const router = require("express").Router();
 
   // Initiate GitHub OAuth flow
@@ -332,4 +333,4 @@ export function addGitHubAuthRoutes(
   }
 
   app.use("/auth", router);
-}
+};

package/src/middleware.test.ts

@@ -0,0 +1,71 @@
+import {beforeEach, describe, expect, it, type Mock, mock} from "bun:test";
+import * as Sentry from "@sentry/bun";
+import type {NextFunction, Request, Response} from "express";
+
+import {sentryAppVersionMiddleware} from "./middleware";
+
+const buildReq = (headers: Record<string, string | undefined>): Request => {
+  return {
+    get: (name: string) => headers[name],
+  } as unknown as Request;
+};
+
+const buildNext = (): Mock<() => void> => mock(() => {});
+
+describe("sentryAppVersionMiddleware", () => {
+  let setTagMock: Mock<(key: string, value: string) => void>;
+
+  beforeEach(() => {
+    // bunSetup.ts mocks @sentry/bun so that getCurrentScope() returns a scope
+    // with a Bun mock setTag. Clear that mock between tests so each assertion
+    // sees only its own calls.
+    setTagMock = Sentry.getCurrentScope().setTag as unknown as Mock<
+      (key: string, value: string) => void
+    >;
+    setTagMock.mockClear();
+  });
+
+  it("sets the app_version tag when the App-Version header is present", () => {
+    const next = buildNext();
+    const req = buildReq({"App-Version": "1.2.3"});
+
+    sentryAppVersionMiddleware(req, {} as Response, next as unknown as NextFunction);
+
+    expect(setTagMock).toHaveBeenCalledTimes(1);
+    expect(setTagMock.mock.calls[0]).toEqual(["app_version", "1.2.3"]);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not set a tag when the App-Version header is missing", () => {
+    const next = buildNext();
+    const req = buildReq({});
+
+    sentryAppVersionMiddleware(req, {} as Response, next as unknown as NextFunction);
+
+    expect(setTagMock).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not set a tag when the App-Version header is an empty string", () => {
+    const next = buildNext();
+    const req = buildReq({"App-Version": ""});
+
+    sentryAppVersionMiddleware(req, {} as Response, next as unknown as NextFunction);
+
+    expect(setTagMock).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls next exactly once with no arguments when the header is present", () => {
+    const next = buildNext();
+
+    sentryAppVersionMiddleware(
+      buildReq({"App-Version": "9.9.9"}),
+      {} as Response,
+      next as unknown as NextFunction
+    );
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(next.mock.calls[0]).toHaveLength(0);
+  });
+});

package/src/notifiers/googleChatNotifier.ts

@@ -34,13 +34,14 @@ export const sendToGoogleChat = async (
 
   try {
     await axios.post(chatWebhookUrl, {text: formattedMessageText});
-  } catch (error: any) {
-    logger.error(`Error posting to Google Chat: ${error.text ?? error.message}`);
+  } catch (error: unknown) {
+    const errorObj = error as {text?: string; message?: string};
+    logger.error(`Error posting to Google Chat: ${errorObj.text ?? errorObj.message}`);
     Sentry.captureException(error);
     if (shouldThrow) {
       throw new APIError({
         status: 500,
-        title: `Error posting to Google Chat: ${error.text ?? error.message}`,
+        title: `Error posting to Google Chat: ${errorObj.text ?? errorObj.message}`,
       });
     }
   }

package/src/plugins.test.ts

@@ -13,6 +13,7 @@ import {
   DateOnly,
   findExactlyOne,
   findOneOrNone,
+  findOneOrNoneFor,
   firebaseJWTPlugin,
   type IsDeleted,
   isDeletedPlugin,
@@ -187,6 +188,106 @@ describe("findOneOrNone", () => {
   });
 });
 
+interface BareThing {
+  name: string;
+  ownerId: string;
+}
+
+const bareThingSchema = new Schema<BareThing>({
+  name: {description: "The name of the bare item", type: String},
+  ownerId: {description: "The owner of the bare item", type: String},
+});
+
+const BareThingModel = model<BareThing>("BareThing", bareThingSchema);
+
+describe("findOneOrNoneFor", () => {
+  beforeEach(async () => {
+    await StuffModel.deleteMany({});
+    await BareThingModel.deleteMany({});
+    await setupDb();
+  });
+
+  describe("when the schema has the findOneOrNone plugin", () => {
+    let things: any;
+
+    beforeEach(async () => {
+      [things] = await Promise.all([
+        StuffModel.create({name: "Things", ownerId: "123"}),
+        StuffModel.create({name: "StuffNThings", ownerId: "123"}),
+      ]);
+    });
+
+    it("returns null with no matches", async () => {
+      const result = await findOneOrNoneFor(StuffModel, {name: "OtherStuff"});
+      expect(result).toBeNull();
+    });
+
+    it("returns a single match", async () => {
+      const result = await findOneOrNoneFor(StuffModel, {name: "Things"});
+      expect(result).not.toBeNull();
+      expect(result?._id.toString()).toBe(things._id.toString());
+    });
+
+    it("throws when multiple documents match", async () => {
+      const fn = () => findOneOrNoneFor(StuffModel, {ownerId: "123"});
+      await expect(fn()).rejects.toThrow(/Stuff\.findOne query returned multiple documents/);
+    });
+
+    it("forwards errorArgs to the thrown APIError", async () => {
+      const fn = () =>
+        findOneOrNoneFor(StuffModel, {ownerId: "123"}, {status: 400, title: "Oh no!"});
+
+      try {
+        await fn();
+        throw new Error("Expected promise to reject");
+      } catch (error: any) {
+        expect(error.title).toBe("Oh no!");
+        expect(error.status).toBe(400);
+      }
+    });
+  });
+
+  describe("when the schema does NOT have the findOneOrNone plugin", () => {
+    let bareThings: any;
+
+    beforeEach(async () => {
+      [bareThings] = await Promise.all([
+        BareThingModel.create({name: "Things", ownerId: "123"}),
+        BareThingModel.create({name: "StuffNThings", ownerId: "123"}),
+      ]);
+    });
+
+    it("returns null with no matches", async () => {
+      const result = await findOneOrNoneFor(BareThingModel, {name: "OtherStuff"});
+      expect(result).toBeNull();
+    });
+
+    it("returns a single match", async () => {
+      const result = await findOneOrNoneFor(BareThingModel, {name: "Things"});
+      expect(result).not.toBeNull();
+      expect((result as any)?._id?.toString()).toBe(bareThings._id?.toString());
+    });
+
+    it("throws when multiple documents match", async () => {
+      const fn = () => findOneOrNoneFor(BareThingModel, {ownerId: "123"});
+      await expect(fn()).rejects.toThrow(/BareThing\.findOne query returned multiple documents/);
+    });
+
+    it("forwards errorArgs to the thrown APIError", async () => {
+      const fn = () =>
+        findOneOrNoneFor(BareThingModel, {ownerId: "123"}, {status: 400, title: "Oh no!"});
+
+      try {
+        await fn();
+        throw new Error("Expected promise to reject");
+      } catch (error: any) {
+        expect(error.title).toBe("Oh no!");
+        expect(error.status).toBe(400);
+      }
+    });
+  });
+});
+
 describe("findExactlyOne", () => {
   let things: any;
 

package/src/plugins.ts

@@ -1,6 +1,7 @@
 import {DateTime} from "luxon";
 import mongoose, {
   type Document,
+  type FilterQuery,
   Error as MongooseError,
   type Query,
   type Schema,
@@ -129,6 +130,40 @@ export const findOneOrNone = <T>(schema: Schema<T>): void => {
   };
 };
 
+/**
+ * Helper that performs a `findOneOrNone` lookup against any Mongoose model. Returns the matching
+ * document, `null` if none match, or throws if more than one matches. If the model's schema has
+ * the {@link findOneOrNone} plugin applied, the plugin static is used; otherwise the lookup is
+ * performed directly via `model.find(...)`. Prefer this helper from framework code where the
+ * consumer's model may or may not have the plugin installed.
+ * @param model Mongoose Model
+ * @param query Mongoose query object
+ * @param errorArgs Optional overrides for the thrown {@link APIError} when multiple match
+ */
+export const findOneOrNoneFor = async <T>(
+  model: mongoose.Model<T>,
+  query: FilterQuery<T>,
+  errorArgs?: Partial<APIErrorConstructor>
+): Promise<(Document & T) | null> => {
+  const withStatic = model as mongoose.Model<T> & Partial<FindOneOrNonePlugin<T>>;
+  if (typeof withStatic.findOneOrNone === "function") {
+    return withStatic.findOneOrNone(query, errorArgs);
+  }
+  const results = await model.find(query);
+  if (results.length === 0) {
+    return null;
+  }
+  if (results.length > 1) {
+    throw new APIError({
+      detail: `query: ${JSON.stringify(query)}`,
+      status: 500,
+      title: `${model.modelName}.findOne query returned multiple documents`,
+      ...errorArgs,
+    });
+  }
+  return results[0] as unknown as Document & T;
+};
+
 /**
  * This adds a static method `Model.findExactlyOne` to the schema. This or findOneOrNone should replace `Model.findOne`
  * in most instances.

package/src/types/consentForm.ts

@@ -12,11 +12,13 @@ export type ConsentFormType = "agreement" | "privacy" | "hipaa" | "research" | "
 // biome-ignore lint/complexity/noBannedTypes: No methods.
 export type ConsentFormMethods = {};
 
-export type ConsentFormStatics = FindExactlyOnePlugin<ConsentFormDocument> &
-  FindOneOrNonePlugin<ConsentFormDocument>;
+export interface ConsentFormStatics
+  extends FindExactlyOnePlugin<ConsentFormDocument>,
+    FindOneOrNonePlugin<ConsentFormDocument> {}
 
-export type ConsentFormModel = mongoose.Model<ConsentFormDocument, object, ConsentFormMethods> &
-  ConsentFormStatics;
+export interface ConsentFormModel
+  extends mongoose.Model<ConsentFormDocument, object, ConsentFormMethods>,
+    ConsentFormStatics {}
 
 export interface ConsentFormDocument extends mongoose.Document {
   _id: mongoose.Types.ObjectId;