@terreno/api 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -5,11 +5,14 @@ export * from "./betterAuthApp";
 export * from "./betterAuthSetup";
 export * from "./configurationApp";
 export * from "./configurationPlugin";
+export * from "./consentApp";
 export * from "./errors";
 export * from "./expressServer";
 export * from "./githubAuth";
 export * from "./logger";
 export * from "./middleware";
+export * from "./models/consentForm";
+export * from "./models/consentResponse";
 export * from "./models/versionConfig";
 export * from "./notifiers";
 export * from "./openApiBuilder";
@@ -21,8 +24,11 @@ export * from "./plugins";
 export * from "./populate";
 export * from "./scriptRunner";
 export * from "./secretProviders";
+export * from "./syncConsents";
 export * from "./terrenoApp";
 export * from "./terrenoPlugin";
 export * from "./transformers";
+export * from "./types/consentForm";
+export * from "./types/consentResponse";
 export * from "./utils";
 export * from "./versionCheckPlugin";

package/dist/index.js

@@ -21,11 +21,14 @@ __exportStar(require("./betterAuthApp"), exports);
 __exportStar(require("./betterAuthSetup"), exports);
 __exportStar(require("./configurationApp"), exports);
 __exportStar(require("./configurationPlugin"), exports);
+__exportStar(require("./consentApp"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./expressServer"), exports);
 __exportStar(require("./githubAuth"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./middleware"), exports);
+__exportStar(require("./models/consentForm"), exports);
+__exportStar(require("./models/consentResponse"), exports);
 __exportStar(require("./models/versionConfig"), exports);
 __exportStar(require("./notifiers"), exports);
 __exportStar(require("./openApiBuilder"), exports);
@@ -37,8 +40,11 @@ __exportStar(require("./plugins"), exports);
 __exportStar(require("./populate"), exports);
 __exportStar(require("./scriptRunner"), exports);
 __exportStar(require("./secretProviders"), exports);
+__exportStar(require("./syncConsents"), exports);
 __exportStar(require("./terrenoApp"), exports);
 __exportStar(require("./terrenoPlugin"), exports);
 __exportStar(require("./transformers"), exports);
+__exportStar(require("./types/consentForm"), exports);
+__exportStar(require("./types/consentResponse"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./versionCheckPlugin"), exports);

package/dist/models/consentForm.d.ts

@@ -0,0 +1,2 @@
+import type { ConsentFormModel } from "../types/consentForm";
+export declare const ConsentForm: ConsentFormModel;

package/dist/models/consentForm.js

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsentForm = void 0;
+var mongoose_1 = __importDefault(require("mongoose"));
+var plugins_1 = require("../plugins");
+var consentFormSchema = new mongoose_1.default.Schema({
+    active: {
+        default: false,
+        description: "Whether this consent form is currently active and available to users",
+        type: Boolean,
+    },
+    agreeButtonText: {
+        default: "I Agree",
+        description: "Label text for the agreement button",
+        type: String,
+    },
+    allowDecline: {
+        default: false,
+        description: "Whether users are allowed to decline the consent form",
+        type: Boolean,
+    },
+    captureSignature: {
+        default: false,
+        description: "Whether to require a drawn or typed signature when the user agrees",
+        type: Boolean,
+    },
+    checkboxes: {
+        default: [],
+        description: "List of checkboxes the user must interact with before agreeing",
+        type: [
+            {
+                confirmationPrompt: {
+                    description: "Optional prompt shown when the user checks this checkbox",
+                    type: String,
+                },
+                label: {
+                    description: "Display label for the checkbox",
+                    required: true,
+                    type: String,
+                },
+                required: {
+                    default: false,
+                    description: "Whether this checkbox must be checked before the user can agree",
+                    type: Boolean,
+                },
+            },
+        ],
+    },
+    content: {
+        description: 'Locale-keyed map of Markdown content for this form (e.g. {"en": "# Terms\\n..."})',
+        of: String,
+        required: true,
+        type: Map,
+    },
+    declineButtonText: {
+        default: "Decline",
+        description: "Label text for the decline button (only shown when allowDecline is true)",
+        type: String,
+    },
+    defaultLocale: {
+        default: "en",
+        description: "Default locale to use when the requested locale is not available",
+        type: String,
+    },
+    order: {
+        default: 0,
+        description: "Display order relative to other consent forms (lower numbers appear first)",
+        required: true,
+        type: Number,
+    },
+    required: {
+        default: true,
+        description: "Whether users must complete this form before accessing the application",
+        type: Boolean,
+    },
+    requireScrollToBottom: {
+        default: false,
+        description: "Whether users must scroll to the bottom of the form content before agreeing",
+        type: Boolean,
+    },
+    slug: {
+        description: "URL-safe identifier for this form, combined with version to uniquely identify a form",
+        index: true,
+        required: true,
+        trim: true,
+        type: String,
+    },
+    title: {
+        description: "Human-readable title of the consent form",
+        required: true,
+        trim: true,
+        type: String,
+    },
+    type: {
+        description: "Category of consent form",
+        enum: ["agreement", "privacy", "hipaa", "research", "terms", "custom"],
+        required: true,
+        type: String,
+    },
+    version: {
+        default: 1,
+        description: "Version number of this form. Incrementing the version requires users to re-consent",
+        required: true,
+        type: Number,
+    },
+}, { strict: "throw", toJSON: { virtuals: true }, toObject: { virtuals: true } });
+consentFormSchema.index({ slug: 1, version: 1 }, { unique: true });
+consentFormSchema.plugin(plugins_1.createdUpdatedPlugin);
+consentFormSchema.plugin(plugins_1.isDeletedPlugin);
+consentFormSchema.plugin(plugins_1.findOneOrNone);
+consentFormSchema.plugin(plugins_1.findExactlyOne);
+exports.ConsentForm = mongoose_1.default.model("ConsentForm", consentFormSchema);

package/dist/models/consentResponse.d.ts

@@ -0,0 +1,2 @@
+import type { ConsentResponseModel } from "../types/consentResponse";
+export declare const ConsentResponse: ConsentResponseModel;

package/dist/models/consentResponse.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsentResponse = void 0;
+var mongoose_1 = __importDefault(require("mongoose"));
+var plugins_1 = require("../plugins");
+var consentResponseSchema = new mongoose_1.default.Schema({
+    agreed: {
+        description: "Whether the user agreed (true) or declined (false) the consent form",
+        required: true,
+        type: Boolean,
+    },
+    agreedAt: {
+        description: "Timestamp when the user submitted their agreement or declination",
+        required: true,
+        type: Date,
+    },
+    checkboxValues: {
+        description: "Map of checkbox index to boolean indicating whether each checkbox was checked",
+        of: Boolean,
+        type: Map,
+    },
+    consentFormId: {
+        description: "Reference to the ConsentForm that was responded to",
+        ref: "ConsentForm",
+        required: true,
+        type: mongoose_1.default.Schema.Types.ObjectId,
+    },
+    contentSnapshot: {
+        description: "Snapshot of the form content in the user's locale at the time of response",
+        type: String,
+    },
+    formVersionSnapshot: {
+        description: "Version number of the form at the time the user responded",
+        type: Number,
+    },
+    ipAddress: {
+        description: "IP address of the user at the time of response, captured for audit purposes",
+        type: String,
+    },
+    locale: {
+        description: "Locale code of the content version the user viewed when responding",
+        required: true,
+        type: String,
+    },
+    signature: {
+        description: "Base64-encoded signature image or typed signature text, if captured",
+        type: String,
+    },
+    signedAt: {
+        description: "Timestamp when the user provided their signature",
+        type: Date,
+    },
+    userAgent: {
+        description: "User-agent string of the browser or app used to submit the response",
+        type: String,
+    },
+    userId: {
+        description: "Reference to the User who submitted this response",
+        index: true,
+        ref: "User",
+        required: true,
+        type: mongoose_1.default.Schema.Types.ObjectId,
+    },
+}, { strict: "throw", toJSON: { virtuals: true }, toObject: { virtuals: true } });
+consentResponseSchema.index({ consentFormId: 1, userId: 1 });
+consentResponseSchema.plugin(plugins_1.createdUpdatedPlugin);
+consentResponseSchema.plugin(plugins_1.isDeletedPlugin);
+consentResponseSchema.plugin(plugins_1.findOneOrNone);
+consentResponseSchema.plugin(plugins_1.findExactlyOne);
+exports.ConsentResponse = mongoose_1.default.model("ConsentResponse", consentResponseSchema);

package/dist/models/versionConfig.d.ts

@@ -1,5 +1,5 @@
 import mongoose, { type Document } from "mongoose";
-import { type APIErrorConstructor } from "../errors";
+import type { APIErrorConstructor } from "../errors";
 export interface VersionConfigDocument extends mongoose.Document {
     webWarningVersion: number;
     webRequiredVersion: number;

package/dist/openApiValidator.js

@@ -113,6 +113,7 @@ var ajv_formats_1 = __importDefault(require("ajv-formats"));
 var mongoose_to_swagger_1 = __importDefault(require("mongoose-to-swagger"));
 var errors_1 = require("./errors");
 var logger_1 = require("./logger");
+var populate_1 = require("./populate");
 // Whether configureOpenApiValidator() has been called
 var isConfigured = false;
 // Global validator configuration - can be modified at runtime
@@ -601,6 +602,7 @@ var m2sOptions = {
  */
 function getSchemaFromModel(model) {
     var modelSwagger = (0, mongoose_to_swagger_1.default)(model, m2sOptions);
+    (0, populate_1.fixMixedFields)(model.schema, modelSwagger.properties);
     return modelSwagger.properties;
 }
 /**

package/dist/populate.d.ts

@@ -4,6 +4,7 @@ export type PopulatePath = {
     openApiComponent?: any;
     fields?: string[];
 };
+export declare const fixMixedFields: (schema: any, properties: Record<string, any>) => void;
 export declare function getOpenApiSpecForModel(model: any, { populatePaths, extraModelProperties, }?: {
     populatePaths?: PopulatePath[];
     extraModelProperties?: any;

package/dist/populate.js

@@ -50,6 +50,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixMixedFields = void 0;
 exports.getOpenApiSpecForModel = getOpenApiSpecForModel;
 exports.unpopulate = unpopulate;
 var isArray_1 = __importDefault(require("lodash/isArray"));
@@ -124,13 +125,52 @@ function getPathInSchema(schema, path) {
     return fullPath;
 }
 // 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.
+var fixMixedFields = function (schema, properties) {
+    var e_1, _a;
+    var _b, _c, _d;
+    if (!properties || !schema) {
+        return;
+    }
+    try {
+        for (var _e = __values(Object.keys(properties)), _f = _e.next(); !_f.done; _f = _e.next()) {
+            var key = _f.value;
+            var schemaPath = schema.path(key);
+            if (!schemaPath) {
+                continue;
+            }
+            // Direct Mixed field
+            if (schemaPath.instance === "Mixed") {
+                properties[key] = { description: (_b = properties[key]) === null || _b === void 0 ? void 0 : _b.description };
+                continue;
+            }
+            // Array of sub-documents — check each sub-field for Mixed
+            if (schemaPath.instance === "Array" &&
+                schemaPath.schema &&
+                ((_d = (_c = properties[key]) === null || _c === void 0 ? void 0 : _c.items) === null || _d === void 0 ? void 0 : _d.properties)) {
+                (0, exports.fixMixedFields)(schemaPath.schema, properties[key].items.properties);
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_f && !_f.done && (_a = _e.return)) _a.call(_e);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+};
+exports.fixMixedFields = fixMixedFields;
 function getOpenApiSpecForModel(model, _a) {
-    var e_1, _b, _c, e_2, _d, e_3, _e, e_4, _f;
+    var e_2, _b, _c, e_3, _d, e_4, _e, e_5, _f;
     var _g, _h, _j, _k;
     var _l = _a === void 0 ? {} : _a, populatePaths = _l.populatePaths, extraModelProperties = _l.extraModelProperties;
     var modelSwagger = (0, mongoose_to_swagger_1.default)(model, {
         props: ["required", "enum"],
     });
+    (0, exports.fixMixedFields)(model.schema, modelSwagger.properties);
     if (populatePaths && (0, isArray_1.default)(populatePaths)) {
         try {
             for (var populatePaths_1 = __values(populatePaths), populatePaths_1_1 = populatePaths_1.next(); !populatePaths_1_1.done; populatePaths_1_1 = populatePaths_1.next()) {
@@ -191,12 +231,12 @@ function getOpenApiSpecForModel(model, _a) {
                 }
             }
         }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
         finally {
             try {
                 if (populatePaths_1_1 && !populatePaths_1_1.done && (_b = populatePaths_1.return)) _b.call(populatePaths_1);
             }
-            finally { if (e_1) throw e_1.error; }
+            finally { if (e_2) throw e_2.error; }
         }
     }
     try {
@@ -212,12 +252,12 @@ function getOpenApiSpecForModel(model, _a) {
             };
         }
     }
-    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
     finally {
         try {
             if (_o && !_o.done && (_d = _m.return)) _d.call(_m);
         }
-        finally { if (e_2) throw e_2.error; }
+        finally { if (e_3) throw e_3.error; }
     }
     // Check subschemas for virtuals (one level deep)
     if (model.schema.childSchemas.length > 0) {
@@ -225,7 +265,7 @@ function getOpenApiSpecForModel(model, _a) {
             for (var _p = __values(model.schema.childSchemas), _q = _p.next(); !_q.done; _q = _p.next()) {
                 var childSchema = _q.value;
                 try {
-                    for (var _r = (e_4 = void 0, __values(Object.keys(childSchema.schema.virtuals))), _s = _r.next(); !_s.done; _s = _r.next()) {
+                    for (var _r = (e_5 = void 0, __values(Object.keys(childSchema.schema.virtuals))), _s = _r.next(); !_s.done; _s = _r.next()) {
                         var virtual = _s.value;
                         if (virtual === "id" || virtual === "__v") {
                             continue;
@@ -235,21 +275,21 @@ function getOpenApiSpecForModel(model, _a) {
                         };
                     }
                 }
-                catch (e_4_1) { e_4 = { error: e_4_1 }; }
+                catch (e_5_1) { e_5 = { error: e_5_1 }; }
                 finally {
                     try {
                         if (_s && !_s.done && (_f = _r.return)) _f.call(_r);
                     }
-                    finally { if (e_4) throw e_4.error; }
+                    finally { if (e_5) throw e_5.error; }
                 }
             }
         }
-        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
         finally {
             try {
                 if (_q && !_q.done && (_e = _p.return)) _e.call(_p);
             }
-            finally { if (e_3) throw e_3.error; }
+            finally { if (e_4) throw e_4.error; }
         }
     }
     return {
@@ -268,7 +308,7 @@ function unpopulate(doc, path) {
     var pathParts = path.split(".");
     // Recursive because we need to support nested paths.
     var recursiveUnpopulate = function (current, parts) {
-        var e_5, _a;
+        var e_6, _a;
         var _b;
         var part = parts[0];
         // If the path doesn't exist, return the original doc
@@ -297,12 +337,12 @@ function unpopulate(doc, path) {
                         recursiveUnpopulate(item, parts.slice(1)); // Recursively handle each item in the array
                     }
                 }
-                catch (e_5_1) { e_5 = { error: e_5_1 }; }
+                catch (e_6_1) { e_6 = { error: e_6_1 }; }
                 finally {
                     try {
                         if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
                     }
-                    finally { if (e_5) throw e_5.error; }
+                    finally { if (e_6) throw e_6.error; }
                 }
             }
             else {

package/dist/syncConsents.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 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[];
+}
+/**
+ * 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 declare const syncConsents: (definitions: Record<string, ConsentFormDefinition>, options?: SyncConsentsOptions) => Promise<SyncConsentsResult>;