@terreno/api 0.11.7 → 0.11.9

package/dist/scriptRunner.d.ts

@@ -25,11 +25,11 @@ interface BackgroundTaskLog {
     level: "info" | "warn" | "error";
     message: string;
 }
-export type BackgroundTaskMethods = {
+export interface BackgroundTaskMethods {
     addLog: (this: BackgroundTaskDocument, level: "info" | "warn" | "error", message: string) => Promise<void>;
     updateProgress: (this: BackgroundTaskDocument, percentage: number, stage?: string, message?: string) => Promise<void>;
-};
-export type BackgroundTaskDocument = Document & BackgroundTaskMethods & {
+}
+export interface BackgroundTaskDocument extends Document, BackgroundTaskMethods {
     taskType: string;
     status: "pending" | "running" | "completed" | "failed" | "cancelled";
     progress?: BackgroundTaskProgress;
@@ -43,10 +43,11 @@ export type BackgroundTaskDocument = Document & BackgroundTaskMethods & {
     created: Date;
     updated: Date;
     deleted: boolean;
-};
-export type BackgroundTaskStatics = {
+}
+export interface BackgroundTaskStatics {
     checkCancellation: (taskId: string) => Promise<void>;
-};
-export type BackgroundTaskModel = Model<BackgroundTaskDocument, Record<string, never>, BackgroundTaskMethods> & BackgroundTaskStatics;
+}
+export interface BackgroundTaskModel extends Model<BackgroundTaskDocument, Record<string, never>, BackgroundTaskMethods>, BackgroundTaskStatics {
+}
 export declare const BackgroundTask: BackgroundTaskModel;
 export {};

package/dist/secretProviders.js

@@ -86,6 +86,7 @@ var __read = (this && this.__read) || function (o, n) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GcpSecretProvider = exports.EnvSecretProvider = void 0;
+var errors_1 = require("./errors");
 var logger_1 = require("./logger");
 /**
  * Secret provider that reads secrets from environment variables.
@@ -143,12 +144,13 @@ var GcpSecretProvider = /** @class */ (function () {
     }
     GcpSecretProvider.prototype.getClient = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var moduleName, mod, SecretManagerServiceClient, _a;
+            var mod, moduleName, _a, SecretManagerServiceClient;
             var _b, _c;
             return __generator(this, function (_d) {
                 switch (_d.label) {
                     case 0:
-                        if (!!this.client) return [3 /*break*/, 4];
+                        if (!!this.client) return [3 /*break*/, 5];
+                        mod = void 0;
                         _d.label = 1;
                     case 1:
                         _d.trys.push([1, 3, , 4]);
@@ -156,13 +158,21 @@ var GcpSecretProvider = /** @class */ (function () {
                         return [4 /*yield*/, Promise.resolve("".concat(/* webpackIgnore: true */ moduleName)).then(function (s) { return __importStar(require(s)); })];
                     case 2:
                         mod = _d.sent();
-                        SecretManagerServiceClient = (_b = mod.SecretManagerServiceClient) !== null && _b !== void 0 ? _b : (_c = mod.default) === null || _c === void 0 ? void 0 : _c.SecretManagerServiceClient;
-                        this.client = new SecretManagerServiceClient();
                         return [3 /*break*/, 4];
                     case 3:
                         _a = _d.sent();
-                        throw new Error("GcpSecretProvider requires @google-cloud/secret-manager. Install it with: bun add @google-cloud/secret-manager");
-                    case 4: return [2 /*return*/, this.client];
+                        throw new errors_1.APIError({
+                            status: 500,
+                            title: "GcpSecretProvider requires @google-cloud/secret-manager. Install it with: bun add @google-cloud/secret-manager",
+                        });
+                    case 4:
+                        SecretManagerServiceClient = (_b = mod.SecretManagerServiceClient) !== null && _b !== void 0 ? _b : (_c = mod.default) === null || _c === void 0 ? void 0 : _c.SecretManagerServiceClient;
+                        if (!SecretManagerServiceClient) {
+                            throw new Error("SecretManagerServiceClient not found in @google-cloud/secret-manager module");
+                        }
+                        this.client = new SecretManagerServiceClient();
+                        _d.label = 5;
+                    case 5: return [2 /*return*/, this.client];
                 }
             });
         });
@@ -198,7 +208,7 @@ var GcpSecretProvider = /** @class */ (function () {
                         return [2 /*return*/, typeof payload === "string" ? payload : new TextDecoder().decode(payload)];
                     case 4:
                         error_1 = _c.sent();
-                        if ((error_1 === null || error_1 === void 0 ? void 0 : error_1.code) === 5) {
+                        if (error_1 instanceof Error && "code" in error_1 && error_1.code === 5) {
                             // NOT_FOUND
                             logger_1.logger.warn("GcpSecretProvider: secret ".concat(secretName, " not found"));
                             return [2 /*return*/, null];

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.7"
+  "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/configurationPlugin.ts

@@ -2,6 +2,7 @@ import type {Document, Model, Schema} from "mongoose";
 
 import {APIError} from "./errors";
 import {logger} from "./logger";
+import {type FindOneOrNonePlugin, findOneOrNone} from "./plugins";
 
 /**
  * Metadata for a secret field discovered by the configuration plugin.
@@ -100,7 +101,7 @@ export interface ConfigurationStatics<T extends object> {
  * const full = await AppConfig.getConfig(); // typed as AppConfigDocument
  * ```
  */
-export type ConfigurationModel<T extends object> = Model<T> & ConfigurationStatics<T>;
+export interface ConfigurationModel<T extends object> extends Model<T>, ConfigurationStatics<T> {}
 
 // ---------------------------------------------------------------------------
 // Plugin
@@ -132,6 +133,9 @@ export type ConfigurationModel<T extends object> = Model<T> & ConfigurationStati
 export const configurationPlugin = (schema: Schema, options?: ConfigurationPluginOptions): void => {
   const pluginOptions = options ?? {};
 
+  // Apply findOneOrNone so the singleton lookup avoids bare Model.findOne (idempotent).
+  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({
@@ -142,8 +146,8 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
   // Enforce singleton: only one document allowed (application-level guard)
   schema.pre("save", async function () {
     if (this.isNew) {
-      // Intentional unfiltered findOne — checking if any singleton document exists
-      const existing = await (this.constructor as Model<unknown>).findOne({});
+      // Cheap existence check — no document needs to be returned.
+      const existing = await (this.constructor as Model<unknown>).exists({});
       if (existing) {
         throw new APIError({
           status: 409,
@@ -173,18 +177,23 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
 
   // Static: get the singleton configuration document or a value at a path (race-safe via upsert)
   schema.statics.getConfig = async function (key?: string): Promise<unknown> {
-    let config = await this.findOne({});
+    const findSingleton = (): Promise<Document | null> =>
+      (this as unknown as FindOneOrNonePlugin<unknown>).findOneOrNone(
+        {}
+      ) as Promise<Document | null>;
+    let config: Document | null = await findSingleton();
     if (!config) {
       try {
         // Use `new` + `save` instead of `create({})` so Mongoose initializes
         // nested subdocument defaults (create({}) skips them).
-        config = new this();
-        await config.save();
+        const created = new this();
+        await created.save();
+        config = created;
       } catch (err: unknown) {
-        // If another process created the document between findOne and create,
+        // If another process created the document between the lookup and create,
         // the pre-save hook will throw a 409. Just fetch the existing one.
         if ((err as {status?: number})?.status === 409) {
-          config = await this.findOne({});
+          config = await findSingleton();
         } else {
           throw err;
         }
@@ -197,7 +206,7 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
 
     // Resolve dot-notation key into the document
     const parts = key.split(".");
-    let value: unknown = config.toObject();
+    let value: unknown = config?.toObject();
     for (const part of parts) {
       if (value == null || typeof value !== "object") {
         return undefined;

package/src/errors.test.ts

@@ -0,0 +1,302 @@
+import {beforeEach, describe, expect, it, mock} from "bun:test";
+import * as Sentry from "@sentry/bun";
+import type {NextFunction, Request, Response} from "express";
+import {Schema} from "mongoose";
+
+import {
+  APIError,
+  apiErrorMiddleware,
+  apiUnauthorizedMiddleware,
+  errorsPlugin,
+  getAPIErrorBody,
+  getDisableExternalErrorTracking,
+  isAPIError,
+} from "./errors";
+
+interface MockResponse {
+  status: ReturnType<typeof mock>;
+  json: ReturnType<typeof mock>;
+  send: ReturnType<typeof mock>;
+}
+
+const buildResponse = (): MockResponse => {
+  const res: MockResponse = {
+    json: mock(() => res),
+    send: mock(() => res),
+    status: mock(() => res),
+  };
+  return res;
+};
+
+describe("APIError", () => {
+  it("creates an error with the provided fields", () => {
+    const error = new APIError({
+      code: "validation-failed",
+      detail: "Email is invalid",
+      id: "abc-123",
+      links: {about: "https://example.com/help", type: "https://example.com/types/validation"},
+      meta: {requestId: "req-1"},
+      source: {header: "x-foo", parameter: "limit", pointer: "/data/email"},
+      status: 400,
+      title: "Validation failed",
+    });
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe("APIError");
+    expect(error.title).toBe("Validation failed");
+    expect(error.detail).toBe("Email is invalid");
+    expect(error.code).toBe("validation-failed");
+    expect(error.status).toBe(400);
+    expect(error.id).toBe("abc-123");
+    expect(error.links).toEqual({
+      about: "https://example.com/help",
+      type: "https://example.com/types/validation",
+    });
+    expect(error.source).toEqual({
+      header: "x-foo",
+      parameter: "limit",
+      pointer: "/data/email",
+    });
+    expect(error.meta).toEqual({requestId: "req-1"});
+  });
+
+  it("includes the title and detail in the error message", () => {
+    const error = new APIError({detail: "Something exploded", title: "Boom"});
+    expect(error.message).toBe("Boom: Something exploded");
+  });
+
+  it("includes the wrapped error stack in the message", () => {
+    const wrapped = new Error("inner");
+    const error = new APIError({error: wrapped, title: "Outer"});
+    expect(error.message).toContain("Outer");
+    expect(error.message).toContain(wrapped.stack ?? "");
+  });
+
+  it("defaults status to 500 when status is omitted", () => {
+    const error = new APIError({title: "No status"});
+    expect(error.status).toBe(500);
+  });
+
+  it("forces status to 500 when below 400", () => {
+    const error = new APIError({status: 200, title: "Too low"});
+    expect(error.status).toBe(500);
+  });
+
+  it("forces status to 500 when above 599", () => {
+    const error = new APIError({status: 600, title: "Too high"});
+    expect(error.status).toBe(500);
+  });
+
+  it("defaults meta to an empty object when not provided", () => {
+    const error = new APIError({title: "No meta"});
+    expect(error.meta).toEqual({});
+  });
+
+  it("merges fields into meta", () => {
+    const error = new APIError({
+      fields: {email: "Required", name: "Required"},
+      title: "Validation",
+    });
+    expect(error.meta?.fields).toEqual({email: "Required", name: "Required"});
+  });
+
+  it("respects disableExternalErrorTracking", () => {
+    const trackedError = new APIError({title: "Tracked"});
+    const untrackedError = new APIError({
+      disableExternalErrorTracking: true,
+      title: "Untracked",
+    });
+    expect(trackedError.disableExternalErrorTracking).toBeUndefined();
+    expect(untrackedError.disableExternalErrorTracking).toBe(true);
+  });
+});
+
+describe("isAPIError", () => {
+  it("returns true for an APIError instance", () => {
+    expect(isAPIError(new APIError({title: "Boom"}))).toBe(true);
+  });
+
+  it("returns false for a regular Error", () => {
+    expect(isAPIError(new Error("nope"))).toBe(false);
+  });
+
+  it("returns true for any error whose name is APIError", () => {
+    const err = new Error("custom");
+    err.name = "APIError";
+    expect(isAPIError(err)).toBe(true);
+  });
+});
+
+describe("getDisableExternalErrorTracking", () => {
+  it("returns the flag from an APIError", () => {
+    const error = new APIError({disableExternalErrorTracking: true, title: "Test"});
+    expect(getDisableExternalErrorTracking(error)).toBe(true);
+  });
+
+  it("returns undefined for a plain Error without the flag", () => {
+    expect(getDisableExternalErrorTracking(new Error("plain"))).toBeUndefined();
+  });
+
+  it("returns the flag when attached to a non-APIError object", () => {
+    const error = {disableExternalErrorTracking: false};
+    expect(getDisableExternalErrorTracking(error)).toBe(false);
+  });
+
+  it("returns undefined for primitives and null", () => {
+    expect(getDisableExternalErrorTracking(null)).toBeUndefined();
+    expect(getDisableExternalErrorTracking(undefined)).toBeUndefined();
+    expect(getDisableExternalErrorTracking("string")).toBeUndefined();
+    expect(getDisableExternalErrorTracking(42)).toBeUndefined();
+  });
+
+  it("returns undefined for an object missing the property", () => {
+    expect(getDisableExternalErrorTracking({foo: "bar"})).toBeUndefined();
+  });
+});
+
+describe("getAPIErrorBody", () => {
+  it("returns title and status by default", () => {
+    const error = new APIError({status: 404, title: "Not Found"});
+    const body = getAPIErrorBody(error);
+    expect(body).toEqual({meta: {}, status: 404, title: "Not Found"});
+  });
+
+  it("includes optional fields when set", () => {
+    const error = new APIError({
+      code: "not-found",
+      detail: "Could not find resource",
+      disableExternalErrorTracking: true,
+      id: "err-1",
+      links: {about: "https://example.com/help"},
+      source: {pointer: "/data/id"},
+      status: 404,
+      title: "Not Found",
+    });
+    const body = getAPIErrorBody(error);
+    expect(body).toEqual({
+      code: "not-found",
+      detail: "Could not find resource",
+      disableExternalErrorTracking: true,
+      id: "err-1",
+      links: {about: "https://example.com/help"},
+      meta: {},
+      source: {pointer: "/data/id"},
+      status: 404,
+      title: "Not Found",
+    });
+  });
+
+  it("omits empty meta and unset optional fields", () => {
+    const error = new APIError({status: 400, title: "Bad"});
+    // meta defaults to {} which is truthy, so it is included.
+    const body = getAPIErrorBody(error);
+    expect(body.meta).toEqual({});
+    expect(body.code).toBeUndefined();
+    expect(body.detail).toBeUndefined();
+    expect(body.id).toBeUndefined();
+    expect(body.links).toBeUndefined();
+    expect(body.source).toBeUndefined();
+  });
+});
+
+describe("errorsPlugin", () => {
+  it("adds an apiErrors array field to the schema", () => {
+    const schema = new Schema({name: String});
+    errorsPlugin(schema);
+    const path = schema.path("apiErrors");
+    expect(path).toBeDefined();
+  });
+
+  it("requires title on each error subdocument", () => {
+    const schema = new Schema({name: String});
+    errorsPlugin(schema);
+    const path = schema.path("apiErrors");
+    // Inspect the embedded error schema for the title definition.
+    const embedded = path as unknown as {schema: Schema};
+    const titlePath = embedded.schema.path("title");
+    expect(titlePath).toBeDefined();
+    expect(titlePath.isRequired).toBe(true);
+  });
+});
+
+describe("apiUnauthorizedMiddleware", () => {
+  let res: MockResponse;
+  let next: ReturnType<typeof mock>;
+  const req = {} as Request;
+
+  beforeEach(() => {
+    res = buildResponse();
+    next = mock(() => {});
+  });
+
+  it("returns a 401 JSON response when the message is Unauthorized", () => {
+    apiUnauthorizedMiddleware(
+      new Error("Unauthorized"),
+      req,
+      res as unknown as Response,
+      next as unknown as NextFunction
+    );
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({status: 401, title: "Unauthorized"});
+    expect(res.send).toHaveBeenCalled();
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("forwards other errors to next", () => {
+    const err = new Error("Something else");
+    apiUnauthorizedMiddleware(
+      err,
+      req,
+      res as unknown as Response,
+      next as unknown as NextFunction
+    );
+    expect(next).toHaveBeenCalledWith(err);
+    expect(res.status).not.toHaveBeenCalled();
+  });
+});
+
+describe("apiErrorMiddleware", () => {
+  let res: MockResponse;
+  let next: ReturnType<typeof mock>;
+  const req = {} as Request;
+  const captureExceptionSpy = Sentry.captureException as unknown as ReturnType<typeof mock>;
+
+  beforeEach(() => {
+    res = buildResponse();
+    next = mock(() => {});
+    captureExceptionSpy.mockClear?.();
+  });
+
+  it("responds with the APIError status and body", () => {
+    const err = new APIError({detail: "missing", status: 404, title: "Not Found"});
+    apiErrorMiddleware(err, req, res as unknown as Response, next as unknown as NextFunction);
+    expect(res.status).toHaveBeenCalledWith(404);
+    expect(res.json).toHaveBeenCalledWith(getAPIErrorBody(err));
+    expect(res.send).toHaveBeenCalled();
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("captures the exception with Sentry by default", () => {
+    const err = new APIError({status: 500, title: "Boom"});
+    apiErrorMiddleware(err, req, res as unknown as Response, next as unknown as NextFunction);
+    expect(captureExceptionSpy).toHaveBeenCalledWith(err);
+  });
+
+  it("does not capture the exception when disableExternalErrorTracking is true", () => {
+    const err = new APIError({
+      disableExternalErrorTracking: true,
+      status: 500,
+      title: "Quiet",
+    });
+    apiErrorMiddleware(err, req, res as unknown as Response, next as unknown as NextFunction);
+    expect(captureExceptionSpy).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(500);
+  });
+
+  it("forwards non-APIError errors to next", () => {
+    const err = new Error("not an api error");
+    apiErrorMiddleware(err, req, res as unknown as Response, next as unknown as NextFunction);
+    expect(next).toHaveBeenCalledWith(err);
+    expect(res.status).not.toHaveBeenCalled();
+  });
+});

package/src/errors.ts

@@ -137,7 +137,7 @@ export class APIError extends Error {
 
 // Create an errors field for storing error information in a JSONAPI compatible form directly on a
 // model.
-export function errorsPlugin(schema: Schema): void {
+export const errorsPlugin = (schema: Schema): void => {
   const errorSchema = new Schema({
     code: {description: "Application-specific error code", type: String},
     detail: {description: "Human-readable explanation of the error", type: String},
@@ -160,18 +160,18 @@ export function errorsPlugin(schema: Schema): void {
   });
 
   schema.add({apiErrors: errorSchema});
-}
+};
 
-export function isAPIError(error: Error): error is APIError {
+export const isAPIError = (error: Error): error is APIError => {
   return error.name === "APIError";
-}
+};
 
 /**
  * Safely extracts the disableExternalErrorTracking property from an error.
  * Works with both APIError instances and regular Error objects that may have
  * this property attached.
  */
-export function getDisableExternalErrorTracking(error: unknown): boolean | undefined {
+export const getDisableExternalErrorTracking = (error: unknown): boolean | undefined => {
   if (error instanceof Error) {
     if (isAPIError(error)) {
       return error.disableExternalErrorTracking;
@@ -181,12 +181,12 @@ export function getDisableExternalErrorTracking(error: unknown): boolean | undef
     return (error as {disableExternalErrorTracking?: boolean}).disableExternalErrorTracking;
   }
   return undefined;
-}
+};
 
 // Creates an APIError body to send to clients as JSON. Errors don't have a toJSON defined,
 // and we want to strip out things like message, name, and stack for the client.
 // There is almost certainly a more elegant solution to this.
-export function getAPIErrorBody(error: APIError): {[id: string]: any} {
+export const getAPIErrorBody = (error: APIError): {[id: string]: any} => {
   const errorData = {status: error.status, title: error.title};
   for (const key of [
     "id",
@@ -203,23 +203,28 @@ export function getAPIErrorBody(error: APIError): {[id: string]: any} {
     }
   }
   return errorData;
-}
+};
 
-export function apiUnauthorizedMiddleware(
+export const apiUnauthorizedMiddleware = (
   err: Error,
   _req: Request,
   res: Response,
   next: NextFunction
-) {
+) => {
   if (err.message === "Unauthorized") {
     // not using the actual APIError class here because we don't want to log it as an error.
     res.status(401).json({status: 401, title: "Unauthorized"}).send();
   } else {
     next(err);
   }
-}
+};
 
-export function apiErrorMiddleware(err: Error, _req: Request, res: Response, next: NextFunction) {
+export const apiErrorMiddleware = (
+  err: Error,
+  _req: Request,
+  res: Response,
+  next: NextFunction
+) => {
   if (isAPIError(err)) {
     if (!err.disableExternalErrorTracking) {
       Sentry.captureException(err);
@@ -228,4 +233,4 @@ export function apiErrorMiddleware(err: Error, _req: Request, res: Response, nex
   } else {
     next(err);
   }
-}
+};