@terreno/api 0.7.2 → 0.8.0

package/src/openApiValidator.ts

@@ -43,6 +43,7 @@ import m2s from "mongoose-to-swagger";
 import {APIError} from "./errors";
 import {logger} from "./logger";
 import type {OpenApiSchema, OpenApiSchemaProperty} from "./openApiBuilder";
+import {fixMixedFields} from "./populate";
 
 /**
  * Global configuration for OpenAPI validation.
@@ -713,6 +714,7 @@ const m2sOptions = {
  */
 export function getSchemaFromModel<T>(model: Model<T>): Record<string, OpenApiSchemaProperty> {
   const modelSwagger = m2s(model, m2sOptions);
+  fixMixedFields((model as any).schema, modelSwagger.properties);
   return modelSwagger.properties as Record<string, OpenApiSchemaProperty>;
 }
 

package/src/populate.ts

@@ -102,6 +102,37 @@ function getPathInSchema(schema: any, path: string): string {
 }
 
 // Replaces populated properties with the populated schema.
+// Recursively walks a Mongoose schema and fixes any Mixed fields in the
+// OpenAPI properties so they use an empty schema (accepts any type) instead
+// of the `{type: "object", properties: {}}` that mongoose-to-swagger emits.
+export const fixMixedFields = (schema: any, properties: Record<string, any>): void => {
+  if (!properties || !schema) {
+    return;
+  }
+
+  for (const key of Object.keys(properties)) {
+    const schemaPath = schema.path(key);
+    if (!schemaPath) {
+      continue;
+    }
+
+    // Direct Mixed field
+    if (schemaPath.instance === "Mixed") {
+      properties[key] = {description: properties[key]?.description};
+      continue;
+    }
+
+    // Array of sub-documents — check each sub-field for Mixed
+    if (
+      schemaPath.instance === "Array" &&
+      schemaPath.schema &&
+      properties[key]?.items?.properties
+    ) {
+      fixMixedFields(schemaPath.schema, properties[key].items.properties);
+    }
+  }
+};
+
 export function getOpenApiSpecForModel(
   model: any,
   {
@@ -113,6 +144,8 @@ export function getOpenApiSpecForModel(
     props: ["required", "enum"],
   });
 
+  fixMixedFields(model.schema, modelSwagger.properties);
+
   if (populatePaths && isArray(populatePaths)) {
     for (const populatePath of populatePaths) {
       // Get the referenced populate model from the model schema

package/src/syncConsents.test.ts

@@ -0,0 +1,124 @@
+import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+import {ConsentForm} from "./models/consentForm";
+import type {ConsentFormDefinition} from "./syncConsents";
+import {syncConsents} from "./syncConsents";
+import {setupDb} from "./tests";
+
+const baseDef: ConsentFormDefinition = {
+  content: {en: "# Terms\nPlease agree."},
+  order: 1,
+  required: true,
+  title: "Terms of Service",
+  type: "terms",
+};
+
+describe("syncConsents", () => {
+  beforeEach(async () => {
+    await setupDb();
+    await ConsentForm.deleteMany({});
+  });
+
+  afterEach(async () => {
+    await ConsentForm.deleteMany({});
+  });
+
+  it("creates a new consent form when none exists", async () => {
+    const result = await syncConsents({terms: baseDef});
+
+    expect(result.created).toEqual(["terms"]);
+    expect(result.updated).toHaveLength(0);
+    expect(result.unchanged).toHaveLength(0);
+
+    const forms = await ConsentForm.find({slug: "terms"});
+    expect(forms).toHaveLength(1);
+    expect(forms[0].active).toBe(true);
+    expect(forms[0].version).toBe(1);
+    expect(forms[0].title).toBe("Terms of Service");
+  });
+
+  it("leaves unchanged forms alone", async () => {
+    await syncConsents({terms: baseDef});
+    const result = await syncConsents({terms: baseDef});
+
+    expect(result.unchanged).toEqual(["terms"]);
+    expect(result.created).toHaveLength(0);
+    expect(result.updated).toHaveLength(0);
+
+    const forms = await ConsentForm.find({slug: "terms"});
+    expect(forms).toHaveLength(1);
+    expect(forms[0].version).toBe(1);
+  });
+
+  it("publishes a new version when content changes", async () => {
+    await syncConsents({terms: baseDef});
+
+    const updated = {...baseDef, content: {en: "# Updated Terms\nNew content."}};
+    const result = await syncConsents({terms: updated});
+
+    expect(result.updated).toEqual(["terms"]);
+
+    const forms = await ConsentForm.find({slug: "terms"}).sort({version: 1});
+    expect(forms).toHaveLength(2);
+    expect(forms[0].active).toBe(false);
+    expect(forms[0].version).toBe(1);
+    expect(forms[1].active).toBe(true);
+    expect(forms[1].version).toBe(2);
+  });
+
+  it("publishes a new version when title changes", async () => {
+    await syncConsents({terms: baseDef});
+
+    const updated = {...baseDef, title: "Updated Terms"};
+    const result = await syncConsents({terms: updated});
+
+    expect(result.updated).toEqual(["terms"]);
+
+    const active = await ConsentForm.findOne({active: true, slug: "terms"});
+    expect(active?.version).toBe(2);
+    expect(active?.title).toBe("Updated Terms");
+  });
+
+  it("deactivates removed forms when deactivateRemoved is true", async () => {
+    await syncConsents({privacy: {...baseDef, title: "Privacy", type: "privacy"}, terms: baseDef});
+
+    const result = await syncConsents({terms: baseDef}, {deactivateRemoved: true});
+
+    expect(result.deactivated).toEqual(["privacy"]);
+    expect(result.unchanged).toEqual(["terms"]);
+
+    const privacy = await ConsentForm.findOne({slug: "privacy"});
+    expect(privacy?.active).toBe(false);
+  });
+
+  it("does not deactivate removed forms by default", async () => {
+    await syncConsents({privacy: {...baseDef, title: "Privacy", type: "privacy"}, terms: baseDef});
+
+    const result = await syncConsents({terms: baseDef});
+
+    expect(result.deactivated).toHaveLength(0);
+    const privacy = await ConsentForm.findOne({slug: "privacy"});
+    expect(privacy?.active).toBe(true);
+  });
+
+  it("does not write to the database in dry run mode", async () => {
+    const result = await syncConsents({terms: baseDef}, {dryRun: true});
+
+    expect(result.created).toEqual(["terms"]);
+    const forms = await ConsentForm.find({slug: "terms"});
+    expect(forms).toHaveLength(0);
+  });
+
+  it("handles multiple forms in a single sync", async () => {
+    const result = await syncConsents({
+      privacy: {...baseDef, order: 2, title: "Privacy Policy", type: "privacy"},
+      terms: baseDef,
+    });
+
+    expect(result.created.sort()).toEqual(["privacy", "terms"]);
+
+    const forms = await ConsentForm.find({}).sort({order: 1});
+    expect(forms).toHaveLength(2);
+    expect(forms[0].slug).toBe("terms");
+    expect(forms[1].slug).toBe("privacy");
+  });
+});

package/src/syncConsents.ts

@@ -0,0 +1,263 @@
+/**
+ * Sync consent form definitions from code to the database.
+ *
+ * Compares the provided definitions (keyed by slug) against what's in the database
+ * and creates, updates, or deactivates forms to match. When content changes, a new
+ * version is published so users are prompted to re-consent.
+ */
+
+import {logger} from "./logger";
+import {ConsentForm} from "./models/consentForm";
+import type {ConsentFormType} from "./types/consentForm";
+
+export interface ConsentFormDefinition {
+  title: string;
+  type: ConsentFormType;
+  content: Record<string, string>;
+  order?: number;
+  required?: boolean;
+  requireScrollToBottom?: boolean;
+  captureSignature?: boolean;
+  agreeButtonText?: string;
+  allowDecline?: boolean;
+  declineButtonText?: string;
+  defaultLocale?: string;
+  checkboxes?: Array<{
+    label: string;
+    required?: boolean;
+    confirmationPrompt?: string;
+  }>;
+}
+
+export interface SyncConsentsOptions {
+  /** Deactivate database forms whose slugs are not in the definitions. Default: false */
+  deactivateRemoved?: boolean;
+  /** If true, log what would change without writing to the database. Default: false */
+  dryRun?: boolean;
+}
+
+export interface SyncConsentsResult {
+  created: string[];
+  updated: string[];
+  deactivated: string[];
+  unchanged: string[];
+}
+
+const contentEqual = (a: Map<string, string>, b: Record<string, string>): boolean => {
+  const aKeys = [...a.keys()].sort();
+  const bKeys = Object.keys(b).sort();
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  return aKeys.every((key, i) => key === bKeys[i] && a.get(key) === b[key]);
+};
+
+const formFieldsMatch = (
+  existing: {
+    title: string;
+    type: string;
+    order: number;
+    required: boolean;
+    requireScrollToBottom: boolean;
+    captureSignature: boolean;
+    agreeButtonText: string;
+    allowDecline: boolean;
+    declineButtonText: string;
+    defaultLocale: string;
+    checkboxes: Array<{label: string; required: boolean; confirmationPrompt?: string}>;
+    content: Map<string, string>;
+  },
+  def: ConsentFormDefinition
+): boolean => {
+  if (existing.title !== def.title) {
+    return false;
+  }
+  if (existing.type !== def.type) {
+    return false;
+  }
+  if (existing.order !== (def.order ?? 0)) {
+    return false;
+  }
+  if (existing.required !== (def.required ?? true)) {
+    return false;
+  }
+  if (existing.requireScrollToBottom !== (def.requireScrollToBottom ?? false)) {
+    return false;
+  }
+  if (existing.captureSignature !== (def.captureSignature ?? false)) {
+    return false;
+  }
+  if (existing.agreeButtonText !== (def.agreeButtonText ?? "I Agree")) {
+    return false;
+  }
+  if (existing.allowDecline !== (def.allowDecline ?? false)) {
+    return false;
+  }
+  if (existing.declineButtonText !== (def.declineButtonText ?? "Decline")) {
+    return false;
+  }
+  if (existing.defaultLocale !== (def.defaultLocale ?? "en")) {
+    return false;
+  }
+  if (!contentEqual(existing.content, def.content)) {
+    return false;
+  }
+
+  const existingCheckboxes = existing.checkboxes ?? [];
+  const defCheckboxes = def.checkboxes ?? [];
+  if (existingCheckboxes.length !== defCheckboxes.length) {
+    return false;
+  }
+  for (let i = 0; i < existingCheckboxes.length; i++) {
+    const ec = existingCheckboxes[i];
+    const dc = defCheckboxes[i];
+    if (ec.label !== dc.label || ec.required !== (dc.required ?? false)) {
+      return false;
+    }
+    if ((ec.confirmationPrompt ?? undefined) !== (dc.confirmationPrompt ?? undefined)) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Sync consent form definitions to the database.
+ *
+ * @param definitions - Map of slug to consent form definition
+ * @param options - Sync options
+ * @returns Summary of what was created, updated, deactivated, or unchanged
+ *
+ * @example
+ * ```typescript
+ * import {syncConsents} from "@terreno/api";
+ *
+ * await syncConsents({
+ *   "terms-of-service": {
+ *     title: "Terms of Service",
+ *     type: "terms",
+ *     content: {"en": "# Terms\n...", "es": "# Términos\n..."},
+ *     required: true,
+ *     order: 1,
+ *   },
+ *   "privacy-policy": {
+ *     title: "Privacy Policy",
+ *     type: "privacy",
+ *     content: {"en": "# Privacy\n..."},
+ *     order: 2,
+ *   },
+ * });
+ * ```
+ */
+export const syncConsents = async (
+  definitions: Record<string, ConsentFormDefinition>,
+  options: SyncConsentsOptions = {}
+): Promise<SyncConsentsResult> => {
+  const {deactivateRemoved = false, dryRun = false} = options;
+
+  const result: SyncConsentsResult = {
+    created: [],
+    deactivated: [],
+    unchanged: [],
+    updated: [],
+  };
+
+  const slugs = Object.keys(definitions);
+
+  // Fetch the current active form for each slug
+  const activeForms = await ConsentForm.find({active: true});
+  const activeBySlug = new Map(activeForms.map((f) => [f.slug, f]));
+
+  for (const slug of slugs) {
+    const def = definitions[slug];
+    const existing = activeBySlug.get(slug);
+
+    if (!existing) {
+      // No active form for this slug — create version 1
+      logger.info(`syncConsents: creating "${slug}"`, {dryRun});
+      if (!dryRun) {
+        await ConsentForm.create({
+          active: true,
+          agreeButtonText: def.agreeButtonText,
+          allowDecline: def.allowDecline,
+          captureSignature: def.captureSignature,
+          checkboxes: def.checkboxes,
+          content: new Map(Object.entries(def.content)),
+          declineButtonText: def.declineButtonText,
+          defaultLocale: def.defaultLocale,
+          order: def.order ?? 0,
+          required: def.required ?? true,
+          requireScrollToBottom: def.requireScrollToBottom,
+          slug,
+          title: def.title,
+          type: def.type,
+          version: 1,
+        });
+      }
+      result.created.push(slug);
+      continue;
+    }
+
+    if (formFieldsMatch(existing, def)) {
+      result.unchanged.push(slug);
+      continue;
+    }
+
+    // Content or config changed — publish a new version
+    const newVersion = existing.version + 1;
+    logger.info(`syncConsents: updating "${slug}" v${existing.version} -> v${newVersion}`, {
+      dryRun,
+    });
+    if (!dryRun) {
+      await ConsentForm.create({
+        active: true,
+        agreeButtonText: def.agreeButtonText,
+        allowDecline: def.allowDecline,
+        captureSignature: def.captureSignature,
+        checkboxes: def.checkboxes,
+        content: new Map(Object.entries(def.content)),
+        declineButtonText: def.declineButtonText,
+        defaultLocale: def.defaultLocale,
+        order: def.order ?? 0,
+        required: def.required ?? true,
+        requireScrollToBottom: def.requireScrollToBottom,
+        slug,
+        title: def.title,
+        type: def.type,
+        version: newVersion,
+      });
+      await ConsentForm.updateMany(
+        {_id: {$ne: undefined}, slug, version: {$lt: newVersion}},
+        {active: false}
+      );
+    }
+    result.updated.push(slug);
+  }
+
+  // Deactivate forms that are no longer in definitions
+  if (deactivateRemoved) {
+    for (const [slug, form] of activeBySlug) {
+      if (!definitions[slug]) {
+        logger.info(`syncConsents: deactivating "${slug}"`, {dryRun});
+        if (!dryRun) {
+          await ConsentForm.updateMany({slug}, {active: false});
+        }
+        result.deactivated.push(slug);
+      }
+    }
+  }
+
+  const summary = [
+    result.created.length > 0 ? `created: ${result.created.join(", ")}` : null,
+    result.updated.length > 0 ? `updated: ${result.updated.join(", ")}` : null,
+    result.deactivated.length > 0 ? `deactivated: ${result.deactivated.join(", ")}` : null,
+    result.unchanged.length > 0 ? `unchanged: ${result.unchanged.join(", ")}` : null,
+  ]
+    .filter(Boolean)
+    .join(" | ");
+
+  logger.info(`syncConsents: ${dryRun ? "[DRY RUN] " : ""}${summary || "nothing to do"}`);
+
+  return result;
+};

package/src/terrenoApp.ts

@@ -301,8 +301,6 @@ export class TerrenoApp {
       app.use("/swagger", oapi.swaggerui());
     }
 
-    addMeRoutes(app, options.userModel as any, options.authOptions);
-
     // GitHub OAuth
     if (options.githubAuth) {
       setupGitHubAuth(app, options.userModel as any, options.githubAuth);
@@ -317,14 +315,16 @@ export class TerrenoApp {
     // Mount registered model routers and plugins
     for (const registration of this.registrations) {
       if (this.isModelRouterRegistration(registration)) {
-        app.use(registration.path, registration.router);
+        const router = registration._buildWithOpenApi(oapi);
+        app.use(registration.path, router);
       } else {
-        registration.register(app);
+        registration.register(app, oapi);
       }
     }
 
-    // Inject openApi into model router options for registered routers
-    // The openApi middleware handles this via the oapi instance already mounted on the app
+    // /auth/me must be registered after plugins so that session middleware
+    // (e.g. Better Auth) has a chance to populate req.user first.
+    addMeRoutes(app, options.userModel as any, options.authOptions);
 
     Sentry.setupExpressErrorHandler(app);
 

package/src/terrenoPlugin.ts

@@ -35,5 +35,5 @@ export interface TerrenoPlugin {
    *
    * @param app - The Express application instance to register with
    */
-  register(app: express.Application): void;
+  register(app: express.Application, openApi?: unknown): void;
 }

package/src/types/consentForm.ts

@@ -0,0 +1,41 @@
+import type mongoose from "mongoose";
+import type {FindExactlyOnePlugin, FindOneOrNonePlugin} from "../plugins";
+
+export interface ConsentFormCheckbox {
+  label: string;
+  required: boolean;
+  confirmationPrompt?: string;
+}
+
+export type ConsentFormType = "agreement" | "privacy" | "hipaa" | "research" | "terms" | "custom";
+
+// biome-ignore lint/complexity/noBannedTypes: No methods.
+export type ConsentFormMethods = {};
+
+export type ConsentFormStatics = FindExactlyOnePlugin<ConsentFormDocument> &
+  FindOneOrNonePlugin<ConsentFormDocument>;
+
+export type ConsentFormModel = mongoose.Model<ConsentFormDocument, object, ConsentFormMethods> &
+  ConsentFormStatics;
+
+export interface ConsentFormDocument extends mongoose.Document {
+  _id: mongoose.Types.ObjectId;
+  title: string;
+  slug: string;
+  version: number;
+  order: number;
+  type: ConsentFormType;
+  content: Map<string, string>;
+  defaultLocale: string;
+  active: boolean;
+  captureSignature: boolean;
+  requireScrollToBottom: boolean;
+  checkboxes: ConsentFormCheckbox[];
+  agreeButtonText: string;
+  allowDecline: boolean;
+  declineButtonText: string;
+  required: boolean;
+  created: Date;
+  updated: Date;
+  deleted: boolean;
+}

package/src/types/consentResponse.ts

@@ -0,0 +1,34 @@
+import type mongoose from "mongoose";
+import type {FindExactlyOnePlugin, FindOneOrNonePlugin} from "../plugins";
+
+// biome-ignore lint/complexity/noBannedTypes: No methods.
+export type ConsentResponseMethods = {};
+
+export type ConsentResponseStatics = FindExactlyOnePlugin<ConsentResponseDocument> &
+  FindOneOrNonePlugin<ConsentResponseDocument>;
+
+export type ConsentResponseModel = mongoose.Model<
+  ConsentResponseDocument,
+  object,
+  ConsentResponseMethods
+> &
+  ConsentResponseStatics;
+
+export interface ConsentResponseDocument extends mongoose.Document {
+  _id: mongoose.Types.ObjectId;
+  userId: mongoose.Types.ObjectId;
+  consentFormId: mongoose.Types.ObjectId;
+  agreed: boolean;
+  agreedAt: Date;
+  checkboxValues?: Map<string, boolean>;
+  locale: string;
+  signature?: string;
+  signedAt?: Date;
+  ipAddress?: string;
+  userAgent?: string;
+  contentSnapshot?: string;
+  formVersionSnapshot?: number;
+  created: Date;
+  updated: Date;
+  deleted: boolean;
+}

package/src/vendor/wesleytodd-openapi/lib/generate-doc.js

@@ -114,7 +114,7 @@ function processComplexMatch (thing, keys) {
     // (i.e. /:id, /:name, etc...) with the name(s) of those parameter(s)
     // This could have been accomplished with replaceAll for Node version 15 and above
     // no-useless-escape is disabled since we need three backslashes
-    .replace(/\(\?\:\(\[\^\\\/\]\+\?\)\)/g, () => `{${keys[i++].name}}`) // eslint-disable-line no-useless-escape
+    .replace(/\(\?\:\(\[\^\\\/\]\+\?\)\)/g, () => `{${keys[i++].name}}`)
     .replace(/\\(.)/g, '$1')
     // The replace below removes the regex used at the start of the string and
     // the regex used to match the query parameters

package/src/versionCheckPlugin.ts

@@ -8,8 +8,10 @@ export type VersionCheckStatus = "ok" | "warning" | "required";
 
 export interface VersionCheckResponse {
   message?: string;
+  requiredVersion?: number;
   status: VersionCheckStatus;
   updateUrl?: string;
+  warningVersion?: number;
 }
 
 const DEFAULT_WARNING_MESSAGE =
@@ -57,21 +59,18 @@ export class VersionCheckPlugin implements TerrenoPlugin {
             : (config.mobileWarningVersion ?? 0);
 
         const response: VersionCheckResponse = {
+          requiredVersion: requiredVersion > 0 ? requiredVersion : undefined,
           status: "ok",
+          updateUrl: config.updateUrl || undefined,
+          warningVersion: warningVersion > 0 ? warningVersion : undefined,
         };
 
         if (requiredVersion > 0 && version < requiredVersion) {
           response.status = "required";
           response.message = config.requiredMessage ?? DEFAULT_REQUIRED_MESSAGE;
-          if (config.updateUrl) {
-            response.updateUrl = config.updateUrl;
-          }
         } else if (warningVersion > 0 && version < warningVersion) {
           response.status = "warning";
           response.message = config.warningMessage ?? DEFAULT_WARNING_MESSAGE;
-          if (config.updateUrl) {
-            response.updateUrl = config.updateUrl;
-          }
         }
 
         return res.json(response);