@terreno/api 0.11.7 → 0.11.9

package/src/plugins.test.ts

@@ -8,10 +8,13 @@ import {addAuthRoutes, setupAuth} from "./auth";
 import type {APIErrorConstructor} from "./errors";
 import {Permissions} from "./permissions";
 import {
+  baseUserPlugin,
   createdUpdatedPlugin,
   DateOnly,
   findExactlyOne,
   findOneOrNone,
+  findOneOrNoneFor,
+  firebaseJWTPlugin,
   type IsDeleted,
   isDeletedPlugin,
   upsertPlugin,
@@ -52,6 +55,33 @@ stuffSchema.plugin(createdUpdatedPlugin);
 
 const StuffModel = model<Stuff>("Stuff", stuffSchema) as unknown as StuffModelType;
 
+describe("baseUserPlugin", () => {
+  it("adds admin and email fields to the schema", () => {
+    const testSchema = new Schema({});
+    // biome-ignore lint/suspicious/noExplicitAny: test schema
+    baseUserPlugin(testSchema as Schema<any, any, any, any>);
+
+    const adminPath = testSchema.path("admin");
+    expect(adminPath).toBeDefined();
+    expect((adminPath as unknown as {options: {default: boolean}}).options.default).toBe(false);
+
+    const emailPath = testSchema.path("email");
+    expect(emailPath).toBeDefined();
+    expect((emailPath as unknown as {options: {index: boolean}}).options.index).toBe(true);
+  });
+});
+
+describe("firebaseJWTPlugin", () => {
+  it("adds firebaseId field to the schema", () => {
+    const testSchema = new Schema({});
+    firebaseJWTPlugin(testSchema);
+
+    const firebaseIdPath = testSchema.path("firebaseId");
+    expect(firebaseIdPath).toBeDefined();
+    expect((firebaseIdPath as unknown as {options: {index: boolean}}).options.index).toBe(true);
+  });
+});
+
 describe("createdUpdate", () => {
   it("sets created and updated on save", async () => {
     setSystemTime(new Date("2022-12-17T03:24:00.000Z"));
@@ -158,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/scriptRunner.ts

@@ -42,7 +42,7 @@ interface BackgroundTaskLog {
   message: string;
 }
 
-export type BackgroundTaskMethods = {
+export interface BackgroundTaskMethods {
   addLog: (
     this: BackgroundTaskDocument,
     level: "info" | "warn" | "error",
@@ -54,35 +54,31 @@ export type BackgroundTaskMethods = {
     stage?: string,
     message?: string
   ) => Promise<void>;
-};
+}
+
+export interface BackgroundTaskDocument extends Document, BackgroundTaskMethods {
+  taskType: string;
+  status: "pending" | "running" | "completed" | "failed" | "cancelled";
+  progress?: BackgroundTaskProgress;
+  createdBy?: mongoose.Types.ObjectId;
+  isDryRun: boolean;
+  result?: string[];
+  error?: string;
+  logs: BackgroundTaskLog[];
+  startedAt?: Date;
+  completedAt?: Date;
+  created: Date;
+  updated: Date;
+  deleted: boolean;
+}
 
-export type BackgroundTaskDocument = Document &
-  BackgroundTaskMethods & {
-    taskType: string;
-    status: "pending" | "running" | "completed" | "failed" | "cancelled";
-    progress?: BackgroundTaskProgress;
-    createdBy?: mongoose.Types.ObjectId;
-    isDryRun: boolean;
-    result?: string[];
-    error?: string;
-    logs: BackgroundTaskLog[];
-    startedAt?: Date;
-    completedAt?: Date;
-    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 {}
 
 const progressSchema = new Schema(
   {

package/src/secretProviders.ts

@@ -1,6 +1,16 @@
 import type {SecretProvider} from "./configurationPlugin";
+import {APIError} from "./errors";
 import {logger} from "./logger";
 
+interface SecretManagerClient {
+  accessSecretVersion(request: {name: string}): Promise<[{payload?: {data?: string | Uint8Array}}]>;
+}
+
+interface SecretManagerModule {
+  SecretManagerServiceClient?: new () => SecretManagerClient;
+  default?: {SecretManagerServiceClient?: new () => SecretManagerClient};
+}
+
 /**
  * Secret provider that reads secrets from environment variables.
  * Useful for local development and testing.
@@ -53,26 +63,34 @@ export interface GcpSecretProviderOptions {
 export class GcpSecretProvider implements SecretProvider {
   name = "gcp";
   private projectId: string;
-  private client: any = null;
+  private client: SecretManagerClient | null = null;
 
   constructor(options: GcpSecretProviderOptions) {
     this.projectId = options.projectId;
   }
 
-  private async getClient(): Promise<any> {
+  private async getClient(): Promise<SecretManagerClient> {
     if (!this.client) {
+      let mod: SecretManagerModule;
       try {
         // Dynamic import — @google-cloud/secret-manager is an optional peer dependency
         const moduleName = "@google-cloud/secret-manager";
-        const mod: any = await import(/* webpackIgnore: true */ moduleName);
-        const SecretManagerServiceClient =
-          mod.SecretManagerServiceClient ?? mod.default?.SecretManagerServiceClient;
-        this.client = new SecretManagerServiceClient();
+        mod = await import(/* webpackIgnore: true */ moduleName);
       } catch {
+        throw new APIError({
+          status: 500,
+          title:
+            "GcpSecretProvider requires @google-cloud/secret-manager. Install it with: bun add @google-cloud/secret-manager",
+        });
+      }
+      const SecretManagerServiceClient =
+        mod.SecretManagerServiceClient ?? mod.default?.SecretManagerServiceClient;
+      if (!SecretManagerServiceClient) {
         throw new Error(
-          "GcpSecretProvider requires @google-cloud/secret-manager. Install it with: bun add @google-cloud/secret-manager"
+          "SecretManagerServiceClient not found in @google-cloud/secret-manager module"
         );
       }
+      this.client = new SecretManagerServiceClient();
     }
     return this.client;
   }
@@ -97,8 +115,8 @@ export class GcpSecretProvider implements SecretProvider {
         return null;
       }
       return typeof payload === "string" ? payload : new TextDecoder().decode(payload);
-    } catch (error: any) {
-      if (error?.code === 5) {
+    } catch (error: unknown) {
+      if (error instanceof Error && "code" in error && (error as {code: number}).code === 5) {
         // NOT_FOUND
         logger.warn(`GcpSecretProvider: secret ${secretName} not found`);
         return null;

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;